To build programs that run under VL, you must

The client library for VL is /usr/lib32/libvl.so. The header files for the VL are in /usr/include/dmedia; the main file is vl.h. This file contains the main definition of the VL API and controls that are common across all hardware. Several useful digital media programming examples are in /usr/share/src/dmedia/video.

---

Note: When building a VL-based program, you must add -lvl to the linking command.

---

For more information on the Video Library and the API usage, see the latest version of the DMPG.

This section explains

VL Concepts

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

• path: an abstraction for a way of moving data around

• node: an endpoint of the path

The basic nodes are a source (such as a VTR) and a drain (such as memory). Figure 2-1 diagrams the simplest VL path, with one of each of these two nodes.

Figure 2-1. Simple VL Path

The two other types of nodes besides source and drain are device node and internal node. DIVO does not support any internal nodes.

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

VLServer svr;
VLPath path;
VLNode src;
VLNode drn;
VLControlValue timing,format, ctrlval;
src = vlGetNode(svr, VL_SRC, VL_VIDEO, VL_ANY);
drn = vlGetNode(svr, VL_DRN, VL_MEM, VL_ANY);
if((path = vlCreatePath(svr, VL_ANY, src, drn)) < 0){
     fprintf(stderr,”%s\n”,vlStrError(vlGetErrno()));
     exit(1);
}
vlSetupPaths(svr, (VLPathList)&path, 1, VL_SHARE, VL_SHARE);

src = vlGetNode(svr, VL_SRC, VL_VIDEO, VL_ANY);

vlGetControl(svr, path, VL_ANY, VL_DEFAULT_SOURCE, &ctrlval);
nodehandle = vlGetNode(svr, VL_SRC, VL_VIDEO, ctrlval.intVal);

drn = vlGetNode(svr, VL_DRN, VL_MEM, VL_ANY); /*Get a memory drain node */
vlAddNode(svr, path, drn); /* Add node to the exisiting path */ 

Compression is handled via enhancements to the VL API; the DIVO board does not support the Compression Library API.

Compression in the VL is supported by adding compression-related controls on memory nodes. The control VL_COMPRESSION specifies the compression. Based on the compression type, additional controls specify compression-related parameters. Table 2-2 later in this chapter summarizes these controls.

DIVO can use Rice compression, a lossless entropy coding mechanism that provides an average compression of 2:1. In some cases, compression can add to the size of the data being transferred, but is limited to a maximum of 1% bloat. Tests at Silicon Graphics show that this compression mechanism can reduce data in ratios of 2:1 to 6:1.

To determine the available devices (that is, video options in the workstation, such as the DIVO board) and the nodes available on them, run vlinfo. To determine possible controls for each device, run

vlinfo -l

---

Note: VL controls specified as true with vlSetControl() are executed immediately. However, they are not guaranteed to happen at a specific time. For better precision on the execution of these controls, see “Specifying Execution Times,” later in this chapter.

---

To set controls for DIVO nodes, use vlSetControl(). The following example sets video format and timing on a node.

timing.intVal = VL_TIMING_525_CCIR601;
format.intVal = VL_FORMAT_RGB;

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.

Tables in this section summarize

The online device-global control for DIVO is VL_DEFAULT_SOURCE (value DIVO_SRC_DIGITAL_VIDEO), which determines the source node selected by VL when VL_ANY has been specified as the source node. DIVO has only one video source.

Table 2-1 summarizes supported node controls for DIVO.

Table 2-2 summarizes the values and uses of controls for DIVO.

Field dominance identifies the frame boundaries in a field sequence, that is, it specifies which pair of fields in a field sequence constitute a frame. The control VL_FIELD_DOMINANCE allows you to specify whether an edit occurs on the nominal video field boundary (field 1) or on the intervening field boundary (field 2)).

Figure 2-2 shows fields as defined for NTSC and PAL.

---

Note: In digital formats and other input modes, half lines become full lines.

---

Figure 2-2. Fields and Frames for NTSC and PAL

Users typically want to edit on Field 1 boundaries, where Field 1 is defined as the first field in the video standard's two-field output sequence. 525 standards send the second (whole) raster line out to begin the first field, and the first (half) raster line out to begin the second field; 625 standards send the first (half) raster line out to begin the first field, and the second (whole) raster line to begin the second field.

Some users may want to edit on F2 boundaries, which fall on the field in between the video standard's frame boundary. To do so, use this control, then program your deck to select F2 edits.

NTSC users might need to vary their field dominance choice, depending on the origin of the input material they are to edit.

---

Note: To output a set of frames, they must be deinterlaced into fields differently, depending on the choice of output field dominance. For example, when F1 dominance is selected, the field with the topmost line must be the first field to be transferred; when F2 dominance is selected, the field with the topmost line must be the second field to be transferred. Deinterlacing must be specified in the application; the following code fragment contains an example of how to consult the field dominance control to determine deinterleave order.

---

/*
* Set the memory node's timing based upon the video drain's timing,
 * which has been set up by the daemon from the defaults file, or by
 * the user via vcp.
 *
 * When we get around to reading image files, we'll check the file
 * size against the size reported by the VL for this node: if the file
 * size does not match the format's, we'll punt.
 */

if (vlGetControl(svr, MEMtoVIDPath, drn, VL_TIMING, &drainTiming) < 0) {
	    vlPerror(“GetControl(VL_TIMING) on video drain failed”);
    exit(1);
}
if (vlSetControl(svr, MEMtoVIDPath, src, VL_TIMING, &drainTiming) < 0) {
    vlPerror(“SetControl(VL_TIMING) on memory source failed”);
    exit(1);
}
/*
 * Read the video drains's field dominance control setting and timing,
 * then set a variable to indicate which field has the first line, so 
 * readimage() will know how to deinterleave frames to fields.
 */
if (vlGetControl(svr, MEMtoVIDPath, drn,
    VL_FIELD_DOMINANCE, &dominance) < 0) {
    vlPerror(“GetControl(VL_FIELD_DOMINANCE) on video drain failed”);
    exit(1);
}

is_525 = (drainTiming.intVal == VL_TIMING_525_CCIR601));

switch (dominance.intVal) {
    case VL_F1_IS_DOMINANT:
        if (is_525) {
        F1_is_first = 0;
        } else {
        F1_is_first = 1;
        }
        break;
    case VL_F2_IS_DOMINANT:
        if (is_525) {
        F1_is_first = 1;
        } else {
        F1_is_first = 0;
        }
        break;
    }

/*
 * Read the video drain's field dominance control setting and set a
 * variable to indicate which field has the first line.
*/
if (vlGetControl(svr, MEMtoVIDPath, drn,
    VL_FIELD_DOMINANCE, &val) < 0) {
    vlPerror(“GetControl(VL_FIELD_DOMINANCE) on video drain failed”);
    exit(1);
}

switch (val.intVal) {
    case VL_F1_IS_DOMINANT:
        F1_is_first = 1;
        break;
    case VL_F2_IS_DOMINANT:
        F1_is_first = 0;
        break;
    }

To assemble fields to frames, the application must consult the field dominance control in order to determine the interleave order. The following code fragment contains an example of how to consult the field dominance control to determine interleave order.

/*
 * Set the memory node's timing based upon the video source's timing,
 * which has been set up by the daemon from the defaults file, or by
 * the user via vcp.
 */
if (vlGetControl(svr, path, src, VL_TIMING, &timing) < 0) {
    vlPerror(“GetControl Failed”);
    exit(1);
}
if (vlSetControl(svr, path, drn, VL_TIMING, &timing) < 0) {
    vlPerror(“SetControl Failed”);
    exit(1);
}
/*
 * Read the video source's field dominance control setting and timing,
 * then set a variable to indicate which field has the first line.
*/
if (vlGetControl(svr, path, src,
    VL_FIELD_DOMINANCE, &dominance) < 0) {
    vlPerror(“GetControl(VL_FIELD_DOMINANCE) on video source failed”);
    exit(1);
}

is_525 = (timing.intVal == VL_TIMING_525_CCIR601));

switch (dominance.intVal) {
    case VL_F1_IS_DOMINANT:
        if (is_525) {
        F1_is_first = 0;
        } else {
        F1_is_first = 1;
        }
        break;
    case VL_F2_IS_DOMINANT:
        if (is_525) {
        F1_is_first = 1;
        } else {
        F1_is_first = 0;
        }
        break;
    }

The VL API supports the GPI as a device-independent interface. It supports GPI triggers in three vlSetControl() interfaces. The union VLControlValue has been extended to support the controls

---

Note: Use the VL_TRANSFER_TRIGGER, supported on video nodes, to set up triggering for beginning the transfers on a path. For more information, see “Using VL_TRANSFER_TRIGGER,” later in this chapter. See Appendix A, “DIVO I/O Panel Connector Specifications,” for hardware information on the GPI interface.

---

VLControlValue val;

                          /* make sure the GPI line is high */
val.gpi_state.gpi   = VL_GPI_OUT;
val.gpi_state.instance = <which GPI line>;
val.gpi_state.state =  VL_GPI_OFF;   
vlSetControl(svr,path,VL_GPI_STATE,&val);

                          /* transfer start */
val.gpi_out.condition = VL_GPI_OUT_XFER_START;
val.gpi_out.instance  = <which GPI output line >;
val.gpi_out.state     = VL_GPI_ON;

vlSetControl(svr,path,VL_GPI_OUT_MODE,&val);

                          /* transfer stop */
val.gpi_out.condition = VL_GPI_OUT_XFER_STOP;
val.gpi_out.instance  = <which GPI output line >;
val.gpi_out.state     = VL_GPI_OFF;

vlSetControl(svr,path,VL_GPI_OUT_MODE,&val);

VLControlValue val; 

val.gpi_state.gpi   = VL_GPI_OUT;
val.gpi_state.instance = <which GPI line>;
val.gpi_state.state =  VL_GPI_CLEAR;

vlSetControl(svr,path,VL_GPI_STATE,&val);

val.gpi_state.gpi = VL.GPI.IN;
val.gpi_state.instance = <which GPI line>;
vlGetControl (svr, path, VL_GPI_STATE, &val);

The VL provides several ways of handling data stream events, such as completion or failure of data transfer, vertical retrace event, loss of the path to another client, lack of detectable sync, or dropped fields or frames. The method you use depends on the kind of application you are writing:

For more information on these functions, see Chapter 4 in the Digital Media Programming Guide.

Table 2-3 summarizes events for DIVO. For DIVO, this table supersedes the table of events in Chapter 14, “VL Event Handling,” in the DMPG; DIVO supports only the events listed in Table 2-3.

Controls executed with vlSetControl() have no guarantees as to when they are executed once transfers are in progress because of the asynchronous nature of the implementation. However, in certain situations, it is useful to be able to specify when controls on a path are executed, for example, to play out video clips with different packings or color-space formats without having to stop transfers while a memory-to-video operation is in progress. You can specify execution times by

int vlSetControlInLine(VLServer svr, VLPath path, VLNode node, 
     VLNode refnode, VLControlType control, VLControlValue *controlVal)

Controlval.intval = VL_PACKING_444_12;
vlSetControlInLine(svr,path,vlMem, vlMem, VL_PACKING, &ControlVal;

int vlSetControlTrigger(VLServer svr, VLPath path, VLNode node,     
     VLTriggerType trigger, VLTriggerData *triggerdata, 
     VLControlType control, VLControlValue *contrlVal) 

typedef union {
    VLNode refnode; /* trigger defined with reference to this node 
         - MSC */
} VLTriggerParam;

typedef union {
    stamp_t msc;        /* msc trigger - MSC */
    uint32_t instance;  /* Which trigger - GPI */
    DMtimecode vitc;    /* vitc - VITC */
} VLTriggerVal;   
typedef struct {
    VLTriggerParam param;
    VLTriggerVal val;
} VLTriggerData;

VLNode video_node, mem_node;
VLTriggerData triggerData;
VLControlValue contrlVal;

triggerData.param.refnode = mem_node; /* identifies the connection
       within the path */
triggerData.vl.msc = <which gpi> /* which gpi input line to trigger 
       on */

contrlVal.intVal = VL_FORMAT_DIGITAL_COMPONENT_DUAL_SERIAL
vlSetControlTrigger (svr, path, video_node, VL_TRIGER_GPI,
       &triggerData, VL_FORMAT, &contrlVal);

typedef struct {
  int triggerType;  /*VL_TRIGGER_GPI, VL_TRIGGER_VITC,VL_TRIGGER_MSC */   
  VLTriggerVal value;
} VLTrigger;
/* Trigger-specific data */
typedef union {
    stamp_t msc;        /* msc trigger - MSC */
    uint32_t instance;  /* Which trigger - GPI */
    DMtimecode vitc;    /* vitc - VITC */
} VLTriggerVal;   
{
...
VLTrigger xfer_trigger;
} VLControlValue

vlSetControl(svr, path, node, VL_TRANSFER_TRIGGER, VLControlValue *);

VLControlValue val;

val.xfer_trigger.triggerType = VL_TRIGGER_GPI;
val.xfer_trigger.value.instance = <which GPI input line>
vlSetControl(svr,path,VL_TRANSFER_TRIGGER,&val);

The DMediaInfo structure has been enhanced to report the Unadjusted System Time (UST) and VITC information.

DIVO makes use of the error events noted in Chapter 4 of the DMPG, plus VLTransferErrorEvent, which reports nonfatal video transfer errors, including EDH errors. The VLTransferComplete and VLSequenceLost events also report the Media Stream Count (MSC) of the field transferred or failed.

The DIVO board supports 16 channels of audio and is compliant with the SMPTE 272M standard. Access to the audio is through the Audio Library (AL) interfaces specified in the DMPG.