This chapter describes how to use the Compression Library algorithms and parameters.
In this chapter:
“Using the Compression Library Algorithms” describes the algorithms available in the CL and explains how to use them.
“Using the Compression Library Parameters” describes the CL global parameters and explains how to use them.
This section describes how to use the algorithms that are supplied with libcl. See Chapter 26, “Customizing the Compression Library,” for information on adding and using your own algorithms.
To use one of the algorithms supplied with libcl, you need to select an appropriate algorithm for your application and specify it in the compress or decompress routines.
Perhaps the most important aspect of developing an application that uses libcl is selecting the appropriate algorithm to use for the application. The algorithm affects the data size and quality and the rate of compression and decompression, so it is important to consider how an algorithm will affect the end result and to consider whether a particular algorithm will achieve the desired effect. A certain amount of experimentation may be necessary.
If you are interested in a particular quality level, you need to set the compression ratio to achieve that quality; if you are primarily interested in a particular data size or data rate, you need to set the compression ratio to achieve the desired data size or rate.
Here are some suggestions for typical application categories:
 | Note: The performance is quoted for Indigo workstations with 33Mhz MIPS® R3000® processors only. |
Algorithms for Multimedia Information Delivery Applications
Algorithms for Telecommunications Applications
Algorithms for Previewing Animations
Algorithms for Editing Movies
Table 25-1 summarizes the compression and performance relationships of the image and motion video algorithms. Compression, decompression, and codec performance measurements are in frames per second (FPS), as measured for 320 by 240 frames on Indigo workstations with 33Mhz MIPS R3000 processors only.
Table 25-1. Capabilities of Image and Video Algorithms
| Typical | Average | Bits per | Bytes |
|
|
|
|---|---|---|---|---|---|---|---|
Uncompresse d | 1:1 | 24 | 27.65Mb | 230.4KB |
|
|
|
RLE 8 bit | 4.8:1 | 5 | 5.76Mb | 48KB | 6 FPS | 11.5 FPS | 3.9 FPS |
MVC1 | 5.33:1 | 4.5 | 5.2Mb | 43.2KB | 3 FPS | 25 FPS | 2.8 FPS |
MVC1 | 8:1 | 3 | 3.456Mb | 28.8KB | 7 FPS | 28 FPS | 5.6 FPS |
RTR1 | 6:1 | 4 | 4.608Mb | 38.4KB | NYM[b] | 2.5 FPS | 2.0 FPS |
RTR1 | 9:1 | 2.67 | 3.072Mb | 25.6KB | NYM | 8 FPS | NYM |
JPEG | 16:1 | 1.5 | 1.728Mb | 14.4KB | 1.1 FPS | 1.8 FPS | 0.7 FPS |
MPEG | 48:1 | 0.5 | 0.576Mb | 4.8KB | << 1 FPS | 4.75 FPS | <<1 FPS |
[a] Decompressed frame per second is the measured performance, including reading the data from disk, decompressing it, and writing it to the screen. [b] NYM—Not Yet Measured. | |||||||
This section explains how you can get a list of available algorithms for an audio or video compressor or decompressor, along with the name and type of algorithm, or find the identifier for an algorithm given its name. Other features of the algorithms can also be queried by the application at run time. Querying algorithms, rather than having hard-coded setups, makes it possible to have an algorithm-independent interface, which lets you take advantage of future algorithms as they are implemented without redesigning your code.
Use clQueryAlgorithms() to get a list of algorithms for the compressor or decompressor identified by handle. clQueryAlgorithms() returns the size of the buffer needed to contain the list of algorithms and their types.
If the size of the algorithmTypeBuffer is smaller than the returned value, a partial list of the algorithms and their types is returned, and you must enlarge the algorithmTypeBuffer in order to receive a complete list.
The function prototype for clQueryAlgorithms() is:
int clQueryAlgorithms ( int algorithmMediaType,
int *algorithmTypebuffer, int bufferLength )
|
where:
| algorithmMediaType |
| |||||
| algorithmTypeBuffer |
| |||||
| bufferLength | is the length of the buffer, in ints, pointed to by paramValueBuffer. If bufferLength is zero, then paramValueBuffer is ignored and only the return value is valid. |
Use clQuerySchemeFromHandle() or clQuerySchemeFromName() to return the algorithm scheme identifier used by the other compression functions. Use clGetAlgorithmName() to return the algorithm name. Their function prototypes are:
int clQuerySchemeFromHandle(CLhandle handle) int clQuerySchemeFromName(int algorithmMediaType, char *name) char *clGetAlgorithmName(int scheme) |
where:
| handle | is a handle to a compressor or a decompressor | |
| algorithmMediaType |
| |
| name | is the algorithm name | |
| scheme | is the algorithm scheme |
Example 25-1 demonstrates how to query the CL for a list of algorithms—in this case, video algorithms. The necessary buffer size is returned in the first call to clQueryAlgorithms(), then malloc() is used to allocate enough buffer space to store the returned list of video algorithms.
Example 25-1. Getting a List of Compression Library Algorithms
#include <dmedia/cl.h> #include <malloc.h> int *buffer, bufferLength; char *name; /* * Get a buffer containing all the video algorithms and types */ bufferLength = clQueryAlgorithms(CL_VIDEO, NULL, 0); buffer = (int *)malloc(bufferLength * sizeof(int)); clQueryAlgorithms(CL_VIDEO, buffer, bufferLength); scheme = clQuerySchemeFromName(handle); name = clGetAlgorithmName(scheme); |
Use clQueryLicense() to obtain license information about an algorithm. The returned message is text intended for inclusion in a message box that is displayed for a user, explaining how to license an algorithm. Failure returns the license error code.
The function prototype is:
int clQueryLicense ( int scheme, int functionality,
char **message)
|
where:
| scheme | is the algorithm scheme. | |
| functionality | is the type of algorithm, which can be one of:
| |
| message | is a pointer to a returned pointer to a character string containing a message. |
The CL has a group of routines for working with a set of state variables called “parameters” that are unique for each instantiation. These routines are similar to a set of routines in the audio library. You can get and set parameters, either individually or as a group; however, all of the parameters have reasonable defaults that are algorithm-dependent and need not be set.
The Compression Library works with data that is contained in frames. A frame is defined as a sample in time so that:
| 1 audio sample: | mono 8 bit = 1 byte | |
| 1 video frame: | width * height * components * bitsPerComponent/8 = n bytes |
Parameters provide state information about frame characteristics, data formats, and algorithms for each compressor/decompressor.
These parameters provide information about image frame dimensions:
| CL_IMAGE_WIDTH |
| |
| CL_IMAGE_HEIGHT |
|
These parameters describe data formats:
| CL_ORIGINAL_FORMAT |
Video values are: CL_RGB, CL_RGBX (default), CL_RGBA, CL_RGB332, CL_GRAYSCALE, CL_YUV, CL_YUV422, or CL_YUV422DC. Audio values are: CL_MONO or CL_STEREO_INTERLEAVED (default). | |
| CL_INTERNAL_FORMAT |
| |
| CL_COMPONENTS |
| |
| CL_BITS_PER_COMPONENT |
| |
| CL_ORIENTATION |
The orientation of compressed data is always top down. When specifying compression or decompression, the original format (or final format) of the data may be bottom up. Specify this inversion by setting the CL_ORIENTATION parameter to CL_BOTTOM_UP instead of the default. |
These parameters describe buffer sizes and characteristics:
| CL_FRAME_BUFFER_SIZE |
| |||||||||
| CL_COMPRESSED_BUFFER_SIZE |
| |||||||||
| CL_NUMBER_OF_FRAMES |
| |||||||||
| CL_BLOCK_SIZE |
| |||||||||
| CL_PREROLL |
| |||||||||
| CL_FRAME_RATE |
| |||||||||
| CL_FRAME_TYPE |
| |||||||||
| CL_ACTUAL_FRAME_INDEX |
|
These parameters control the compression ratio and/or quality:
| CL_ALGORITHM_ID |
| |
| CL_COMPRESSION_RATIO |
| |
| CL_EXACT_COMPRESSION_RATIO |
| |
| CL_SPEED | The relative speed of playback. A value of 1.0 for this single-precision floating point value means no change. When this value is greater than 1.0, the algorithm tries to use less CPU time by dropping frames or by reducing the quality. |
JPEG has the following additional parameters:
| CL_JPEG_COMPONENT_TABLES |
YUV formats use AC huffman table 0, DC huffman table 0, and quantization table 0 for component 0; AC huffman table 1, DC huffman table 1, and quantization table 1 for components 1 and 2. RGB formats use tables AC table 0, DC table 0, and quantization table 0 for all components. | ||
| CL_JPEG_QUANTIZATION_TABLES |
| ||
| CL_JPEG_QUALITY_FACTOR |
Each time the quality factor is set, the reference quantization tables are scaled and downloaded into the codec. The formula used to obtain the scale factor is:
Using a value of 1 results in coarse quantization, a high compression ratio, and very poor image quality. Using a value of 100 results in the finest possible quantization, a low compression ratio (perhaps even image expansion), and near-perfect image quality. The most useful quality factor is typically in the range of 25–95. The default quality is CL_JPEG_QUALITY_DEFAULT, which represents a good-quality compressed image. Use the value CL_JPEG_QUALITY_NO_SCALE to bypass scaling. When CL_QUALITY_FACTOR is set, the approximate value of CL_COMPRESSION_RATIO is calculated; when CL_COMPRESSION_RATIO is set, the approximate value of CL_QUALITY_FACTOR is calculated. When decompressing JPEG, clDecompress() fills in this value. The actual compression ratio is determined by the quality factor and the image content and therefore may not be exactly what you expect. |
MPEG_VIDEO has the following additional parameters:
| CL_END_OF_SEQUENCE |
|
RTR has the following additional parameters:
| CL_QUALITY_LEVEL |
|
Table 25-2 lists the parameters and their types, ranges, and defaults.
Table 25-2. Compression Library Parameters
Parameter | Range | Default |
|---|---|---|
CL_ALGORITHM_ID | Current ID | Current ID |
CL_ALGORITHM_VERSION | Current version | Current version |
CL_BITS_PER_COMPONENT | 0–32 | Audio: 16 Video: 8 |
CL_BLOCK_SIZE | 0–2 Billion | 1, depends on algorithm |
CL_COMPONENTS (read only) | 0–8 | Depends on original format |
CL_COMPRESSED_BUFFER_SIZE | 0–2 Billion | Maximum amount of compressed data needed for one frame |
CL_COMPRESSION_RATIO | Depends on original format and algorithm | Uncompressed 1.0:1 μ-law 2.0:1 A-law 2.0:1 Aware MultiRate I 2–4:1 Aware MPEG 2–4:1 MVC1 5.3:1 JPEG 15.0:1 MPEG Video 48.0:1 RLE 1.0:1 RLE24 1.5:1 RTR 5.0:1 |
CL_ENABLE_IMAGEINFO |
|
|
CL_END_OF_SEQUENCE | 0 (FALSE)–1 (TRUE) | 0 (FALSE) |
CL_EXACT_COMPRESSION_RATIO | 0 (FALSE)– 1 (TRUE) | Audio: 0 (FALSE) Video: 0 (FALSE) |
CL_FRAME_BUFFER_SIZE | 0–2 Billion | Size of one frame |
CL_FRAME_RATE | 0–1 Million | Audio: 44100.0 Video: 30.0 |
CL_FRAME_TYPE | 0–2 | Supplied by decompressor |
CL_IMAGE_HEIGHT | 0–1Million | Audio: 1 Video: 320 |
CL_IMAGE_WIDTH | 0–1Million | Audio: 1 Video: 240 |
CL_INTERNAL_FORMAT | 0–max[a] | Audio: CL_STEREO_INTERLEAVED Video: depends on algorithm |
CL_INTERNAL_IMAGE_HEIGHT |
|
|
CL_INTERNAL_IMAGE_WIDTH |
|
|
CL_JPEG NUM_PARAMS (JPEG only) | 0–2 Billion | 0 (unknown) |
CL_JPEG_QUALITY_FACTOR | 0–100 | 75 |
CL_JPEG_QUANTIZATION_TABLES |
|
|
CL_LAST_FRAME_INDEX | 0–2 Billion | 0 |
CL_NUMBER_OF_FRAMES |
|
|
CL_NUMBER_OF_PARAMS |
|
|
CL_ORIENTATION | CL_TOP_DOWN to CL_BOTTOM_UP | CL_TOP_DOWN |
CL_ORIGINAL_FORMAT | 0–max[b] | Audio: CL_STEREO_INTERLEAVED Video: CL_RGBX |
CL_PREROLL | 0–2Billion | 0, depends on algorithm |
CL_RTR_QUALITY_LEVEL (RTR only) | 1–6 | 1 |
CL_SPEED | 0 (stopped) to 2 Billion, depends on algorithm | 1.0 (real-time playback) |
[a] max = CL_MAX_NUMBER_OF_ORIGINAL_FORMATS. [b] max = Enumerated type value that depends on the format. | ||
After a compressor or decompressor is opened, thus specifying the compression scheme to use, various parameters can be modified using clSetParams(). All of these parameters have reasonable defaults that are algorithm-dependent and need not be set. Some parameters, such as CL_IMAGE_WIDTH and CL_IMAGE_HEIGHT for video compression, should be set, but setting them is not required.
Use clQueryParams() to get a list of valid parameters and their types for a specified a compressor or decompressor. The compressor being queried is identified by its handle. Its function prototype is:
int clQueryParams(CLhandle handle,int *paramValuebuffer, int maxLength) |
where:
| handle | is the handle to a compressor or decompressor. | |
| paramValuebuffer |
| |
| maxLength | is the length of the buffer, in ints, pointed to by paramValuebuffer. If maxLength is zero, then paramValuebuffer is ignored and only the return value is valid. |
clQueryParams() returns the size of the buffer, in ints, needed to hold all the parameter identifier/parameter type pairs for the compressor or decompressor identified by handle. The parameters are returned in the even locations of paramValuebuffer, and their types are returned in the odd locations.
If the size of the paramValuebuffer is smaller than the returned value, a partial list of the parameter identifier/parameter type pairs is returned, making it necessary to enlarge the paramValuebuffer in order to receive a complete list. To avoid this situation, you can obtain the correct size of the buffer by calling clQueryParams() with a NULL buffer pointer and a maxLength of 0 to return the actual buffer length without writing any data.
clQueryParams() also reports whether the parameter is one of a set of enumerated types, any integer number within a specific range, or any floating point number within a specific range. In each case, the values are numbers within the range returned by clGetMinMax() and have the defaults returned by clGetDefault().
Example 25-2 demonstrates how to get a list of parameters for a specified compressor/decompressor.
Example 25-2. Getting a List of Parameters for a Compressor/Decompressor
#include <dmedia/cl.h> #include <malloc.h> /* * Get a buffer containing all the parameters for a specified * compressor or decompressor. */ int *buf, bufferLength; bufferLength = clQueryParams(handle, 0, 0); buf = (int *)malloc(bufferLength * sizeof(int)); clQueryParams(handle, buf, bufferLength); |
If you know the name of a parameter, but not its identifier, you can use clGetParamID() to get the identifier of a parameter from its name.
Its function prototype is:
int clGetParamID(CLhandle handle, char *name) |
You can get or set parameter values as a group or individually.
Use clGetParams() to return the current values for the parameters referenced in the paramValuebuffer array. The values are written into the odd locations of paramValuebuffer immediately after the corresponding parameters.
Use clSetParams() to set the current state of the parameters referenced in the paramValuebuffer array.
To change a state parameter:
Call clQueryParams() to find out which parameters are available.
Call clGetParams() to find out the current state.
Fill in the even entries of the paramValuebuffer array corresponding to the parameters to be changed and then call clSetParams().
The function prototypes are:
void clGetParams ( CLhandle handle, int *paramValuebuffer,
int bufferLength )
void clSetParams ( CLhandle handle, int *paramValuebuffer,
int bufferLength )
|
where:
| handle | is a handle that identifies a compressor or decompressor. | |
| paramValuebuffer |
| |
| bufferLength | is the number of ints in the buffer pointed to by paramValuebuffer. |
Alternatively, parameters can be changed individually with clSetParam() and clGetParam(). clGetParam() returns the current value of the parameter. clSetParam() returns the previous value of the parameter.
The function prototypes are:
int clGetParam(CLhandle handle, int paramID) int clSetParam(CLhandle handle, int paramID, int value) |
where:
| handle | is a handle that identifies a compressor or decompressor. | |
| paramID | is the identifier of the parameter to get or set. | |
| value | is the new value of the parameter. |
Example 25-3 demonstrates how to extract the current value of specific parameters from a list of parameters returned as a group. In this case, the current block size and preroll values are obtained from the list of parameters that are returned in paramValuebuffer from clGetParams().
Example 25-3. Getting the Current Values of Selected Parameters
#include <dmedia/cl.h>
...
/* Get the block size and preroll */
int paramValueBuffer[][2] = {
CL_BLOCK_SIZE, 0,
CL_PREROLL, 0
};
clGetParams(handle, (int *)paramValueBuffer,
sizeof(paramValueBuffer) / sizeof(int));
/* paramValueBuffer[0][1] is the block size */
/* paramValueBuffer[1][1] is the preroll */
|
Some parameters, such as CL_COMPRESSION_RATIO and CL_FRAME_RATE, are floating point values. You don't have to cast expressions involving floating point values, because macros are provided within libcl that handle the conversions for you; even though a value is a float you can cast to an int. To set a floating point value, use the macro CL_TypeIsInt(); to retrieve a floating point value, use the macro CL_TypeIsFloat().
The argument must be a variable, because the type definitions in /usr/include/dmedia/cl.h are:
| float | *(float *) &value | |
| int | *(int *) &value |
Example 25-4 demonstrates how to use the libcl macros to get/set a floating point parameter value.
Example 25-4. Using Macros to Get or Set the Value of a Floating Point Parameter
float number; number = 3.0; ... clSetParam(handle, CL_COMPRESSION_RATIO, CL_TypeIsInt(number)); number = CL_TypeIsFloat(clGetParam(handle,CL_COMPRESSION_RATIO)); |
You can query parameters individually to get the name, defaults, and range of valid values, given the parameter identifier and a handle.
Use clGetName() to return a pointer to a null-terminated string that supplies the English name of a parameter. Its function prototype is:
char* clGetName(CLhandle handle, int param) |
where:
| handle | is a handle that identifies a compressor or decompressor. | |
| param | is a parameter identifier. |
Use clGetDefault() to return the default value of the parameter specified by param. Use clSetDefault() to set the default value. Setting the default value is particularly useful when an algorithm has been added and new defaults need to be set.
The function prototypes are:
int clGetDefault(CLhandle handle, int param) int clSetDefault(int scheme, int paramID, int value) |
where:
| handle | is a handle that identifies a compressor or decompressor. | |
| paramID | is a parameter identifier. | |
| scheme | is the identifier of the scheme for which to set the defaults. | |
| value | is the new default value associated with param. |
Example 25-5 demonstrates how to get and set defaults for a parameter. In this case, the default for the CL_ORIGINAL_FORMAT parameter is set to CL_RGBX for the specified decompressor.
Example 25-5. Getting and Setting Parameter Defaults
#include <dmedia/cl.h> int default; ... clOpenDecompressor(scheme, &handle); ... default = clGetDefault(handle, CL_ORIGINAL_FORMAT); clSetDefault(scheme, CL_ORIGINAL_FORMAT, CL_RGBX); ... |
Use clGetMinMax() to get the maximum and minimum values for a parameter. Use clSetMin() and clSetMax() to set new minimum and maximum parameter values, or to establish the minimum and maximum values when adding a new algorithm.
The function prototypes are:
int clGetMinMax ( CLhandle handle, int param, int *minParam,
int *maxParam)
|
int clSetMin(int scheme, int paramID, int min) int clSetMax(int scheme, int paramID, int max) |
where:
| handle | is a handle that identifies a compressor or decompressor. | |
| paramID | is a parameter identifier. | |
| minParam | is a pointer to the parameter into which clGetMinMax() can write the minimum value associated with paramID. | |
| maxParam | is a pointer to the parameter into which clGetMinMax() can write the maximum value associated with paramID. | |
| scheme | is the identifier of the scheme that is to have its minimum or maximum value changed. | |
| min | is the new minimum value associated with paramID. | |
| max | is the new maximum value associated with paramID. |
Example 25-6 demonstrates how to get and set the minimum and maximum values of a particular parameter for the specified compressor or decompressor.
Example 25-6. Getting and Setting Minimum and Maximum Parameter Values
#include <dmedia/cl.h> int oldMin, oldMax; ... clOpenDecompressor(scheme, &handle); 6 ... clGetMinMax(handle, CL_ORIGINAL_FORMAT, &oldMin, &oldMax); clSetMin(scheme, CL_ORIGINAL_FORMAT, CL_RGB); clSetMax(scheme, CL_ORIGINAL_FORMAT, CL_RGB332); ... |
Some compression algorithms do not allow direct compression or decompression of an arbitrary frame. These algorithms—MPEG, CCITT H.261, and so on—have blocks of frames, where each frame can be decompressed only if all previous frames in the block have been decompressed. The frame at the beginning of the block is called a keyframe.
A frame can be queried for its status as a keyframe by using the CL_FRAME_TYPE state parameter. Legal values are CL_KEYFRAME (or CL_INTRA), CL_PREDICTED, and CL_BIDIRECTIONAL. Predicted frames use information from a previous keyframe, bidirectional frames use information from both previous and future reference frames, where a reference frame is either of the other two types—CL_KEYFRAME or CL_PREDICTED.The Compression Library interface allows keyframe control from the application.
Some algorithms contain only keyframes, such as JPEG, MVC1, RTR, RLE, G.711, and so on. MPEG Video is the only algorithm currently supported that has all three types of frames.