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.

Note: The Compression Session retains the ICMCompressionSessionOptions object, so you can change the value for the kICMCompressionSessionOptionsPropertyID_Quality property between calls to ICMCompressionSessionEncodeFrame.

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.

Back to Top 

Document Revision History

DateNotes
2005-10-17Discusses how to set encoding quality for a Compression Sequence

Posted: 2005-10-17

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.