dmIC(3dm) dmIC(3dm)
NAME
dm_jpeg - JPEG compression programming with dmIC and dmBuffers
SYNOPSIS
#include <dmedia/dmimagecvt.h>
#include <dmedia/dm_jpeg.h>
DESCRIPTION
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, Huffman-
encoded) 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 cljpeg for more
information.
AVAILABLE JPEG IMAGE CONVERTERS
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 DMICID parameter -- from the DMparams list
returned by dmICGetDescription -- has the value 'jpeg'.
The DMICSPEED parameter will have the value DMICSPEEDREALTIME if the
converter is capable of video rate processing. If the value is
DMICSPEEDNONREALTIME the converter is not capable of operating at
video rate.
The DMICCODEDIRECTION parameter indicates if the converter compresses
or decompresses. If the value is DMICCODEDIRECTIONDECODE then the
input to the converter is JPEG and the output is pixel data. If the
value is DMICCODEDIRECTIONENCODE 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
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 DMIMAGEWIDTH,
DMIMAGEHEIGHT, and DMIMAGEPACKING 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 DMIMAGECOMPRESSION parameter must be set to DMIMAGEJPEG on the
source or destination side as appropriate for the conversion direction.
All JPEG image converters support the DMIMAGEPACKINGCbYCrY on the
compressed side. This is the same as the Video Library pixel packing for
4:2:2 video VLPACKINGYVYU4228, and is the same as the OpenGL
GLYCRCB422SGIX 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 DMIMAGETOPTOBOTTOM 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 DMIMAGEQUALITYSPATIAL 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 DMIMAGEBITRATE. 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 DMIMAGEBITRATE and DMIMAGEQUALITYSPATIAL
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)
SEE ALSO
dmIC(4), dmBuffer(4), mvIntro(3dm), VLintro(3dm).
Page 5