Compression and Decompression Reference for QuickTime

Framework	Frameworks/QuickTime.framework
Declared in	IOMacOSTypes.h ImageCompression.h MacTypes.h OSUtils.h

Overview

QuickTime compression and decompression APIs help applications compress and decompress movie data.

Functions by Task

Aligning Windows

Applying Matrix Transformations

Changing Sequence-Compression Parameters

Changing Sequence-Decompression Parameters

Constraining Compressed Data

Controlling Hardware Scaling

Creating an Effect Sample Description

Creating File Previews

Getting Information About Compressed Data

Getting Information About Compressor Components

Image Compression Manager Utility Functions

Image Transcoder Support

Making Thumbnail Pictures

Managing Matrices

Obtaining a Graphics Importer Instance

Working With Graphics Devices and Graphics Worlds

Working With Image Descriptions

Working With Pictures and PICT Files

Working With Pixel Maps

Working With Sequences

Working With the StdPix Function

Working With Video Fields

Supporting Functions

Functions

AddFilePreview

Adds a preview to a file.

OSErr AddFilePreview (
   short resRefNum,
   OSType previewType,
   Handle previewData
);

Parameters

resRefNum: The resource file for this operation. You must have opened this resource file with write permission. If there is a preview in the specified file, the Movie Toolbox replaces that preview with a new one.
previewType: The resource type to be assigned to the preview. This type should correspond to the type of data stored in the preview. For example, if you have created a QuickDraw picture that you want to use as a preview for a file, you should set the previewType parameter to 'PICT'.
previewData: A handle to the preview data. For example, if the preview data is a picture, you would provide a picture handle.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You must have created the preview data yourself. If the specified file already has a preview defined, the AddFilePreview function replaces it with the new preview.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

AddImageDescriptionExtension

Adds an extension to an ImageDescription structure.

OSErr AddImageDescriptionExtension (
   ImageDescriptionHandle desc,
   Handle extension,
   long idType
);

Parameters

desc: A handle to the ImageDescription structure to add the extension to.
extension: The handle containing the extension data.
idType: A four-byte signature identifying the type of data being added to the ImageDescription.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows the application to add custom data to an ImageDescriptionHandle. This data could be specific to the compressor component referenced by the ImageDescription structure.

Special Considerations

The Image Compression Manager makes a copy of the data referred to by the extension parameter. Thus, your application should dispose its copy of the data when it is no longer needed.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

AlignScreenRect

Aligns a specified rectangle to the strictest screen that the rectangle intersects.

void AlignScreenRect (
   Rect *rp,
   ICMAlignmentProcRecordPtr alignmentProc
);

Parameters

rp: A pointer to a rectangle defined in global screen coordinates.
alignmentProc: Points to your own alignment behavior function. Set this parameter to NIL to use the standard behavior.

Discussion

For a specification of your alignment function, see ICMAlignmentProc.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

AlignWindow

Moves a specified window to the nearest optimal alignment position.

void AlignWindow (
   WindowRef wp,
   Boolean front,
   const Rect *alignmentRect,
   ICMAlignmentProcRecordPtr alignmentProc
);

Parameters

wp: Points to the window to be aligned.
front: The frontmost window. If the front parameter is TRUE and the window specified in the wp parameter isn't the active window, AlignWindow makes it the active window.
alignmentRect: A pointer to a rectangle in window coordinates that allows you to align the window to a rectangle within the window. Set this parameter to NIL to align using the bounds of the window.
alignmentProc: Points to a function that allows you to provide your own alignment behavior. Set this parameter to NIL to use the standard behavior.

Discussion

For a specification of your alignment function, see ICMAlignmentProc.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceBusy

Checks the status of an asynchronous compression or decompression operation.

OSErr CDSequenceBusy (
   ImageSequence seqID
);

Parameters

seqID: Contains the unique sequence identifier that was returned by DecompressSequenceBegin or CompressSequenceBegin.

Return Value

If there is no asynchronous operation in progress, CDSequenceBusy returns a 0 result code. If there is an asynchronous operation in progress, the result code is 1. Negative result codes indicate an error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceChangedSourceData

Notifies the compressor that the image source data has changed.

OSErr CDSequenceChangedSourceData (
   ImageSequenceDataSource sourceID
);

Parameters

sourceID: Contains the source identifier of the data source.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Use this function to indicate that the image has changed but the data pointer to that image has not changed. For example, if the data pointer points to the base address of a PixMap structure, the image in the PixMap can change, but the data pointer remains constant.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceDisposeDataSource

Disposes of a data source.

OSErr CDSequenceDisposeDataSource (
   ImageSequenceDataSource sourceID
);

Parameters

sourceID: The data source identifier that was returned by the CDSequenceNewDataSource function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Use this function to dispose of a data source created by the CDSequenceNewDataSource function. All data sources are automatically disposed when the sequence they are associated with is disposed.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceDisposeMemory

Disposes of memory allocated by the codec.

OSErr CDSequenceDisposeMemory (
   ImageSequence seqID,
   Ptr data
);

Parameters

seqID: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
data: Points to the previously allocated memory block.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You call this function to release memory allocated by the CDSequenceNewMemory function.

Special Considerations

Do not call CDSequenceDisposeMemory at interrupt time.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceEnd

Indicates the end of processing for an image sequence.

OSErr CDSequenceEnd (
   ImageSequence seqID
);

Parameters

seqID: Contains the unique sequence identifier that was returned by DecompressSequenceBegin or CompressSequenceBegin.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceEquivalentImageDescription

Reports whether two image descriptions are the same.

OSErr CDSequenceEquivalentImageDescription (
   ImageSequence seqID,
   ImageDescriptionHandle newDesc,
   Boolean *equivalent
);

Parameters

seqID: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
newDesc: A handle to the ImageDescription structure structure that describes the compressed image.
equivalent: A pointer to a Boolean value. If the ImageDescriptionHandle provided in the newDesc parameter is equivalent to the ImageDescription structure currently in use by the image sequence, this value is set to TRUE. If the ImageDescriptionHandle is not equivalent, and therefore a new image sequence must be created to display an image using the new image description, this value is set to FALSE.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows an application to ask whether two image descriptions are the same. If they are, the decompressor does not have to create a new image decompression sequence to display those images.

Special Considerations

The Image Compression Manager can only implement part of this function by itself. There are some fields in the ImageDescription structure that it knows are irrelevant to the decompressor. If the Image Compression Manager determines that there are differences in fields that may be significant to the codec, it calls the function ImageCodecIsImageDescriptionEquivalent to ask the codec.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceEquivalentImageDescriptionS

Undocumented

OSErr CDSequenceEquivalentImageDescriptionS (
   ImageSequence seqID,
   ImageDescriptionHandle newDesc,
   Boolean *equivalent,
   Boolean *canSwitch
);

Parameters

seqID: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
newDesc: A handle to the ImageDescription structure structure that describes the compressed image.
equivalent: A pointer to a Boolean value. If the ImageDescriptionHandle provided in the newDesc parameter is equivalent to the ImageDescription structure currently in use by the image sequence, this value is set to TRUE. If the ImageDescriptionHandle is not equivalent, and therefore a new image sequence must be created to display an image using the new image description, this value is set to FALSE.
canSwitch: Undocumented

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceFlush

Stops a decompression sequence, aborting processing of any queued frames.

OSErr CDSequenceFlush (
   ImageSequence seqID
);

Parameters

seqID: Contains the unique sequence identifier that was returned by DecompressSequenceBegin.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function is used to tell a decompressor component to stop processing of any queued scheduled asynchronous decompression. This is useful when several frames have been queued for decompression in the future and the application needs to suspend playback of the sequence.

For any outstanding frames, your application's completion routine, passed to DecompressSequenceFrameWhen, will be called with an error result of -1, indicating that the frame was cancelled. If any frames are currently being decompressed and cannot be cancelled, CDSequenceFlush waits until the frame has finished decompressing before returning.

Version Notes

Introduced in QuickTime 2.0.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceGetDataSource

Gets a data source for a decompression sequence.

OSErr CDSequenceGetDataSource (
   ImageSequence seqID,
   ImageSequenceDataSource *sourceID,
   OSType sourceType,
   long sourceInputNumber
);

Parameters

seqID: The image sequence that this source is associated with.
sourceID: A pointer to the source reference identifying this source.
sourceType: A four-character code describing how the input will be used. This value is passed by CDSequenceNewDataSource when the source is created.
sourceInputNumber: A value passed by CDSequenceNewDataSource when the source is created.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceInvalidate

Notifies the Image Compression Manager that the destination port for the given image decompression sequence has been invalidated.

OSErr CDSequenceInvalidate (
   ImageSequence seqID,
   RgnHandle invalRgn
);

Parameters

seqID: Contains the unique sequence identifier that was returned by DecompressSequenceBegin.
invalRgn: A handle to the region specifying the invalid portion of the image.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You call this function to force the Image Compression Manager to redraw the screen bits on the next decompression operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceNewDataSource

Creates a new data source.

OSErr CDSequenceNewDataSource (
   ImageSequence seqID,
   ImageSequenceDataSource *sourceID,
   OSType sourceType,
   long sourceInputNumber,
   Handle dataDescription,
   ICMConvertDataFormatUPP transferProc,
   void *refCon
);

Parameters

seqID: The unique sequence identifier that was returned by the DecompressSequenceBegin function.
sourceID: Returns the new data source identifier.
sourceType: A four-character code describing how the input will be used. This code is usually derived from the information returned by the codec. For example, if a mask plane was passed, this field might contain 'mask'.
sourceInputNumber: More than one instance of a given source type may exist. The first occurrence should have a source input number of 1, the second a source input number of 2, and so on.
dataDescription: A handle to a data structure describing the input data. For compressed image data, this is an ImageDescriptionHandle.
transferProc: A routine that allows the application to transform the type of the input data to the kind of data preferred by the codec. The client of the codec passes the source data in the form most convenient for it. If the codec needs the data in another form, it can negotiate with the client or directly with the Image Compression Manager to obtain the required data format.
refCon: A reference constant to be passed to the transfer procedure. Use this parameter to point to a data structure containing any information your function needs.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function returns a sourceID parameter which must be passed to all other functions that reference the source. All data sources are automatically disposed when the sequence they are associated with is disposed.

// CDSequenceNewDataSource coding example

// See "Discovering QuickTime," page 309

    ImageSequenceDataSource     lSrc1 =0;

    // Store a description of the first GWorld in hImageDesc1

    nErr =MakeImageDescriptionForPixMap(GetGWorldPixMap(gWorld1),

                    &hImageDesc1);

    // Create a source from the GWorld description.

    nErr =CDSequenceNewDataSource(gEffectSequenceID,

                                    &lSrc1,

                                    'srcA',

1,

                                    (Handle)hImageDesc1,

                                    NIL,

0);

    // Set the data for source srcA to be the pixMap of gWorld1

    CDSequenceSetSourceData(lSrc1,

                            GetPixBaseAddr(GetGWorldPixMap(gWorld1)),

                            (**hImageDesc1).dataSize);

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceNewMemory

Requests codec-allocated memory.

OSErr CDSequenceNewMemory (
   ImageSequence seqID,
   Ptr *data,
   Size dataSize,
   long dataUse,
   ICMMemoryDisposedUPP memoryGoneProc,
   void *refCon
);

Parameters

seqID: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
data: Returns a pointer to the allocated memory.
dataSize: The requested size of the data buffer.
dataUse: A code (see below) that indicates how the memory is to be used. For example, the memory may be used to store compressed image or mask plane data, or used as an offscreen image buffer. If there is no benefit to storing a particular kind of data in codec memory, the codec should deny the request for the memory allocation. See these constants:
memoryGoneProc: A pointer to a callback function that will be called before disposing of the memory allocated by a codec, as described in ICMMemoryDisposedProc.
refCon: A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your function needs.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Because many hardware decompression boards contain dedicated on-board memory, significant performance gains can be realized if this memory is used to store data before it is decompressed. When memory is allocated, a callback function must be provided, as described in ICMMemoryDisposedProc. The decompressor can dispose of all memory it has allocated at any time, but it calls the callback routine before disposing of the memory. A callback procedure is required because memory on the hardware decompression board may be limited. If the decompressor cannot deallocate memory as required, it is possible that an idle decompressor instance may be holding a large amount of memory, denying those resources to the currently active decompressor instance. When the callback procedure is called, the memory is still available. This allows any pending reads into the block to be canceled before the block is disposed. The decompressor disposing the memory must ensure that it is not disposing a block that it is currently using (that is, a block that contains the currently decompressing frame). To dispose of the memory, use CDSequenceDisposeMemory.

Special Considerations

Decompressor memory must never be disposed at interrupt time.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceSetSourceData

Sets data in a new frame to a specific data source.

OSErr CDSequenceSetSourceData (
   ImageSequenceDataSource sourceID,
   void *data,
   long dataSize
);

Parameters

sourceID: Contains the source identifier of the data source.
data: Points to the data. This pointer must contain a 32-bit clean address.
dataSize: The size of the data buffer.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function is called to set data in a new frame to a specific source. For example, as a new frame of compressed data arrives at a source, CDSequenceSetSourceData will be called.

// CDSequenceSetSourceData coding example

// See "Discovering QuickTime," page 309

    ImageSequenceDataSource     lSrc1 =0;

    // Store a description of the first GWorld in hImageDesc1

    nErr =MakeImageDescriptionForPixMap(GetGWorldPixMap(gWorld1),

                    &hImageDesc1);

    // Create a source from the GWorld description.

    nErr =CDSequenceNewDataSource(gEffectSequenceID,

                                    &lSrc1,

                                    'srcA',

1,

                                    (Handle)hImageDesc1,

                                    NIL,

0);

    // Set the data for source srcA to be the pixMap of gWorld1

    CDSequenceSetSourceData(lSrc1,

                            GetPixBaseAddr(GetGWorldPixMap(gWorld1)),

                            (**hImageDesc1).dataSize);

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceSetSourceDataQueue

Sets a data queue as the source for a decompression sequence.

OSErr CDSequenceSetSourceDataQueue (
   ImageSequenceDataSource sourceID,
   QHdrPtr dataQueue
);

Parameters

sourceID: Contains the source identifier of the data source.
dataQueue: A pointer to a QHdr structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CDSequenceSetTimeBase

Sets a time base for a decompression sequence.

OSErr CDSequenceSetTimeBase (
   ImageSequence seqID,
   void *base
);

Parameters

seqID: A unique sequence identifier that was returned by CompressSequenceBegin.
base: A pointer to the time base for this operation. Your application obtains this time base identifier from NewTimeBase.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When you run a visual effect outside a movie, you must designate a time base that will be used when the effect is run. The following code illustrates this use of CDSequenceSetTimeBase:

// CDSequenceSetTimeBase coding example

// See "Discovering QuickTime," page 310

timeBase =NewTimeBase();

SetTimeBaseRate(timeBase, 0);

CDSequenceSetTimeBase(gEffectSequenceID, timeBase);

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CodecManagerVersion

Determines the version of the installed Image Compression Manager.

OSErr CodecManagerVersion (
   long *version
);

Parameters

version: A pointer to a long integer that is to receive the version information. The Image Compression Manager returns its version number into this location. The version number is a long integer value.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function returns the version information as a long integer value. Use this function to retrieve the version number associated with the Image Compression Manager that is installed on a particular computer.

Special Considerations

The Image Compression Manager provides a number of functions that allow your application to obtain information about the facilities available for image compression or about compressed images. Your application may use some of these functions to select a specific compressor or decompressor for a given operation or to determine how much memory to allocate to receive a decompressed image. In addition, your application may use some of these functions to determine the capabilities of the components that are available on the user's computer system. You can then condition the options your program makes available to the user based on the user's system configuration.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompAdd

Undocumented

void CompAdd (
   wide *src,
   wide *dst
);

Parameters

src: Undocumented
dst: Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompCompare

Undocumented

long CompCompare (
   const wide *a,
   const wide *minusb
);

Parameters

a: Undocumented
minusb: Undocumented

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompDiv

Undocumented

long CompDiv (
   wide *numerator,
   long denominator,
   long *remainder
);

Parameters

numerator: Undocumented
denominator: Undocumented
remainder: Undocumented

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompFixMul

Undocumented

void CompFixMul (
   wide *compSrc,
   Fixed fixSrc,
   wide *compDst
);

Parameters

compSrc: Undocumented
fixSrc: Undocumented
compDst: Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompMul

Undocumented

void CompMul (
   long src1,
   long src2,
   wide *dst
);

Parameters

src1: Undocumented
src2: Undocumented
dst: Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompMulDiv

Undocumented

void CompMulDiv (
   wide *co,
   long mul,
   long divisor
);

Parameters

co: Undocumented
mul: Undocumented
divisor: Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompMulDivTrunc

Undocumented

void CompMulDivTrunc (
   wide *co,
   long mul,
   long divisor,
   long *remainder
);

Parameters

co: Undocumented
mul: Undocumented
divisor: Undocumented
remainder: Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompNeg

Undocumented

void CompNeg (
   wide *dst
);

Parameters

dst: Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompressImage

Compresses a single-frame image that is currently stored as a pixel map structure.

OSErr CompressImage (
   PixMapHandle src,
   const Rect *srcRect,
   CodecQ quality,
   CodecType cType,
   ImageDescriptionHandle desc,
   Ptr data
);

Parameters

src

A handle to the image to be compressed. The image must be stored in a pixel map structure.

srcRect

A pointer to a rectangle defining the portion of the image to compress.

quality

A constant (see below) that defines the desired compressed image quality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

cType

A compressor type; see Codec Identifiers.

desc

data

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function. The Image Compression Manager places the actual size of the compressed image into the dataSize field of the ImageDescription structure structure referred to by the desc parameter. This pointer must contain a 32-bit clean address.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The following code sample illustrates the process of compressing and decompressing a pixel map.

// CompressImage coding example

// See "Discovering QuickTime," page 286

PicHandle GetQTCompressedPict (PixMapHandle hpmImage)

    long                    lMaxCompressedSize =0;

    Handle                  hCompressedData =NIL;

    Ptr                     pCompressedData;

    ImageDescriptionHandle  hImageDesc =NIL;

    OSErr                   nErr;

    PicHandle               hpicPicture =NIL;

    Rect                    rectImage =(**hpmImage).bounds;

    CodecType               dwCodecType =kJPEGCodecType;

    CodecComponent          codec =(CodecComponent)anyCodec;

    CodecQ                  dwSpatialQuality =codecNormalQuality;

    short                   nDepth =0;          // let ICM choose depth

    nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,

                                        dwSpatialQuality,

                                        dwCodecType,

                                        (CompressorComponent)codec,

                                        &lMaxCompressedSize);

    if (nErr !=noErr)

        return NIL;

    hImageDesc =(ImageDescriptionHandle)NewHandle(4);

    hCompressedData =NewHandle(lMaxCompressedSize);

    if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {

        MoveHHi(hCompressedData);

        HLock(hCompressedData);

        pCompressedData =StripAddress(*hCompressedData);

        nErr =CompressImage(hpmImage,

                                        &rectImage,

                                        dwSpatialQuality,

                                        dwCodecType,

                                        hImageDesc,

                                        pCompressedData);

        if (nErr ==noErr) {

            ClipRect(&rectImage);

            hpicPicture =OpenPicture(&rectImage);

            nErr =DecompressImage(pCompressedData,

                                        hImageDesc,

                                        hpmImage,

                                        &rectImage,

                                        &rectImage,

                                        srcCopy,

                                        NIL);

            ClosePicture();

        if (theErr || (GetHandleSize((Handle)hpicPicture) ==

                                            sizeof(Picture))) {

            KillPicture(hpicPicture);

            hpicPicture =NIL;

    if (hImageDesc !=NIL)

        DisposeHandle((Handle)hImageDesc);

    if (hCompressedData !=NIL)

        DisposeHandle(hCompressedData);

    return hpicPicture;

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompressPicture

Compresses a single-frame image stored as a picture structure and places the result in another picture.

OSErr CompressPicture (
   PicHandle srcPicture,
   PicHandle dstPicture,
   CodecQ quality,
   CodecType cType
);

Parameters

srcPicture

A handle to the source image, stored as a picture.

dstPicture

A handle to the destination for the compressed image. The compressor resizes this handle for the result data.

quality

A constant (see below) that defines the desired compressed image quality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

cType

You must set this parameter to a valid compressor identifier; see Codec Identifiers. If the value passed in is 0, or 'raw ', and the source picture is compressed, the destination picture is created as an uncompressed picture and does not require QuickTime for its display.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function compresses only image data. Any other types of data in the picture, such as text, graphics primitives, and previously compressed images, are not modified in any way and are passed through to the destination picture. This function supports parameters governing image quality and compressor type. The compressor infers the other compression parameters from the image data in the source picture.

Special Considerations

If a picture with multiple pixel maps and other graphical objects is passed, the pixel maps will be compressed individually and the other graphic objects will not be affected. This function does not use the graphics port.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompressPictureFile

Compresses a single-frame image stored as a picture file and places the result in another picture file.

OSErr CompressPictureFile (
   short srcRefNum,
   short dstRefNum,
   CodecQ quality,
   CodecType cType
);

Parameters

srcRefNum

A file reference number for the source 'PICT' file.

dstRefNum

A file reference number for the destination 'PICT' file. Note that the compressor overwrites the contents of the file referred to by dstRefNum. You must open this file with write permission. The destination file can be the same as the source file specified by the srcRefNum parameter.

quality

A constant (see below) that defines the desired compressed image quality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

cType

A compressor type. You must set this parameter to a valid compressor type constant; see Codec Identifiers. If the value passed in is 0, or 'raw-', and the source picture is compressed, the destination picture is created as an uncompressed picture and does not require QuickTime to be displayed.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function supports parameters governing image quality and compressor type. The compressor infers the other compression parameters from the image data in the source picture file.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompressSequenceBegin

Signals the beginning of the process of compressing a sequence of frames.

OSErr CompressSequenceBegin (
   ImageSequence *seqID,
   PixMapHandle src,
   PixMapHandle prev,
   const Rect *srcRect,
   const Rect *prevRect,
   short colorDepth,
   CodecType cType,
   CompressorComponent codec,
   CodecQ spatialQuality,
   CodecQ temporalQuality,
   long keyFrameRate,
   CTabHandle ctable,
   CodecFlags flags,
   ImageDescriptionHandle desc
);

Parameters

seqID

A pointer to a field to receive the unique identifier for this sequence. You must supply this identifier to all subsequent Image Compression Manager functions that relate to this sequence.

src

A handle to a pixel map that will contain the image to be compressed. The image must be stored in a pixel map structure.

prev

A handle to a pixel map that will contain a previous image. The compressor uses this buffer to store a previous image against which the current image (stored in the pixel map referred to by the src parameter) is compared when performing temporal compression. This pixel map must be created at the same depth and with the same color table as the source image. The compressor manages the contents of this pixel map based upon several considerations, such as the key frame rate and the degree of difference between compared images. If you want the compressor to allocate this pixel map or if you do not want to perform temporal compression (that is, you have set the value of the temporalQuality parameter to 0), set this parameter to NIL.

srcRect

A pointer to a rectangle defining the portion of the image to compress. The compressor applies this rectangle to the image stored in the buffer referred to by the src parameter.

prevRect

A pointer to a rectangle defining the portion of the previous image to use for temporal compression. The compressor uses this portion of the previous image as the basis of comparison with the current image. The compressor ignores this parameter if you have not provided a buffer for previous images. This rectangle must be the same size as the source rectangle, which is specified with the srcRect parameter.

colorDepth

The depth at which the sequence is likely to be viewed. Compressors may use this as an indication of the color or grayscale resolution of the compressed images. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function.

cType

You must set this parameter to a valid compressor type constant. See Codec Identifiers.

codec

Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). Specifying a component instance may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation. See these constants:

spatialQuality

A pointer to a field containing a constant (see below) that defines the desired compressed image quality. You can change the value of this parameter for an active sequence by calling SetCSequenceQuality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

temporalQuality

A pointer to a field containing a constant (see below) that defines the desired temporal quality. This parameter governs the level of compression you desire with respect to information between successive frames in the sequence. Set to 0 if you do not want temporal compression. You can change the value of this parameter for an active sequence by calling SetCSequenceQuality.

keyFrameRate

Specifies the maximum number of frames allowed between key frames. The compressor determines the optimum placement for key frames based upon the amount of redundancy between adjacent images in the sequence. Consequently, the compressor may insert key frames more frequently than you have requested. However, the compressor never places fewer key frames than is indicated by the setting of the keyFrameRate parameter. The compressor ignores this parameter if you have not requested temporal compression (that is, you have set the temporalQuality parameter to 0). If you pass in 0 in this parameter, this indicates that there are no key frames in the sequence. If you pass in any other number, it specifies the number of non-key frames between key frames. Set this parameter to 1 to specify all key frames, to 2 to specify every other frame as a key frame, to 3 to specify every third frame as a key frame, and so forth. Your application may change the key frame rate for an active sequence by calling SetCSequenceKeyFrameRate.

ctable

A handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the ctable parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to NIL, the compressor uses the color lookup table from the source pixel map.

flags

Contains flags (see below) that provide further control information. You must set either codecFlagUpdatePrevious or codecFlagUpdatePreviousComp to 1. Set unused flags to 0. See these constants:

codecFlagUpdatePrevious
codecFlagUpdatePreviousComp
codecFlagWasCompressed

desc

A handle that is to receive a formatted ImageDescription structure. The Image Compression Manager resizes this handle for the returned image description structure. Your application should store this image description with the compressed sequence. During the compression operation, the Image Compression Manager and the compressor component update the contents of this image description. Consequently, you should not store the image description until the sequence has been completely processed.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The Image Compression Manager prepares for a sequence-compression operation by reserving appropriate system resources. Hence you must call CompressSequenceBegin before you call CompressSequenceFrame.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompressSequenceFrame

Compresses one of a sequence of frames.

OSErr CompressSequenceFrame (
   ImageSequence seqID,
   PixMapHandle src,
   const Rect *srcRect,
   CodecFlags flags,
   Ptr data,
   long *dataSize,
   UInt8 *similarity,
   ICMCompletionProcRecordPtr asyncCompletionProc
);

Parameters

seqID

Unique sequence identifier that was returned by CompressSequenceBegin.

src

A handle to a pixel map that contains the image to be compressed. The image must be stored in a pixel map structure.

srcRect

A pointer to a rectangle defining the portion of the image to compress. The compressor applies this rectangle to the image stored in the buffer referred to by the src parameter.

flags

Specifies flags (see below) that provide further control information. You must set either codecFlagUpdatePrevious or codecFlagUpdatePreviousComp to 1. Set unused flags to 0. See these constants:

codecFlagUpdatePrevious
codecFlagWasCompressed
codecFlagUpdatePreviousComp
codecFlagForceKeyFrame
codecFlagLiveGrab

data

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function. The Image Compression Manager places the actual size of the compressed image into the field referred to by the dataSize parameter. This pointer must contain a 32-bit clean address.

dataSize

A pointer to a field that is to receive the size, in bytes, of the compressed image.

similarity

A pointer to a field that is to receive a similarity value. The CompressSequenceFrame function returns a value that indicates the similarity of the current frame to the previous frame. A value of 0 indicates that the current frame is a key frame in the sequence. A value of 255 indicates that the current frame is identical to the previous frame. Values from 1 through 254 indicate relative similarity, ranging from very different (1) to very similar (254).

asyncCompletionProc

Points to an ICMCompletionProc callback. The compressor calls your completion function when an asynchronous compression operation is complete. You can cause the compression to be performed asynchronously by specifying a completion function if the compressor supports asynchronous compression.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Special Considerations

If you specify asynchronous operation, you must not read the compressed data until the compressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to NIL to specify synchronous compression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the compressor does not call your completion function. If the asyncCompletionProc parameter is not NIL, the following conditions are in effect: the pixels in the source image must stay valid until the completion function is called with its codecCompletionSource flag, and the resulting compressed data is not valid until it is called with its codecCompletionDest flag set.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompShift

Undocumented

void CompShift (
   wide *src,
   short shift
);

Parameters

src: Undocumented
shift: Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompSquareRoot

Undocumented

unsigned long CompSquareRoot (
   const wide *src
);

Parameters

src: Undocumented

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CompSub

Undocumented

void CompSub (
   wide *src,
   wide *dst
);

Parameters

src: Undocumented
dst: Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ConcatMatrix

Concatenates two matrices, combining the transformations described by both matrices into a single matrix.

void ConcatMatrix (
   const MatrixRecord *a,
   MatrixRecord *b
);

Parameters

a: A pointer to the source matrix.
b: A pointer to the destination matrix. The ConcatMatrix function performs a matrix multiplication operation on the two matrices and leaves the result in the matrix specified by this parameter.

Discussion

This is a matrix multiplication operation, as a result of which [B] =[B] x [A]. Note that matrix multiplication is not commutative.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ConvertImage

Converts the format of a compressed image.

OSErr ConvertImage (
   ImageDescriptionHandle srcDD,
   Ptr srcData,
   short colorDepth,
   CTabHandle ctable,
   CodecQ accuracy,
   CodecQ quality,
   CodecType cType,
   CodecComponent codec,
   ImageDescriptionHandle dstDD,
   Ptr dstData
);

Parameters

srcDD

A handle to the ImageDescription structure that describes the compressed image.

srcData

Points to the compressed image data. This pointer must contain a 32-bit clean address.

colorDepth

The depth at which the recompressed image is likely to be viewed. Decompressors may use this as an indication of the color or grayscale resolution of the compressed image. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function.

ctable

accuracy

A constant (see below) that defines the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. For a good display of still images, you should specify at least codecHighQuality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

quality

A constant (see below) that defines the desired compressed image quality.

cType

A compressor type; see Codec Identifiers.

codec

Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special constant (see below). Specifying a component instance may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation. See these constants:

dstDD

A handle that is to receive a formatted ImageDescription structure. The Image Compression Manager resizes this handle for the returned ImageDescription structure. Your application should store this image description with the compressed image data.

dstData

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by GetMaxCompressionSize. The Image Compression Manager places the actual size of the compressed image into the dataSize field of the image description referred to by the dstDD parameter. This pointer must contain a 32-bit-clean address.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The action of this function is essentially equivalent to decompressing and recompressing the image. During the decompression operation, the decompressor uses the srcDD, srcData, and accuracy parameters. During the subsequent compression operation, the compressor uses the colorDepth, ctable, cType, codec, quality, dstDD, and dstData parameters.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CopyMatrix

Copies the contents of one matrix into another matrix.

void CopyMatrix (
   const MatrixRecord *m1,
   MatrixRecord *m2
);

Parameters

m1: The source matrix for the copy operation.
m2: A pointer to the destination matrix for the copy operation. CopyMatrix copies the values from the matrix specified by the m1 parameter into this matrix.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CountImageDescriptionExtensionType

Counts the number of extensions of a given type in an ImageDescriptionHandle.

OSErr CountImageDescriptionExtensionType (
   ImageDescriptionHandle desc,
   long idType,
   long *count
);

Parameters

desc: A handle to the ImageDescription structure with the extensions to be counted.
idType: Indicates the type of extension to be counted in the specified ImageDescription structure. Set the value of this parameter to 0 to match any extension, and return a count of all of the extensions.
count: A pointer to an integer that indicates how many extensions of the given type are in the given ImageDescription structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When used with GetNextImageDescriptionExtensionType, this function allows the application to determine the total set of extensions present in the ImageDescription structure designated by desc.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DecompressImage

Decompresses a single-frame image into a pixel map structure.

OSErr DecompressImage (
   Ptr data,
   ImageDescriptionHandle desc,
   PixMapHandle dst,
   const Rect *srcRect,
   const Rect *dstRect,
   short mode,
   RgnHandle mask
);

Parameters

data: Points to the compressed image data. This pointer must contain a 32-bit clean address.
desc: A handle to the ImageDescription structure that describes the compressed image.
dst: A handle to the pixel map where the decompressed image is to be displayed. Set the current graphics port to the port that contains this pixel map.
srcRect: A pointer 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 (0,0) and ((**desc).width,(**desc).height). If you want to decompress the entire source image, set this parameter to NIL. If the parameter is NIL, the rectangle is set to the rectangle structure of the ImageDescription structure.
dstRect: A pointer to the rectangle into which the decompressed image is to be loaded. The compressor scales the source image to fit into this destination rectangle.
mode: The transfer mode for the operation, as listed in Graphics Transfer Modes.
mask: A handle to a clipping region in the destination coordinate system. If specified, the compressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Note that DecompressImage is invoked through the StdPix function. The following code sample illustrates the process of compressing and decompressing a pixel map.

// DecompressImage coding example

// See "Discovering QuickTime," page 286

PicHandle GetQTCompressedPict (PixMapHandle hpmImage)

    long                    lMaxCompressedSize =0;

    Handle                  hCompressedData =NIL;

    Ptr                     pCompressedData;

    ImageDescriptionHandle  hImageDesc =NIL;

    OSErr                   nErr;

    PicHandle               hpicPicture =NIL;

    Rect                    rectImage =(**hpmImage).bounds;

    CodecType               dwCodecType =kJPEGCodecType;

    CodecComponent          codec =(CodecComponent)anyCodec;

    CodecQ                  dwSpatialQuality =codecNormalQuality;

    short                   nDepth =0;          // let ICM choose depth

    nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,

                                        dwSpatialQuality,

                                        dwCodecType,

                                        (CompressorComponent)codec,

                                        &lMaxCompressedSize);

    if (nErr !=noErr)

        return NIL;

    hImageDesc =(ImageDescriptionHandle)NewHandle(4);

    hCompressedData =NewHandle(lMaxCompressedSize);

    if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {

        MoveHHi(hCompressedData);

        HLock(hCompressedData);

        pCompressedData =StripAddress(*hCompressedData);

        nErr =CompressImage(hpmImage,

                                        &rectImage,

                                        dwSpatialQuality,

                                        dwCodecType,

                                        hImageDesc,

                                        pCompressedData);

        if (nErr ==noErr) {

            ClipRect(&rectImage);

            hpicPicture =OpenPicture(&rectImage);

            nErr =DecompressImage(pCompressedData,

                                        hImageDesc,

                                        hpmImage,

                                        &rectImage,

                                        &rectImage,

                                        srcCopy,

                                        NIL);

            ClosePicture();

        if (theErr || (GetHandleSize((Handle)hpicPicture) ==

                                            sizeof(Picture))) {

            KillPicture(hpicPicture);

            hpicPicture =NIL;

    if (hImageDesc !=NIL)

        DisposeHandle((Handle)hImageDesc);

    if (hCompressedData !=NIL)

        DisposeHandle(hCompressedData);

    return hpicPicture;

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DecompressSequenceBegin

Obsolete. See DecompressSequenceBeginS.

OSErr DecompressSequenceBegin (
   ImageSequence *seqID,
   ImageDescriptionHandle desc,
   CGrafPtr port,
   GDHandle gdh,
   const Rect *srcRect,
   MatrixRecordPtr matrix,
   short mode,
   RgnHandle mask,
   CodecFlags flags,
   CodecQ accuracy,
   DecompressorComponent codec
);

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DecompressSequenceBeginS

Sends a sample image to a decompressor.

OSErr DecompressSequenceBeginS (
   ImageSequence *seqID,
   ImageDescriptionHandle desc,
   Ptr data,
   long dataSize,
   CGrafPtr port,
   GDHandle gdh,
   const Rect *srcRect,
   MatrixRecordPtr matrix,
   short mode,
   RgnHandle mask,
   CodecFlags flags,
   CodecQ accuracy,
   DecompressorComponent codec
);

Parameters

seqID

A pointer to a field to receive the unique identifier for the sequence you are creating. You should use this identifier for subsequent calls relating to this decompression sequence.

desc

A handle to the ImageDescription structure that describes the compressed image.

data

Points to the compressed image data. This pointer must contain a 32-bit clean address. Ideally, you should pass a pointer to the first frame of the compressed image data, which lets the Image Compression Manager do a better job of preflighting the decompression sequence. If the image data is not available at the time of this call, you can pass NIL for this parameter and 0 for dataSize. If you pass NIL here, then your first call to DecompressSequenceFrameWhen may require more setup time.

dataSize

The size of the data buffer, or 0 if you passed NIL in the data parameter.

port

Points to the CGrafPort structure for the destination image.

gdh

A handle to the GDevice structure for the destination image. You can pass NIL if the GDevice is implicit in the port selection (for example, if it is an offscreen graphics world).

srcRect

A pointer to a Rect structure that defines the portions of the image to decompress. Pass NIL if you want to decompress the entire source image. You can call SetDSequenceSrcRect to change the source rectangle for an active decompression sequence.

matrix

Points to a MatrixRecord structure that specifies how to transform the image during decompression. Pass NIL to use the identity matrix. Your application can change the matrix for an active sequence by calling SetDSequenceMatrix.

mode

The transfer mode for the operation. See Graphics Transfer Modes. Your application can change the transfer mode for an active sequence by calling SetDSequenceTransferMode.

mask

A handle to a clipping region in the destination coordinate system. If specified, the compressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to NIL. Your application can change the clipping mask for an active sequence by calling SetDSequenceMask.

flags

Buffer allocation flags (see below). See these constants:

codecFlagUseScreenBuffer
codecFlagUseImageBuffer

accuracy

A constant (see below) that defines the desired compression accuracy. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

codec

A decompressor identifier. Specify a particular decompressor by setting this parameter to its identifier. Alternatively, you may use a special identifier (see below). Specifying a component instance may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation. See these constants:

Return Value

See Error Codes. Returns codecWouldOffscreenErr if codecFlagDontUseImageBuffer is set and the codec requires an offscreen buffer to decompress to the destination port. Returns noErr if there is no error.

Discussion

This function lets you pass a compressed sample so a codec can perform preflighting before the first DecompressSequenceFrameWhen call. To decompress a series of images, call it once to preflight the decompressor, make calls to DecompressSequenceFrameWhen to decompress each image in the sequence, then call CDSequenceEnd when you are done.

Version Notes

Introduced in QuickTime 1.6.1.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DecompressSequenceFrame

Obsolete. See DecompressSequenceFrameS.

OSErr DecompressSequenceFrame (
   ImageSequence seqID,
   Ptr data,
   CodecFlags inFlags,
   CodecFlags *outFlags,
   ICMCompletionProcRecordPtr asyncCompletionProc
);

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DecompressSequenceFrameS

Queues a frame for decompression and specifies the size of the compressed data; new applications should use DecompressSequenceFrameWhen.

OSErr DecompressSequenceFrameS (
   ImageSequence seqID,
   Ptr data,
   long dataSize,
   CodecFlags inFlags,
   CodecFlags *outFlags,
   ICMCompletionProcRecordPtr asyncCompletionProc
);

Parameters

seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

data

Points to the compressed image data. This pointer must contain a 32-bit clean address.

dataSize

The size of the data buffer.

inFlags

Contains flags (see below) that provide further control information. See these constants:

codecFlagNoScreenUpdate
codecFlagDontOffscreen
codecFlagOnlyScreenUpdate

outFlags

Contains status flags (see below). The decompressor updates these flags at the end of the decompression operation. See these constants:

codecFlagUsedNewImageBuffer
codecFlagUsedImageBuffer
codecFlagDontUseNewImageBuffer
codecFlagInterlaceUpdate
codecFlagCatchUpDiff

asyncCompletionProc

Points to an ICMCompletionProcRecord structure. The compressor calls your completion function when an asynchronous decompression operation is complete. You can cause the decompression to be performed asynchronously by specifying a completion function. If you specify asynchronous operation, you must not read the decompressed image until the decompressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to NIL to specify synchronous decompression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the decompressor does not call your completion function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function accepts the same parameters as the DecompressSequenceFrame function, with the addition of the dataSize parameter.

Special Considerations

New applications should use DecompressSequenceFrameWhen.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DecompressSequenceFrameWhen

Queues a frame for decompression and specifies the time at which decompression will begin.

OSErr DecompressSequenceFrameWhen (
   ImageSequence seqID,
   Ptr data,
   long dataSize,
   CodecFlags inFlags,
   CodecFlags *outFlags,
   ICMCompletionProcRecordPtr asyncCompletionProc,
   const ICMFrameTimeRecord *frameTime
);

Parameters

seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

data

Points to the compressed image data. This pointer must contain a 32-bit clean address.

dataSize

The size of the data buffer.

inFlags

Contains flags (see below) that provide further control information. See these constants:

codecFlagNoScreenUpdate
codecFlagDontOffscreen
codecFlagOnlyScreenUpdate

outFlags

Contains status flags (see below). The decompressor updates these flags at the end of the decompression operation. See these constants:

codecFlagUsedNewImageBuffer
codecFlagUsedImageBuffer
codecFlagDontUseNewImageBuffer
codecFlagInterlaceUpdate
codecFlagCatchUpDiff

asyncCompletionProc

frameTime

Points to an ICMFrameTimeRecord structure, which contains the frame's time information, including the time at which the frame should be displayed, its duration, and the movie's playback rate. This parameter can be NIL, in which case the decompression operation will happen immediately.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The following code snippet shows this function being used to execute one frame of a visual effect.

// DecompressSequenceFrameWhen coding example

// See "Discovering QuickTime," page 310

// Decompress a single step of the effect sequence.

OSErr RunEffect(TimeValue lTime, int nNumberOfSteps)

    OSErr               nErr =noErr;

    ICMFrameTimeRecord  ftr;

    // Set the timebase time to the step of the sequence to be rendered

    SetTimeBaseValue(timeBase, lTime, nNumberOfSteps);

    ftr.value.lo            =lTime;

    ftr.value.hi            =0;

    ftr.scale               =nNumberOfSteps;

    ftr.base                =0;

    ftr.duration            =nNumberOfSteps;

    ftr.rate                =0;

    ftr.recordSize          =sizeof(ftr);

    ftr.frameNumber         =1;

    ftr.flags               =icmFrameTimeHasVirtualStartTimeAndDuration;

    ftr.virtualStartTime.lo     =0;

    ftr.virtualStartTime.hi     =0;

    ftr.virtualDuration         =nNumberOfSteps;

    HLock(hEffectDesc);

    DecompressSequenceFrameWhen(gEffectSequenceID,

                                StripAddress(*hEffectDesc),

                                GetHandleSize(hEffectDesc),

0,

0,

                                NIL,

                                &ftr);

    HUnlock(hEffectDesc);

Special Considerations

If the current decompressor component does not support scheduled asynchronous decompression, the Image Compression Manager returns an error code of codecCantWhenErr. In this case, the application will need to reissue the request with the frameTime parameter set to NIL. If the decompressor cannot service your request at a particular time (for example, if its queue is full), the Image Compression Manager returns an error code of codecCantQueueErr. The best way to determine whether a decompressor component supports this function is to call the function and test the result code. A decompressor's ability to honor the request may change based on screen depth, clipping settings, and so on.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DisposeCodecNameList

Disposes of the compressor name list structure you obtained by calling GetCodecNameList.

OSErr DisposeCodecNameList (
   CodecNameSpecListPtr list
);

Parameters

list: Points to the compressor name list to be disposed of. You obtain the compressor list by calling GetCodecNameList.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DragAlignedGrayRgn

Drags a specified gray region along an optimal alignment grid.

long DragAlignedGrayRgn (
   RgnHandle theRgn,
   Point startPt,
   Rect *boundsRect,
   Rect *slopRect,
   short axis,
   UniversalProcPtr actionProc,
   Rect *alignmentRect,
   ICMAlignmentProcRecordPtr alignmentProc
);

Parameters

theRgn: A handle to the specified region for this operation. When the user holds down the mouse button, DragAlignedGrayRgn pulls a gray outline of the region around following the movement of the mouse until the mouse button is released.
startPt: The point where the mouse button was originally pressed in the local coordinates of the current graphics port.
boundsRect: A pointer to the boundary rectangle of the current graphics port. The offset point follows the mouse location except that DragAlignedGrayRgn never moves the offset point outside this rectangle. This limits the travel of the region's outline, not the movements of the mouse.
slopRect: A pointer to the slop rectangle that completely encloses the boundary rectangle so that the user is allowed some flexibility in moving the mouse.
axis: Allows you to constrain the region's motion to only one axis (see constants below). See these constants:
actionProc: Points to a function that defines some action to be performed repeatedly as long as the user holds down the mouse button. The function should have no parameters. If the actionProc parameter is NIL, DragAlignedGrayRgn simply retains control until the mouse button is released.
alignmentRect: A pointer to a rectangle within the bounds of the region specified in the parameter theRgn. Pass NIL to align using the bounds of the parameter theRgn.
alignmentProc: A pointer to your alignment behavior function; see ICMAlignmentProc. Pass NIL to use the standard behavior.

Return Value

The difference between the point where the mouse button was pressed and the offset point; that is, the point in the region whose horizontal and vertical offsets from the upper-left corner of the region's enclosing rectangle are the same as the offsets of the starting point when the user pressed the mouse button. The vertical difference between the starting point and the offset point is stored in the high-order word of the return value and the horizontal difference is stored in the low-order word.

Discussion

This function limits the movement of the region defined by theRgn according to the constraints set by the boundsRect and slopRect parameters. While the cursor is inside the boundsRect rectangle, the region's outline follows it normally. If the mouse button is released while the cursor is within this rectangle, the return value reflects the simple distance that the cursor moved in each dimension. When the cursor moves outside the boundsRect rectangle, the offset point stops at the edge of the boundsRect rectangle. If the mouse button is released while the cursor is outside the boundsRect rectangle but inside the slopRect rectangle, the return value reflects only the difference between the starting point and the offset point, regardless of how far outside of the boundsRect rectangle the cursor may have moved. (Note that part of the region can fall outside the boundsRect rectangle, but not the offset point.) When the cursor moves outside the slopRect rectangle, the region's outline disappears from the screen. DragAlignedGrayRgn continues to track the cursor, however, and if the cursor moves back into the slopRect rectangle, the outline reappears. If the mouse button is released while the cursor is anywhere inside the slopRect rectangle, the window is redrawn in its new location, calculated from the value returned by DragAlignedGrayRgn If the mouse button is released while the cursor is outside the slopRect rectangle, both words of the return value are set to 0x8000 and the window does not move from its original location.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DragAlignedWindow

Drags the specified window along an optimal alignment grid.

void DragAlignedWindow (
   WindowRef wp,
   Point startPt,
   Rect *boundsRect,
   Rect *alignmentRect,
   ICMAlignmentProcRecordPtr alignmentProc
);

Parameters

wp: A window pointer to the window to be dragged.
startPt: A point that is equal to the point where the mouse button was pressed (in global coordinates, as stored in the where field of the event structure). DragAlignedWindow pulls a gray outline of the window around the screen, following the movements of the mouse until the button is released.
boundsRect: Points to the boundary rectangle in global coordinates. If the mouse button is released when the mouse position is outside the limits of the boundary rectangle, DragAlignedWindow returns without moving the window or making it the active window. For a document window, the boundary rectangle typically is four pixels in from the menu bar and from the other edges of the screen, to ensure that there won't be less than a four-pixel-square area of the title bar visible on the screen.
alignmentRect: Points to a rectangle in window coordinates that allows you to align the window to a rectangle within the window. Set this parameter to NIL to align using the bounds of the window.
alignmentProc: A pointer to your alignment behavior function; see ICMAlignmentProc. Pass NIL to use the standard behavior.

Discussion

The following code sample illustrates the use of DragAlignedWindow:

// DragAlignedWindow coding example

// See "Discovering QuickTime," page 265

Boolean IsQuickTimeInstalled (void)

    OSErr       nErr;

    long        lResult;

    nErr =Gestalt(gestaltQuickTime, &lResult);

    return (nErr ==noErr);

void MyInitialize (void)

    InitGraf(&qd.thePort);

    InitFonts();

    InitWindows();

    InitMenus();

    TEInit();

    InitDialogs(NIL);

    MaxApplZone();

    EnterMovies();

WindowRef MakeMyWindow (void)

    WindowRef   pMacWnd;

    Rect        rectWnd ={0, 0, 120, 160};

    Rect        rectBest;

    // figure out the best monitor for the window

    GetBestDeviceRect(NIL, &rectBest);

    // put the window in the top left corner of that monitor

    OffsetRect(&rectWnd, rectBest.left + 10, rectBest.top + 50);

    // create the window

    pMacWnd =NewCWindow(NIL, &rectWnd, "\pGrabber",

                            TRUE, noGrowDocProc, (WindowRef)-1,

                            TRUE, 0);

    // set the port to the new window

    SetPort(pMacWnd);

    return pMacWnd;

main (void)

    WindowRef           pMacWnd;

    SeqGrabComponent    seqGrab;

    SGChannel           sgchanVideo, sgchanSound;

    Boolean             bDone =FALSE;

    OSErr               nErr;

    MyInitialize();

    pMacWnd =MakeMyWindow();

    seqGrab =MakeMySequenceGrabber(pMacWnd);

    if (seqGrab ==NIL)

        return;

    MakeMyGrabChannels(seqGrab, &sgchanVideo, &sgchanSound,

                         &pMacWnd->

portRect, FALSE);

    nErr =SGStartPreview(seqGrab);

    while (!bDone) {

        ICMAlignmentProcRecord  apr;

        short                   nPart;

        WindowRef               pWhichWnd;

        EventRecord             er;

        GetNextEvent(everyEvent, &er);

        switch (er.what) {

            case nullEvent:     // give the sequence grabber time

                nErr =SGIdle(seqGrab);

                if (nErr !=noErr)

                    bDone =TRUE;

                break;

            case updateEvt:

                if (er.message ==(long)pMacWnd) {

                    // inform the sequence grabber of the update

                    SGUpdate(seqGrab,((WindowPeek)

                                     pMacWnd)->

updateRgn);

                    // and swallow the update event

                    BeginUpdate(pMacWnd);

                    EndUpdate(pMacWnd);

                break;

            case mouseDown:

                nPart =FindWindow(er.where, &pWhichWnd);

                if (pWhichWnd !=pMacWnd)

                    break;

                switch (nPart) {

                    case inContent:

                        // pause until mouse button is released

                        SGPause(seqGrab, TRUE);

                        while (StillDown())

                            SGPause(seqGrab, FALSE);

                            break;

                    case inGoAway:

                        bDone =TrackGoAway(pMacWnd, er.where);

                        break;

                    case inDrag:

                        // pause when dragging window so video

                        // doesn't draw in the wrong place

                        SGPause(seqGrab, TRUE);

                        SGGetAlignmentProc(seqGrab, &apr);

                        DragAlignedWindow(pMacWnd,

                                            er.where,

                                            &screenBits.bounds,

                                            NIL, &alignProc);

                        SGPause(seqGrab, FALSE);

                        break;

                break;

    // clean up

    SGStop(seqGrab);

    CloseComponent(seqGrab);

    DisposeWindow(pMacWnd);

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DrawPictureFile

Draws an image from a specified picture file in the current graphics port.

OSErr DrawPictureFile (
   short refNum,
   const Rect *frame,
   ICMProgressProcRecordPtr progressProc
);

Parameters

refNum: A file reference number for the source PICT file.
frame: A pointer to the rectangle into which the image is to be loaded. The compressor scales the source image to fit into this destination rectangle.
progressProc: Points to an ICMProgressProc callback. During the operation, the draw function may occasionally call a function you provide in order to report its progress; see ICMProgressProcRecord. If you have not provided a progress function, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function draws the picture that it finds in the picture file specified by the refNum parameter within the rectangle specified by the frame parameter. The Image Compression Manager performs any spooling that may be necessary when reading the picture file. Specify a clipping region appropriate for your picture before drawing it. If the clipping region is very large (as it is when a graphics port is initialized) and you want to scale the picture, the clipping region can become invalid when DrawPictureFile scales the clipping region, in which case your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when DrawPictureFile draws it. Setting a clipping region equal to the port rectangle of the current graphics port always sets a valid clipping region.

Special Considerations

When it scales fonts, DrawPictureFile changes the size of the font instead of scaling the bits. However, the widths used by bitmap fonts are not always linear. For example, the 12-point width isn't exactly 1/2 of the 24-point width. This can cause lines of text to become slightly longer or shorter as the picture is scaled. The easiest way to avoid such problems is to specify a destination rectangle that is the same size as the bounding rectangle for the picture.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DrawTrimmedPicture

Draws an image that is stored as a picture into the current graphics port and trims that image to fit a specified region.

OSErr DrawTrimmedPicture (
   PicHandle srcPicture,
   const Rect *frame,
   RgnHandle trimMask,
   short doDither,
   ICMProgressProcRecordPtr progressProc
);

Parameters

srcPicture

A handle to the source image, stored as a picture.

frame

A pointer to the rectangle into which the decompressed image is to be loaded.

trimMask

A handle to a clipping region in the destination coordinate system. The decompressor applies this mask to the destination image and ignores any image data that fall outside the specified region. Set this parameter to NIL if you do not want to clip the source image.

doDither

Indicates whether to dither the image. Use this parameter if you want the image to be dithered when it is displayed on a lower-resolution screen (see below). See these constants:

defaultDither
forceDither
suppressDither

progressProc

A pointer to an ICMProgressProc callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided a progress function, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function works with compressed image data; the source data stays compressed. The function trims the image to fit the specified clipping region. Note that if you just use a clip while making a picture, the data (though not visible) is still stored in the picture.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DrawTrimmedPictureFile

Draws an image that is stored as a picture file into the current graphics port and trims that image to fit a specified region.

OSErr DrawTrimmedPictureFile (
   short srcRefnum,
   const Rect *frame,
   RgnHandle trimMask,
   short doDither,
   ICMProgressProcRecordPtr progressProc
);

Parameters

srcRefnum

A file reference number for the source PICT file.

frame

A pointer to the rectangle into which the decompressed image is to be loaded.

trimMask

doDither

Indicates whether to dither the image. Use this parameter if you want the image to be dithered when it is displayed on a lower-resolution screen (see below). See these constants:

defaultDither
forceDither
suppressDither

progressProc

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You can use this function to save part of a picture, since the image data that is not within the trim region is ignored and is not included in the destination picture file. All the remaining objects in the resulting object are clipped.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

EqualMatrix

Compares two matrices and returns a result that indicates whether the matrices are equal.

Boolean EqualMatrix (
   const MatrixRecord *m1,
   const MatrixRecord *m2
);

Parameters

m1: A pointer to one matrix for the compare operation.
m2: A pointer to the other matrix for the compare operation.

Return Value

TRUE if the matrices are equal, FALSE otherwise.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FCompressImage

Compresses a single-frame image that is currently stored as a pixel map structure, with added control over the compression process.

OSErr FCompressImage (
   PixMapHandle src,
   const Rect *srcRect,
   short colorDepth,
   CodecQ quality,
   CodecType cType,
   CompressorComponent codec,
   CTabHandle ctable,
   CodecFlags flags,
   long bufferSize,
   ICMFlushProcRecordPtr flushProc,
   ICMProgressProcRecordPtr progressProc,
   ImageDescriptionHandle desc,
   Ptr data
);

Parameters

src

A handle to the image to be compressed. The image must be stored in a pixel map structure.

srcRect

A pointer to a rectangle defining the portion of the image to compress.

colorDepth

The depth at which the image is likely to be viewed. Compressors may use this as an indication of the color or grayscale resolution of the compressed image. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function.

quality

A constant (see below) that defines the desired compressed image quality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

cType

A compressor type. You must set this parameter to a valid compressor type constant.

codec

A compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). Specifying a component instance may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation. See these constants:

ctable

flags

Contains a flag (see below) that indicates whether or not the image was previously compressed. See these constants:

codecFlagWasCompressed

bufferSize

The size of the buffer to be used by the data-unloading function specified by the flushProc parameter. If you have not specified a data-unloading function, set this parameter to 0.

flushProc

Points to an ICMDataProc data-unloading callback. If there is not enough memory to store the compressed image, the compressor calls a function you provide that unloads some of the compressed data. If you have not provided a data-unloading callback, set this parameter to NIL. In this case, the compressor writes the entire compressed image into the memory location specified by the data parameter.

progressProc

Points to an ICMProgressProc progress callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided a progress callback, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

desc

data

Points to a location to receive the compressed image data. It is your program's responsibility to make sure that this location can receive at least as much data as indicated by the GetMaxCompressionSize function. If there is not sufficient memory to store the compressed image, you may choose to write the compressed data to mass storage during the compression operation. Use the flushProc parameter to identify your data-unloading function to the compressor. This pointer must contain a 32-bit clean address. The Image Compression Manager places the actual size of the compressed image into the dataSize field of the ImageDescription structure referenced by the desc parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function acts like CompressImage, but gives your application additional control over the parameters that guide the compression operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FCompressPicture

Compresses a single-frame image stored as a picture structure and places the result in another picture, with added control over the compression process.

OSErr FCompressPicture (
   PicHandle srcPicture,
   PicHandle dstPicture,
   short colorDepth,
   CTabHandle ctable,
   CodecQ quality,
   short doDither,
   short compressAgain,
   ICMProgressProcRecordPtr progressProc,
   CodecType cType,
   CompressorComponent codec
);

Parameters

srcPicture

A handle to the source image, stored as a picture.

dstPicture

A handle to the destination for the compressed image. The compressor resizes this handle for the result data.

colorDepth

The depth at which the image is to be compressed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor information structure returned by the GetCodecInfo function.

ctable

quality

A constant that defines the desired compressed image quality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

doDither

A constant (see below) that indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. See these constants:

defaultDither
forceDither
suppressDither

compressAgain

Indicates whether to recompress compressed image data in the picture. Use this parameter to control whether any compressed image data that is in the source picture should be decompressed and then recompressed using the current parameters. Set the value of this parameter to TRUE to recompress such data. Set the value of the parameter to FALSE to leave the data as it is. Note that recompressing the data may have undesirable side effects, including image quality degradation.

progressProc

Points to an ICMProgressProc callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided a progress callback, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

cType

A compressor type. You must set this parameter to a valid compressor type constant; see Codec Identifiers. If the value passed in is 0, or 'raw ', the resulting picture is not compressed and does not require QuickTime to be displayed.

codec

A compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). See these constants:

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

If a picture with multiple pixel maps and other graphical objects is passed, the pixel maps will be compressed individually and the other graphic objects will not be affected. FCompressPicture compresses only image data. Any other types of data in the picture, such as text, graphics primitives, and previously compressed images, are not modified in any way and are passed through to the destination picture. This function supports parameters governing image quality, compressor type, image depth, custom color tables, and dithering.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FCompressPictureFile

Compresses a single-frame image stored as a picture file and places the result in another picture file, with added control over the compression process.

OSErr FCompressPictureFile (
   short srcRefNum,
   short dstRefNum,
   short colorDepth,
   CTabHandle ctable,
   CodecQ quality,
   short doDither,
   short compressAgain,
   ICMProgressProcRecordPtr progressProc,
   CodecType cType,
   CompressorComponent codec
);

Parameters

srcRefNum

A file reference number for the source PICT file.

dstRefNum

A file reference number for the destination PICT file. Note that the compressor overwrites the contents of the file referred to by dstRefNum. You must open this file with write permissions. The destination file may be the same as the source file specified by the srcRefNum parameter.

colorDepth

The depth at which the image is to be compressed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor capability structure returned by the GetCodecInfo function.

ctable

quality

A constant (see below) that defines the desired compressed image quality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

doDither

Indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. The following constants are available: See these constants:

defaultDither
forceDither
suppressDither

compressAgain

Indicates whether to recompress compressed image data in the picture. Use this parameter to control whether any compressed image data that is in the source picture should be decompressed and then recompressed using the current parameters. Set the value of this parameter to TRUE to recompress such data. Set the value of this parameter to FALSE to leave the data as it is. Note that recompressing the data may have undesirable side effects, including image quality degradation.

progressProc

Points to an ICMProgressProc callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress.

cType

A compressor type. You must set this parameter to a valid compressor type constant.

codec

A compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). See these constants:

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function compresses only image data. Any other types of data in the file, such as text, graphics primitives, and previously compressed images, are not modified in any way and are passed through to the destination picture file. This function supports parameters governing image quality, compressor type, image depth, custom color tables, and dithering.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FDecompressImage

Decompresses a single-frame image into a pixel map structure, with added control over the decompression process.

OSErr FDecompressImage (
   Ptr data,
   ImageDescriptionHandle desc,
   PixMapHandle dst,
   const Rect *srcRect,
   MatrixRecordPtr matrix,
   short mode,
   RgnHandle mask,
   PixMapHandle matte,
   const Rect *matteRect,
   CodecQ accuracy,
   DecompressorComponent codec,
   long bufferSize,
   ICMDataProcRecordPtr dataProc,
   ICMProgressProcRecordPtr progressProc
);

Parameters

data

Points to the compressed image data. If the entire compressed image cannot be stored at this location, your application may provide a data-loading function (see the discussion of the dataProc parameter to this function). This pointer must contain a 32-bit clean address.

desc

A handle to the ImageDescription structure that describes the compressed image.

dst

A handle to the pixel map where the decompressed image is to be displayed. Set the current graphics port to the port that contains this pixel map.

srcRect

A pointer 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 (0,0) and ((**desc).width,(**desc).height). If you want to decompress the entire source image, set this parameter to NIL. If the parameter is NIL, the rectangle is set to the rectangle structure of the ImageDescription structure.

matrix

Points to a matrix structure that specifies how to transform the image during decompression. You can use the matrix structure to translate or scale the image during decompression. If you do not want to apply such effects, set the matrix parameter to NIL.

mode

The transfer mode for the operation; see Graphics Transfer Modes.

mask

A handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to NIL.

matte

A handle to a pixel map that contains a blend matte. You can use the blend matte to cause the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported pixel depth; the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If you do not want to apply a blend matte, set this parameter to NIL.

matteRect

A pointer to a rectangle defining a portion of the blend matte to apply. If you do not want to use the entire matte referred to by the matte parameter, use this parameter to specify a rectangle within that matte. If specified, this rectangle must be the same size as the rectangle specified by the srcRect parameter. If you want to use the entire matte, or if you are not providing a blend matte, set this parameter to NIL.

accuracy

A constant (see below) that defines the desired compression accuracy. For a good display of still images, you should specify at least codecHighQuality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

codec

bufferSize

The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

dataProc

Points to an ICMDataProc data-loading callback. If there is not enough memory to store the compressed image, the compressor calls a function you provide that loads more compressed data. If you have not provided a data-unloading callback, set this parameter to NIL. In this case, the compressor expects that the entire compressed image is in the memory location specified by the data parameter.

progressProc

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function gives your application greater control over the parameters that guide the decompression operation. If you find that you do not need this level of control, use DecompressImage. Note that this function is invoked through the StdPix function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FindCodec

Determines which of the installed compressors or decompressors has been chosen to field requests made by using one of the special compressor identifiers.

OSErr FindCodec (
   CodecType cType,
   CodecComponent specCodec,
   CompressorComponent *compressor,
   DecompressorComponent *decompressor
);

Parameters

cType: You must set this parameter to a valid compressor type constant; see Codec Identifiers.
specCodec: A special codec identifier value (see below). See these constants:
compressor: A pointer to a field to receive the identifier for the compressor component. The Image Compression Manager returns the identifier of the compressor that meets the special characteristics you specify in the specCodec parameter. Note that this identifier may differ from the value of the field referred to by the decompressor field. The Image Compression Manager sets this field to 0 if it cannot find a suitable compressor component. Set this parameter to NIL if you do not want this information.
decompressor: A pointer to a field to receive the identifier for the decompressor component. The Image Compression Manager returns the identifier of the decompressor that meets the special characteristics you specify in the specCodec parameter. Note that this identifier may differ from the value of the field referred to by the compressor field. The Image Compression Manager sets this field to 0 if it cannot find a suitable decompressor component. Set this parameter to NIL if you do not want this information.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Some Image Compression Manager functions allow you to specify a particular compressor component by its identifier. For example, you may use the codec parameter to CompressSequenceBegin to specify a particular compressor to do the compression. The Image Compression Manager also supports several special identifiers (see specCodec Constants, above) that allow you to exert some control over the component for a given action without having to know its identifier.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FixExp2

Undocumented

Fixed FixExp2 (
   Fixed src
);

Parameters

src: A fixed integer.

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FixLog2

Undocumented

Fixed FixLog2 (
   Fixed src
);

Parameters

src: A fixed integer.

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FixMulDiv

Undocumented

Fixed FixMulDiv (
   Fixed src,
   Fixed mul,
   Fixed divisor
);

Parameters

src: Undocumented
mul: Undocumented
divisor: Undocumented

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FixPow

Undocumented

Fixed FixPow (
   Fixed base,
   Fixed exp
);

Parameters

base: Undocumented
exp: Undocumented

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FracSinCos

Undocumented

Fract FracSinCos (
   Fixed degree,
   Fract *cosOut
);

Parameters

degree: Undocumented
cosOut: Undocumented

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GDGetScale

Returns the current scale of the given screen graphics device.

OSErr GDGetScale (
   GDHandle gdh,
   Fixed *scale,
   short *flags
);

Parameters

gdh: A handle to a screen graphics device.
scale: Points to a fixed-point field to hold the scale result.
flags: Points to a short integer that returns the status parameter flags for the video driver. Currently, 0 is always returned in this field.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GDHasScale

Returns the closest possible scaling that a particular screen device can be set to in a given pixel depth.

OSErr GDHasScale (
   GDHandle gdh,
   short depth,
   Fixed *scale
);

Parameters

gdh: A handle to a screen graphics device.
depth: The pixel depth of the screen device.
scale: Points to a fixed-point scale value. On input, this field should be set to the desired scale value. On output, this field will contain the closest scale available for the given depth. A scale of 0x10000 indicates normal size, 0x20000 indicates double size, and so on.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function returns scaling information for a particular screen device for a requested depth. This function allows you to query a screen device without actually changing it. For example, if you specify 0x20000 but the screen device does not support it, GDHasScale returns noErr and a scale of 0x10000. Because this function checks for a supported depth, your requested depth must be supported by the screen device.

Special Considerations

GDHasScale references the video driver through the graphics device structure.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GDSetScale

Sets a screen graphics device to a new scale.

OSErr GDSetScale (
   GDHandle gdh,
   Fixed scale,
   short flags
);

Parameters

gdh: A handle to a screen graphics device.
scale: A fixed-point scale value.
flags: Points to a short integer. It returns the status parameter flags for the video driver. Currently, 0 is always returned in this field.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetBestDeviceRect

Selects the deepest of all available graphics devices, while treating 16-bit and 32-bit screens as having equal depth.

OSErr GetBestDeviceRect (
   GDHandle *gdh,
   Rect *rp
);

Parameters

gdh: A pointer to the handle of the rectangle for the chosen device. If you do not need the information in this parameter returned, specify NIL.
rp: A pointer to the rectangle that is adjusted for the height of the menu bar if the device is the main device. If you do not need the information in this parameter returned, specify NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function does not center a rectangle on a device. Rather, it returns the rectangle for the best device. The following code sample illustrates its use:

// GetBestDeviceRect coding example

// See "Discovering QuickTime," page 265

WindowRef MakeMyWindow (void)

    WindowRef   pMacWnd;

    Rect        rectWnd ={0, 0, 120, 160};

    Rect        rectBest;

    // figure out the best monitor for the window

    GetBestDeviceRect(NIL, &rectBest);

    // put the window in the top left corner of that monitor

    OffsetRect(&rectWnd, rectBest.left + 10, rectBest.top + 50);

    // create the window

    pMacWnd =NewCWindow(NIL, &rectWnd, "\pGrabber",

                            TRUE, noGrowDocProc, (WindowRef)-1, TRUE, 0);

    // set the port to the new window

    SetPort(pMacWnd);

    return pMacWnd;

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCodecInfo

Returns information about a single compressor component.

ComponentResult ADD_IMAGECODEC_BASENAME() GetCodecInfo

Parameters

info: A pointer to a CodecInfo structure. GetCodecInfo returns detailed information about the appropriate compressor component in this structure.
cType: Set this parameter to a valid compressor type constant; see Codec Identifiers. If you want information about any compressor of the type specified by this parameter, set the codec parameter to 0. The Image Compression Manager then returns information about the first compressor it finds of the type you have specified.
codec: Set this parameter to the component identifier of the specific compressor for the request, or to 0 for any compressor. Component identifiers are available in the CodecNameSpecList structure returned by GetCodecNameList.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCodecNameList

Retrieves a list of installed compressor components or types.

OSErr GetCodecNameList (
   CodecNameSpecListPtr *list,
   short showAll
);

Parameters

list: A pointer to a field that is to receive a pointer to a CodecNameSpecList structure. The Image Compression Manager creates the appropriate list and returns a pointer to that list in the field specified by this parameter.
showAll: A short integer that controls the contents of the list. Set this parameter to 1 to receive a list of the names of all installed compressor components; the returned list contains one entry for each installed compressor. Set this parameter to 0 to receive a list of the types of installed compressor components; the returned list contains one entry for each installed compressor type.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The CodecType data type defines a field in the CodecNameSpec structure that identifies the compression method employed by a given compressor component. See Codec Identifiers. Apple Computer's Developer Technical Support group assigns these values so that they remain unique. These values correspond, in turn, to text strings that can identify the compression method to the user.

Special Considerations

GetCodecNameList creates the CodecNameSpecList structure in your application's current heap zone.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCompressedImageSize

Determines the size, in bytes, of a compressed image.

ComponentResult ADD_IMAGECODEC_BASENAME() GetCompressedImageSize

Parameters

desc: A handle to the ImageDescription structure that defines the compressed image for the operation.
data: Points to the compressed image data. This pointer must contain a 32-bit clean address.
bufferSize: The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.
dataProc: Points to an ICMDataProc callback. If the data stream is not all in memory when your program calls GetCompressedImageSize, the compressor calls a function you provide that loads more compressed data. If you have not provided a data-loading callback, set this parameter to NIL. In this case, the entire image must be in memory at the location specified by the data parameter.
dataSize: A pointer to a field that is to receive the size, in bytes, of the compressed image.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Most applications do not need to use this function because compressed images have a corresponding ImageDescription structure with a size field. You only need to use this function if you do not have an image description structure associated with your data; for example, when you are taking a compressed image out of a movie one frame at a time.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCompressedPixMapInfo

Retrieves information about a compressed image.

OSErr GetCompressedPixMapInfo (
   PixMapPtr pix,
   ImageDescriptionHandle *desc,
   Ptr *data,
   long *bufferSize,
   ICMDataProcRecord *dataProc,
   ICMProgressProcRecord *progressProc
);

Parameters

pix: Points to a structure that holds encoded compressed image data.
desc: A pointer to a field that is to receive a handle to the ImageDescription structure that defines the compressed image. If you are not interested in this information, specify NIL in this parameter.
data: A pointer to a field that is to receive a pointer to the compressed image data. If the entire compressed image cannot be stored at this location, you can define a data-loading function for this operation. If you are not interested in this information, you may specify NIL in this parameter.
bufferSize: A pointer to a field that is to receive the size of the buffer to be used by the data-loading function specified by the dataProc parameter. If there is no data-loading function defined for this operation, this parameter is ignored. If you are not interested in this information, you may specify NIL in this parameter.
dataProc: A pointer to an ICMDataProc callback. If there is not enough memory to store the compressed image, the decompressor calls a function you provide that loads more compressed data. If there is no data-loading function for this image, the function sets the dataProc field in the function structure to NIL. If you are not interested in this information, specify NIL in this parameter.
progressProc: A pointer to an ICMProgressProc callback. During a decompression operation, the decompressor may occasionally call a function you provide in order to report its progress. If there is no progress function for this image, the function sets the progressProc field in the function structure to NIL. If you pass a value of -1, QuickTime provides a standard progress function. If you are not interested in progress information, specify NIL in this parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCompressionTime

Determines the estimated amount of time required to compress a given image.

ComponentResult ADD_IMAGECODEC_BASENAME() GetCompressionTime

Parameters

src

A handle to the source image. The source image must be stored in a pixel map structure. The compressor uses only the bit depth of this image to determine the compression time. You may set this parameter to NIL if you are interested only in information about quality settings.

srcRect

A pointer to a rectangle defining the portion of the source image to compress. You may set this parameter to NIL if you are interested only in information about quality settings. GetCompressionTime then uses the bounds of the source pixel map.

colorDepth

cType

You must set this parameter to a valid compressor type constant; see Codec Identifiers.

codec

Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation. See these constants:

spatialQuality

A pointer to a field containing a constant (see below) that defines the desired compressed image quality. The Image Compression Manager sets this field to the closest actual quality that the compressor can achieve. If you are not interested in this information, pass NIL in this parameter. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

temporalQuality

A pointer to a field containing a constant (see below) that defines the desired temporal quality. Use this value only with images that are part of image sequences. The Image Compression Manager sets this field to the closest actual quality that the compressor can achieve. If you are not interested in this information, pass NIL in this parameter.

compressTime

A pointer to a field to receive the compression time in milliseconds. If the compressor cannot determine the amount of time required to compress the image or if the compressor does not support this function, this field is set to 0. If you are not interested in this information, pass NIL in this parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows you to verify that the quality settings you desire are supported by a given compressor component. You specify the compression characteristics, including compression type and quality, along with the image. The Image Compression Manager returns the maximum compression time for the specified image and parameters. Note that some compressors may not support this function. If the component you specify does not support this function, the Image Compression Manager returns a time value of 0.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCSequenceDataRateParams

Obtains the data rate parameters previously set with SetCSequenceDataRateParams.

OSErr GetCSequenceDataRateParams (
   ImageSequence seqID,
   DataRateParamsPtr params
);

Parameters

seqID: Contains the unique sequence identifier that was returned by CompressSequenceBegin.
params: Points to the data rate parameters structure associated with the sequence identifier specified in the seqID parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCSequenceFrameNumber

Returns the current frame number of the specified sequence.

OSErr GetCSequenceFrameNumber (
   ImageSequence seqID,
   long *frameNumber
);

Parameters

seqID: Contains the unique sequence identifier that was returned by the CompressSequenceBegin function.
frameNumber: A pointer to the current frame number of the sequence identified by the seqID parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCSequenceKeyFrameRate

Determines the current key frame rate of a sequence.

OSErr GetCSequenceKeyFrameRate (
   ImageSequence seqID,
   long *keyFrameRate
);

Parameters

seqID: Contains the unique sequence identifier that was returned by CompressSequenceBegin.
keyFrameRate: A pointer to a long integer that specifies the maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCSequenceMaxCompressionSize

Determines the maximum size an image will be after compression for a given compression sequence.

OSErr GetCSequenceMaxCompressionSize (
   ImageSequence seqID,
   PixMapHandle src,
   long *size
);

Parameters

seqID: Contains the unique sequence identifier that was returned by the CompressSequenceBegin function.
src: A handle to the source PixMap structure. The compressor uses only the image's size and pixel depth to determine the maximum size of the compressed image.
size: A pointer to a field to receive the maximum size, in bytes, of the compressed image.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function is similar to GetMaxCompressionSize, but operates on a compression sequence instead of requiring the application to pass individual parameters about the source image.

Special Considerations

Before calling GetCSequenceMaxCompressionSize you must have already started a compression sequence with CompressSequenceBegin

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetCSequencePrevBuffer

Determines the location of the previous image buffer allocated by the compressor.

OSErr GetCSequencePrevBuffer (
   ImageSequence seqID,
   GWorldPtr *gworld
);

Parameters

seqID: Contains the unique sequence identifier that was returned by the CompressSequenceBegin function.
gworld: A pointer to a field to receive a pointer to the CGrafPort structure that describes the graphics world for the image buffer. You should not dispose of this graphics world; the returned pointer refers to a buffer that the Image Compression Manager is using. If the compressor has not allocated a buffer, GetCSequencePrevBuffer returns an error result code.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Note that this function only returns information about buffers that were allocated by the compressor. You cannot use this function to determine the location of a buffer you have provided.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetDSequenceImageBuffer

Determines the location of the offscreen image buffer allocated by a decompressor.

OSErr GetDSequenceImageBuffer (
   ImageSequence seqID,
   GWorldPtr *gworld
);

Parameters

seqID: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
gworld: A pointer to a field to receive a pointer to the CGrafPort structure describing the graphics world for the image buffer. You should not dispose of this graphics world; the returned pointer refers to a buffer that the Image Compression Manager is using. It is disposed of for you when the CDSequenceEnd function is called. If the decompressor has not allocated a buffer, GetDSequenceImageBuffer returns an error result code.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetDSequenceMatrix

Gets the matrix that was specified for a decompression sequence by a call to SetDSequenceMatrix, or that was set at DecompressSequenceBegin.

OSErr GetDSequenceMatrix (
   ImageSequence seqID,
   MatrixRecordPtr matrix
);

Parameters

seqID: Contains the unique sequence identifier that was returned by DecompressSequenceBegin.
matrix: Points to a matrix structure that specifies how to transform the image during decompression

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetDSequenceNonScheduledDisplayDirection

Returns the display direction for a decompress sequence.

OSErr GetDSequenceNonScheduledDisplayDirection (
   ImageSequence sequence,
   Fixed *rate
);

Parameters

sequence: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
rate: A pointer to the display direction. Negative values represent backward display and positive values represent forward display.

Return Value

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

Availability

Available in OS X v10.4 and later.

Declared In

ImageCompression.h

GetDSequenceNonScheduledDisplayTime

Gets the display time for a decompression sequence.

OSErr GetDSequenceNonScheduledDisplayTime (
   ImageSequence sequence,
   TimeValue64 *displayTime,
   TimeScale *displayTimeScale
);

Parameters

sequence: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
displayTime: A pointer to a variable to hold the display time.
displayTimeScale: A pointer to a variable to hold the display time scale.

Return Value

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

Availability

Available in OS X v10.4 and later.

Declared In

ImageCompression.h

GetDSequenceScreenBuffer

Determines the location of the offscreen screen buffer allocated by a decompressor.

OSErr GetDSequenceScreenBuffer (
   ImageSequence seqID,
   GWorldPtr *gworld
);

Parameters

seqID: The unique sequence identifier that was returned by the DecompressSequenceBegin function.
gworld: A pointer to a field to receive a pointer to the CGrafPort structure that describes the graphics world for the screen buffer. You should not dispose of this graphics world; the returned pointer refers to a buffer that the Image Compression Manager is using. It is disposed of for you when the CDSequenceEnd function is called. If the decompressor has not allocated a buffer, GetDSequenceScreenBuffer returns an error result code.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetGraphicsImporterForDataRef

Locates and opens a graphics importer component that can be used to draw the image from specified data reference.

OSErr GetGraphicsImporterForDataRef (
   Handle dataRef,
   OSType dataRefType,
   ComponentInstance *gi
);

Parameters

dataRef: The data reference to be drawn using a graphics importer component.
dataRefType: The type of data reference pointed to by the dataRef parameter; see Data References. For alias-based data references, the dataRef handle contains an AliasRecord and dataRefType is set to rAliasType.
gi: On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found, this parameter will be set to NIL. If GetGraphicsImporterForDataRef is able to locate a graphics importer for the data reference, the returned graphics importer ComponentInstance will already be set up to draw from the specified data reference to the current port.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function tries to locate a graphics importer component for the specified data reference by checking the file extension (such as .GIF or .JPG), the Macintosh file type, and the MIME type of the file. The file extension is retrieved from the data reference by using DataHGetFileName to call the data handler associated with the data reference. If a graphics importer cannot be found using the file's type, file extension, or MIME type, GetGraphicsImporterForDataRef asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming; to bypass it, call GetGraphicsImporterForDataRefWithFlags instead.

Special Considerations

The caller of GetGraphicsImporterForDataRef is responsible for closing the returned ComponentInstance using CloseComponent. You must call CloseComponent when you are finished with the importer.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetGraphicsImporterForDataRefWithFlags

Locates and opens a graphics importer component for a data reference with flags that control the search process.

OSErr GetGraphicsImporterForDataRefWithFlags (
   Handle dataRef,
   OSType dataRefType,
   ComponentInstance *gi,
   long flags
);

Parameters

dataRef

The data reference to be drawn using a graphics importer component.

dataRefType

The type of data reference pointed to by the dataRef parameter; see Data References. For alias-based data references, the dataRef handle contains an AliasRecord and dataRefType is set to rAliasType.

gi

On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found, this parameter will be set to NIL. If GetGraphicsImporterForDataRefWithFlags is able to locate a graphics importer for the data reference, the returned graphics importer ComponentInstance will already be set up to draw from the specified data reference to the current port.

flags

Contains flags (see below) that control the graphics importer search process. See these constants:

kDontUseValidateToFindGraphicsImporter

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function tries to locate a graphics importer component for the specified data reference by checking the file extension (such as .GIF or .JPG), the Macintosh file type, and the MIME type of the file. The file extension is retrieved from the data reference by using DataHGetFileName to call the data handler associated with the data reference. If a graphics importer cannot be found using the file's type, file extension, or MIME type, this function asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming; to bypass it, pass kDontUseValidateToFindGraphicsImporter in the flags parameter.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetGraphicsImporterForFile

Locates and opens a graphics importer component that can be used to draw a specified file.

OSErr GetGraphicsImporterForFile (
   const FSSpec *theFile,
   ComponentInstance *gi
);

Parameters

theFile: The file to be drawn using a graphics importer component.
gi: On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found for the specified file, the gi will be set to NIL. If GetGraphicsImporterForFile is able to locate a graphics importer for the file, the returned graphics importer ComponentInstance will already be set up to draw the specified file to the current port.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function first tries to locate a graphics importer component for the specified file based on its file type. If it is unable to locate a graphics importer component based on the Macintosh file type, or the call is made on a non-Macintosh file, GetGraphicsImporterForFile will try to locate a graphics importer component based on the file extension (such as .JPG or .GIF). If a graphics importer cannot be found using the file's type or extension, GetGraphicsImporterForFile asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming. To bypass the validation attempt, call GetGraphicsImporterForFileWithFlags instead. The following code sample illustrates the use of GetGraphicsImporterForFile:

// Get a graphics importer for the image file, determine the natural size

// of the image, and draw the image

// See "Discovering QuickTime," page 274

void drawFile(const FSSpec *fss, const Rect *boundsRect)

        GraphicsImportComponent gi;

        GetGraphicsImporterForFile(fss, &gi);

        GraphicsImportSetBoundsRect(gi, boundsRect);

        GraphicsImportDraw(gi);

        CloseComponent(gi);

Special Considerations

The caller of GetGraphicsImporterForFile is responsible for closing the returned ComponentInstance using CloseComponent.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetGraphicsImporterForFileWithFlags

Locates and opens a graphics importer component for a file with flags that control the search process.

OSErr GetGraphicsImporterForFileWithFlags (
   const FSSpec *theFile,
   ComponentInstance *gi,
   long flags
);

Parameters

theFile

The file to be drawn using a graphics importer component.

gi

On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found for the specified file, the gi will be set to NIL. If GetGraphicsImporterForFileWithFlags is able to locate a graphics importer for the file, the returned graphics importer ComponentInstance will already be set up to draw the specified file to the current port.

flags

Contains flags (see below) that control the graphics importer search process. See these constants:

kDontUseValidateToFindGraphicsImporter

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function first tries to locate a graphics importer component for the specified file based on its file type. If it is unable to locate a graphics importer component based on the Macintosh file type, or the call is made on a non-Macintosh file, GetGraphicsImporterForFile will try to locate a graphics importer component based on the file extension (such as .JPG or .GIF). If a graphics importer cannot be found using the file's type or extension, GetGraphicsImporterForFile asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming. To bypass the validation attempt, pass kDontUseValidateToFindGraphicsImporter in the flags parameter.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetImageDescriptionCTable

Gets the custom color table for an image.

OSErr GetImageDescriptionCTable (
   ImageDescriptionHandle desc,
   CTabHandle *ctable
);

Parameters

desc: A handle to the appropriate ImageDescription structure.
ctable: A pointer to a field that is to receive a color table handle.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function returns the color table for the image described by the ImageDescription structure that is referred to by the desc parameter. The function correctly sizes the handle for the color table it returns.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetImageDescriptionExtension

Returns a new handle with the data from a specified image description extension.

OSErr GetImageDescriptionExtension (
   ImageDescriptionHandle desc,
   Handle *extension,
   long idType,
   long index
);

Parameters

desc: A handle to the appropriate ImageDescription structure.
extension: A pointer to a field to receive a handle to the returned data. The GetImageDescriptionExtension function returns the extended data for the image described by the ImageDescription structure referred to by the desc parameter. The function correctly sizes the handle for the data it returns.
idType: Specifies the extension's type value. Use this parameter to determine the data type of the extension. This parameter contains a four-character code, similar to an OSType field value.
index: The index of the extension to retrieve. This is a number between 1 and the count returned by CountImageDescriptionExtensionType.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows the application to get a copy of a specified image description extension. Note that each compressor type may have its own format for the extended data that is stored with an image. The extended data is similar in concept to the user data that applications can associate with QuickTime movies. Once you have added extended data to an image, you cannot delete it.

Special Considerations

The Image Compression Manager allocates a new handle and passes it back in the extension parameter. Your application should dispose of the handle when it is no longer needed.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetMatrixType

Obtains information about a matrix.

short GetMatrixType (
   const MatrixRecord *m
);

Parameters

m: Points to the MatrixRecord structure for this operation.

Return Value

A constant (see below) that defines the type of the matrix.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetMaxCompressionSize

Determines the maximum size an image will be after compression.

ComponentResult ADD_IMAGECODEC_BASENAME() GetMaxCompressionSize

Parameters

src

A handle to the source image. The source image must be stored in a pixel map structure. The compressor uses only the image's size and pixel depth to determine the maximum size of the compressed image.

srcRect

A pointer to a rectangle defining the portion of the source image that is to be compressed. You may set this parameter to NIL if you are interested only in information about quality settings. GetCompressionTime then uses the bounds of the source pixel map.

colorDepth

quality

A constant (see below) that defines the desired compressed image quality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

cType

You must set this parameter to a valid compressor type constant; see Codec Identifiers.

codec

A compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation. See these constants:

size

A pointer to a field to receive the size, in bytes, of the compressed image.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function returns the maximum resulting size for the specified image and parameters. Your application may then use this information to allocate memory for the compression operation. The following code sample illustrates its use:

// GetMaxCompressionSize coding example

// See "Discovering QuickTime," page 286

PicHandle GetQTCompressedPict (PixMapHandle hpmImage)

    long                    lMaxCompressedSize =0;

    Handle                  hCompressedData =NIL;

    Ptr                     pCompressedData;

    ImageDescriptionHandle  hImageDesc =NIL;

    OSErr                   nErr;

    PicHandle               hpicPicture =NIL;

    Rect                    rectImage =(**hpmImage).bounds;

    CodecType               dwCodecType =kJPEGCodecType;

    CodecComponent          codec =(CodecComponent)anyCodec;

    CodecQ                  dwSpatialQuality =codecNormalQuality;

    short                   nDepth =0;          // let ICM choose depth

    nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,

                                        dwSpatialQuality,

                                        dwCodecType,

                                        (CompressorComponent)codec,

                                        &lMaxCompressedSize);

    if (nErr !=noErr)

        return NIL;

    hImageDesc =(ImageDescriptionHandle)NewHandle(4);

    hCompressedData =NewHandle(lMaxCompressedSize);

    if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {

        MoveHHi(hCompressedData);

        HLock(hCompressedData);

        pCompressedData =StripAddress(*hCompressedData);

        nErr =CompressImage(hpmImage,

                                        &rectImage,

                                        dwSpatialQuality,

                                        dwCodecType,

                                        hImageDesc,

                                        pCompressedData);

        if (nErr ==noErr) {

            ClipRect(&rectImage);

            hpicPicture =OpenPicture(&rectImage);

            nErr =DecompressImage(pCompressedData,

                                        hImageDesc,

                                        hpmImage,

                                        &rectImage,

                                        &rectImage,

                                        srcCopy,

                                        NIL);

            ClosePicture();

        if (theErr || (GetHandleSize((Handle)hpicPicture) ==

                                            sizeof(Picture))) {

            KillPicture(hpicPicture);

            hpicPicture =NIL;

    if (hImageDesc !=NIL)

        DisposeHandle((Handle)hImageDesc);

    if (hCompressedData !=NIL)

        DisposeHandle(hCompressedData);

    return hpicPicture;

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetNextImageDescriptionExtensionType

Retrieves an image description structure extension type.

OSErr GetNextImageDescriptionExtensionType (
   ImageDescriptionHandle desc,
   long *idType
);

Parameters

desc: A handle to an ImageDescription structure.
idType: A pointer to an integer that indicates the type of the extension after which this function is to return the next extension type. Point to a value of 0 to return the first type found.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows your application to search for all the types of extensions in an ImageDescription structure. The idType parameter should be set to 0 to start the search. When no more extension types can be found, the function will set this field to 0.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetPictureFileHeader

Extracts the picture frame and file header from a specified picture file.

OSErr GetPictureFileHeader (
   short refNum,
   Rect *frame,
   OpenCPicParams *header
);

Parameters

refNum: A file reference number for the source PICT file.
frame: A pointer to a rectangle that is to receive the picture frame rectangle of the picture file. This function places the picFrame rectangle from the picture structure into the rectangle referred to by the frame parameter. If you are not interested in this information, pass NIL in this parameter.
header: A pointer to an OpenCPicParams structure. The GetPictureFileHeader function places the header from the specified picture file into this structure. If you are not interested in this information, pass NIL in this parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Your program can use the information returned in the header parameter to determine how to draw an image without having to read the picture file.

Special Considerations

Note that this function always returns a version 2 header. If the source file is a version 1 PICT file, the GetPictureFileHeader function converts the header into version 2 format before returning it to your application. See Inside Macintosh: Imaging With QuickDraw for more information about picture headers.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

GetSimilarity

Compares a compressed image to a picture stored in a pixel map and returns a value indicating the relative similarity of the two images.

ComponentResult ADD_IMAGECODEC_BASENAME() GetSimilarity

Parameters

src: A handle to the noncompressed image. The image must be stored in a pixel map structure.
srcRect: A pointer to a rectangle defining the portion of the image to compare to the compressed image. This rectangle should be the same size as the image described by the ImageDescription structure specified by the desc parameter.
desc: A handle to the ImageDescription structure that defines the compressed image for the operation.
data: Points to the compressed image data. This pointer must contain a 32-bit clean address.
similarity: A pointer to a field that is to receive the similarity value. The compressor sets this field to reflect the relative similarity of the two images. Valid values range from 0 (completely different) to 1.0 (identical).

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

HitTestDSequenceData

Undocumented

OSErr HitTestDSequenceData (
   ImageSequence seqID,
   void *data,
   Size dataSize,
   Point where,
   long *hit,
   long hitFlags
);

Parameters

seqID: The unique sequence identifier that was returned by the DecompressSequenceBegin function.
data: A pointer to data.
dataSize: The size of the data.
where: A Point structure that defines the hit location.
hit: Undocumented
hitFlags: Undocumented

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMDecompressComplete

Signals the completion of a decompression operation.

void ICMDecompressComplete (
   ImageSequence seqID,
   OSErr err,
   short flag,
   ICMCompletionProcRecordPtr completionRtn
);

Parameters

seqID

The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

err

Indicates whether the operation succeeded or failed. Set this parameter to 0 for successful operations. For failed operations, set the error code appropriate for the failure. For canceled operations (for example, when the ICM calls your component's ImageCodecFlush function), set this parameter to -1.

flag

Completion flags (see below). Note that you may set more than one of these flags to 1. See these constants:

codecCompletionSource
codecCompletionDest
codecCompletionDontUnshield

completionRtn

A pointer to an ICMCompletionProcRecord structure. That structure identifies the application's completion function and contains a reference constant associated with the frame. Your component obtains this structure as part of the CodecDecompressParams structure provided by the Image Compression Manager at the start of the decompression operation.

Discussion

Your component must call this function at the end of decompression operations.

Special Considerations

Prior to QuickTime 2.0, decompressor components called the application's completion function directly. For compatibility, that method is still supported except for scheduled asynchronous decompression operations, which must use the ICMDecompressComplete call. Newer decompressors should always use ICMDecompressComplete rather than calling the completion function directly, regardless of the type of decompression operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMDecompressCompleteS

Undocumented

OSErr ICMDecompressCompleteS (
   ImageSequence seqID,
   OSErr err,
   short flag,
   ICMCompletionProcRecordPtr completionRtn
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
err: Indicates whether the operation succeeded or failed. See Error Codes.
flag: Undocumented
completionRtn: A pointer to an ICMCompletionProcRecord structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMGetPixelFormatInfo

Retrieves pixel format information.

OSErr ICMGetPixelFormatInfo (
   OSType PixelFormat,
   ICMPixelFormatInfoPtr theInfo
);

Parameters

PixelFormat: A constant that identifies the format; see Pixel Formats.
theInfo: A pointer to your ICMPixelFormatInfo structure in which information is returned. You should initialize the size field of this structure with sizeof (ICMPixelFormatInfo). The function will not copy more than this number of bytes into the structure. On return, the size field contains the actual size of the data structure. If this amount is greater the size you passed in, that means you didn't retrieve all of the information.

Return Value

Returns cDepthErr if the pixel format is not valid. For other errors, see Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMSequenceGetChainMember

Undocumented

OSErr ICMSequenceGetChainMember (
   ImageSequence seqID,
   ImageSequence *retSeqID,
   long flags
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
retSeqID: Undocumented
flags: Undocumented

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMSequenceGetInfo

Gets multiprocessing properties for compression and decompression sequences.

OSErr ICMSequenceGetInfo (
   ImageSequence seqID,
   OSType which,
   void *data
);

Parameters

seqID

The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

which

A constant (see below) that determines the property to be returned. See these constants:

kICMSequenceTaskWeight
kICMSequenceTaskName

data

The value of the property indicated by the which parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function determines if ICM clients have requested that multiprocessor tasks assisting compression and decompression operations use specific task weights and task names.

Special Considerations

Apple's multiprocessing capability supports both co-operatively scheduled tasks and preemptively scheduled tasks. The support for preemptively tasks allow applications to create symmetrically scheduled preemptive tasks that can be run on a single processor machine, and will take full advantage of multiple processors when they are installed.

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMSequenceLockBits

Undocumented

OSErr ICMSequenceLockBits (
   ImageSequence seqID,
   PixMapPtr dst,
   long flags
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
dst: A pointer to a PixMap structure.
flags: Undocumented

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMSequenceSetInfo

Sets multiprocessing properties for compression and decompression sequences.

OSErr ICMSequenceSetInfo (
   ImageSequence seqID,
   OSType which,
   void *data,
   Size dataSize
);

Parameters

seqID

The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

which

A constant (see below) that determines the property to be set. See these constants:

kICMSequenceTaskWeight
kICMSequenceTaskName

data

The value of the property to be set.

dataSize

The length in bytes of the data parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function lets ICM clients request that multiprocessor tasks assisting compression and decompression operations use specific task weights and task names.

Special Considerations

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMSequenceUnlockBits

Undocumented

OSErr ICMSequenceUnlockBits (
   ImageSequence seqID,
   long flags
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
flags: Undocumented

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMSetPixelFormatInfo

Lets you define your own pixel format.

OSErr ICMSetPixelFormatInfo (
   OSType PixelFormat,
   ICMPixelFormatInfoPtr theInfo
);

Parameters

PixelFormat: A pixel format constant. See Pixel Formats.
theInfo: A pointer to an ICMPixelFormatInfo structure containing a definition of the new pixel format.

Return Value

Returns paramErr if the format is already defined. See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ICMShieldSequenceCursor

Hides the cursor during decompression operations.

OSErr ICMShieldSequenceCursor (
   ImageSequence seqID
);

Parameters

seqID: The unique sequence identifier, assigned by CompressSequenceBegin or DecompressSequenceBegin, for which to shield the cursor.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

For correct image display behavior, the cursor must be shielded (hidden) during decompression. By default, the Image Compression Manager handles the cursor for you, hiding it at the beginning of a decompression operation and revealing it at the end. With scheduled asynchronous decompression, however, the ICM cannot do as precise a job of managing the cursor, because it does not know exactly when scheduled operations actually begin and end. While the ICM can still manage the cursor, it must hide the cursor when each request is queued, rather than when the request is serviced. This may result in the cursor remaining hidden for long periods of time. To achieve better cursor behavior, you can choose to manage the cursor in your decompressor component. If you so choose, you can use this function to hide the cursor; the ICM displays the cursor when you call ICMDecompressComplete. In this manner, the cursor is hidden only when your component is decompressing and displaying the frame.

Special Considerations

This function may be called at interrupt time.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageFieldSequenceBegin

Initiates an image field sequence operation and specifies the input and output data format.

OSErr ImageFieldSequenceBegin (
   ImageFieldSequence *ifs,
   ImageDescriptionHandle desc1,
   ImageDescriptionHandle desc2,
   ImageDescriptionHandle descOut
);

Parameters

ifs: On return, contains the unique sequence identifier assigned to the sequence.
desc1: An ImageDescription structure describing the format and characteristics of the data to be passed to ImageFieldSequenceExtractCombine through the data1 parameter.
desc2: An ImageDescription structure describing the format and characteristics of the data to be passed to the ImageFieldSequenceExtractCombine function through the data2 parameter. Set to NIL if the requested operation uses only one input frame.
descOut: The desired format of the resulting frames. Typically this is the same format specified by the desc1 and desc2 parameters.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Use this function to set up an image field sequence operation and specify the input and output data format.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageFieldSequenceEnd

Ends an image field sequence operation.

OSErr ImageFieldSequenceEnd (
   ImageFieldSequence ifs
);

Parameters

ifs: The unique sequence identifier that was returned by the ImageFieldSequenceBegin function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You must call this function to terminate an image field sequence operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageFieldSequenceExtractCombine

Performs field operations on video data.

OSErr ImageFieldSequenceExtractCombine (
   ImageFieldSequence ifs,
   long fieldFlags,
   void *data1,
   long dataSize1,
   void *data2,
   long dataSize2,
   void *outputData,
   long *outDataSize
);

Parameters

ifs

The unique sequence identifier that was returned by ImageFieldSequenceBegin.

fieldFlags

Flags (see below) that specify the operation to be performed. A correctly formed request will specify two input fields, mapping one to the odd output field and the other to the even output field. See these constants:

evenField1ToEvenFieldOut
evenField1ToOddFieldOut
oddField1ToEvenFieldOut
oddField1ToOddFieldOut
evenField2ToEvenFieldOut
evenField2ToOddFieldOut
oddField2ToEvenFieldOut
oddField2ToOddFieldOut

data1

A pointer to a buffer containing the data of input field one.

dataSize1

The size of the data1 buffer.

data2

A pointer to a buffer containing the data of input field two. Set to NIL if the requested operation uses only one input frame.

dataSize2

The size of the data2 buffer. Set to 0 if the requested operation uses only one input frame.

outputData

A pointer to a buffer to receive the resulting frame. Use GetMaxCompressionSize to determine the amount of memory to allocate for this buffer.

outDataSize

On output this parameter returns the actual size of the data.

Return Value

Returns the codecUnimpErr result code if there is no codec present in the system that can perform the requested operation. See Error Codes. Returns noErr if there is no error.

Discussion

This function provides a method for working directly with fields of interlaced video. You can use it to change the field dominance of an image by reversing the two fields, or to create or remove the effects of the 3:2 pulldown commonly performed when transferring film to NTSC videotape. Because this function operates directly on the compressed video data, it is faster than working with decompressed images. It also has the added benefit of eliminating any image quality degradation that might result from lossy codecs.

This function accepts one or two compressed images as input and creates a single compressed image on output. You specify the operation to be performed using the fieldFlags parameter.

Special Considerations

The Apple Component Video (YUV) and Motion JPEG codecs currently support this function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageTranscodeDisposeFrameData

Disposes transcoded image data.

OSErr ImageTranscodeDisposeFrameData (
   ImageTranscodeSequence its,
   void *dstData
);

Parameters

its: The image transcoder sequence that was used to generate the transcoded data.
dstData: A pointer to the transcoded image data generated by the ImageTranscodeFrame function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When the transcoded image data returned by ImageTranscodeFrame is no longer needed, use this function to dispose of the data. Only the image transcoder that generated the data can properly dispose of it.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageTranscodeFrame

Transcodes a frame of image data.

OSErr ImageTranscodeFrame (
   ImageTranscodeSequence its,
   void *srcData,
   long srcDataSize,
   void **dstData,
   long *dstDataSize
);

Parameters

its: The image transcoder sequence to use to perform the transcoding operation.
srcData: A pointer to the source data to transcode.
srcDataSize: The size of the compressed source image data in bytes.
dstData: On return, a pointer to the transcoded image data.
dstDataSize: On return, the size of the transcoded image data.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

After creating the image transcoder sequence, using ImageTranscodeSequenceBegin, use this function to transcode a frame of image data. The caller is responsible for disposing of the transcoded data using ImageTranscodeDisposeFrameData.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageTranscodeSequenceBegin

Initiates an image transcoder sequence operation.

OSErr ImageTranscodeSequenceBegin (
   ImageTranscodeSequence *its,
   ImageDescriptionHandle srcDesc,
   OSType destType,
   ImageDescriptionHandle *dstDesc,
   void *data,
   long dataSize
);

Parameters

its: The image transcoder sequence identifier. If the operation fails, the value pointed to is set to NIL.
srcDesc: The ImageDescription structure for the source compressed image data.
destType: The desired compression format into which to transcode the source data.
dstDesc: On return, an ImageDescription structure for the data which will be generated by the image transcoding sequence.
data: A pointer to first frame of compressed data to transcode. Set to NIL of not available.
dataSize: The size of the compressed data, in bytes. Set to 0 if no data is provided.

Return Value

See Error Codes. Returns noErr if there is no error. If no transcoder is available to perform the requested transcoding operation, a cantFindHandler error is returned.

Discussion

This function begins an image transcoder sequence operation and returns the sequence identifier in the its parameter. The caller is responsible for disposing of the ImageDescription structure that is returned in the dstDesc parameter.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageTranscodeSequenceEnd

Ends an image transcoder sequence operation.

OSErr ImageTranscodeSequenceEnd (
   ImageTranscodeSequence its
);

Parameters

its: The identifier of the image transcoder sequence to dispose. It is safe to pass a value of 0 in this parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You must call this function to terminate an image transcoder sequence operation and dispose of the sequence.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

InverseMatrix

Creates a new matrix that is the inverse of a specified matrix.

Boolean InverseMatrix (
   const MatrixRecord *m,
   MatrixRecord *im
);

Parameters

m: A pointer to the source MatrixRecord structure for the operation.
im: A pointer to a MatrixRecord structure that is to receive the new matrix. The function updates this structure so that it contains a matrix that is the inverse of that specified by the m parameter.

Return Value

A Boolean value of TRUE if InverseMatrix was able to create an inverse matrix, FALSE otherwise.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

MakeFilePreview

Creates a preview for a file.

OSErr MakeFilePreview (
   short resRefNum,
   ICMProgressProcRecordPtr progress
);

Parameters

resRefNum

The resource file for this operation. You must have opened this resource file with write permission. If there is a preview in the specified file, the Movie Toolbox replaces that preview with a new one.

progress

A pointer to an ICMProgressProcRecord structure. During the process of creating the preview, the Movie Toolbox may occasionally call a function you provide in order to report its progress. You can then use this information to keep the user informed.

Set this parameter to -1 to use the default progress function. If you specify a progress function, it must comply with the interface defined for Image Compression Manager progress functions; see "Image Compression Manager" in Inside Macintosh: QuickTime for more information. Set this parameter to NIL to prevent the Movie Toolbox from calling a progress function.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You should create a preview whenever you save a movie. You specify the file by supplying a reference to its resource file. You must have opened this resource file with write permission. If there is a preview in the specified file, the Movie Toolbox replaces that preview with a new one.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

MakeImageDescriptionForEffect

Returns an ImageDescription structure you can use to help create a sample description for an effect.

OSErr MakeImageDescriptionForEffect (
   OSType effectType,
   ImageDescriptionHandle *idh
);

Parameters

effectType: The four-character code identifying the type of effect to make an image description for. See Effects Codes.
idh: The handle of an ImageDescription structure. On entry, this parameter normally points to an ImageDescription structure whose contents are NIL. On return, the structure is correctly filled out for the selected effect type.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

To create a sample description, you create and fill out a data structure of type ImageDescription. This function simplifies this process. Only sample descriptions made with this function can be used in stacked effects, where one effect track acts as a source for another.

The following sample code creates a sample description:.

// MakeImageDescriptionForEffect coding example

// Return a new image description with default and specified values.

ImageDescriptionHandle QTEffSeg_MakeSampleDescription (

                   OSType theEffectType, short theWidth, short theHeight)

    ImageDescriptionHandle      mySampleDesc =NIL;

#if USES_MAKE_IMAGE_DESC_FOR_EFFECT

    OSErr  myErr =noErr;

    // create a new sample description

    myErr =MakeImageDescriptionForEffect(theEffectType, &mySampleDesc);

    if (myErr !=noErr)

        return(NIL);

#else

    // create a new sample description

    mySampleDesc =(ImageDescriptionHandle)

                                 NewHandleClear(sizeof(ImageDescription));

    if (mySampleDesc ==NIL)

        return(NIL);

    // fill in the fields of the sample description

    (**mySampleDesc).cType =theEffectType;

    (**mySampleDesc).idSize =sizeof(ImageDescription);

    (**mySampleDesc).hRes =72L << 16;

    (**mySampleDesc).vRes =72L << 16;

    (**mySampleDesc).frameCount =1;

    (**mySampleDesc).depth =0;

    (**mySampleDesc).clutID =-1;

#endif

    (**mySampleDesc).vendor =kAppleManufacturer;

    (**mySampleDesc).temporalQuality =codecNormalQuality;

    (**mySampleDesc).spatialQuality =codecNormalQuality;

    (**mySampleDesc).width =theWidth;

    (**mySampleDesc).height =theHeight;

    return(mySampleDesc);

Version Notes

Introduced in QuickTime 4. Image descriptions built using sample code from earlier versions of QuickTime cannot be used when stacking effects.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

MakeImageDescriptionForPixMap

Fills out an ImageDescription structure corresponding to a PixMap structure.

OSErr MakeImageDescriptionForPixMap (
   PixMapHandle pixmap,
   ImageDescriptionHandle *idh
);

Parameters

pixmap: A handle to a PixMap structure.
idh: The handle of an ImageDescription structure. On entry, this parameter normally points to an ImageDescription structure whose contents are NIL. On return, the structure is correctly filled out for the selected PixMap.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

MakeThumbnailFromPicture

Creates a thumbnail picture from a specified Picture structure.

OSErr MakeThumbnailFromPicture (
   PicHandle picture,
   short colorDepth,
   PicHandle thumbnail,
   ICMProgressProcRecordPtr progressProc
);

Parameters

picture: A handle to the image from which the thumbnail is to be extracted. The image must be stored in a Picture structure.
colorDepth: The depth at which the image is likely to be viewed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images.
thumbnail: A handle to the destination Picture structure for the thumbnail image. The compressor resizes this handle for the resulting data.
progressProc: A pointer to an ICMProgressProcRecord structure. During the operation, the Image Compression Manager will occasionally call a function to report its progress. You can provide a function through this structure. If you have not provided a progress function, set this parameter to NIL. If you pass a value of -1, you obtain a standard progress function.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

MakeThumbnailFromPictureFile

Creates a thumbnail picture from a specified picture file.

OSErr MakeThumbnailFromPictureFile (
   short refNum,
   short colorDepth,
   PicHandle thumbnail,
   ICMProgressProcRecordPtr progressProc
);

Parameters

refNum: A file reference number for the PICT file from which the thumbnail is to be extracted.
colorDepth: The depth at which the image is likely to be viewed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images.
thumbnail: A handle to the destination picture structure for the thumbnail image. The compressor resizes this handle for the resulting data.
progressProc: A pointer to an ICMProgressProcRecord structure. During the operation, the Image Compression Manager will occasionally call a function to report its progress. You can provide a function through this structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

MakeThumbnailFromPixMap

Creates a thumbnail picture from a specified PixMap structure.

OSErr MakeThumbnailFromPixMap (
   PixMapHandle src,
   const Rect *srcRect,
   short colorDepth,
   PicHandle thumbnail,
   ICMProgressProcRecordPtr progressProc
);

Parameters

src: A handle to the image from which the thumbnail is to be extracted. The image must be stored in a PixMap structure.
srcRect: A pointer to a Rect structure that defines the portion of the image to use for the thumbnail.
colorDepth: The depth at which the image is likely to be viewed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images.
thumbnail: A handle to the destination picture structure for the thumbnail image. The compressor resizes this handle for the resulting data.
progressProc: A pointer to an ICMProgressProcRecord structure. During the operation, the Image Compression Manager will occasionally call a function to report its progress. You can provide a function through this structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

MapMatrix

Alters an existing matrix so that it defines a transformation from one rectangle to another.

void MapMatrix (
   MatrixRecord *matrix,
   const Rect *fromRect,
   const Rect *toRect
);

Parameters

matrix: A pointer to a matrix structure. The MapMatrix function modifies this matrix so that it performs a transformation in the rectangle specified by the toRect parameter that is analogous to the transformation it currently performs in the rectangle specified by the fromRect parameter.
fromRect: A pointer to the source Rect structure.
toRect: A pointer to the destination Rect structure.

Discussion

MapMatrix affects only the scaling and translation attributes of the matrix.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

NewImageGWorld

Creates an offscreen graphics world.

ComponentResult ADD_IMAGECODEC_BASENAME() NewImageGWorld

Parameters

gworld: A pointer to a graphic world created using the width, height, depth, and color table specified in the ImageDescription structure pointed to in the idh parameter.
idh: A handle to an ImageDescription structure that contains information for the graphics world pointed to by the gworld parameter.
flags: Graphics world creation flags (see below). The pixPurge, noNewDevice, useTempMem, keepLocal, pixelsPurgeable, and pixelsLocked flags are commands to this function; the others are returned by this function. See these constants:

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

PtInDSequenceData

Tests to see if a compressed image contains data at a a given point.

OSErr PtInDSequenceData (
   ImageSequence seqID,
   void *data,
   Size dataSize,
   Point where,
   Boolean *hit
);

Parameters

seqID: The unique sequence identifier that was returned by the DecompressSequenceBegin function.
data: Pointer to compressed data in the format specified by the desc param.
dataSize: Size of the compressed data referred to by the data param.
where: A QuickDraw Point structure of value (0,0), based at the top-left corner of the image.
hit: A pointer to a field to receive the Boolean indicating whether or not the image contained data at the specified point. The Boolean will be set to TRUE if the point specified by the where parameter is contained within the compressed image data specified by the data param, or FALSE if the specified point falls within a blank portion of the image.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

PtInDSequenceData allows the application to perform hit testing on compressed data.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTGetFileNameExtension

Gets the extension to a file name.

OSErr QTGetFileNameExtension (
   ConstStrFileNameParam fileName,
   OSType fileType,
   OSType *extension
);

Parameters

fileName: A file name string.
fileType: A file type; see File Types and Creators.
extension: A pointer to the file name extension string.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTGetPixelFormatDepthForImageDescription

For a given pixel format, returns the depth value that should be used in image descriptions.

short QTGetPixelFormatDepthForImageDescription (
   OSType PixelFormat
);

Parameters

PixelFormat: The image description's pixel format; see Pixel Formats.

Return Value

The pixel depth for that format.

Discussion

Given a pixel format, this function returns the corresponding depth value that should be used in image descriptions. Such a value is not the literal number of bits per pixel, but the closest corresponding classic QuickDraw depth. For any pixel format with an alpha channel, it is 32. For grayscale pixel formats of 8 or more bits per pixel, it is 40. For color quantized to 5 or 6 bits per component, it is 16. For all other color pixel formats, it is 24.

Version Notes

Introduced in QuickTime 6.

Availability

Available in OS X v10.2 and later.

Declared In

ImageCompression.h

QTGetPixelSize

Returns the bits per pixel for a given pixel format.

short QTGetPixelSize (
   OSType PixelFormat
);

Parameters

PixelFormat: A constant that identifies the pixel format; see Pixel Formats. This function returns meaningful information only for non-planar formats.

Return Value

The bits per pixel. Returns 0 if the format is unknown.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTGetPixMapHandleGammaLevel

Retrieves the current PixMap extension's gamma level setting.

Fixed QTGetPixMapHandleGammaLevel (
   PixMapHandle pm
);

Parameters

pm: A handle to a PixMap structure that has a PixMapExtension structure.

Return Value

On return, the gamma level previously set (or the default level) for the pixel map referenced by the pm parameter.

Discussion

A typical use for this function is to retrieve the gamma level of a pixel map after a codec decompresses it into a PixMap structure.

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTGetPixMapHandleRequestedGammaLevel

Retrieves the current PixMap extension's requested gamma level setting.

Fixed QTGetPixMapHandleRequestedGammaLevel (
   PixMapHandle pm
);

Parameters

pm: A handle to a PixMap structure that has a PixMapExtension structure.

Return Value

On return, the requested gamma level previously set (or the default level) for the pixel map referenced by the pm parameter.

Discussion

A typical use for this function is to retrieve the gamma level of a pixel map after a codec decompresses it into a PixMap structure. The requested gamma level is used to control what gamma conversion is attempted during decompression. The requested gamma level may differ from the actual gamma level depending on the compressed data and the capabilities of the codecs involved.

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTGetPixMapHandleRowBytes

Gets the rowBytes value for a pixel map accessed by a handle.

long QTGetPixMapHandleRowBytes (
   PixMapHandle pm
);

Parameters

pm: A handle to a PixMap structure.

Return Value

The rowBytes value.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTGetPixMapPtrGammaLevel

Retrieves the current PixMap extension's gamma level setting.

Fixed QTGetPixMapPtrGammaLevel (
   PixMapPtr pm
);

Parameters

pm: A pointer to a PixMap structure that has a PixMapExtension structure.

Return Value

On return, the gamma level previously set (or the default level) for the pixel map pointed to by the pm parameter.

Discussion

A typical use for this function is to retrieve the gamma level of a pixel map after a codec decompresses it into a PixMap structure.

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTGetPixMapPtrRequestedGammaLevel

Retrieves the current PixMap extension's gamma level setting.

Fixed QTGetPixMapPtrRequestedGammaLevel (
   PixMapPtr pm
);

Parameters

pm: A pointer to a PixMap structure that has a PixMapExtension structure.

Return Value

On return, the requested gamma level previously set (or the default level) for the pixel map pointed to by the pm parameter.

Discussion

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTGetPixMapPtrRowBytes

Gets the rowBytes value for a pixel map accessed by a pointer.

long QTGetPixMapPtrRowBytes (
   PixMapPtr pm
);

Parameters

pm: A pointer to a PixMap structure.

Return Value

The rowBytes value.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTNewGWorld

Creates an offscreen graphics world that may have a non-Macintosh pixel format.

OSErr QTNewGWorld (
   GWorldPtr *offscreenGWorld,
   OSType PixelFormat,
   const Rect *boundsRect,
   CTabHandle cTable,
   GDHandle aGDevice,
   GWorldFlags flags
);

Parameters

offscreenGWorld: On return, a pointer to the offscreen graphics world created by this routine.
PixelFormat: The new graphics world's pixel format; see Pixel Formats. This function won't work with planar pixel formats; use QTNewGWorldFromPtr instead. See the ICMPixelFormatInfo structure for a discussion of planar and chunky formats.
boundsRect: A pointer to the boundary rectangle and port rectangle for the offscreen pixel map. This becomes the boundary rectangle for the GDevice structure, if this function creates one. If you specify 0 in the PixelFormat parameter, the function interprets the boundaries in global coordinates that it uses to determine which screens intersect the rectangle. It then uses the pixel format, color table, and GDevice structure from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle. Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.
cTable: A handle to a ColorTable structure. If you pass NIL in this parameter, the function uses the default color table for the pixel format that you specify in the PixelFormat parameter. If you set the PixelFormat parameter to 0, the function ignores the cTable parameter and instead copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If you use this function on a computer that supports only basic QuickDraw, you may specify only NIL in this parameter.
aGDevice: A handle to a GDevice structure that is used only when you specify the noNewDevice flag in the flags parameter, in which case the function attaches this structure to the new offscreen graphics world. If you set the PixelFormat parameter to 0, or if you do not set the noNewDevice flag, the function ignores this parameter, so you should set it to NIL. If you set the PixelFormat parameter to 0, the function uses the GDevice structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. You should pass NIL in this parameter if the computer supports only basic QuickDraw. Generally, your application should never create GDevice structures for offscreen graphics worlds.
flags: Constants (see below) that identify options available to your application. You can set a combination of these flags. If you don't wish to use any of them, pass 0 in this parameter. In this case the default behavior is to create an offscreen graphics world where the base address for the offscreen pixel image is unpurgeable, the graphics world uses an existing GDevice structure (if you pass 0 in the depth parameter) or creates a new GDevice structure, it uses memory in your application heap, and it allows graphics accelerators to cache the offscreen pixel image. See these constants:

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTNewGWorldFromPtr

Wraps a graphics world and pixel map structure around an existing block of memory containing an image.

OSErr QTNewGWorldFromPtr (
   GWorldPtr *gw,
   OSType pixelFormat,
   const Rect *boundsRect,
   CTabHandle cTable,
   GDHandle aGDevice,
   GWorldFlags flags,
   void *baseAddr,
   long rowBytes
);

Parameters

gw: On entry, a pointer that isn't going to change during the lifetime of the allocated graphics world. On return, this pointer references the offscreen graphics world created by this function.
pixelFormat: The new graphics world's pixel format; see Pixel Formats.
boundsRect: A pointer to the boundary rectangle and port rectangle for the offscreen pixel map. This becomes the boundary rectangle for the GDevice structure, if this function creates one. If you specify 0 in the pixelFormat parameter, the function interprets the boundaries in global coordinates that it uses to determine which screens intersect the rectangle. It then uses the pixel format, color table, and GDevice structure from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle. Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.
cTable: A handle to a ColorTable structure. If you pass NIL in this parameter, the function uses the default color table for the pixel format that you specify in the pixelFormat parameter. If you set the pixelFormat parameter to 0, the function ignores the cTable parameter and instead copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If you use this function on a computer that supports only basic QuickDraw, you may specify only NIL in this parameter.
aGDevice: A handle to a GDevice structure that is used only when you specify the noNewDevice flag in the flags parameter, in which case the function attaches this structure to the new offscreen graphics world. If you set the pixelFormat parameter to 0, or if you do not set the noNewDevice flag, the function ignores this parameter, so you should set it to NIL. If you set the pixelFormat parameter to 0, the function uses the GDevice structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. You should pass NIL in this parameter if the computer supports only basic QuickDraw. Generally, your application should never create GDevice structures for offscreen graphics worlds.
flags: A constant (see below) that identifies an option available to your application. If you don't wish to use this option, pass 0 in this parameter. In this case the default behavior is to create an offscreen graphics world that uses an existing GDevice structure (if you pass 0 in the depth parameter) or creates a new GDevice structure. Most constants used in creating a GWorld are irrelevant for this function, as its purpose is to wrap a GWorld around an existing block of pixels rather than to define and create a pixmap. See these constants:
baseAddr: The base address for the pixel data.
rowBytes: The total size of the pixel data divided by the height of the pixel map. In other words, the number of bytes in one row of pixels or the number of bytes between vertically adjacent pixels.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function wraps a GWorld around an existing pixel map. Note that it does not copy the pixmap. A subsequent call to DisposeGWorld will not dispose of the pixel map; it will only dispose of the GWorld wrapper. It is the caller's responsibility to dispose of the pixel map.

You can use this call to allocate an offscreen graphics world using special memory (such as on a video card). If you have an image in memory that belong to something else (a hardware screen buffer, a 3D card, or another file format or program), you can use this function to wrap a graphics world around the image and then use QuickTime calls on that graphics world to compress it, scale it, draw to it, and so on. If your new graphics world has a planar pixel format, you must use this call instead of QTNewGWorld.

Special Considerations

Do not unlock the pixels of the allocated graphics world. If your original pixels are from another graphics world then you must ensure that the source pixels are locked.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTSetPixMapHandleGammaLevel

Sets the gamma level of a pixel map.

OSErr QTSetPixMapHandleGammaLevel (
   PixMapHandle pm,
   Fixed gammaLevel
);

Parameters

pm: A handle to a PixMap structure that has a PixMapExtension structure.
gammaLevel: The new gamma level.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function does not convert the contents of the PixMap structure. A typical usage would be to set the gamma level of a pixel map before compressing it so that the codec knows if it needs to do additional gamma correcting when compressing.

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTSetPixMapHandleRequestedGammaLevel

Sets the requested gamma level of a pixel map.

OSErr QTSetPixMapHandleRequestedGammaLevel (
   PixMapHandle pm,
   Fixed requestedGammaLevel
);

Parameters

pm

A handle to a PixMap structure that has a PixMapExtension structure.

requestedGammaLevel

A specified gamma level or a constant (see below). See these constants:

kQTUsePlatformDefaultGammaLevel
kQTUseSourceGammaLevel
kQTCCIR601VideoGammaLevel

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function does not convert the contents of the PixMap structure. A typical usage would be to set the requested gamma level of a pixel map before decompressing so that the codec knows what gamma correction is necessary when decompressing into the PixMap structure. The resulting gamma level can then be found by calling QTGetPixMapHandleGammaLevel.

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTSetPixMapHandleRowBytes

Sets the rowBytes value for a pixel map accessed by a handle.

OSErr QTSetPixMapHandleRowBytes (
   PixMapHandle pm,
   long rowBytes
);

Parameters

pm: A handle to a PixMap structure.
rowBytes: The rowBytes value to be set.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTSetPixMapPtrGammaLevel

Sets the gamma level of a pixel map.

OSErr QTSetPixMapPtrGammaLevel (
   PixMapPtr pm,
   Fixed gammaLevel
);

Parameters

pm: A pointer to a PixMap structure that has a PixMapExtension structure.
gammaLevel: The new gamma level.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTSetPixMapPtrRequestedGammaLevel

Sets the requested gamma level of a pixel map.

OSErr QTSetPixMapPtrRequestedGammaLevel (
   PixMapPtr pm,
   Fixed requestedGammaLevel
);

Parameters

pm

A pointer to a PixMap structure that has a PixMapExtension structure.

requestedGammaLevel

A specified gamma level or a constant (see below). See these constants:

kQTUsePlatformDefaultGammaLevel
kQTUseSourceGammaLevel
kQTCCIR601VideoGammaLevel

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTSetPixMapPtrRowBytes

Sets the rowBytes value for a pixel map accessed by a pointer.

OSErr QTSetPixMapPtrRowBytes (
   PixMapPtr pm,
   long rowBytes
);

Parameters

pm: A pointer to a PixMap structure.
rowBytes: The rowBytes value to be set.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QTUpdateGWorld

Changes the pixel depth, boundary rectangle, or color table for an existing offscreen graphics world with a non-Macintosh pixel format.

GWorldFlags QTUpdateGWorld (
   GWorldPtr *offscreenGWorld,
   OSType PixelFormat,
   const Rect *boundsRect,
   CTabHandle cTable,
   GDHandle aGDevice,
   GWorldFlags flags
);

Parameters

offscreenGWorld: On input, a pointer to an existing offscreen graphics world; upon completion, the pointer to the updated offscreen graphics world.
PixelFormat: The updated graphics world's pixel format; see Pixel Formats.
boundsRect: A pointer to the boundary rectangle and port rectangle for the updated offscreen pixel map. This becomes the boundary rectangle for the GDevice structure, if this function creates one. If you specify 0 in the PixelFormat parameter, the function interprets the boundaries in global coordinates that it uses to determine which screens intersect the rectangle. It then uses the pixel format, color table, and GDevice structure from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle. If the rectangle you specify in this parameter differs from, but has the same size as, the previous boundary rectangle, the function realigns the pixel image to the screen for optimum performance for CopyBits. Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.
cTable: A handle to a ColorTable structure for the updated graphics world. If you pass NIL in this parameter, the function uses the default color table for the pixel format that you specify in the PixelFormat parameter. If you set the PixelFormat parameter to 0, the function ignores the cTable parameter and instead copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If the color table that you specify in this parameter is different from the previous color table, or if the color table associated with the GDevice structure that you specify in the aGDevice parameter is different, the function maps the pixel values in the offscreen pixel map to the new color table. If you use this function on a computer that supports only basic QuickDraw, you may specify only NIL in this parameter.
aGDevice: A handle to a GDevice structure that is used only when you specify the noNewDevice flag in the flags parameter, in which case the function attaches this structure to the new offscreen graphics world. If you set the PixelFormat parameter to 0, or if you do not set the noNewDevice flag, the function ignores this parameter, so you should set it to NIL. If you set the PixelFormat parameter to 0, the function uses the GDevice structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. You should pass NIL in this parameter if the computer supports only basic QuickDraw. Generally, your application should never create GDevice structures for offscreen graphics worlds.
flags: Constants (see below) that identify options available to your application. You can set a combination of these flags. If you don't wish to use any of them, pass 0 in this parameter. In this case the default behavior is to create an offscreen graphics world where the base address for the offscreen pixel image is unpurgeable, the graphics world uses an existing GDevice structure (if you pass 0 in the depth parameter) or creates a new GDevice structure, it uses memory in your application heap, and it allows graphics accelerators to cache the offscreen pixel image. See these constants:

Return Value

A constant (see below) that reports on the operation of this function.

Discussion

If the Memory Manager purged the base address for the offscreen pixel image, this function reallocates the memory but the pixel image is lost. You must reconstruct it.

Special Considerations

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

QuadToQuadMatrix

Defines a matrix that maps between four input points and four output points.

OSErr QuadToQuadMatrix (
   const Fixed *source,
   const Fixed *dest,
   MatrixRecord *map
);

Parameters

source: A pointer to four input FixedPoint points.
dest: A pointer to four output FixedPoint points.
map: A pointer to a MatrixRecord structure that maps the value passed in source to the value passed in dest.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

RectMatrix

Creates a matrix that performs the translate and scale operation described by the relationship between two rectangles.

void RectMatrix (
   MatrixRecord *matrix,
   const Rect *srcRect,
   const Rect *dstRect
);

Parameters

matrix: A pointer to a MatrixRecord structure. This function updates the contents of this matrix so that the matrix describes a transformation from points in the rectangle specified by the srcRect parameter to points in the rectangle specified by the dstRect parameter. The previous contents of the matrix are ignored.
srcRect: A pointer to the source Rect structure.
dstRect: A pointer to the destination Rect structure.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

RemoveImageDescriptionExtension

Removes a specified extension from an ImageDescription structure.

OSErr RemoveImageDescriptionExtension (
   ImageDescriptionHandle desc,
   long idType,
   long index
);

Parameters

desc: A handle to an ImageDescription structure.
idType: The type of extension to remove.
index: The index of the extension to remove. This is a number between 1 and the count returned by CountImageDescriptionExtensionType.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows an application to remove a specified extension from an ImageDescription structure. Note that any extensions that are present in the structure after the deleted extension will have their index numbers renumbered.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ReplaceDSequenceImageDescription

Undocumented

OSErr ReplaceDSequenceImageDescription (
   ImageSequence seqID,
   ImageDescriptionHandle newDesc
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
newDesc: A handle to an ImageDescription structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 5.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

RotateMatrix

Modifies the contents of a matrix so that it defines a rotation operation.

void RotateMatrix (
   MatrixRecord *m,
   Fixed degrees,
   Fixed aboutX,
   Fixed aboutY
);

Parameters

m: A pointer to a MatrixRecord structure.
degrees: The number of degrees of rotation.
aboutX: The x coordinate of the anchor point of rotation.
aboutY: The y coordinate of the anchor point of rotation.

Discussion

This function updates the contents of a matrix so that the matrix describes a rotation operation; that is, it concatenates the rotation transformations onto whatever was initially in the matrix structure. You specify the direction and amount of rotation with the degrees parameter. You specify the point of rotation with the aboutX and aboutY parameters.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ScaleMatrix

Modifies the contents of a matrix so that it defines a scaling operation.

void ScaleMatrix (
   MatrixRecord *m,
   Fixed scaleX,
   Fixed scaleY,
   Fixed aboutX,
   Fixed aboutY
);

Parameters

m: A pointer to a MatrixRecord structure. The ScaleMatrix function updates the contents of this matrix so that the matrix describes a scaling operation; that is, it concatenates the respective transformations onto whatever was initially in the matrix structure. You specify the magnitude of the scaling operation with the scaleX and scaleY parameters. You specify the anchor point with the aboutX and aboutY parameters.
scaleX: The scaling factor applied to x coordinates.
scaleY: The scaling factor applied to y coordinates.
aboutX: The x coordinate of the anchor point.
aboutY: The y coordinate of the anchor point.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetCompressedPixMapInfo

Stores information about a compressed image for StdPix.

OSErr SetCompressedPixMapInfo (
   PixMapPtr pix,
   ImageDescriptionHandle desc,
   Ptr data,
   long bufferSize,
   ICMDataProcRecordPtr dataProc,
   ICMProgressProcRecordPtr progressProc
);

Parameters

pix: A pointer to a PixMap structure that holds compressed image data.
desc: A handle to the ImageDescription structure that defines the compressed image.
data: A pointer to the buffer for the compressed image data. If the entire compressed image cannot be stored at this location, you may assign a data-loading function (see the dataProc parameter, below). This pointer must contain a 32-bit clean address.
bufferSize: The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If there is no data-loading function defined for this operation, set this parameter to 0.
dataProc: A pointer to an ICMDataProcRecord structure. If there is not enough memory to store the compressed image, the decompressor calls an ICMDataProc callback that you provide, which loads more compressed data. If you do not want to assign a data-loading function, set this parameter to NIL.
progressProc: A pointer to an ICMProgressProcRecord structure. During the decompression operation, the decompressor may occasionally call an ICMProgressProc callback that you provide, in order to report its progress. If you do not want to assign a progress function, set this parameter to NIL. If you pass a value of -1, you obtain a standard progress function.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetCSequenceDataRateParams

Communicates information to compressors that can constrain compressed data in a particular sequence to a specific data rate.

OSErr SetCSequenceDataRateParams (
   ImageSequence seqID,
   DataRateParamsPtr params
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
params: A pointer to a DataRateParams structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetCSequenceFlushProc

Assigns a data-unloading function to a sequence.

OSErr SetCSequenceFlushProc (
   ImageSequence seqID,
   ICMFlushProcRecordPtr flushProc,
   long bufferSize
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
flushProc: A pointer to an ICMFlushProcRecord structure. If there is not enough memory to store the compressed image, the compressor calls an ICMFlushProc callback that you provide, which unloads some of the compressed data. If you have not provided such a data-unloading function, set this parameter to NIL. In this case, the compressor writes the entire compressed image into the memory location specified by the data parameter to CompressSequenceFrame.
bufferSize: The size of the buffer to be used by the data-unloading function specified by the flushProc parameter. If you have not specified such a data-unloading function, set this parameter to 0.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Data-unloading functions allow compressors to work with images that cannot fit in memory. During the compression operation, the compressor calls the data-unloading function whenever it has accumulated a specified amount of compressed data. Your data-unloading function then writes the compressed data to some other device, freeing buffer space for more compressed data. The compressor starts using the data-unloading function with the next image in the sequence.

Special Considerations

There is no parameter to the CompressSequenceBegin function that allows you to assign a data-unloading function to a sequence.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetCSequenceFrameNumber

Informs the compressor in use for the specified sequence that frames are being compressed out of order.

OSErr SetCSequenceFrameNumber (
   ImageSequence seqID,
   long frameNumber
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
frameNumber: The frame number of the frame that is being compressed out of sequence.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This information is necessary only for compressors that are sequence-sensitive.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetCSequenceKeyFrameRate

Adjusts the key frame rate for the current sequence.

OSErr SetCSequenceKeyFrameRate (
   ImageSequence seqID,
   long keyFrameRate
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
keyFrameRate: The maximum number of frames allowed between key frames. Set this parameter to 1 to specify all key frames, to 2 to specify every other frame as a key frame, to 3 to specify every third frame as a key frame, and so forth. The compressor determines the optimum placement for key frames based upon the amount of redundancy between adjacent images in the sequence. Consequently, the compressor may insert key frames more frequently than you have requested. However, the compressor will never place fewer key frames than is indicated by this parameter. If you set this parameter to 0, the Image Compression Manager only places key frames in the compressed sequence when you call CompressSequenceFrame, setting the codecFlagForceKeyFrame flag in the flags parameter. The compressor ignores this parameter if you have not requested temporal compression; that is, you have passed 0 for the temporalQuality parameter of CompressSequenceBegin.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Key frames provide points from which a temporally compressed sequence may be decompressed. Use this parameter to control the frequency at which the compressor places key frames into the compressed sequence. The new key frame rate takes effect with the next image in the sequence.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetCSequencePreferredPacketSize

Sets the preferred packet size for a sequence.

OSErr SetCSequencePreferredPacketSize (
   ImageSequence seqID,
   long preferredPacketSizeInBytes
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
preferredPacketSizeInBytes: The preferred packet size in bytes.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

This function was added in QuickTime 2.5 to support video conferencing applications by making each transmitted packet an independently decodable chunk of data.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetCSequencePrev

Allows the application to set the pixel map and boundary rectangle used by the previous frame in temporal compression.

OSErr SetCSequencePrev (
   ImageSequence seqID,
   PixMapHandle prev,
   const Rect *prevRect
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
prev: A handle to the new previous image buffer. You must allocate this buffer using the same pixel depth and ColorTable structure as the source image buffer that you specified with the src parameter when you called CompressSequenceBegin. The compressor uses this buffer to store a previous image against which the current image is compared when performing temporal compression. The compressor manages the contents of this buffer based upon several considerations, such as the key frame rate and the degree of difference between compared images. The current image is stored in the buffer referred to by the src parameter to CompressSequenceBegin.
prevRect: A pointer to a Rect structure that defines the portion of the previous image to use for temporal compression. The compressor uses this portion of the previous image as the basis of comparison with the current image. This rectangle must be the same size as the source rectangle you specify with the srcRect parameter to CompressSequenceBegin. To get the boundary of a source pixel map, set this parameter to NIL.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

When you start compressing a sequence, you may assign a previous frame buffer and rectangle with the prev and prevRect parameters to CompressSequenceBegin. If you specified a NIL value for the prev parameter, the compressor allocates an offscreen buffer for the previous frame. In either case you may use this function to assign a new previous frame buffer.

Special Considerations

This is a very specialized function; your application should not need to call it under most circumstances.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetCSequenceQuality

Adjusts the spatial or temporal quality for the current sequence.

OSErr SetCSequenceQuality (
   ImageSequence seqID,
   CodecQ spatialQuality,
   CodecQ temporalQuality
);

Parameters

seqID

The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

spatialQuality

A constant (see below) that specifies the desired compressed image quality. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

temporalQuality

A constant (see below) that specifies the desired sequence temporal quality. This parameter governs the level of compression you desire with respect to information between successive frames in the sequence. Set this parameter to 0 to prevent the compressor from applying temporal compression to the sequence.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

You originally set the default spatial and temporal quality values for a sequence with CompressSequenceBegin. The new quality parameters take effect with the next frame in the sequence.

Special Considerations

If you change the quality settings while processing an image sequence, you affect the maximum image size that you may receive during sequence compression. Consequently, you should call GetMaxCompressionSize after you change the quality settings. If the maximum size has increased, you should reallocate your image buffers to accommodate the larger image size.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceAccuracy

Adjusts the decompression accuracy for the current sequence.

OSErr SetDSequenceAccuracy (
   ImageSequence seqID,
   CodecQ accuracy
);

Parameters

seqID

The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

accuracy

A constant (see below) that specifies the accuracy desired in the decompressed image. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The accuracy parameter governs how precisely the decompressor decompresses the image data. Some decompressors may choose to ignore some image data to improve decompression speed. A new accuracy value takes effect with the next frame in the sequence.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceDataProc

Assigns a data-loading function to a sequence.

OSErr SetDSequenceDataProc (
   ImageSequence seqID,
   ICMDataProcRecordPtr dataProc,
   long bufferSize
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
dataProc: A pointer to an ICMDataProcRecord structure. If the data stream is not all in memory when your program calls DecompressSequenceFrame, the decompressor calls an ICMDataProc callback that you provide, which loads more compressed data. If you have not provided such a data-loading function, or if you want the decompressor to stop using your data-loading function, set this parameter to NIL. In this case, the entire image must be in memory at the location specified by the data parameter to DecompressSequenceFrame.
bufferSize: The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

Data-loading functions allow decompressors to work with images that cannot fit in memory. During the decompression operation the decompressor calls the data-loading function whenever it has exhausted its supply of compressed data.

Special Considerations

There is no parameter to the DecompressSequenceBegin function that allows you to assign a data-loading function to a sequence.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceFlags

Sets data loading flags.

OSErr SetDSequenceFlags (
   ImageSequence seqID,
   long flags,
   long flagsMask
);

Parameters

seqID

The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

flags

Flags (see below) for data loading. See these constants:

codecDSequenceSingleField

flagsMask

Use this field to preserve the state of any flags you do not wish to alter. If a flag (see below) is set in this field, and is not set in the flags parameter, it will not be changed from its current setting.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 4.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceMask

Assigns a clipping region to a sequence.

OSErr SetDSequenceMask (
   ImageSequence seqID,
   RgnHandle mask
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
mask: A handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you want to stop masking, set this parameter to NIL. The new region takes effect with the next frame in the sequence.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The decompressor draws only that portion of the decompressed image that lies within the specified clipping region. You should not dispose of this region until the Image Compression Manager is finished with the sequence, or until you set the mask either to NIL or to a different region by calling this function again.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceMatrix

Assigns a mapping matrix to a sequence.

OSErr SetDSequenceMatrix (
   ImageSequence seqID,
   MatrixRecordPtr matrix
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
matrix: A MatrixRecord structure that specifies how to transform the image during decompression. You can use this structure to translate or scale the image during decompression. To set the matrix to identity, pass NIL in this parameter. The new matrix takes effect with the next frame in the sequence.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The decompressor uses the matrix to create special effects with the decompressed image, such as translating or scaling the image.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceMatte

Assigns a blend matte to a sequence.

OSErr SetDSequenceMatte (
   ImageSequence seqID,
   PixMapHandle matte,
   const Rect *matteRect
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
matte: A handle to a PixMap structure that contains a blend matte. You can use the blend matte to cause the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported pixel depth; the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If you want to turn off the blend matte, set this parameter to NIL.
matteRect: A pointer to a Rect structure that defines the boundary rectangle for the matte. The decompressor uses only that portion of the matte that lies within the specified rectangle. This rectangle must be the same size as the source rectangle you specify with SetDSequenceSrcRect or with the srcRect parameter to DecompressSequenceBegin. To use the matte's PixMap structure bounds as the boundary rectangle, pass NIL in this parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The decompressor uses the matte to blend the decompressed image into the destination pixel map. The new matte and matte boundary rectangle take effect with the next frame in the sequence. You should not dispose of the matte until the Image Compression Manager has finished with the sequence.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceNonScheduledDisplayDirection

Sets the display direction for a decompress sequence.

OSErr SetDSequenceNonScheduledDisplayDirection (
   ImageSequence sequence,
   Fixed rate
);

Parameters

sequence: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
rate: The display direction to be set. Negative values represent backward display and positive values represent forward display.

Return Value

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

Availability

Available in OS X v10.4 and later.

Declared In

ImageCompression.h

SetDSequenceNonScheduledDisplayTime

Sets the display time for a decompression sequence.

OSErr SetDSequenceNonScheduledDisplayTime (
   ImageSequence sequence,
   TimeValue64 displayTime,
   TimeScale displayTimeScale,
   UInt32 flags
);

Parameters

sequence: Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.
displayTime: The display time to be set.
displayTimeScale: The display time scale to be set.
flags: Not used; set to 0.

Return Value

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

Availability

Available in OS X v10.4 and later.

Declared In

ImageCompression.h

SetDSequenceSrcRect

Defines the portion of an image to decompress.

OSErr SetDSequenceSrcRect (
   ImageSequence seqID,
   const Rect *srcRect
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
srcRect: A pointer to a Rect structure that defines the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by (0,0) and ((**desc).width,(**desc).height), where desc refers to the ImageDescription structure you supply to DecompressSequenceBegin. If the srcRect parameter is NIL, the rectangle is set to the Rect structure in the ImageDescription.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

The decompressor acts on that portion of the compressed image that lies within this rectangle. A new source rectangle takes effect with the next frame in the sequence.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceTimeCode

Sets the timecode value for a frame that is about to be decompressed.

OSErr SetDSequenceTimeCode (
   ImageSequence seqID,
   void *timeCodeFormat,
   void *timeCodeTime
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
timeCodeFormat: A pointer to a TimeCodeDef structure. You provide the appropriate timecode definition information for the next frame to be decompressed.
timeCodeTime: A pointer to a TimeCodeRecord structure. You provide the appropriate time value for the next frame in the current sequence.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

QuickTime's video media handler uses this function to set the timecode information for a movie. When a movie that contains timecode information starts playing, the media handler calls this function as it processes the movie's first frame. The Image Compression Manager passes the timecode information straight through to the image decompressor component. That is, the Image Compression Manager does not make a copy of any of this timecode information. As a result, you must make sure that the data referred to by the timeCodeFormat and timeCodeTime parameters is valid until the next decompression operation completes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetDSequenceTransferMode

Sets the mode used when drawing a decompressed image.

OSErr SetDSequenceTransferMode (
   ImageSequence seqID,
   short mode,
   const RGBColor *opColor
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
mode: A constant (see below) that specifies the transfer mode to be used when drawing the decompressed image. See also Graphics Transfer Modes. See these constants:
opColor: Contains a pointer to the color for use in addPin, subPin, blend, and transparent operations. The Image Compression Manager passes this color to QuickDraw as appropriate. If NIL, the opcolor is left unchanged.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

For any given sequence, the default opColor value is 50 percent gray and the default mode is ditherCopy. The new mode takes effect with the next frame in the sequence.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetIdentityMatrix

Sets the contents of a matrix so that it performs no transformation.

void SetIdentityMatrix (
   MatrixRecord *matrix
);

Parameters

matrix: A pointer to a MatrixRecord structure. The function updates the contents of this matrix so that the matrix describes the identity matrix.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetImageDescriptionCTable

Updates the custom ColorTable structure for an image.

OSErr SetImageDescriptionCTable (
   ImageDescriptionHandle desc,
   CTabHandle ctable
);

Parameters

desc: Contains a handle to the appropriate ImageDescription structure. The function updates the size of the structure to accommodate the new ColorTable structure and removes the old color table, if one is present.
ctable: A handle to the new ColorTable structure. The function loads this color table into the ImageDescription structure referred to by the desc parameter. Set this parameter to NIL to remove a ColorTable structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function does not change the image data, just the color table.

Special Considerations

This function is rarely used. Typically, you supply the color table when your application compresses an image, and the Image Compression Manager stores the ColorTable structure with the image.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SetSequenceProgressProc

Installs a progress procedure for a sequence.

OSErr SetSequenceProgressProc (
   ImageSequence seqID,
   ICMProgressProcRecord *progressProc
);

Parameters

seqID: The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.
progressProc: A pointer to an ICMProgressProcRecord structure.

Return Value

See Error Codes. Returns noErr if there is no error.

Discussion

This function allows you to set an ICMProgressProc callback for a compression or decompression sequence, just as you can set a progress procedure when compressing or decompressing a still image.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

SkewMatrix

Modifies the contents of a matrix so that it defines a skew transformation.

void SkewMatrix (
   MatrixRecord *m,
   Fixed skewX,
   Fixed skewY,
   Fixed aboutX,
   Fixed aboutY
);

Parameters

m: A pointer to the matrix for this operation. The SkewMatrix function updates the contents of the MatrixRecord structure so that it defines a skew operation; it concatenates the respective transformations onto whatever was initially in the matrix structure. You specify the magnitude and direction of the skew operation with the skewX and skewY parameters. You specify an anchor point with the aboutX and aboutY parameters.
skewX: The skew value to be applied to x coordinates.
skewY: The skew value to be applied to y coordinates.
aboutX: The x coordinate of the anchor point.
aboutY: The y coordinate of the anchor point.

Discussion

A skew operation alters the display of an element along one dimension. For example, converting a rectangle into a parallelogram is a skew operation.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

StdPix

Extends the grafProcs field of the CGrafPort structure to support compressed data, mattes, matrices, and pixel maps, letting you intercept image data in compressed form before it is decompressed and displayed.

void StdPix (
   PixMapPtr src,
   const Rect *srcRect,
   MatrixRecordPtr matrix,
   short mode,
   RgnHandle mask,
   PixMapPtr matte,
   const Rect *matteRect,
   short flags
);

Parameters

src

Contains a pointer to a PixMap structure containing the image to draw. Use GetCompressedPixMapInfo to retrieve information about this structure.

srcRect

Points to a Rect structure that defines the portion of the image to display. This rectangle must lie within the boundary rectangle of the compressed image or within the source image. If this parameter is set to NIL, the entire image is displayed.

matrix

Contains a pointer to a MatrixRecord structure that specifies the mapping of the source rectangle to the destination. It is a fixed-point, 3-by-3 matrix.

mode

Specifies the transfer mode for the operation; see Graphics Transfer Modes. Note that this parameter also controls the accuracy of any decompression operation that may be required to display the image. If bit 7 (0x80) of the mode parameter is set to 1, the StdPix function sets the decompression accuracy to codecNormalQuality. If this bit is set to 0, the function sets the accuracy to codecHighQuality.

mask

Contains a handle to a clipping region in the destination coordinate system. If specified, the compressor applies this mask to the destination image. If there is no mask, this parameter is set to NIL.

matte

Points to a PixMap structure that contains a blend matte. The blend matte causes the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported pixel depth; the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If there is no matte, this parameter is set to NIL

matteRect

Contains a pointer to a Rect structure that defines a portion of the blend matte to apply. This parameter is set to NIL if there is no matte or if the entire matte is to be used.

flags

Contains control flags (see below). See these constants:

callOldBits
callStdBits
noDefaultOpcodes

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

TransformFixedPoints

Transforms a set of fixed points through a specified matrix.

OSErr TransformFixedPoints (
   const MatrixRecord *m,
   FixedPoint *fpt,
   long count
);

Parameters

m: A pointer to the transformation matrix for this operation.
fpt: A pointer to the first fixed point to be transformed.
count: The number of fixed points to be transformed. These points must be stored immediately following the point specified by the fpt parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

TransformFixedRect

Transforms the upper-left and lower-right points of a rectangle through a matrix that is specified by fixed points.

Boolean TransformFixedRect (
   const MatrixRecord *m,
   FixedRect *fr,
   FixedPoint *fpp
);

Parameters

m: A pointer to the matrix for this operation.
fr: A pointer to the FixedRect structure that defines the rectangle to be transformed. TransformFixedRect returns the updated coordinates into the structure referred to by this parameter. If the resulting rectangle has been rotated or skewed (that is, the transformation involves operations other than scaling and translation), the function sets the returned Boolean value to FALSE and returns the coordinates of the boundary box of the transformed rectangle. The function then updates the points specified by the fpp parameter to contain the coordinates of the four corners of the transformed rectangle.
fpp: A pointer to an array of four fixed points. The function returns the coordinates of the four corners of the rectangle after the transformation operation. If you do not want this information, set this parameter to NIL.

Return Value

If the resulting rectangle has been rotated or skewed (that is, the transformation involves operations other than scaling and translation), the function returns FALSE, updates the rectangle specified by the fr parameter to define the boundary box of the resulting rectangle, and places the coordinates of the corners of the resulting rectangle in the points specified by the fpp parameter. If the transformed rectangle and its boundary box are the same, the function returns TRUE.

Discussion

This function does not return any error codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

TransformPoints

Transforms a set of QuickDraw points through a specified matrix.

OSErr TransformPoints (
   const MatrixRecord *mp,
   Point *pt1,
   long count
);

Parameters

mp: A pointer to the transformation matrix for this operation.
pt1: A pointer to the first QuickDraw point to be transformed.
count: The number of QuickDraw points to be transformed. These points must be stored immediately following the point specified by the pt1 parameter.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

TransformRect

Transforms the upper-left and lower-right points of a rectangle through a specified matrix.

Boolean TransformRect (
   const MatrixRecord *m,
   Rect *r,
   FixedPoint *fpp
);

Parameters

m: The matrix for this operation.
r: A pointer to the Rect structure that defines the rectangle to be transformed. The function returns the updated coordinates into the structure referred to by this parameter.
fpp: A pointer to an array of four fixed points. The TransformRect function returns the coordinates of the four corners of the rectangle after the transformation operation. If you do not want this information, set this parameter to NIL.

Return Value

If the resulting rectangle has been rotated or skewed (that is, the transformation involves operations other than scaling and translation), the function returns FALSE, updates the rectangle specified by the r parameter to define the boundary box of the resulting rectangle, and places the coordinates of the corners of the resulting rectangle in the points specified by the fpp parameter. If the transformed rectangle and its boundary box are the same, the function returns TRUE.

Discussion

This function does not return any error codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

TransformRgn

Applies a specified matrix to a region.

OSErr TransformRgn (
   MatrixRecordPtr matrix,
   RgnHandle rgn
);

Parameters

matrix: Points to the matrix for this operation. The TransformRgn function currently supports only translation and scaling operations.
rgn: A handle to the MacRegion structure to be transformed. The function transforms each point in the region according to the specified matrix

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

TranslateMatrix

Adds a translation value to a specified matrix.

void TranslateMatrix (
   MatrixRecord *m,
   Fixed deltaH,
   Fixed deltaV
);

Parameters

m: A pointer to the MatrixRecord structure for this operation.
deltaH: The value to be added to the x coordinate translation value.
deltaV: The value to be added to the y coordinate translation value.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

TrimImage

Adjusts a compressed image to the boundaries defined by a specified rectangle.

ComponentResult ADD_IMAGECODEC_BASENAME() TrimImage

Parameters

desc: A handle to the ImageDescription structure that describes the compressed image. On return, the compressor updates this structure to describe the resized image.
inData: A pointer to the compressed image data. This pointer must contain a 32-bit clean address. If the entire compressed image cannot be stored at this location, your application may provide an ICMDataProc callback through the dataProc parameter.
inBufferSize: The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, this parameter is ignored.
dataProc: A pointer to an ICMDataProcRecord structure that references an ICMDataProc callback. If there is not enough memory to store the compressed image, the compressor calls a function you provide that loads more compressed data. If you have not provided such a data-loading function, set this parameter to NIL. In this case, the compressor expects that the entire compressed image is in the memory location specified by the inData parameter
outData: A pointer to a buffer to receive the trimmed image. The Image Compression Manager places the actual size of the resulting image into the dataSize field of the ImageDescription structure referred to by the desc parameter. This pointer must contain a 32-bit clean address. Your application should create a destination buffer at least as large as the source image. If there is not sufficient memory to store the compressed image, you may choose to write the compressed data to mass storage during the compression operation, in which case you use the flushProc parameter to identify your data-unloading function to the compressor.
outBufferSize: The size of the buffer to be used by the data-unloading function specified by the flushProc parameter. If you have not specified a data-unloading function, this parameter is ignored.
flushProc: A pointer to an ICMFlushProcRecord structure that references an ICMFlushProc callback. If there is not enough memory to store the compressed image, the compressor calls a function you provide that unloads some of the compressed data. If you have not provided such a data-unloading function, set this parameter to NIL. In this case, the compressor writes the entire compressed image into the memory location specified by the data parameter
trimRect: A pointer to a Rect structure that defines the desired image dimensions. On return, the function adjusts the rectangle values so that they refer to the same rectangle in the result image. This is necessary whenever data is removed from the beginning or left side of the image.
progressProc: A pointer to an ICMProgressProcRecord structure that references an ICMProgressProc callback. During the operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided such a progress function, set this parameter to NIL. If you pass a value of -1, you obtain a standard progress function.

Return Value

See Error Codes. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

UnsignedFixMulDiv

Performs multiplications and divisions on unsigned fixed-point numbers.

Fixed UnsignedFixMulDiv (
   Fixed src,
   Fixed mul,
   Fixed divisor
);

Parameters

src: The value to be multiplied or divided.
mul: The multiplier to be applied to the value in the src parameter. Pass 0x00010000 if you do not want to multiply.
divisor: The divisor to be applied to the value in the src parameter. Pass 0x00010000 if you do not want to divide.

Return Value

The fixed-point number that is the value of the src parameter, multiplied by the value in the mul parameter and divided by the value in the divisor parameter. The function performs both operations before returning.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

Callbacks

Data Types

CodecComponent

Represents a type used by the Compression and Decompression API.

typedef Component CodecComponent;

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

CodecNameSpecList

Contains a list of CodecNameSpec structures.

struct CodecNameSpecList {
   short            count;
   CodecNameSpec    list[1];
};

Fields

count: Indicates the number of compressor name structures contained in the list array that follows.
list: Contains an array of compressor name structures. Each structure corresponds to one compressor component or type that meets the selection criteria your application specifies when it calls GetCodecNameList.

Discussion

See also DisposeCodecNameList and GetCodecNameList.

Declared In

ImageCompression.h

CodecNameSpecListPtr

Represents a type used by the Compression and Decompression API.

typedef CodecNameSpecList * CodecNameSpecListPtr;

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ConstStrFileNameParam

Represents a type used by the Compression and Decompression API.

typedef ConstStr255Param ConstStrFileNameParam;

Availability

Available in OS X v10.0 through OS X v10.7.

Declared In

MacTypes.h

DataRateParams

Communicates information to compressors that can constrain compressed data to a specific data rate.

struct DataRateParams {
   long      dataRate;
   long      dataOverrun;
   long      frameDuration;
   long      keyFrameRate;
   CodecQ    minSpatialQuality;
   CodecQ    minTemporalQuality;
};

Fields

dataRate

Specifies the bytes per second to which the data rate must be constrained.

dataOverrun

Indicates the current number of bytes above or below the desired data rate. A value of 0 means that the data rate is being met exactly. If your application doesn't know the data overrun, it should set this field to 0.

frameDuration

Specifies the duration of the current frame in milliseconds.

keyFrameRate

Indicates the frequency of key frames. This frequency is normally identical to the key frame rate passed to the CompressSequenceBegin.

minSpatialQuality

A constant (see below) that specifies the minimum spatial quality the compressor should use to meet the requested data rate. See these constants:

codecMinQuality
codecLowQuality
codecNormalQuality
codecHighQuality
codecMaxQuality
codecLosslessQuality

minTemporalQuality

A constant (see below) that specifies the minimum temporal quality the compressor should use to meet the requested data rate.

Discussion

The CodecQ data type defines a field that identifies the quality characteristics of a given image or sequence. Note that individual components may not implement all the quality levels shown here. In addition, components may implement other quality levels in the range from codecMinQuality to codecMaxQuality. Relative quality should scale within the defined value range. Values above codecLosslessQuality are reserved for use by individual components.

Declared In

ImageCompression.h

DataRateParamsPtr

Represents a type used by the Compression and Decompression API.

typedef DataRateParams * DataRateParamsPtr;

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

DecompressorComponent

Represents a type used by the Compression and Decompression API.

typedef Component DecompressorComponent;

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

FixedRect

Defines the size and location of a rectangle in fixed-point numbers.

struct FixedRect {
   Fixed    left;
   Fixed    top;
   Fixed    right;
   Fixed    bottom;
};

Fields

left: The x coordinate of the upper-left corner of the rectangle.
top: The y coordinate of the upper-left corner of the rectangle.
right: The x coordinate of the lower-right corner of the rectangle.
bottom: The y coordinate of the lower-right corner of the rectangle.

Discussion

Declared In

ImageCompression.h

Fract

Represents a type used by the Compression and Decompression API.

typedef long Fract;

Availability

Available in OS X v10.0 and later.

Declared In

IOMacOSTypes.h

ICMPixelFormatInfo

Defines a pixel format.

struct ICMPixelFormatInfo {
   long             size;
   unsigned long    formatFlags;
   short            bitsPerPixel[14];
};

Fields

size

The size of this structure. This quantity isn't necessarily equal to sizeof(ICMPixelFormatInfo) because it is dependent on whether the pixel format is chunky or planar, and, if planar, the number of components (see below).

formatFlags

A constant (see below) indicating the pixel format. See these constants:

kICMPixelFormatIsPlanarMask
kICMPixelFormatIsIndexed
kICMPixelFormatIsSupportedByQD

bitsPerPixel

An array that defines the number of bits for each component. The element bitsPerPixel[0] contains the number of bits for the first component, bitsPerPixel[1] the number of bits for the second component, etc. The meaning of this parameter depends on the format flag (see below).

Discussion

You can represent a format that has from 1 to 14 discrete components using this data structure. For ARGB, there are 4 components. RGB without an alpha channel has 3 components. A component count of 15 is reserved for future expansion.

See also ICMGetPixelFormatInfo and ICMSetPixelFormatInfo.

Declared In

ImageCompression.h

ICMPixelFormatInfoPtr

Represents a type used by the Compression and Decompression API.

typedef ICMPixelFormatInfo * ICMPixelFormatInfoPtr;

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageFieldSequence

Represents a type used by the Compression and Decompression API.

typedef long ImageFieldSequence;

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageSequenceDataSource

Represents a type used by the Compression and Decompression API.

typedef long ImageSequenceDataSource;

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

ImageTranscodeSequence

Represents a type used by the Compression and Decompression API.

typedef long ImageTranscodeSequence;

Availability

Available in OS X v10.0 and later.

Declared In

ImageCompression.h

OpenCPicParams

Specifies resolutions when creating images.

struct OpenCPicParams {
   Rect     srcRect;
   Fixed    hRes;
   Fixed    vRes;
   short    version;
   short    reserved1;
   long     reserved2;
};

Fields

srcRect: The optimal bounding rectangle for the resolution indicated by the hRes and vRes fields. To display a picture at a resolution other than that specified in the the hRes and vRes fields, your application should compute an appropriate destination rectangle by scaling the image's width and height by the destination resolution divided by the source resolution.
hRes: The best horizontal resolution for the picture. A value of 0x0048000 specifies a horizontal resolution of 72 dpi.
vRes: The best vertical resolution for the picture. A value of 0x0048000 specifies a vertical resolution of 72 dpi.
version: Always set this field to -2.
reserved1: Reserved; set to 0.
reserved2: Reserved; set to 0.

Discussion

Declared In

ImageCompression.h

QHdr

A Windows queue header structure.

struct QHdr {
   short       qFlags;
   short       pad;
   long        MutexID;
   QElemPtr    qHead;
   QElemPtr    qTail;
};

Fields

qFlags: Undocumented
pad: Unused.
MutexID: Undocumented
qHead: Undocumented
qTail: Undocumented

Discussion

See also CDSequenceSetSourceDataQueue, Dequeue, Enqueue, InitializeQHdr, and TerminateQHdr.

Declared In

ImageCompression.h

QHdrPtr

Represents a type used by the Compression and Decompression API.

typedef QHdr * QHdrPtr;

Availability

Available in OS X v10.0 and later.

Declared In

OSUtils.h

Constants

StdPix Values

Constants passed to StdPix.

enum {
   callStdBits                   = 1,
   callOldBits                   = 2,
   noDefaultOpcodes              = 4
};

Declared In

ImageCompression.h

DSequence Flags

Constants that represent <codeVoice>DSequence</codeVoice> flags.

enum {
   codecDSequenceDisableOverlaySurface = (1L << 5),
   codecDSequenceSingleField     = (1L << 6),
   codecDSequenceBidirectionalPrediction = (1L << 7),
   codecDSequenceFlushInsteadOfDirtying = (1L << 8),
   codecDSequenceEnableSubPixelPositioning = (1L << 9),
   codecDSequenceDeinterlaceFields = (1L << 10)
};

Declared In

ImageCompression.h

FCompressImage Values

Constants passed to FCompressImage.

enum {
   codecFlagUseImageBuffer       = (1L << 0), /* decompress*/
   codecFlagUseScreenBuffer      = (1L << 1), /* decompress*/
   codecFlagUpdatePrevious       = (1L << 2), /* compress*/
   codecFlagNoScreenUpdate       = (1L << 3), /* decompress*/
   codecFlagWasCompressed        = (1L << 4), /* compress*/
   codecFlagDontOffscreen        = (1L << 5), /* decompress*/
   codecFlagUpdatePreviousComp   = (1L << 6), /* compress*/
   codecFlagForceKeyFrame        = (1L << 7), /* compress*/
   codecFlagOnlyScreenUpdate     = (1L << 8), /* decompress*/
   codecFlagLiveGrab             = (1L << 9), /* compress*/
   codecFlagDiffFrame            = (1L << 9), /* decompress*/
   codecFlagDontUseNewImageBuffer = (1L << 10), /* decompress*/
   codecFlagInterlaceUpdate      = (1L << 11), /* decompress*/
   codecFlagCatchUpDiff          = (1L << 12), /* decompress*/
   codecFlagSupportDisable       = (1L << 13), /* decompress*/
   codecFlagReenable             = (1L << 14) /* decompress*/
};

Constants

codecFlagUpdatePrevious

Controls whether your compressor updates the previous image during compression. This flag is only used with sequences that are being temporally compressed. If this flag is set to 1, your compressor should copy the current frame into the previous frame buffer at the end of the frame-compression sequence. Use the source image.

Available in OS X v10.0 and later.

Declared in ImageCompression.h.

codecFlagWasCompressed

Indicates to your compressor that the image to be compressed has been compressed before. This information may be useful to compressors that can compensate for the image degradation that may otherwise result from repeated compression and decompression of the same image. This flag is set to 1 to indicate that the image was previously compressed. This flag is set to 0 if the image was not previously compressed.

Available in OS X v10.0 and later.

Declared in ImageCompression.h.

codecFlagUpdatePreviousComp

Controls whether your compressor updates the previous image buffer with the compressed image. This flag is only used with temporal compression. If this flag is set to 1, your compressor should update the previous frame buffer at the end of the frame-compression sequence, allowing your compressor to perform frame differencing against the compression results. Use the image that results from the compression operation. If this flag is set to 0, your compressor should not modify the previous frame buffer during compression.

Available in OS X v10.0 and later.

Declared in ImageCompression.h.

codecFlagLiveGrab

Indicates whether the current sequence results from grabbing live video. When working with live video, your compressor should operate as quickly as possible and disable any additional processing, such as compensation for previously compressed data. This flag is set to 1 when you are compressing from a live video source.

Available in OS X v10.0 and later.

Declared in ImageCompression.h.

codecFlagDiffFrame

Decompress.

Available in OS X v10.0 and later.

Declared in ImageCompression.h.

codecFlagSupportDisable

Decompress.

Available in OS X v10.0 and later.

Declared in ImageCompression.h.

Declared In

ImageCompression.h

Color Modes

Constants that represent color modes.

enum {
   defaultDither                 = 0,
   forceDither                   = 1,
   suppressDither                = 2,
   useColorMatching              = 4
};
enum {
   graphicsModeStraightAlpha     = 256,
   graphicsModePreWhiteAlpha     = 257,
   graphicsModePreBlackAlpha     = 258,
   graphicsModeComposition       = 259,
   graphicsModeStraightAlphaBlend = 260,
   graphicsModePreMulColorAlpha  = 261,
   graphicsModePerComponentAlpha = 272
};
enum {
   kQTTIFFUserDataPrefix         = 0x74690000, /* Added to some tag values in TIFF IFDs to generate user data codes.  (0x7469 is 'ti'.) */
   /* For example,
   YCbCrPositioning is tag x0213,
   so its user data code is 0x74690213. */
   kQTTIFFExifUserDataPrefix     = 0x65780000, /* Added to tag values in Exif IFDs to generate user data codes.  (0x6578 is 'ex'.) */
   /* For example,
   DateTimeOriginal is tag x9003,
   so its user data code is 0x65789003. */
   kQTTIFFExifGPSUserDataPrefix  = 0x67700000, /* Added to tag values in Exif GPS IFDs to generate user data codes.  (0x6770 is 'gp'.) */
   /* For example,
   GPSAltitude is tag x0006,
   so its user data code is 0x6770006. */
   kQTAlphaMode                  = 'almo', /* UInt32; eg,
   graphicsModeStraightAlpha or graphicsModePreBlackAlpha */
   kQTAlphaModePreMulColor       = 'almp', /* RGBColor; used if kQTAlphaMode is graphicsModePreMulColorAlpha */
   kUserDataIPTC                 = 'iptc'
};

Constants

kQTTIFFUserDataPrefix

Added to some tag values in TIFF IFDs to generate user data codes. (0x7469 is 'ti'.).

Available in OS X v10.1 and later.

Declared in ImageCompression.h.

kQTTIFFExifUserDataPrefix

Added to tag values in Exif IFDs to generate user data codes. (0x6578 is 'ex'.).

Available in OS X v10.1 and later.

Declared in ImageCompression.h.

kQTTIFFExifGPSUserDataPrefix

Added to tag values in Exif GPS IFDs to generate user data codes. (0x6770 is 'gp'.).

Available in OS X v10.1 and later.

Declared in ImageCompression.h.

kQTAlphaMode

UInt32; for example, graphicsModeStraightAlpha or graphicsModePreBlackAlpha.

Available in OS X v10.1 and later.

Declared in ImageCompression.h.

kQTAlphaModePreMulColor

RGBColor; used if kQTAlphaMode is graphicsModePreMulColorAlpha.

Available in OS X v10.1 and later.

Declared in ImageCompression.h.

Declared In

ImageCompression.h

GetGraphicsImporterForFileWithFlags Values

Constants passed to GetGraphicsImporterForFileWithFlags.

enum {
   kDontUseValidateToFindGraphicsImporter = 1L << 0
};

Declared In

ImageCompression.h

QTSetPixMapPtrRequestedGammaLevel Values

Constants passed to QTSetPixMapPtrRequestedGammaLevel.

enum {
   kQTUsePlatformDefaultGammaLevel = 0,  /* When decompressing into this PixMap,
   gamma-correct to the platform's standard gamma. */
   kQTUseSourceGammaLevel        = -1L,  /* When decompressing into this PixMap,
   don't perform gamma-correction. */
   kQTCCIR601VideoGammaLevel     = 0x00023333 /* 2.2,
   standard television video gamma.*/
};

Constants

kQTCCIR601VideoGammaLevel

Gamma 2.2, for ITU-R BT.601 based video.

Available in OS X v10.0 and later.

Declared in ImageCompression.h.

Declared In

ImageCompression.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.