What Are the SGI Video-Related Libraries? - Lurker's Guide - lurkertech.com
lurkertech.com Lurker's Guide What Are the SGI Video-Related Libraries?

Support This SiteI created this site and made it available free to all readers. If you have found it helpful or amusing, please support the effort, and future updates, in one of these ways:
donate now   Donate Now
Use your credit card or PayPal to donate in support of the site.
get anything from amazon.com
Use this link to Amazon—you pay the same, I get 4%.
get my thai dictionary app
Learn Thai with my Talking Thai-English-Thai Dictionary app: iOS, Android, Windows.
get my thai phrasebook app
Experience Thailand richly with my Talking Thai-English-Thai Phrasebook app.
get my chinese phrasebook app
Visit China easily with my Talking Chinese-English-Chinese Phrasebook app.
get thailand fever
I co-authored this bilingual cultural guide to Thai-Western romantic relationships.
Support This Site

I created this site and made it available free to all readers. If you have found it helpful or amusing, please support the effort, and future updates, in one of these ways:
donate now   Donate Now
Use your credit card or PayPal to donate in support of the site.
get anything from amazon.com
Use this link to Amazon—you pay the same, I get 4%.
get my thai dictionary app
Learn Thai with my Talking Thai-English-Thai Dictionary app: iOS, Android, Windows.
get my thai phrasebook app
Experience Thailand richly with my Talking Thai-English-Thai Phrasebook app.
get my chinese phrasebook app
Visit China easily with my Talking Chinese-English-Chinese Phrasebook app.
get thailand fever
I co-authored this bilingual cultural guide to Thai-Western romantic relationships.

Submit This SiteLike what you see?
Help spread the word on social media:
Submit This Site

Like what you see?
Help spread the word on social media:

Note: Updated Lurker's Guide available (but not this page!)

This page belongs to the old 1990s SGI Lurker's Guide. As of 2008, several of the Lurker's Guide pages have been updated for HDTV and for modern OS platforms like Windows and Mac. This particular page is not one of those, but you can see what new stuff is available here. Thanks!

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 APIbuffering mechanismVL platformsOS releases
classicVLInfoPtrs and VLBuffersallall
O2DMbuffers and DMbufferpoolsO2 (mvp)IRIX 6.3 and later
cross-platformDMbuffers and DMbufferpools ev3, cosmo2, divoIRIX 6.4 and later
allIRIX 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 *)

Support This SiteI created this site and made it available free to all readers. If you have found it helpful or amusing, please support the effort, and future updates, in one of these ways:
donate now   Donate Now
Use your credit card or PayPal to donate in support of the site.
get anything from amazon.com
Use this link to Amazon—you pay the same, I get 4%.
get my thai dictionary app
Learn Thai with my Talking Thai-English-Thai Dictionary app: iOS, Android, Windows.
get my thai phrasebook app
Experience Thailand richly with my Talking Thai-English-Thai Phrasebook app.
get my chinese phrasebook app
Visit China easily with my Talking Chinese-English-Chinese Phrasebook app.
get thailand fever
I co-authored this bilingual cultural guide to Thai-Western romantic relationships.
CopyrightAll text and images copyright 1999-2017 Chris Pirazzi unless otherwise indicated.
Support This Site

I created this site and made it available free to all readers. If you have found it helpful or amusing, please support the effort, and future updates, in one of these ways:
donate now   Donate Now
Use your credit card or PayPal to donate in support of the site.
get anything from amazon.com
Use this link to Amazon—you pay the same, I get 4%.
get my thai dictionary app
Learn Thai with my Talking Thai-English-Thai Dictionary app: iOS, Android, Windows.
get my thai phrasebook app
Experience Thailand richly with my Talking Thai-English-Thai Phrasebook app.
get my chinese phrasebook app
Visit China easily with my Talking Chinese-English-Chinese Phrasebook app.
get thailand fever
I co-authored this bilingual cultural guide to Thai-Western romantic relationships.
Copyright

All text and images copyright 1999-2017 Chris Pirazzi unless otherwise indicated.