IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3dm/old-compression/CLintro.z/CLintro

Text File | 1998-10-20 | 74.4 KB | 1,123 lines

CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



NNNNAAAAMMMMEEEE
     CLintro, CompressionLibrary, compression, libcl, cl - A library for
     working with compressed video and audio data

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ccccllll....hhhh>>>>
     ----llllccccllll


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     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).


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


   VVVVIIIIDDDDEEEEOOOO CCCCOOOOMMMMPPPPRRRREEEESSSSSSSSIIIIOOOONNNN

     MMMMPPPPEEEEGGGG----1111 VVVViiiiddddeeeeoooo (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.

     JJJJPPPPEEEEGGGG (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-



                                                                        PPPPaaaaggggeeee 1111






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     assisted version (scheme is CL_JPEG_COSMO).

     MMMMVVVVCCCC1111 (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.

     MMMMVVVVCCCC2222 (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.

     MMMMVVVVCCCC3333 (Motion Video Compressor 3) is an SGI proprietary algorithm based on
     fast transform coding.  Scheme is CL_MVC3_SOFTWARE.

     RRRRLLLLEEEE (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.

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

     TTTTaaaabbbblllleeee 1111:::: VVVViiiiddddeeeeoooo AAAAllllggggoooorrrriiiitttthhhhmmmmssss ---- PPPPeeeerrrrffffoooorrrrmmmmaaaannnncccceeee EEEExxxxaaaammmmpppplllleeee

                                             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



   AAAAUUUUDDDDIIIIOOOO CCCCOOOOMMMMPPPPRRRREEEESSSSSSSSIIIIOOOONNNN

     MMMMPPPPEEEEGGGG----1111 AAAAuuuuddddiiiioooo (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



                                                                        PPPPaaaaggggeeee 2222






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     CL_MPEG1_AUDIO_AWARE), and an SGI version that provides other features
     (scheme is CL_MPEG1_AUDIO_SOFTWARE).

     AAAAwwwwaaaarrrreeee MMMMuuuullllttttiiiirrrraaaatttteeee 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.

     GGGG777711111111 uuuu----llllaaaawwww 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.

     GGGG777711111111 AAAA----llllaaaawwww 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.

     TTTTaaaabbbblllleeee 2222:::: AAAAuuuuddddiiiioooo AAAAllllggggoooorrrriiiitttthhhhmmmmssss ---- PPPPeeeerrrrffffoooorrrrmmmmaaaannnncccceeee EEEExxxxaaaammmmpppplllleeee

                                       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





DDDDAAAATTTTAAAA FFFFOOOORRRRMMMMAAAATTTTSSSS
     The Compression Library recognizes the following video and audio formats.


   VVVVIIIIDDDDEEEEOOOO FFFFOOOORRRRMMMMAAAATTTTSSSS

     CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____AAAABBBBGGGGRRRR means R, G, B, and A data are 8-bit components packed into
     a 32-bit word as:











                                                                        PPPPaaaaggggeeee 3333






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



              0xAABBGGRR
                  where:
                      AA  contains the alpha value.
                      BB  contains the blue value.
                      GG  contains the green value.
                      RR  contains the red value.



     CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____XXXXBBBBGGGGRRRR means R, G, B, and X (don't care) data are packed into a
     32-bit word as 0xXXBBGGRR.

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

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



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



     CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____GGGGRRRRAAAAYYYYSSSSCCCCAAAALLLLEEEE means four luminance bytes are packed into a 32-bit
     word.

     CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____YYYYCCCCbbbbCCCCrrrr means 3 8-bit components, Y (Luminance), Cb (Luminance-
     Blue), and Cr (Luminance-Red), are packed into 24 bits as:















                                                                        PPPPaaaaggggeeee 4444






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



              0xCbYYCr
                  where:
                      Cb  contains the luma-blue value.
                      YY  contains the luminance value.
                      Cr  contains the luma-red value.


     CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____YYYYCCCCbbbbCCCCrrrr444422222222 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).

     CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____YYYYCCCCbbbbCCCCrrrr444422222222DDDDCCCC (duplicate chroma) means that the chroma are sub-
     sampled by 2 vertically in addition to horizontally, and are packed the
     same as CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____YYYYCCCCbbbbCCCCrrrr444422222222 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].

   AAAAUUUUDDDDIIIIOOOO FFFFOOOORRRRMMMMAAAATTTTSSSS

     CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____MMMMOOOONNNNOOOO means that the audio samples represent a single channel.

     CCCCLLLL____FFFFOOOORRRRMMMMAAAATTTT____SSSSTTTTEEEERRRREEEEOOOO____IIIINNNNTTTTEEEERRRRLLLLEEEEAAAAVVVVEEEEDDDD means that the audio samples alternately
     represent left and right channels.


PPPPRRRROOOOGGGGRRRRAAAAMMMMMMMMIIIINNNNGGGG IIIINNNNTTTTEEEERRRRFFFFAAAACCCCEEEE
     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.


   AAAAPPPPIIII FFFFOOOORRRR PPPPRRRROOOOCCCCEEEESSSSSSSSIIIINNNNGGGG DDDDAAAATTTTAAAA

     iiiinnnntttt ccccllllOOOOppppeeeennnnCCCCoooommmmpppprrrreeeessssssssoooorrrr((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, CCCCLLLLhhhhaaaannnnddddlllleeee ****ccccoooommmmpppprrrreeeessssssssoooorrrrHHHHddddllll))))
     iiiinnnntttt ccccllllCCCCoooommmmpppprrrreeeessssssss((((CCCCLLLLhhhhaaaannnnddddlllleeee ccccoooommmmpppprrrreeeessssssssoooorrrrHHHHddddllll,,,, iiiinnnntttt nnnnuuuummmmbbbbeeeerrrrOOOOffffFFFFrrrraaaammmmeeeessss,,,,
         vvvvooooiiiidddd ****ffffrrrraaaammmmeeeeBBBBuuuuffffffffeeeerrrr,,,, iiiinnnntttt ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrrSSSSiiiizzzzeeee,,,, vvvvooooiiiidddd ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrr))))



                                                                        PPPPaaaaggggeeee 5555






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     iiiinnnntttt ccccllllCCCClllloooosssseeeeCCCCoooommmmpppprrrreeeessssssssoooorrrr((((CCCCLLLLhhhhaaaannnnddddlllleeee ccccoooommmmpppprrrreeeessssssssoooorrrrHHHHddddllll))))

     iiiinnnntttt ccccllllOOOOppppeeeennnnDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, CCCCLLLLhhhhaaaannnnddddlllleeee ****ddddeeeeccccoooommmmpppprrrreeeessssssssoooorrrrHHHHddddllll))))
     iiiinnnntttt ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss((((CCCCLLLLhhhhaaaannnnddddlllleeee ddddeeeeccccoooommmmpppprrrreeeessssssssoooorrrrHHHHddddllll,,,, iiiinnnntttt nnnnuuuummmmbbbbeeeerrrrOOOOffffFFFFrrrraaaammmmeeeessss,,,,
         iiiinnnntttt ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrrSSSSiiiizzzzeeee,,,, vvvvooooiiiidddd ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrr,,,, vvvvooooiiiidddd ****ffffrrrraaaammmmeeeeBBBBuuuuffffffffeeeerrrr))))
     iiiinnnntttt ccccllllCCCClllloooosssseeeeDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr((((CCCCLLLLhhhhaaaannnnddddlllleeee ddddeeeeccccoooommmmpppprrrreeeessssssssoooorrrrHHHHddddllll))))



     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:

     EEEExxxxaaaammmmpppplllleeee ((((ccccoooommmmpppprrrreeeessssssssiiiioooonnnn))))

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



                                                                        PPPPaaaaggggeeee 6666






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     BBBBuuuuffffffffeeeerrrriiiinnnngggg MMMMooooddddeeeellllssss

     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. DDDDiiiirrrreeeecccctttt   - 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. IIIImmmmpppplllliiiicccciiiitttt - 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 ccccllllCCCCrrrreeeeaaaatttteeeeBBBBuuuuffff and ccccllllDDDDeeeessssttttrrrrooooyyyyBBBBuuuuffff), 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).


   AAAAPPPPIIII FFFFOOOORRRR MMMMAAAANNNNAAAAGGGGIIIINNNNGGGG IIIIMMMMPPPPLLLLIIIICCCCIIIITTTT BBBBUUUUFFFFFFFFEEEERRRRSSSS

     CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll ccccllllCCCCrrrreeeeaaaatttteeeeBBBBuuuuffff((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt bbbbuuuuffffffffeeeerrrrTTTTyyyyppppeeee,,,,
         iiiinnnntttt bbbblllloooocccckkkkssss,,,, iiiinnnntttt bbbblllloooocccckkkkSSSSiiiizzzzeeee,,,, vvvvooooiiiidddd ********bbbbuuuuffffffffeeeerrrr))))
     iiiinnnntttt ccccllllDDDDeeeessssttttrrrrooooyyyyBBBBuuuuffff((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll))))
     CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll ccccllllQQQQuuuueeeerrrryyyyBBBBuuuuffffffffeeeerrrrHHHHddddllll((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,,
         iiiinnnntttt bbbbuuuuffffffffeeeerrrrTTTTyyyyppppeeee,,,, vvvvooooiiiidddd ********bbbbuuuuffffffffeeeerrrr))))
     CCCCLLLLhhhhaaaannnnddddlllleeee ccccllllQQQQuuuueeeerrrryyyyHHHHaaaannnnddddlllleeee((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll))))

     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyyFFFFrrrreeeeeeee((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll,,,, iiiinnnntttt ffffrrrreeeeeeeeAAAAmmmmoooouuuunnnntttt,,,,
         vvvvooooiiiidddd ********ffffrrrreeeeeeeeDDDDaaaattttaaaa,,,, iiiinnnntttt ****ffffrrrreeeeeeeeWWWWrrrraaaapppp))))
     iiiinnnntttt ccccllllUUUUppppddddaaaatttteeeeHHHHeeeeaaaadddd((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll,,,, iiiinnnntttt aaaammmmoooouuuunnnnttttTTTTooooAAAAdddddddd))))
     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyyVVVVaaaalllliiiidddd((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll,,,, iiiinnnntttt vvvvaaaalllliiiiddddAAAAmmmmoooouuuunnnntttt,,,,
         vvvvooooiiiidddd ********vvvvaaaalllliiiiddddDDDDaaaattttaaaa,,,, iiiinnnntttt ****vvvvaaaalllliiiiddddWWWWrrrraaaapppp))))
     iiiinnnntttt ccccllllUUUUppppddddaaaatttteeeeTTTTaaaaiiiillll((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll,,,, iiiinnnntttt aaaammmmoooouuuunnnnttttTTTTooooRRRReeeelllleeeeaaaasssseeee))))
     iiiinnnntttt ccccllllDDDDoooonnnneeeeUUUUppppddddaaaattttiiiinnnnggggHHHHeeeeaaaadddd((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll))))


     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



                                                                        PPPPaaaaggggeeee 7777






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     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
     CCCCLLLL____BBBBUUUUFFFF____FFFFRRRRAAAAMMMMEEEE and CCCCLLLL____BBBBUUUUFFFF____CCCCOOOOMMMMPPPPRRRREEEESSSSSSSSEEEEDDDD.

     ccccllllCCCCrrrreeeeaaaatttteeeeBBBBuuuuffff and ccccllllDDDDeeeessssttttrrrrooooyyyyBBBBuuuuffff 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.  ccccllllQQQQuuuueeeerrrryyyyBBBBuuuuffffffffeeeerrrrHHHHddddllll
     returns the ring buffer of specified type given a processing object;
     ccccllllQQQQuuuueeeerrrryyyyHHHHaaaannnnddddlllleeee returns the processing object given a ring buffer.

     A ring buffer producer calls ccccllllQQQQuuuueeeerrrryyyyFFFFrrrreeeeeeee and ccccllllUUUUppppddddaaaatttteeeeHHHHeeeeaaaadddd 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 ccccllllQQQQuuuueeeerrrryyyyVVVVaaaalllliiiidddd and ccccllllUUUUppppddddaaaatttteeeeTTTTaaaaiiiillll, which are complementary
     calls for querying valid data and reading from the tail of the buffer.
     The producer should call ccccllllDDDDoooonnnneeeeUUUUppppddddaaaattttiiiinnnnggggHHHHeeeeaaaadddd 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.

     EEEExxxxaaaammmmpppplllleeee ((((iiiimmmmpppplllliiiicccciiiitttt bbbbuuuuffffffffeeeerrrriiiinnnngggg mmmmooooddddeeeellll ---- rrrreeeeccccoooorrrrdddd))))

     | /* 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);
     | }

     EEEExxxxaaaammmmpppplllleeee ((((iiiimmmmpppplllliiiicccciiiitttt bbbbuuuuffffffffeeeerrrriiiinnnngggg mmmmooooddddeeeellll ---- ppppllllaaaayyyybbbbaaaacccckkkk))))



                                                                        PPPPaaaaggggeeee 8888






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     | /* 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);

     EEEExxxxaaaammmmpppplllleeee ((((iiiimmmmpppplllliiiicccciiiitttt bbbbuuuuffffffffeeeerrrriiiinnnngggg mmmmooooddddeeeellll ---- mmmmuuuullllttttiiiipppprrrroooocccceeeessssssss rrrreeeeccccoooorrrrdddd))))

     | 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);
     | }

     EEEExxxxaaaammmmpppplllleeee ((((iiiimmmmpppplllliiiicccciiiitttt bbbbuuuuffffffffeeeerrrriiiinnnngggg mmmmooooddddeeeellll ---- mmmmuuuullllttttiiiipppprrrroooocccceeeessssssss ppppllllaaaayyyybbbbaaaacccckkkk))))

     | 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);



                                                                        PPPPaaaaggggeeee 9999






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     | }



   AAAAPPPPIIII FFFFOOOORRRR MMMMAAAANNNNAAAAGGGGIIIINNNNGGGG PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS

     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyyPPPPaaaarrrraaaammmmssss((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,,
         iiiinnnntttt ****ppppaaaarrrraaaammmmVVVVaaaalllluuuueeeeBBBBuuuuffffffffeeeerrrr,,,, iiiinnnntttt bbbbuuuuffffffffeeeerrrrLLLLeeeennnnggggtttthhhh))))
     iiiinnnntttt ccccllllGGGGeeeettttPPPPaaaarrrraaaammmmIIIIDDDD((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, cccchhhhaaaarrrr ****ppppaaaarrrraaaammmmNNNNaaaammmmeeee))))

     iiiinnnntttt ccccllllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,,
         iiiinnnntttt ****ppppaaaarrrraaaammmmVVVVaaaalllluuuueeeeBBBBuuuuffffffffeeeerrrr,,,, iiiinnnntttt bbbbuuuuffffffffeeeerrrrLLLLeeeennnnggggtttthhhh))))
     iiiinnnntttt ccccllllSSSSeeeettttPPPPaaaarrrraaaammmmssss((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,,
         iiiinnnntttt ****ppppaaaarrrraaaammmmVVVVaaaalllluuuueeeeBBBBuuuuffffffffeeeerrrr,,,, iiiinnnntttt bbbbuuuuffffffffeeeerrrrLLLLeeeennnnggggtttthhhh))))
     iiiinnnntttt ccccllllGGGGeeeettttPPPPaaaarrrraaaammmm((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD))))
     iiiinnnntttt ccccllllSSSSeeeettttPPPPaaaarrrraaaammmm((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt vvvvaaaalllluuuueeee))))

     iiiinnnntttt ccccllllGGGGeeeettttDDDDeeeeffffaaaauuuulllltttt((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD))))
     iiiinnnntttt ccccllllGGGGeeeettttMMMMiiiinnnnMMMMaaaaxxxx((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt ****mmmmiiiinnnn,,,, iiiinnnntttt ****mmmmaaaaxxxx))))
     cccchhhhaaaarrrr ****ccccllllGGGGeeeettttNNNNaaaammmmeeee((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD))))


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

     ccccllllQQQQuuuueeeerrrryyyyPPPPaaaarrrraaaammmmssss is used to determine what parameters are defined for an
     object.  ccccllllGGGGeeeettttPPPPaaaarrrraaaammmmIIIIDDDD returns the parameter identifier used in other
     calls.  ccccllllGGGGeeeettttPPPPaaaarrrraaaammmmssss, ccccllllSSSSeeeettttPPPPaaaarrrraaaammmmssss, ccccllllGGGGeeeettttPPPPaaaarrrraaaammmm, and ccccllllSSSSeeeettttPPPPaaaarrrraaaammmm are used to
     read and write groups of parameters or individual parameters.
     ccccllllGGGGeeeettttDDDDeeeeffffaaaauuuulllltttt, ccccllllGGGGeeeettttMMMMiiiinnnnMMMMaaaaxxxx, and ccccllllGGGGeeeettttNNNNaaaammmmeeee 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.

        CCCCLLLL____EEEENNNNUUUUMMMM____VVVVAAAALLLLUUUUEEEE           only certain constant values are valid
        CCCCLLLL____RRRRAAAANNNNGGGGEEEE____VVVVAAAALLLLUUUUEEEE          any value in a given range is valid
        CCCCLLLL____FFFFLLLLOOOOAAAATTTTIIIINNNNGGGG____EEEENNNNUUUUMMMM____VVVVAAAALLLLUUUUEEEE  only certain constant floating point values
                                are valid
        CCCCLLLL____FFFFLLLLOOOOAAAATTTTIIIINNNNGGGG____RRRRAAAANNNNGGGGEEEE____VVVVAAAALLLLUUUUEEEE 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.




                                                                       PPPPaaaaggggeeee 11110000






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     CCCCLLLL____IIIIMMMMAAAAGGGGEEEE____WWWWIIIIDDDDTTTTHHHH,,,, CCCCLLLL____IIIIMMMMAAAAGGGGEEEE____HHHHEEEEIIIIGGGGHHHHTTTT
          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.

     CCCCLLLL____IIIINNNNTTTTEEEERRRRNNNNAAAALLLL____IIIIMMMMAAAAGGGGEEEE____WWWWIIIIDDDDTTTTHHHH,,,, CCCCLLLL____IIIINNNNTTTTEEEERRRRNNNNAAAALLLL____IIIIMMMMAAAAGGGGEEEE____HHHHEEEEIIIIGGGGHHHHTTTT
          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.

     CCCCLLLL____IIIIMMMMAAAAGGGGEEEE____CCCCRRRROOOOPPPP____LLLLEEEEFFFFTTTT,,,, CCCCLLLL____IIIIMMMMAAAAGGGGEEEE____CCCCRRRROOOOPPPP____RRRRIIIIGGGGHHHHTTTT,,,,
     CCCCLLLL____IIIIMMMMAAAAGGGGEEEE____CCCCRRRROOOOPPPP____TTTTOOOOPPPP,,,, CCCCLLLL____IIIIMMMMAAAAGGGGEEEE____CCCCRRRROOOOPPPP____BBBBOOOOTTTTTTTTOOOOMMMM
          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.

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

     CCCCLLLL____IIIINNNNTTTTEEEERRRRNNNNAAAALLLL____FFFFOOOORRRRMMMMAAAATTTT
          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,



                                                                       PPPPaaaaggggeeee 11111111






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



                                  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.

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

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

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

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

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

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

     CCCCLLLL____EEEEXXXXAAAACCCCTTTT____CCCCOOOOMMMMPPPPRRRREEEESSSSSSSSIIIIOOOONNNN____RRRRAAAATTTTIIIIOOOO
          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



                                                                       PPPPaaaaggggeeee 11112222






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



          the target ratio may have little effect on the actual ratio achieved.

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

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

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

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

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

     CCCCLLLL____FFFFRRRRAAAAMMMMEEEE____IIIINNNNDDDDEEEEXXXX
          Type: CL_RANGE_VALUE
          A read-only parameter for decompressors which indicates the
          index of the frame most recently decoded.

     CCCCLLLL____NNNNUUUUMMMMBBBBEEEERRRR____OOOOFFFF____FFFFRRRRAAAAMMMMEEEESSSS
          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



                                                                       PPPPaaaaggggeeee 11113333






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



          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.

     CCCCLLLL____SSSSPPPPEEEEEEEEDDDD
          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).

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

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

     CCCCLLLL____AAAALLLLGGGGOOOORRRRIIIITTTTHHHHMMMM____IIIIDDDD
          Type: CL_RANGE_VALUE
          The algorithm identifier (e.g. CL_MPEG1_VIDEO_SOFTWARE).  This is
          a read-only parameter for all processing objects.

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


   AAAAPPPPIIII FFFFOOOORRRR AAAADDDDDDDDIIIINNNNGGGG AAAALLLLGGGGOOOORRRRIIIITTTTHHHHMMMMSSSS AAAANNNNDDDD PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS

     iiiinnnntttt ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((cccchhhhaaaarrrr ****nnnnaaaammmmeeee,,,, iiiinnnntttt aaaallllggggTTTTyyyyppppeeee,,,, iiiinnnntttt mmmmaaaaxxxxHHHHeeeeaaaaddddeeeerrrrSSSSiiiizzzzeeee,,,,
         FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ooooppppeeeennnnCCCCoooommmmpppprrrreeeessssssssoooorrrr,,,, FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ccccoooommmmpppprrrreeeessssssss,,,,
         FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr cccclllloooosssseeeeCCCCoooommmmpppprrrreeeessssssssoooorrrr,,,,



                                                                       PPPPaaaaggggeeee 11114444






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



         FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ooooppppeeeennnnDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr,,,, FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ddddeeeeccccoooommmmpppprrrreeeessssssss,,,,
         FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr cccclllloooosssseeeeDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr,,,,
         FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr rrrreeeeaaaaddddHHHHeeeeaaaaddddeeeerrrr,,,, FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr qqqquuuueeeerrrryyyySSSScccchhhheeeemmmmeeee,,,,
         FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr qqqquuuueeeerrrryyyyLLLLiiiicccceeeennnnsssseeee,,,,
         FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ggggeeeettttPPPPaaaarrrraaaammmmssss,,,, FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr sssseeeettttPPPPaaaarrrraaaammmmssss,,,,
         iiiinnnntttt ****sssscccchhhheeeemmmmeeee))))
     vvvvooooiiiidddd ****ccccllllSSSSeeeettttUUUUnnnniiiiqqqquuuueeee((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, vvvvooooiiiidddd ****uuuunnnniiiiqqqquuuueeee))))
     vvvvooooiiiidddd ****ccccllllGGGGeeeettttUUUUnnnniiiiqqqquuuueeee((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee))))
     iiiinnnntttt  ccccllllFFFFeeeettttcccchhhhPPPPaaaarrrraaaammmm((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD))))
     vvvvooooiiiidddd ccccllllSSSSttttoooorrrreeeePPPPaaaarrrraaaammmm((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt vvvvaaaalllluuuueeee))))
     vvvvooooiiiidddd ccccllllEEEErrrrrrrroooorrrr((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ccccooooddddeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffoooorrrrmmmmaaaatttt,,,, ............))))

     iiiinnnntttt ccccllllAAAAddddddddPPPPaaaarrrraaaammmm((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, cccchhhhaaaarrrr ****nnnnaaaammmmeeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmTTTTyyyyppppeeee,,,,
         iiiinnnntttt mmmmiiiinnnn,,,, iiiinnnntttt mmmmaaaaxxxx,,,, iiiinnnntttt iiiinnnniiiittttiiiiaaaallll,,,, iiiinnnntttt ****ppppaaaarrrraaaammmmIIIIDDDD))))
     iiiinnnntttt ccccllllSSSSeeeettttDDDDeeeeffffaaaauuuulllltttt((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt iiiinnnniiiittttiiiiaaaallll))))
     iiiinnnntttt ccccllllSSSSeeeettttMMMMiiiinnnn((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt mmmmiiiinnnn))))
     iiiinnnntttt ccccllllSSSSeeeettttMMMMaaaaxxxx((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt mmmmaaaaxxxx))))
     iiiinnnntttt ccccllllSSSSeeeettttMMMMiiiinnnnMMMMaaaaxxxx((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt mmmmiiiinnnn,,,, iiiinnnntttt mmmmaaaaxxxx))))
     iiiinnnntttt ccccllllSSSSeeeettttRRRRaaaannnnggggeeee((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt mmmmiiiinnnn,,,, iiiinnnntttt mmmmaaaaxxxx,,,, iiiinnnntttt iiiinnnniiiittttiiiiaaaallll))))


     These calls support the addition of custom algorithms and parameters to
     the library.

     ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm installs a new codec given the functions that implement
     it.  ccccllllSSSSeeeettttUUUUnnnniiiiqqqquuuueeee and ccccllllGGGGeeeettttUUUUnnnniiiiqqqquuuueeee 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.
     ccccllllFFFFeeeettttcccchhhhPPPPaaaarrrraaaammmm and ccccllllSSSSttttoooorrrreeeePPPPaaaarrrraaaammmm are used by the codec implementation to
     directly access parameters in the handle.  (Users of the codec, however,
     should call the standard routines ccccllllGGGGeeeettttPPPPaaaarrrraaaammmm and ccccllllSSSSeeeettttPPPPaaaarrrraaaammmm.)  ccccllllEEEErrrrrrrroooorrrr is
     the active error handler function, and may be used by the codec
     implementation to report errors.

     ccccllllAAAAddddddddPPPPaaaarrrraaaammmm is used to extend the basic parameter list for new codecs.
     ccccllllSSSSeeeettttDDDDeeeeffffaaaauuuulllltttt, ccccllllSSSSeeeettttMMMMiiiinnnn, ccccllllSSSSeeeettttMMMMaaaaxxxx, ccccllllSSSSeeeettttMMMMiiiinnnnMMMMaaaaxxxx, and ccccllllSSSSeeeettttRRRRaaaannnnggggeeee 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.


   AAAAPPPPIIII FFFFOOOORRRR OOOOTTTTHHHHEEEERRRR FFFFEEEEAAAATTTTUUUURRRREEEESSSS

     iiiinnnntttt ccccllllCCCCoooommmmpppprrrreeeessssssssIIIImmmmaaaaggggeeee((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, iiiinnnntttt wwwwiiiiddddtttthhhh,,,, iiiinnnntttt hhhheeeeiiiigggghhhhtttt,,,,
         iiiinnnntttt ffffoooorrrrmmmmaaaatttt,,,, ffffllllooooaaaatttt ccccoooommmmpppprrrreeeessssssssiiiioooonnnnRRRRaaaattttiiiioooo,,,, vvvvooooiiiidddd ****ffffrrrraaaammmmeeeeBBBBuuuuffffffffeeeerrrr,,,,
         iiiinnnntttt ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrrSSSSiiiizzzzeeee,,,, vvvvooooiiiidddd ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrr))))
     iiiinnnntttt ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssssIIIImmmmaaaaggggeeee((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, iiiinnnntttt wwwwiiiiddddtttthhhh,,,, iiiinnnntttt hhhheeeeiiiigggghhhhtttt,,,,
         iiiinnnntttt ffffoooorrrrmmmmaaaatttt,,,, iiiinnnntttt ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrrSSSSiiiizzzzeeee,,,,
         vvvvooooiiiidddd ****ccccoooommmmpppprrrreeeesssssssseeeeddddBBBBuuuuffffffffeeeerrrr,,,, vvvvooooiiiidddd ****ffffrrrraaaammmmeeeeBBBBuuuuffffffffeeeerrrr))))

     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyyAAAAllllggggoooorrrriiiitttthhhhmmmmssss((((iiiinnnntttt aaaallllggggTTTTyyyyppppeeee,,,, iiiinnnntttt ****bbbbuuuuffffffffeeeerrrr,,,, iiiinnnntttt bbbbuuuuffffffffeeeerrrrLLLLeeeennnnggggtttthhhh))))



                                                                       PPPPaaaaggggeeee 11115555






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyySSSScccchhhheeeemmmmeeeeFFFFrrrroooommmmHHHHaaaannnnddddlllleeee((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee))))
     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyySSSScccchhhheeeemmmmeeeeFFFFrrrroooommmmNNNNaaaammmmeeee((((iiiinnnntttt aaaallllggggTTTTyyyyppppeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****nnnnaaaammmmeeee))))
     cccchhhhaaaarrrr ****ccccllllGGGGeeeettttAAAAllllggggoooorrrriiiitttthhhhmmmmNNNNaaaammmmeeee((((iiiinnnntttt sssscccchhhheeeemmmmeeee))))
     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyyLLLLiiiicccceeeennnnsssseeee((((iiiinnnntttt sssscccchhhheeeemmmmeeee,,,, iiiinnnntttt ffffuuuunnnnccccttttiiiioooonnnnaaaalllliiiittttyyyy,,,, cccchhhhaaaarrrr ********mmmmeeeessssssssaaaaggggeeee))))

     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyySSSScccchhhheeeemmmmeeee((((vvvvooooiiiidddd ****hhhheeeeaaaaddddeeeerrrr))))
     iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyyMMMMaaaaxxxxHHHHeeeeaaaaddddeeeerrrrSSSSiiiizzzzeeee((((iiiinnnntttt sssscccchhhheeeemmmmeeee))))
     iiiinnnntttt ccccllllRRRReeeeaaaaddddHHHHeeeeaaaaddddeeeerrrr((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt hhhheeeeaaaaddddeeeerrrrSSSSiiiizzzzeeee,,,, vvvvooooiiiidddd ****hhhheeeeaaaaddddeeeerrrr))))

     iiiinnnntttt ccccllllGGGGeeeettttNNNNeeeexxxxttttIIIImmmmaaaaggggeeeeIIIInnnnffffoooo((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,,
         CCCCLLLLiiiimmmmaaaaggggeeeeIIIInnnnffffoooo ****iiiimmmmaaaaggggeeeeIIIInnnnffffoooo,,,, iiiinnnntttt ssssiiiizzzzeeeeOOOOffffIIIImmmmaaaaggggeeeeIIIInnnnffffoooo))))

     CCCCLLLLeeeerrrrrrrrFFFFuuuunnnncccc ccccllllSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr((((CCCCLLLLeeeerrrrrrrrFFFFuuuunnnncccc eeeeffffuuuunnnncccc))))


     ccccllllCCCCoooommmmpppprrrreeeessssssssIIIImmmmaaaaggggeeee and ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssssIIIImmmmaaaaggggeeee 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.

     ccccllllQQQQuuuueeeerrrryyyyAAAAllllggggoooorrrriiiitttthhhhmmmmssss gives a list of algorithms recognized by the library.
     ccccllllQQQQuuuueeeerrrryyyySSSScccchhhheeeemmmmeeeeFFFFrrrroooommmmHHHHaaaannnnddddlllleeee and ccccllllQQQQuuuueeeerrrryyyySSSScccchhhheeeemmmmeeeeFFFFrrrroooommmmNNNNaaaammmmeeee return the scheme
     identifier from the handle and text name, respectively;
     ccccllllGGGGeeeettttAAAAllllggggoooorrrriiiitttthhhhmmmmNNNNaaaammmmeeee returns the text name from the scheme.  Some schemes
     must be enabled with a NetLS license (see the section on option
     products); ccccllllQQQQuuuueeeerrrryyyyLLLLiiiicccceeeennnnsssseeee is used to determine whether a license is
     available.

     Applications which need to read data generated by several algorithms may
     use ccccllllQQQQuuuueeeerrrryyyySSSScccchhhheeeemmmmeeee 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
     ccccllllQQQQuuuueeeerrrryyyyMMMMaaaaxxxxHHHHeeeeaaaaddddeeeerrrrSSSSiiiizzzzeeee and ccccllllRRRReeeeaaaaddddHHHHeeeeaaaaddddeeeerrrr.

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

     ccccllllSSSSeeeettttEEEErrrrrrrroooorrrrHHHHaaaannnnddddlllleeeerrrr allows an application to override the default error
     handler.  The default function prints a message to stderr.


OOOOPPPPTTTTIIIIOOOONNNN PPPPRRRROOOODDDDUUUUCCCCTTTTSSSS
     Some schemes must be enabled with the installation of separate option
     products.





                                                                       PPPPaaaaggggeeee 11116666






CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))                                                      CCCCLLLLiiiinnnnttttrrrroooo((((3333ddddmmmm))))



   MMMMPPPPEEEEGGGG EEEEnnnnccccooooddddeeeerrrr
     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).


   CCCCoooossssmmmmoooo CCCCoooommmmpppprrrreeeessssssss
     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.


   AAAAwwwwaaaarrrreeee AAAAuuuuddddiiiiooooPPPPuuuubbbblllliiiisssshhhheeeerrrr,,,, AAAAuuuuddddiiiiooooPPPPrrrroooodddduuuucccceeeerrrr,,,, aaaannnndddd AAAAuuuuddddiiiiooooPPPPllllaaaayyyybbbbaaaacccckkkk
     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).


FFFFIIIILLLLEEEESSSS
     /usr/include/dmedia/cl.h                        - header file
                                                        (including error codes)

     /usr/share/src/dmedia/dmrecord               - sample code
     /usr/share/src/dmedia/dmplay            - sample code


SSSSEEEEEEEE AAAALLLLSSSSOOOO
     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)




                                                                       PPPPaaaaggggeeee 11117777