dm_jpeg(3dm)
dm_jpeg - JPEG compression programming with dmIC and dmBuffers
As shipped in IRIX 6.5.5. Unchanged since IRIX 6.5.
NAME dm_jpeg - JPEG compression programming with dmIC and dmBuffers SYNOPSIS #include <dmedia/dm_imagecvt.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 cl_jpeg 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 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); 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 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). 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. 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. SEE ALSO dmIC(4), dmBuffer(4), mvIntro(3dm), VLintro(3dm).