SUNWrtvc(3)
NAME
SUNWrtvc − XIL driver for SunVideo capture/compression card
DESCRIPTION
SUNWrtvc is the XIL device driver for the SunVideo SBus video capture/compression card. The interface to SUNWrtvc is through the following XIL calls:
xil_create_from_device(3)
xil_get_device_attribute(3)
xil_set_device_attribute(3)
The compression capabilities are handled automatically through the XIL deferred execution scheme. Deferred execution looks for specific sequences of atomic operations that can be grouped into molecules to reduce execution time. The molecules that are accelerated are listed in the "MOLECULES" section.
For xil_create_from_device(3), the devicename parameter should be SUNWrtvc. The value parameter can be a (void ∗)NULL, in which case /dev/rtvc0 is opened, or a device name (i.e., (void ∗)"/dev/rtvc1" ). The image returned will be a 640x480 3-banded YUV image.
The following device attributes are available with the SUNWrtvc device:
FRAME_NUMBER
PORT_V
PORT
FIRST_SCANLINE
TIMESTAMP
FORMAT_V
FORMAT
IMAGE_SKIP
MAX_BUFFERS
NUM_BUFFERS
FULL_BUFFERS
FLUSH_BUFFERS
FILE_DESCRIPTOR
The following paragraphs describe the attributes in more detail. All structures and enumerations are defined in the header files xil.h or rtvc.h. Note that some attributes are "set-only" and others are "get-only." This is noted under the Access heading for each attribute.
FRAME_NUMBER
Description Provides an ID for the last captured frame.
Access set/get
Type integer
PORT_V
Description Defines which of the three ports video will be captured from.
Access set/get
Type integer
0 is the S_VIDEO port.
1 is the COMPOSITE VIDEO #1 port.
2 is the COMPOSITE VIDEO #2 port.
Default 1
PORT
Description A string interface to set the port.
Access set/get
Type char ∗
S VIDEO is the S_VIDEO port.
COMPOSITE VIDEO 1 is the COMPOSITE VIDEO #1 port.
COMPOSITE VIDEO 2 is the COMPOSITE VIDEO #2 port.
Default "COMPOSITE VIDEO 1"
FIRST_SCANLINE
Description FIRST_SCANLINE sets or gets the number of the scanline in the first field of video that will be the top scanline in a CIF image. Although scanline 21 is supposed to contain active video, some video devices may not provide active video until line 22 or line 23. Therefore, the default FIRST_SCANLINE value for both NTSC and PAL is line 23. You can set the FIRST_SCANLINE attribute to adjust an image vertically in a window. This can be useful if you want to read a scanline that’s above or below the scanlines in a nominally active frame. You can also change the attribute to adjust for variations in video devices. Depending on the video source, some legal values of this attribute can cause captures after the attribute is set to return the following error message:
XILDefaultErrorFunc:
error category: System
error string: SUNWrtvc: Data Capture failed
error id: SUNWrtvc-3
...
object info: Timer expired
The SUNWrtvc device driver also returns an error if you set the attribute to a negative or out-of-range number.
Access set/get
Type integer
TIMESTAMP
Description Returns a pointer to a volatile long that always contains the timestamp for the most recently captured frame. Therefore, this attribute only needs to be retrieved once.
Access get
Type hrtime_t
FORMAT_V
Description Returns 0 if capturing from PAL, non-zero if capturing from NTSC.
Access get
Type integer
FORMAT
Description Returns the video format being captured ("NTSC," "PAL," or "UNKNOWN").
Access get
Type char ∗
IMAGE_SKIP
Description Sets/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 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
MAX_BUFFERS
Description 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. The value of MAX_BUFFERS has a direct effect on latency, and you should experiment to find the best value for your particular application. A value of 2 (the default) provides double buffering, which enables the SunVideo firmware to write a compressed image into one buffer while the host is downloading the image from the other buffer. A value of zero means to buffer as many images as possible. A higher value means that the SunVideo card is less likely to drop frames, but the latency may be increase as a result of the buffering. If you are capturing images to a file, latency isn’t an issue, and you would use the maximum number of buffers.
Access set/get
Type int
Default 2
NUM_BUFFERS
Description NUM_BUFFERS returns an integer that specifies the 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. An application can use the NUM_BUFFERS attribute, in conjunction with the FULL_BUFFERS attribute, to determine whether the IMAGE_SKIP value should be changed. The NUM_BUFFERS attribute returns a valid value after the first capture (or capture/compress) operation has been performed.
Access get
Type integer
FULL_BUFFERS
Description FULL_BUFFERS returns an integer that specifies the current number of buffers that contain valid data. An application can use this attribute, in conjunction with the NUM_BUFFERS attribute, to determine whether the IMAGE_SKIP value should be changed. An application can use this attribute, in conjunction with the NUM_BUFFERS attribute, to determine whether the IMAGE_SKIP value should be changed.
Access get
Type integer
FLUSH_BUFFERS
Description If the FLUSH_BUFFERS attribute is set, then all saved buffers (see "MAX_BUFFERS") 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 get
Type void ∗
FILE_DESCRIPTOR
Description Returns the file descriptor that was used to open the rtvc device. This file descriptor can be used as input to the poll(2) call in order to determine when a frame is available.
Access get
Type char ∗
MOLECULES
XIL is a general-purpose imaging library that provides many low-level (atomic) functions that are designed to be used as building blocks to create higher-level functions. However, the performance of functions built from sequences of atomic functions may not be as good as the performance of high-level (specific-purpose) library functions. Functions in high-level libraries, for example, can optimize (minimize) image-paging operations by grouping operations that work on the same image. High-level functions can also minimize the number of temporary images that need to be created and destroyed during an operation.
Instead of providing directly callable high-level functions, XIL provides a deferred execution facility that automatically recognizes certain sequences of atomic operations and executes the sequences as a single molecule. An example is a sequence of XIL atoms that captures, scales, and compresses an image. XIL defers execution of the capture atom to see if a scale atom follows. If it does, execution of the capture and scale atoms are deferred to see if a compression atom follows. If it does, the three atoms are executed together as a molecule.
Note: It’s important to remember that you do not call molecules explicitly. Molecule-based acceleration occurs automatically when the XIL deferred execution facility recognizes specific sets of atoms.
To determine if atomic operations are executing within molecules, set the XIL "XIL_DEBUG" environment variable to "show_action":
%setenv XIL_DEBUG show_action
This causes the XIL library to print a message to stderr whenever an operation that affects an XIL image or compressed image sequence is executed.
The list that follows includes the molecules that the SUNWrtvc device supports currently. The atoms within the molecules are presented in the sequence that they must appear to be executed as a molecule. Atoms in square brackets are optional. For example, the scale8nearest atom is optional in the molecule:
capture -> [scale8nearest -> ] compressCellb
This sequence will be executed as a molecule with all three atoms (capture, scale8nearest, and compressCellb) or just the capture and compressCellb atoms.
In the list, the line(s) that follow the syntax of each molecule is the output of the XIL "show_action" command that shows that the atoms are being executed as a molecule.
Note: The molecules that have a "scale8nearest" option require a scale factor in the form 1/x, where x is an integer. The exceptions are the scale factors in the CellB molecules, which must be 1, 1/2, 1/4, or 1/8, or MPEG1, and JPEG molecules, which must be 1/2 (CIF).
• capture -> [scale8nearest ->] colorconvert
colorconvert(scale8nearest(capture_SUNWrtvc()))
or
colorconvert(capture_SUNWrtvc())
• capture -> [rescale8 ->] [scale8nearest ->] ordereddither8_8
ordereddither8_8(scale8nearest(rescale8(capture_SUNWrtvc())))
or
ordereddither8_8(scale8nearest(capture_SUNWrtvc()))
or
ordereddither8_8(rescale8(capture_SUNWrtvc()))
or
ordereddither8_8(capture_SUNWrtvc())
• capture -> scale8nearest -> rescale8 -> ordereddither8_8
ordereddither8_8(rescale8(scale8nearest(capture_SUNWrtvc())))
• capture -> scale8nearest
scale8nearest(capture_SUNWrtvc())
• capture -> [scale8nearest -> ] compressCellB (Where scale8nearest must be a scale factor of 1/2.)
compress_CellB(scale8nearest(capture_SUNWrtvc()))
or
compress_CellB(capture_SUNWrtvc())
• capture -> scale8nearest -> compressMpeg1 (Where scale8nearest must be a scale factor of 1/2.)
compress_Mpeg1(scale8nearest(capture_SUNWrtvc()))
• capture -> scale8nearest -> compressJpeg (Where scale8nearest must be a scale factor of 1/2.)
compress_Jpeg(scale8nearest(capture_SUNWrtvc()))
Firmware Acceleration
In addition to this host acceleration with molecules, firmware on the SunVideo card can further accelerate some molecules (or molecules with certain attributes).
The XIL molecules (with specific attributes) that are executed in firmware on the SunVideo card are contained in the following list.
• capture -> [scale8nearest -> ] compressCellB
Where the scale8nearest scale factor is 1, 1/2, 1/4, or 1/8. There are no limitations on width or height.
• capture -> scale8nearest -> compressMpeg1
Where the scale8nearest scale factor is 1/2 and width and height is not changed.
• capture -> scale8nearest -> compressJpeg
Where the scale8nearest scale factor is 1/2 and width and height is not changed.
For more information about molecules and deferred execution, refer to the Acceleration in XIL Programs chapter of the Solaris XIL Imaging Library Programmer’s Guide.
ERRORS
The following list contains the SUNWrtvc device driver’s error messages, organized by Message ID number.
SUNWrtvc-1 SUNWRtvc: invalid PORT specification The application program requested a non-existent port (either through the PORT or PORT_V attribute).
SUNWrtvc-4 SUNWRtvc: could not open SUNWRtvc device The open of /dev/rtvc∗ or /dev/rtvcctl∗ failed. The reason for the failure is printed in the default error handler. Possible causes include: the device is being used by another program; the device is not installed; the program is referencing the wrong device number.
SUNWrtvc-5 SUNWRtvc: could not set video characteristics Either the value of the FIRST_SCANLINE attribute is out of range, or the program isn’t able set the port’s characteristics.
SUNWrtvc-8 SUNWRtvc: could not open rtvc microcode file The file $XILHOME/lib/pipelines/xilSUNWrtvc_ucode.a is either non-existent or corrupt.
SUNWrtvc-9 SUNWRtvc: problem in loading rtvc microcode file An expected firmware program was missing from the microcode file.
SUNWrtvc-10 SUNWRtvc: startup of CL4000 failed Probable failure of the CL4000 compression engine or supporting logic.
SUNWrtvc-11 SUNWRtvc: reset of CL4000 failed Probable failure of the CL4000 compression engine or supporting logic.
SUNWrtvc-12 SUNWRtvc: firmware parameters not sent/received Either the video signal coming from the SunVideo card is bad (the video is from a VCR running in fast forwared, for example), or there is a firmware problem.
SUNWrtvc-13 SUNWRtvc: Data capture failed Either the video signal coming from the SunVideo card is bad (the video is from a VCR running in fast forwared, for example), or there is a firmware problem.
SUNWrtvc-14 SUNWrtvc: could not get video characteristics The program is not able to read video characteristics from the SunVideo card.
SUNWrtvc-15 SUNWrtvc: Invalid IMAGE_SKIP specification The program passed an illegal value to the xil_device_set_attribute() function.
SUNWrtvc-16 SUNWrtvc: Invalid MAX_BUFFERS specification The program passed an illegal value to the xil_device_set_attribute() function.
SUNWrtvc-17 SUNWrtvc: rtvc UNIX driver does not match XIL driver The SUNWrtvc and SUNWrtvcu packages are not compatible.
SUNWrtvc-18 SUNWrtvc: Internal Error: Insufficient buffer size This internal error indicates that the SunVideo card has encountered an internal error (a bug). Please report this error to Sun Microsystems.
For a list of XIL error messages by number, consult Appendix B of the Solaris XIL Imaging Library Programmer’s Guide.
EXAMPLES
Create a device image attached to a SUNWrtvc card and set the video port to be COMPOSITE PORT 2.
XilImage image;
char ∗attribute;
image = xil_create_from_device(state, "SUNWrtvc", (void ∗)NULL);
status = xil_set_attribute (image, "PORT", (void ∗)"COMPOSITE VIDEO 2");
if(status==XIL_FAILURE)
fprintf(stderr,"Failed to set PORT attribute");
SEE ALSO
xil_get_device_attribute(3), xil_set_device_attribute(3), xil_create_from_device(3).
Sun Microsystems — Last change: 31 August 1993