In addition to the executable SunVideo demonstration program, the SunVideo release includes the source code for three example programs. The programs, described in this and the next two chapters, are provided to highlight some of the capabilities of the SunVideo subsystem, the XIL programming interface, and the compression techniques that the SunVideo subsystem supports.
Note - Please understand that these are truly example programs; they were not designed as production applications. The programs are provided to give you a starting point for working with the SunVideo subsystem.
The video capture and display program (rtvc_display), described in this chapter, captures uncompressed video frames from one of the SunVideo card's input ports and displays the frames in a window (Figure 5-1).
Figure 5-1 Video Capture and Display
Note - The example SunVideo programs assume that the SunVideo card is receiving standard video. However, it is possible that the video you receive from cable or from broadcasters is non-standard. We have found, for example, a "local information" cable channel that sends non-standard video. The SunVideo subsystem will not capture this non-standard video, even though it appears normal when viewed on a television.
The sources for the rtvc_display program are installed in the directory:
/opt/SUNWits/Graphics-sw/xil/examples/rtvc_display
Use the provided Makefile to compile the program, creating the file:
/opt/SUNWits/Graphics-sw/xil/examples/rtvc_display/rtvc_display
A compiled version of the program is in the directory:
/opt/SUNWits/Graphics-sw/xil/examples/test
You can display the program's usage information by typing the program name and an argument that the program doesn't use. For example:
% rtvc_display -@
Table 5-1 describes the rtvc_display program's arguments. Arguments without values are switches. For example, -g is a switch.
Table 5-1 Arguments for the rtvc_display Program
--------------------------------------------------------------------------------
Argument Description Default --------------------------------------------------------------------------------
-I <port_number'> The number of the SunVideo card's Composite
input port to which your video device port 1
is connected (0 for S-Video, 1 or 2 for
composite).
-g Enables grayscale mode. Capture and Color mode
display only the Y (luminance) band of
the YUV image.
-f <number_frames The number of frames to capture. 100
-w <width'> Specifies (in pixels) the width of a 640 NTSC
rectangle that enables you to select part 768 PAL
of a device image. The rectangle is
centered on the image. The maximum
width is 640 pixels for NTSC and 768
pixels for PAL.
-h <height'> Specifies (in pixels) the height of a 480 NTSC
rectangle that enables you to select part 576 PAL
of a device image. The rectangle is
centered on the image. The maximum
height is 480 pixels for NTSC and 576
pixels for PAL.
-i <skip_frames'> Number of frames to skip between 0
captures. For example, for NTSC,
skipping one frame captures frames at
a rate of 15 fps.
-s <shrink_factor'> Shrinks the captured image by the 2
integer value of <shrink_factor>
(1, 2, 3, 4, 5, ... ). A shrink factor of 0
turns off shrinking, which is equivalent
to a shrink factor of 1.
For NTSC, the default shrink factor of 2
delivers Source Input Format (SIF)
images of 320x240 pixel images. A
shrink factor of 4 delivers smaller
Quarter SIF (QSIF) images of 160x120
pixels.
-m <frames'> Maximum number of frames to buffer. 2
This argument sets the MAX_BUFFERS
attribute, which determines how many
of the SunVideo card's buffers are used
to store frames. (The SunVideo XIL
attributes are described in Chapter 9 of
this book.)
-d When specified, does not display the Display
captured image in a desktop window.
-x <xpos'> Specifies the x-axis location of the Random
display window relative to the upper
left-hand corner of the screen.
-y <ypos'> Specifies the y-axis location of the Random
display window relative to the upper
left-hand corner of the screen.
-D <devname'> Name of the SunVideo card. See the /dev/rtvc0
section "A Comment About Moving
SunVideo Cards Among Slots" on
page 19 for more information about
SunVideo device names.
-E Exit on first XIL error. Keep running
and try to
recover
--------------------------------------------------------------------------------
Capture and display video from the S-Video port with a shrink factor of 4 (for NTSC video, this equates to a display window of 160 x120 pixels):
% rtvc_display -I 0 -s 4
Capture and display 1000 frames of video from composite port 1 (the default), skipping 29 frames between captures (for NTSC video, this will capture approximately one frame per second):
% rtvc_display -f 1000 -i 29
Capture and display video from a second SunVideo card (/dev/rtvc1).
% rtvc_display -D /dev/rtvc1
Note - The information presented in this and the other "about the code" sections assume that you are familiar with the use of the XIL functions that are described in the XIL Programmer's Guide. Attributes of XIL functions that are specific to the SunVideo card are described in Chapter 9 of this book.
The rtvc_display program demonstrates some of the basic programming elements that are common to most programs that work with SunVideo cards. The parts of the program that are highlighted in this section are:
Not described here are the parts of the example program that handle command-line arguments, perform colorspace conversion, and write to the display. These operations are described in detail in the XIL Programmer's Guide.
The source for the rtvc_display program is installed in the directory:
/opt/SUNWits/Graphics-sw/xil/examples/rtvc_display
The following example opens the XIL library. If there's an error, an error message is generated and the program exits.
-------------------------------------------------
XilSystemState state; . . state = xil_open(); if (state == NULL) { fprintf(stderr, "Unable to open xil library\n"); exit(1); } -------------------------------------------------
Use the xil_create_from_device() function to create a device image into which to capture data from a SunVideo card. The prototype of this function is
XilImage xil_create_from_device(XilSystemState state,
char *devicename, XilDevice deviceObj);
The name of the XIL I/O driver for the SunVideo card is SUNWrtvc. (The XIL SUNWrtvc driver is described in the SUNWrtvc(3) man page.) Therefore, for a SunVideo card, the xil_create_from_device() function's devicename parameter must be SUNWrtvc.
As discussed in the XIL Programmer's Guide, there are two methods available to set device attributes. The first method is to call the xil_device_create() and xil_device_set_value() functions prior to creating the device image with the xil_create_from_device() function. The second method is to call the xil_device_set_attribute() function after calling the xil_create_from_device() function.
The device attribute, DEVICE_NAME, must be set using the first method. You can set all other SunVideo device attributes using either method.
The following code example opens the device /dev/rtvc1 [3]) and connects it to the device image named rtvc_image. You can read from an rtvc (SunVideo) image or perform XIL operations on the image. Because the connection to a device image implies a capture operation, there is no need for an explicit XIL "capture" function.
----------------------------------------------------------------------------------
XilSystemState state; XilImage rtvc_image; XilDevice device; char* devname = "/dev/rtvc1"; . . if (!(device = xil_device_create(state, "SUNWrtvc"))) { fprintf(stderr, "Unable to create a device object\n"); xil_close(state); exit(1); } xil_device_set_value(device, "DEVICE_NAME", (void *) devname); if (!(rtvc_image = xil_create_from_device(state, "SUNWrtvc",(void *) device))) { fprintf(stderr, "failed to open SUNWrtvc device\n"); xil_close(state); exit(1); } xil_device_destroy(device); ----------------------------------------------------------------------------------
If the third parameter in the xil_create_from_device() call is NULL, all device attributes will have default values.
The default value for the DEVICE_NAME attribute is /dev/rtvc0. Chapter 9, "XIL Attributes for the SunVideo Subsystem," provides a complete list of the SunVideo device attributes.
Note -
Although the current XIL syntax for the xil_create_from_device()
function specifies that the third parameter is an XilDevice object, the
previous syntax also is supported in this release of the SunVideo software.
Under the previous syntax, the third parameter is the pathname specifying the
SunVideo device, such as /dev/rtvc1. If this parameter is NULL, the default
pathname is /dev/rtvc0. Supporting the previous syntax in this release
allows programs written for the SunVideo 1.0 release to work with this release.
This old syntax may not be supported in future releases.
If your SunVideo application is written in C++ rather than C, you will need to
use a #ifdef as is illustrated in the rtvc_capture_movie example to be
compatible with previous and current XIL syntax for the
xil_create_from_device() function. This is because pointers can be
assigned to and from type (void*) in C, but not in C++.
The SunVideo card's input ports connect the card's analog-to-digital converters through a 3-to-1 multiplexor. Therefore, you can capture video from only one port at a time. You cannot mix video signals from the ports.
Use the xil_set_device_attribute() function to select one of the three ports from which to capture video. The following code example uses the PORT_V attribute to select a video port on the SunVideo card. The default is composite port 1. You also use the xil_set_device_attribute() function to set other SunVideo attributes. The attributes are described in Chapter 9, "XIL Attributes for the SunVideo Subsystem."
--------------------------------------------------------------------------
int port = 1; . /* Set port attributes */ . status=xil_set_device_attribute(rtvc_image, "PORT_V",(void *) port); if(status==XIL_FAILURE) fprintf(stderr,"Failed to set the SunVideo Port attribute\n"); --------------------------------------------------------------------------
The characteristics of SunVideo images are as follows:
The luminance and color-difference ranges above adhere to those specified for a nominal video signal as defined in the CCIR Rec. 601-2 specification. However, the SunVideo card can digitize video signals that are outside the nominal specifications. In that case, image luminance or color-difference values may be less than 16 or greater than 235 or 240.
Use the xil_get_info() function to ask the capture device, in this case SunVideo, what type of image it provides.
The following code fragment is an example of the xil_get_info() function. The function returns information about the captured image's width, height, bands, and datatype. You can use this information to ensure that child images are properly sized. CellB, for example, requires that the dimensions of images used with xil_compress() be a multiple of 4. For the SunVideo device, the number of bands is 3 and the datatype is XIL_BYTE.
----------------------------------------------------------------
XilImage rtvc_image; unsigned int width, height, nbands; XilDataType datatype; . . xil_get_info(rtvc_image, &width, &height, &nbands, &datatype); ----------------------------------------------------------------
Use the xil_scale() function to capture and change the size of images. For example, you would use scale factors of 0.5 and 0.5 to scale an NTSC image from 640x480 to 320x240. The following code is an example of creating a scaled image named "scaled_image" using nearest-neighbor interpolation.
-------------------------------------------------------------
XilImage rtvc_image, scaled_image; . . xil_scale(rtvc_image, scaled_image, "nearest", 0.5, 0.5); -------------------------------------------------------------
Note - It's important to remember that XIL has no explicit capture operation. When the source for an XIL function is a device image, such as /dev/rtvc0, the capture operation is performed automatically. For example, XIL functions such as xil_scale(), xil_copy(), and xil_compress() perform a capture operation and then the scale, copy, or compress operation.
The xil_scale() function in the previous code fragment can take advantage of XIL's deferred execution facility, which can increase performance by executing certain sequences of XIL functions as a single molecule. In the rtvc_display program, for example, the sequence of the three functions xil_rescale(), xil_scale(), and xil_ordered_dither() can execute as a single molecule.
Refer to Chapter 8, "Acceleration in XIL and the SunVideo Subsystem," for more information about the sequences of functions that are accelerated by molecules.
Use the xil_rescale() function to change the range of a SunVideo image's data. The YUV images returned by the SunVideo subsystem are in the range of 16-235 for "Y" and 16-240 for "U" and "V."
To provide better contrast, you can rescale the image's data range to 0-255. The following code fragment is an example.
-------------------------------------------------------------
XilImage rtvc_image, rescaled_image; float rescale_values[3]; float offset_values[3]; . . rescale_values[0] = 255.0 / (235.0 - 16.0); rescale_values[1] = 255.0 / (240.0 - 16.0); rescale_values[2] = 255.0 / (240.0 - 16.0); offset_values[0] = -16.0 * rescale_values[0]; offset_values[1] = -16.0 * rescale_values[1]; offset_values[2] = -16.0 * rescale_values[2]; . . if (display_depth == 8) { xil_rescale(rtvc_image, rescaled_image, rescale_values, offset_values); } -------------------------------------------------------------
As discussed in the section "About the Characteristics of SunVideo Images" on
page 44, the luminance and color difference values may be outside of the
16-235 and 16-240 ranges if the signal is outside of nominal specifications. In
this case, xil_rescale() results are clipped to the 0-255 range.
See Chapter 10, "Tips and Techniques," for discussions about gamma correction and varying the range of colors in an image.
