dmbuffer(4)

NAME
     DMbuffer, DMbufferpool - Digital Media data transport subsystem

SYNOPSIS
     #include <dmedia/dm_buffer.h>

     -ldmedia

     DMbufferpool pool;

     DMbuffer buf;

DESCRIPTION
     The DMbufferpool and DMbuffer data types and operations on them implement
     the Digital Media data transport subsystem.  This subsystem is for
     sharing and exchanging time sensitive visual data between compression
     devices and algorithms, video input/output, graphics rendering and
     texturing, and the host processor(s).

     An overview of the DMbufferpool and DMbuffer data types is presented here
     along with brief descriptions of their defined operations within the data
     transport subsystem as well as in the image converter subsystem (dmIC),
     video I/O subsystem (VL), and graphics (Opengl DMbuffer extension).
     Refer to the individual manual pages for detailed descriptions of each
     operation.

     A DMbufferpool is memory specially allocated to guarantee the
     requirements of one or more time sensitive visual data processing and/or
     transport devices.  Before a process begins operation of one or more such
     devices one or more DMbufferpool's are created.

     In general a DMbufferpool is quite large and depending on device
     requirements may consist of physical memory.  Full rate full size video
     I/O devices and full rate full size image conversion devices
     (compression/decompression) generally require large amounts of physical
     memory.  For these reasons the initial creation of all DMbufferpool's is
     best done during program initialization.

     A DMbuffer generally holds a video image (field or frame) or data
     representing a compressed video image.  The exact description of the data
     in the buffer is generally held in a DMparams data structure which the
     program manages separately from the DMbuffers.  That is, the DMbuffer
     subsystem does not itself have any knowledge of the data.

     Each DMbuffer is allocated from a DMbufferpool and when no longer needed
     is returned to that pool for reuse.  A file descriptor for the
     DMbufferpool is available for use with select(2) to determine when there
     is a DMbuffer available for allocation.  The operations to allocate a
     DMbuffer and return one for reuse are very lightweight.  Multiple
     outstanding DMbuffer's are well behaved and may be further transported to
     and from video I/O devices, image converter devices and algorithms, and
     graphics out of order with respect to allocation.
POOL CREATION
     dmBufferCreatePool creates a DMbufferpool using a DMparams
     parameter/value list encapsulating the combined buffering requirements of
     all devices to access this memory.  After a pool is created the host may
     initiate device and/or direct access to the memory at the granularity of
     a DMbuffer.

     dmBufferSetPoolDefaults initializes the DMparams list which can then be
     passed to:  dmICGetSrcPoolParams or dmICGetDstPoolParams to gather the
     input or output memory requirements of an image conversion (compression,
     decompression) device or algorithm; vlDMPoolGetParams(3dm) to gather the
     memory requirements of a video input or output device.

BUFFER ALLOCATION
     dmBufferGetPoolFD returns a file descriptor for use in the writefds
     fd_set in select(2). When select returns a ready indication for this file
     descriptor the process is assured that dmBufferAllocate will successfully
     allocate a new DMbuffer.

     dmBufferMapData gives the host direct access to the memory in the
     DMbuffer.

     The DMbuffer may be transferred to and from one or more devices as
     described in the next section.

     dmBufferFree releases the buffer and further is the only means by which a
     process releases a buffer for reuse.  A buffer is not available for reuse
     until all devices as well as the process release their reference to the
     buffer.

BUFFER TRANSPORT
     A DMbuffer originating in the process is used as follows:

               dmBufferAllocate(pool, &buf);
               cp = dmBufferMapData(buf);
               bcopy(from, cp, nbytes);
               -or-
               read(fd, cp, nbytes);
               dmBufferSetSize(buf, nbytes);
               (*send1)(handle1, buf);
               (*send2)(handle2, buf);
               dmBufferFree(buf);

     A DMbuffer originating with a device is used as follows:

               (*recv)(&buf);
               cp = dmBufferMapData(buf);
               nbytes = dmBufferGetSize(buf);
               bcopy(cp, to, nbytes);
               -or-
               write(fd, cp, nbytes);
               (*send1)(handle1, buf);
               (*send2)(handle2, buf);
               dmBufferFree(buf);

     Note that in either case the DMbuffer is available for further transport
     to 0 or more other devices.

     The following sections give an overview of the (*send)() and (*recv)()
     operations for different classes of visual processing devices.

IMAGE CONVERTER - dmIC
     dmICReceive transfers a DMbuffer from the image converter output queue to
     the process.  This is a simple queue operation and immediately fails if
     no data is available.  The image converter provides a file descriptor
     which indicates when data is available on the output queue.

     dmICSend transfers a DMbuffer from the process to the image converter
     input queue.  This is a simple queue operation and immediately fails if
     the input queue is full.

VIDEO DEVICE I/O - VL
     vlEventRecv and vlEventToDMBuffer transfer a DMbuffer from a video input
     device to the process.

     vlDMBufferSend transfers a DMbuffer from the process to a video ouput
     device.

HOST ACCESS
     dmBufferMapData gives the process a pointer to the data in the DMbuffer.

     dmBufferGetSize returns the number of bytes of valid data in the buffer.

     dmBufferSetSize is used by the process to set the amount of valid data
     placed in the buffer.

SEE ALSO
     dmICGetSrcPoolParams(3dm), dmICGetDstPoolParams(3dm),
     vlDMPoolGetParams(3dm), dmBufferCreatePool(3dm), dmBufferAllocate(3dm),
     dmICSend(3dm), dmICReceive(3dm), vlEventRecv(3dm),
     vlEventToDMBuffer(3dm), vlDMBufferSend(3dm), dmBufferMapData(3dm).