CompressionLibrary man page on IRIX

Man page or keyword search:  
man Server   31559 pages
apropos Keyword Search (all sections)
Output format
IRIX logo
[printable version]



CLintro(3dm)							  CLintro(3dm)

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

SYNOPSIS
     #include <dmedia/cl.h>
     -lcl


DESCRIPTION
     The Compression Library provides an application programming interface for
     processing video and audio data using a variety of compression
     algorithms.

     Compression techniques are useful for extending the utility of system
     resources such as memory, disk space, and network bandwidth.  Some
     application areas include publishing (presentations, documentation,
     training, archiving, and annotation), telecommunications (video/voice
     mail, phone, and conferencing), animation previewing (2D/3D graphics
     renderings), and movie editing.

     The Compression Library is used by several Silicon Graphics digital media
     tools, including capture(1), movieplayer(1) and moviemaker(1).

ALGORITHMS
     The library focuses on accepted standards, as well as proprietary methods
     that have additional benefits.  Some algorithms are enabled with the
     installation of separate products (see the section on option products).

     The techniques currently supported are discussed below.  Note that each
     algorithm implementation has a corresponding "scheme" identifier that
     begins with the common library prefix, CL.	 Algorithms are grouped into
     two categories : video compression and audio compression.

   VIDEO COMPRESSION

     MPEG-1 Video (ISO 11172-2) is a video compression standard designed to
     exploit temporal as well as spatial redundancies in order to achieve good
     image quality at very high compression ratios; an MPEG-1 stream at 1.2
     Mbit/second (low enough for single-speed CD-ROMs) gives quality
     comparable to VHS video.  MPEG-1 is an asymmetrical technique, with
     compression being much more computationally demanding than decompression.
     Scheme is CL_MPEG1_VIDEO_SOFTWARE.

     JPEG (baseline) is a standard method for encoding individual images.
     Very good compressed quality (almost indistinguishable from the original)
     can be achieved at about 1.2 to 1.5 bits/pixel. Compression consists of
     frequency transformation, quantization, and entropy coding; decompression
     is the reverse.  Two versions of the JPEG algorithm are supported, an
     all-software implementation (scheme is CL_JPEG_SOFTWARE) and a hardware-

									Page 1

CLintro(3dm)							  CLintro(3dm)

     assisted version (scheme is CL_JPEG_COSMO).

     MVC1 (Motion Video Compressor 1) is an SGI proprietary algorithm. It is
     designed for efficient decompression of motion video.  Reasonable quality
     can be achieved at about 4.5 bits/pixel.  Scheme is CL_MVC1_SOFTWARE.

     MVC2 (Motion Video Compressor 2) is similar to MVC1, but can compress to
     about 2 bits/pixel with approximately the same quality.  Scheme is
     CL_MVC2_SOFTWARE.

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

     RLE (Run Length Encoding) is a lossless algorithm for compressing 8-bit
     RGB data.	Compression ratios are often 2:1 or less for many images, but
     may be higher for graphics scenes.	 Scheme is CL_RLE_SOFTWARE.

     RLE24 is run length encoding applied to 24-bit RGB data.  Scheme is
     CL_RLE24_SOFTWARE.

     An "uncompressed" video algorithm is also supported.  This allows
     uncompressed data to be handled without alteration using the same library
     interface that is used for compressing data, which may be convenient for
     some applications.	 Scheme is CL_UNCOMPRESSED_VIDEO.

     The performance of these techniques for one test sequence is shown below.
     Results will vary with other data sequences and compression parameters,
     and may change with newer implementations.

     Table 1: Video Algorithms - Performance Example

					     320 by 240 frames on Indy R4400
		     Comp.     Average	     bits/s	     frames/second
     Algorithm	     Ratio     bits/pixel      at	   compress
					     30 f/s		   decompress
     Uncompressed    1:1       24	     55.30M	   -	   -
     MPEG-1	     48:1      0.5	     1.16M	   0.5	   17.5
     JPEG (software) 33:1      0.7	     1.66M	   3.1	   7.2
     MVC1	     8:1       3.1	     7.10M	   11.7	   83.9
     MVC2	     19:1      1.3	     2.92M	   10.0	   89.7
     MVC3	     14:1      1.7	     3.96M	   9.3	   17.6
     RLE	     6:1       3.9	     8.90M	   20.3	   39.4
     RLE24	     6:1       4.2	     9.76M	   43.3	   20.3

   AUDIO COMPRESSION

     MPEG-1 Audio (ISO 11172-3) is an audio compression standard based on
     subband coding and perceptual bit allocation.  The core engine is
     licensed from Aware, Inc.	Two interfaces are provided by the Compression
     Library - one that accesses the Aware codec directly (scheme is

									Page 2

CLintro(3dm)							  CLintro(3dm)

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

     Aware Multirate is an Aware proprietary technique that provides lossless
     to near-lossless quality.	Compression ratios are typically 2:1 to 5:1.
     Scheme is CL_MULTIRATE_AWARE.

     G711 u-law is a simple 16-bit to 8-bit conversion that uses coarse
     quantization at high volumes and fine quantization at low volumes.	 It is
     a standard encoding format in the U.S.  Scheme is CL_G711_ULAW_SOFTWARE.

     G711 A-law also performs 16-bit to 8-bit conversion, but with a slightly
     different mapping.	 It is a standard encoding format in Europe.  Scheme
     is CL_G711_ALAW_SOFTWARE.

     An "uncompressed" audio algorithm is also supported.  Scheme is
     CL_UNCOMPRESSED_AUDIO.

     The performance of these techniques for one test sequence is shown below.

     Table 2: Audio Algorithms - Performance Example

				       2x16-bit (stereo) frames on Indy R4400
		     Comp.    Average	   bits/s	 frames/second
     Algorithm	     Ratio    bits/samp	     at	       compress
					  44.1 KHz	       decompress
     Uncompressed    1:1      16.0	  1.41M	       -       -
     MPEG-1	     7:1      2.2	  192K	       54.6K   163.8K
     Multirate	     5:1      3.4	  296K	       179.2K  220.5K
     u-law	     2:1      8.0	  706K	       1.17M   2.21M
     A-law	     2:1      8.0	  706K	       1.79M   2.05M

DATA FORMATS
     The Compression Library recognizes the following video and audio formats.

   VIDEO FORMATS

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

									Page 3

CLintro(3dm)							  CLintro(3dm)

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

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

     CL_FORMAT_BGR means R, G, and B data are packed into a 24-bit word. Note
     that with this format, the RGB triplets may cross 32-bit word boundaries.

     CL_FORMAT_BGR332 means R, G, and B data are packed into a byte as:

	      rrrbbggg
		  where:
		      rrr  is three bits of red.
		      bb   is two bits of blue.
		      ggg  is three bits of green.

     CL_FORMAT_BGR233 means R, G, and B data are packed into a byte as:

	      bbgggrrr
		  where:
		      bb   is two bits of blue.
		      ggg  is three bits of green.
		      rrr  is three bits of red.

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

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

									Page 4

CLintro(3dm)							  CLintro(3dm)

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

     CL_FORMAT_YCbCr422 means that two luminance components are packed into a
     32-bit word with one Cb-Cr pair (i.e., chroma components are sampled with
     half of the horizontal rate of the luma). The order of the components is:

	      0xCbY1CrY2
		  where:
		      Cb  contains the chroma-blue value.
		      Y1  contains the first luminance value.
		      Cr  contains the chroma-red value.
		      Y2  contains the second luminance value.

     This 32-bit word represents two pixels (Y1, Cb, Cr) and (Y2, Cb, Cr).

     CL_FORMAT_YCbCr422DC (duplicate chroma) means that the chroma are sub-
     sampled by 2 vertically in addition to horizontally, and are packed the
     same as CL_FORMAT_YCbCr422 except that Cb & Cr are duplicated on the odd
     lines.

     The YCbCr formats use CCIR 601 style scaling and biasing of components.
     This means that the nominal range of an eight bit Y component is
     [16...235].

   AUDIO FORMATS

     CL_FORMAT_MONO means that the audio samples represent a single channel.

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

PROGRAMMING INTERFACE
     The operations supported by the Compression Library are compression and
     decompression.  The application programming interface is described in
     several parts : processing data, managing implicit buffers, managing
     parameters, adding algorithms and parameters, and other features.	This
     description provides an overview of the API calls.	 Further details on
     each call are available from the corresponding man page.

   API FOR PROCESSING DATA

     int clOpenCompressor(int scheme, CLhandle *compressorHdl)
     int clCompress(CLhandle compressorHdl, int numberOfFrames,
	 void *frameBuffer, int *compressedBufferSize, void *compressedBuffer)

									Page 5

CLintro(3dm)							  CLintro(3dm)

     int clCloseCompressor(CLhandle compressorHdl)

     int clOpenDecompressor(int scheme, CLhandle *decompressorHdl)
     int clDecompress(CLhandle decompressorHdl, int numberOfFrames,
	 int compressedBufferSize, void *compressedBuffer, void *frameBuffer)
     int clCloseDecompressor(CLhandle decompressorHdl)

     Each processing operation (compress, decompress) has a corresponding
     object, or CLhandle, which is used to maintain state across processing
     calls.  First, the object is created with an "Open" call.	Then,
     processing is performed with one or more "Execute" calls.	Finally, when
     no more data needs to be processed the object is destroyed with a "Close"
     call.

     The example below illustrates how to compress a series of 320 by 240 XBGR
     images using MVC1:

     Example (compression)

     | CLhandle compressorHdl;
     | int frameBuffer[320][240];
     | int compressedBufferSize;
     | void *compressedBuffer;
     | int k, numberOfFrames;
     |
     | /* Create and configure the object */
     | clOpenCompressor(CL_MVC1_SOFTWARE, &compressorHdl);
     | clSetParam(compressorHdl, CL_IMAGE_WIDTH, 320);
     | clSetParam(compressorHdl, CL_IMAGE_HEIGHT, 240);
     | clSetParam(compressorHdl, CL_FORMAT, CL_FORMAT_XBGR);
     |
     | /* Allocate space for compressed buffer */
     | compressedBufferSize = clGetParam(compressorHdl,
     |					 CL_COMPRESSED_BUFFER_SIZE);
     | compressedBuffer = malloc(compressedBufferSize);
     |
     | /* Compress and write out each frame */
     | for (k = 0; k < numberOfFrames; k++) {
     |	 GetVideo(k, frameBuffer);
     |	 clCompress(compressorHdl, 1, frameBuffer,
     |		    &compressedBufferSize, compressedBuffer);
     |	 write(fd, compressedBuffer, compressedBufferSize);
     | }
     |
     | /* Destroy the object */
     | clCloseCompressor(compressorHdl);

     GetVideo reads frame k from the video source.  clSetParam and clGetParam,
     used here to configure and query the compressor, are discussed in a later
     section (API for Managing Parameters).

									Page 6

CLintro(3dm)							  CLintro(3dm)

     Buffering Models

     Compressors operate on an input "frame" buffer and an output "compressed"
     buffer; decompressors reverse this direction. These buffers are specified
     to the processing calls using one of two buffering models.

     1. Direct	 - buffer is given as argument to processing call

	o For clCompress and clDecompress, frameBuffer/compressedBuffer
	  is set to some application-allocated memory (or set to
	  CL_EXTERNAL_DEVICE, currently supported by CL_JPEG_COSMO).

     2. Implicit - buffer is set up prior to processing call

	o For clCompress and clDecompress, frameBuffer/compressedBuffer is
	  set to NULL.

     The previous example uses the Direct model, which is the simpler of the
     two.  The Implicit model is more complicated (requiring several
     additional calls such as clCreateBuf and clDestroyBuf), but provides
     several benefits described in the next section.  Note that it is possible
     to mix the two models in one call (e.g. clCompress may be called with
     frameBuffer=CL_EXTERNAL_DEVICE and compressedBuffer=NULL).

   API FOR MANAGING IMPLICIT BUFFERS

     CLbufferHdl clCreateBuf(CLhandle handle, int bufferType,
	 int blocks, int blockSize, void **buffer)
     int clDestroyBuf(CLbufferHdl bufferHdl)
     CLbufferHdl clQueryBufferHdl(CLhandle handle,
	 int bufferType, void **buffer)
     CLhandle clQueryHandle(CLbufferHdl bufferHdl)

     int clQueryFree(CLbufferHdl bufferHdl, int freeAmount,
	 void **freeData, int *freeWrap)
     int clUpdateHead(CLbufferHdl bufferHdl, int amountToAdd)
     int clQueryValid(CLbufferHdl bufferHdl, int validAmount,
	 void **validData, int *validWrap)
     int clUpdateTail(CLbufferHdl bufferHdl, int amountToRelease)
     int clDoneUpdatingHead(CLbufferHdl bufferHdl)

     Implicit buffers are ring buffers created and managed separately from the
     processing calls.	A ring buffer contains a number of blocks of arbitrary
     size and maintains a pointer to the buffer space, the capacity, and
     pointers to the head of (newest) and tail of (oldest) valid data.

     The Implicit buffering model facilitates decompression of streaming data
     by freeing the application from having to know about data boundaries, and
     conveniently supports multiple input or output buffers necessary for
     multiplexed data.	Separating buffer management calls from data

									Page 7

CLintro(3dm)							  CLintro(3dm)

     processing calls also allows an application to be implemented with
     multiple threads for input, processing, and output.  The ring buffers
     support synchronization with a blocking access mode.

     The buffer management calls allow applications to create, access, and
     destroy ring buffers.  Compressors and decompressors have buffers of type
     CL_BUF_FRAME and CL_BUF_COMPRESSED.

     clCreateBuf and clDestroyBuf create and destroy a ring buffer,
     respectively.  The actual buffer memory may be allocated by the
     application by passing in a non-NULL buffer to the creation function; if
     buffer is NULL, the library will allocate the memory.  clQueryBufferHdl
     returns the ring buffer of specified type given a processing object;
     clQueryHandle returns the processing object given a ring buffer.

     A ring buffer producer calls clQueryFree and clUpdateHead to add data to
     the buffer.  clQueryFree gives the size and location of free space in a
     buffer.  If the requested amount is positive, the calling process will
     block until that amount is available.  If the requested amount is zero,
     then the query will return immediately.  clUpdateHead advances the ring
     buffer head pointer to indicate newly written data.  A ring buffer
     consumer calls clQueryValid and clUpdateTail, which are complementary
     calls for querying valid data and reading from the tail of the buffer.
     The producer should call clDoneUpdatingHead when no more data is to be
     written.  This allows clQueryValid to return to the consumer instead of
     blocking for data that will never arrive.

     The following code segments illustrate how to use implicit buffers.

     Example (implicit buffering model - record)

     | /* Create the frame (input) and compressed (output) buffers */
     | frameBufferHdl = clCreateBuf(compressorHdl, CL_BUF_FRAME,
     |				    numberOfFrames, bytesPerFrame, NULL);
     | compressedBufferHdl = clCreateBuf(compressorHdl, CL_BUF_COMPRESSED,
     |					 compressedBufferSize, 1, NULL);
     |
     | /* Write a frame from screen to buffer */
     | clQueryFree(frameBufferHdl, 1, &frameBuffer, &wrap);
     | lrectread(0, 0, width - 1, height - 1, frameBuffer);
     | clUpdateHead(frameBufferHdl, 1);
     |
     | /* Compress the frame */
     | clCompress(compressorHdl, 1, NULL, &compressedBufferSize, NULL);
     |
     | /* Copy compressed bytes to file */
     | while ((size=clQueryValid(compressedBufferHdl, 0, &buf, &wrap)) > 0) {
     |	 write(fd, buf, size);
     |	 clUpdateTail(compressedBufferHdl, size);
     | }

     Example (implicit buffering model - playback)

									Page 8

CLintro(3dm)							  CLintro(3dm)

     | /* Fill the compressed buffer */
     | while ((size=clQueryFree(compressedBufferHdl, 0, &buf, &wrap)) > 0) {
     |	 read(fd, buf, size);
     |	 clUpdateHead(compressedBufferHdl, size);
     | }
     |
     | /* Decompress a frame */
     | clDecompress(decompressorHdl, 1, 0, NULL, NULL);
     |
     | /* Read and display the frame */
     | clQueryValid(frameBufferHdl, 1, &frameBuffer, &wrap);
     | lrectwrite(0, 0, width-1, height-1, frameBuffer);
     | clUpdateTail(frameBufferHdl, 1);

     Example (implicit buffering model - multiprocess record)

     | ProduceFrameProcess() :
     | while (1) {
     |	 clQueryFree(frameBufferHdl, 1, &frameBuffer, &wrap);
     |	 lrectread(0, 0, width - 1, height - 1, frameBuffer);
     |	 clUpdateHead(frameBufferHdl, 1);
     | }
     |
     | CompressProcess() :
     | while (1)
     |	 clCompress(compressorHdl, 1, NULL, &compressedBufferSize, NULL);
     |
     | ConsumeCompressedDataProcess() :
     | while (1) {
     |	 size = clQueryValid(compressedBufferHdl, 0, &buf, &wrap);
     |	 write(fd, buf, size);
     |	 clUpdateTail(compressedBufferHdl, size);
     | }

     Example (implicit buffering model - multiprocess playback)

     | ProduceCompressedDataProcess() :
     | while (1) {
     |	 size = clQueryFree(compressedBufferHdl, 0, &buf, &wrap);
     |	 read(fd, buf, size);
     |	 clUpdateHead(compressedBufferHdl, size);
     | }
     |
     | DecompressProcess() :
     | while (1)
     |	 clDecompress(decompressorHdl, 1, 0, NULL, NULL);
     |
     | ConsumeFrameProcess() :
     | while (1) {
     |	 clQueryValid(frameBufferHdl, 1, &frameBuffer, &wrap);
     |	 lrectwrite(0, 0, width - 1, height - 1, frameBuffer);
     |	 clUpdateTail(frameBufferHdl, 1);

									Page 9

CLintro(3dm)							  CLintro(3dm)

     | }

   API FOR MANAGING PARAMETERS

     int clQueryParams(CLhandle handle,
	 int *paramValueBuffer, int bufferLength)
     int clGetParamID(CLhandle handle, char *paramName)

     int clGetParams(CLhandle handle,
	 int *paramValueBuffer, int bufferLength)
     int clSetParams(CLhandle handle,
	 int *paramValueBuffer, int bufferLength)
     int clGetParam(CLhandle handle, int paramID)
     int clSetParam(CLhandle handle, int paramID, int value)

     int clGetDefault(CLhandle handle, int paramID)
     int clGetMinMax(CLhandle handle, int paramID, int *min, int *max)
     char *clGetName(CLhandle handle, int paramID)

     Operations in the Compression Library are guided and monitored through
     the use of various parameters.  Each compressor or decompressor object
     has a list of parameters that is accessible through querying, setting,
     and getting.  Each parameter has an identifier (paramID) and a text name
     (paramName).

     clQueryParams is used to determine what parameters are defined for an
     object.  clGetParamID returns the parameter identifier used in other
     calls.  clGetParams, clSetParams, clGetParam, and clSetParam are used to
     read and write groups of parameters or individual parameters.
     clGetDefault, clGetMinMax, and clGetName are used to determine defaults,
     ranges, and text names.

     Each parameter is classified as one of the following types.  Individual
     algorithms may impose further restrictions on parameter values in
     addition to those implied by the parameter type.

	CL_ENUM_VALUE		only certain constant values are valid
	CL_RANGE_VALUE		any value in a given range is valid
	CL_FLOATING_ENUM_VALUE	only certain constant floating point values
				are valid
	CL_FLOATING_RANGE_VALUE any value in a given floating point range
				is valid

     Below is the list of basic parameters common to all processing objects,
     identified by paramID.  Note that not all parameters are useful for all
     schemes (e.g. image dimensions are ignored by audio compressors).	Also,
     some parameters are designated read-only, indicating that they should not
     be set.

								       Page 10

CLintro(3dm)							  CLintro(3dm)

     CL_IMAGE_WIDTH, CL_IMAGE_HEIGHT
	  Type: CL_RANGE_VALUE
	  Horizontal and vertical dimensions of uncompressed image.  For
	  compressors, these should be set to match the input dimensions.
	  For most decompressors, this is a read-only parameter.  For
	  decompressors that support scaling (CL_JPEG_COSMO), this may be
	  set to configure the output dimensions.

     CL_INTERNAL_IMAGE_WIDTH, CL_INTERNAL_IMAGE_HEIGHT
	  Type: CL_RANGE_VALUE
	  Horizontal and vertical dimensions of the encoded image.
	  For most compressors, these default to CL_IMAGE_WIDTH and
	  CL_IMAGE_HEIGHT.  For compressors that support scaling
	  (CL_MPEG1_VIDEO_SOFTWARE, CL_JPEG_COSMO), setting different
	  values causes the input image to be scaled to the internal
	  dimensions prior to compression.  For decompressors, these
	  parameters are read-only.

     CL_IMAGE_CROP_LEFT, CL_IMAGE_CROP_RIGHT,
     CL_IMAGE_CROP_TOP, CL_IMAGE_CROP_BOTTOM
	  Type: CL_RANGE_VALUE
	  Cropping parameters.	For compressors that support cropping
	  (CL_MPEG1_VIDEO_SOFTWARE), these may be set to indicate how many
	  pixels should be cropped from the left, right, top, and bottom
	  borders of the input image.  If combined with scaling, the order
	  of operations is input->crop->scale->compress.

     CL_FORMAT
	  Type: CL_RANGE_VALUE
	  Format of the uncompressed data (e.g. CL_FORMAT_YCbCr or
	  CL_FORMAT_MONO).  For compressors, this should be set to match
	  the input format.  For video decompressors, this may be set to
	  indicate the desired output format.  For audio decompressors, this
	  is a read-only parameter.  Currently, the format is restricted to
	  CL_FORMAT_XBGR for CL_JPEG_COSMO and CL_MVC2_SOFTWARE.

     CL_INTERNAL_FORMAT
	  Type: CL_RANGE_VALUE
	  Internal format used by video schemes.  If this is different from
	  CL_FORMAT, color space conversion is performed from CL_FORMAT to
	  CL_INTERNAL_FORMAT on compression, and vice versa for decompression.
	  For compressors, the following internal formats may be set.

	  Scheme		  Internal Formats
	  ------		  ----------------
	  CL_MPEG1_VIDEO_SOFTWARE CL_FORMAT_YCbCr422DC
	  CL_JPEG_SOFTWARE	  CL_FORMAT_YCbCr, CL_FORMAT_YCbCr422,
				  CL_FORMAT_GRAYSCALE
	  CL_JPEG_COSMO		  CL_FORMAT_YCbCr422
	  CL_MVC1_SOFTWARE	  CL_FORMAT_XBGR, CL_FORMAT_GRAYSCALE
	  CL_MVC2_SOFTWARE	  CL_FORMAT_XBGR
	  CL_MVC3_SOFTWARE	  CL_FORMAT_YCbCr, CL_FORMAT_YCbCr422,

								       Page 11

CLintro(3dm)							  CLintro(3dm)

				  CL_FORMAT_YCbCr422DC, CL_FORMAT_GRAYSCALE
	  CL_RLE_SOFTWARE	  CL_FORMAT_BGR332
	  CL_RLE24_SOFTWARE	  CL_FORMAT_XBGR

	  For decompressors, this is a read-only parameter.

     CL_COMPONENTS
	  Type: CL_RANGE_VALUE
	  The number of components in the format, e.g. 1 for CL_FORMAT_MONO,
	  2 for CL_FORMAT_STEREO_INTERLEAVED, 4 for CL_FORMAT_ABGR.  This is
	  a read-only parameter determined from CL_FORMAT.

     CL_BITS_PER_COMPONENT
	  Type: CL_RANGE_VALUE
	  For audio compressors, this may be set to indicate the input sample
	  width (8 or 16 bits); G711 u-law and A-law accept only 16 bit inputs.
	  For audio decompressors, this is a read-only parameter which gives
	  the output sample width.

     CL_FRAME_RATE
	  Type: CL_FLOATING_RANGE_VALUE
	  The frames per second of video or audio.  For compressors that use
	  this information (MPEG-1 Video and Audio), this should be set to
	  match the frame rate of the input.  For decompressors, this is a
	  read-only parameter.

     CL_ORIENTATION
	  Type: CL_ENUM_VALUE
	  Image orientation, either CL_TOP_DOWN or CL_BOTTOM_UP.  For video
	  compressors, this should be set to match the input images.  For
	  video decompressors, this may be set to indicate the desired
	  output orientation.  CL_JPEG_COSMO supports only CL_TOP_DOWN.

     CL_PIXEL_ASPECT
	  Type: CL_FLOATING_RANGE_VALUE
	  Pixel aspect ratio, defined as the vertical extent of a pixel divided
	  by its horizontal extent.  For video compressors, this should be set
	  to indicate the aspect ratio of the input pixels.  For video
	  decompressors, this is a read-only parameter.

     CL_COMPRESSION_RATIO
	  Type: CL_FLOATING_RANGE_VALUE
	  The target compression ratio, including effects of cropping and
	  scaling.  For compressors, this parameter may be set to indicate
	  the degree of compression desired.

     CL_EXACT_COMPRESSION_RATIO
	  Type: CL_RANGE_VALUE
	  A read-only flag which indicates whether a compressor is able to
	  achieve compression ratio targets.  If this flag is TRUE, the average
	  compression ratio over many frames should be very close to the
	  value of CL_COMPRESSION_RATIO.  If this flag is FALSE, then setting

								       Page 12

CLintro(3dm)							  CLintro(3dm)

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

     CL_BITRATE
	  Type : CL_RANGE_VALUE
	  The rate of the sequence in bits per second.	This may be set on
	  compression to select a target bitrate.  On decompression, this
	  is a read-only parameter.  Currently supported by
	  CL_MPEG1_VIDEO_SOFTWARE, CL_MPEG1_AUDIO_SOFTWARE, and (Cosmo) JPEG.

     CL_FRAMES_PER_CHUNK
	  Type: CL_RANGE_VALUE
	  A read-only parameter which gives the number of frames in a "chunk".
	  clCompress and clDecompress should be called with numberOfFrames
	  equal to an integer multiple of CL_FRAMES_PER_CHUNK.	For most
	  schemes, CL_FRAMES_PER_CHUNK is 1, so this is not a significant
	  restriction.	For MPEG-1 Audio, this parameter is either 384 or
	  1152.

     CL_FRAME_SIZE
	  Type: CL_RANGE_VALUE
	  A read-only parameter which equals the number of bytes in one
	  frame of uncompressed data.  This value is calculated based on
	  CL_FORMAT, CL_IMAGE_WIDTH, CL_IMAGE_HEIGHT, CL_COMPONENTS and
	  CL_BITS_PER_COMPONENT.  A frame is defined as the data corresponding
	  to a single time instant.  One video frame consists of width*height
	  pixels.  One audio frame consists of 1 mono sample or 2 stereo
	  samples.

     CL_COMPRESSED_BUFFER_SIZE
	  Type: CL_RANGE_VALUE
	  A read-only parameter which gives the maximum number of bytes
	  generated by compressing CL_FRAMES_PER_CHUNK frames.	The value
	  may depend on other parameters such as CL_IMAGE_WIDTH and
	  CL_IMAGE_HEIGHT.  This parameter should be used to allocate enough
	  space for a compressor's output buffer and a decompressor's input
	  buffer so that clCompress and clDecompress do not block.

     CL_FRAME_TYPE
	  Type: CL_RANGE_VALUE
	  A read-only parameter for decompressors which indicates the
	  type of frame most recently decoded.	May be CL_INTRA (same
	  as CL_KEYFRAME), CL_PREDICTED, CL_BIDIRECTIONAL, or CL_NONE.

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

     CL_NUMBER_OF_FRAMES
	  Type: CL_RANGE_VALUE
	  The number of frames in the video or audio sequence.	For
	  compressors, this should be set (if known) since some schemes

								       Page 13

CLintro(3dm)							  CLintro(3dm)

	  include this data in the header.  For decompressors, this parameter
	  is read-only and is available after calling clReadHeader; the value
	  may be zero if the number of frames is not listed in the header.

     CL_SPEED
	  Type: CL_FLOATING_RANGE_VALUE
	  The relative speed of playback.  For decompressors that support
	  variable rate decoding, this parameter may be set to adjust playback
	  speed.  Ranges are scheme-specific but, in general, 1.0 is the
	  default and higher values correspond to faster decoding (at the
	  expense of some quality loss).

     CL_PREROLL
	  Type: CL_RANGE_VALUE
	  A read-only parameter which gives the number of chunks of frames
	  that must be decompressed before valid frames are returned.
	  Currently not used.

     CL_ENABLE_IMAGEINFO
	  Type: CL_RANGE_VALUE
	  This parameter is used to enable the clGetNextImageInfo call
	  for video compressors or decompressors.  To enable the call,
	  CL_ENABLE_IMAGEINFO should be set to TRUE before invoking
	  clCompress or clDecompress.  This is currently supported for
	  CL_JPEG_COSMO.

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

     CL_ALGORITHM_VERSION
	  Type: CL_RANGE_VALUE
	  The algorithm version number.	 This is a read-only parameter for
	  all processing objects.

     Note that some parameters, such as CL_COMPRESSED_BUFFER_SIZE, depend on
     other parameters and should not be read until other parameters are set.
     For decompressors, parameters are generally valid after clReadHeader is
     called.

     Some algorithms and products have additional parameters which extend this
     basic set.	 See cl_mpeg1(3dm), cl_jpeg(3dm), cl_mvc2(3dm), and
     cl_mvc3(3dm) for algorithm-specific parameters. See cl_cosmo(3dm) and
     cl_aware(3dm) for product-specific parameters.

   API FOR ADDING ALGORITHMS AND PARAMETERS

     int clAddAlgorithm(char *name, int algType, int maxHeaderSize,
	 FunctionPtr openCompressor, FunctionPtr compress,
	 FunctionPtr closeCompressor,

								       Page 14

CLintro(3dm)							  CLintro(3dm)

	 FunctionPtr openDecompressor, FunctionPtr decompress,
	 FunctionPtr closeDecompressor,
	 FunctionPtr readHeader, FunctionPtr queryScheme,
	 FunctionPtr queryLicense,
	 FunctionPtr getParams, FunctionPtr setParams,
	 int *scheme)
     void *clSetUnique(CLhandle handle, void *unique)
     void *clGetUnique(CLhandle handle)
     int  clFetchParam(CLhandle handle, int paramID)
     void clStoreParam(CLhandle handle, int paramID, int value)
     void clError(CLhandle handle, int code, const char *format, ...)

     int clAddParam(int scheme, char *name, int paramType,
	 int min, int max, int initial, int *paramID)
     int clSetDefault(int scheme, int paramID, int initial)
     int clSetMin(int scheme, int paramID, int min)
     int clSetMax(int scheme, int paramID, int max)
     int clSetMinMax(int scheme, int paramID, int min, int max)
     int clSetRange(int scheme, int paramID, int min, int max, int initial)

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

     clAddAlgorithm installs a new codec given the functions that implement
     it.  clSetUnique and clGetUnique allow the codec implementation to save
     and retrieve a private data structure with each codec object, enabling
     unique state information to be retained across processing calls.
     clFetchParam and clStoreParam are used by the codec implementation to
     directly access parameters in the handle.	(Users of the codec, however,
     should call the standard routines clGetParam and clSetParam.)  clError is
     the active error handler function, and may be used by the codec
     implementation to report errors.

     clAddParam is used to extend the basic parameter list for new codecs.
     clSetDefault, clSetMin, clSetMax, clSetMinMax, and clSetRange are used to
     configure a parameter after it is added.

     Once installed with these calls, new algorithms and their parameters may
     be accessed with the same API used for the base schemes.

   API FOR OTHER FEATURES

     int clCompressImage(int scheme, int width, int height,
	 int format, float compressionRatio, void *frameBuffer,
	 int *compressedBufferSize, void *compressedBuffer)
     int clDecompressImage(int scheme, int width, int height,
	 int format, int compressedBufferSize,
	 void *compressedBuffer, void *frameBuffer)

     int clQueryAlgorithms(int algType, int *buffer, int bufferLength)

								       Page 15

CLintro(3dm)							  CLintro(3dm)

     int clQuerySchemeFromHandle(CLhandle handle)
     int clQuerySchemeFromName(int algType, const char *name)
     char *clGetAlgorithmName(int scheme)
     int clQueryLicense(int scheme, int functionality, char **message)

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

     int clGetNextImageInfo(CLhandle handle,
	 CLimageInfo *imageInfo, int sizeOfImageInfo)

     CLerrFunc clSetErrorHandler(CLerrFunc efunc)

     clCompressImage and clDecompressImage provide a simple way to process
     individual video frames in one call; the application does not need to
     open and close a compressor or decompressor.  Note, however, that these
     calls do not save state between invocations so algorithms that have
     dependencies between frames (e.g. MPEG-1 Video) should not be used.
     Also, these calls do not allow general parameter modification and are not
     compatible with implicit buffers.

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

     Applications which need to read data generated by several algorithms may
     use clQueryScheme to determine the appropriate decompressor to use.  This
     call attempts to identify the algorithm based on the first 16 bytes of
     data so that the correct processing object may be opened.	Once opened,
     the decompressor should be configured by reading the header with
     clQueryMaxHeaderSize and clReadHeader.

     clGetNextImageInfo is used to obtain information about images as they are
     compressed or decompressed.  This call is currently supported by the
     CL_JPEG_COSMO scheme, and provides information such as time stamps and
     image counts.

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

OPTION PRODUCTS
     Some schemes must be enabled with the installation of separate option
     products.

								       Page 16

CLintro(3dm)							  CLintro(3dm)

   MPEG Encoder
     This product includes the CL_MPEG1_VIDEO_SOFTWARE and
     CL_MPEG1_AUDIO_SOFTWARE compressors.  The audio compressor may also
     enabled by a license from Aware, Inc. (see below).

   Cosmo Compress
     This hardware product enables the CL_JPEG_COSMO scheme, which offers
     accelerated JPEG compression and decompression for realtime video capture
     and playback.  Cosmo is supported on Indy and Indigo2 systems.

   Aware AudioPublisher, AudioProducer, and AudioPlayback
     These products provide various levels of NetLS licenses for MPEG-1 Audio
     (CL_MPEG1_AUDIO_SOFTWARE, CL_MPEG1_AUDIO_AWARE) and Aware Multirate
     (CL_MULTIRATE_AWARE).

     For more details see cl_aware(3dm) and cl_mpeg1(3dm).

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

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

SEE ALSO
     clOpenCompressor(3dm), clCompress(3dm), clCloseCompressor(3dm),
     clOpenDecompressor(3dm), clDecompress(3dm), clCloseDecompressor(3dm),
     clCreateBuf(3dm), clDestroyBuf(3dm),
     clQueryBufferHdl(3dm), clQueryHandle(3dm),
     clQueryFree(3dm), clUpdateHead(3dm), clQueryVaild(3dm),
     clUpdateTail(3dm), clDoneUpdatingHead(3dm),
     clQueryParams(3dm), clGetParamID(3dm),
     clGetParams(3dm), clSetParams(3dm),
     clGetDefault(3dm), clGetMinMax(3dm), clGetName(3dm),
     clAddAlgorithm(3dm), clSetUnique(3dm), clGetUnique(3dm),
     clFetchParam(3dm), clStoreParam(3dm), clError(3dm),
     clAddParam(3dm), clSetDefault(3dm), clSetMin(3dm), clSetMax(3dm),
     clSetMinMax(3dm), clSetRange(3dm),
     clCompressImage(3dm), clDecompressImage(3dm),
     clQueryAlgorithms(3dm), clQuerySchemeFromHandle(3dm),
     clQuerySchemeFromName(3dm), clGetAlgorithmName(3dm), clQueryLicense(3dm),
     clQueryScheme(3dm), clQueryMaxHeaderSize(3dm), clReadHeader(3dm),
     clGetNextImageInfo(3dm), clSetErrorHandler(3dm),
     mpeg(4), jpeg(4),
     cl_mpeg1(3dm), cl_jpeg(3dm), cl_mvc2(3dm), cl_mvc3(3dm),
     cl_cosmo(3dm), cl_aware(3dm),
     dmconvert(1), dmrecord(1), dmplay(1)

								       Page 17

[top]

List of man pages available for IRIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net