Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Compression and Decompression Reference for QuickTime

Framework
Frameworks/QuickTime.framework
Declared in
IOMacOSTypes.h
ImageCodec.k.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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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