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/tools (such as capture/avcapture, capture/avplayback, and vlan/vlan).

---

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 

DIVO/DIVO-DVC nodes are further discussed in “VL Nodes for DIVO and DIVO-DVC ”.

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

VLServer svr;
VLPath path;
VLNode src;
VLNode drn;
                     /*Set up video source node */
VLControlValue timing,format, val; 
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);

To determine the available devices (that is, video options in the workstation, such as the DIVO or DIVO-DVC option 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, it is not guaranteed that they execute at a specific time. For better precision on the execution of these controls, see “Setting Inline Controls ”.

---

To set controls for DIVO/DIVO-DVC 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

Table 2-1 summarizes supported node controls for the DIVO/DIVO-DVC option.

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

Compression is handled via enhancements to the VL API; the DIVO and DIVO-DVC boards do not support the Compression Library API.

For DIVO and DIVO-DVC, 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—Rice, DV (DIVO-DVC only), DVCPRO (DIVO-DVC only), DVCam (DIVO-DVC only), or none—additional controls specify compression-related parameters. Table 2-2 earlier in this chapter summarizes these controls.

---

Note: Compression for the DIVO-DVC option is different from compression for DIVO; see “DV and DVCPRO Compression for DIVO-DVC ”.

---

{
   int GvlPacking;
   VLControlValue val;
   int GvlCspace;
   int GvlCapType;

VL_PACKING_242_8
VL_COLORSPACE_CCIR(0)

GvlCapType = VL_CAPTURE_INTERLEAVED;

   val.intVal = GvlPacking;
   if (vlSetControl(GvlSvr, GvlPath, GvlMemNode, VL_PACKING, &val) < 0)
   vl_error(“vlSetControl(VL_PACKING) on memory node”);
   if (vlGetControl(GvlSvr, GvlPath, GvlMemNode, VL_PACKING, &val) < 0)
   vl_error(“vlGetControl(VL_PACKING) on memory node”);
   if (val.intVal != GvlPacking)
   other_error(“can't set VL_PACKING on memory node”);

   val.intVal = GvlCspace;
   if (vlSetControl(GvlSvr, GvlPath, GvlMemNode, VL_COLORSPACE, &val) < 0)
   vl_error(“vlSetControl(VL_COLORSPACE) on memory node”);
   if (vlGetControl(GvlSvr, GvlPath, GvlMemNode, VL_COLORSPACE, &val) < 0)
   vl_error(“vlGetControl(VL_COLORSPACE) on memory node”);
   if (val.intVal != GvlCspace)
   other_error(“can't set VL_COLORSPACE on memory node”);

   val.intVal = GvlCapType;
   if (vlSetControl(GvlSvr, GvlPath, GvlMemNode, VL_CAP_TYPE, &val) < 0)
   vl_error(“vlSetControl(VL_CAP_TYPE) on memory node”);
   if (vlGetControl(GvlSvr, GvlPath, GvlMemNode, VL_CAP_TYPE, &val) < 0)
   vl_error(“vlGetControl(VL_CAP_TYPE) on memory node”);
   if (val.intVal != GvlCapType)
   other_error(“can't set VL_CAP_TYPE on memory node”);

}

/* display only field # 2 */
 field_display = VL_DIVO_FIELD_DISPLAY_F2F2;
 val.intVal = field_display;
 if (vlSetControl(GvlSvr, GvlPath, GvlVidNode, VL_DIVO_FIELD_DISPLAY, &val) <0)
     vl_error(“vlSetControl(VL_DIVO_FIELD_DISPLAY) on video node”);
 if (vlGetControl(GvlSvr, GvlPath, GvlVidNode, VL_DIVO_FIELD_DISPLAY, &val) <0)
     vl_error(“vlGetControl(VL_DIVO_FIELD_DISPLAY) on video node”);
 if (val.intVal != field_display)
     other_error(“can't set VL_DIVO_FIELD_DISPLAY on video node”);

For the DIVO and DIVO-DVC options, SDTI with embedded DV is handled by means of features in the VL API and hardware support in the input and output pipes. The API includes the following SDTI features:

This section consists of the following:

                /*  SDTI Header  */
typedef struct {
  u_char did;            /* data id identifier */
  u_char sdid;           /* sec. data id identifier */
  u_char dc;             /* data word count */
  u_char lnum[2];        /* linenumber0 and linenumber1 */
  u_char lnumcrc[2];     /* linenumber0 and linenumber1 crc */
  u_char aai_code;       /* appl identifier and code */
  u_char dst_addr[16];   /* destination address */
  u_char src_addr[16];   /* source address */
  u_char btype;          /* block type */
  u_char crcflag;        /* payload crc flag */
  u_char dextflag;       /* data extension flag */
  u_char reserved[4];    /* reserved words */
} 


void init_sdti_header_dv( sdti_hdr_t *  sdti_hdr, VLControlValue *val)
{
  int i;

  sdti_hdr->did           = 0x40; /* see smpte 305M spec */
  sdti_hdr->sdid          = 0x01;
  sdti_hdr->dc            = 0x2E;
  sdti_hdr->lnum[0]       = 0x00;
  sdti_hdr->lnum[1]       = 0x00;
  sdti_hdr->lnumcrc[0]    = 0x00;
  sdti_hdr->lnumcrc[1]    = 0x00;
  sdti_hdr->aai_code      = 0x01;

  for(i=0;i<16;i++) sdti_hdr->dst_addr[i] = 0; /* dst_addr[0] is msb */
  for(i=0;i<16;i++) sdti_hdr->src_addr[i] = 0; /* src_addr[0] is msb */

  sdti_hdr->btype         = DIVO_SDTI_BLOCK_TYPE_FIXED; /* fixed block, no ecc
*/
  sdti_hdr->crcflag       = 0x01;  /* insert CRC */
  sdti_hdr->dextflag      = 0x00;  /* no data extension packets */
  for(i=0;i<4;i++) sdti_hdr->reserved[i] = 0; /* set to zero */

  /* copy sdti header into control string variable */
  bcopy(sdti_hdr,val->stringVal,sizeof(sdti_hdr_t));

}

    /* Set the SDTI Header */
    if (vlSetControl(GvlSvr, GvlPath, GvlMemNode, VL_SDTI_HEADER, &val) < 0)
      vl_error(“vlSetControl(VL_SDTI_HEADER) on memory node”); 

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 F1) or on the intervening field boundary (Field 2, or F2).

Whether a field is Field 1 or Field 2 is determined by the setting of bit 9, the F bit, in the XYZ word of the EAV and SAV sequences. The setting means the following:

Figure 2-2 shows fields and frames as defined for digital 525-line and 625-line formats for the DIVO/DIVO-DVC option.^[1] 

Figure 2-2. DIVO/DIVO-DVC 525-Line and 625-Line Frames and Fields

Editing is usually on Field 1 boundaries, where Field 1 is defined as the first field in the video standard's two-field output sequence. 525-line 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-line standards send the first (half) raster line out to begin the first field, and the second (whole) raster line to begin the second field.

However, 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.

If you use component 525-line format, you might need to vary the field dominance choice, depending on the origin of the input material they are to edit.

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.
 */

int is_525, F1_is_first;
VLControlValue drn timing, dominance;
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;
    } 

The DIVO and DIVO-DVC option boards have two GPI connectors, each associated with one of the serial digital video ports. Each port has two transmit and two receive channels, lines 0 and 1 in and out.

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

Using VL_GPI_OUT_MODE

Use VL_GPI_OUT_MODE to program the gpi_out line. Two conditions are supported for asserting the GPI line: transfer_start and transfer_stop. You can have multiple trigger conditions outstanding.

Figure 2-3 diagrams the effect of VL_GPI_OUT_MODE values.

Figure 2-3. Output GPI (OFF Assumed to Be Low)

---

Note: In this section, OFF is assumed to be low. VL_CLEAR_GPI changes the state of the GPI signal to low.

---

The following pseudocode segment illustrates a setup for gpi_out line 1 to toggle at the beginning and end of transfer:

VLControlValue val; /* make sure the GPI line is high */ val.gpi_state.gpi = VL_GPI_OUT; val.gpi_state.instance = <which GPI line>; /* integer */ 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);

To clear all outstanding trigger controls on a particular line, use the gpi_state control with the clear flag.

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);

Using VL_TRANSFER_TRIGGER

The VL_TRANSFER_TRIGGER control specifies the conditions under which transfers begin on a path based on external GPI triggers. This control is valid only on video nodes.

The following code illustrates an input GPI-based trigger transfer setup:

VLTransferDescriptor desc; int num_images = 30; /* 1 second of video */ int trigger = TRUE; /* enable trigger transfers */ if (trigger) { val.xfer_trigger.triggerType = VL_TRIGGER_GPI; val.xfer_trigger.value.instance = 1; /* GPI line 1 */ desc.trigger = VLDeviceEvent; } else { /* reset for subsequent transfers */ val.xfer_trigger.triggerType = VL_TRIGGER_NONE; desc.trigger = VLTriggerImmediate; } vlSetControl(svr, path, src, VL_TRANSFER_TRIGGER, &val); desc.mode = VL_TRANSFER_MODE_DISCRETE; desc.count = num_images; desc.delay = 0; vlBeginTransfer(svr, path, 1, &desc);

---

Note: The trigger type is a persistent device control setting and remains valid until reset. Thus the VL_TRANSFER_TRIGGER control must be set to VL_TRIGGER_NONE if subsequent transfers are of a nontrigger type.

---

Over-the-wire electrical time-code signals are used as clocks by which one master device can drive the input or output of data by other slave devices. Each tick of the clock consists of a unique signal that represents a time code.

VITC time code is a standardized part of a 525- or 625-line video signal. The code itself occupies lines in the vertical blanking interval of each field of the video signal. Each VITC code word contains a time code, 32 user bits, an F1/F2 field indicator, and other useful information. People use the user bits to store information such as reel and shot number for indexing footage. Under certain circumstances, the original VITC recorded with footage can go along with that footage as it is edited, so that you can produce an edit list or track assets for a final prototype edit.

The DIVO and DIVO-DVC options always extract VITC information from the fields as they are captured and pass this information to the application as buffer information associated with the dmBuffer. To extract this information, call vlDMBufferGetVideoInfo(). In the structure returned, a valid bit (validinfo) indicates if the VITC is valid. Refer to the programming example divo_vitc.c in the directory /usr/share/src/dmedia/video/DIVO.

To insert VITC, fill the DMBufferVideoInfo* structure and call the function vlDMBufferSetVideoInfo().

To parse a VITC image out of a pixel buffer, you can use a VITC parser included in libdmedia (see dmVITC(3dm)); see /usr/share/src/dmedia/video/vitc.c for sample code.

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/DIVO-DVC. For these options, this table supersedes the table of events in Chapter 14, “VL Event Handling,” in the DMPG; DIVO and DIVO-DVC support only the events listed in Table 2-3.

Because of the asynchronous nature of the implementation, controls executed with vlSetControl() have no guarantees as to when they are executed once transfers are in progress. 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.

Inline controls specify control changes to happen between buffers. For example, if you want to play out two video clips that have different packing formats in memory, the application would set up the path, queue the buffers from the first clip, set up inline controls to match the next clip, and queue the buffers from the second clip. The syntax for usage is

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

In this syntax, refnode is the reference node, identifying a unique connection in a path with more than two nodes.

Inline controls are generally applied on a memory node being used as the source node. Control changes are queued to the hardware along with the buffers and are executed in order. To change packing control inline, for example, use

VLNode mem;

mem = vlGetNode(svr, VL_SRC, VL_MEM, VL_ANY);
val.intval = VL_PACKING_444_12;
vlSetControlInLine(svr, path, mem, mem, VL_PACKING, &val);

To capture graphics to video, you can use OpenGL to read pixels into memory. However, the coordinate system differs between video and Open GL; under OpenGL, the origin is at the lower left corner and in video, origin is in the upper left corner. To adjust for this difference, the image must be inverted in memory before it is sent to the DIVO board for output.

Besides sending an image out to the DIVO board, you can use the GVO graphics option to get zero-latency transcoding to CCIR 601-2 digital video.

The DMediaInfo structure reports the Unadjusted System Time (UST) and VITC information.

The DIVO and DIVO-DVC options make use of the error events noted in Chapter 4 of the DMPG, as well as VLTransferErrorEvent, which reports nonfatal video transfer errors, including error detection and handling (EDH) errors. The VLTransferComplete and VLSequenceLost events also report the Media Stream Count ( MSC) of the field or frame transferred or failed.