dmIC(3dm) dmIC(3dm)
dm_jpeg - JPEG compression programming with dmIC and dmBuffers
#include <dmedia/dm_imagecvt.h>
#include <dmedia/dm_jpeg.h>
The JPEG compression standard (ISO/IEC 10918) operates with dmIC and
dmBuffers as described in this man page. The dmIC man pages are generic
and contain no information about specific compression schemes. This man
page describes details of dmIC specific to baseline (DCT-based, Huffmanencoded)
JPEG.
NOTE: Some previous generation realtime JPEG products are not supported
via this interface. Indy Cosmo and Indigo2 Cosmo2 are available only via
the Compression Library (CL). See CLintro and cl_jpeg for more
information.
AVAILABLE JPEG IMAGE CONVERTERS [Toc] [Back] A variety of realtime JPEG hardware products operate under this
programming interface. There is a basic common subset of JPEG supported
in all implementations.
FINDING AND CREATING A JPEG CONVERTER
This section describes how to use dmIC operations to find and create a
JPEG image converter for either encode (compression) or decode
(decompression) in realtime or non-realtime. (Realtime generally refers
to a JPEG converter that operates at video rate -- NTSC, PAL, or 601).
A JPEG image converter's DM_IC_ID parameter -- from the DMparams list
returned by dmICGetDescription -- has the value 'jpeg'.
The DM_IC_SPEED parameter will have the value DM_IC_SPEED_REALTIME if the
converter is capable of video rate processing. If the value is
DM_IC_SPEED_NONREALTIME the converter is not capable of operating at
video rate.
The DM_IC_CODE_DIRECTION parameter indicates if the converter compresses
or decompresses. If the value is DM_IC_CODE_DIRECTION_DECODE then the
input to the converter is JPEG and the output is pixel data. If the
value is DM_IC_CODE_DIRECTION_ENCODE then the input to the converter is
pixel data and the output is JPEG.
The following code fragment shows how to find a realtime JPEG decoder and
create a context for operating on it:
DMimageconverter ic;
DMparams *p;
int n = dmICGetNum();
while (n--) {
dmParamsCreate(&p);
Page 1
dmIC(3dm) dmIC(3dm)
if (dmICGetDescription(n, p) == DM_SUCCESS
dmParamsGetInt(p, DM_IC_ID) == 'jpeg' &&
dmParamsGetEnum(p, DM_IC_SPEED) == DM_IC_SPEED_REALTIME &&
dmParamsGetEnum(p, DM_IC_CODE_DIRECTION) ==
DM_IC_CODE_DIRECTION_DECODE) {
dmParamsDestroy(p);
break;
}
dmParamsDestroy(p);
}
dmICCreate(n, &ic);
The number of simultanously active realtime JPEG converters system-wide
may exceed the capabilities of the underlying hardware. That is, one or
more programs may create one or more JPEG converter contexts and if too
many are simultaneously compressing or decompressing JPEG data the result
may be less than realtime for one or more contexts.
JPEG CONVERTER CONTROL [Toc] [Back] These sections describe how generic and JPEG-specific parameters are used
to control a JPEG converter. In general each parameter value should be
considered undefined until set explicitly by the program.
The input image format, the output image format and the conversion
operation are controlled using dmICSetSrcParams, dmICSetDstParams, and,
dmICSetConvParams repectively.
The following discussion will use the terms source and destination to
refer to the image format of the converter input and output,
respectively. The terms compressed side and uncompressed side will
generally refer to parameters of the source and destination respectively
if the converter is a JPEG decoder and vice versa if the converter is a
JPEG encoder.
JPEG SOURCE AND DESTINATION IMAGE FORMAT
The image orientation, width, height, and pixel format must be set on
both the source and destination side of the converter. Use of
dmSetImageDefaults is recommended to set the DM_IMAGE_WIDTH,
DM_IMAGE_HEIGHT, and DM_IMAGE_PACKING parameters. The width and height
on the compressed side must match the native size of the JPEG encoded
data. (A note on obtaining width and height for image data stored in a
movie file appears later in this man page.)
The DM_IMAGE_COMPRESSION parameter must be set to DM_IMAGE_JPEG on the
source or destination side as appropriate for the conversion direction.
All JPEG image converters support the DM_IMAGE_PACKING_CbYCrY on the
compressed side. This is the same as the Video Library pixel packing for
4:2:2 video VL_PACKING_YVYU_422_8, and is the same as the OpenGL
GL_YCRCB_422_SGIX format for use with glDrawPixels on some machines (O2,
for example).
Page 2
dmIC(3dm) dmIC(3dm)
The following code fragment configures the source and destination of the
realtime decoder context created in the previous example. Error
processing is left off for clarity:
DMparams *p;
int wid, ht;
size_t imagebytes;
dmParamsCreate(&p);
dmSetImageDefaults(p, wid, ht, DM_IMAGE_PACKING_CbYCrY);
dmParamsSetEnum(p, DM_IMAGE_ORIENTATION, DM_IMAGE_TOP_TO_BOTTOM);
dmParamsSetString(p, DM_IMAGE_COMPRESSION, DM_IMAGE_JPEG);
dmICSetSrcParams(ic, p);
imagebytes = dmImageFrameSize(p);
dmParamsSetString(p, DM_IMAGE_COMPRESSION, DM_IMAGE_UNCOMPRESSED);
dmICSetDstParams(ic, p);
dmParamsDestroy(p);
In the above code note that the DMparams list p is recycled since only
one parameter value is different between the source and destination
formats. This is safe since dmIC saves away the values of the paramters
of interest before returning from any call accepting a DMparams as an
argument. Also note the use of dmImageFrameSize to impute the size (in
bytes) of an image described by the given parameters. The orientation in
this example is DM_IMAGE_TOP_TO_BOTTOM which is the proper orientation of
video imagery and is the value required for DM_IMAGE_ORIENTATION to
ensure realtime processing.
WARNING: A realtime JPEG converter may not necessarily operate in
realtime if one or more of the image parameters (other than
DM_IMAGE_COMPRESSION) is different between source and destination. That
is, the implied conversion (from one width and height to a different if
those paramters are different) may take place in software.
All realtime JPEG converters will operate at video rate if the compressed
side is 4:2:2 (DM_IMAGE_PACKING_CbYCrY) and the uncompressed side is
either 4:2:2 YCrCb or RGB (DM_IMAGE_PACKING_XBGR). The conversion
algorithm used for RGB assumes strict Recommendation 601 values for the
YCrCb color model (blackest black is Y=16, 1-15 are clamped to 16, peak Y
is 240, 241-255 clamped to 240, etc). NOTE: This is a slighty different
color model than that used in JFIF images.
JPEG CONVERSION CONTROLS
Aside from the rudimentary image conversion controls on width, height,
pixel packing, orientation and so forth there are controls specific to
the JPEG encode process typically to control the image quality or the
compression ratio or bitrate. This section describes parameters for use
with dmICSetConvParams.
Page 3
dmIC(3dm) dmIC(3dm)
The JPEG quality factor (a scaling of the quantization tables) is
controlled using the DM_IMAGE_QUALITY_SPATIAL parameter. The parameter
value ranges from 0.0 (lowest quality and most compression) to 1.0
(highest quality and least compression). Setting this control overrides
(erases) the converters internal setting for bitrate (if such had been
previously set by the program).
The compression ratio is controlled using DM_IMAGE_BITRATE. Use of this
control erases the converter's internal setting of quality (if such had
been previously set by the program). The JPEG encoder destination
parameters for DM_IMAGE_RATE (frames per second) and DM_IMAGE_INTERLACING
(essentially indicating fields or frames) must be set explicitly by the
program to engage the rate control mechanism of the encoder. The actual
data rate acheived is "best effort" and may vary from image to image, but
the average will tend towards the desired value. All realtime encoders
are capable of acheiving an average rate in the range of 2 to 30
megabits/second. Some realtime encoders may be capable of higher rates.
Note that some decoders have a maximum bitrate that is different than its
companion encoder.
It is recommended that the program set either the quality or bitrate
explicitly. If both DM_IMAGE_BITRATE and DM_IMAGE_QUALITY_SPATIAL
parameters are set then bitrate setting prevails and the quality setting
is used as the initial condition for the compressed image size.
JPEG, QUICKTIME, AND THE MOVIE LIBRARY
Here are some notes on how to access the Quicktime Motion JPEG Type-A
file format using the Movie File Library specifically to transfer data
between a JPEG image converter and the Movie File using dmBuffers.
When using JPEG with the Movie File Library the width and height of the
images in a track may be obtained using mvGetImageWidth and
mvGetImageHeight.
The height of an image in the track is that of a full frame whether the
each image is stored as a field pair or a frame. If the track data is
interlaced then the appropriate value to use for the DM_IMAGE_HEIGHT
parameter with the image converter is half that of the value returned
from the movie file. That is, the Movie Library operates in terms of
full frames in contrast to dmIC and JPEG which operates only in terms of
images. A dmIC JPEG converter must therefore be informed of the exact
dimensions of the image. It's the program's responsibility to know
whether each image represents a field or a frame and to know the
dimensions in either case.
The mvInsertTrackDataFields call is used when creating a Quicktime Motion
JPEG Type-A file of pairs of fields of JPEG encoded video. And, the
mvGetTrackDataFieldInfo and mvReadTrackDataFields calls are used to read
pairs of fields from a Quicktime file.
Page 4
dmIC(3dm) dmIC(3dm)
dmIC(4), dmBuffer(4), mvIntro(3dm), VLintro(3dm).
PPPPaaaaggggeeee 5555 [ Back ]
|
