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 buffering APIs below.
AL: The Audio Library (alintro(3dm)).
GL: Either OpenGL (glIntro(3G)) or the obsolete IRIS GL.
CL: The Compression Library (clintro(3dm)). Obsoleted by dmIC.
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 hardware and software image compression/decompression.
dmBuffer: Buffering mechanism shared by the VL 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 3 VL Buffering APIs

Since the VL was born, all VL devices have supported a common set of VL function calls, including a set of VLBuffer calls which you can use to read incoming pixels or write outgoing pixels. The VLBuffer calls:

    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)

are collectively known as the "classic buffering API." Even the latest batch of VL devices support this API.

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 most recent VL devices also support DMbuffer-based buffering APIs, which solve all of the shortcomings above. An application creates a DMbufferpool instead of a VLBuffer. The DMbufferpool 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 VL and dmIC. No mapping (vlGetActiveRegion) or copy operation is required.

A video input application using DMbuffers tells the VL to allocate DMbuffers for input data from a supplied DMbufferpool. The application then uses VL calls to wait for and dequeue filled-in DMbuffers. The application can then pass each DMbuffer directly to another library (such as dmIC), or map and manipulate each buffer if it wishes. The application can free received DMbuffers in any order, and their memory will immediately be returned to the DMbufferpool.

A video output application using DMbuffers allocates its own DMbuffers from the DMbufferpool it has created, or uses DMbuffers received from another library (such as dmIC). The application uses VL calls to enqueue DMbuffers for output. The application can send its DMbuffers to the VL as many times and in whatever order it wants.

And now, the catch. Due to icky historical reasons, the DMbuffer API originally released for O2 (mvp) on IRIX 6.3 consists of a different set of calls from that released for ev3, cosmo2, and divo on IRIX 6.4. These two DMbuffer APIs are called the O2 buffering API and the cross-platform buffering API, respectively. As its name suggests, the cross-platform buffering API is the one which will be available on all modern platforms (mvp, ev3, cosmo2, and divo) under IRIX 6.5. This table summarizes the combinations:

buffering API	buffering mechanism	VL platforms	OS releases
classic	VLInfoPtrs and VLBuffers	all	all
O2	DMbuffers and DMbufferpools	O2 (mvp)	IRIX 6.3 and later
cross-platform	DMbuffers and DMbufferpools	ev3, cosmo2, divo	IRIX 6.4 and later
cross-platform	DMbuffers and DMbufferpools	all	IRIX 6.5 and later

Micheal Minakami has written a most excellent document detailing the exact differences between the DMbuffer APIs and providing sample code to ease your transition to the cross-platform DMbuffer API. This document is in the Developer's Toolbox at https://toolbox.sgi.com under src/exampleCode/video/VLdmbuffer/video_library_buffering.html. As of 12/16/97, it is not available in the free "Taste of the Toolbox": you need to be registered as described at http://www.sgi.com/Technology/toolbox.html.

Check out Multi-Threaded Apps and the VL to see how the three buffering APIs can and cannot coexist in the same program.

The O2 buffering API consists of these calls:

    vlDMPoolRegister(VLServer, VLPath, VLNode, DMbufferpool)
    vlDMPoolDeregister(VLServer, VLPath, VLNode, DMbufferpool)
    vlDMPoolGetParams(VLServer, VLPath, VLNode, DMparams *)
    vlDMBufferSend(VLServer, VLPath, DMbuffer)
    vlPathGetFD(VLServer, VLPath, int *ret_fd)
    vlEventRecv(VLServer, VLPath, VLEvent *)
    vlEventToDMBuffer(VLEvent *, DMbuffer *)
    vlGetFilledByNode(VLServer server, VLPath path, VLNode node)

The cross-platform buffering API consists of these calls:

    vlDMPoolRegister(VLServer, VLPath, VLNode, DMbufferpool)
    vlDMPoolDeregister(VLServer, VLPath, VLNode, DMbufferpool)
    vlDMGetParams(VLServer, VLPath, VLNode, DMparams*)
    vlDMBufferPutValid(VLServer, VLPath, VLNode, DMbuffer)
    vlDMBufferGetValid(VLServer, VLPath, VLNode, DMbuffer*)
    vlNodeGetFd(VLServer, VLPath, VLNode)
    vlDMBufferGetFilledByNode(VLServer, VLPath, VLNode)
    vlDMBufferResetNode(VLServer, VLPath, VLNode)
    vlDMBufferGetVideoInfo(DMbuffer, DMBufferVideoInfo* )
    vlDMBufferSetVideoInfo(DMbuffer, DMBufferVideoInfo* )
    vlNextEvent (VLServer, VLEvent *)
    vlCheckEvent(VLServer, VLEventMask, VLEvent *)