clOpenCompressor(3dm)

NAME
     clOpenCompressor, clCompress, clCloseCompressor - Compress a video or
     audio stream

SYNOPSIS
     #include <dmedia/cl.h>

     int clOpenCompressor(int scheme, CLhandle *handlePtr)
     int clCompress(CLhandle handle, int numberOfFrames,
         void *frameBuffer, int *compressedBufferSize, void *compressedBuffer)
     int clCloseCompressor(CLhandle handle)

ARGUMENTS
     scheme         The compression scheme to use.

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

     handle         A handle to the compressor.

     numberOfFrames The number of frames to compress, 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.

     frameBuffer    A pointer to the frame buffer to be compressed. A value of
                    CL_EXTERNAL_DEVICE may be used with some compressors to
                    indicate a direct connection to an external video or audio
                    source.  A value of NULL selects the use of a previously
                    created buffer to supply the frame data (Implicit
                    Buffering).

     compressedBufferSize
                    A pointer to the returned size of the compressed data in
                    bytes.

     compressedBuffer
                    A pointer to where the compressed data is to be placed. A
                    value of NULL selects the use of a previously created
                    buffer to place the compressed data (Implicit Buffering).

DESCRIPTION
     clOpenCompressor opens a compressor for a given scheme.  It is called
     before clCompress or any call that requires a compressor handle.
     clCloseCompressor closes the compressor after which handle is no longer
     valid.

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

     1. Direct Buffering

          If frameBuffer and compressedBuffer are non-NULL,
          clCompress compresses numberOfFrames from
          frameBuffer and stores the result in compressedBuffer
          and the resulting size in compressedBufferSize.
          frameBuffer may also be set to CL_EXTERNAL_DEVICE to indicate
          a hardware input source (currently supported by CL_JPEG_COSMO).

     2. Implicit Buffering

          If frameBuffer and compressedBuffer are NULL,
          clCompress 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 clCompress.  The input frame buffer should have a minimum
     capacity of CL_FRAMES_PER_CHUNK frames.  The output compressed buffer
     should have a minimum capacity of CL_COMPRESSED_BUFFER_SIZE bytes.  These
     parameters may be determined by calling clGetParams, after first calling
     clSetParams to provide the compressor with initialization information
     such as input dimensions and format.

     If numberOfFrames is non-negative, clCompress attempts to consume
     numberOfFrames frames of input data and may produce up to
     CL_COMPRESSED_BUFFER_SIZE * numberOfFrames / CL_FRAMES_PER_CHUNK bytes 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 clCompress continues until either the input
     buffer is marked done, or a call to clCloseCompressor is made.
     CL_CONTINUOUS_NONBLOCK differs from CL_CONTINUOUS_BLOCK in that the call
     to clCompress returns immediately while the compression occurs in a
     separate thread.  These special values should only be used with Implicit
     Buffering.

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


RETURN VALUES
     Upon success, clOpenCompressor and clCloseCompressor return SUCCESS, and
     clCompress returns either the numberOfFrames actually consumed or, in the
     case of CL_CONTINUOUS_NONBLOCK, returns SUCCESS immediately.

     Upon failure, each routine returns a negative error code.  With some
     schemes, clOpenCompressor 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>

          int paramValueBuffer[][2] = {
              CL_IMAGE_WIDTH,  0,
              CL_IMAGE_HEIGHT, 0,
              CL_COMPRESSED_BUFFER_SIZE, 0
          };
           ...
          /* Open the compressor */
          clOpenCompressor(CL_MVC1_SOFTWARE, &handle);

          /* Configure the compressor by setting some params */
          paramValueBuffer[0][1] = 320;
          paramValueBuffer[1][1] = 240;
          clSetParams(handle, (int *)paramValueBuffer, 4);

          /* Allocate output buffer of the required size */
          clGetParams(handle, (int *)paramValueBuffer, 6);
          compressedBuffer = malloc(paramValueBuffer[2][1]);

          /* Compress a series of frames */
          for(i = 0; i < N; i++)
          {
              /* Get a frame from somewhere */
               ...
              clCompress(handle, 1, frameBuffer, &compressedBufferSize,
               compressedBuffer);
              /* Write the compressed data to somewhere else */
               ...
          }

          /* Close the compressor */
          clCloseCompressor(handle);


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