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

---

Note: Parameters are explained in detail in Chapter 6, “Using Compression Library 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 2-4 demonstrates how to compress a series of frames using the CL_MVC1 algorithm. A compressor is opened, and 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 2-4 for a list of typical header contents, and Table 2-5 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 2-4.

---

Note: For complete information on algorithms used with the OCTANE Compression option, see Chapter 7, “Using Compression Library Algorithms.” For information on parameters, see Chapter 6, “Using Compression Library Parameters.”

---

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

The code fragment in Example 2-5 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); 
read(inFile, header, headerSize); 
} 

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 framebuffer 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 2-6 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 2-10 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 framebuffer, 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 framebuffer. If space for a frame exists in the framebuffer, then the routine begins decompressing directly to the framebuffer. 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. When it finishes decompressing a frame, it updates the framebuffer pointers and returns. clDecompress() does not return until decompression is complete or until an error occurs.

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

clQueryValid() returns the pointer into the frame ring buffer. clUpdateTail() is required to free the internal framebuffer 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 framebuffers 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 does 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 2-11 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 does not get any larger, so the amount remaining in the buffer must be consumed.

The code fragment in Example 2-12 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 framebuffer, 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 framebuffer, but does not copy the data.

clCompress() reads from the framebuffer and writes to the data buffer. If a frame exists in the framebuffer, then the routine begins compressing directly from the framebuffer. 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 framebuffer 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 or 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 2-13 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 does 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(). To use data input buffering, clDecompress() receives NULL for compressedData. To use frame output buffering, clDecompress() receives NULL for frameBuffer.

clCompress() reads from the framebuffer and writes to the data buffer. If a frame exists in the framebuffer, then the routine begins compressing directly from the framebuffer. 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 framebuffer pointers and returns. clCompress() does not return until compression is complete or until an error occurs.