cl Create/Destroy Implicit Buffers(3dm)



NAME
     clCreateBuf, clDestroyBuf, clQueryBufferHdl, clQueryHandle - Create and
     destroy implicit buffers, and find related handles.

SYNOPSIS
     #include <dmedia/cl.h>

     CLbufferHdl clCreateBuf(CLhandle handle, int bufferType,
         int blocks, int blockSize, void **bufferPtr1)
     int clDestroyBuf(CLbufferHdl bufferHdl)
     CLbufferHdl clQueryBufferHdl(CLhandle handle,
         int bufferType, void **bufferPtr2)
     CLhandle clQueryHandle(CLbufferHdl bufferHdl)

ARGUMENTS
     handle       A handle to the compressor or decompressor.

     bufferType   The type of buffer, either CL_BUF_FRAME or
                  CL_BUF_COMPRESSED.

     blocks       The number of blocks in the buffer.

     blockSize    The size in bytes of each block.  This must be equal to the
                  frame size for CL_BUF_FRAME, and 1 for CL_BUF_COMPRESSED.

     bufferPtr1   A pointer to a pointer to the buffer space. If bufferPtr1 is
                  NULL, clCreateBuf will allocate the blocks.  If bufferPtr1
                  is not NULL and *bufferPtr1 is NULL, clCreateBuf will
                  allocate the blocks and set *bufferPtr1 to point to the new
                  space.  Otherwise, the space at *bufferPtr1 will be managed
                  as the ring buffer.  See the NOTES section below for more
                  information.

     bufferHdl    The handle to the buffer.

     bufferPtr2   A pointer to a pointer to the buffer space.  If bufferPtr2
                  is not NULL, clQueryBufferHdl will set *bufferPtr2 to point
                  to the buffer space.


DESCRIPTION
     clCreateBuf is used to create a CL ring buffer.  These ring buffers are
     needed for the "Implicit Buffering" model of data processing, where
     buffers are not specified in the processing call.  Implicit buffering is
     invoked for clCompress and clDecompress by giving NULL as the frameBuffer
     or compressedBuffer.

     Compressors and decompressors have buffers of type CL_BUF_FRAME and
     CL_BUF_COMPRESSED.

     Buffer space may be allocated by either the application or the library.
     The former is useful if there already exists memory space that contains









cl Create/Destroy Implicit Buffers(3dm)



     data to be processed, or holds results to be read.  In this case,
     creating the ring buffer directly from this memory saves on potential
     copies to or from the CL buffer.

     clDestroyBuf is used to deallocate the CL buffer.  clQueryBufferHdl is
     used to find the buffer handle from a compressor or decompressor handle.
     clQueryHandle is used to find the processing object handle from a buffer
     handle.

     An application may read from and write to these buffers using the
     additional calls clQueryFree, clUpdateHead, clQueryValid, clUpdateTail,
     and clDoneUpdatingHead.


NOTES
     Some schemes may have constraints on the alignment of their buffers.
     Specifying the bufferPtr1 argument to clCreateBuf as NULL and then using
     only the read/write functions will allow the application to work with
     every scheme.


RETURN VALUES
     clCreateBuf returns the buffer handle used in subsequent buffering calls,
     or NULL on failure.  clDestroyBuf returns SUCCESS, or a negative error
     code on failure.  clQueryBufferHdl returns the handle to the buffer, or
     NULL on failure.  clQueryHandle returns the handle to the processing
     object, or NULL on failure.



EXAMPLE
          #include <dmedia/cl.h>
          CLhandle  handle;
          CLbufferHdl    bufferHdl;
          void           *buffer;
           ...
          clOpenCompressor(CL_MVC1_SOFTWARE, &handle);
           ...
          /* Create a buffer of 10 blocks of size 10000 */
          buffer = malloc(10*10000);
          bufferHdl = clCreateBuf(handle, CL_BUF_FRAME, 10, 10000, &buffer);
          bufferHdl = clQueryBufferHdl(handle, CL_BUF_FRAME, &buffer);
          handle = clQueryHandle(bufferHdl);
           ...
          clDestroyBuf(bufferHdl);
          clCloseCompressor(handle);









                                                                        Page 2






cl Create/Destroy Implicit Buffers(3dm)



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




















































                                                                        Page 3



                                                                        Page 1