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

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

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)

where

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 Indigo² IMPACT 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[4] argument. For each j, qtables[j] must either be NULL or point to a unsigned short[64] 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 Indigo² IMPACT 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).