videolibrary(3dm)
VLintro, libvl, vl - IRIS Video Library for SGI workstations
As shipped in IRIX 6.5.5. Unchanged since IRIX 6.5.
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 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 */ 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); 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 VL_EXT_EVENT_RECV(3dm). The following routines cannot be used with DMbuffers: Buffer Oriented: vlCreateBuffer vlRegisterBuffer vlDeregisterBuffer vlBufferAdvise vlBufferGetFd vlBufferDone vlBufferReset vlDestroyBuffer vlGetNextFree vlPutFree 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); 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)