clOpenDecompressor(3dm)

NAME
     clOpenDecompressor, clDecompress, clCloseDecompressor - Decompress a
     video or audio stream

SYNOPSIS
     #include <dmedia/cl.h>

     int clOpenDecompressor(int scheme, CLhandle *handlePtr)
     int clDecompress(CLhandle handle, int numberOfFrames,
         int compressedBufferSize, void *compressedBuffer, void *frameBuffer)
     int clCloseDecompressor(CLhandle handle)

ARGUMENTS
     scheme         The decompression scheme to use.

     handlePtr      A pointer to the returned handle of the decompressor. Used
                    by subsequent calls to identify the decompressor.

     handle         A handle to the decompressor.

     numberOfFrames The number of frames to decompress, which should be a
                    multiple of CL_FRAMES_PER_CHUNK (usually 1 for video).
                    numberOfFrames may also be specified as
                    CL_CONTINUOUS_BLOCK or CL_CONTINUOUS_NONBLOCK.

     compressedBufferSize
                    The size of the data to be decompressed in bytes.  Used
                    with non-NULL compressedBuffer to describe buffer length.

     compressedBuffer
                    A pointer to the data to be decompressed.  A value of NULL
                    selects the use of a previously created buffer to supply
                    the compressed data (Implicit Buffering).

     frameBuffer    A pointer to where decompressed frames are to be placed.
                    A value of CL_EXTERNAL_DEVICE may be used with some
                    decompressors to indicate a direct connection to an
                    external video or audio destination.  A value of NULL
                    selects the use of a previously created buffer to hold the
                    decompressed frames (Implicit Buffering).


DESCRIPTION
     clOpenDecompressor opens a decompressor for a given scheme. It is called
     before clDecompress or any call that requires a decompressor handle.
     clCloseDecompressor closes the decompressor after which handle is no
     longer valid.

     clDecompress invokes different buffering models depending on the values
     of the buffer arguments (see CLintro(3dm)).

     1. Direct Buffering
          If compressedBuffer and frameBuffer are non-NULL,
          clDecompress decompresses numberOfFrames from
          compressedBuffer and stores the result in frameBuffer.
          frameBuffer may also be set to CL_EXTERNAL_DEVICE to indicate
          a hardware output destination (currently supported by CL_JPEG_COSMO).

     2. Implicit Buffering

          If compressedBuffer and frameBuffer are NULL,
          clDecompress operates on buffers that have been created
          previously with clCreateBuf.  The input buffer should be
          filled with calls to clQueryFree, clUpdateHead, and
          clDoneUpdatingHead.  The output buffer should be emptied
          with calls to clQueryValid and clUpdateTail.

     Direct and Implicit Buffering models may be mixed in one call by setting
     one of the buffer arguments to be non-NULL, and the other to be NULL.

     With either model, buffers should be appropriately sized for proper
     execution of clDecompress.  The input compressed buffer should have a
     minimum capacity of CL_COMPRESSED_BUFFER_SIZE bytes.  The output frame
     buffer should have a minimum capacity of CL_FRAMES_PER_CHUNK frames.
     These parameters may be determined by calling clGetParams, after first
     calling clReadHeader to configure the decompressor.

     If numberOfFrames is non-negative, clDecompress may consume up to
     CL_COMPRESSED_BUFFER_SIZE * numberOfFrames / CL_FRAMES_PER_CHUNK bytes of
     input data and attempts to produce numberOfFrames frames of output data.
     The call does not return until processing is completed.

     If numberOfFrames is specified as CL_CONTINUOUS_BLOCK or
     CL_CONTINUOUS_NONBLOCK then clDecompress continues until either the input
     buffer is marked done, or a call to clCloseDecompressor is made.
     CL_CONTINUOUS_NONBLOCK differs from CL_CONTINUOUS_BLOCK in that the call
     to clDecompress returns immediately while the decompression occurs in a
     separate thread.  These special values should only be used with Implicit
     Buffering.

     Multiple decompressors can be open simultaneously. handle identifies
     which one is being referenced.


RETURN VALUES
     Upon success, clOpenDecompressor and clCloseDecompressor return SUCCESS,
     and clDecompress returns the numberOfFrames actually produced or, in the
     case of CL_CONTINUOUS_NONBLOCK, returns SUCCESS immediately.

     Upon failure, each routine returns a negative error code.  With some
     schemes, clOpenDecompressor returns CL_SCHEME_BUSY if there is a system
     resource (e.g. a piece of hardware) which is in use by another process.
     A return code of CL_SCHEME_NOT_AVAILABLE indicates that the hardware or
     software required by the scheme is not installed on the system.
EXAMPLE
          #include <dmedia/cl.h>
           ...
          /* Open the decompressor */
          clOpenDecompressor(CL_MVC1_SOFTWARE, &handle);

          /* Configure the decompressor by reading the header */
          headerSize = clQueryMaxHeaderSize(CL_MVC1_SOFTWARE);
          /* Get the header data from somewhere */
           ...
          clReadHeader(handle, headerSize, header);

          /* Allocate implicit input buffer of the required size */
          compressedBufferSize = clGetParam(handle, CL_COMPRESSED_BUFFER_SIZE);
          clCreateBuf(handle, CL_BUF_COMPRESSED, compressedBufferSize, 1, NULL);

          /* Decompress a series of frames */
          for(i = 0; i < N; i++)
          {
              /* Keep input buffer full with compressed data */
               ...
              clDecompress(handle, 1, 0, NULL, frameBuffer);
              /* Write the frame to somewhere (such as the screen) */
               ...
          }

          /* Close the decompressor */
          clCloseDecompressor(handle);


SEE ALSO
     CLintro(3dm), clReadHeader(3dm), clGetParams(3dm), clCreateBuf(3dm),
     clQueryFree(3dm), clUpdateHead(3dm), clQueryValid(3dm),
     clUpdateTail(3dm), clDoneUpdatingHead(3dm)