cl_mpeg1(3dm)
cl_mpeg1 - MPEG-1 schemes in the Compression Library
As shipped in IRIX 6.5.22. Unchanged since IRIX 6.5.
NAME cl_mpeg1 - MPEG-1 schemes in the Compression Library SYNOPSIS #include <dmedia/cl.h> DESCRIPTION The MPEG compression standard, mpeg(4), is supported in the Compression Library, CLintro(3dm), with two schemes 1. CL_MPEG1_VIDEO_SOFTWARE video compressor/decompressor 2. CL_MPEG1_AUDIO_SOFTWARE audio compressor/decompressor Each scheme is accessed using the basic CL API and parameter set. This man page describes the features supported by these schemes, as well as the general CL and MPEG-specific parameters that are relevant for their operation. The Compression Library also provides MPEG audio support through a third scheme, CL_MPEG1_AUDIO_AWARE, which uses somewhat different parameters. For a discussion of this and other compression schemes from Aware, Inc., see cl_aware(3dm). FEATURES Video Compression o Cropping and smoothing of input frames o High-quality rate control o Automatic I-frame insertion at scene changes Audio Compression o Layer I and II support o Stereo, joint, dual, and single-channel modes PROGRAMMING MPEG The two MPEG schemes, CL_MPEG1_VIDEO_SOFTWARE and CL_MPEG1_AUDIO_SOFTWARE, are accessed through the standard CL API. See CLintro(3dm) for an overview of the CL calls and their usage. Only Implicit Buffering is currently supported for input buffers of video and audio decompressors, and for both buffers of video compressors. This model requires that the implicit buffer be created with clCreateBuf(3dm) prior to calling clDecompress(3dm) or clCompress(3dm). Once created, the same implicit buffer should be used for the lifetime of the processing object. PARAMETERS Various parameters are useful for guiding and monitoring MPEG processing. These are discussed in several groups : General CL, MPEG-1, MPEG-1 Video, and MPEG-1 Audio. PARAMETERS : GENERAL CL All of the general CL parameters are described in CLintro(3dm). Below we mention only those for which additional information is useful (such as parameter ranges and other constraints). CL_IMAGE_WIDTH, CL_IMAGE_HEIGHT For video compressors, these should be set to match the input frame size. Each dimension has a minimum value of 16 and a maximum value of 4080. For video decompressors, these are read-only and match the encoded ("internal") dimensions. CL_INTERNAL_IMAGE_WIDTH, CL_INTERNAL_IMAGE_HEIGHT For video compressors, these default to the "source input format" (SIF), which is 352x240 (CCIR601-525 pixel aspect ratio), 352x288 (CCIR601-625 pixel aspect ratio), or 320x240 (square pixels). For inputs with other pixel aspect ratios, the closest of these three applies. If cropping is used (see below), the cropped image is scaled to the internal dimensions prior to encoding. The internal width and height must each be between 16 and 4080, inclusive, and be a multiple of 16. For video decompressors, these parameters are read-only. CL_IMAGE_CROP_LEFT, CL_IMAGE_CROP_RIGHT, CL_IMAGE_CROP_TOP, CL_IMAGE_CROP_BOTTOM For video compressors, these indicate how many pixels to crop from each of the four sides of the input image. These may be set to any value from 0 to 4064. On the first call to clCompress, the cropped region is checked to make sure it is at least 16x16 pixels in size. CL_INTERNAL_FORMAT For video, this is always CL_FORMAT_YCbCr422DC. To be MPEG- compliant, the bitstream is actually encoded in 4:2:0 format, where the chroma is subsampled by 2 vertically in addition to horizontally, but the current implementation exposes only the duplicate chroma format. CL_BITS_PER_COMPONENT For audio, only 16-bit samples are supported. CL_FRAME_RATE For compressors, this should be set to indicate the frame rate of the input. The following rates are allowed. Video : 23.976, 24, 25, 29.97, 30, 50, 59.94, 60 Audio : 32000, 44100, 48000 For decompressors, this is read-only. CL_PIXEL_ASPECT Pixel aspect ratio, defined as the vertical extent of a pixel divided by its horizontal extent. For video compressors, this should be set to match the aspect ratio of the input pixels. The closest value from the following list is used. 1.0000 Square 0.6735 0.7031 16:9, 625line 0.7615 0.8055 0.8437 16:9, 525line 0.8935 0.9157 CCIR601, 625line 0.9815 1.0255 1.0695 1.0950 CCIR601, 525line 1.1575 1.2015 For video decompressors, this is read-only. CL_COMPRESSION_RATIO For compressors, setting this parameter will result in an appropriate CL_BITRATE to be calculated (and vice versa). CL_EXACT_COMPRESSION_RATIO TRUE for video and audio compressors, since bitrate targets are generally met. However, some deviation from the requested compression ratio may occur due to the bitrates actually allowed (see below). CL_BITRATE May be set for compressors to indicate a target bitrate. For compressors, setting this parameter will result in an appropriate CL_COMPRESSION_RATIO to be calculated (and vice versa). The allowed bitrates are Video : 100 Kbps - 4.5 Mbps Audio : (in Kbps) layer I - 32, 64, 96,128,160,192,224,256,288,320,352,384,416,448 layer II - 32, 48, 56, 64, 80, 96,112,128,160,192,224,256,320,384 The default bitrates are 1.158 Mbps for video and 96/192 Kbps for mono/stereo audio. These correspond to single-speed CD-ROM, and work best for SIF-size images (352x240, 352x288, 320x240). Values of CL_INTERNAL_WIDTH and CL_INTERNAL_HEIGHT that are larger should use higher bitrates. For decompressors, this is read-only. CL_NUMBER_OF_FRAMES For video and audio decompressors, this parameter keeps track of the known number of frames in the sequence. As the sequence is decoded, the number of frames may increase. PARAMETERS : MPEG-1 This parameter is shared by the MPEG schemes. CL_MPEG1_END_OF_STREAM Type : CL_ENUM_VALUE A read-only parameter which indicates that the end of stream has been reached. Used by compressors to indicate there is no more data to write. Used by decompressors to indicate there is no data left to read. PARAMETERS : MPEG-1 VIDEO The following parameters apply only to the MPEG-1 Video scheme. CL_MPEG1_VIDEO_M CL_MPEG1_VIDEO_N Type : CL_RANGE_VALUE Used to select IPB pattern for video compressors. M is the distance between reference frames (I or P), and N is the distance between I frames, measured in numbers of frames. M ranges from 1 to 12, and N ranges from 1 to 60. The first call to clCompress checks that N/M is an integer. Default is M=4, N=16. The actual encoded pattern may be different due to automatic I frame insertion at scene changes. M N Pattern 1 1 IIIIII IIIIII 1 3 IPPIPP IPPIPP 3 3 BBIBBI BBIBBI 3 6 BBIBBP BBIBBP CL_MPEG1_VIDEO_MAX_MOTION_VECTOR_LENGTH_P_X, CL_MPEG1_VIDEO_MAX_MOTION_VECTOR_LENGTH_P_Y, CL_MPEG1_VIDEO_MAX_MOTION_VECTOR_LENGTH_B_X, CL_MPEG1_VIDEO_MAX_MOTION_VECTOR_LENGTH_B_Y Type : CL_RANGE_VALUE For video compressors, the maximum search range (in pixels) for motion vectors. Vectors in P frames have maximum lengths of P_X and P_Y, and in B frames have maximum lengths of B_X and B_Y. Higher values may give better image quality at the expense of more computation. Allowable parameter values range from 1 to 60. Defaults are P_X=48, P_Y=32, B_X=32, and B_Y=24. CL_MPEG1_VIDEO_SOFTNESS Type : CL_ENUM_VALUE The smoothing filter parameter for video compressors. May be set to one of CL_MPEG1_VIDEO_SOFTNESS_NONE (default) CL_MPEG1_VIDEO_SOFTNESS_MEDIUM CL_MPEG1_VIDEO_SOFTNESS_MAXIMUM Setting this parameter modifies the filter that is applied when scaling from the cropped window to the internal dimensions. PARAMETERS : MPEG-1 AUDIO The following parameters apply only to the MPEG-1 Audio scheme. CL_MPEG1_AUDIO_LAYER Type : CL_ENUM_VALUE The layer used for audio encoding. Allowed values are CL_MPEG1_AUDIO_LAYER_I CL_MPEG1_AUDIO_LAYER_II For compressors this may be set to select the layer. For decompressors, this is a read-only parameter. CL_MPEG1_AUDIO_MODE Type : CL_ENUM_VALUE The mode in which input channel(s) are encoded. Allowed values are CL_MPEG1_AUDIO_MODE_STEREO CL_MPEG1_AUDIO_MODE_JOINT CL_MPEG1_AUDIO_MODE_DUAL CL_MPEG1_AUDIO_MODE_SINGLE For compressors, this may be set to select the encoding mode. Stereo channels should be encoded with CL_MPEG1_AUDIO_MODE_STEREO or CL_MPEG1_AUDIO_MODE_JOINT. The latter exploits correlation between channels for more compression. Two independent channels should be encoded with CL_MPEG1_AUDIO_MODE_DUAL. A mono signal should be encoded with CL_MPEG1_AUDIO_MODE_SINGLE. For decompressors, this is a read-only parameter. NOTES This section provides miscellaneous information and tips on how to use the MPEG schemes. Error Codes CL_BAD_LICENSE may be returned by clOpenCompressor if the appropriate license is not installed. CL_MPEG1_ERROR may be returned by a CL call if an MPEG-specific error occurs, e.g. a non-compliant data stream. Video Compression Since the MPEG video compressor reorders input frames, compressed bits that are generated by a call to clCompress do not necessarily correspond to the frame that is consumed from the input buffer. The compressor maps the cropped window to the internal width and height. If the cropped window and the internal dimensions are not related by the same scale factor in each dimension, the final image is stretched more along one axis than the other. FILES /usr/include/dmedia/cl.h SEE ALSO CLintro(3dm), mpeg(4)