cl Compression(3dm) cl Compression(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
Page 1
cl Compression(3dm) cl Compression(3dm)
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.
Page 2
cl Compression(3dm) cl Compression(3dm)
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 ALSOCLintro(3dm), clSetParams(3dm), clGetParams(3dm), clCreateBuf(3dm),
clQueryFree(3dm), clUpdateHead(3dm), clQueryValid(3dm), clUpdateTail(3dm)clDoneUpdatingHead(3dm)
Page 3
