---

Image Compression Manager Reference

Overview

Applications can use the QuickTime image compression APIs to compress and decompress sounds, images, and image sequences, as well as to transcode sounds and images between compression formats.

Functions by Task

Image Transcoder Support

• ImageTranscoderBeginSequence
• ImageTranscoderConvert
• ImageTranscoderDisposeData
• ImageTranscoderEndSequence

Managing an ICM Compression Session

• ICMCompressionSessionCompleteFrames
• ICMCompressionSessionCreate
• ICMCompressionSessionEncodeFrame
• ICMCompressionSessionGetImageDescription
• ICMCompressionSessionGetPixelBufferPool
• ICMCompressionSessionGetProperty

Using the OpenGL Texture Context

• QTOpenGLTextureContextCreate
• QTVisualContextCopyImageForTime
• QTVisualContextGetAttribute
• QTVisualContextGetTypeID
• QTVisualContextIsNewImageAvailable
• QTVisualContextRelease
• QTVisualContextRetain
• QTVisualContextSetAttribute
• QTVisualContextSetImageAvailableCallback
• QTVisualContextTask

Supporting Functions

• DisposeICMAlignmentUPP
• DisposeICMCompletionUPP
• DisposeICMConvertDataFormatUPP
• DisposeICMCursorShieldedUPP
• DisposeICMDataUPP
• DisposeICMFlushUPP
• DisposeICMMemoryDisposedUPP
• DisposeICMProgressUPP
• DisposeQDPixUPP
• DisposeStdPixUPP
• ICMCompressionFrameOptionsCreate
• ICMCompressionFrameOptionsCreateCopy
• ICMCompressionFrameOptionsGetForceKeyFrame
• ICMCompressionFrameOptionsGetFrameType
• ICMCompressionFrameOptionsGetProperty
• ICMCompressionFrameOptionsGetPropertyInfo
• ICMCompressionFrameOptionsGetTypeID
• ICMCompressionFrameOptionsRelease
• ICMCompressionFrameOptionsRetain
• ICMCompressionFrameOptionsSetForceKeyFrame
• ICMCompressionFrameOptionsSetFrameType
• ICMCompressionFrameOptionsSetProperty
• ICMCompressionSessionBeginPass
• ICMCompressionSessionEndPass
• ICMCompressionSessionGetPropertyInfo
• ICMCompressionSessionGetTimeScale
• ICMCompressionSessionGetTypeID
• ICMCompressionSessionOptionsCreate
• ICMCompressionSessionOptionsCreateCopy
• ICMCompressionSessionOptionsGetAllowFrameReordering
• ICMCompressionSessionOptionsGetAllowFrameTimeChanges
• ICMCompressionSessionOptionsGetAllowTemporalCompression
• ICMCompressionSessionOptionsGetDurationsNeeded
• ICMCompressionSessionOptionsGetMaxKeyFrameInterval
• ICMCompressionSessionOptionsGetProperty
• ICMCompressionSessionOptionsGetPropertyInfo
• ICMCompressionSessionOptionsGetTypeID
• ICMCompressionSessionOptionsRelease
• ICMCompressionSessionOptionsRetain
• ICMCompressionSessionOptionsSetAllowFrameReordering
• ICMCompressionSessionOptionsSetAllowFrameTimeChanges
• ICMCompressionSessionOptionsSetAllowTemporalCompression
• ICMCompressionSessionOptionsSetDurationsNeeded
• ICMCompressionSessionOptionsSetMaxKeyFrameInterval
• ICMCompressionSessionOptionsSetProperty
• ICMCompressionSessionProcessBetweenPasses
• ICMCompressionSessionRelease
• ICMCompressionSessionRetain
• ICMCompressionSessionSetProperty
• ICMCompressionSessionSupportsMultiPassEncoding
• ICMCompressorSessionDropFrame
• ICMCompressorSessionEmitEncodedFrame
• ICMCompressorSourceFrameGetDisplayNumber
• ICMCompressorSourceFrameGetDisplayTimeStampAndDuration
• ICMCompressorSourceFrameGetFrameOptions
• ICMCompressorSourceFrameGetPixelBuffer
• ICMCompressorSourceFrameGetTypeID
• ICMCompressorSourceFrameRelease
• ICMCompressorSourceFrameRetain
• ICMDecompressionFrameOptionsCreate
• ICMDecompressionFrameOptionsCreateCopy
• ICMDecompressionFrameOptionsGetProperty
• ICMDecompressionFrameOptionsGetPropertyInfo
• ICMDecompressionFrameOptionsGetTypeID
• ICMDecompressionFrameOptionsRelease
• ICMDecompressionFrameOptionsRetain
• ICMDecompressionFrameOptionsSetProperty
• ICMDecompressionSessionCreate
• ICMDecompressionSessionCreateForVisualContext
• ICMDecompressionSessionDecodeFrame
• ICMDecompressionSessionFlush
• ICMDecompressionSessionGetProperty
• ICMDecompressionSessionGetPropertyInfo
• ICMDecompressionSessionGetTypeID
• ICMDecompressionSessionOptionsCreate
• ICMDecompressionSessionOptionsCreateCopy
• ICMDecompressionSessionOptionsGetProperty
• ICMDecompressionSessionOptionsGetPropertyInfo
• ICMDecompressionSessionOptionsGetTypeID
• ICMDecompressionSessionOptionsRelease
• ICMDecompressionSessionOptionsRetain
• ICMDecompressionSessionOptionsSetProperty
• ICMDecompressionSessionRelease
• ICMDecompressionSessionRetain
• ICMDecompressionSessionSetNonScheduledDisplayDirection
• ICMDecompressionSessionSetNonScheduledDisplayTime
• ICMDecompressionSessionSetProperty
• ICMEncodedFrameCreateMutable
• ICMEncodedFrameGetBufferSize
• ICMEncodedFrameGetDataPtr
• ICMEncodedFrameGetDataSize
• ICMEncodedFrameGetDecodeDuration
• ICMEncodedFrameGetDecodeNumber
• ICMEncodedFrameGetDecodeTimeStamp
• ICMEncodedFrameGetDisplayDuration
• ICMEncodedFrameGetDisplayOffset
• ICMEncodedFrameGetDisplayTimeStamp
• ICMEncodedFrameGetFrameType
• ICMEncodedFrameGetImageDescription
• ICMEncodedFrameGetMediaSampleFlags
• ICMEncodedFrameGetSimilarity
• ICMEncodedFrameGetSourceFrameRefCon
• ICMEncodedFrameGetTimeScale
• ICMEncodedFrameGetTypeID
• ICMEncodedFrameGetValidTimeFlags
• ICMEncodedFrameRelease
• ICMEncodedFrameRetain
• ICMEncodedFrameSetDataSize
• ICMEncodedFrameSetDecodeDuration
• ICMEncodedFrameSetDecodeTimeStamp
• ICMEncodedFrameSetDisplayDuration
• ICMEncodedFrameSetDisplayTimeStamp
• ICMEncodedFrameSetFrameType
• ICMEncodedFrameSetMediaSampleFlags
• ICMEncodedFrameSetSimilarity
• ICMEncodedFrameSetValidTimeFlags
• ICMImageDescriptionGetProperty
• ICMImageDescriptionGetPropertyInfo
• ICMImageDescriptionSetProperty
• ICMMultiPassStorageCopyDataAtTimeStamp
• ICMMultiPassStorageCreateWithCallbacks
• ICMMultiPassStorageCreateWithTemporaryFile
• ICMMultiPassStorageGetTimeStamp
• ICMMultiPassStorageGetTypeID
• ICMMultiPassStorageRelease
• ICMMultiPassStorageRetain
• ICMMultiPassStorageSetDataAtTimeStamp
• NewICMAlignmentUPP
• NewICMCompletionUPP
• NewICMConvertDataFormatUPP
• NewICMCursorShieldedUPP
• NewICMDataUPP
• NewICMFlushUPP
• NewICMMemoryDisposedUPP
• NewICMProgressUPP
• NewQDPixUPP
• NewStdPixUPP
• QTAddComponentPropertyListener
• QTComponentPropertyListenerCollectionAddListener
• QTComponentPropertyListenerCollectionCreate
• QTComponentPropertyListenerCollectionHasListenersForProperty
• QTComponentPropertyListenerCollectionIsEmpty
• QTComponentPropertyListenerCollectionNotifyListeners
• QTComponentPropertyListenerCollectionRemoveListener
• QTGetComponentProperty
• QTGetComponentPropertyInfo
• QTPixelBufferContextCreate
• QTRemoveComponentPropertyListener
• QTSetComponentProperty

Functions

DisposeICMAlignmentUPP

Disposes of an ICMAlignmentUPP pointer.

void DisposeICMAlignmentUPP (
   ICMAlignmentUPP userUPP
);

Parameters

userUPP

An ICMAlignmentUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeICMCompletionUPP

Disposes of an ICMCompletionUPP pointer.

void DisposeICMCompletionUPP (
   ICMCompletionUPP userUPP
);

Parameters

userUPP

An ICMCompletionUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeICMConvertDataFormatUPP

Disposes of an ICMConvertDataFormatUPP pointer.

void DisposeICMConvertDataFormatUPP (
   ICMConvertDataFormatUPP userUPP
);

Parameters

userUPP

An ICMConvertDataFormatUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeICMCursorShieldedUPP

Disposes of an ICMCursorShieldedUPP pointer.

void DisposeICMCursorShieldedUPP (
   ICMCursorShieldedUPP userUPP
);

Parameters

userUPP

An ICMCursorShieldedUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeICMDataUPP

Disposes of an ICMDataUPP pointer.

void DisposeICMDataUPP (
   ICMDataUPP userUPP
);

Parameters

userUPP

An ICMDataUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeICMFlushUPP

Disposes of an ICMFlushUPP pointer.

void DisposeICMFlushUPP (
   ICMFlushUPP userUPP
);

Parameters

userUPP

An ICMFlushUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeICMMemoryDisposedUPP

Disposes of an ICMMemoryDisposedUPP pointer.

void DisposeICMMemoryDisposedUPP (
   ICMMemoryDisposedUPP userUPP
);

Parameters

userUPP

An ICMMemoryDisposedUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeICMProgressUPP

Disposes of an ICMProgressUPP pointer.

void DisposeICMProgressUPP (
   ICMProgressUPP userUPP
);

Parameters

userUPP

An ICMProgressUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeQDPixUPP

Disposes of a QDPixUPP pointer.

void DisposeQDPixUPP (
   QDPixUPP userUPP
);

Parameters

userUPP

A QDPixUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeStdPixUPP

Disposes of a StdPixUPP pointer.

void DisposeStdPixUPP (
   StdPixUPP userUPP
);

Parameters

userUPP

A StdPixUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsCreate

Creates a frame compression options object.

OSStatus ICMCompressionFrameOptionsCreate (
   CFAllocatorRef allocator,
   ICMCompressionSessionRef session,
   ICMCompressionFrameOptionsRef *options
);

Parameters

allocator

An allocator. Pass NULL to use the default allocator.

session

A compression session reference. This reference is returned by ICMCompressionSessionCreate.

options

On return, a reference to a new frame compression options object.

Return Value

An error code. Returns noErr if there is no error.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsCreateCopy

Copies a frame compression options object.

OSStatus ICMCompressionFrameOptionsCreateCopy (
   CFAllocatorRef allocator,
   ICMCompressionFrameOptionsRef originalOptions,
   ICMCompressionFrameOptionsRef *copiedOptions
);

Parameters

allocator

An allocator. Pass NULL to use the default allocator.

originalOptions

A frame compression options reference. This reference is returned by ICMCompressionFrameOptionsCreate.

copiedOptions

On return, a reference to a copy of the frame compression options object passed in originalOptions.

Return Value

An error code. Returns noErr if there is no error.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsGetForceKeyFrame

Retrieves the force key frame flag.

Boolean ICMCompressionFrameOptionsGetForceKeyFrame (
   ICMCompressionFrameOptionsRef options
);

Parameters

options

A compression frame options reference. This reference is returned by ICMCompressionFrameOptionsCreate.

Return Value

Returns TRUE if frames are forced to be compressed as key frames, FALSE otherwise.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsGetFrameType

Retrieves the frame type setting.

ICMFrameType ICMCompressionFrameOptionsGetFrameType (
   ICMCompressionFrameOptionsRef options
);

Parameters

options

A compression frame options reference. This reference is returned by ICMCompressionFrameOptionsCreate.

Return Value

On return, one of the frame types listed below.

Discussion

This function can return one of these constants:

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsGetProperty

Retrieves the value of a specific property of a compression frame options object.

OSStatus ICMCompressionFrameOptionsGetProperty (
   ICMCompressionFrameOptionsRef options,
   ComponentPropertyClass inPropClass,
   ComponentPropertyID inPropID,
   ByteCount inPropValueSize,
   ComponentValuePtr outPropValueAddress,
   ByteCount *outPropValueSizeUsed
);

Parameters

options

A compression frame options reference. This reference is returned by ICMCompressionFrameOptionsCreate.

inPropClass

Pass the following constant to define the property class: kComponentPropertyClassPropertyInfo = 'pnfo' The property information class. See these constants:

• kComponentPropertyClassPropertyInfo

inPropID

Pass one of these constants to define the property ID: kComponentPropertyInfoList = 'list' An array of CFData values, one for each property. kComponentPropertyCacheSeed = 'seed' A property cache seed value. kComponentPropertyCacheFlags = 'flgs' One of the kComponentPropertyCache flags: kComponentPropertyCacheFlagNotPersistentProperty metadata should not be saved in persistent cache. kComponentPropertyCacheFlagIsDynamicProperty metadata should not cached at all. kComponentPropertyExtendedInfo = 'meta' A CFDictionary with extended property information. See these constants:

• kComponentPropertyInfoList

• kComponentPropertyCacheSeed

• kComponentPropertyCacheFlags

• kComponentPropertyExtendedInfo

outPropType

A pointer to the type of the returned property's value.

outPropValueAddress

A pointer to a variable to receive the returned property's value.

outPropValueSizeUsed

On return, a pointer to the number of bytes actually used to store the property.

Return Value

An error code. Returns noErr if there is no error.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsGetPropertyInfo

Retrieves information about properties of a compression frame options object.

OSStatus ICMCompressionFrameOptionsGetPropertyInfo (
   ICMCompressionFrameOptionsRef options,
   ComponentPropertyClass inPropClass,
   ComponentPropertyID inPropID,
   ComponentValueType *outPropType,
   ByteCount *outPropValueSize,
   UInt32 *outPropertyFlags
);

Parameters

options

A compression frame options reference. This reference is returned by ICMCompressionFrameOptionsCreate.

inPropClass

Pass the following constant to define the property class: kComponentPropertyClassPropertyInfo = 'pnfo' The property information class. See these constants:

• kComponentPropertyClassPropertyInfo

inPropID

Pass one of these constants to define the property ID: kComponentPropertyInfoList = 'list' An array of CFData values, one for each property. kComponentPropertyCacheSeed = 'seed' A property cache seed value. kComponentPropertyCacheFlags = 'flgs' One of the kComponentPropertyCache flags: kComponentPropertyCacheFlagNotPersistentProperty metadata should not be saved in persistent cache. kComponentPropertyCacheFlagIsDynamicProperty metadata should not cached at all. kComponentPropertyExtendedInfo = 'meta' A CFDictionary with extended property information. See these constants:

• kComponentPropertyInfoList

• kComponentPropertyCacheSeed

• kComponentPropertyCacheFlags

• kComponentPropertyExtendedInfo

outPropType

A pointer to the type of the returned property's value.

outPropValueSize

A pointer to the size of the returned property's value.

outPropFlags

On return, a pointer to flags representing the requested information about the property.

Return Value

An error code. Returns noErr if there is no error.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsGetTypeID

Returns the type ID for the current frame compression options object.

CFTypeID ICMCompressionFrameOptionsGetTypeID (
   void
);

Return Value

A CFTypeID value.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsRelease

Decrements the retain count of a frame compression options object.

void ICMCompressionFrameOptionsRelease (
   ICMCompressionFrameOptionsRef options
);

Parameters

options

A reference to a frame compression options object. This reference is returned by ICMCompressionFrameOptionsCreate. If you pass NULL, nothing happens.

Discussion

If the retain count drops to 0, the object is disposed.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsRetain

Increments the retain count of a frame compression options object.

ICMCompressionFrameOptionsRef ICMCompressionFrameOptionsRetain (
   ICMCompressionFrameOptionsRef options
);

Parameters

options

A reference to a frame compression options object. This reference is returned by ICMCompressionFrameOptionsCreate. If you pass NULL, nothing happens.

Return Value

A copy of the object reference passed in options, for convenience.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsSetForceKeyFrame

Forces frames to be compressed as key frames.

OSStatus ICMCompressionFrameOptionsSetForceKeyFrame (
   ICMCompressionFrameOptionsRef options,
   Boolean forceKeyFrame
);

Parameters

options

A compression frame options reference. This reference is returned by ICMCompressionFrameOptionsCreate.

forceKeyFrame

Pass TRUE to force frames to be compressed as key frames, FALSE otherwise.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The compressor must obey this flag if set. By default it is set FALSE.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsSetFrameType

Requests a frame be compressed as a particular frame type.

OSStatus ICMCompressionFrameOptionsSetFrameType (
   ICMCompressionFrameOptionsRef options,
   ICMFrameType frameType
);

Parameters

options

A compression frame options reference. This reference is returned by ICMCompressionFrameOptionsCreate.

frameType

A constant that identifies a frame type. Pass one of the following but do not assume that there are no other frame types: kICMFrameType_I = 'I' An I frame. kICMFrameType_P = 'P' A P frame. kICMFrameType_B = 'B' A B frame. kICMFrameType_Unknown = 0 A frame of unknown type. See these constants:

• kICMFrameType_I

• kICMFrameType_P

• kICMFrameType_B

• kICMFrameType_Unknown

Return Value

An error code. Returns noErr if there is no error.

Discussion

The frame type setting may be ignored by the compressor if it is not appropriate. By default it is set to kICMFrameType_Unknown.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionFrameOptionsSetProperty

Sets the value of a specific property of a compression frame options object.

OSStatus ICMCompressionFrameOptionsSetProperty (
   ICMCompressionFrameOptionsRef options,
   ComponentPropertyClass inPropClass,
   ComponentPropertyID inPropID,
   ByteCount inPropValueSize,
   ConstComponentValuePtr inPropValueAddress
);

Parameters

options

A compression frame options reference. This reference is returned by ICMCompressionFrameOptionsCreate.

inPropClass

Pass the following constant to define the property class: kComponentPropertyClassPropertyInfo = 'pnfo' The property information class. See these constants:

• kComponentPropertyClassPropertyInfo

inPropID

Pass one of these constants to define the property ID: kComponentPropertyInfoList = 'list' An array of CFData values, one for each property. kComponentPropertyCacheSeed = 'seed' A property cache seed value. kComponentPropertyCacheFlags = 'flgs' One of the kComponentPropertyCache flags: kComponentPropertyCacheFlagNotPersistentProperty metadata should not be saved in persistent cache. kComponentPropertyCacheFlagIsDynamicProperty metadata should not cached at all. kComponentPropertyExtendedInfo = 'meta' A CFDictionary with extended property information. See these constants:

• kComponentPropertyInfoList

• kComponentPropertyCacheSeed

• kComponentPropertyCacheFlags

• kComponentPropertyExtendedInfo

inPropValueSize

The size of the property value to be set.

inPropValueAddress

A pointer to the value of the property to be set.

Return Value

An error code. Returns noErr if there is no error.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

ImageCompression.h

ICMCompressionSessionBeginPass

Announces the start of a specific compression pass.

OSStatus ICMCompressionSessionBeginPass (
   ICMCompressionSessionRef session,
   ICMCompressionPassModeFlags passModeFlags,
   UInt32 flags
);

Parameters

session

A compression session reference. This reference is returned by ICMCompressionSessionCreate.

passModeFlags

Flags that describe how the compressor should behave in this pass of multipass encoding: kICMCompressionPassMode_OutputEncodedFrames = 1L<<0 Output encoded frames. kICMCompressionPassMode_NoSourceFrames = 1L<<1 The client need not provide source frame buffers. kICMCompressionPassMode_WriteToMultiPassStorage = 1L<<2 The compressor may write private data to multipass storage. kICMCompressionPassMode_ReadFromMultiPassStorage = 1L<<3 The compressor may read private data from multipass storage. See these constants: