cl_mpeg1(3dm)cl_mpeg1(3dm)NAMEcl_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.
Page 1
cl_mpeg1(3dm)cl_mpeg1(3dm)
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.
Page 2
cl_mpeg1(3dm)cl_mpeg1(3dm)
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
Page 3
cl_mpeg1(3dm)cl_mpeg1(3dm)
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
Page 4
cl_mpeg1(3dm)cl_mpeg1(3dm)
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.
Page 5
cl_mpeg1(3dm)cl_mpeg1(3dm)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 ALSOCLintro(3dm), mpeg(4)
Page 6
