test

SunVideo Plus for PCI User's Guide

Chapter 5 XIL Attributes for SunVideo Plus

This chapter describes the XIL attributes that are specific to SunVideo Plus. This information assumes 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.

XIL operates through a 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 in this chapter. Refer to the Solaris XIL 1.0, Imaging Library Programmer's Guide for more information on general XIL programming. Source code to various XIL examples are included as part of the developer kit. These examples give developers a good start in using XIL and the SunVideo Plus card.

MMACo1k is the XIL software driver for the SunVideo Plus card. The interface to MMACo1k is through the following XIL calls:

For xil_device_create(3), the device parameter should be MMACo1k. For xil_create_from_device(3), the devicename parameter should be MMACo1k, and the deviceObj parameter can be a NULL, in which case /dev/o1k0 is opened. To open another device such as /dev/o1k1, create a MMACo1k device, set the DEVICE_NAME attribute with xil_device_set_value(3) with this device. The image returned will be a 640x480 (NTSC) or 768x576 (PAL) 3-banded YUV image.

Attributes Overview

To support binary compatibility, some of the SunVideo attributes that do not have particular applicability for SunVideo Plus are supported on a limited basis.

There are two methods for setting device attributes. The first method is to call the xil_device_create(3) and xil_device_set_value(3) functions prior to creating the device image with the xil_create_from_device(3) function. The second method is to call xil_device_set_value(3) after calling xil_create_from_device(3). Certain attributes require that they be set with the first method (such as DEVICE_NAME) and are documented as such in the following sections. See "Important Attribute Information" for addition information.

The following general device attributes are available with the MMACo1k device and are also supported by SunVideo:

The following device attributes have no affect, but are either ignored or handled by SunVideo Plus in a reasonable way to support binary and source compatibility with SunVideo.

The following are SunVideo Plus video attributes:

The following sections describe the attributes in more detail. Note that some attributes are "set-only" and others are "get-only." This is noted under the ACCESS heading for each attribute. Some of these attributes are also parameters in the SunVideo Plus control panel. Although default values are given, the true default value is the value last made in either the control panel or by a previous XIL set attribute call. These attributes have an asterisk (*) before there DEFAULT entry. See "The SunVideo Plus Control Panel and XIL Attributes" for more information.

General Attributes

DEVICE_NAME

This attribute sets the path name of the o1k (SunVideo Plus) device. You must set this attribute using the xil_device_create(3) and xil_device_set_value(3) functions prior to creating the device image.

Access: set/get Type: char * Default: "/dev/o1k0"

PORT_V

This attribute defines which of the three ports will capture the video signal.

0 

S_VIDEO port 

1 

Composite Video #1 port 

2 

Composite Video #2 port 

Access: set/get Type: int Default: 1

PORT

This attribute is a string interface to set the port.

S VIDEO 

S_VIDEO port 

COMPOSITE VIDEO 1 

Composite Video #1 port 

COMPOSITE VIDEO 2 

Composite Video #2 port 

Access: set/get Type: char * * Default: "COMPOSITE VIDEO 1"

FORMAT_V

This attribute returns 0 if the format is unknown, 1 if capturing from PAL, and 2 if capturing from NTSC. See "Video Ports, Formats, and Auto Format Detection" for more information.

Access: get Type: int

FORMAT

This attribute returns the video format being captured (NTSC, PAL, or UNKNOWN). See "Video Ports, Formats, and Auto Format Detection" for more information.

Access: get Type: char *

FRAME_NUMBER

This attribute provides an ID (a timestamp) for the last captured frame. The timestamp is initially set to -1. After the first field or frame acquired, the timestamp (FRAME_NUMBER) increments to reflect the number of fields that have been captured by the SunVideo Plus hardware.

Access: get Type: int

TIMESTAMP

This attribute 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 an hrtime_t, which is an 8-byte timestamp. The units are expressed as "nanoseconds since boot." See the gethrtime(3C) manual page for information about hrtime_t.

Access: get Type: hrtime_t * (defined in <sys/time.h>)

IMAGE_SKIP

This attribute 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 to use IMAGE_SKIP when you want to limit the frame rate to match a particular network 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 Plus card to capture every third frame.

Access: set/get Type: intDefault: 0

MAX_BUFFERS

This attribute sets and returns the maximum number of compressed frames that the XIL SunVideo Plus driver will hold while waiting for an application to retrieve via a compress call. The value must be in the range between 1 and 10. See the figure below. The value is clipped to provide the number of buffers that fit in the available memory.

Figure 5-1 Maximum Number of Buffers

Graphic

Access: set/get Type: integer Default: 2

NUM_BUFFERS

This attribute returns an integer that specifies the actual number of buffers that can be used to hold compressed frames. The NUM_BUFFERS value is 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: set Type: integer

FULL_BUFFERS

This attribute 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) has been performed.

Access: get Type: integer

FLUSH_BUFFERS

If the FLUSH_BUFFERS attribute is set, then all saved buffers are 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

Video Attributes

The following attributes affect various video characteristics. Note that these can be controlled programmatically through XIL or through the SunVideo Plus control panel described in "Using the SunVideo Plus Control Panel". Although default values are given here, the true default value is the value last set by either the control panel or by XIL program control.

HUE

This attribute affects the color hue of the incoming video signal.

Access: set/get Type: int (range -128 to +127) * Default: 0

CHROMA_GAIN_U

This attribute affects color gain of the U component of the incoming video signal.

Access: set/get Type: int (range -128 to +127) * Default: 0

CHROMA_GAIN_V

This attribute affects color gain of the V component of the incoming video signal.

Access: set/get Type: int (range 0 to 511) * Default: 180

CONTRAST

This attribute affects the contrast of the luma portion of the incoming video signal.

Access: set/get Type: int (range 0 to 511) * Default: 216

LUMA_BRIGHTNESS

This attribute affects the overall brightness level of the luma portion of the incoming video signal.

Access: set/get Type: int (range -128 to +127) * Default: 0

H.261 Attributes

These attributes are specific to SunVideo Plus when used in conjunction with H.261 compression or decompression. They have no effect if not performing hardware-based compression or decompression.

H261_BIT_RATE

This attribute sets the desired maximum compression bit rate. The rate is in bits per second of units of 1000. For example, the default value of 256 produces a maximum bit rate of 256000 bits per second (32000 bytes/sec).

Access: set/get Type: int (in kbits/sec) Default: 256

H261_MAX_QUANT

This attribute sets the desired maximum quantization. As the quantization factor is lowered, the compressed image quality improves. Since a lower quantization generally results in an increase in bits-per-image, the frame rate for a given bit rate can decrease. The opposite is true for increasing quantization.

Access: set/get Type: int (range: 1 to 31) Default: 10

H261_IBLOCK_REFRESH

This attribute sets the desired period in milliseconds before the compressor should update a given H261 macroblock with an intra-encoded block. H261 requires that each macroblock be encoded as an intra-encoded block every 132 frames. If compressing at 10 fps, this implies that a given block may not be intra-encoded for up to 13 seconds. On a lossy network, a loss of a frame results visually in distorted blocks in the decompressed image. Waiting for up to 13 seconds for these bad blocks to refresh is probably not acceptable. The purpose of this attribute is to speed up the refresh of macroblocks during lossy transmission of H261 streams over networks.

Access: set/get Type: int Default: 1500 (msec)

H261_FUR

Setting this flag issues a fast update request to the H.261 compressor. The fast update is basically the request for an intra/key frame.

Access: set/get Type: XIL_boolean Default: FALSE

H261_PIP

This flag tells the H.261 decoder to inlay a picture of the local view in the top-left corner of the decompressed image. If not performing hardware compression, the pip image is gray.

Access: set/get Type: XIL_boolean Default: FALSE

HW_DECOMPRESS_CIS

This attribute selects which CIS hardware accelerated decompression should be performed on. The default value of NULL implies that the first CIS encountered by a decompression molecule is targeted for hardware accelerated decompression. Once a CIS has been selected, any other CIS encountered by hardware decompression molecules will be rejected and the decompression will occur through the appropriate XIL software decoder. A value of -1 is a good value to use to disable hardware-based decompression.

Because XIL has no mechanism for informing the decompressor when a CIS is destroyed, this attribute must also be set in order to perform hardware accelerated decompression on a new CIS.

Access: set/get Type: XilCis Default: NULL

Important Attribute Information

Note -

XIL 1.3 attributes do not support get attribute at this time.

Video Ports, Formats, and Auto Format Detection

The default behavior of the XIL drivers is to auto detect the video format on the selected video port during device image creation. This auto detect sequence can take up to 1.5 seconds to complete. If you know the video format, the video format in the SunVideo Plus control panel can be set from AUTO to the known format (NTSC or PAL). Auto format detection is not performed in this case.

The SunVideo Plus does not currently support having two different video formats (such as NTSC or PAL) on different video ports and switching between them dynamically. When the device image is created in an XIL application, the SunVideo Plus drivers will possibly auto detect the video format on the selected video port. For this reason, it is best to set the desired video port using xil_device_set_value(3) prior to creating the device image if you do have different video formats plugged into the various video input ports. You should also do this if you do not have video plugged into the default video port (port 1).

HW Decompression and CIS Selection

The HW_DECOMPRESS_CIS attribute can be used to selectively set which CIS should use hardware accelerated decompression. An application which is going to be decompressing multiple CIS should set this attribute to -1 before any XIL decompress molecules are performed. This keeps a decompress molecule on a CIS that you do not want to hardware decode from attaching itself to the hardware. Before performing a decompress molecule on the CIS that you do want to use hardware decompression on, set the HW_DECOMPRESS_CIS attribute.

HW Decompression and Creating an XIL Device

When performing hardware based decompression, the SunVideo Plus acts like an XIL compute device in that it is accelerating an XIL molecule. For applications that use decompression only, it is not necessary to create an xil device and device image as described in "Creating a Sample MMACo1k Device Image". The exception to this is when an application wants to set a device specific attribute that affects decompression. There is no method in XIL of setting certain types of attribute on a compute device like the SunVideo Plus, short of opening the device explicitly and then setting the attribute. Thus, to use such attributes, you must create an xil device and image. See "XIL Source Examples" for more information.

If a device and device image are not created directly by an application, the hardware-based SunVideo Plus XIL decompression molecules will do this implicitly. However, the molecules do not currently hunt for a available hardware device to use as an accelerator. They currently attempt to use the first device in a system (/dev/o1k0). Thus, if multiple SunVideo Plus cards are installed in your system, the only current way to use each as a hardware-accelerated decompression device is to explicitly create a device and device image in an application and use a different device name for each device creation. See "XIL Source Examples" for more information.

Using Both HW Compression and HW Decompression

The previous section explained that the hardware decompression molecule of SunVideo Plus will implicitly create a device and device image if one has not already been created. Thus, if an application performed a decompress molecule and then created an MMACo1k device and device image, it would receive the device and image previously created implicitly by the decompress molecule. However, there is a problem in XIL with respect to deleting the device image. For this reason, if both hardware compression and decompression are to occur in an application, then the application is required to explicitly create a device and device image before the first hardware decompress molecule occurs.

The SunVideo Plus Control Panel and XIL Attributes

All of the video related parameters in the SunVideo Plus control panel have XIL attributes that enable an application developer to programmatically change these parameters. These attributes in XIL do not have default values because the default value is the current value set by the control panel. Thus, unless an application explicitly sets a given video attribute, the control panel value is used.

This is a feature of SunVideo Plus. It removes the responsibility of setting video parameters (such as brightness, contrast, and so on) out of an XIL application. Thus, end users can tune these video parameters for their video source once and not have to deal with making the same changes each time they run an XIL application.

Note that the source for both of these XIL attributes and the parameter in the control panel is the same. Therefore, making a change to one of these parameters through an XIL set attribute call will also change the value in the control panel. For example, if an XIL application sets the brightness to a given value and then exits, the next XIL application that is run will use this new brightness setting unless it also sets a new value.

Molecules

The following lists the color and grayscale molecules that the MMACo1k device currently supports.

Errors

The following table lists MMACo1k device driver error messages.

Table 5-1 MMACo1k Error Messages

Error Message 

Description 

MMACo1k-1

MMACo1k: invalid PORT specification

MMACo1k-4

MMACo1k: could not open MMACo1k device. 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. 

MMACo1k-5

MMACo1k: could not set video characteristics. The program is not able to set the port characteristics.

For a list of other XIL error messages, see Appendix B of the XIL Programmer's Guide.

Creating a Sample MMACo1k Device Image

Create a device image attached to a SunVideo Plus card, and set the video port to be COMPOSITE VIDEO 2. To do this, type: 

# XilImage
image
# XilDevice image

where image = xil_create_from_device(state, "MMACo1k", device); device = xil_device_create(state, "MMACo1k") xil_device_set_value(device, "DEVICE_NAME", (void *) "/dev/o1k0"); xil_device_set_value(device, "PORT", (void *) "COMPOSITE VIDEO 2")

XIL Source Examples

The best source of information about programming using the XIL programming interface is within the XIL examples provided in the developer kit. The following table lists these examples.

Table 5-2 XIL Source Examples

XIL Source Example 

Description 

xil_display

A video capture and display example. This example could be easily modified to be a video recorder or player. 

xil_compress

A video compression example. This example shows how to compress and save to disk various compression formats. It also illustrates setting device-specific attributes such as the bitrate setting for H.261. 

xil_decompress

An example of how to perform video decompression. For the most part, this example does not require a hardware based entity to provide decompression since XIL software decoders will do the work implicitly. The example does show, however, how to use the SunVideo Plus hardware-based H261 decompression. 

xil_broadcast

This example shows how to capture and compress video and a method for broadcasting this video over a network using UDP. 

xil_receive

This example shows how to receive video from xil_broadcast and how to decompress and display it.

xilh_broadcast

Same as xil_broadcast, but adds H261.

xilh_receive

Same as xil_receive, but adds H261.

o1k_conf

A GUI point-to-point conference application that uses XIL and libotiaudio.