cl Decompression(3dm) cl Decompression(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
CLCONTINUOUSBLOCK or CLCONTINUOUSNONBLOCK.
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 CLEXTERNALDEVICE 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
Page 1
cl Decompression(3dm) cl Decompression(3dm)
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.
Page 2
cl Decompression(3dm) cl Decompression(3dm)
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)
Page 3