CLintro(3dm) CLintro(3dm) NAME CLintro, CompressionLibrary, compression, libcl, cl - A library for working with compressed video and audio data SYNOPSIS #include <dmedia/cl.h> -lcl DESCRIPTION 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), movieplayer(1) and moviemaker(1). ALGORITHMS 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 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- 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 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 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 DATA FORMATS The Compression Library recognizes the following video and audio formats. VIDEO FORMATS CL_FORMAT_ABGR means R, G, B, and A data are 8-bit components packed into a 32-bit word as: 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 (Luminance- Blue), and Cr (Luminance-Red), are packed into 24 bits as: 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 sub- sampled 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 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 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 int clOpenCompressor(int scheme, CLhandle *compressorHdl) int clCompress(CLhandle compressorHdl, int numberOfFrames, void *frameBuffer, int *compressedBufferSize, void *compressedBuffer) 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) | 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). Buffering Models 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 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 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) | /* 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) | /* 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) | 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) | 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); | } API FOR MANAGING PARAMETERS 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. 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 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 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, 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 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 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 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 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 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 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 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 the target ratio may have little effect on the actual ratio achieved. CL_BITRATE 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 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 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 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 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 Type: CL_RANGE_VALUE A read-only parameter for decompressors which indicates the index of the frame most recently decoded. CL_NUMBER_OF_FRAMES 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 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 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 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 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 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 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 int clAddAlgorithm(char *name, int algType, int maxHeaderSize, FunctionPtr openCompressor, FunctionPtr compress, FunctionPtr closeCompressor, 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 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) 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) 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. OPTION PRODUCTS Some schemes must be enabled with the installation of separate option products. 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 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). FILES /usr/include/dmedia/cl.h - header file (including error codes) /usr/share/src/dmedia/dmrecord - sample code /usr/share/src/dmedia/dmplay - sample code SEE ALSO 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) Page 17