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.
DESCRIPTIONclCreateBuf 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
Page 1
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 VALUESclCreateBuf 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 ALSOCLintro(3dm), clQueryFree(3dm), clUpdateHead(3dm), clQueryValid(3dm),
clUpdateTail(3dm), clDoneUpdatingHead(3dm)
Page 3
