Call clOpenCompressor() to open a compressor for a given algorithm. Its function prototype is:

int clOpenCompressor(int scheme, CLhandle *handlePtr)

where:

More than one compressor can be open at a time. Use the handle that is returned in handle to identify a specific compressor.

After a compressor has been opened, call clCompress() to compress the data. Pass to clCompress() the handle returned by clOpenCompressor(), the number of frames to be compressed, and pointers to reference the frame buffer containing the data frames, the size of the data, and the location of the buffer that is to store the compressed data.

The function prototype for clCompress() is:

int clCompress(CLhandle handle, int numberOfFrames,
void *frameBuffer, int *compressedDataSize,
void *compressedBuffer);

where:

Call clCompress() once to compress numberOfFrames sequential frames. clCompress() reads the raw data from the location pointed to by frameBuffer and writes the compressed data to the location pointed to by compressedBuffer. clCompress() returns either the number of frames successfully compressed, or in the case of CL_CONTINUOUS_NONBLOCK, returns SUCCESS immediately.

The size of the compressed data is stored in compressedDataSize, even if this size exceeds the COMPRESSED_BUFFER_SIZE state parameter. If COMPRESSED_BUFFER_SIZE is less than the actual size returned by clCompress(), then the data returned in compressedBuffer is not complete.

An application-allocated compressed buffer must be at least COMPRESSED_BUFFER_SIZE bytes. This parameter should be determined by calling clGetParams() after the frame buffer dimensions are defined by clSetParams(). It is not required to set the COMPRESSED_BUFFER_SIZE, because the default is the largest possible compressed data size, which is computed from the given parameters.

To close a compressor, call clCloseCompressor() with the handle of the compressor you wish to close. This frees resources associated with the compressor.

The code fragment in Example 24-3 demonstrates how to compress a series of frames using the CL_MVC1 algorithm. A compressor is opened, then a compression loop is entered, where frames are accessed one at a time and compressed using the selected algorithm, then written to a data buffer. The compressor is closed when all of the frames have been compressed.

#include <dmedia/cl.h>

int pbuf[][2] = {
    CL_IMAGE_WIDTH,  0,
    CL_IMAGE_HEIGHT, 0,
    CL_COMPRESSED_BUFFER_SIZE, 0
};
 ...
/* Compress a series of frames */
clOpenCompressor(CL_MVC1, &handle);

/* set parameters */
pbuf[0][1] = 320;
pbuf[1][1] = 240;
clSetParams(handle, (int *)pbuf, 4);
/* allocate the required size buffer */
clGetParams(handle, (int *)pbuf, 6);
compressedBuffer = malloc(pbuf[2][1]);

for(i = 0; i < numberOfFrames; i++)
{
    /* Get a frame from somewhere */
    ...
    clCompress(handle, 1, frameBuffer, &compressedBufferSize,
        compressedBuffer);
    /* Write the compressed data to somewhere else. */
    ...
}
clCloseCompressor(handle);

To determine which scheme to pass to the decompressor, use clQueryScheme() to get the scheme from the 16 bytes of the stream header (see Table 24-1 for a list of typical header contents, and Table 24-2 for a list of additional video stream header contents). clQueryScheme() returns the scheme, or the (negative) error code when an error occurs.

Once you determine the scheme, you can open the decompressor and read the header using clReadHeader(), which returns the actual size of the header, or zero if none is detected. Use clQueryMaxHeaderSize(), which returns the maximum size of the header, or zero if none is detected, to determine the size of the header to send to clReadHeader(). You should free the space used for the header buffer when you are finished with it.

clReadHeader() is generally called before clCreateBuf() to help calculate the compressed buffer size. It uses the data passed to it without affecting the buffering. clReadHeader() also sets up any state parameters that can be determined from the header.

The function prototypes are:

int clQueryScheme(void *header)
int clQueryMaxHeaderSize(int scheme)
int clReadHeader(CLhandle handle, int headerSize,void *header)

where:

A typical header begins with a start code and a size, followed by parameter-value pairs such as those listed in Table 24-1.

In addition, video algorithms usually supply the width and height parameters listed in the header, as shown in Table 24-2.

The code fragment in Example 24-4 demonstrates how to query a stream header and read its contents.

#include <cl.h>
...
int decompressionScheme;
...
/*
 * Determine the scheme from the first 16 bytes of the
 *  header(from the beginning of video data)
*/
header = malloc(16);
read(inFile, header, 16);
decompressionScheme = clQueryScheme(header);
if(decompressionScheme < 0) {
fprintf(stderr, “Unknown compression scheme in stream
header.0);
exit(0);
}
free(header);

clOpenDecompressor(decompressionScheme, &decompressorHdl);

/* Find out how big the header can be. */
headerSize = clQueryMaxHeaderSize(decompressionScheme);
if(headerSize > 0) {
/* Read the header from the beginning of video data */
header = malloc(headerSize);
lseek(inFile, 0, SEEK_SET);

Call clOpenDecompressor(), with the desired compression scheme and a pointer for returning a handle, to open a decompressor for a given algorithm. Its function prototype is:

int clOpenDecompressor(int scheme, CLhandle *handlePtr)

where:

More than one decompressor can be open at a time. Use the handle that is returned in handle to identify a specific decompressor.

After a decompressor has been opened, call clDecompress() to decompress the data. Pass to clDecompress() the handle returned by clOpenDecompressor(), the number of frames to be decompressed, the size of the data, and pointers to reference the decompressed data and the frame buffer that contains the compressed frames.

The function prototype for clDecompress() is:

int clDecompress ( CLhandle handle, int numberOfFrames,
                   int compressedDataSize, void *compressedData
                   void *frameBuffer);

where:

To close a decompressor, call clCloseDecompressor() with the handle of the decompressor you wish to close.

The code fragment in Example 24-5 demonstrates how to decompress a series of 320 × 240 (32-bit) RGBX frames by using the CL_MVC1 algorithm. A decompressor is opened, then a decompression loop is entered, where frames are accessed one at a time and decompressed by using the selected algorithm, then written to a location such as the screen. The decompressor is closed when all of the frames have been compressed.

#include <cl.h>
...
int compressedBufferSize;
int compressedBuffer[320][240], frameBuffer[320][240];
int     width, height, k;
static int    paramBuf[][2] = {
    CL_IMAGE_WIDTH, 0,
    CL_IMAGE_HEIGHT, 0,
    CL_ORIGINAL_FORMAT, 0,
};
width = 320;
height = 240;

clOpenDecompressor(CL_MVC1, &decompressorHdl);
paramBuf[0][1] = width;
paramBuf[1][1] = height;
paramBuf[2][1] = CL_RGBX;
clSetParams(decompressorHdl, (int *)paramBuf,
sizeof(paramBuf) / sizeof(int));

for (k = 0; k < numberOfFrames; k++)
{ /* Decompress each frame and display it */
  dataSize = GetCompressedVideo(k, frameSize, data);
  clDecompress(decompressorHdl, 1, dataSize, data,
frameBuffer);
  lrectwrite(0, 0, width-1, height-1,
(unsigned int *)frameBuffer);
}
/* Close Decompressor */
clCloseDecompressor(decompressorHdl);

The code fragment in Example 24-8 demonstrates how to use buffers for a playback application. The amount of space is queried, the data is read directly into the data buffer, and the decompressor is notified of the change. The data can then be decompressed and retrieved by querying the number of frames, displaying them directly from the frame buffer, then releasing the consumed frames.

#include <cl.h>
 ...
actualLen = clQueryFree(decompressorHdl, len, &buf, &wrap);
read(fd, buf, actualLen);
len = clUpdateHead(dataHdl, actualLen);

clDecompress(decompressorHdl, 1, 0, NULL, NULL);

actualNumberOfFrames = clQueryValid(frameHdl, numberOfFrames,
  &frameBuffer, &wrap);
ConsumeFrames(actualNumberOfFrames, frameBuffer);
numberOfFrames = clUpdateTail(bufferHdl, actualNumberOfFrames);

clUpdateHead() indicates to the library that the data has been placed in the data buffer, but does not copy the data.

clDecompress() reads compressed data from the data buffer and writes uncompressed frames to the frame buffer. If space for a frame exists in the frame buffer, then it begins decompressing directly to the frame buffer. It consumes data from the data buffer until there is no more data, then it sleeps for a while and periodically continues to check for data until there is enough data. When it finishes decompressing a frame, it updates the frame buffer pointers and returns. clDecompress() does not return until decompression is complete or until an error occurs.

If no more data will be added to the buffer, the application can call clDoneUpdatingHead() so that the library will not stall.

clQueryValid() returns the pointer into the frame ring buffer. clUpdateTail() is required to free the internal frame buffer space, which you don't want to happen until after you consume it. The pointer to the next valid frame is kept internally, and only the actual number of frame buffers that have been decompressed are returned.

The size (or numberOfFrames) returned by the routines are for the contiguous data (or frames, depending on the buffer type). The wrap argument of the clQuery() routines returns the actualLen (or numberOfFrames) that have wrapped to the beginning of the buffer.

The frame accesses will not cross the buffer boundary, and the wrap argument does not need to be used if both:

If the len (or numberOfFrames) passed to the clQuery() routines is greater than zero, the routine blocks until that much data (or that many frames) is available. If it is less than or equal to zero, then the routine returns immediately with whatever data is available. In either case, the buffer pointers are not adjusted until the clUpdate() routines are called.

The code fragment in Example 24-9 demonstrates how to implement nonblocking playback.

actualLen = clQueryFree(decompressorHdl, 0, &buf, &wrap);
if((actualLen > MIN_READ_SIZE) || (wrap > 0)) {
   read(fd, buf, actualLen);
   len = clUpdateHead(decompressorHdl, actualLen);
}
/* Go do something else */
 ...

Each call to clQueryFree() returns the same buf pointer, but increasing values of actualLen until MIN_READ_SIZE is reached, whereupon clUpdateHead(dataHdl) updates the pointers and the next call to clQueryFree() returns a different buf pointer and a reset actualLen. If wrap becomes greater than zero, the end of the buffer has been reached and actualLen will not get any larger, so the amount remaining in the buffer must be consumed.

The code fragment in Example 24-10 demonstrates how to use buffers for recording.

actualNumberOfFrames = clQueryFree(bufferHdl, numberOfFrames,
                                   &frameBuffer, &wrap);
ProduceFrames(actualNumberOfFrames, frameBuffer);
numberOfFrames = clUpdateHead(bufferHdl, actualNumberOfFrames);

clCompress(compressorHdl, 1, NULL, 0, NULL);

actualBufSize = clQueryValid(compressorHdl, bufSize, &buf,
                             &wrap);
write(fd, buf, actualBufSize);
bufSize = clUpdateTail(compressorHdl, actualBufSize);

The amount of free space is queried, the frames are read directly into the frame buffer, and the compressor is notified of the change. The frames can then be compressed and the data can be retrieved by querying the amount of the data, consuming directly from the data buffer, then releasing the consumed data.

clUpdateHead() indicates that the frames have been placed in the frame buffer, but does not copy the data.

clCompress() reads from the frame buffer and writes to the data buffer. If a frame exists in the frame buffer, then it begins compressing directly from the frame buffer. It places compressed data in the data buffer until there is no more room, then it blocks until there is enough room. When it completes compression of a frame, it updates the frame buffer pointers and returns. clCompress() does not return until compression is complete (or an error occurs).

clQueryValid() returns the pointer into the data ring buffer. clUpdateTail() is required to free the internal data buffer space, which you don't want to happen until after you consume it—in this case, by writing it. The pointer to valid data is kept internally, and clUpdateTail() returns only the actual number of bytes released.

The amount/numberOfFrames returned by the routines are for contiguous data/ frames. The wrap parameter of the clQuery() routines returns the amount/numberOfFrames that have wrapped to the beginning of the buffer.

If the allocated size of the frame ring buffer is a multiple of the size of a frame times the numberOfFrames that will be requested, assuming that the same number of frames is always requested, then the frame accesses will not cross the buffer boundary, and the wrap parameter does not need to be used.

If the amount passed to the clQuery() routines is greater than zero, then the routine blocks until that much data is available. If it is less than or equal to zero, then the routine returns immediately with whatever data is available. In either case, the buffer pointers are not adjusted until the clUpdate() routine is called.

The code fragment in Example 24-11 demonstrates how to use buffers for nonblocking recording.

actualLen = clQueryValid(dataHdl, 0, &buf, &wrap);
if((actualLen > MIN_READ_SIZE) || (wrap > 0)){
write(fd, buf, actualLen);
len = clUpdateTail(dataHdl, actualLen);
}

Each call to clQueryValid() returns the same buf pointer, but increasing values of actualLen until MIN_READ_SIZE is reached, whereupon clUpdateTail() updates the pointers, and the next call to clQueryValid() returns a different buf pointer and a reset actualLen. If wrap becomes greater than zero, then the end of the buffer has been reached, and actualLen will not get any larger, so the amount remaining in the buffer must be consumed.

Note that the consuming, compressing or decompressing, and producing have been separated into different sets of calls. The most powerful use of the interface is to separate these functional groupings into shared processes using sproc() or to allocate them to separate (shared data) processors. See sproc(2) for more information about using sproc().

The buffers are set up by clCreateBuf(). In order to use data input buffering, clDecompress() receives NULL for compressedData. In order to use frame output buffering, clDecompress() receives NULL for frameBuffer.

clCompress() reads from the frame buffer and writes to the data buffer. If a frame exists in the frame buffer, then it begins compressing directly from the frame buffer. It places compressed data in the data buffer until there is no more room, then it sleeps for a while and checks again until there is enough room. When it finishes compressing a frame, it updates the frame buffer pointers and returns. clCompress() does not return until compression is complete or until an error occurs.

To compress frames into memory using Cosmo Compress:

When compressing images from memory into a buffer, Cosmo Compress supports image widths of 16–768 and image heights of 16–336, in multiples of 8. You cannot scale images when compressing into memory, therefore, CL_IMAGE_WIDTH equals CL_INTERNAL_IMAGE_WIDTH, and CL_IMAGE_HEIGHT equals CL_INTERNAL_IMAGE_HEIGHT.

The uncompressed data format must be 32-bit RGB (CL_RGBX), and the uncompressed image size cannot be larger than PAL video.

---

Note: NTSC frames have a width of 243, but Cosmo Compress supports only input image widths that are multiples of 8. For NTSC, you must specify an image width of either 240 (causing the image to be cropped 3 lines from the bottom) or 248 (causing the image to be padded with 5 extra lines). Output image widths do not have to be multiples of 8.

---

Example 24-14 demonstrates memory-to-memory compression of NTSC video.

#include <dmedia/cl.h>
...
    int pbuf[][2] = {
        CL_IMAGE_WIDTH,  0,
        CL_IMAGE_HEIGHT, 0,
        CL_COMPRESSED_BUFFER_SIZE, 0
    };
     ...
    /* Compress a series of frames */
    clOpenCompressor(CL_JPEG_COSMO, &handle);

    /* set parameters */
    pbuf[0][1] = 640;
    pbuf[1][1] = 240;
    clSetParams(handle, (int *)pbuf, 4);

    /* allocate the required size buffer */
    clGetParams(handle, (int *)pbuf, 6);
    compressedBuffer = malloc(pbuf[2][1]);

    for(i = 0; i < numberOfFrames; i++)
    {
        /* Get a frame from somewhere */
        ...
        clCompress(handle, 1, frameBuffer,
                   &compressedBufferSize, compressedBuffer);
        /* Write the compressed data to somewhere else. */
        ...
    }
    clCloseCompressor(handle);

After compressing the images, you can use mvInsertCompressedImage() to insert the compressed images into a movie file, as described in “Reading and Inserting Compressed Images” in Chapter 29. Since the JPEG images are stored in fields, you must read two fields for every frame.

To decompress JPEG images from memory using Cosmo Compress:

You can shrink the images as they are decompressed, which is useful for displaying thumbnail images. When decompressing images from memory into a buffer, Cosmo Compress supports image widths of 16–768 and image heights of 16–336. Scaling can be arbitrary, that is, you can scale the image dimensions down by any amount, and the output image dimensions do not have to be multiples of 8. To shrink images as they are decompressed, make the uncompressed image dimensions (CL_IMAGE_WIDTH and CL_IMAGE_HEIGHT) less than the corresponding compressed image dimensions (CL_INTERNAL_IMAGE_WIDTH and CL_INTERNAL_IMAGE_HEIGHT).

To capture video from an external video device using Cosmo Compress:

---

Note: Instead of using CL_CONTINUOUS_NONBLOCK, you can call clCompress() from a separate thread within the program. clCompress() does not return until the transfer is complete.

---

See cosmo_capture.c in /usr/people/4Dgifts/examples/dmedia/dmrecord for an example of capturing external video through Cosmo Compress.

Video fields entering Cosmo Compress from the direct video connection are captured into an array of field buffers. The field buffers support field widths from 640 to 768 and field heights from 16 to 336. Field dimensions depend on the video timing, as shown in Table 24-4.

Table 24-4 shows video field dimensions for the video formats supported by Cosmo Compress.

Lines in the field buffers following the end of valid video data are filled with indeterminate data (that is, they are not blacked out).

When the compressed image height is less than the height of the incoming video fields, the video fields are clipped from the bottom before they are sent to the compressor. When the compressed image height is greater than the height of the incoming video fields, additional lines of indeterminate data are appended to the valid video data before the data is sent to the compressor.

---

Note: NTSC fields have a height (243 pixels) which is not a multiple of 8. For NTSC capture, you can choose to have your application either throw away 3 lines from the bottom of each field (240 pixel height) or append 5 extra lines to the bottom of each field (248 pixel height) prior to compression.

---

You can scale the captured image to half-size before compressing it. This allows for an additional increase in data compression by factor of 4.

Specify vertical decimation by setting the compressed image height (CL_INTERNAL_IMAGE_HEIGHT) to half the size of the uncompressed image height (CL_IMAGE_HEIGHT). Compressed image heights can range from 16 to 168 and uncompressed image heights can range from 32 to 336.

Specify horizontal decimation by setting the compressed image width (CL_INTERNAL_IMAGE_WIDTH) to half the size of the uncompressed image width (CL_IMAGE_WIDTH) as indicated in Table 24-5.

During video compression from an external device, CLimageInfo.imagecount is initialized to 1 when the first field is received by the compressor after calling clCompress(). The count advances when a new field arrives. If the compression data buffer fills up, then a field will be dropped, but the imagecount continues to increase. An application can thus detect a dropped field by noticing a jump in the imagecount field of more than one. The ustime indicates the time the uncompressed field entered the compressor.

The connections for decompressing from memory to an external video are set up similar to those for capturing video, except that a decompressor is opened. See clInit.c in /usr/people/4Dgifts/examples/dmedia/dmplay for example code that initializes the CL for JPEG decompression (optionally through Cosmo Compress) from memory to external video.

Video playback of the decompressed frames requires media synchronization. See dmplay.c and streamDecompress.c in /usr/people/4Dgifts/examples/dmedia/dmplay for more information.

Uncompressed fields leaving the JPEG decompressor may optionally be scaled up by a factor of 2 in the horizontal and/or vertical dimensions. NTSC, PAL or CCIR(525)/CCIR(625) fields are then scanned out of the array of field buffers. Horizontal scaling is performed by pixel replication, vertical scaling is performed by line doubling. If the uncompressed fields leaving the decompressor have fewer lines than the field height required by the NTSC, PAL or CCIR(525)/CCIR(625) connection (after optional pistoling), additional lines of indeterminate (not blacked out) data will be scanned out of the field buffers to pad out bottoms of the uncompressed images. If the uncompressed fields leaving the decompressor have more lines than the NTSC/PAL/CCIR(525)/CCIR(625) field height (after optional pistoling), lines will be clipped from the bottom of the uncompressed images.

Specify horizontal scaling by setting the uncompressed image width (CL_IMAGE_WIDTH) that is twice the compressed image width (CL_INTERNAL_IMAGE_WIDTH) as indicated in Table 24-6.

Specify vertical scaling by setting the uncompressed image height (CL_IMAGE_HEIGHT) to twice the size of the compressed image height (CL_INTERNAL_IMAGE_HEIGHT). Compressed image heights can range from 16 to 168 and uncompressed image heights can range from 32 to 336.

During video decompression to an external device, CLimageInfo.imagecount reflects the count of fields sent by the application to the decompressor. The ustime indicates the time that field left the decompressor. In certain situations, fields are repeated on output, in which case the imagecount will remain the same, but the ustime will increase. Cosmo Compress decompression has a 1 frame delay through Galileo/IndyVideo before the field actually leaves the machine.

When transferring to or from external video, the video can be played continuously (default) or single-stepped a field or frame at a time. In either mode, the frame output is composed of either a single field replicated twice or two different fields. Specify the frame control by setting CL_COSMO_VIDEO_TRANSFER_MODE.

For continuous transfer, set CL_COSMO_VIDEO_TRANSFER_MODE to CL_COSMO_VIDEO_TRANSFER_AUTO_1_FIELD for the first field in a frame, and CL_COSMO_VIDEO_TRANSFER_AUTO_2_FIELD for the second field in a frame.

For manual control, set CL_COSMO_VIDEO_TRANSFER_MODE to CL_COSMO_VIDEO_TRANSFER_MANUAL_1_FIELD, and CL_COSMO_VIDEO_TRANSFER_MANUAL_2_FIELD.

In manual video transfer mode, the output frame can be set to either advance or repeat the current frame or field, as specified by CL_COSMO_VIDEO_FRAME_CONTROL.

You can control compression or decompression with CL_COSMO_CODEC_CONTROL. Setting CL_COSMO_CODEC_CONTROL to CL_COSMO_STOP halts compression or decompression. If clCompress() or clDecompress() was called with CL_CONTINUOUS_BLOCK, the function returns. If clCompress() or clDecompress() was called with CL_CONTINUOUS_NONBLOCK, the associated thread terminates.

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 Cosmo Compress 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.

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 then stored as reference tables, and 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. Currently, you cannot change this parameter for Cosmo Compress—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.