The CL_IMAGE_WIDTH and CL_IMAGE_HEIGHT parameters provide information about image frame dimensions. For more information on these parameters, see “Using OCTANE Compression Image Formats” in Chapter 4.

These parameters describe data formats:

These parameters describe buffer sizes and characteristics:

These parameters control the compression ratio and quality:

JPEG has the following additional parameters:

MPEG_VIDEO has the following additional parameter:

For a summary of parameters and their types, ranges, and defaults, see Table A-1 in Appendix A, “Video Library Controls and Compression Library Parameters for the OCTANE Compression Option.””

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

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 6-1 demonstrates how to get a list of parameters for a specified 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:

The function prototypes are:

void clGetParams ( CLhandle handle, int *paramValuebuffer,
                   int bufferLength )
void clSetParams ( CLhandle handle, int *paramValuebuffer,
                   int bufferLength )

where

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

Example 6-2 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().

#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_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

Example 6-3 demonstrates how to use the libcl macros to get/set a floating point parameter value.

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

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

Example 6-4 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.

#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

Example 6-5 demonstrates how to get and set the minimum and maximum values of a particular parameter for the specified compressor or decompressor.

#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.