This chapter describes the XIL attributes that are specific to the SunVideo subsystem.
We assume that you are familiar with the concepts of video compression and imaging and the related XIL functions that are described in the XIL Programmer's Guide.
The following device attributes are available for the SunVideo SUNWrtvc device.
The attributes are presented in alphabetical order in the following subsections with the buffer attributes in their own section. All structures and enumerations are defined in the header file xil.h. Some attributes are "set/get" and others are "get-only" or "set-only." This is noted in each attribute's "Access:" row.
You get these attributes with the xil_get_device_attribute() function. 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 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 shows how you might set the IMAGE_SKIP attribute. This technique applies to all of the attributes (except DEVICE_NAME).
--------------------------------------------------------------------
int image_skip = 0; . /* Enable user to override image_skip value from command line */ . xil_set_device_attribute(rtvc_image,"IMAGE_SKIP", (void *)image_skip); --------------------------------------------------------------------
DEVICE_NAME sets the pathname of the rtvc (SunVideo) device.
Access: set/get
Type: char *
Default: "/dev/rtvc0"
FILE_DESCRIPTOR returns the file descriptor that was used to open the SUNWrtvc device. This file descriptor can be used as input to the poll(2) call in order to determine when a frame is available. For example, the file descriptor could point to a SunVideo device that was accepting compressed frames at a rate of once a second. Rather than calling compress when no video is available, an application can be interrupted when a new frame is available.
Access: get
Type: int
FIRST_SCANLINE sets or gets the top scanline of a captured/processed image.
This can be useful for scrolling above or below the default video frame, especially in NTSC where the SunVideo card captures only 480 of the possible 486 active scanlines. In PAL, all 576 possible active lines can be captured simultaneously, so first scanline control is less of an issue.
Access: set/get
Type: int
The default FIRST_SCANLINE is 23 for NTSC and PAL operation. Figure 9-1 shows how the scanlines are numbered in these interlaced formats. The numbering follows video industry standards. Two interlaced fields form the complete frame; field 1 lines are shown as black lines and field 2 lines as shaded lines. The dashed half-lines, top and bottom, represent blanked (or black) video that is part of the normal active video frame structure for NTSC and PAL.
In NTSC the top half-line is from field 2, and for PAL it is from field 1. The first line captured by the SunVideo card is always from field 1.
Figure 9-1 Active Frames in NTSC and PAL
Typical ranges for FIRST_SCANLINE are 10-26 for NTSC and 4-24 for PAL. Settings that request video frame captures too soon or too late in the video frame can cause the following error message to be returned (after the attribute is set):
XILDefaultErrorFunc:
error category: System
error string: SUNWrtvc: Data Capture failed
error id: SUNWrtvc-3
...
object info: Timer expired
The SUNWrtvc I/O device driver also returns an error if you set the attribute to a negative number.
FORMAT returns the type of video format being captured: NTSC, PAL, or UNKNOWN.
Access: get
Type: char *
FORMAT_V returns 1 if capturing from a PAL video source, 2 if capturing from an NTSC video source, and 0 if there is no video or the video format cannot be determined.
Access: get
Type: int
FRAME_NUMBER provides an ID number for the last captured frame. The default starting value is zero.
Access: get
Type: int
IMAGE_SKIP sets and returns the number of images to skip between captures. You can use the IMAGE_SKIP attribute to pace the flow of images. For example, an application that supports security cameras could use the attribute to provide images at 30 second intervals.
Another example is when you want to limit the frame rate to match a network's bandwidth. To capture NTSC frames at a rate of approximately 10 fps, you would set the IMAGE_SKIP attribute to 2. This causes the SunVideo card to capture every third frame. You can use the values returned by the NUM_BUFFERS and FULL_BUFFERS attributes to determine if the IMAGE_SKIP value should be changed.
Access: set/get
Type: int
Default: 0
MPEG_FIXED_QUANT sets the quantizer scale for the bitstream, which effects the quality of SunVideo's variable bit rate MPEG-1 compressor. The integer range of values for this attribute is 1 to 31. A value of 1 produces the highest quality bitstream but also produces the most bits per second for a given frame rate. A value of 31 produces the poorest quality bitstream and the least bits per second for a given frame rate. Values you set are clipped to the valid range. The following list shows data for a typical NTSC signal:
Access: set/get
Type: int
Default: 4
MPEG_RATE_CONTROL creates a constant bit rate MPEG-1 bitstream when this attribute is set to TRUE. If this attribute is set to TRUE, only the compression of an MPEG-1 CIS is valid.
The constant bit rate MPEG-1 compressor cannot compress PAL at 384 x 288. Instead, a centered 320 x 240 image is compressed when PAL is the source.
If an application is using xil_get_info() to ask the SunVideo capture device for the type of image it will provide, the application should set the MPEG_RATE_CONTROL attribute before the call to xil_get_info().
Access: set/get
Type: Xil_boolean
Default: FALSE
MPEG_WEIGHTS sets the weights for I, P, and B frames for SunVideo's constant bit rate MPEG-1 compressor. This attribute takes as its value a pointer to a struct of three integers. For example,
------------------------------------------------------------------
typedef struct {
int weight_i;
int weight_p;
int weight_b;
} RtvcMpeg1Weights;
RtvcMpeg1Weights w;
w.weight_i = 10;
w.weight_p = 6;
w.weight_b = 1;
xil_set_device_attribute(image, "MPEG_WEIGHTS", (void*) &w);
------------------------------------------------------------------
This example tells the SunVideo constant bit rate MPEG-1 compressor to allocate six times as many bits to a P picture than a B picture and to allocate ten times as many bits to an I picture than a B picture (or 1.67 times as many bits than a P picture).
Access: set/get
Type: struct
Default: I = 4, P = 2, B = 1
The compressor pattern also plays a large role in determining the number of bits allocated to a picture type and thus to the overall quality of the bitstream. As the number of smaller weighted frame types increases, more bits are available to all frame types, which is shown in Table 9-1 where the bit rate, frame rate, and weights (I = 10, P = 6, and B = 1) are all held constant as the pattern changed. The numbers in the table represent the amount of bits allocated per macroblock for the given frame type.
Table 9-1 MPEG_WEIGHTS Example
----------------------------
Pattern I P B ----------------------------
IP 150 90
IPP 170 102
IPPPP 180 108
IPBP 270 162 27
IBPBPB 300 180 30
IBPBPBPB 310 186 31
IBPBPBPBPB 320 192 32
IBBPBB 380 228 38
IBBPBBPBB 390 234 39
IBBPBBPBBPBB 410 246 41
IBBPBBPBBPBBPBB 430 258 43
----------------------------
PORT is a string interface to select a port. The values are:
Access: set/get
Type: char *
Default: "COMPOSITE VIDEO 1"
PORT_V defines which one of the SunVideo card's three ports is being used to capture data. The values are:
Access: set/get
Type: int
Default: 1
Note - After selecting a video port with live video, the video format cannot be determined for up to one second. Therefore, a user may see a slight delay when switching ports.
TIMESTAMP returns a pointer to a volatile hrtime_t that always contains the timestamp for the most recently captured frame. Therefore, this attribute only needs to be retrieved once. The timestamp value is updated each time a capture operation occurs. This enables you to associate a timestamp with each captured frame.
The pointer points to a hrtime_t, which is an 8 byte (long long) timestamp. The units are expressed as "nanoseconds since boot." See the gethrtime(3C) man page for information about hrtime_t.
Access: get
Type: hrtime_t * (defined in <sys/time.h>)
The SunVideo card uses Dynamic RAM (DRAM) to store code, intermediate results of compression operations, as well as captured (and compressed) images. The DRAM that is available to store compressed images is divided into equally sized buffers. These image buffers are sized automatically, depending on the width and height of the images being captured and the type of compression.
The following four attributes enable you to manage the pool of image buffers:
Use the MAX_BUFFERS attribute to allocate the SunVideo card's image buffers. The value of MAX_BUFFERS has an effect on latency and the capture frame rate (performance).
Figure 9-2 shows the static relationship among the MAX_BUFFERS attribute, capture performance, and latency. In general, a larger value for MAX_BUFFERS guarantees the highest frame rate performance at the expense of increased latency.
With a value of 1 for MAX_BUFFERS, latency is minimized but the capture frame rate is guaranteed to not exceed 50% of the maximum incoming frame rate.
If the host application can reliably empty one output buffer while the SunVideo system fills the next buffer, then double buffering with a value of 2 for MAX_BUFFERS should provide optimum performance with low latency. In practice, the knee in the performance curve for achieving best capture performance typically occurs at a MAX_BUFFERS value of 4.
A value of zero for MAX_BUFFERS means to buffer as many images as possible (up to 64). If your application is capturing images to a file (where latency is not an issue), maximum buffering is useful in guaranteeing that no images are skipped.
Because the effect of the MAX_BUFFERS value on performance and latency depends on many factors (such as the type of compression), you should experiment to find the best value for your particular application.
It is possible to request more buffers than can fit into memory. In that case the number of buffers allocated is clipped. Use the NUM_BUFFERS attribute to get an integer that specifies the actual number of buffers that were allocated by the last MAX_BUFFERS request. Therefore, the value of NUM_BUFFERS will be less than or equal to the value of MAX_BUFFERS. Figure 9-3 shows an example where the number of buffers requested was twelve and the number allocated is ten.
Figure 9-3 MAX_BUFFERS and NUM_BUFFERS
The FULL_BUFFERS attribute returns an integer that specifies the number of buffers that currently contain valid data (frames that have not been retrieved by the host).
An application can use the FULL_BUFFERS attribute in conjunction with the NUM_BUFFERS attribute to determine whether the IMAGE_SKIP value should be changed. In Figure 9-4, for example, the FULL_BUFFERS value is 4 and NUM_BUFFERS is 10. Therefore, there are six buffers available and the card's capture operations can continue without losing frames.
Figure 9-4 Number of Buffers In Use
The FLUSH_BUFFERS attribute is provided to enable an application to mark all of the allocated buffers as "read," which resets the value of NUM_BUFFERS to zero.
If the FLUSH_BUFFERS attribute is set, then all saved buffers (see "MAX_BUFFERS" on page 99) will be flushed before the next image is captured. After the operation completes, the value of FULL_BUFFERS is set to zero. The input value of the set attribute call is ignored.
Access: set
Type: void *
FULL_BUFFERS returns an integer that specifies the current number of buffers that contain valid data. The FULL_BUFFERS attribute returns a valid value after the first capture (or capture/compress) operation has been performed.
Access: get
Type: int
MAX_BUFFERS sets and returns the maximum number of images that the SunVideo card's DRAM can store while waiting for the host to download the images. The value must be in the range between 0 and 64 (Figure 9-5). The value is clipped to provide the number of buffers that fit in the available memory.
Figure 9-5 Maximum Number of Buffers
Access: set/get
Type: int
Default: 2
NUM_BUFFERS returns an integer that specifies the actual number of buffers that can be used to hold captured frames. The NUM_BUFFERS value will be less than or equal to the value of the MAX_BUFFERS attribute.
The NUM_BUFFERS attribute returns a valid value after the first capture (or capture/compress) operation has been performed.
Access: get
Type: int
