Image Codec Reference for QuickTime

Overview

An image codec (or image compressor component) is a code resource that provides QuickTime with compression or decompression services for image data.

Functions by Task

Base Image Decompressor Functions

• ImageCodecBeginBand
• ImageCodecDisposeMemory
• ImageCodecDITLEvent
• ImageCodecDITLInstall
• ImageCodecDITLItem
• ImageCodecDITLRemove
• ImageCodecDITLValidateInput
• ImageCodecDrawBand
• ImageCodecEndBand
• ImageCodecExtractAndCombineFields
• ImageCodecFlush
• ImageCodecGetDITLForSize
• ImageCodecGetMaxCompressionSizeWithSources
• ImageCodecGetSettings
• ImageCodecHitTestData
• ImageCodecInitialize
• ImageCodecIsImageDescriptionEquivalent
• ImageCodecMergeFloatingImageOntoWindow
• ImageCodecNewImageBufferMemory
• ImageCodecNewMemory
• ImageCodecPreflight
• ImageCodecQueueStarting
• ImageCodecQueueStopping
• ImageCodecRemoveFloatingImage
• ImageCodecRequestSettings
• ImageCodecSetSettings
• ImageCodecSetTimeCode
• ImageCodecSourceChanged

Low-Level Effects Functions

• ImageCodecCreateStandardParameterDialog
• ImageCodecDismissStandardParameterDialog
• ImageCodecGetParameterList
• ImageCodecIsStandardParameterDialogEvent
• ImageCodecStandardParameterDialogDoAction

Vector Codec Component Functions

• CurveAddAtomToVectorStream
• CurveAddPathAtomToVectorStream
• CurveAddZeroAtomToVectorStream
• CurveCountPointsInPath
• CurveCreateVectorStream
• CurveGetAtomDataFromVectorStream
• CurveGetLength
• CurveGetNearestPathPoint
• CurveGetPathPoint
• CurveInsertPointIntoPath
• CurveLengthToPoint
• CurveNewPath
• CurvePathPointToLength
• CurveSetPathPoint

Supporting Functions

• DisposeImageCodecDrawBandCompleteUPP
• DisposeImageCodecMPDrawBandUPP
• DisposeImageCodecTimeTriggerUPP
• ImageCodecBandCompress
• ImageCodecBandDecompress
• ImageCodecBeginPass
• ImageCodecBusy
• ImageCodecCancelTrigger
• ImageCodecCompleteFrame
• ImageCodecDecodeBand
• ImageCodecDisposeImageGWorld
• ImageCodecDroppingFrame
• ImageCodecEffectBegin
• ImageCodecEffectCancel
• ImageCodecEffectConvertEffectSourceToFormat
• ImageCodecEffectDisposeSMPTEFrame
• ImageCodecEffectGetSpeed
• ImageCodecEffectPrepareSMPTEFrame
• ImageCodecEffectRenderFrame
• ImageCodecEffectRenderSMPTEFrame
• ImageCodecEffectSetup
• ImageCodecEncodeFrame
• ImageCodecFlushFrame
• ImageCodecGetBaseMPWorkFunction
• ImageCodecGetCodecInfo
• ImageCodecGetCompressedImageSize
• ImageCodecGetCompressionTime
• ImageCodecGetDecompressLatency
• ImageCodecGetMaxCompressionSize
• ImageCodecGetParameterListHandle
• ImageCodecGetSettingsAsText
• ImageCodecGetSimilarity
• ImageCodecGetSourceDataGammaLevel
• ImageCodecHitTestDataWithFlags
• ImageCodecNewImageGWorld
• ImageCodecPreCompress
• ImageCodecPreDecompress
• ImageCodecPrepareToCompressFrames
• ImageCodecProcessBetweenPasses
• ImageCodecRequestGammaLevel
• ImageCodecScheduleFrame
• ImageCodecSetTimeBase
• ImageCodecTrimImage
• ImageCodecValidateParameters
• NewImageCodecDrawBandCompleteUPP
• NewImageCodecMPDrawBandUPP
• NewImageCodecTimeTriggerUPP
• QTPhotoDefineHuffmanTable
• QTPhotoDefineQuantizationTable
• QTPhotoSetRestartInterval
• QTPhotoSetSampling

Functions

CurveAddAtomToVectorStream

Adds an atom to a vector data stream.

ComponentResult CurveAddAtomToVectorStream (
   ComponentInstance effect,
   OSType atomType,
   Size atomSize,
   void *pAtomData,
   Handle vectorStream
);

CurveAddPathAtomToVectorStream

Adds a path to a vector data stream.

ComponentResult CurveAddPathAtomToVectorStream (
   ComponentInstance effect,
   Handle pathData,
   Handle vectorStream
);

CurveAddZeroAtomToVectorStream

Adds a kCurveEndAtom to a vector data stream; this atom marks the end of the vector data stream,

ComponentResult CurveAddZeroAtomToVectorStream (
   ComponentInstance effect,
   Handle vectorStream
);

CurveCountPointsInPath

Counts the points along either one of a path's contours or all of its contours.

ComponentResult CurveCountPointsInPath (
   ComponentInstance effect,
   gxPaths *aPath,
   unsigned long contourIndex,
   unsigned long *pCount
);

CurveCreateVectorStream

Creates a new, empty vector data stream.

ComponentResult CurveCreateVectorStream (
   ComponentInstance effect,
   Handle *pStream
);

CurveGetAtomDataFromVectorStream

Finds the first atom of a specified type within a vector data stream and get its data.

ComponentResult CurveGetAtomDataFromVectorStream (
   ComponentInstance effect,
   Handle vectorStream,
   long atomType,
   long *dataSize,
   Ptr *dataPtr
);

CurveGetLength

Calculates the length of one of a path's contours or the sum of the lengths of all of its contours.

ComponentResult CurveGetLength (
   ComponentInstance effect,
   gxPaths *target,
   long index,
   wide *wideLength
);

CurveGetNearestPathPoint

Finds the closest point on a path to a specified point.

ComponentResult CurveGetNearestPathPoint (
   ComponentInstance effect,
   gxPaths *aPath,
   FixedPoint *thePoint,
   unsigned long *contourIndex,
   unsigned long *pointIndex,
   Fixed *theDelta
);

CurveGetPathPoint

Obtains a point from a path and to find out if the point is on the curve.

ComponentResult CurveGetPathPoint (
   ComponentInstance effect,
   gxPaths *aPath,
   unsigned long contourIndex,
   unsigned long pointIndex,
   gxPoint *thePoint,
   Boolean *ptIsOnPath
);

CurveInsertPointIntoPath

Adds a new point to a path.

ComponentResult CurveInsertPointIntoPath (
   ComponentInstance effect,
   gxPoint *aPoint,
   Handle thePath,
   unsigned long contourIndex,
   unsigned long pointIndex,
   Boolean ptIsOnPath
);

CurveLengthToPoint

Obtains the point at a specified distance along a curve.

ComponentResult CurveLengthToPoint (
   ComponentInstance effect,
   gxPaths *target,
   long index,
   Fixed length,
   FixedPoint *location,
   FixedPoint *tangent
);

CurveNewPath

Creates a new path.

ComponentResult CurveNewPath (
   ComponentInstance effect,
   Handle *pPath
);

CurvePathPointToLength

Obtains the length of a path between specified starting and ending distances that is nearest a point.

ComponentResult CurvePathPointToLength (
   ComponentInstance ci,
   gxPaths *aPath,
   Fixed startDist,
   Fixed endDist,
   FixedPoint *thePoint,
   Fixed *pLength
);

CurveSetPathPoint

Changes the location of a point in a path.

ComponentResult CurveSetPathPoint (
   ComponentInstance effect,
   gxPaths *aPath,
   unsigned long contourIndex,
   unsigned long pointIndex,
   gxPoint *thePoint,
   Boolean ptIsOnPath
);

DisposeImageCodecDrawBandCompleteUPP

Disposes of an ImageCodecDrawBandCompleteUPP pointer.

void DisposeImageCodecDrawBandCompleteUPP (
   ImageCodecDrawBandCompleteUPP userUPP
);

DisposeImageCodecMPDrawBandUPP

Disposes of an ImageCodecMPDrawBandUPP pointer.

void DisposeImageCodecMPDrawBandUPP (
   ImageCodecMPDrawBandUPP userUPP
);

DisposeImageCodecTimeTriggerUPP

Disposes of an ImageCodecTimeTriggerUPP pointer.

void DisposeImageCodecTimeTriggerUPP (
   ImageCodecTimeTriggerUPP userUPP
);

ImageCodecBandCompress

Asks your component to compress an image or a band of an image.

ComponentResult ImageCodecBandCompress (
   ComponentInstance ci,
   CodecCompressParams *params
);

ImageCodecBandDecompress

Asks your component to decompress a frame.

ComponentResult ImageCodecBandDecompress (
   ComponentInstance ci,
   CodecDecompressParams *params
);

ImageCodecBeginBand

Called before drawing a band or frame; it allows your image decompressor component to save information about a band before decompressing it.

ComponentResult ImageCodecBeginBand (
   ComponentInstance ci,
   CodecDecompressParams *params,
   ImageSubCodecDecompressRecord *drp,
   long flags
);

ImageCodecBeginPass

Notifies the compressor that it should operate in multipass mode and use the given multipass storage.

ComponentResult ImageCodecBeginPass (
   ComponentInstance ci,
   ICMCompressionPassModeFlags passModeFlags,
   UInt32 flags,
   ICMMultiPassStorageRef multiPassStorage
);

ImageCodecBusy

Lets your component report whether it is performing an asynchronous operation.

ComponentResult ImageCodecBusy (
   ComponentInstance ci,
   ImageSequence seq
);

ImageCodecCancelTrigger

Cancels an image codec's ImageCodecTimeTriggerProc callback.

ComponentResult ImageCodecCancelTrigger (
   ComponentInstance ci
);

ImageCodecCompleteFrame

Directs the compressor to finish with a queued source frame, either emitting or dropping it.

ComponentResult ImageCodecCompleteFrame (
   ComponentInstance ci,
   ICMCompressorSourceFrameRef sourceFrame,
   UInt32 flags
);

ImageCodecCreateStandardParameterDialog

Creates a parameters dialog box for a specified effect.

ComponentResult ImageCodecCreateStandardParameterDialog (
   ComponentInstance ci,
   QTAtomContainer parameterDescription,
   QTAtomContainer parameters,
   QTParameterDialogOptions dialogOptions,
   DialogPtr existingDialog,
   short existingUserItem,
   QTParameterDialog *createdDialog
);

// ImageCodecCreateStandardParameterDialog coding example

// See "Discovering QuickTime," page 303

pMovableModalDialog =GetNewDialog(kExtraDialogID, NIL, (WindowRef)-1);

if (pMovableModalDialog !=NIL) {

    ImageCodecCreateStandardParameterDialog(

        compInstance,

        qtacParameterDescription,

        qtacEffectSample,

        pdOptionsModelDialogBox,

        pMovableModalDialog,

        kExtraUserItemID,

        &lCreatedDialogID);

    ShowWindow(pMovableModalDialog);

    SelectWindow(pMovableModalDialog);

    SetPort(pMovableModalDialog);

}

ImageCodecDecodeBand

Returns an ImageSubCodecDecompressRecord structure for an image codec component.

ComponentResult ImageCodecDecodeBand (
   ComponentInstance ci,
   ImageSubCodecDecompressRecord *drp,
   unsigned long flags
);

ImageCodecDismissStandardParameterDialog

Retrieves values from a standard parameter dialog box created by the low-level ImageCodecCreateStandardParameterDialog function, then closes the dialog box.

ComponentResult ImageCodecDismissStandardParameterDialog (
   ComponentInstance ci,
   QTParameterDialog createdDialog
);

ImageCodecDisposeImageGWorld

Disposes of an image graphics world associated with an image codec.

ComponentResult ImageCodecDisposeImageGWorld (
   ComponentInstance ci,
   GWorldPtr theGW
);

ImageCodecDisposeMemory

Disposes codec-allocated memory.

ComponentResult ImageCodecDisposeMemory (
   ComponentInstance ci,
   Ptr data
);

ImageCodecDITLEvent

Lets an image codec component receive and process dialog events.

ComponentResult ImageCodecDITLEvent (
   ComponentInstance ci,
   DialogRef d,
   short itemOffset,
   const EventRecord *theEvent,
   short *itemHit,
   Boolean *handled
);

ImageCodecDITLInstall

Installs added items in an image codec settings dialog box before the dialog box is displayed to the user.

ComponentResult ImageCodecDITLInstall (
   ComponentInstance ci,
   DialogRef d,
   short itemOffset
);

ImageCodecDITLItem

Receives and processes mouse clicks in the image codec settings dialog box.

ComponentResult ImageCodecDITLItem (
   ComponentInstance ci,
   DialogRef d,
   short itemOffset,
   short itemNum
);

ImageCodecDITLRemove

Removes a panel from the image codec settings dialog box.

ComponentResult ImageCodecDITLRemove (
   ComponentInstance ci,
   DialogRef d,
   short itemOffset
);

ImageCodecDITLValidateInput

Validates the contents of the user dialog box for an image codec component.

ComponentResult ImageCodecDITLValidateInput (
   ComponentInstance ci,
   Boolean *ok
);

ImageCodecDrawBand

Decompresses a band or frame.

ComponentResult ImageCodecDrawBand (
   ComponentInstance ci,
   ImageSubCodecDecompressRecord *drp
);

ImageCodecDroppingFrame

Undocumented

ComponentResult ImageCodecDroppingFrame (
   ComponentInstance ci,
   const ImageSubCodecDecompressRecord *drp
);

ImageCodecEffectBegin

Undocumented

ComponentResult ImageCodecEffectBegin (
   ComponentInstance effect,
   CodecDecompressParams *p,
   EffectsFrameParamsPtr ePtr
);

ImageCodecEffectCancel

Undocumented

ComponentResult ImageCodecEffectCancel (
   ComponentInstance effect,
   EffectsFrameParamsPtr p
);

ImageCodecEffectConvertEffectSourceToFormat

Undocumented

ComponentResult ImageCodecEffectConvertEffectSourceToFormat (
   ComponentInstance effect,
   EffectSourcePtr sourceToConvert,
   ImageDescriptionHandle requestedDesc
);

ImageCodecEffectDisposeSMPTEFrame

Undocumented

ComponentResult ImageCodecEffectDisposeSMPTEFrame (
   ComponentInstance effect,
   SMPTEFrameReference frameRef
);

ImageCodecEffectGetSpeed

Undocumented

ComponentResult ImageCodecEffectGetSpeed (
   ComponentInstance effect,
   QTAtomContainer parameters,
   Fixed *pFPS
);

ImageCodecEffectPrepareSMPTEFrame

Undocumented

ComponentResult ImageCodecEffectPrepareSMPTEFrame (
   ComponentInstance effect,
   PixMapPtr destPixMap,
   SMPTEFrameReference *returnValue
);

ImageCodecEffectRenderFrame

Undocumented

ComponentResult ImageCodecEffectRenderFrame (
   ComponentInstance effect,
   EffectsFrameParamsPtr p
);

ImageCodecEffectRenderSMPTEFrame

Undocumented

ComponentResult ImageCodecEffectRenderSMPTEFrame (
   ComponentInstance effect,
   PixMapPtr destPixMap,
   SMPTEFrameReference frameRef,
   Fixed effectPercentageEven,
   Fixed effectPercentageOdd,
   Rect *pSourceRect,
   MatrixRecord *matrixP,
   SMPTEWipeType effectNumber,
   long xRepeat,
   long yRepeat,
   SMPTEFlags flags,
   Fixed penWidth,
   long strokeValue
);

ImageCodecEffectSetup

Undocumented

ComponentResult ImageCodecEffectSetup (
   ComponentInstance effect,
   CodecDecompressParams *p
);

ImageCodecEncodeFrame

Presents the compressor with a frame to encode.

ComponentResult ImageCodecEncodeFrame (
   ComponentInstance ci,
   ICMCompressorSourceFrameRef sourceFrame,
   UInt32 flags
);

ImageCodecEndBand

Notifies your image decompressor component that decompression of a band has finished or that it was terminated by the Image Compression Manager.

ComponentResult ImageCodecEndBand (
   ComponentInstance ci,
   ImageSubCodecDecompressRecord *drp,
   OSErr result,
   long flags
);

ImageCodecExtractAndCombineFields

Performs field operations on video data.

ComponentResult ImageCodecExtractAndCombineFields (
   ComponentInstance ci,
   long fieldFlags,
   void *data1,
   long dataSize1,
   ImageDescriptionHandle desc1,
   void *data2,
   long dataSize2,
   ImageDescriptionHandle desc2,
   void *outputData,
   long *outDataSize,
   ImageDescriptionHandle descOut
);

kImageCodecExtractAndCombineFieldsSelect    =0x0015

ImageCodecFlush

Empties an image decompressor component's input queue of pending scheduled frames.

ComponentResult ImageCodecFlush (
   ComponentInstance ci
);

ImageCodecFlushFrame

Undocumented

ComponentResult ImageCodecFlushFrame (
   ComponentInstance ci,
   UInt32 flags
);

ImageCodecGetBaseMPWorkFunction

Gets an image codec's ComponentMPWorkFunctionProc callback.

ComponentResult ImageCodecGetBaseMPWorkFunction (
   ComponentInstance ci,
   ComponentMPWorkFunctionUPP *workFunction,
   void **refCon,
   ImageCodecMPDrawBandUPP drawProc,
   void *drawProcRefCon
);

ImageCodecGetCodecInfo

Notifies your codec whenever an application calls GetCodecInfo.

ComponentResult ImageCodecGetCodecInfo (
   ComponentInstance ci,
   CodecInfo *info
);

ImageCodecGetCompressedImageSize

Notifies your codec whenever an application calls GetCompressedImageSize.

ComponentResult ImageCodecGetCompressedImageSize (
   ComponentInstance ci,
   ImageDescriptionHandle desc,
   Ptr data,
   long bufferSize,
   ICMDataProcRecordPtr dataProc,
   long *dataSize
);

ImageCodecGetCompressionTime

Notifies your codec whenever an application calls GetCompressionTime.

ComponentResult ImageCodecGetCompressionTime (
   ComponentInstance ci,
   PixMapHandle src,
   const Rect *srcRect,
   short depth,
   CodecQ *spatialQuality,
   CodecQ *temporalQuality,
   unsigned long *time
);

ImageCodecGetDecompressLatency

Retrieves the video latency value from a specified video codec.

ComponentResult ImageCodecGetDecompressLatency (
   ComponentInstance ci,
   TimeRecord *latency
);

ImageCodecGetDITLForSize

Returns the size of various dialog item lists.

ComponentResult ImageCodecGetDITLForSize (
   ComponentInstance ci,
   Handle *ditl,
   Point *requestedSize
);

ImageCodecGetMaxCompressionSize

Notifies your codec whenever an application calls GetMaxCompressionSize.

ComponentResult ImageCodecGetMaxCompressionSize (
   ComponentInstance ci,
   PixMapHandle src,
   const Rect *srcRect,
   short depth,
   CodecQ quality,
   long *size
);

ImageCodecGetMaxCompressionSizeWithSources

Notifies your codec when an application calls GetCSequenceMaxCompressionSize.

ComponentResult ImageCodecGetMaxCompressionSizeWithSources (
   ComponentInstance ci,
   PixMapHandle src,
   const Rect *srcRect,
   short depth,
   CodecQ quality,
   CDSequenceDataSourcePtr sourceData,
   long *size
);

ImageCodecGetParameterList

Returns a parameter description atom container for a specified effect component instance.

ComponentResult ImageCodecGetParameterList (
   ComponentInstance ci,
   QTAtomContainer *parameterDescription
);

ImageCodecGetParameterListHandle

Returns a handle to a Mac OS resource of type 'atms'.

ComponentResult ImageCodecGetParameterListHandle (
   ComponentInstance ci,
   Handle *parameterDescriptionHandle
);

ImageCodecGetSettings

Returns the codec settings chosen by the user.

ComponentResult ImageCodecGetSettings (
   ComponentInstance ci,
   Handle settings
);

ImageCodecGetSettingsAsText

Undocumented

ComponentResult ImageCodecGetSettingsAsText (
   ComponentInstance ci,
   Handle *text
);

ImageCodecGetSimilarity

Notifies your codec when an application calls GetSimilarity.

ComponentResult ImageCodecGetSimilarity (
   ComponentInstance ci,
   PixMapHandle src,
   const Rect *srcRect,
   ImageDescriptionHandle desc,
   Ptr data,
   Fixed *similarity
);

ImageCodecGetSourceDataGammaLevel

Returns the native gamma of compressed data, if any.

ComponentResult ImageCodecGetSourceDataGammaLevel (
   ComponentInstance ci,
   Fixed *sourceDataGammaLevel
);

ImageCodecHitTestData

Notifies your codec when the application calls PtInDSequenceData.

ComponentResult ImageCodecHitTestData (
   ComponentInstance ci,
   ImageDescriptionHandle desc,
   void *data,
   Size dataSize,
   Point where,
   Boolean *hit
);

ImageCodecHitTestDataWithFlags

Undocumented

ComponentResult ImageCodecHitTestDataWithFlags (
   ComponentInstance ci,
   ImageDescriptionHandle desc,
   void *data,
   Size dataSize,
   Point where,
   long *hit,
   long hitFlags
);

ImageCodecInitialize

Called before making any other all calls to your component.

ComponentResult ImageCodecInitialize (
   ComponentInstance ci,
   ImageSubCodecDecompressCapabilities *cap
);

ImageCodecIsImageDescriptionEquivalent

Compares image descriptions.

ComponentResult ImageCodecIsImageDescriptionEquivalent (
   ComponentInstance ci,
   ImageDescriptionHandle newDesc,
   Boolean *equivalent
);

ImageCodecIsStandardParameterDialogEvent

Processes events related to a standard parameters dialog box created by ImageCodecCreateStandardParameterDialog.

ComponentResult ImageCodecIsStandardParameterDialogEvent (
   ComponentInstance ci,
   EventRecord *pEvent,
   QTParameterDialog createdDialog
);

ImageCodecMergeFloatingImageOntoWindow

Draws the current contents of a floating image.

ComponentResult ImageCodecMergeFloatingImageOntoWindow (
   ComponentInstance ci,
   UInt32 flags
);

ImageCodecNewImageBufferMemory

Asks a codec to allocate memory for an offscreen buffer of non-RGB pixels.

ComponentResult ImageCodecNewImageBufferMemory (
   ComponentInstance ci,
   CodecDecompressParams *params,
   long flags,
   ICMMemoryDisposedUPP memoryGoneProc,
   void *refCon
);

ImageCodecNewImageGWorld

Undocumented

ComponentResult ImageCodecNewImageGWorld (
   ComponentInstance ci,
   CodecDecompressParams *params,
   GWorldPtr *newGW,
   long flags
);

ImageCodecNewMemory

Requests codec-allocated memory.

ComponentResult ImageCodecNewMemory (
   ComponentInstance ci,
   Ptr *data,
   Size dataSize,
   long dataUse,
   ICMMemoryDisposedUPP memoryGoneProc,
   void *refCon
);

ImageCodecPreCompress

Notifies your component before compressing an image or a band of an image.

ComponentResult ImageCodecPreCompress (
   ComponentInstance ci,
   CodecCompressParams *params
);

ImageCodecPreDecompress

Notifies your component before decompressing an image or sequence of frames.

ComponentResult ImageCodecPreDecompress (
   ComponentInstance ci,
   CodecDecompressParams *params
);

ImageCodecPreflight

Called before decompressing an image, in response to an ImageCodecPreDecompress call from the Image Compression Manager.

ComponentResult ImageCodecPreflight (
   ComponentInstance ci,
   CodecDecompressParams *params
);

ImageCodecPrepareToCompressFrames

Prepares the compressor to receive frames.

ComponentResult ImageCodecPrepareToCompressFrames (
   ComponentInstance ci,
   ICMCompressorSessionRef session,
   ICMCompressionSessionOptionsRef compressionSessionOptions,
   ImageDescriptionHandle imageDescription,
   void *reserved,
   CFDictionaryRef *compressorPixelBufferAttributesOut
);

ImageCodecProcessBetweenPasses

Provides the compressor with an opportunity to perform processing between passes.

ComponentResult ImageCodecProcessBetweenPasses (
   ComponentInstance ci,
   ICMMultiPassStorageRef multiPassStorage,
   Boolean *interpassProcessingDoneOut,
   ICMCompressionPassModeFlags *requestedNextPassModeFlagsOut
);

ImageCodecQueueStarting

Called by the base image decompressor before decompressing the frames in the queue if your image decompressor component supports asynchronous scheduled decompression.

ComponentResult ImageCodecQueueStarting (
   ComponentInstance ci
);

ImageCodecQueueStopping

Notifies your component that the frames in the queue have been decompressed, if your image decompressor component supports asynchronous scheduled decompression.

ComponentResult ImageCodecQueueStopping (
   ComponentInstance ci
);

ImageCodecRemoveFloatingImage

Hides an image codec's floating image without having to close the component.

ComponentResult ImageCodecRemoveFloatingImage (
   ComponentInstance ci,
   UInt32 flags
);

ImageCodecRequestGammaLevel

Asks an image codec to convert from source to destination gamma levels.

ComponentResult ImageCodecRequestGammaLevel (
   ComponentInstance ci,
   Fixed srcGammaLevel,
   Fixed dstGammaLevel,
   long *codecCanMatch
);

ImageCodecRequestSettings

Displays a dialog box containing codec-specific compression settings.

ComponentResult ImageCodecRequestSettings (
   ComponentInstance ci,
   Handle settings,
   Rect *rp,
   ModalFilterUPP filterProc
);

ImageCodecScheduleFrame

Undocumented

ComponentResult ImageCodecScheduleFrame (
   ComponentInstance ci,
   const ImageSubCodecDecompressRecord *drp,
   ImageCodecTimeTriggerUPP triggerProc,
   void *triggerProcRefCon
);

ImageCodecSetSettings

Sets the settings of an optional image codec dialog box.

ComponentResult ImageCodecSetSettings (
   ComponentInstance ci,
   Handle settings
);

ImageCodecSetTimeBase

Sets the time base for an image codec component.

ComponentResult ImageCodecSetTimeBase (
   ComponentInstance ci,
   void *base
);

ImageCodecSetTimeCode

Sets the timecode for the next frame that is to be decompressed.

ComponentResult ImageCodecSetTimeCode (
   ComponentInstance ci,
   void *timeCodeFormat,
   void *timeCodeTime
);

ImageCodecSourceChanged

Notifies your codec that one of the data sources has changed when an application calls CDSequenceSetSourceData or CDSequenceChangedSourceData.

ComponentResult ImageCodecSourceChanged (
   ComponentInstance ci,
   UInt32 majorSourceChangeSeed,
   UInt32 minorSourceChangeSeed,
   CDSequenceDataSourcePtr sourceData,
   long *flagsOut
);

ImageCodecStandardParameterDialogDoAction

Allows you to control the behavior of a standard parameter dialog box created by ImageCodecCreateStandardParameterDialog.

ComponentResult ImageCodecStandardParameterDialogDoAction (
   ComponentInstance ci,
   QTParameterDialog createdDialog,
   long action,
   void *params
);

ImageCodecTrimImage

Notifies your component whenever an application calls TrimImage.

ComponentResult ImageCodecTrimImage (
   ComponentInstance ci,
   ImageDescriptionHandle Desc,
   Ptr inData,
   long inBufferSize,
   ICMDataProcRecordPtr dataProc,
   Ptr outData,
   long outBufferSize,
   ICMFlushProcRecordPtr flushProc,
   Rect *trimRect,
   ICMProgressProcRecordPtr progressProc
);

ImageCodecValidateParameters

Validates effect parameters.

ComponentResult ImageCodecValidateParameters (
   ComponentInstance ci,
   QTAtomContainer parameters,
   QTParameterValidationOptions validationFlags,
   StringPtr errorString
);

NewImageCodecDrawBandCompleteUPP

Allocates a Universal Procedure Pointer for an ImageCodecDrawBandCompleteProc callback.

ImageCodecDrawBandCompleteUPP NewImageCodecDrawBandCompleteUPP (
   ImageCodecDrawBandCompleteProcPtr userRoutine
);

NewImageCodecMPDrawBandUPP

Allocates a Universal Procedure Pointer for the ImageCodecMPDrawBandProc callback.

ImageCodecMPDrawBandUPP NewImageCodecMPDrawBandUPP (
   ImageCodecMPDrawBandProcPtr userRoutine
);

NewImageCodecTimeTriggerUPP

Allocates a Universal Procedure Pointer for the ImageCodecTimeTriggerProc callback.

ImageCodecTimeTriggerUPP NewImageCodecTimeTriggerUPP (
   ImageCodecTimeTriggerProcPtr userRoutine
);

QTPhotoDefineHuffmanTable

Defines a Huffman table.

ComponentResult QTPhotoDefineHuffmanTable (
   ComponentInstance codec,
   short componentNumber,
   Boolean isDC,
   unsigned char *lengthCounts,
   unsigned char *values
);

QTPhotoDefineQuantizationTable

Specifies a custom quantization table.

ComponentResult QTPhotoDefineQuantizationTable (
   ComponentInstance codec,
   short componentNumber,
   unsigned char *table
);

QTPhotoSetRestartInterval

Specifies the restart interval to use in future JPEG compression operations.

ComponentResult QTPhotoSetRestartInterval (
   ComponentInstance codec,
   unsigned short restartInterval
);

QTPhotoSetSampling

Specifies the chrominance downsampling ratio to use in future JPEG compression operations.

ComponentResult QTPhotoSetSampling (
   ComponentInstance codec,
   short yH,
   short yV,
   short cbH,
   short cbV,
   short crH,
   short crV
);

Callbacks

ComponentMPWorkFunctionProc

Undocumented

typedef ComponentResult (*ComponentMPWorkFunctionProcPtr) (void *globalRefCon, ComponentMPWorkFunctionHeaderRecordPtr header);

If you name your function MyComponentMPWorkFunctionProc, you would declare it this way:

ComponentResult MyComponentMPWorkFunctionProc (
   void                                      *globalRefCon,
   ComponentMPWorkFunctionHeaderRecordPtr    header );

ImageCodecMPDrawBandProc

Undocumented

typedef ComponentResult (*ImageCodecMPDrawBandProcPtr) (void *refcon, ImageSubCodecDecompressRecord *drp);

If you name your function MyImageCodecMPDrawBandProc, you would declare it this way:

ComponentResult MyImageCodecMPDrawBandProc (
   void                             *refcon,
   ImageSubCodecDecompressRecord    *drp );

ImageCodecTimeTriggerProc

Undocumented

typedef void (*ImageCodecTimeTriggerProcPtr) (void *refcon);

If you name your function MyImageCodecTimeTriggerProc, you would declare it this way:

void MyImageCodecTimeTriggerProc (
   void    *refcon );

Data Types

CDSequenceDataSource

Contains a linked list of all data sources for a decompression sequence.

struct CDSequenceDataSource {
   long                       recordSize;
   void *                     next;
   ImageSequence              seqID;
   ImageSequenceDataSource    sourceID;
   OSType                     sourceType;
   long                       sourceInputNumber;
   void *                     dataPtr;
   Handle                     dataDescription;
   long                       changeSeed;
   ICMConvertDataFormatUPP    transferProc;
   void *                     transferRefcon;
   long                       dataSize;
   QHdrPtr                    dataQueue;
   void *                     originalDataPtr;
   long                       originalDataSize;
   Handle                     originalDataDescription;
   long                       originalDataDescriptionSeed;
};

Fields

recordSize

The size of this structure.

next

A pointer to the next source entry. If it is NIL, there are no more entries.

seqID

The image sequence that this source is associated with.

sourceID

The source reference identifying this source.

sourceType

A four-character code describing how the input will be used. This value is passed to this parameter by CDSequenceNewDataSource when the source is created.

sourceInputNumber

A value is passed to this parameter by CDSequenceNewDataSource when the source is created.

dataPtr

A pointer to the actual source data.

dataDescription

A handle to a data structure describing the data format. This is often a handle to an ImageDescription structure.

changeSeed

An integer that is incremented each time the dataPtr field changes or that data that the dataPtr field points to changes. By remembering the value of this field and comparing to the value the next time the decompressor or compressor component is called, the component can determine if new data is present.

transferProc

Reserved.

transferRefcon

Reserved.

dataSize

The size of the data pointed to by the dataPtr field.

dataQueue

A pointer to a QHdr structure that contains a queue of CDSequenceDataSourceQueueEntry structures.

originalDataPtr

The original value of dataPtr.

originalDataSize

The original value of dataSize.

originalDataDescription

The original value of dataDescription.

originalDataDescriptionSeed

The original value of changeSeed.

CDSequenceDataSourcePtr

Represents a type used by the Image Codec API.

typedef CDSequenceDataSource * CDSequenceDataSourcePtr;

CodecCompressParams

Contains parameters that govern a compression operation.

struct CodecCompressParams {
   ImageSequence              sequenceID;
   ImageDescriptionHandle     imageDescription;
   Ptr                        data;
   long                       bufferSize;
   long                       frameNumber;
   long                       startLine;
   long                       stopLine;
   long                       conditionFlags;
   CodecFlags                 callerFlags;
   CodecCapabilities *        capabilities;
   ICMProgressProcRecord      progressProcRecord;
   ICMCompletionProcRecord    completionProcRecord;
   ICMFlushProcRecord         flushProcRecord;
   PixMap                     srcPixMap;
   PixMap                     prevPixMap;
   CodecQ                     spatialQuality;
   CodecQ                     temporalQuality;
   Fixed                      similarity;
   DataRateParamsPtr          dataRateParams;
   long                       reserved;
   UInt16                     majorSourceChangeSeed;
   UInt16                     minorSourceChangeSeed;
   CDSequenceDataSourcePtr    sourceData;
   long                       preferredPacketSizeInBytes;
   long                       requestedBufferWidth;
   long                       requestedBufferHeight;
   OSType                     wantedSourcePixelType;
   long                       compressedDataSize;
   UInt32                     taskWeight;
   OSType                     taskName;
};

Fields

sequenceID

Contains a unique sequence identifier. If the image to be compressed is part of a sequence, this field contains the sequence identifier that was assigned by CompressSequenceBegin. If the image is not part of a sequence, this field is set to 0.

imageDescription

Contains a handle to the image description structure that describes the image to be compressed.

data

Points to a location to receive the compressed image data. This is a 32-bit clean address. If there is not sufficient memory to store the compressed image, the application may choose to write the compressed data to mass storage during the compression operation. The flushProcRecord field identifies the data-unloading function that the application provides for this purpose. This field is used only by ImageCodecBandCompress.

bufferSize

Contains the size of the buffer specified by the data field. Your component sets the value of the bufferSize field to the number of bytes of compressed data written into the buffer. Your component should not return more data than the buffer can hold; it should return a nonzero result code instead. This field is used only by ImageCodecBandCompress.

frameNumber

Contains a frame identifier. Indicates the relative frame number within the sequence. The Image Compression Manager increments this value for each frame in the sequence. This field is used only by ImageCodecBandCompress.

startLine

Contains the starting line for the band. This field indicates the starting line number for the band to be compressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row is row number 0. This field is used only by ImageCodecBandCompress.

stopLine

Contains the ending line for the band. This field indicates the ending line number for the band to be compressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row in the image is row number 0. The image band includes the row specified by this field. So, to define a band that contains one row of pixels at the top of an image, you set the startLine field to 0 and the stopLine field to 1.

conditionFlags

Contains flags (see below) that identify the condition under which your component has been called. This field is used only by ImageCodecBandCompress. In addition, these fields contain information about actions taken by your component. See these constants:

• codecConditionFirstBand

• codecConditionLastBand

• codecConditionCodecChangedMask

callerFlags

Flags that provide further control information. This field is used only by ImageCodecBandCompress. See these constants:

• codecFlagUpdatePrevious

• codecFlagWasCompressed

• codecFlagUpdatePreviousComp

• codecFlagLiveGrab

capabilities

Points to a compressor capability structure. The Image Compression Manager uses this field to determine the capabilities of your compressor component. This field is used only by ImageCodecPreCompress.

progressProcRecord

Contains an ICMProgressProcRecord structure. During the compression operation, your compressor may occasionally call a function that the application provides in order to report your progress. This field contains a structure that identifies the progress function. If the progressProc field in this structure is set to NIL, the application has not supplied a progress function. This field is used only by ImageCodecBandCompress.

completionProcRecord

Contains an ICMCompletionProcRecord structure. This structure governs whether you perform the compression asynchronously. If the completionProc field in this structure is set to NIL, perform the compression synchronously. If this field is not NIL, it specifies an application completion function. Perform the compression asynchronously and call that completion function when your component is finished. If the completionProc field in this structure has a value of -1, perform the operation asynchronously but do not call the application's completion function. This field is used only by ImageCodecBandCompress.

flushProcRecord

Contains an ICMFlushProcRecord structure. If there is not enough memory to store the compressed image, the application may provide a function that unloads some of the compressed data. This field contains a structure that identifies that data-unloading function. If the application did not provide a data-unloading function, the flushProc field in this structure is set to NIL. In this case, your component writes the entire compressed image into the memory location specified by the data field. The data-unloading function structure is used only by ImageCodecBandCompress.

srcPixMap

Points to the image to be compressed. The image must be stored in a pixel map structure. The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value; the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address. This field is used only by ImageCodecBandCompress.

prevPixMap

Points to a pixel map containing the previous image. If the image to be compressed is part of a sequence that is being temporally compressed, this field defines the previous image for temporal compression. Your component should then use this previous image as the basis of comparison for the image to be compressed. If the temporalQuality field is set to 0, do not perform temporal compression. If the codecFlagUpdatePrevious flag or the codecFlagUpdatePreviousComp flag in the flags field is set to 1, update the previous image at the end of the compression operation. The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value; the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address. This field is used only by ImageCodecBandCompress.

spatialQuality

Specifies the desired compressed image quality. This field is used only by ImageCodecBandCompress.

temporalQuality

Specifies the desired sequence temporal quality. This field governs the level of compression the application desires with respect to information in successive frames in the sequence. If this field is set to 0, do not perform temporal compression on this frame. This field is used only by ImageCodecBandCompress.

similarity

Indicates the relative similarity between the frame just compressed and the previous frame when performing temporal compression. Fixed-point value, ranges from 0 (0x00000000), indicating a key frame, to 255 (0x00FF0000), indicating an identical frame that can be discarded without damage. If bad video would result from discarding a frame, the compressor should limit similarity to 254 (0x00FE0000). The Image Compression Manager may request a compressor to recompress a frame as a key frame if its similarity to its predecessor is very low (a value of 1 or 2, for example). The Image Compression Manager will not do this if the codecFlagLiveGrab flag is set, or if an asynchronous completion proc is supplied. This field is used only by ImageCodecBandCompress.

dataRateParams

Points to the parameters used when performing data rate constraint.

reserved

Reserved.

majorSourceChangeSeed

Contains an integer value that is incremented each time a data source is added or removed. This provides a fast way for a codec to know when it needs to redetermine which data source inputs are available.

minorSourceChangeSeed

Contains an integer value that is incremented each time a data source is added or removed, or the data contained in any of the data sources changes. This provides a way for a codec to know if the data available to it has changed.

sourceData

Contains a pointer to a CDSequenceDataSource structure. This structure contains a linked list of all data sources. Because each data source contains a link to the next data source, a codec can access all data sources from this field.

preferredPacketSizeInBytes

Specifies the preferred packet size for data.

requestedBufferWidth

Specifies the the width of the image buffer to use, in pixels. For this value to be used, the codecWantsSpecialScaling flag in the CodecCapabilities structure must be set.

requestedBufferHeight

Specifies the the height of the image buffer to use, in pixels. For this value to be used, the codecWantsSpecialScaling flag in the CodecCapabilities structure must be set.

wantedSourcePixelType

Undocumented

compressedDataSize

The size of the compressed image, in bytes. If this field is nonzero, it overrides the dataSize field of the ImageDescription structure. This provides a safer way for asynchronous compressors to return the size of the compressed frame data, because the dataSize field of ImageDescription may be referenced by an unlocked handle.

taskWeight

The preferred weight for multiprocessing tasks implementing this operation. You should assign a value by means of the Mac OS function MPSetTaskWeight.

taskName

The preferred type for multiprocessing tasks implementing this operation. You should assign a value by means of the Mac OS function MPSetTaskType.

CodecDecompressParams

The basic parameter block that is passed to a decompressor.

struct CodecDecompressParams {
   ImageSequence              sequenceID;
   ImageDescriptionHandle     imageDescription;
   Ptr                        data;
   long                       bufferSize;
   long                       frameNumber;
   long                       startLine;
   long                       stopLine;
   long                       conditionFlags;
   CodecFlags                 callerFlags;
   CodecCapabilities *        capabilities;
   ICMProgressProcRecord      progressProcRecord;
   ICMCompletionProcRecord    completionProcRecord;
   ICMDataProcRecord          dataProcRecord;
   CGrafPtr                   port;
   PixMap                     dstPixMap;
   BitMapPtr                  maskBits;
   PixMapPtr                  mattePixMap;
   Rect                       srcRect;
   MatrixRecord *             matrix;
   CodecQ                     accuracy;
   short                      transferMode;
   ICMFrameTimePtr            frameTime;
   long                       reserved[1];
   SInt8                      matrixFlags;
   SInt8                      matrixType;
   Rect                       dstRect;
   UInt16                     majorSourceChangeSeed;
   UInt16                     minorSourceChangeSeed;
   CDSequenceDataSourcePtr    sourceData;
   RgnHandle                  maskRegion;
   OSType **                  wantedDestinationPixelTypes;
   long                       screenFloodMethod;
   long                       screenFloodValue;
   short                      preferredOffscreenPixelSize;
   ICMFrameTimeInfoPtr        syncFrameTime;
   Boolean                    needUpdateOnTimeChange;
   Boolean                    enableBlackLining;
   Boolean                    needUpdateOnSourceChange;
   Boolean                    pad;
   long                       unused;
   CGrafPtr                   finalDestinationPort;
   long                       requestedBufferWidth;
   long                       requestedBufferHeight;
   Rect                       displayableAreaOfRequestedBuffer;
   Boolean                    requestedSingleField;
   Boolean                    needUpdateOnNextIdle;
   Boolean                    pad2[2];
   fixed                      bufferGammaLevel;
   UInt32                     taskWeight;
   OSType                     taskName;
};

Fields

sequenceID

Contains the unique sequence identifier. If the image to be decompressed is part of a sequence, this field contains the sequence identifier that was assigned by DecompressSequenceBegin. If the image is not part of a sequence, this field is set to 0.

imageDescription

Contains a handle to the ImageDescription that describes the image to be decompressed.

data

Points to the compressed image data. This must be a 32-bit clean address. The bufferSize field indicates the size of this data buffer. If the entire compressed image does not fit in memory, the application should provide a data-loading function, identified by the dataProc field of the data-loading function structure stored in the dataProcRecord field. This field is used only by ImageCodecBandDecompress.

bufferSize

Specifies the size of the image data buffer. This field is used only by ImageCodecBandDecompress.

frameNumber

Contains a frame identifier. Indicates the relative frame number within the sequence. The Image Compression Manager increments this value for each frame in the sequence. This field is used only by ImageCodecBandDecompress.

startLine

Specifies the starting line for the band. The line number refers to the pixel row in the image, starting from the top of the image. The first row in the image is row number 0. This field is used only by ImageCodecBandDecompress.

stopLine

Specifies the ending line for the band. The line number refers to the pixel row in the image, starting from the top of the image. The first row is row number 0. The image band includes the row specified by this field. So, to define a band that contains one row of pixels at the top of an image, you set the startLine field to 0 and the stopLine field to 1. This field is used only by ImageCodecBandDecompress.

conditionFlags

Contains flags (see below) that identify the condition under which your component has been called (in order to save the component some work). The flags in this field are passed to the component by ImageCodecBandCompress and ImageCodecPreDecompress when conditions change, to save it some work. In addition, these fields contain information about actions taken by your component. See these constants:

• codecConditionFirstBand

• codecConditionLastBand

• codecConditionFirstFrame

• codecConditionNewDepth

• codecConditionNewTransform

• codecConditionNewSrcRect

• codecConditionNewMatte

• codecConditionNewTransferMode

• codecConditionNewClut

• codecConditionNewAccuracy

• codecConditionNewDestination

• codecConditionCodecChangedMask

• codecConditionFirstScreen

• codecConditionDoCursor

• codecConditionCatchUpDiff

• codecConditionMaskMayBeChanged

• codecConditionToBuffer

callerFlags

Contains flags (see below) that provide further control information. This field is used only by ImageCodecBandCompress. See these constants:

• codecFlagUpdatePrevious

• codecFlagWasCompressed

• codecFlagUpdatePreviousComp

• codecFlagLiveGrab

capabilities

Points to a CodecCapabilities structure. The Image Compression Manager uses this parameter to determine the capabilities of your decompressor component. This field is used only by ImageCodecPreDecompress.

progressProcRecord

Contains a ICMProgressProcRecord structure. During the decompression operation, your decompressor may occasionally call a function that the application provides in order to report your progress. This field contains a structure that identifies the progress function. If the progressProc field of this structure is set to NIL, the application did not provide a progress function. This field is used only by ImageCodecBandDecompress.

completionProcRecord

Contains an ICMCompletionProcRecord structure. This field governs whether you perform the decompression asynchronously. If the completionProc field in this structure is set to NIL, perform the decompression synchronously. If this field is not NIL, it specifies an application completion function. Perform the decompression asynchronously and call that completion function when your component is finished. If this field has a value of -1, perform the operation asynchronously but do not call the application's completion function. This field is used only by ImageCodecBandDecompress.

dataProcRecord

Contains an ICMDataProcRecord structure. If the data stream is not all in memory, your component may call an application function that loads more compressed data. This field contains a structure that identifies that data-loading function. If the application did not provide a data-loading function, the dataProc field in this structure is set to NIL. In this case, the entire image must be in memory at the location specified by the data field. This field is used only by ImageCodecBandDecompress.

port

Points to the color graphics port that receives the decompressed image.

dstPixMap

Points to the pixel map where the decompressed image is to be displayed. The GDevice global variable is set to the destination graphics device. The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value; the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.

maskBits

Contains an update mask. If your component can mask result data, use this mask to indicate which pixels in the destination pixel map to update. Your component indicates whether it can mask with the codecCanMask flag in the flags field of the CodecCapabilities structure referred to by the capabilities field. This field is updated in response to the ImageCodecPreDecompress request. If the mask has not changed since the last ImageCodecBandDecompress request, the codecConditionCodecChangedMask flag in the conditionFlags field is set to 0. This field is used only by ImageCodecBandDecompress.

mattePixMap

Points to a pixel map that contains a blend matte. The matte can be defined at any supported pixel depth; the matte depth need not correspond to the source or destination depths. The matte must be in the coordinate system of the source image. If the application does not want to apply a blend matte, this field is set to NIL. The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value; the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address. This field is used only by ImageCodecBandDecompress.

srcRect

Points to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by the width and height fields of the image description structure referred to by the imageDescription field.

matrix

Points to a matrix structure that specifies how to transform the image during decompression.

accuracy

Constant (see below) that specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality; see CompressImage. See these constants:

• codecMinQuality

• codecLowQuality

• codecNormalQuality

• codecHighQuality

• codecMaxQuality

• codecLosslessQuality

transferMode

Specifies the QuickDraw transfer mode for the operation; see Graphics Transfer Modes.

frameTime

Contains a pointer to an ICMFrameTimeRecord structure. This structure contains a frame's time information for scheduled asynchronous decompression operations.

matrixFlags

Flag (see below) specifying the transformation matrix. Set to 0 for no transformation. See these constants:

• matrixFlagScale2x

• matrixFlagScale1x

• matrixFlagScaleHalf

matrixType

Contains the type of the transformation matrix, as returned by GetMatrixType.

dstRect

The destination rectangle. It is the result of transforming the source rectangle (the srcRect parameter) by the transformation matrix (the matrix parameter).

majorSourceChangeSeed

Contains an integer value that is incremented each time a data source is added or removed. This provides a fast way for a codec to know when it needs to redetermine which data source inputs are available.

minorSourceChangeSeed

Contains an integer value that is incremented each time a data source is added or removed, or the data contained in any of the data sources changes. This provides a way for a codec to know if the data available to it has changed.

sourceData

Contains a pointer to a CDSequenceDataSource structure. This structure contains a linked list of all data sources. Because each data source contains a link to the next data source, a codec can access all data sources from this field.

maskRegion

If the maskRegion field is not NIL, it contains a QuickDraw region that is equivalent to the bit map contained in the maskBits field. For some codecs, using the QuickDraw region may be more convenient than the mask bit map.

wantedDestinationPixelTypes

Filled in by the codec during the execution of ImageCodecPreDecompress. Contains a handle to a zero-terminated list of non-RGB pixels that the codec can decompress to. Leave set to NIL if the codec does not support non-RGB pixel spaces. The ICM copies this data structure, so it is up to the codec to dispose of it later. Since the predecompress call can be called often, it is suggested that codecs allocate this handle during the Open function and dispose of it during the Close function.

screenFloodMethod

A constant (see below) for codecs that require key-color flooding. See these constants:

• kScreenFloodMethodNone

• kScreenFloodMethodKeyColor

• kScreenFloodMethodAlpha

screenFloodValue

If screenFloodMethod is kScreenFloodMethodKeyColor, contains the index of the color that should be used to flood the image area on screen when a refresh occurs. This is valid for both indexed and direct screen devices (e.g., for devices with 16 bit depth, it should contain the 5-5-5 RGB value). If screenFloodMethod is kScreenFloodMethodAlpha, contains the value that the alpha channel should be flooded with.

preferredOffscreenPixelSize

Should be filled in ImageCodecPreDecompress with the preferred depth of an offscreen buffer should the ICM have to create one. It is not guaranteed that an offscreen buffer will actually be of this depth. A codec should still be sure to specify what depths it can decompress to by using the capabilities field. A codec might use this field if if was capable of decompressing to several depths, but was faster decompressing to a particular depth.

syncFrameTime

A pointer to an ICMFrameTimeInfo structure. This structure contains timing information about the display of the frame.

needUpdateOnTimeChange

Undocumented

enableBlackLining

If TRUE, indicates that the client has requested blacklining (displaying every other line of the image). Blacklining increases the speed of movie playback while decreasing the image quality.

needUpdateOnSourceChange

Undocumented

pad

Unused.

unused

Unused.

finalDestinationPort

Undocumented

requestedBufferWidth

Specifies the width of the image buffer to use, in pixels. For this value to be used, the codecWantsSpecialScaling flag in CodecCapabilities must be set.

requestedBufferHeight

Specifies the height of the image buffer to use, in pixels. For this value to be used, the codecWantsSpecialScaling flag in CodecCapabilities must be set.

displayableAreaOfRequestedBuffer

This field can be used to prevent parts of the requested buffer from being displayed. When the codecWantsSpecialScaling flag is set, this rectangle can be filled in to indicate what portion of the requested buffer's width and height should be used. The buffer rectangle created by the requested buffer is always based at (0,0), so this coordinate system is also used by displayableAreaOfRequestedBuffer. If this field is not filled in, a default value of (0,0,0,0) is used, and the entire buffer is displayed. Use this field if you are experiencing edge problems with FlashPix images.

requestedSingleField

Undocumented

needUpdateOnNextIdle

Undocumented

pad2

Unused.

bufferGammaLevel

The gamma level of the data buffer.

taskWeight

The preferred weight for multiprocessing tasks implementing this operation. You should assign a value by means of the Mac OS function MPSetTaskWeight.

taskName

The preferred type for multiprocessing tasks implementing this operation. You should assign a value by means of the Mac OS function MPSetTaskType.

ComponentMPWorkFunctionUPP

Represents a type used by the Image Codec API.

typedef STACK_UPP_TYPE(ComponentMPWorkFunctionProcPtr) ComponentMPWorkFunctionUPP;

EffectsFrameParams

Contains information about the current frame of a video effect.

struct EffectsFrameParams {
   ICMFrameTimeRecord    frameTime;
   long                  effectDuration;
   Boolean               doAsync;
   unsigned char         pad[3];
   EffectSourcePtr       source;
   void *                refCon;
};

Fields

frameTime

Timing data for the current frame. This structure includes information such as the total number of frames being rendered in this sequence, and the current frame number.

effectDuration

The duration of a single effect frame.

doAsync

This field contains TRUE if the effect can process asynchronously.

pad

Unused.

source

A pointer to the input sources; see the EffectSource structure.

refCon

A pointer to storage for this instantiation of the effect.

EffectsFrameParamsPtr

Represents a type used by the Image Codec API.

typedef EffectsFrameParams * EffectsFrameParamsPtr;

EffectSource

Provides data for the EffectsFrameParams structure.

struct EffectSource {
   long               effectType;
   Ptr                data;
   SourceData         source;
   EffectSourcePtr    next;

Fields

effectType

The type of the effect or a default effect type constant (see below). Enter kEffectRawSource if the source is raw image compression manager data. See these constants:

• kEffectRawSource

• kEffectGenericType

data

A pointer to the track data for the effect.

source

The source itself.

next

A pointer to the next source in the input chain.

lastTranslatedFrameTime

The start frame time of last converted frame; this value may be -1.

lastFrameDuration

The duration of the last converted frame; this value may be 0.

lastFrameTimeScale

The time scale of this source frame; this field has meaning only if the lastTranslatedFrameTime and lastFrameDuration fields are valid.

EffectSourcePtr

Represents a type used by the Image Codec API.

typedef EffectSource * EffectSourcePtr;

gxPaths

Encapsulates a multiple-path geometry.

struct gxPaths {
   long      contours;
   gxPath    contour[1];
};

Fields

contours

The number of path contours.

contour

The path contours; see gxPath.

gxPoint

Defines a point in vector graphics.

struct gxPoint {
   Fixed    x;
   Fixed    y;
};

Fields

x

A horizontal distance. Greater values of the x field indicate distances further to the right.

y

A vertical distance. Greater values of the y field indicate distances further down.

ImageCodecMPDrawBandUPP

Represents a type used by the Image Codec API.

typedef STACK_UPP_TYPE(ImageCodecMPDrawBandProcPtr) ImageCodecMPDrawBandUPP;

ImageCodecTimeTriggerUPP

Represents a type used by the Image Codec API.

typedef STACK_UPP_TYPE(ImageCodecTimeTriggerProcPtr) ImageCodecTimeTriggerUPP;

ImageSubCodecDecompressCapabilities

Returned by an image decompressor component in response to ImageCodecInitialize.

struct ImageSubCodecDecompressCapabilities {
   long       recordSize;
   long       decompressRecordSize;
   Boolean    canAsync;
   UInt8      pad0;

Fields

recordSize

The size of this structure in bytes.

decompressRecordSize

The size of the ImageSubCodecDecompressRecord structure that your image decompressor component requires. This structure is used to pass information from ImageCodecBeginBand to ImageCodecDrawBand and ImageCodecEndBand.

canAsync

Specifies whether your image decompressor component can perform asynchronous scheduled decompression. This should be TRUE unless your image decompressor component calls functions that cannot be called during interrupt time.

pad0

Unused.

ImageSubCodecDecompressRecord

Contains information needed for decompressing a frame.

struct ImageSubCodecDecompressRecord {
   Ptr                      baseAddr;
   long                     rowBytes;
   Ptr                      codecData;
   ICMProgressProcRecord    progressProcRecord;
   ICMDataProcRecord        dataProcRecord;
   void *                   userDecompressRecord;
   UInt8                    frameType;
   UInt8                    pad[3];
   long                     priv[2];
};

Fields

baseAddr

The address of the destination pixel map, which includes adjustment for the offset. Note that if the bit depth of the pixel map is less than 8, your image decompressor component must adjust for the bit offset.

rowBytes

The offset in bytes from one row of the destination pixel map to the next. The value of the rowBytes field must be less than 0x4000.

codecData

A pointer to the data to be decompressed.

progressProcRecord

An ICMProgressProcRecord structure that specifies a progress function. This function reports on the progress of a decompression operation. If there is no progress function, the Image Compression Manager sets the progressProc field in the ICMProgressProcRecord structure to NIL.

dataProcRecord

An ICMDataProcRecord structure that specifies a data-loading function. If the data to be decompressed is not all in memory, your component can call this function to load more data. If there is no data-loading function, the Image Compression Manager sets the dataProc field in the ICMDataProcRecord structure to NIL, and the entire image must be in memory at the location specified by the codecData field of the ImageSubCodecDecompressRecord structure.

userDecompressRecord

A pointer to storage for the decompression operation. The storage is allocated by the base image decompressor after it calls ImageCodecInitialize. The size of the storage is determined by the decompressRecordSize field of the ImageSubCodecDecompressCapabilities structure that is returned by ImageCodecInitialize. Your image decompressor component should use this storage to store any additional information needed about the frame in order to decompress it.

frameType

A constant (see below) that indicates the frame type. See these constants:

• kCodecFrameTypeUnknown

• kCodecFrameTypeKey

• kCodecFrameTypeDifference

• kCodecFrameTypeDroppableDifference

pad

Unused.

priv

Private to QuickTime; do not use.

QTParameterValidationOptions

Represents a type used by the Image Codec API.

typedef long QTParameterValidationOptions;

SMPTEFlags

Represents a type used by the Image Codec API.

typedef long SMPTEFlags;

SMPTEFrameReference

Represents a type used by the Image Codec API.

typedef long SMPTEFrameReference;

SMPTEWipeType

Represents a type used by the Image Codec API.

typedef unsigned long SMPTEWipeType;

Constants

Codec Properties

Constants that represent the properties of codecs.

enum {
   /* The minimum data size for spooling in or out data */
   codecMinimumDataSize          = 32768L
};
enum {
   codecConditionFirstBand       = 1L << 0,
   codecConditionLastBand        = 1L << 1,
   codecConditionFirstFrame      = 1L << 2,
   codecConditionNewDepth        = 1L << 3,
   codecConditionNewTransform    = 1L << 4,
   codecConditionNewSrcRect      = 1L << 5,
   codecConditionNewMask         = 1L << 6,
   codecConditionNewMatte        = 1L << 7,
   codecConditionNewTransferMode = 1L << 8,
   codecConditionNewClut         = 1L << 9,
   codecConditionNewAccuracy     = 1L << 10,
   codecConditionNewDestination  = 1L << 11,
   codecConditionFirstScreen     = 1L << 12,
   codecConditionDoCursor        = 1L << 13,
   codecConditionCatchUpDiff     = 1L << 14,
   codecConditionMaskMayBeChanged = 1L << 15,
   codecConditionToBuffer        = 1L << 16,
   codecConditionCodecChangedMask = 1L << 31
};
enum {
   codecInfoResourceType         = 'cdci', /* codec info resource type */
   codecInterfaceVersion         = 2     /* high word returned in component GetVersion */
};
enum {
   codecSuggestedBufferSentinel  = 'sent' /* codec public resource containing suggested data pattern to put past end of data buffer */
};
enum {
   codecUsesOverlaySurface       = 1L << 0, /* codec uses overlay surface */
   codecImageBufferIsOverlaySurface = 1L << 1, /* codec image buffer is overlay surface,
   the bits in the buffer are on the screen */
   codecSrcMustBeImageBuffer     = 1L << 2, /* codec can only source data from an image buffer */
   codecImageBufferIsInAGPMemory = 1L << 4, /* codec image buffer is in AGP space,
   byte writes are OK */
   codecImageBufferIsInPCIMemory = 1L << 5, /* codec image buffer is across a PCI bus; byte writes are bad */
   codecImageBufferMemoryFlagsValid = 1L << 6, /* set by ImageCodecNewImageBufferMemory/NewImageGWorld to indicate that it set the AGP/PCI flags (supported in QuickTime 6.0 and later) */
   codecDrawsHigherQualityScaled = 1L << 7, /* codec will draw higher-quality image if it performs scaling (eg,
   wipe effect with border) */
   codecSupportsOutOfOrderDisplayTimes = 1L << 8, /* codec supports frames queued in one order for display in a different order,
   eg,
   IPB content */
   codecSupportsScheduledBackwardsPlaybackWithDifferenceFrames = 1L << 9 /* codec can use additional buffers to minimise redecoding during backwards playback */
};

Constants

codecConditionFirstBand

An input flag that indicates if this is the first band in the frame. If this flag is set to 1, then your component is being called for the first time for the current frame.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionLastBand

An input flag that indicates if this is the last band in the frame. If this flag is set to 1, then your component is being called for the last time for the current frame. If the codecConditionFirstBand flag is also set to 1, this is the only time the Image Compression Manager is calling your component for the current frame.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionFirstFrame

An input flag that indicates that this is the first frame to be decompressed for this image sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionNewDepth

An input flag that indicates that the depth of the destination has changed for this image sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionNewTransform

An input flag that indicates that the transformation matrix has changed for this sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionNewSrcRect

An input flag that indicates that the source rectangle has changed for this sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionNewMatte

An input flag that indicates that the matte pixel map has changed for this sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionNewTransferMode

An input flag that indicates that the transfer mode has changed for this sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionNewClut

An input flag that indicates that the color lookup table has changed for this sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionNewAccuracy

An input flag that indicates to the component that the accuracy parameter has changed for this sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionNewDestination

An input flag that indicates to the component that the destination pixel map has changed for this sequence.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionFirstScreen

Indicates when the codec is decompressing an image to the first of multiple screens. That is, if the decompressed image crosses multiple screens, then the codec can look at this flag to determine if this is the first time an image is being decompressed for each of the screens to which it is being decompressed. A codec that depends on the maskBits field of this structure being a valid RgnHandle on ImageCodecPreDecompress needs to know that in this case it is not able to clip images since the region handle is only passed for the first of the screens; clipping would be incorrect for the subsequent screen for that image.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionDoCursor

Set to 1 if the decompressor component should shield and unshield the cursor for the current decompression operation. This flag should be set only if the codec has indicated its ability to handle cursor shielding by setting the codecCanShieldCursor flag in the capabilities field during ImageCodecPreDecompress.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionCatchUpDiff

Indicates if the current frame is a "catch-up" frame. Set this flag to 1 if the current frame is a catch-up frame. Note that you must also set the codecFlagCatchUpDiff flag to 1. This may be useful to decompressors that can drop frames when playback is falling behind.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionMaskMayBeChanged

The Image Compression Manager has always included support for decompressors that could provide a bit mask of pixels that were actually drawn when a particular frame was decompressed. If a decompressor can provide a bit mask of pixels that changed, the Image Compression Manager transfers to the screen only the pixels that actually changed. QuickTime 2.1 extended this capability by adding this new condition flag. The decompressor should write back the mask only if this flag is set. This flag is used only by ImageCodecFlush.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionToBuffer

Set to 1 if the current decompression operation is decompressing into an offscreen buffer.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecConditionCodecChangedMask

An output flag that indicates that the component has changed the mask bits. If your image decompressor component can mask decompressed images and if some of the image pixels should not be written to the screen, set to 0 the corresponding bits in the mask defined by the maskBits field in the decompression parameter structure. In addition, set this flag to 1. Otherwise, set this flag to 0.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecInfoResourceType

Codec info resource type.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecInterfaceVersion

High word returned in component GetVersion.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecSuggestedBufferSentinel

Codec public resource containing suggested data pattern to put past end of data buffer.

Available in OS X v10.2 and later.

Declared in ImageCodec.h.

codecUsesOverlaySurface

Undocumented

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecImageBufferIsOverlaySurface

Indicates that the codec's image buffer is an overlay surface; the bits in the buffer appear on the screen.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecSrcMustBeImageBuffer

Indicates that the codec can accept source data only from an image buffer.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecImageBufferIsInAGPMemory

Indicates that the codec's image buffer resides in AGP address space and accepts byte writes.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecImageBufferIsInPCIMemory

Codec image buffer is across a PCI bus; byte writes are bad.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

codecImageBufferMemoryFlagsValid

Set by ImageCodecNewImageBufferMemory or NewImageGWorld to indicate that the codecImageBufferIsInAGPMemory and codecImageBufferIsInPCIPMemory flags have been set correctly.

Available in OS X v10.2 and later.

Declared in ImageCodec.h.

codecDrawsHigherQualityScaled

Indicates that the codec will draw a higher quality image if it performs scaling; for example, while drawing a wipe effect with a border.

Available in OS X v10.2 and later.

Declared in ImageCodec.h.

codecSupportsOutOfOrderDisplayTimes

Codec supports frames queued in one order for display in a different order, for example IPB content.

Available in OS X v10.3 and later.

Declared in ImageCodec.h.

ImageSubCodecDecompressRecord Values

Constants passed to ImageSubCodecDecompressRecord.

enum {
   kCodecFrameTypeUnknown        = 0,
   kCodecFrameTypeKey            = 1,
   kCodecFrameTypeDifference     = 2,
   kCodecFrameTypeDroppableDifference = 3
};

Constants

kCodecFrameTypeUnknown

The frame type is unknown.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

kCodecFrameTypeKey

This is a key frame.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

kCodecFrameTypeDifference

This is a difference frame.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

EffectSource Values

Constants passed to EffectSource.

enum {
   kEffectRawSource              = 0,    /* the source is raw image data*/
   kEffectGenericType            = 'geff' /* generic effect for combining others*/
};

Constants

kEffectRawSource

The source is raw Image Compression Manager data.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

ImageCodecValidateParameters Values

Constants passed to ImageCodecValidateParameters.

enum {
   kParameterValidationNoFlags   = 0x00000000,
   kParameterValidationFinalValidation = 0x00000001
};

CodecDecompressParams Values

Constants passed to CodecDecompressParams.

enum {
   kScreenFloodMethodNone        = 0,
   kScreenFloodMethodKeyColor    = 1,
   kScreenFloodMethodAlpha       = 2
};
enum {
   matrixFlagScale2x             = 1L << 7,
   matrixFlagScale1x             = 1L << 6,
   matrixFlagScaleHalf           = 1L << 5
};

Constants

kScreenFloodMethodNone

No method; value is 0.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

kScreenFloodMethodKeyColor

Key color method; value is 1.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

kScreenFloodMethodAlpha

Alpha channel method; value is 2.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

matrixFlagScale2x

Double-scale; value is 1L<<7.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.

matrixFlagScale1x

Single-scale; value is 1L<<6.

Available in OS X v10.0 and later.

Declared in ImageCodec.h.