CLintro(3dm) CLintro(3dm)
CLintro, CompressionLibrary, compression, libcl, cl - A library for
working with compressed video and audio data
#include <dmedia/cl.h>
-lcl
The Compression Library provides an application programming interface for
processing video and audio data using a variety of compression
algorithms.
Compression techniques are useful for extending the utility of system
resources such as memory, disk space, and network bandwidth. Some
application areas include publishing (presentations, documentation,
training, archiving, and annotation), telecommunications (video/voice
mail, phone, and conferencing), animation previewing (2D/3D graphics
renderings), and movie editing.
The Compression Library is used by several Silicon Graphics digital media
tools, including capture(1), movieplay
.
The library focuses on accepted standards, as well as proprietary methods
that have additional benefits. Some algorithms are enabled with the
installation of separate products (see the section on option products).
The techniques currently supported are discussed below. Note that each
algorithm implementation has a corresponding "scheme" identifier that
begins with the common library prefix, CL. Algorithms are grouped into
two categories : video compression and audio compression.
VIDEO COMPRESSION [Toc] [Back]
MPEG-1 Video (ISO 11172-2) is a video compression standard designed to
exploit temporal as well as spatial redundancies in order to achieve good
image quality at very high compression ratios; an MPEG-1 stream at 1.2
Mbit/second (low enough for single-speed CD-ROMs) gives quality
comparable to VHS video. MPEG-1 is an asymmetrical technique, with
compression being much more computationally demanding than decompression.
Scheme is CL_MPEG1_VIDEO_SOFTWARE.
JPEG (baseline) is a standard method for encoding individual images.
Very good compressed quality (almost indistinguishable from the original)
can be achieved at about 1.2 to 1.5 bits/pixel. Compression consists of
frequency transformation, quantization, and entropy coding; decompression
is the reverse. Two versions of the JPEG algorithm are supported, an
all-software implementation (scheme is CL_JPEG_SOFTWARE) and a hardware
Page 1
CLintro(3dm) CLintro(3dm)
assisted version (scheme is CL_JPEG_COSMO).
MVC1 (Motion Video Compressor 1) is an SGI proprietary algorithm. It is
designed for efficient decompression of motion video. Reasonable quality
can be achieved at about 4.5 bits/pixel. Scheme is CL_MVC1_SOFTWARE.
MVC2 (Motion Video Compressor 2) is similar to MVC1, but can compress to
about 2 bits/pixel with approximately the same quality. Scheme is
CL_MVC2_SOFTWARE.
MVC3 (Motion Video Compressor 3) is an SGI proprietary algorithm based on
fast transform coding. Scheme is CL_MVC3_SOFTWARE.
RLE (Run Length Encoding) is a lossless algorithm for compressing 8-bit
RGB data. Compression ratios are often 2:1 or less for many images, but
may be higher for graphics scenes. Scheme is CL_RLE_SOFTWARE.
RLE24 is run length encoding applied to 24-bit RGB data. Scheme is
CL_RLE24_SOFTWARE.
An "uncompressed" video algorithm is also supported. This allows
uncompressed data to be handled without alteration using the same library
interface that is used for compressing data, which may be convenient for
some applications. Scheme is CL_UNCOMPRESSED_VIDEO.
The performance of these techniques for one test sequence is shown below.
Results will vary with other data sequences and compression parameters,
and may change with newer implementations.
Table 1: Video Algorithms - Performance Example
320 by 240 frames on Indy R4400
Comp. Average bits/s frames/second
Algorithm Ratio bits/pixel at compress
30 f/s decompress
Uncompressed 1:1 24 55.30M - -
MPEG-1 48:1 0.5 1.16M 0.5 17.5
JPEG (software) 33:1 0.7 1.66M 3.1 7.2
MVC1 8:1 3.1 7.10M 11.7 83.9
MVC2 19:1 1.3 2.92M 10.0 89.7
MVC3 14:1 1.7 3.96M 9.3 17.6
RLE 6:1 3.9 8.90M 20.3 39.4
RLE24 6:1 4.2 9.76M 43.3 20.3
AUDIO COMPRESSION [Toc] [Back]
MPEG-1 Audio (ISO 11172-3) is an audio compression standard based on
subband coding and perceptual bit allocation. The core engine is
licensed from Aware, Inc. Two interfaces are provided by the Compression
Library - one that accesses the Aware codec directly (scheme is
Page 2
CLintro(3dm) CLintro(3dm)
CL_MPEG1_AUDIO_AWARE), and an SGI version that provides other features
(scheme is CL_MPEG1_AUDIO_SOFTWARE).
Aware Multirate is an Aware proprietary technique that provides lossless
to near-lossless quality. Compression ratios are typically 2:1 to 5:1.
Scheme is CL_MULTIRATE_AWARE.
G711 u-law is a simple 16-bit to 8-bit conversion that uses coarse
quantization at high volumes and fine quantization at low volumes. It is
a standard encoding format in the U.S. Scheme is CL_G711_ULAW_SOFTWARE.
G711 A-law also performs 16-bit to 8-bit conversion, but with a slightly
different mapping. It is a standard encoding format in Europe. Scheme
is CL_G711_ALAW_SOFTWARE.
An "uncompressed" audio algorithm is also supported. Scheme is
CL_UNCOMPRESSED_AUDIO.
The performance of these techniques for one test sequence is shown below.
Table 2: Audio Algorithms - Performance Example
2x16-bit (stereo) frames on Indy R4400
Comp. Average bits/s frames/second
Algorithm Ratio bits/samp at compress
44.1 KHz decompress
Uncompressed 1:1 16.0 1.41M - -
MPEG-1 7:1 2.2 192K 54.6K 163.8K
Multirate 5:1 3.4 296K 179.2K 220.5K
u-law 2:1 8.0 706K 1.17M 2.21M
A-law 2:1 8.0 706K 1.79M 2.05M
The Compression Library recognizes the following video and audio formats.
VIDEO FORMATS [Toc] [Back]
CL_FORMAT_ABGR means R, G, B, and A data are 8-bit components packed into
a 32-bit word as:
Page 3
CLintro(3dm) CLintro(3dm)
0xAABBGGRR
where:
AA contains the alpha value.
BB contains the blue value.
GG contains the green value.
RR contains the red value.
CL_FORMAT_XBGR means R, G, B, and X (don't care) data are packed into a
32-bit word as 0xXXBBGGRR.
CL_FORMAT_BGR means R, G, and B data are packed into a 24-bit word. Note
that with this format, the RGB triplets may cross 32-bit word boundaries.
CL_FORMAT_BGR332 means R, G, and B data are packed into a byte as:
rrrbbggg
where:
rrr is three bits of red.
bb is two bits of blue.
ggg is three bits of green.
CL_FORMAT_BGR233 means R, G, and B data are packed into a byte as:
bbgggrrr
where:
bb is two bits of blue.
ggg is three bits of green.
rrr is three bits of red.
CL_FORMAT_GRAYSCALE means four luminance bytes are packed into a 32-bit
word.
CL_FORMAT_YCbCr means 3 8-bit components, Y (Luminance), Cb (LuminanceBlue),
and Cr (Luminance-Red), are packed into 24 bits as:
Page 4
CLintro(3dm) CLintro(3dm)
0xCbYYCr
where:
Cb contains the luma-blue value.
YY contains the luminance value.
Cr contains the luma-red value.
CL_FORMAT_YCbCr422 means that two luminance components are packed into a
32-bit word with one Cb-Cr pair (i.e., chroma components are sampled with
half of the horizontal rate of the luma). The order of the components is:
0xCbY1CrY2
where:
Cb contains the chroma-blue value.
Y1 contains the first luminance value.
Cr contains the chroma-red value.
Y2 contains the second luminance value.
This 32-bit word represents two pixels (Y1, Cb, Cr) and (Y2, Cb, Cr).
CL_FORMAT_YCbCr422DC (duplicate chroma) means that the chroma are subsampled
by 2 vertically in addition to horizontally, and are packed the
same as CL_FORMAT_YCbCr422 except that Cb & Cr are duplicated on the odd
lines.
The YCbCr formats use CCIR 601 style scaling and biasing of components.
This means that the nominal range of an eight bit Y component is
[16...235].
AUDIO FORMATS [Toc] [Back]
CL_FORMAT_MONO means that the audio samples represent a single channel.
CL_FORMAT_STEREO_INTERLEAVED means that the audio samples alternately
represent left and right channels.
PROGRAMMING INTERFACE [Toc] [Back] The operations supported by the Compression Library are compression and
decompression. The application programming interface is described in
several parts : processing data, managing implicit buffers, managing
parameters, adding algorithms and parameters, and other features. This
description provides an overview of the API calls. Further details on
each call are available from the corresponding man page.
API FOR PROCESSING DATA [Toc] [Back]
int clOpenCompressor(int scheme, CLhandle *compressorHdl)
int clCompress(CLhandle compressorHdl, int numberOfFrames,
void *frameBuffer, int *compressedBufferSize, void *compressedBuffer)
Page 5
CLintro(3dm) CLintro(3dm)
int clCloseCompressor(CLhandle compressorHdl)
int clOpenDecompressor(int scheme, CLhandle *decompressorHdl)
int clDecompress(CLhandle decompressorHdl, int numberOfFrames,
int compressedBufferSize, void *compressedBuffer, void *frameBuffer)
int clCloseDecompressor(CLhandle decompressorHdl)
Each processing operation (compress, decompress) has a corresponding
object, or CLhandle, which is used to maintain state across processing
calls. First, the object is created with an "Open" call. Then,
processing is performed with one or more "Execute" calls. Finally, when
no more data needs to be processed the object is destroyed with a "Close"
call.
The example below illustrates how to compress a series of 320 by 240 XBGR
images using MVC1:
Example (compression) [Toc] [Back]
| CLhandle compressorHdl;
| int frameBuffer[320][240];
| int compressedBufferSize;
| void *compressedBuffer;
| int k, numberOfFrames;
|
| /* Create and configure the object */
| clOpenCompressor(CL_MVC1_SOFTWARE, &compressorHdl);
| clSetParam(compressorHdl, CL_IMAGE_WIDTH, 320);
| clSetParam(compressorHdl, CL_IMAGE_HEIGHT, 240);
| clSetParam(compressorHdl, CL_FORMAT, CL_FORMAT_XBGR);
|
| /* Allocate space for compressed buffer */
| compressedBufferSize = clGetParam(compressorHdl,
| CL_COMPRESSED_BUFFER_SIZE);
| compressedBuffer = malloc(compressedBufferSize);
|
| /* Compress and write out each frame */
| for (k = 0; k < numberOfFrames; k++) {
| GetVideo(k, frameBuffer);
| clCompress(compressorHdl, 1, frameBuffer,
| &compressedBufferSize, compressedBuffer);
| write(fd, compressedBuffer, compressedBufferSize);
| }
|
| /* Destroy the object */
| clCloseCompressor(compressorHdl);
GetVideo reads frame k from the video source. clSetParam and clGetParam,
used here to configure and query the compressor, are discussed in a later
section (API for Managing Parameters).
Page 6
CLintro(3dm) CLintro(3dm)
Buffering Models [Toc] [Back]
Compressors operate on an input "frame" buffer and an output "compressed"
buffer; decompressors reverse this direction. These buffers are specified
to the processing calls using one of two buffering models.
1. Direct - buffer is given as argument to processing call
o For clCompress and clDecompress, frameBuffer/compressedBuffer
is set to some application-allocated memory (or set to
CL_EXTERNAL_DEVICE, currently supported by CL_JPEG_COSMO).
2. Implicit - buffer is set up prior to processing call
o For clCompress and clDecompress, frameBuffer/compressedBuffer is
set to NULL.
The previous example uses the Direct model, which is the simpler of the
two. The Implicit model is more complicated (requiring several
additional calls such as clCreateBuf and clDestroyBuf), but provides
several benefits described in the next section. Note that it is possible
to mix the two models in one call (e.g. clCompress may be called with
frameBuffer=CL_EXTERNAL_DEVICE and compressedBuffer=NULL).
API FOR MANAGING IMPLICIT BUFFERS [Toc] [Back]
CLbufferHdl clCreateBuf(CLhandle handle, int bufferType,
int blocks, int blockSize, void **buffer)
int clDestroyBuf(CLbufferHdl bufferHdl)
CLbufferHdl clQueryBufferHdl(CLhandle handle,
int bufferType, void **buffer)
CLhandle clQueryHandle(CLbufferHdl bufferHdl)
int clQueryFree(CLbufferHdl bufferHdl, int freeAmount,
void **freeData, int *freeWrap)
int clUpdateHead(CLbufferHdl bufferHdl, int amountToAdd)
int clQueryValid(CLbufferHdl bufferHdl, int validAmount,
void **validData, int *validWrap)
int clUpdateTail(CLbufferHdl bufferHdl, int amountToRelease)
int clDoneUpdatingHead(CLbufferHdl bufferHdl)
Implicit buffers are ring buffers created and managed separately from the
processing calls. A ring buffer contains a number of blocks of arbitrary
size and maintains a pointer to the buffer space, the capacity, and
pointers to the head of (newest) and tail of (oldest) valid data.
The Implicit buffering model facilitates decompression of streaming data
by freeing the application from having to know about data boundaries, and
conveniently supports multiple input or output buffers necessary for
multiplexed data. Separating buffer management calls from data
Page 7
CLintro(3dm) CLintro(3dm)
processing calls also allows an application to be implemented with
multiple threads for input, processing, and output. The ring buffers
support synchronization with a blocking access mode.
The buffer management calls allow applications to create, access, and
destroy ring buffers. Compressors and decompressors have buffers of type
CL_BUF_FRAME and CL_BUF_COMPRESSED.
clCreateBuf and clDestroyBuf create and destroy a ring buffer,
respectively. The actual buffer memory may be allocated by the
application by passing in a non-NULL buffer to the creation function; if
buffer is NULL, the library will allocate the memory. clQueryBufferHdl
returns the ring buffer of specified type given a processing object;
clQueryHandle returns the processing object given a ring buffer.
A ring buffer producer calls clQueryFree and clUpdateHead to add data to
the buffer. clQueryFree gives the size and location of free space in a
buffer. If the requested amount is positive, the calling process will
block until that amount is available. If the requested amount is zero,
then the query will return immediately. clUpdateHead advances the ring
buffer head pointer to indicate newly written data. A ring buffer
consumer calls clQueryValid and clUpdateTail, which are complementary
calls for querying valid data and reading from the tail of the buffer.
The producer should call clDoneUpdatingHead when no more data is to be
written. This allows clQueryValid to return to the consumer instead of
blocking for data that will never arrive.
The following code segments illustrate how to use implicit buffers.
Example (implicit buffering model - record) [Toc] [Back]
| /* Create the frame (input) and compressed (output) buffers */
| frameBufferHdl = clCreateBuf(compressorHdl, CL_BUF_FRAME,
| numberOfFrames, bytesPerFrame, NULL);
| compressedBufferHdl = clCreateBuf(compressorHdl, CL_BUF_COMPRESSED,
| compressedBufferSize, 1, NULL);
|
| /* Write a frame from screen to buffer */
| clQueryFree(frameBufferHdl, 1, &frameBuffer, &wrap);
| lrectread(0, 0, width - 1, height - 1, frameBuffer);
| clUpdateHead(frameBufferHdl, 1);
|
| /* Compress the frame */
| clCompress(compressorHdl, 1, NULL, &compressedBufferSize, NULL);
|
| /* Copy compressed bytes to file */
| while ((size=clQueryValid(compressedBufferHdl, 0, &buf, &wrap)) > 0) {
| write(fd, buf, size);
| clUpdateTail(compressedBufferHdl, size);
| }
Example (implicit buffering model - playback) [Toc] [Back]
Page 8
CLintro(3dm) CLintro(3dm)
| /* Fill the compressed buffer */
| while ((size=clQueryFree(compressedBufferHdl, 0, &buf, &wrap)) > 0) {
| read(fd, buf, size);
| clUpdateHead(compressedBufferHdl, size);
| }
|
| /* Decompress a frame */
| clDecompress(decompressorHdl, 1, 0, NULL, NULL);
|
| /* Read and display the frame */
| clQueryValid(frameBufferHdl, 1, &frameBuffer, &wrap);
| lrectwrite(0, 0, width-1, height-1, frameBuffer);
| clUpdateTail(frameBufferHdl, 1);
Example (implicit buffering model - multiprocess record) [Toc] [Back]
| ProduceFrameProcess() :
| while (1) {
| clQueryFree(frameBufferHdl, 1, &frameBuffer, &wrap);
| lrectread(0, 0, width - 1, height - 1, frameBuffer);
| clUpdateHead(frameBufferHdl, 1);
| }
|
| CompressProcess() :
| while (1)
| clCompress(compressorHdl, 1, NULL, &compressedBufferSize, NULL);
|
| ConsumeCompressedDataProcess() :
| while (1) {
| size = clQueryValid(compressedBufferHdl, 0, &buf, &wrap);
| write(fd, buf, size);
| clUpdateTail(compressedBufferHdl, size);
| }
Example (implicit buffering model - multiprocess playback) [Toc] [Back]
| ProduceCompressedDataProcess() :
| while (1) {
| size = clQueryFree(compressedBufferHdl, 0, &buf, &wrap);
| read(fd, buf, size);
| clUpdateHead(compressedBufferHdl, size);
| }
|
| DecompressProcess() :
| while (1)
| clDecompress(decompressorHdl, 1, 0, NULL, NULL);
|
| ConsumeFrameProcess() :
| while (1) {
| clQueryValid(frameBufferHdl, 1, &frameBuffer, &wrap);
| lrectwrite(0, 0, width - 1, height - 1, frameBuffer);
| clUpdateTail(frameBufferHdl, 1);
Page 9
CLintro(3dm) CLintro(3dm)
| }
API FOR MANAGING PARAMETERS [Toc] [Back]
int clQueryParams(CLhandle handle,
int *paramValueBuffer, int bufferLength)
int clGetParamID(CLhandle handle, char *paramName)
int clGetParams(CLhandle handle,
int *paramValueBuffer, int bufferLength)
int clSetParams(CLhandle handle,
int *paramValueBuffer, int bufferLength)
int clGetParam(CLhandle handle, int paramID)
int clSetParam(CLhandle handle, int paramID, int value)
int clGetDefault(CLhandle handle, int paramID)
int clGetMinMax(CLhandle handle, int paramID, int *min, int *max)
char *clGetName(CLhandle handle, int paramID)
Operations in the Compression Library are guided and monitored through
the use of various parameters. Each compressor or decompressor object
has a list of parameters that is accessible through querying, setting,
and getting. Each parameter has an identifier (paramID) and a text name
(paramName).
clQueryParams is used to determine what parameters are defined for an
object. clGetParamID returns the parameter identifier used in other
calls. clGetParams, clSetParams, clGetParam, and clSetParam are used to
read and write groups of parameters or individual parameters.
clGetDefault, clGetMinMax, and clGetName are used to determine defaults,
ranges, and text names.
Each parameter is classified as one of the following types. Individual
algorithms may impose further restrictions on parameter values in
addition to those implied by the parameter type.
CL_ENUM_VALUE only certain constant values are valid
CL_RANGE_VALUE any value in a given range is valid
CL_FLOATING_ENUM_VALUE only certain constant floating point values
are valid
CL_FLOATING_RANGE_VALUE any value in a given floating point range
is valid
Below is the list of basic parameters common to all processing objects,
identified by paramID. Note that not all parameters are useful for all
schemes (e.g. image dimensions are ignored by audio compressors). Also,
some parameters are designated read-only, indicating that they should not
be set.
Page 10
CLintro(3dm) CLintro(3dm)
CL_IMAGE_WIDTH, CL_IMAGE_HEIGHT
Type: CL_RANGE_VALUE
Horizontal and vertical dimensions of uncompressed image. For
compressors, these should be set to match the input dimensions.
For most decompressors, this is a read-only parameter. For
decompressors that support scaling (CL_JPEG_COSMO), this may be
set to configure the output dimensions.
CL_INTERNAL_IMAGE_WIDTH, CL_INTERNAL_IMAGE_HEIGHT
Type: CL_RANGE_VALUE
Horizontal and vertical dimensions of the encoded image.
For most compressors, these default to CL_IMAGE_WIDTH and
CL_IMAGE_HEIGHT. For compressors that support scaling
(CL_MPEG1_VIDEO_SOFTWARE, CL_JPEG_COSMO), setting different
values causes the input image to be scaled to the internal
dimensions prior to compression. For decompressors, these
parameters are read-only.
CL_IMAGE_CROP_LEFT, CL_IMAGE_CROP_RIGHT,
CL_IMAGE_CROP_TOP, CL_IMAGE_CROP_BOTTOM
Type: CL_RANGE_VALUE
Cropping parameters. For compressors that support cropping
(CL_MPEG1_VIDEO_SOFTWARE), these may be set to indicate how many
pixels should be cropped from the left, right, top, and bottom
borders of the input image. If combined with scaling, the order
of operations is input->crop->scale->compress.
CL_FORMAT [Toc] [Back]
Type: CL_RANGE_VALUE
Format of the uncompressed data (e.g. CL_FORMAT_YCbCr or
CL_FORMAT_MONO). For compressors, this should be set to match
the input format. For video decompressors, this may be set to
indicate the desired output format. For audio decompressors, this
is a read-only parameter. Currently, the format is restricted to
CL_FORMAT_XBGR for CL_JPEG_COSMO and CL_MVC2_SOFTWARE.
CL_INTERNAL_FORMAT [Toc] [Back]
Type: CL_RANGE_VALUE
Internal format used by video schemes. If this is different from
CL_FORMAT, color space conversion is performed from CL_FORMAT to
CL_INTERNAL_FORMAT on compression, and vice versa for decompression.
For compressors, the following internal formats may be set.
Scheme Internal Formats
------ ----------------
CL_MPEG1_VIDEO_SOFTWARE CL_FORMAT_YCbCr422DC
CL_JPEG_SOFTWARE CL_FORMAT_YCbCr, CL_FORMAT_YCbCr422,
CL_FORMAT_GRAYSCALE
CL_JPEG_COSMO CL_FORMAT_YCbCr422
CL_MVC1_SOFTWARE CL_FORMAT_XBGR, CL_FORMAT_GRAYSCALE
CL_MVC2_SOFTWARE CL_FORMAT_XBGR
CL_MVC3_SOFTWARE CL_FORMAT_YCbCr, CL_FORMAT_YCbCr422,
Page 11
CLintro(3dm) CLintro(3dm)
CL_FORMAT_YCbCr422DC, CL_FORMAT_GRAYSCALE
CL_RLE_SOFTWARE CL_FORMAT_BGR332
CL_RLE24_SOFTWARE CL_FORMAT_XBGR
For decompressors, this is a read-only parameter.
CL_COMPONENTS [Toc] [Back]
Type: CL_RANGE_VALUE
The number of components in the format, e.g. 1 for CL_FORMAT_MONO,
2 for CL_FORMAT_STEREO_INTERLEAVED, 4 for CL_FORMAT_ABGR. This is
a read-only parameter determined from CL_FORMAT.
CL_BITS_PER_COMPONENT [Toc] [Back]
Type: CL_RANGE_VALUE
For audio compressors, this may be set to indicate the input sample
width (8 or 16 bits); G711 u-law and A-law accept only 16 bit inputs.
For audio decompressors, this is a read-only parameter which gives
the output sample width.
CL_FRAME_RATE [Toc] [Back]
Type: CL_FLOATING_RANGE_VALUE
The frames per second of video or audio. For compressors that use
this information (MPEG-1 Video and Audio), this should be set to
match the frame rate of the input. For decompressors, this is a
read-only parameter.
CL_ORIENTATION [Toc] [Back]
Type: CL_ENUM_VALUE
Image orientation, either CL_TOP_DOWN or CL_BOTTOM_UP. For video
compressors, this should be set to match the input images. For
video decompressors, this may be set to indicate the desired
output orientation. CL_JPEG_COSMO supports only CL_TOP_DOWN.
CL_PIXEL_ASPECT [Toc] [Back]
Type: CL_FLOATING_RANGE_VALUE
Pixel aspect ratio, defined as the vertical extent of a pixel divided
by its horizontal extent. For video compressors, this should be set
to indicate the aspect ratio of the input pixels. For video
decompressors, this is a read-only parameter.
CL_COMPRESSION_RATIO [Toc] [Back]
Type: CL_FLOATING_RANGE_VALUE
The target compression ratio, including effects of cropping and
scaling. For compressors, this parameter may be set to indicate
the degree of compression desired.
CL_EXACT_COMPRESSION_RATIO [Toc] [Back]
Type: CL_RANGE_VALUE
A read-only flag which indicates whether a compressor is able to
achieve compression ratio targets. If this flag is TRUE, the average
compression ratio over many frames should be very close to the
value of CL_COMPRESSION_RATIO. If this flag is FALSE, then setting
Page 12
CLintro(3dm) CLintro(3dm)
the target ratio may have little effect on the actual ratio achieved.
CL_BITRATE [Toc] [Back]
Type : CL_RANGE_VALUE
The rate of the sequence in bits per second. This may be set on
compression to select a target bitrate. On decompression, this
is a read-only parameter. Currently supported by
CL_MPEG1_VIDEO_SOFTWARE, CL_MPEG1_AUDIO_SOFTWARE, and (Cosmo) JPEG.
CL_FRAMES_PER_CHUNK [Toc] [Back]
Type: CL_RANGE_VALUE
A read-only parameter which gives the number of frames in a "chunk".
clCompress and clDecompress should be called with numberOfFrames
equal to an integer multiple of CL_FRAMES_PER_CHUNK. For most
schemes, CL_FRAMES_PER_CHUNK is 1, so this is not a significant
restriction. For MPEG-1 Audio, this parameter is either 384 or
1152.
CL_FRAME_SIZE [Toc] [Back]
Type: CL_RANGE_VALUE
A read-only parameter which equals the number of bytes in one
frame of uncompressed data. This value is calculated based on
CL_FORMAT, CL_IMAGE_WIDTH, CL_IMAGE_HEIGHT, CL_COMPONENTS and
CL_BITS_PER_COMPONENT. A frame is defined as the data corresponding
to a single time instant. One video frame consists of width*height
pixels. One audio frame consists of 1 mono sample or 2 stereo
samples.
CL_COMPRESSED_BUFFER_SIZE [Toc] [Back]
Type: CL_RANGE_VALUE
A read-only parameter which gives the maximum number of bytes
generated by compressing CL_FRAMES_PER_CHUNK frames. The value
may depend on other parameters such as CL_IMAGE_WIDTH and
CL_IMAGE_HEIGHT. This parameter should be used to allocate enough
space for a compressor's output buffer and a decompressor's input
buffer so that clCompress and clDecompress do not block.
CL_FRAME_TYPE [Toc] [Back]
Type: CL_RANGE_VALUE
A read-only parameter for decompressors which indicates the
type of frame most recently decoded. May be CL_INTRA (same
as CL_KEYFRAME), CL_PREDICTED, CL_BIDIRECTIONAL, or CL_NONE.
CL_FRAME_INDEX [Toc] [Back]
Type: CL_RANGE_VALUE
A read-only parameter for decompressors which indicates the
index of the frame most recently decoded.
CL_NUMBER_OF_FRAMES [Toc] [Back]
Type: CL_RANGE_VALUE
The number of frames in the video or audio sequence. For
compressors, this should be set (if known) since some schemes
Page 13
CLintro(3dm) CLintro(3dm)
include this data in the header. For decompressors, this parameter
is read-only and is available after calling clReadHeader; the value
may be zero if the number of frames is not listed in the header.
CL_SPEED [Toc] [Back]
Type: CL_FLOATING_RANGE_VALUE
The relative speed of playback. For decompressors that support
variable rate decoding, this parameter may be set to adjust playback
speed. Ranges are scheme-specific but, in general, 1.0 is the
default and higher values correspond to faster decoding (at the
expense of some quality loss).
CL_PREROLL [Toc] [Back]
Type: CL_RANGE_VALUE
A read-only parameter which gives the number of chunks of frames
that must be decompressed before valid frames are returned.
Currently not used.
CL_ENABLE_IMAGEINFO [Toc] [Back]
Type: CL_RANGE_VALUE
This parameter is used to enable the clGetNextImageInfo call
for video compressors or decompressors. To enable the call,
CL_ENABLE_IMAGEINFO should be set to TRUE before invoking
clCompress or clDecompress. This is currently supported for
CL_JPEG_COSMO.
CL_ALGORITHM_ID [Toc] [Back]
Type: CL_RANGE_VALUE
The algorithm identifier (e.g. CL_MPEG1_VIDEO_SOFTWARE). This is
a read-only parameter for all processing objects.
CL_ALGORITHM_VERSION [Toc] [Back]
Type: CL_RANGE_VALUE
The algorithm version number. This is a read-only parameter for
all processing objects.
Note that some parameters, such as CL_COMPRESSED_BUFFER_SIZE, depend on
other parameters and should not be read until other parameters are set.
For decompressors, parameters are generally valid after clReadHeader is
called.
Some algorithms and products have additional parameters which extend this
basic set. See cl_mpeg1(3dm), cl_jpeg(3dm), cl_mvc2(3dm), and
cl_mvc3(3dm) for algorithm-specific parameters. See cl_cosmo(3dm) and
cl_aware(3dm) for product-specific parameters.
API FOR ADDING ALGORITHMS AND PARAMETERS [Toc] [Back]
int clAddAlgorithm(char *name, int algType, int maxHeaderSize,
FunctionPtr openCompressor, FunctionPtr compress,
FunctionPtr closeCompressor,
Page 14
CLintro(3dm) CLintro(3dm)
FunctionPtr openDecompressor, FunctionPtr decompress,
FunctionPtr closeDecompressor,
FunctionPtr readHeader, FunctionPtr queryScheme,
FunctionPtr queryLicense,
FunctionPtr getParams, FunctionPtr setParams,
int *scheme)
void *clSetUnique(CLhandle handle, void *unique)
void *clGetUnique(CLhandle handle)
int clFetchParam(CLhandle handle, int paramID)
void clStoreParam(CLhandle handle, int paramID, int value)
void clError(CLhandle handle, int code, const char *format, ...)
int clAddParam(int scheme, char *name, int paramType,
int min, int max, int initial, int *paramID)
int clSetDefault(int scheme, int paramID, int initial)
int clSetMin(int scheme, int paramID, int min)
int clSetMax(int scheme, int paramID, int max)
int clSetMinMax(int scheme, int paramID, int min, int max)
int clSetRange(int scheme, int paramID, int min, int max, int initial)
These calls support the addition of custom algorithms and parameters to
the library.
clAddAlgorithm installs a new codec given the functions that implement
it. clSetUnique and clGetUnique allow the codec implementation to save
and retrieve a private data structure with each codec object, enabling
unique state information to be retained across processing calls.
clFetchParam and clStoreParam are used by the codec implementation to
directly access parameters in the handle. (Users of the codec, however,
should call the standard routines clGetParam and clSetParam.) clError is
the active error handler function, and may be used by the codec
implementation to report errors.
clAddParam is used to extend the basic parameter list for new codecs.
clSetDefault, clSetMin, clSetMax, clSetMinMax, and clSetRange are used to
configure a parameter after it is added.
Once installed with these calls, new algorithms and their parameters may
be accessed with the same API used for the base schemes.
API FOR OTHER FEATURES [Toc] [Back]
int clCompressImage(int scheme, int width, int height,
int format, float compressionRatio, void *frameBuffer,
int *compressedBufferSize, void *compressedBuffer)
int clDecompressImage(int scheme, int width, int height,
int format, int compressedBufferSize,
void *compressedBuffer, void *frameBuffer)
int clQueryAlgorithms(int algType, int *buffer, int bufferLength)
Page 15
CLintro(3dm) CLintro(3dm)
int clQuerySchemeFromHandle(CLhandle handle)
int clQuerySchemeFromName(int algType, const char *name)
char *clGetAlgorithmName(int scheme)
int clQueryLicense(int scheme, int functionality, char **message)
int clQueryScheme(void *header)
int clQueryMaxHeaderSize(int scheme)
int clReadHeader(CLhandle handle, int headerSize, void *header)
int clGetNextImageInfo(CLhandle handle,
CLimageInfo *imageInfo, int sizeOfImageInfo)
CLerrFunc clSetErrorHandler(CLerrFunc efunc) [Toc] [Back]
clCompressImage and clDecompressImage provide a simple way to process
individual video frames in one call; the application does not need to
open and close a compressor or decompressor. Note, however, that these
calls do not save state between invocations so algorithms that have
dependencies between frames (e.g. MPEG-1 Video) should not be used.
Also, these calls do not allow general parameter modification and are not
compatible with implicit buffers.
clQueryAlgorithms gives a list of algorithms recognized by the library.
clQuerySchemeFromHandle and clQuerySchemeFromName return the scheme
identifier from the handle and text name, respectively;
clGetAlgorithmName returns the text name from the scheme. Some schemes
must be enabled with a NetLS license (see the section on option
products); clQueryLicense is used to determine whether a license is
available.
Applications which need to read data generated by several algorithms may
use clQueryScheme to determine the appropriate decompressor to use. This
call attempts to identify the algorithm based on the first 16 bytes of
data so that the correct processing object may be opened. Once opened,
the decompressor should be configured by reading the header with
clQueryMaxHeaderSize and clReadHeader.
clGetNextImageInfo is used to obtain information about images as they are
compressed or decompressed. This call is currently supported by the
CL_JPEG_COSMO scheme, and provides information such as time stamps and
image counts.
clSetErrorHandler allows an application to override the default error
handler. The default function prints a message to stderr.
Some schemes must be enabled with the installation of separate option
products.
Page 16
CLintro(3dm) CLintro(3dm)
MPEG Encoder
This product includes the CL_MPEG1_VIDEO_SOFTWARE and
CL_MPEG1_AUDIO_SOFTWARE compressors. The audio compressor may also
enabled by a license from Aware, Inc. (see below).
Cosmo Compress [Toc] [Back]
This hardware product enables the CL_JPEG_COSMO scheme, which offers
accelerated JPEG compression and decompression for realtime video capture
and playback. Cosmo is supported on Indy and Indigo2 systems.
Aware AudioPublisher, AudioProducer, and AudioPlayback
These products provide various levels of NetLS licenses for MPEG-1 Audio
(CL_MPEG1_AUDIO_SOFTWARE, CL_MPEG1_AUDIO_AWARE) and Aware Multirate
(CL_MULTIRATE_AWARE).
For more details see cl_aware(3dm) and cl_mpeg1(3dm).
/usr/include/dmedia/cl.h - header file
(including error codes)
/usr/share/src/dmedia/dmrecord - sample code
/usr/share/src/dmedia/dmplay - sample code
clOpenCompressor(3dm), clCompress(3dm), clCloseCompressor(3dm),
clOpenDecompressor(3dm), clDecompress(3dm), clCloseDecompressor(3dm),
clCreateBuf(3dm), clDestroyBuf(3dm),
clQueryBufferHdl(3dm), clQueryHandle(3dm),
clQueryFree(3dm), clUpdateHead(3dm), clQueryVaild(3dm),
clUpdateTail(3dm), clDoneUpdatingHead(3dm),
clQueryParams(3dm), clGetParamID(3dm),
clGetParams(3dm), clSetParams(3dm),
clGetDefault(3dm), clGetMinMax(3dm), clGetName(3dm),
clAddAlgorithm(3dm), clSetUnique(3dm), clGetUnique(3dm),
clFetchParam(3dm), clStoreParam(3dm), clError(3dm),
clAddParam(3dm), clSetDefault(3dm), clSetMin(3dm), clSetMax(3dm),
clSetMinMax(3dm), clSetRange(3dm),
clCompressImage(3dm), clDecompressImage(3dm),
clQueryAlgorithms(3dm), clQuerySchemeFromHandle(3dm),
clQuerySchemeFromName(3dm), clGetAlgorithmName(3dm), clQueryLicense(3dm),
clQueryScheme(3dm), clQueryMaxHeaderSize(3dm), clReadHeader(3dm),
clGetNextImageInfo(3dm), clSetErrorHandler(3dm),
mpeg(4), jpeg(4),
cl_mpeg1(3dm), cl_jpeg(3dm), cl_mvc2(3dm), cl_mvc3(3dm),
cl_cosmo(3dm), cl_aware(3dm),
dmconvert(1), dmrecord(1), dmplay(1)
PPPPaaaaggggeeee 11117777 [ Back ]
|
