vlxeventrecv(3dm)

NAME
     VL_EXT_EVENT_RECV - VL Event Receive library extension for O2
     workstations (now obsolete)

SYNOPSIS
     #include <dmedia/vl.h>


DESCRIPTION
     This API has been supplanted by a cross-platform API for video and
     DMbuffers.  It is supported for backwards compatibility only.  Please see
     vlintro(3dm).

     The VL Event Receive extension provides a mechanism for video
     applications to send and receive DMbuffers on the O2 system.  These
     buffers can be used to move images between software subsystems, such as
     dmIC and OpenGL (see glIntro(3G)), without copying any data.

     The VL Event Receive extension consists of the following function calls:

     vlPathGetFD(3dm) - Get the event file descriptor associated with a VL
     path

     vlEventRecv(3dm) - Receive a VL event from a VL path

     vlEventToDMBuffer(3dm) - Get a pointer to the DMBuffer referenced by a VL
     event

     vlDMBufferSend(3dm) - Send a VL buffer to a VL path

     vlDMPoolGetParams(3dm) - Determine the memory pool requirements for this
     VL memory node

     The following standard VL function calls may be particularly useful with
     the above named function calls:

     vlDMPoolRegister(3dm) - Register a DMPool with a VL node for memory
     transfers

     vlDMPoolDeregister(3dm) - Deregister a DMPool with a VL node

     vlGetFilledByNode(3dm) - Determine the depth of a VL event queue


DIGITAL MEDIA BUFFERS
     The Video Library supports digital media buffers, dmbuffer(3dm), for some
     devices. DMbuffers replace the fixed ring buffer of DMRB with a more
     flexible mechanism based on a FIFO. DMbuffers provide the ability to
     retain individual buffers without stopping video transfers.  They can be
     used to pass data efficiently, by reference instead of copying, between
     different video paths and between libraries. (e.g., digital media Image
     Converter, dmIC(3dm).)
     The routines in the VL Event Receive extension are incompatible with some
     of the existing vl interfaces.  Using them in combination may result in
     the error VLAPIConflict.

     The following routines are specific to DMbuffers:

          vlPathGetFD(3dm)
          vlEventRecv(3dm)
          vlEventToDMBuffer(3dm)
          vlDMBufferSend(3dm)
          vlDMPoolGetParams(3dm)
          vlDMPoolRegister(3dm)
          vlDMPoolDeregister(3dm)


     The following routines cannot be used with DMbuffers:

          Event Oriented:
              vlPending
              vlNextEvent
              vlCheckEvent
              vlPeekEvent

          Callbacks and Handlers:
              vlMainLoop
              vlRegisterHandler
              vlRemoveHandler
              vlAddCallback
              vlRemoveCallback
              vlRemoveAllCallbacks
              vlCallCallbacks

          Buffer Oriented:
              vlCreateBuffer
              vlRegisterBuffer
              vlDeregisterBuffer
              vlBufferAdvise
              vlBufferGetFD
              vlBufferDone
              vlBufferReset
              vlDestroyBuffer
              vlGetNextFree
              vlPutFree
              vlPutValid
              vlGetNextValid
              vlGetLatestValid
              vlGetActiveRegion
              vlGetDMediaInfo
              vlGetImageInfo

EXAMPLE
     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 */
               vlDMPoolGetParams(svr, path, drn, plist);

               /* create the pool */
               dmBufferCreatePool(plist, &pool);

               /* register it with the path and node */
               vlDMPoolRegister(svr, path, drn, pool);




NOTES
     The vlinfo(1) command reports which video library extensions are
     available on a system.

     Extensions may be queried programmatically using the vlGetString(3dm)
     function of the video library.


SEE ALSO
     vlEventRecv(3dm), vlDMBufferSend(3dm), vlGetString(3dm),
     vlDMPoolGetParams(3dm), dmbuffer(3dm), dmIC(3dm)