Technical Q&A QA1444

Compression Sessions - Configuring codec quality settings

Q:  When migrating from Compression Sequences to Compression Sessions how are the Codec Quality settings for Spatial and Temporal quality set for the Session? Can these be changed per frame?

A: When using CompressSequenceBegin, the appropriate CodecQ settings for spatial and temporal quality are passed into the API and can be changed for the Sequence by calling SetCSequenceQuality. Passing in 0 for temporalQuality prevents the compressor from applying any temporal compression to the sequence.

The setup for Compression Sessions is a little different. You first create and configure a ICMCompressionSessionOptions object using the ICMCompressionSessionOptionsCreate API, then pass in this configuration to ICMCompressionSessionCreate.

Configuration of spatial quality for a Compression Session is done using the kICMCompressionSessionOptionsPropertyID_Quality property along with the ICMCompressionSessionOptionsSetProperty API.

Temporal compression can be enabled or disabled for a session by calling ICMCompressionSessionOptionsSetAllowTemporalCompression and passing in either true or false. See Listing 1.

If temporal compression is enabled, the kICMCompressionSessionOptionsPropertyID_Quality property is also used to set temporalQuality.

Listing 1  Configuring Session Options

CodecQ compressionQuality = codecNormalQuality;
Boolean allowTemporalCompression = true;
ICMCompressionSessionOptionsRef sessionOptions = NULL;
ICMCompressionSessionRef session = NULL;
 
...
 
// Create a compression session options token (ICMCompressionSessionOptionsRef).
err = ICMCompressionSessionOptionsCreate(kCFAllocatorDefault, &sessionOptions);
if(err || NULL == sessionOptions) goto bail;
 
// Set temporal compression on/off.
err = ICMCompressionSessionOptionsSetAllowTemporalCompression(sessionOptions,
                                                    allowTemporalCompression);
if (err) goto bail;
 
// Set the compression quality.
// kICMCompressionSessionOptionsPropertyID_Quality property is always used to
// set the spatialQuality; if temporal compression is enabled, it is also used
// to set temporalQuality.
// The default quality is codecNormalQuality.
err = ICMCompressionSessionOptionsSetProperty(sessionOptions,
                                kQTPropertyClass_ICMCompressionSessionOptions,
                                kICMCompressionSessionOptionsPropertyID_Quality,
                                sizeof(compressionQuality),
                                &compressionQuality );
if (err) goto bail;
 
...
 
err = ICMCompressionSessionCreate(kCFAllocatorDefault, ..., &session);
if (err) goto bail;
 
// Encode some frames
...
 
bail:
    // Both of these release calls are NULL safe, so we don't have to do an extra check.
    ICMCompressionSessionOptionsRelease(sessionOptions);
    ICMCompressionSessionRelease(session);
...

References:

See ImageCompression.h for additional property information.



Document Revision History


DateNotes
2005-10-17

New document that discusses how to set encoding quality for a Compression Sequence