Decompression Sessions - Setting codec accuracy and field mode

Q: When transitioning to Decompression Sessions how are codec accuracy and options such as deinterlacing set?

A: The older Decompression Sequence APIs had a couple of specific APIs for setting these options. Codec accuracy for example could be set when first creating the sequence by calling DecompressSequenceBeginS or after the sequence was created by calling SetDSequenceAccuracy. Decompression Sequence flags such as codecDSequenceDeinterlaceFields on the other hand would need to be set separately by calling SetDSequenceFlags.

The Decompression Session APIs now present a more unified approach for getting and setting options though the use of properties (this is a trend you can see throughout the entire modern QuickTime API).

When creating a Decompression Session, one of the parameters you pass to ICMDecompressionSessionCreate is a decompression session options reference (ICMDecompressionSessionOptionsRef). This reference is returned by ICMDecompressionSessionOptionsCreate and the values of specific properties of a decompression session options object are set by calling ICMDecompressionSessionOptionsSetProperty.

ImageCompression.h contains a list of enumerations for decompression session options (kQTPropertyClass_ICMDecompressionSessionOptions), for example kICMDecompressionSessionOptionsPropertyID_FieldMode for setting special field handling. Field mode options are UInt32 values described by the typedef ICMFieldMode. These modes are then used with the kICMDecompressionSessionOptionsPropertyID_FieldMode property.

kICMFieldMode_BothFields - Both fields should be decompressed.

kICMFieldMode_TopFieldOnly - Only the top field should be decompressed, producing a half-height image.

kICMFieldMode_BottomFieldOnly - Only the bottom field should be decompressed, producing a
                                half-height image.

kICMFieldMode_DeinterlaceFields - Both fields should be decompressed, and then filtered to reduce
                                  interlacing artifacts.

ImageCompression.h also contains a list of CodecQ values specifying decompression accuracy. These values are used with the kICMDecompressionSessionOptionsPropertyID_Accuracy property. If this property hasn't been set in the decompression session options object, the default session accuracy setting is codecNormalQuality.

Listing 1: Setting some Decompression Session options.

ICMDecompressionSessionOptionsRef sessionOptions = NULL;
CodecQ codecAccuracy = codecHighQuality;
ICMFieldMode fieldMode = kICMFieldMode_DeinterlaceFields;


// create a decompression session options object
err = ICMDecompressionSessionOptionsCreate(kCFAllocatorDefault, &sessionOptions);
if (noErr == err) {

    // set accuracy
    // set field mode


// create the decompression session passing in the options object
err = ICMDecompressionSessionCreate(kCFAllocatorDefault, ..., sessionOptions, ...);
if (err) goto bail;


// the session will retain the options object so you can release it
// you can also change options during the session by modifying the options object


IMPORTANT: Not all codecs will obey the kICMDecompressionSessionOptionsPropertyID_FieldMode request, and some codecs will only handle it at certain accuracy levels. This request is ignored for non-interlaced content.


Back to Top 

Document Revision History

2006-01-12Describes how to set codec accuracy and field mode options when creating a decompression sessions.

Posted: 2006-01-12

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.