The Video Library defines a basic set of primitives and mechanisms that specify interconnections and controls for the desired setup. The following concepts are central to VL:

The HD I/O Board has a video source node (the video input), a video drain node (the video output), a memory source node (for output from application), and a memory drain node (for input to application). For transfers, each path must contain exactly one video node and one memory node. HD I/O nodes are further discussed in “VL Nodes for the HD I/O Board ”.

VL syntax elements are as follows:

The VL recognizes these classes of objects:

Following are the two types of VL controls:

Using the HD I/O Board with both types of VL controls is explained later in this chapter. 

Use  vlGetNode() to specify nodes. This call returns the node's handle, which is used when setting controls or setting up paths. Its function prototype is:

VLNode vlGetNode(VLServer svr, int type, int kind, int number)

In this prototype, variables are as follows:

VL_ANY can also be used as a value for number to reference the first available node of the specified type and kind.

In general, a path for the HD I/O Board has a memory node and a video node. The following fragment creates a digital video input source node and a memory drain node, and creates the path:

VLServer svr;
VLPath path;
VLNode src;
VLNode drn;
                     /*Set up video source node */
src = vlGetNode(svr, VL_SRC, VL_VIDEO, VL_ANY);
                     /*Set up memory drain node */
drn = vlGetNode(svr, VL_DRN, VL_MEM, VL_ANY); 
                     /* Create source-to-drain path */
if((path = vlCreatePath(svr, VL_ANY, src, drn)) < 0){ 
     fprintf(stderr,”%s\n”,vlStrError(vlGetErrno()));
     exit(1);
}
                     /* Set up path with shared src and drn node */
vlSetupPaths(svr, (VLPathList)&path, 1, VL_SHARE, VL_SHARE);

After you specify the nodes, use vlSetControl() to specify the parameters as follows:

Controls for each node are defined in “HD I/O Controls”, and are summarized in Table 2-2. You can set controls in any order.  

This section summarizes VL data transfer categories, and provides basic instructions for creating an application. For the HD I/O Board, VL data transfers always involve memory (video to memory, memory to video), which requires a DMbuffer pool setup.

Follow these steps to create a VL application using the VL programming model:

The diagram in Figure 2-2 shows the input data flow.

Figure 2-2. Input Data Flow

The diagram in Figure 2-2 shows the output data flow.

Figure 2-3. Output Data Flow

The diagram in Figure 2-4 shows the control flow.

Figure 2-4. Control Flow

After you set up a path, and before you start a transfer, you must configure the memory and video nodes appropriately. Controls on the video node are persistent; that is, they retain their values between path destruction and creation. Memory node controls, however, are reset at each path creation. Because the video node controls are persistent, they need not be set by an application that can deal with arbitrary settings.

For a memory node, you must set the following controls because the default values are likely to be inappropriate:

On the video node, applications will probably need to set some controls as well. Most of them can also be set with the video control panel application (vcp).

To determine the available devices (that is, video options in the workstation, such as the HD I/O Board) and the nodes available on them, run vlinfo. To determine possible controls for each device, enter

vlinfo -l

---

Note: VL controls specified as true with vlSetControl() are executed immediately. However, they do not necessarily occur at a specific time.

---

To set controls for HD I/O nodes, use  vlSetControl(). The following example sets video format and timing on a node:

timing.intVal = VL_TIMING_1125_1920x1080_5994i;
format.intVal = VL_FORMAT_DIGITAL_COMPONENT
;

if (vlSetControl(svr, path, drn, VL_TIMING, &timing) <0)
{
     vlPerror(“VlSetControl:TIMING”);
     exit(1);
}
if (vlSetControl(svr, path, drn, VL_FORMAT, &format) <0)
{
     vlPerror(“VlSetControl:FORMAT”);
     exit(1);
 }

For details on vlSetControl() and vlGetControl(), see the latest version of the DMPG.

Table 2-1 summarizes node controls for the HD I/O Board.

---

Note: Except for VL_XTHD_VITC_LINE_OFFSET, VL_H_PHASE, and VL__VPHASE, none of the controls can be changed during a transfer.

---

Table 2-2 summarizes the values and uses of controls for the HD I/O Board.

The VL_TIMING control sets timing type, which expresses the timing of video presented to a source or drain.

---

Note: For the HD I/O Board, VL_TIMING is specified on the video node only, and not on the memory mode, as with other Silicon Graphics video options.

---

Table 2-3 lists output timings for various inputs.

Each value for VL_TIMING indicates the raster configuration of a particular SMPTE specification, such as SMPTE 274M-1995 system 3. The values are named according to the raster format:

For example, VL_TIMING_1125_1920x1080_5994i specifies 1125 total lines, an active region of 1920 pixels by 1080 lines, 59.94 fields per second, and 2:1interlacing.

---

Note: Although the VL defines timings with sampling rates up through 148.5 MHz, the HD I/O Board supports only those through 74.25 MHz.

---

The HD I/O Board has flexible sync and genlock controls. You can select sync for the outputs only; inputs sync only to the sync and clock information embedded in the digital input stream.

You can configure the video output to lock to an external sync source (genlock) or to free run (stand-alone). The VL_SYNC control allows you to select stand-alone mode or one of the genlock modes. If the setting is genlock, the following sync sources are available:

For valid sync source/timing genlock combinations, see Table 2-3. Only these combinations are supported.

The VL_FORMAT control is used on video nodes only. It specifies the sampling format of data on the wire, specifically, dual-link (4:4:4 or 4:4:4:4) or single-link (4:2:2).

The memory packing mode VL_PACKING determines how components are actually sampled.

VL_FORMAT does not imply color space, nor does it imply whether the second link is used. The second link is used whenever alpha/key channel is used, which depends on the VL_PACKING setting, or when color is sampled at 4:4:4.

A video packing describes how a video signal is stored in memory, in contrast to a video format, which describes the characteristics of the video signal. For example, the memory source node accepts packed video from a DMbuffer and outputs video in a given format. Packings are specified through the VL_PACKING control on the memory nodes.

---

Note: Because of HDTV's multiple color spaces, “old style” packings, such as VL_PACKING_Y_8_P, are ambiguous and therefore no longer supported for the HD I/O Board. You must specify the packing and color space explicitly.

---

The HD I/O Board supports common packings up through 32 bits per pixel, including 4:4:4, 4:2:2, and 4:4:4:4, at 8, 10, and 12 bits per component. Specifically, it supports packings compatible with OpenGL and IRIS GL, and those in common use from other video products. Appendix C, “Pixel Packings and Color Spaces ” shows the layout of each packing for the HD I/O Board. It also provides the corresponding names for these packings that are used by other libraries.

An application must set both VL_PACKING and VL_COLORSPACE. Note that changes in one parameter may change the values of other parameters set earlier; for example, clipped size may change if VL_PACKING is set after VL_SIZE. For example:

VLControlValue val;

val.intVal = VL_PACKING_444_8;
vlSetControl(vlSvr, path, memdrn, VL_PACKING, &val);

---

Note: At the beginning of a data transfer, it takes several seconds to activate a change in this control.

---

The VL_COLORSPACE control specifies the color space of video data in memory or for input and output. A color space is a color component encoding format, for example, RGB and YUV. Because video equipment uses more than one color space, the HD I/O video nodes, in addition to the memory nodes, support the VL_COLORSPACE control.

Each component of an image has

Normally, a component stays within the minimum and maximum values. For example, for a luma signal such as Y, you can think of these limits as the black level and the peak white level, respectively. For an unsigned component with n bits, there are two possibilities for [minimum value, maximum value]:

Color Spaces and Color Models

Various HDTV specifications define color models differently from those defined in Recommendation 601 ( ITU-R BT.601), which is used by most standard-definition digital video equipment. For HDTV, the VL defines three color models:

• SMPTE 240M

• SMPTE 274M Recommendation 709 ( ITU-R BT.709-2)

• Recommendation 601 (ITU-R BT.601)

Within each color model, four different color spaces exist:

• YCrCb: headroom range

  Headroom range means that black is at, for example, code 64 rather than 0, and white is at, for example, code 940 rather than 1023. Headroom-range color spaces can accommodate overshoot (superwhite) and undershoot (superblack) colors. Full-range color spaces clamp these out-of-range colors to black and white.

• YUV: full range

• RGB_H: headroom range

• RGB_F: full range

For memory nodes, these four color spaces are defined for each of three color models, resulting in 12 color spaces. Note that all 12 are supported on memory nodes, but only YCrCb and RGB_H color spaces are supported on video nodes.

Table 2-4 summarizes currently supported combinations of VL_FORMAT and VL_COLORSPACE; future releases will support more combinations. For detailed information on supported combinations, refer to the XTHD MAN pages and release notes regarding “Color Representations.”

Table 2-4. VL_FORMAT and VL_COLORSPACE Combinations Supported

Video Node	Memory Node
4:2:2 YCrCb	4:4:4 RGB_F
4:2:2 YCrCb	4:4:4 RGB_H
4:2:2 YCrCb	4:2:2 YCrCb
4:4:4YCrCb	4:4:4 YCrCb
4:4:4 RGB_H	4:4:4 RGB_H

Color-space conversion is performed within a color model if the color spaces are different on the memory and video nodes. Conversion between the color models is not supported.

---

Note: Changing this control at the beginning of data transfer takes several seconds to go into effect.

---

Typically, two sets of colors are used together, RGB ( RGBA) and YCrCb /YUV ( VYUA). YCrCb ( YUV), the most common representation of color from the video world, represents each color by a luma component called Y and two components of chroma, called Cr (or V), and Cb (or U). The luma component is loosely related to brightness or luminance, and the chroma components make up a quantity loosely related to hue. These components are defined in ITU-R BT.601 (also known as Rec. 601 and CCIR 601), ITU-R BT.709-2, and SMPTE 240M.

The alpha channel is not a real color. For that channel, the minimum value means completely transparent, and the maximum value means completely opaque.

For OpenGL, IRIS GL, and DM:

• the library constant indicates whether the data is RGBA or VYUA

• RGBA data is full-range by default

• VYUA data in DM can be full-range or compressed-range; you must determine this from context

For more information about color spaces, see A Technical Introduction to Digital Video, by Charles A. Poynton (New York: Wiley, 1996).

VL_COLORSPACE Examples

Figure 2-5 and Figure 2-6 show examples of color-space conversions.

In the examples, RGB are values in linear space and R'G'B' are values in nonlinear space after the optoelectric transfer function is applied as specified in ITU-R BT.709. You can use the LUTs to apply this function or its inverse to convert between RGB and R'G'B'.

The example in Figure 2-5 shows a typical video capture path. In this example, the input jack is YCrCb 4:2:2 and the desired result in system memory is RGB. First, an appropriate filter interpolates YCrCb 4:2:2 to YCrCb 4:4:4 to fill in the missing CrCb samples. Then a 3x3 matrix multiplier with appropriate offsets and coefficients obtains RGB values for each pixel. At this point, you can use the LUT option to convert gamma pre-corrected RGB values to linear RGB values. Finally, the packer swizzles the bits into the desired memory packing format and DMA places the result in system memory.

Figure 2-5. Color-Space Conversion Example 1

Figure 2-6 summarizes a complicated conversion between color spaces for 4:2:2 sampling rates and different primary colors. The example shows the conversion of material produced using SMPTE 240M colorimetry to material in SMPTE 274M format (ITU-R BT.709.2 colors).

Figure 2-6. Color-Space Conversion Example 2

An application can request that the HD I/O Board capture or play back a video stream in a number of ways. For example, the application can request that each field be placed in its own buffer, or that each buffer contain an interleaved frame. This section describes the capture types supported by the HD I/O Board.

Supported capture types are as follows:

VL_CAPTURE_FIELDS is equivalent to VL_CAPTURE_NONINTERLEAVED. The HD I/O Board does not support VL_CAPTURE_EVEN_FIELDS and VL_CAPTURE_ODD_FIELDS.

---

Note: VL_SIZE refers to the size of each frame, rather than the size of the buffer in memory, so it is independent of VL_CAP_TYPE; the VL_CAP_TYPE setting does not change VL_SIZE.

---

VL_SIZE refers to the size of each frame, rather than the size of the buffer in memory, so it is independent of VL_CAP_TYPE; the VL_CAP_TYPE setting does not change VL_SIZE.

For memory nodes, VL_SIZE specifies the desired region of the video raster, which must be the same as the default active region. There is no default; this control must be set. On video nodes, this control is read-only and cannot be set.

For memory nodes, VL_OFFSET is related to VL_SIZE; it specifies the origin of the video region to be captured at (0,0), the standard beginning of active video. The recommended way to set VL_SIZE for the memory node is to query it on the video node (after setting VL_TIMING appropriately) and use the returned value to set VL_SIZE on the memory node.

The VL_ZOOM control specifies the site of the top video line in memory; it does not scale (zoom and decimate) a video image as for some other Silicon Graphics video options. The VL_ZOOM value can be 1 or -1:

This example shows an application that simply captures video data and records it to disk, for later playout. The video is left in its original 4:2:2 sampling and color space. Because 10 bits are required, the R242_10 packing mode is chosen. Frames start on F1 boundaries. After creating the VL path, the application sets up the video node, mostly as a result of user input, since it depends on external equipment.

videoSource.VL_TIMING = VL_TIMING_1125_1920x1080_5994i
videoSource.VL_COLORSPACE = VL_COLORSPACE_REC709_YCRCB
videoSource.VL_FIELD_DOMINANCE = VL_F1_IS_DOMINANT
videoSource.VL_FORMAT = VL_FORMAT_DIGITAL_COMPONENT
videoSource.VL_XTHD_LOOPBACK = VL_XTHD_LOOPBACK_OFF 
videoSource.VL_XTHD_INTERFACE_PRECISION = VL_XTHD_INTERFACE_PRECISION_10

Next, the application configures memory node:

memoryDrain.VL_SIZE = videoSource.VL_SIZE 
memoryDrain.VL_COLORSPACE = videoSource.VL_COLORSPACE
memoryDrain.VL_CAP_TYPE = VL_CAPTURE_NONINTERLEAVED
memoryDrain.VL_PACKING = VL_PACKING_R242_1

Next, the application calls vlGetTransferSize() to get the required buffer size to hold each field. Using that size, it creates and registers a DMS buffer pool and starts the transfer.

This example shows an application that plays back data captured in the previous example.

The application in the previous example stored various attributes along with the data, including color space, frame rate, dominance, and size. These attributes, along with some user-specified options, are used to derive the control values. After creating the VL path, the application sets up the video node:

videoDrain.VL_TIMING = VL_TIMING_1125_1920x1080_5994i
videoDrain.VL_COLORSPACE = VL_COLORSPACE_REC709_YCRCB
videoDrain.VL_FIELD_DOMINANCE = VL_F1_IS_DOMINANT 
videoDrain.VL_FORMAT = VL_FORMAT_DIGITAL_COMPONENT
videoDrain.VL_XTHD_INTERFACE_PRECISION = VL_XTHD_INTERFACE_PRECISION_10
videoDrain.VL_SYNC = VL_SYNC_GENLOCK 
videoDrain.VL_SYNC_SOURCE = VL_XTHD_SYNC_HOUSE 

Next, the application configures the memory node:

memorySource.VL_SIZE = videoDrain.VL_SIZE 
memorySource.VL_COLORSPACE = videoDrain.VL_COLORSPACE
memorySource.VL_CAP_TYPE = VL_CAPTURE_NONINTERLEAVED
memorySource.VL_PACKING = VL_PACKING_R242_10

Next, the application calls vlGetTransferSize() to get the required buffer size to hold each field. Using that size, it creates a DMS buffer pool, allocates, fills, and prequeues some buffers, and starts the transfer.

In this example, the application captures video and draws it on the graphics screen using OpenGL. This example resembles the videoin application.

The incoming video is converted to 10-bit 4:4:4 full-range RGB in an OpenGL-compatible packing format. The 4444_10_10_10_2 packing is chosen; it is compatible with OpenGL using packed-pixel extension GL_UNSIGNED_INT_10_10_10_2_EXT pixel format. Video is interleaved in memory into frames, and is written upside down to be compatible with OpenGL's default coordinate system (glPixelZoom of (1.0, 1.0)).

First, the video node is configured:

videoSource.VL_TIMING = VL_TIMING_1125_1920x1080_5994i
videoSource.VL_COLORSPACE = VL_COLORSPACE_REC709_YCRCB
videoSource.VL_FIELD_DOMINANCE = VL_F1_IS_DOMINANT
videoSource.VL_FORMAT = VL_FORMAT_DIGITAL_COMPONENT
videoSource.VL_XTHD_LOOPBACK = VL_XTHD_LOOPBACK_OFF
videoSource.VL_XTHD_INTERFACE_PRECISION = VL_XTHD_INTERFACE_PRECISION_10 

Next, the application configures memory node:

memoryDrain.VL_SIZE = videoSource.VL_SIZE 
memoryDrain.VL_COLORSPACE = VL_COLORSPACE_REC709_RGB_F
memoryDrain.VL_CAP_TYPE = VL_CAPTURE_INTERLEAVED 
memoryDrain.VL_PACKING = VL_PACKING_4444_10_10_10_2 memoryDrain.VL_ZOOM = -1/1 

Next, the application calls vlGetTransferSize() to get the required buffer size to hold each field. Using that size, it creates and registers a DMS buffer pool and starts the transfer.