Image Codec Reference for QuickTime

Framework
Frameworks/QuickTime.framework
Declared in
Components.h
ImageCodec.h

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

Low-Level Effects Functions

Vector Codec Component Functions

Supporting Functions

Functions

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 );

Parameters
globalRefCon

Undocumented

header

Pointer to a ComponentMPWorkFunctionHeaderRecord structure.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
ImageCodec.h

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 );

Parameters
refcon

Pointer to a reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

drp

Pointer to an ImageSubCodecDecompressRecord structure.

Return Value

See Error Codes. Your callback should return noErr if there is no error.

Declared In
ImageCodec.h

ImageCodecTimeTriggerProc

Undocumented

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

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

void MyImageCodecTimeTriggerProc (
   void    *refcon );

Parameters
refcon

Pointer to a reference constant that the client code supplies to your callback. You can use this reference to point to a data structure containing any information your callback needs.

Declared In
ImageCodec.h

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.

Discussion

Because each data source is associated with a link to the next data source, a codec can access all data sources using this structure.

See also ImageCodecGetMaxCompressionSizeWithSources and ImageCodecSourceChanged.

Version Notes

Fields from dataQueue onward were introduced in QuickTime 3.

Declared In
ImageCodec.h

CDSequenceDataSourcePtr

Represents a type used by the Image Codec API.

typedef CDSequenceDataSource * CDSequenceDataSourcePtr;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

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.

Discussion

Compressor components accept the parameters that govern a compression operation in the form of the CodecCompressParams structure. This structure is used by ImageCodecBandCompress and ImageCodecPreCompress.

See also ImageCodecBandCompress and ImageCodecPreCompress.

Version Notes

Some of the fields in CodecCompressParams were added for various versions of QuickTime starting with version 2.1. See comments in the C interface file for details.

Declared In
ImageCodec.h

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.

Discussion

The Image Compression Manager creates the decompression parameters structure, and your image decompressor component is required only to provide values for the wantedDestinationPixelSize and wantedDestinationPixelTypes fields of the structure. Your image decompressor component can also modify other fields if necessary. For example, if it can scale images, it must set the codecCapabilityCanScale flag in the capabilities field of the structure.

See also ImageCodecBandDecompress, ImageCodecBeginBand, ImageCodecEffectBegin, ImageCodecEffectSetup, ImageCodecNewImageBufferMemory, ImageCodecNewImageGWorld, ImageCodecPreDecompress, and ImageCodecPreflight.

Version Notes

Some of the fields in CodecDecompressParams were added for various versions of QuickTime starting with version 2.1. See comments in the C interface file for details.

Declared In
ImageCodec.h

ComponentMPWorkFunctionUPP

Represents a type used by the Image Codec API.

typedef STACK_UPP_TYPE(ComponentMPWorkFunctionProcPtr) ComponentMPWorkFunctionUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Components.h

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.

Declared In
ImageCodec.h

EffectsFrameParamsPtr

Represents a type used by the Image Codec API.

typedef EffectsFrameParams * EffectsFrameParamsPtr;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

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.

Declared In
ImageCodec.h

EffectSourcePtr

Represents a type used by the Image Codec API.

typedef EffectSource * EffectSourcePtr;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

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.

Discussion

The contours field indicates the total number of contours (in other words, the total number of separate paths), and the contour field is an array that contains the path geometries. Since a gxPaths structure is of variable length and every element in it is of type long, you can define a path geometry as an array of long integer values.

See also CurveCountPointsInPath, CurveGetLength, CurveGetNearestPathPoint, CurveGetPathPoint, CurveLengthToPoint, CurvePathPointToLength, and CurveSetPathPoint.

Declared In
ImageCodec.h

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.

Discussion

The location of the origin depends on the context where you use the point; for example, it might be the upper-left corner of a view port. Notice that the x and y fields are of type Fixed. QuickDraw GX allows you to specify fractional coordinate positions.

See also CurveGetPathPoint, CurveInsertPointIntoPath, and CurveSetPathPoint.

Declared In
ImageCodec.h

ImageCodecMPDrawBandUPP

Represents a type used by the Image Codec API.

typedef STACK_UPP_TYPE(ImageCodecMPDrawBandProcPtr) ImageCodecMPDrawBandUPP;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

ImageCodecTimeTriggerUPP

Represents a type used by the Image Codec API.

typedef STACK_UPP_TYPE(ImageCodecTimeTriggerProcPtr) ImageCodecTimeTriggerUPP;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

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.

Discussion

The first function call that your image decompressor component receives from the base image decompressor is always a call to ImageCodecInitialize. In response to this call, your image decompressor component returns an ImageSubCodecDecompressCapabilities structure that specifies its capabilities.

See also ImageCodecInitialize.

Declared In
ImageCodec.h

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.

Discussion

See also ImageCodecBeginBand, ImageCodecDrawBand, ImageCodecEndBand, ImageCodecMPDrawBandProc.

Declared In
ImageCodec.h

QTParameterValidationOptions

Represents a type used by the Image Codec API.

typedef long QTParameterValidationOptions;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

SMPTEFlags

Represents a type used by the Image Codec API.

typedef long SMPTEFlags;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

SMPTEFrameReference

Represents a type used by the Image Codec API.

typedef long SMPTEFrameReference;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

SMPTEWipeType

Represents a type used by the Image Codec API.

typedef unsigned long SMPTEWipeType;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
ImageCodec.h

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

Declared in ImageCodec.h.

codecInfoResourceType

Codec info resource type.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in ImageCodec.h.

codecInterfaceVersion

High word returned in component GetVersion.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

Declared in ImageCodec.h.

codecUsesOverlaySurface

Undocumented

Available in OS X v10.0 and later.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

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.

Not available to 64-bit applications.

Declared in ImageCodec.h.

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.

Not available to 64-bit applications.

Declared in ImageCodec.h.

kCodecFrameTypeKey

This is a key frame.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in ImageCodec.h.

kCodecFrameTypeDifference

This is a difference frame.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in ImageCodec.h.

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.

Not available to 64-bit applications.

Declared in ImageCodec.h.

Declared In
ImageCodec.h

ImageCodecValidateParameters Values

Constants passed to ImageCodecValidateParameters.

enum {
   kParameterValidationNoFlags   = 0x00000000,
   kParameterValidationFinalValidation = 0x00000001
};
Declared In
ImageCodec.h

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.

Not available to 64-bit applications.

Declared in ImageCodec.h.

kScreenFloodMethodKeyColor

Key color method; value is 1.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in ImageCodec.h.

kScreenFloodMethodAlpha

Alpha channel method; value is 2.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in ImageCodec.h.

matrixFlagScale2x

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

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in ImageCodec.h.

matrixFlagScale1x

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

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in ImageCodec.h.

Declared In
ImageCodec.h