*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> old-compression/CLintro (3d)              



CLintro(3dm)							  CLintro(3dm)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #include <dmedia/cl.h>

DESCRIPTION    [Toc]    [Back]

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

     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), movieplay

ALGORITHMS    [Toc]    [Back]

     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    [Toc]    [Back]

     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.

     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

     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

     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    [Toc]    [Back]

     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

     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    [Toc]    [Back]

     The Compression Library recognizes	the following video and	audio formats.

   VIDEO FORMATS    [Toc]    [Back]

     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)

		      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:

		      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:

		      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

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

									Page 4

CLintro(3dm)							  CLintro(3dm)

		      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:

		      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 subsampled
 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

     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

   AUDIO FORMATS    [Toc]    [Back]

     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.


     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    [Toc]    [Back]

     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"

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

     Example (compression)    [Toc]    [Back]

     | 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,
     | 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    [Toc]    [Back]

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


     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

     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)    [Toc]    [Back]

     | /* 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)    [Toc]    [Back]

									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)    [Toc]    [Back]

     | 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)    [Toc]    [Back]

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

     | }


     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

     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)

	  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.

	  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.

	  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    [Toc]    [Back]
	  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_INTERNAL_FORMAT    [Toc]    [Back]
	  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
	  ------		  ----------------

								       Page 11

CLintro(3dm)							  CLintro(3dm)


	  For decompressors, this is a read-only parameter.

     CL_COMPONENTS    [Toc]    [Back]
	  The number of	components in the format, e.g. 1 for CL_FORMAT_MONO,
	  a read-only parameter	determined from	CL_FORMAT.

     CL_BITS_PER_COMPONENT    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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_FRAMES_PER_CHUNK    [Toc]    [Back]
	  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

     CL_FRAME_SIZE    [Toc]    [Back]
	  A read-only parameter	which equals the number	of bytes in one
	  frame	of uncompressed	data.  This value is calculated	based on
	  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

     CL_COMPRESSED_BUFFER_SIZE    [Toc]    [Back]
	  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    [Toc]    [Back]
	  A read-only parameter	for decompressors which	indicates the
	  type of frame	most recently decoded.	May be CL_INTRA	(same

     CL_FRAME_INDEX    [Toc]    [Back]
	  A read-only parameter	for decompressors which	indicates the
	  index	of the frame most recently decoded.

     CL_NUMBER_OF_FRAMES    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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_ALGORITHM_ID    [Toc]    [Back]
	  The algorithm	identifier (e.g. CL_MPEG1_VIDEO_SOFTWARE).  This is
	  a read-only parameter	for all	processing objects.

     CL_ALGORITHM_VERSION    [Toc]    [Back]
	  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

     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.


     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    [Toc]    [Back]

     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)    [Toc]    [Back]

     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

     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    [Toc]    [Back]

     Some schemes must be enabled with the installation	of separate option

								       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    [Toc]    [Back]
     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

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

FILES    [Toc]    [Back]

     /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    [Toc]    [Back]

     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
[ Back ]
 Similar pages
Name OS Title
dmDVIAudioDecode IRIX decode audio data compressed using the IMA
dmMPEG1AudioHeaderGetParams IRIX get decoder parameter information from a header of any compressed MPEG1 audio data block.
vintovout IRIX Video Library video output from video input tool
clAddParam IRIX Add a video or audio compression parameter to the Compression Library
clAddAlgorithm IRIX Add a video or audio compression algorithm to the Compression Library
videoout IRIX Video Library video output from screen tool
videoin IRIX Video Library video-in-a-window tool
dmPMSetAudioCallback IRIX sets the audio and video callbacks
clOpenCompressor IRIX Compress a video or audio stream
clOpenDecompressor IRIX Decompress a video or audio stream
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service