VLINTRO(3dm) VLINTRO(3dm)
NAME
VLintro, libvl, vl - IRIS Video Library for SGI workstations
SYNOPSIS
#include <dmedia/vl.h>
-lvl
DESCRIPTION
The IRIS Video Library (VL) provides a software interface for working
with video devices and image data. It provides a programming interface to
the various SGI video products.
PROGRAMMING MODEL
The VL model is based on data paths. These paths represent ways in which
video data can be moved through the system. Paths consist of nodes,
buffers and controls. A node is a building block of a path. The source
and drain of a video stream, as well as any filters which affect data
flowing between the source and drain are all types of nodes.
Nodes have controls associated with them. Controls dictate the behavior
of the node, and of any path containing that node.
Once a path is setup, transfers can be initiated which cause data to flow
from source to drain. Transfers involving host memory, or memory nodes,
require the use of a ring buffer. Events are delivered to paths to report
changes in the system which affect it.
PROGRAMMING INTERFACE
vlAddNode(3dm), vlRemoveNode(3dm) - Add or remove nodes in a path
vlCreateBuffer(3dm), vlDestroyBuffer(3dm) - Buffer creation routines for
transfers involving memory nodes
vlGetNextValid(3dm), vlPutFree(3dm), vlGetNextFree(3dm), vlPutValid(3dm),
vlGetFilled(3dm) - ring buffer management routines
vlDMBufferGetValid(3dm), vlDMBufferPutValid(3dm), vlNodeGetFd(3dm) -
dmbuffer handling routines. These are available cross-platform and should
be used in preference to the O2-specific functions vlEventRecv(3dm),
vlEventToDMBuffer(3dm), vlDMBufferSend(3dm).
vlPathGetFD(3dm), vlEventRecv(3dm), vlEventToDMBuffer(3dm),
vlDMBufferSend(3dm) - obsolete dmbuffer handling functions, only
supported on O2. vlDMBufferGetValid, etc., should be used instead.
vlDMPoolRegister(3dm), vlDMPoolDeregister(3dm) - DMbufferpool management
vlCreatePath(3dm), vlDestroyPath(3dm) - manage video paths
Page 1
VLINTRO(3dm) VLINTRO(3dm)
vlGetControlInfo(3dm) - Get information about a specified control
vlGetControlList(3dm) - Get list of valid video controls for a path
vlGetControl(3dm), vlSetControl(3dm) - Get or set control value
vlGetConnection (3dm), vlSetConnection(3dm) - Get or set path
connectivity
vlGetTransferSize(3dm) - Get video ring buffer frame size
vlNextEvent(3dm), vlCheckEvent(3dm), vlPeekEvent(3dm) - Get or peek at
next video event
vlOpenVideo(3dm), vlCloseVideo(3dm) - Open or close a connection to the
video server
vlPerror(3dm), vlStrError(3dm), vlErrno(3dm) - Video-library Specific
Error Routines
vlSelectEvents(3dm) - Select Video Events of Interest
vlSetErrorHandler(3dm), vlSetIOErrorHandler(3dm) - Set the VL non-fatal
or fatal error handler
vlSetupPaths(3dm) - Setup video paths
vlBeginTransfer(3dm), vlEndTransfer(3dm) - Initiate, End transfer on
video path
vlGetUSTMSCPair(3dm), vlGetFrontierMSC(3dm), vlGetUSTPerMSC(3dm),
vlGetPathDelay(3dm) - Video stream synchronization routines
vlGetString(3dm) - Get information about the VL extensions supported by
this version of the library
PATH CREATION
The following example demonstrates the creation of a path between a
memory source and a video drain.
VLServer svr;
VLPath path;
VLNode src, drn;
if (!(svr = vlOpenVideo(NULL)))
{
vlPerror(argv[0]);
exit(1);
}
/* Set up a source node in memory */
Page 2
VLINTRO(3dm) VLINTRO(3dm)
src = vlGetNode(svr, VL_SRC, VL_MEM, VL_ANY);
/* Set up a video drain node */
drn = vlGetNode(svr, VL_DRN, VL_VIDEO, VL_ANY);
/* Create a path on the first available device */
path = vlCreatePath(svr, VL_ANY, src, drn);
if (!path) {
vlPerror("vlCreatePath");
exit(1);
}
/* Set up the hardware for and define the usage of the path */
if (vlSetupPaths(svr, (VLPathList)&path, 1, VL_SHARE, VL_SHARE)<0)
{
vlPerror("vlSetupPaths");
exit(1);
}
BUFFER MANAGEMENT
The video library has two sets of buffer management calls, one providing
compatibility with older VL applications using VLBuffer-type buffers, and
a new set supporting Digital Media Buffers (i.e. dmBuffers). This
dmBuffer interface is outlined below.
The Video Library provides a set of buffer management calls that allow
the sending or receiving of frame data to or from host memory providing
ring buffer-type semantics using VLBuffer typed buffers.
A VLBuffer consists of a list of frame-sized regions of memory each with
an associated header block. Buffers are needed for transferring data to
or from memory nodes. To receive a frame, the reader calls one of
vlGetNextValid or vlGetLatestValid, and to free that frame calls
vlPutFree. To send a frame, the writer calls vlGetNextFree, copies the
data to be sent into the acquired buffer, and then vlPutValid to send
that frame.
Various controls affect buffer size. Setting controls which affect frame
size should be done prior to calling vlCreateBuffer.
The following example demonstrates the creation of a buffer and
registration of that buffer with a path and node.
VLBuffer buf;
/* Create a ring buffer for the data transfers */
buf = vlCreateBuffer(svr, path, src, 1);
/* Associate the ring buffer with the path */
vlRegisterBuffer(svr, path, src, buf);
Page 3
VLINTRO(3dm) VLINTRO(3dm)
DIGITAL MEDIA BUFFERS
The Video Library supports digital media buffers, dmbuffer(3dm) on some
platforms. DMbuffers replace the fixed ring buffer with a more flexible
mechanism based on a FIFO. DMbuffers provide the ability to hang onto
individual buffers without stopping video transfers. They can be used to
pass data efficiently between different video paths and between
libraries. (e.g., digital media Image Converter, dmIC(3dm).)
The new routines are incompatible with some existing vl interfaces,
particularly those dealing with VLBuffers (ring buffers). Using them in
combination will result in the error VLAPIConflict.
The following routines are specific to DMbuffers:
vlDMGetParams(3dm)
vlDMPoolRegister(3dm)
vlDMPoolDeregister(3dm)
vlDMBufferGetValid(3dm)
vlDMBufferPutValid(3dm)
vlDMBufferResetNode(3dm)
vlDMBufferGetFilledByNode(3dm)
vlDMBufferGetVideoInfo(3dm)
vlDMBufferSetVideoInfo(3dm)
vlNodeGetFd(3dm)
The DMbuffer handling routines from IRIX 6.3 have been replaced with the
ones listed above. The obsolete routines, now available only for
backwards compatability, are:
vlDMPoolGetParams(3dm)
vlDMBufferSend(3dm)
vlEventRecv(3dm)
vlEventToDMBuffer(3dm)
vlPathGetFD(3dm)
These obsolete routines are described in VLEXTEVENTRECV(3dm).
The following routines cannot be used with DMbuffers:
Buffer Oriented:
vlCreateBuffer
vlRegisterBuffer
vlDeregisterBuffer
vlBufferAdvise
vlBufferGetFd
vlBufferDone
vlBufferReset
vlDestroyBuffer
vlGetNextFree
vlPutFree
Page 4
VLINTRO(3dm) VLINTRO(3dm)
vlPutValid
vlGetNextValid
vlGetLatestValid
vlGetActiveRegion
vlGetDMediaInfo
vlGetImageInfo
In addition, the following routines cannot be used with DMbuffers on the
O2 platform, when using the obsolete functions (vlDMBufferSend, etc.):
Event Oriented:
vlPending
vlNextEvent
vlCheckEvent
vlPeekEvent
Callbacks and Handlers:
vlMainLoop
vlRegisterHandler
vlRemoveHandler
vlAddCallback
vlRemoveCallback
vlRemoveAllCallbacks
vlCallCallbacks
The following example demonstrates the creation of a DMbufferpool and its
registration for use with a VL path and node.
DMbufferpool pool;
DMParams plist;
int xfersize;
/* Create a parameter list */
dmParamsCreate(&plist);
xfersize = vlGetTransferSize(svr, path);
/* set our requirements for the pool */
dmBufferSetPoolDefaults(plist, num_frames, xfersize, DM_TRUE, DM_TRUE);
/* request the vl's requirements for the pool */
vlDMGetParams(svr, path, drn, plist);
/* create the pool */
dmBufferCreatePool(plist, &pool);
/* register it with the path and node */
vlDMPoolRegister(svr, path, drn, pool);
Page 5
VLINTRO(3dm) VLINTRO(3dm)
ERROR HANDLING
When errors occur, a global variable, vlErrno is set to reflect the
cause. The call vlGetErrno should be used to determine its value.
FILES
/usr/include/dmedia/vl.h C/C++ header file
/usr/share/src/dmedia/video Example programs
/usr/lib/libvl.so VL DSO
/usr/lib/dmedia/video/*.so VL device modules
SEE ALSO
vlOpenVideo(3dm), vlCreatePath(3dm), vlGetNode(3dm), vlSetupPaths(3dm),
vlSetControl(3dm), vlCreateBuffer(3dm), vlBeginTransfer(3dm),
vlGetNextValid(3dm), vlSetConnection(3dm), videosync(3dm), dmbuffer(3dm),
dmIC(3dm)
Page 6