vlDMBufferGetValid(3dm)

NAME
     vlDMBufferGetValid, vlDMBufferPutValid, vlDMBufferGetVideoInfo,
     vlDMBufferSetVideoInfo - VL DMbuffer management routines

SYNOPSIS
     #include <dmedia/vl.h>

     int vlDMBufferGetValid(VLServer vlServer, VLPath path, VLNode node, DMbuffer* dmbuffer);
     int vlDMBufferPutValid(VLServer vlServer, VLPath path, VLNode node, DMbuffer dmbuffer);
     #include <sys/dmcommon.h>
     int vlDMBufferGetVideoInfo(DMbuffer dmbuffer, DMBufferVideoInfo* vidinfo)
     int vlDMBufferSetVideoInfo(DMbuffer dmbuffer, DMBufferVideoInfo* vidinfo)

DESCRIPTION
     vlDMBufferGetValid returns a valid DMbuffer containing video data from
     the specified node and path.  This call is used in video capture-type
     applications where a path is set up to route image data from a source
     video device node to drain memory node.

     The buffer that is returned contains one video image, either a field or a
     frame.  dmBufferMapData can be used to get a pointer to the image in the
     buffer.  The contents of the buffer should not be modified.

     vlDMBufferPutValid takes a valid DMbuffer and sends it to the path via
     the specified node.  This call is used in video playback-type
     applications where a path is set up to route image data from a source
     memory node to a drain video device node.

     After calling vlDMBufferPutValid, the video library and the call both
     have references to the buffer.  The contents of the buffer should not be
     changed by the caller.

     vlDMBufferGetVideoInfo copies the contents of the DMBufferVideoInfo
     structure associated with a DMBuffer to the address of a
     DMBufferVideoInfo structure specified by the user.

     vlDMBufferSetVideoInfo copies the contents of a DMBufferVideoInfo
     structure pointed to by the specified address to the DMBufferVideoInfo
     structure associated with a DMBuffer.

     The DMBufferVideoInfo structure is currently defined as:

     typedef struct DMBufferVideoInfo_s {
         DMVITCcode vitc[2];
         unsigned int validinfo;
         unsigned int sdti;
         char pad[DMBUF_VIDINFO_PAD]; } DMBufferVideoInfo;

     #define DMBUF_VIDINFO_SIZE      96  /* size in bytes of DMBufferVideoInfo
     */
     #define DMBUF_VIDINFO_PAD  ((DMBUF_VIDINFO_SIZE) - 2*sizeof(DMVITCcode) -
     2*sizeof(unsigned int))

     #define DMBUF_VIDINFO_VALID_VITC1 0x1

     #define DMBUF_VIDINFO_VALID_VITC2 0x2

     #define DMBUF_VIDINFO_VALID_SDTI  0x4

     and is included in sys/dmcommon.h header file.

MACHINE DEPENDENCIES
     When using glXAssociateDMPbufferSGIX to pass DMbuffers between video and
     OpenGL on the O2 platform, VL_LAYOUT should be set to VL_LAYOUT_GRAPHICS.
     This way, the video libary will expect DMbuffers in the format used
     internally by OpenGL.

RETURN VALUE
     Upon successful completion, vlDMBufferGetValid returns VLSuccess and
     dmbuffer points to a valid DMbuffer referencing video data.  Otherwise,
     -1 is returned, dmbuffer is set to NULL and vlErrno is set indicating the
     error.  Note that vlErrno set to VLAgain does not indicate an error but
     rather that there was no video data at the specified node when
     vlDMBufferGetValid was called.

     Upon success completion, vlDMBufferPutValid returns VLSuccess, otherwise
     a value of -1 is returned and vlErrno is set indicating the error.

SEE ALSO
     vlDMPoolRegister(3dm), vlDMPoolDeregister(3dm), dmBufferAllocate(3dm),
     dmBufferFree(3dm), dmBufferMapData(3dm)