The first thing a VL application must do is open the device with vlOpenVideo(). Its function prototype is:

VLServer vlOpenVideo(const char *sName) 

where sName is the name of the server to which to connect; set it to a NULL string for the local server. For example:

vlSvr = vlOpenVideo("")

Use vlGetNode() to specify nodes; this call returns the node's handle. Its function prototype is:

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

where:

To use the default node kind, use VL_ANY.

nodehandle = vlGetNode(vlSvr, VL_SRC, VL_VIDEO, VL_ANY);

To discover which node the default is, use the control VL_DEFAULT_SOURCE after getting the node handle the normal way. The default video source is maintained by the VL. For example:

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

In the second line above, the last argument is a struct that gets the value.

Once nodes are specified, use VL calls to:

Creating the Path

Use vlCreatePath() to create the data path. Its function prototype is:

VLPath vlCreatePath(VLServer vlSvr, VLDev vlDev VLNode src, VLNode drn)

This code fragment creates a path if the device is unknown:

if ((path = vlCreatePath(vlSvr, VL_ANY, src, drn)) < 0) { vlPerror(_progName); exit(1); }

This code fragment creates a path that uses a device specified by parsing a devlist:

if ((path = vlCreatePath(vlSvr, devlist[devicenum].dev, src, drn)) < 0) { vlPerror(_progName); exit(1); }

---

Note: If the path contains one or more invalid nodes, vlCreatePath() returns VLBadNode.

---

VLDev vlGetDevice(VLServer vlSvr, VLPath path)

devicenum = vlGetDevice(vlSvr, path);
deviceName = devlist.devices[devicenum].name;
printf("Device is: %s/n", deviceName);

int vlAddNode(VLServer vlSvr, VLPath vlPath, VLNodeId node)

vlAddNode(vlSvr, vlPath, src_vid);
vlAddNode(vlSvr, vlPath, blend_node);

int vlSetupPaths(VLServer vlSvr, VLPathList paths,
      u_int count, VLUsageType ctrlusage,
      VLUsageType streamusage) 

if (vlSetupPaths(vlSvr, (VLPathList)&path, 1, VL_SHARE,
    VL_LOCK) < 0)
{
    vlPerror(_progName);
    exit(1);
}

int vlSelectEvents(VLServer vlSvr, VLPath path, VLEventMask eventmask)

vlSelectEvents(vlSvr, path, VLTransferCompleteMask); 

vlSelectEvents(vlSvr, path, VLTransferCompleteMask |
      VLTransferFailedMask);

Important data transfer controls for source nodes are summarized in
Table 2-2. They should be set in the order in which they appear in the table.

The use of VL_MUXSWITCH and VL_TIMING is explained in further detail in the following sections.

Important data transfer controls for drain nodes are summarized in
Table 2-5. They should be set in the order in which they appear in the table.

These controls are highly interdependent, so the order in which they are set is important. In most cases, the value being set takes precedence over other values that were previously set.

---

Note: VL_PACKING must be set first. 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.

---

To determine default values, use vlGetControl() to query the values on the video source or drain node before setting controls. The initial offset of the video node is the first active line of video.

Similarly, the initial size value on the video source or drain node is the full size of active video being captured by the hardware, beginning at the default offset. Because some hardware can capture more than the size given by the video node, this value should be treated as a default size.

For all these controls, it pays to track return codes. If the value returned is VLValueOutOfRange, the value set is not what you requested.

To specify the controls, use vlSetControl(), for which the function prototype is:

int vlSetControl(VLServer vlSvr, VLPath vlPath, VLNode node, 
      VLControlType type, VLControlValue * value) 

The use of VL_FORMAT, VL_PACKING, VL_ZOOM, VL_SIZE, VL_OFFSET, VL_RATE, and VL_CAP_TYPE is explained in more detail in the following sections.

Using VL_FORMAT

To specify video input and output formats of the video signal on the physical connector, use VL_FORMAT. For Indigo² Video for Indigo² IMPACT, the native format is YUV 4:2:2; this format is always fastest. The Indigo² Video option also supports 32-bit RGB.

---

Note: To convert formats, use VL_PACKING, which is explained in the next section.

---

Using VL_PACKING

To convert a video output format to another in memory, use the control VL_PACKING. Packing type expresses the packing in memory of the video data at the source or drain.

Packing types are summarized in Table 2-6, which shows the most significant byte (MSB) on the left. An X means don't care; this bit is not used.

Table 2-6. Packing Types and Their Sizes and Formats

Type	Size	Format MSB ------------------------------------------------------------------LSB
VL_PACKING_RGB_332_P	8-bit word	BBGGGRRR (four pixels packed into a 32-bit word)
VL_PACKING_RGBA_8	32-bit word	AAAAAAAA BBBBBBBB GGGGGGGG RRRRRRRR
VL_PACKING_RGB_8	24-bit word	XXXXXXXX BBBBBBBB GGGGGGGG RRRRRRRR
VL_PACKING_Y_8_P	8-bit word	YYYYYYYY (four pixels packed into a 32-bit word)
VL_PACKING_YVYU_422_8 (native format)	32-bit word	UUUUUUUU YYYYYYYY VVVVVVVV YYYYYYYY

---

Note: The packing names follow the naming conventions used by the IRIS Graphics Library; other libraries such as the OpenGL may use different names.

---

For example:

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

Using VL_ZOOM

VL_ZOOM controls the expansion or decimation of the video image. Values greater than one expand the video; values less than one perform decimation. Figure 2-1 illustrates zooming and decimation.

Figure 2-1. Zoom and Decimation

VL_ZOOM takes a nonzero fraction as its argument; do not use negative values. For example, this fragment captures half-size decimation video to memory:

val.fractVal.numerator = 1; val.fractVal.denominator = 2; if (vlSetControl(server, memory_path, memory_drain_node, VL_ZOOM, &val)){ vlPerror("Unable to set zoom"); exit(1); }

---

Note: For a source, zooming takes place before blending; for a drain, blending takes place before zooming.

---

This fragment captures half-size decimation video to memory, with clipping to 320 × 243 (NTSC size minus overscan).

val.fractVal.numerator = 1; val.fractVal.denominator = 2; if (vlSetControl(server, memory_path, memory_drain_node, VL_ZOOM, &val)) { vlPerror("Unable to set zoom"); exit(1); } val.xyVal.x = 320; val.xyVal.y = 243; if (vlSetControl(server, memory_path, memory_drain_node, VL_SIZE, &val)) { vlPerror("Unable to set size"); exit(1); }

This fragment captures xsize×ysize video with as much decimation as possible, assuming the size is smaller than the video stream.

if (vlGetControl(server, memory_path, video_source, VL_SIZE, &val)) { vlPerror("Unable to get size"); exit(1); } if (val.xyVal.x/xsize < val.xyVal.y/ysize) zoom_denom = (val.xyVal.x + xsize - 1)/xsize; else zoom_denom = (val.xyVal.y + ysize - 1)/ysize; val.fractVal.numerator = 1; val.fractVal.denominator = zoom_denom; if (vlSetControl(server, memory_path, memory_drain_node, VL_ZOOM, &val)) { /* allow this error to fall through */ vlPerror("Unable to set zoom"); } val.xyVal.x = xsize; val.xyVal.y = ysize; if (vlSetControl(server, memory_path, memory_drain_node, VL_SIZE, &val)) { vlPerror("Unable to set size"); exit(1); }

Using VL_SIZE

VL_SIZE controls how much of the image sent to the drain is used, that is, how much clipping takes place. This control operates on the zoomed image; for example, when the image is zoomed to half size, the limits on the size control change by a factor of 2. Figure 2-2 illustrates clipping.

Figure 2-2. Clipping an Image

For example, to display PAL video in a 320 × 243 space, clip the image to that size, as shown in the following fragment:

VLControlValue value;

value.xyval.x=320; value.xyval.y=243; vlSetControl(vlSvr, path, drn, VL_SIZE, &value);

---

Note: Because this control is device-dependent and interacts with other controls, always check the error returns. For example, if offset is set before size and an error is returned, set size before offset.

---

VLControlValue value;

value.xyval.x=10; 
value.xyval.y=10; 
vlSetControl(vlSvr, path, drn, VL_OFFSET, &value); 

Once you have specified frame parameters in a transfer involving memory (or have determined to use the defaults), create a buffer for the frames.

Like other libraries in the IRIX digital media development environment, the VL uses ring buffers. Ring buffers provide a way to read and write varying sizes of frames of data. A frame of data consists of the actual frame data and an information structure describing the underlying data, including device-specific information.

When a ring buffer is created, constraints are specified that control the total size of the data segment and the number of information buffers to allocate.

A head and a tail flag are automatically set in a ring buffer so that the latest frame can be accessed. A sector is locked down if it is not called; that is, it remains locked until it is read. When the ring buffer is written to and all sectors are occupied, data transfer stops. The sector last written to remains locked down until it is released.

The ring buffer can accommodate data of varying sizes. You can specify a ring buffer at a fixed size, or you can determine the size of the data in the buffer. To determine frame data size, use vlGetTransferSize(). Its function prototype is:

long vlGetTransferSize(VLServer vlSvr, VLPath path)

For example:

transfersize = vlGetTransferSize(vlSvr, path); 

where transfersize is the size of the data in bytes.

To create a ring buffer for the frame data, use vlCreateBuffer(). Its function prototype is:

VLBuffer vlCreateBuffer(VLServer vlSvr, VLPath path,
      VLNode node, int numFrames)

where:

For example:

buf = vlCreateBuffer(vlSvr, path, src, 1); 

Use vlRegisterBuffer() to register the ring buffer with the data path. Its function prototype is:

int vlRegisterBuffer(VLServer vlSvr, VLPath path,
     VLNode memnodeid, VLBuffer buffer)

where:

For example:

vlRegisterBuffer(vlSvr, path, drn, Buffer);

To begin data transfer, use vlBeginTransfer(). Its function prototype is:

int vlBeginTransfer(VLServer vlSvr, VLPath path, int count,
      VLTransferDescriptor* xferDesc) 

where:

Tailor the data transfer by means of transfer descriptors. The transfer descriptors are:

This example fragment transfers the entire contents of the buffer immediately.

xferDesc.mode = VL_TRANSFER_MODE_DISCRETE;

xferDesc.count = imageCount;
xferDesc.delay = 0;
xferDesc.trigger = VLTriggerImmediate;

This fragment shows the default descriptor, which is the same as passing in a null for the descriptor pointer. Transfer begins immediately; count is ignored.

xferDesc.mode = VL_TRANSFER_MODE_CONTINUOUS;

xferDesc.count = 0;
xferDesc.delay = 0;
xferDesc.trigger = VLTriggerImmediate;

If your application uses a buffer, use various VL calls for reading frames, getting pointers to active buffers, freeing buffers, and other operations. Table 2-8 lists the buffer-related calls.

Figure 2-4 illustrates the difference between vlGetNextValid() and vlGetLatestValid(), and their interaction with vlPutFree().

Table 2-9 lists the calls that extract information from a buffer.

---

Caution: None of these calls has count or block arguments; appropriate calls in the application must deal with a NULL return in cases of no data being returned.

---

In summary, for video-to-memory transfer use:

buffer = vlCreateBuffer(vlSvr, path, memnode1);
vlRegisterBuffer(vlSvr, path, memnode1, buffer); 
vlBeginTransfer(vlSvr, path, 0, NULL); 
info = vlGetNextValid(vlSvr, buffer);
/* OR vlGetLatestValid(vlSvr, buffer); */
dataptr = vlGetActiveRegion(vlSvr, buffer, info); 

/* use data for application */
…
vlPutFree(vlSvr, buffer); 

For memory-to-video transfer, use:

buffer = vlCreateBuffer(vlSvr, path, memnode1);
vlRegisterBuffer(vlSvr, path, memnode1, buffer); 
vlBeginTransfer(vlSvr, path, 0, NULL); 
buffer = vlGetNextFree(vlSvr, buffer, bufsize); 
/* fill buffer with data */
…
vlPutValid(vlSvr, buffer); 

These calls are explained in separate sections.

VLInfoPtr vlGetNextValid(VLServer vlSvr, VLBuffer vlBuffer)

VLInfoPtr vlGetLatestValid(VLServer vlSvr, VLBuffer vlBuffer) 

int vlPutFree(VLServer vlSvr, VLBuffer vlBuffer)

Sending Frames From Memory to Video

Use vlGetNextFree() to get a free buffer to which to write data. Its function prototype is:

VLInfoPtr vlGetNextFree(VLServer vlSvr, VLBuffer vlBuffer, int size)

After filling the buffer with the data you want to send to video output, use vlPutValid() to put a frame into the valid list for output to video (memory to video). Its function prototype is:

int vlPutValid(VLServer vlSvr, VLBuffer vlBuffer)

---

Caution: These calls do not have count or block arguments; appropriate calls in the application must deal with a NULL return in cases of no data being returned.

---

void * vlGetActiveRegion(VLServer vlSvr, VLBuffer vlBuffer,
     VLInfoPtr ptr)

DMediaInfo * vlGetDMediaInfo(VLServer vlSvr,
   VLBuffer vlBuffer, VLInfoPtr ptr)

DMImageInfo * vlGetImageInfo(VLServer vlSvr,
   VLBuffer vlBuffer, VLInfoPtr ptr)