What Are the SGI Video-Related Libraries
By Chris Pirazzi.
The libraries we may mention in the Lurker's Guide are:
- VL: The Video Library (vlintro(3dm)). See note about O2 below.
- AL: The Audio Library (alintro(3dm)).
- GL: Either OpenGL (glIntro(3G)) or the obsolete IRIS GL.
- CL: The Compression Library (clintro(3dm)).
- MV: The Movie Library (man mvIntro(3dm)). Actually two libraries, libmoviefile and libmovieplay.
- DM: One or more of the digital media facilities in libdmedia, such as dmParams, dmIC, dmBuffer, dmTC, dmLTC, dmVITC, or dmColor.
- dmIC: The Image Conversion library, part of libdmedia (dmic(4)). dmIC is used for image compression/decompression on O2.
- dmBuffer: Buffering mechanism shared by the O2 VL API and dmIC (dmbuffer(4)).
- dmTC: timecode math routines in libdmedia (man -k dmTC)
- dmLTC: linear timecode parsing routines in libdmedia (dmLTC(3dm))
- dmVITC: vertical interval timecode parsing routines in libdmedia (dmVITC(3dm))
- dmColor: color conversion library in libdmedia (dmColor(3dm))
- MD: MIDI library (man mdIntro(3dm))
- tserialio: timestamped serial I/O library (IRIX 6.3, man tserialio(3))
The O2 and the VL
The O2 workstation implements all of the same VL calls as all of the other VL devices. Call the set of VL calls present in IRIX 6.2 the classic VL API. In addition, the O2 VL offers an optional, improved buffering API which we'll call the O2
buffering API or just the O2 API.
A video application may use either the buffering routines from the classic VL API, which are:
vlGetTransferSize(VLServer, VLPath) vlCreateBuffer(VLServer, VLPath, VLNode, numFrames) vlDestroyBuffer(VLServer, VLBuffer) vlRegisterBuffer(VLServer, VLPath, VLNode, VLBuffer) vlDeregisterBuffer(VLServer, VLPath, VLNode, VLBuffer) vlBufferAdvise(VLBuffer, usageInfo) vlBufferGetFd(VLBuffer) vlBufferDone(VLBuffer) vlBufferReset(VLServer, VLBuffer) vlGetNextFree(VLServer, VLBuffer, size) vlPutValid(VLServer svr, VLBuffer buffer) vlGetNextValid(VLServer, VLBuffer) vlGetLatestValid(VLServer, VLBuffer) vlPutFree(VLServer, VLBuffer) vlGetActiveRegion(VLServer, VLBuffer, VLInfoPtr) vlGetDMediaInfo(VLServer svr, VLBuffer buffer, VLInfoPtr info) vlGetImageInfo(VLServer svr, VLBuffer buffer, VLInfoPtr info) vlGetFilled(VLServer server, VLPath path, VLBuffer buffer)
or an application may use the buffering routines from the O2 buffering API, which are:
vlDMPoolGetParams(VLServer, VLPath, VLNode, DMparams *) vlDMPoolRegister(VLServer, VLPath, VLNode, DMbufferpool) vlDMPoolDeregister(VLServer, VLPath, VLNode, DMbufferpool) vlDMBufferSend(VLServer, VLPath, DMbuffer) vlPathGetFD(VLServer, VLPath, int *ret_fd) vlEventRecv(VLServer, VLPath, VLEvent *) vlEventToDMBuffer(VLEvent *, DMbuffer *) vlGetFilledByNode(VLServer server, VLPath path, VLNode node)
In the classic buffering API, video data is transferred between the device and the application using a VLBuffer data structure, which is essentially a ringbuffer. An application can pull items arriving from video input off of an input ringbuffer by calling vlGetNextValid(3dm). The application can get a pointer to the memory corresponding to that item. The application can only free items in the order in which it received the items. Video output works similarly---the application allocates one item in the output ringbuffer per field or frame, gets a pointer to the space, fills the data in, and sends the item on with vlPutValid(3dm). The application cannot send the same video data multiple times without imposing additional copies. The VLbuffer items are allocated by the VL and cannot be passed to any other image
processing libraries without copying all of the image data.
The O2 buffering API solves all of the shortcomings above. An application creates a DMpool instead of a VLBuffer. The DMpool is a collection of DMbuffers (in the DM terminology, each field or frame is containined in a DMbuffer). DMbuffers are understood by more than just the VL. For example, when doing JPEG compression and decompression, you pass DMbuffers directly between the O2 VL and dmIC. No mapping (vlGetActiveRegion) or copy operation is required.
A video input application using the O2 buffering API tells the VL to pull DMbuffers from a supplied DMpool. The application then waits for DMbuffers to arrive from the VL via the VL event mechanism. It can then pass each DMbuffer directly to dmIC, or map and manipulate each buffer if it wishes.
A video output application using the O2 buffering API allocates its own DMbuffers from the DMpool it has created, or uses DMbuffers received from dmIC. The application passes DMbuffers to the VL using vlDMBufferSend(3dm). The application can send DMbuffers from a given DMpool as many times and in whatever order it wants.
Check out Multi-Threaded Apps and the VL to see how the two buffering APIs can and cannot coexist.