This chapter describes how to use the algorithms that are supplied with libcl. To use one of these algorithms, you need to select an appropriate algorithm for your application and specify it in the compress or decompress routines.
In this chapter:
“Choosing a Compression Library Algorithm” gives factors for selecting an algorithm for specific types of applications.
“Querying Compression Library Algorithms” tells how to get a list of available algorithms, the name and type of the algorithm, and licensing information for it.
“Controlling JPEG Compressed Image Quality” explains controls for optimizing the JPEG compression algorithm.
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 might affect the end result and whether a particular algorithm achieves 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 quoted is for Indigo® workstations with 33 MHz MIPS® R3000® processors only. Corresponding capabilities for the OCTANE workstation have not yet been measured, but are expected to surpass these statistics generally.|
multimedia information delivery applications
MPEG gives the best video quality for a given data size or rate, but playback speed is limited by the CPU. MVC1 is usually the best choice if MPEG is not fast enough. If an expensive frame-by-frame VCR is not available, recording in real time to disk is important, which can be done with RTR1.
The key factors to consider when choosing a video compression algorithm for video/voice mail, video teleconferencing, and other telecommunications applications are the combined compression-decompression speed, data size/rate, and to a lesser extent, quality.
The key factors when choosing a video compression algorithm for previewing 2D and 3D animations are playback speed, quality, and, to a lesser extent, data size/rate. MVC1 gives the appropriate speed and quality.
The key factors to consider when choosing a video compression algorithm for movie editing applications are decompression speed, image quality, data size/rate, and compression speed.
For motion video applications, MVC1 is the best choice, especially when the playback is provided by the MoviePlayer tool. MVC1 provides rapid decompression. Playback speed can be traded off with image quality. When recording from video hardware to disk, recording in real time to disk is important if a frame-by-frame VCR is not available—leading to the use of RTR1.
Table 7-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 33 Mhz MIPS R3000 processors only.
[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.
|Note: The corresponding capabilities for OCTANE workstation have not yet been measured, but are expected to surpass these statistics generally.|
This section explains how you can get a list of available algorithms for a 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 )
The returned types take on one of three values:
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)
is a handle to a compressor or a decompressor
is the algorithm name
is the algorithm scheme
Example 7-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(), and then malloc() is used to allocate enough buffer space to store the returned list of video 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)
is the algorithm scheme.
is the type of algorithm, which can be one of:
is a pointer to a returned pointer to a character string containing a message.
JPEG is a tunable algorithm—you can trade quality for compression ratio and vice versa. You can specify a hint (CL_COMPRESSION_RATIO) for an approximate compression ratio, or you can set more explicit quality factors or target bit rates, as described in this section.
The source image is compressed in three basic steps.
The process is reversed for decompression.
The quantization step controls the trade-off between image quality and size. The JPEG quantization table is used to scale each of the 64 DCT coefficients. The luminance (Y) and the chrominance (Cr and Cb) components each use a separate table.
The CL provides three methods for controlling image quality from these quantization tables. You can
specify an overall JPEG quality factor (CL_JPEG_QUALITY_FACTOR) for scaling the default JPEG quantization tables
manually set the quantization tables using CL_JPEG_QUANTIZATION_TABLES
specify a target bit rate that you would like the compressed data to approximate
The JPEG algorithm does not allow you to specify exact compression ratios, but the hardware implementation of JPEG used in OCTANE Compression supports the concept of a target bit rate. Specifying CL_BITRATE causes the hardware to create a new quantization table as each field is compressed. If the current field were compressed again, this quantization table would yield the exact target bit rate. Since this bit rate would reduce the maximum capture rate, the CL applies the new quantization table to the next field, since adjacent fields usually have similar compressibility.
You can use the CL_JPEG_QUALITY_FACTOR parameter to specify a JPEG quantization table scale factor that represents a rough percentage of the image detail preservation. This is one method to control the image loss and therefore the compression ratio for the OCTANE Compression JPEG algorithm.
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:
scalefactor = 50/quality (quality < 50) scalefactor = 2 - 2*quality/100; (otherwise)
The default quality is CL_JPEG_QUALITY_DEFAULT, which represents a good-quality compressed image. A quality factor of 1 results in coarse quantization, a high compression ratio, and very poor image quality.
A quality factor 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.
To bypass scaling, specify CL_JPEG_QUALITY_NO_SCALE.
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.
You can customize the JPEG quantization tables by using the CL_JPEG_QUANTIZATION_TABLES parameter. To set the tables, specify an unsigned short *qtables argument. For each j, qtables[j] must either be NULL or point to a unsigned short area of memory that represents a JPEG-baseline quantization table in natural scanning order. These custom tables are stored as reference tables; then scaled versions of them based on the current CL_JPEG_QUALITY_FACTOR are downloaded into the codec, becoming the tables associated with the ID j.
When getting the value of CL_JPEG_QUANTIZATION_TABLES, the CL allocates the required memory and returns the currently used tables, as indicated by CL_JPEG_COMPONENT_TABLES, scaled by the value of CL_JPEG_QUALITY_FACTOR. Your application is responsible for freeing the memory allocated to return these tables.
You can specify the quantization tables on a per-component basis, by using the CL_JPEG_COMPONENT_TABLES parameter. It specifies the IDs of the AC Huffman table, DC Huffman table, and quantization table to be used for each component. You cannot change this parameter for OCTANE Compression; it is set up for YUV422 processing. This setting uses 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.
You can specify a target bit rate for the compressed data stream. The bit rate is the number of bits per second.
bitrate = (image_height * image_width * components_per_pixel * fields_per_second * 8) / compression_ratio;
Useful values for bit rate for NTSC video range from 15,000,000 (2:1 compression) to 3,000,000 (100:1).