ICM Functions, Data Types, and Constants
This chapter describes the various functions, data types, and constants your application can take advantage of in working with the Image Compression Manager.
In this section:
Making Thumbnail Pictures
Constraining Compressed Data
The Compressor Information Structure
The Compressor Name Structure
Controlling Hardware Scaling
Working With the StdPix Function
Aligning Windows
Alignment Functions
Working With Graphics Devices and Graphics Worlds
Data-Loading Functions
Data-Unloading Functions
Progress Functions
Completion Functions
Constants
Image Compression Manager Function Control Flags
Making Thumbnail Pictures
Thumbnail pictures are useful for creating small, representative images of a source image. You can use thumbnails when you create previews for files that contain image data (for more information about file previews, see the chapter “Movie Toolbox” in this book).
You can create thumbnails from pictures, picture files, or pixel maps; use the MakeThumbnailFromPicture, MakeThumbnailFromPictureFile, or MakeThumbnailFromPixMap function, as appropriate.
Constraining Compressed Data
The Image Compression Manager provides two functions and a data structure that allow your application to communicate information to compressors that can constrain compressed data to a specific data rate. Compressors indicate that they can constrain the data rate by setting the following flag in their compressor information structure:
#define codecInfoDoesRateConstrain(1L<<23) |
For details, see The Compressor Information Structure.
The DataRateParams data type defines the data rate parameters structure.
typedef struct { |
long dataRate; /* bytes per second */ |
long dataOverrun; /* number of bytes outside |
rate */ |
long frameDuration; /* in milliseconds */ |
long keyFrameRate; /* frequency of key frames */ |
CodecQ minSpatialQuality; /* minimum spatial quality */ |
CodecQ minTemporalQuality; /* minimum temporal quality */ |
} DataRateParams; |
typedef DataRateParams *DataRateParamsPtr; |
Field |
Description |
|---|---|
|
Specifies the bytes per second to which the data rate must be constrained. |
|
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. |
|
Specifies the duration of the current frame in milliseconds. |
|
Indicates the frequency of key frames. This frequency is normally identical to the key frame rate passed to the |
|
Specifies the minimum spatial quality the compressor should use to meet the requested data rate. |
|
Indicates the minimum temporal quality the compressor should use to meet the requested data rate. |
See Compression Quality Constants for available values of the minSpatialQuality and minTemporalQuality fields.
The SetCSequenceDataRateParams function allows you to specify the parameters in this structure and the GetCSequenceDataRateParams function allows you to retrieve the parameters.
The Compressor Information Structure
Your application can retrieve information describing the capabilities of compressors with the GetCodecInfo function. The CodecInfo data type defines the format of the compressor information structure.
/* compressor information structure */ |
struct CodecInfo { |
Str31 typeName; /* compression algorithm (codec type) */ |
short version; /* version supported by component */ |
short revisionLevel; /* version assigned by developer */ |
long vendor; /* developer of component */ |
long decompressFlags; /* decompression capability flags */ |
long compressFlags; /* compression capability flags */ |
long formatFlags; /* compression format flags */ |
unsigned char compressionAccuracy; |
/* relative accuracy of this algorithm */ |
unsigned char decompressionAccuracy; |
/* relative accuracy of this algorithm */ |
unsigned short compressionSpeed; |
/* relative compression speed */ |
unsigned short decompressionSpeed; |
/* relative decompression speed */ |
unsigned char compressionLevel; |
/* relative compression of component */ |
char resvd; /* reserved--set to 0 */ |
short minimumHeight; /* minimum image height for component */ |
short minimumWidth; /* minimum image width for component */ |
short decompressPipelineLatency; |
/* in milliseconds (asynchronous) */ |
short compressPipelineLatency; |
/* in milliseconds (asynchronous) */ |
long privateData; /* reserved for use by Apple */ |
}; |
typedef struct CodecInfo CodecInfo; |
Field |
Description |
|---|---|
|
Indicates the compression algorithm used by the component; for example, |
|
Indicates the version of compressed data this component supports. The contents of this field should indicate the most recent version of the compression algorithm that the component can understand. |
|
Indicates the version of the component; for example, |
|
Identifies the developer of the component; for example, |
|
Contains flags that specify the decompression capabilities of the component. Typically, these flags are of interest only to developers of image decompressors. |
|
Contains flags that specify the compression capabilities of the component. Typically, these flags are of interest only to developers of image compressors. |
|
Contains flags that describe the possible format for compressed data produced by this component and the format of compressed files that the component can handle during decompression. Typically, these flags are of interest only to developers of compressor components. |
|
Indicates the relative accuracy of the compression algorithm employed by the component. Valid values for this field range from 0 to 255. A value of 0 means that the accuracy is unknown. Values from 1 to 255 provide a gauge for the relative accuracy of the compression algorithm; higher values indicate better accuracy. The Image Compression Manager examines this field to determine which compressor component can most accurately compress a given image. The |
|
Indicates the relative accuracy of the decompression algorithm employed by the component. Valid values for this field range from 0 to 255. A value of 0 means that the accuracy is unknown. Values from 1 to 255 indicate the relative accuracy of the decompression technique; higher values mean better accuracy. The Image Compression Manager examines this field to determine which decompressor component can most accurately decompress a given image. The |
|
Indicates the relative speed of the component for compression operations. Valid values for this field lie in the range from 0 to 65,535. A value of 0 means that the speed is unknown. Values from 1 to 65,535 correspond to the number of milliseconds the component requires to compress a 320-by-240 pixel image on a Macintosh II computer. The Image Compression Manager examines this field to determine which compressor component can most quickly compress a given image. |
|
Indicates the relative speed of the component for decompression operations. Valid values for this field lie in the range from 0 to 65,535. A value of 0 means that the speed is unknown. Values from 1 to 65,535 correspond to the number of milliseconds the component requires to decompress a 320-by-240 pixel image on a Macintosh II computer. The Image Compression Manager examines this field to determine which compressor component can most quickly decompress a given image. |
|
Indicates the relative compression achieved by this component. Valid values for this field lie in the range from 0 to 255. A value of 0 means that the compression level is unknown. Values from 1 to 255 map to percentage values of relative compression; lower values mean lesser compression. A value of 1 means no compression (0 percent); a value of 255 means maximum compression (100 percent). The Image Compression Manager examines this field to determine which available compressor component will yield the smallest resulting data for a given image. The |
|
Reserved for Apple. This field must be set to 0. |
|
Specifies the height in pixels of the smallest image the component can handle. Together with the |
|
Specifies the width in pixels of the smallest image the component can handle. Together with the |
|
Reserved for future use. This field must be set to 0. |
|
Reserved for future use. This field must be set to 0. |
|
Reserved for use by Apple. This field must be set to 0. |
The Compressor Name Structure
The CodecNameSpec data type defines a compressor name structure.
/* compressor name structure from GetCodecNameList function */ |
struct CodecNameSpec |
{ |
CodecComponent codec; /* component ID for compressor */ |
CodecType cType; /* type identifier for compressor */ |
Str31 typeName; /* string identifier of algorithm */ |
Handle name; /* name of compressor component */ |
}; |
typedef struct CodecNameSpec CodecNameSpec; |
Field |
Description |
|---|---|
|
Uniquely identifies the component or, in some cases, contains a special value that selects all components. If your application requests a list of components, the |
|
Contains the type identifier for the compressor. The value of this field indicates the compression algorithm supported by the component. See the documentation for |
|
Contains a text string in Pascal format that identifies the compression algorithm supported by the component. This string may be used to identify the compression algorithm to the user. The value of this field should correspond to the value of the |
|
Specifies the name of the compressor component. Developers assign these names to uniquely identify their products. This name may be used to identify the component to the user. |
Controlling Hardware Scaling
QuickTime provides three functions that allow applications to zoom a monitor (GDHasScale, GDGetScale, and GDSetScale). These three functions are considered low-level calls (comparable to SetEntries ) that you should use only when playing back QuickTime movies in a controlled environment with no user interaction. Also, because this capability is not present on all computers, applications should not depend on its availability.
These functions provide a standard way for you to access the resizing abilities of a user’s monitor for playback. Effectively, this allows you to have full screen Cinepak playback on low-end Macintosh computers.
Working With the StdPix Function
To allow applications to have access to compressed image data as it is displayed, a graphics function has been added to the grafProcs field of the color graphics port structure (defined by the CGrafPort data type).
The StdPix function extends the current grafProcs field to support compressed data, mattes, and matrices. The new function supports pixel maps and allows you to intercept image data in compressed form before it is decompressed and displayed. For example, you can use the StdPix function to collect compressed image data that is to be processed and printed. In addition, your application can call the StdPix function directly.
The replaced grafProcs field is referred to in the original QuickDraw documentation as the newProc1 field. The standard handler is called StdPix, and you obtain its address by calling QuickDraw’s SetStdCProcs routine. Alternatively, your application can call the StdPix function directly, using the interface described here. Your application can intercept the low-level grafProcs drawing routines just as it would any of the other routines, except that you must call SetStdCProcs to gain access to the standard grafProcs handler.
Note:
QuickDraw’s CopyDeepMask function uses the StdPix function if QuickTime is present.
To work with the control information associated with a compressed image, you can use the SetCompressedPixMapInfo and GetCompressedPixMapInfo functions.
Aligning Windows
This section describes the functions that allow your application to position and drag windows to optimal screen positions based on the depth of the screen. These functions are useful for movie playback performance considerations that depend on where you draw on the screen.
The Image Compression Manager places the windows at an optimal position on the screen by aligning rectangles horizontally on 1-bit and 2-bit screens to multiples of 16 pixels, aligning 4-bit screens to multiples of 8, aligning 8-bit screens to multiples of 4, and aligning 16-bit screens to multiples of 2. (Alignment on 32-bit screens is to multiples of 4 pixels and only occurs on Macintosh computers of class 68040 or greater.) When the alignment rectangle crosses more than one screen, the Image Compression Manager uses the alignment of the strictest screen.
Decompression to non-optimally aligned destinations can reduce performance by as much as 50 percent, so you should use these functions whenever possible.
The alignment behavior provided by these functions is adequate in the vast majority of situations. However, if you need customized alignment behavior (for example, justification specifications geared to particular video hardware), you can use the application-defined function described in Alignment Functions to override the standard alignment. All the alignment functions provide a parameter in which you can specify a function with customized alignment behavior.
The AlignWindow function enables you to transport a specified window to the nearest optimal alignment position. The DragAlignedWindow function drags the specified window along an optimal alignment grid. The DragAlignedGrayRgn function drags a specified gray region along an optimal alignment grid. The AlignScreenRect function aligns a specified rectangle to the strictest screen that the rectangle intersects.
Alignment Functions
Your application can use alignment functions to specify the alignment in any of the Image Compression Manager’s alignment functions (described in Aligning Windows ). You call the alignment function with a rectangle (defined in global screen coordinates) that has already been aligned using the default behavior. The alignment function then has the option of applying some additional alignment criteria to the rectangle, such as vertical alignment of some form. In the case of supporting hardware alignment, it is the function’s responsibility to determine if the rectangle applies to the relevant device.
The AlignmentProcPtr data type defines a pointer to an alignment function. You assign an alignment function by passing a pointer to the alignment function structure, which identifies the alignment function to the appropriate function.
/* alignment function structure */ |
typedef struct |
{ |
ICMAlignmentUPP alignmentProc; /* pointer to your |
alignment function */ |
long alignmentRefCon; /* reference constant */ |
} ICMAlignmentProcRecord, *ICMAlignmentProcRecordPtr; |
Field |
Description |
|---|---|
|
Points to your alignment function. |
|
Contains a reference constant for use by your alignment function. |
Working With Graphics Devices and Graphics Worlds
This section describes two Image Compression Manager functions that enable you to select graphics devices and create graphics worlds. You can use the GetBestDeviceRect function to select the best available graphics device. The NewImageGWorld function allows you to create a graphics world based on the width, height, depth, and color table of a specified image description structure.
Data-Loading Functions
Compressors use the data-loading and data-unloading functions when working with images that do not fit into memory. The data-loading function supplies compressed data during a decompression operation.
The DataProcPtr data type defines a pointer to a data-loading function. You assign a data-loading function to an image or a sequence by passing a pointer to a structure that identifies the function to the appropriate decompress function.
/* data-loading function structure */ |
typedef struct ICMDataProcRecord ICMDataProcRecord; |
typedef ICMDataProcRecord *ICMDataProcRecordPtr; |
The data-loading function structure contains the following fields:
struct ICMDataProcRecord |
{ |
ICMDataUPP dataProc; /* pointer to data-loading function */ |
long dataRefCon; /* reference constant */ |
}; |
Field |
Description |
|---|---|
|
Contains a pointer to your data-loading function. |
|
Contains a reference constant for use by your data-loading function. |
If your data-loading function returns a nonzero result code, the Image Compression Manager terminates the current operation.
Data-Unloading Functions
Compressors use the data-loading and data-unloading functions when working with images that do not fit into the computer’s memory. The data-unloading function writes compressed data to a storage device during a compression operation.
The FlushProcPtr data type defines a pointer to a data-unloading function.
/* data-unloading structure */ |
typedef struct ICMFlushProcRecord ICMFlushProcRecord; |
typedef ICMFlushProcRecord *ICMFlushProcRecordPtr; |
You assign a data-unloading function to an image or a sequence by passing a pointer to a structure that identifies the function to the appropriate compression function.
The data-unloading function structure contains the following fields:
struct ICMFlushProcRecord |
{ |
ICMFlushUPP flushProc; /* pointer to data-unloading function */ |
long flushRefCon;/* reference constant */ |
}; |
Field |
Description |
|---|---|
|
Contains a pointer to your data-unloading function. |
|
Contains a reference constant for use by your data-unloading function. |
Progress Functions
Compressors and decompressors call progress functions to report on their progress in the current operation. When a component calls your progress function, it supplies you with a number that indicates the completion percentage. This fixed-point value may range from 0.0 through 1.0. Your program can cause the component to terminate the current operation by returning a result code of codecAbortErr.
The Image Compression Manager calls your progress function only during long operations, and it does not call your function more than 30 times per second.
The ProgressProcPtr data type defines a pointer to a progress function. You assign a progress function to an image or a sequence by passing a pointer to a structure that identifies the progress function to the appropriate function.
/* progress function structure */ |
typedef struct ICMProgressProcRecord ICMProgressProcRecord; |
typedef ICMProgressProcRecord *ICMProgressProcRecordPtr; |
The progress function structure contains the following fields:
struct ICMProgressProcRecord |
{ |
ICMProgressUPP progressProc; /* ptr to progress function */ |
long progressRefCon;/* reference constant */ |
}; |
Field |
Description |
|---|---|
|
Contains a pointer to your progress function. |
|
Contains a reference constant for use by your progress function. |
Completion Functions
Compressor components call completion functions when they have finished an asynchronous operation. The component supplies a result code to your completion function. This result code indicates the success or failure of the asynchronous operation. Note that any other result data that may be produced by the asynchronous operation is not valid until the component calls your completion function.
The CompletionProcPtr data type defines a pointer to a completion function. You assign a completion function to an image or a sequence by passing a pointer to a structure that identifies the function to the appropriate function.
typedef struct CompletionProcRecord CompletionProcRecord; |
The completion function structure contains the following fields:
typedef ICMCompletionProcRecord *ICMCompletionProcRecordPtr; |
struct ICMCompletionProcRecord |
{ |
ICMCompletionUPP completionProc; |
/* pointer to completion function */ |
long completionRefCon; |
/* reference constant */ |
}; |
Field |
Description |
|---|---|
|
Contains a pointer to your completion function. Your completion function may be called at interrupt time. Therefore your function may not use Memory Manager functions or other functions that move memory. |
|
Contains a reference constant for use by your completion function. |
Constants
This section describes constants provided by the Image Compression Manager.
/* alpha channel graphics modes */ |
enum { |
graphicsModeStraightAlpha = 256, |
graphicsModePreWhiteAlpha = 257, |
graphicsModePreBlackAlpha = 258, |
graphicsModeStraightAlphaBlend = 260 |
}; |
/* fieldFlags for the ImageFieldSequenceExtractCombine function */ |
enum { |
evenField1ToEvenFieldOut = 1<<0, |
evenField1ToOddFieldOut = 1<<1, |
oddField1ToEvenFieldOut = 1<<2, |
oddField1ToOddFieldOut = 1<<3, |
evenField2ToEvenFieldOut = 1<<4, |
evenField2ToOddFieldOut = 1<<5, |
oddField2ToEvenFieldOut = 1<<6, |
oddField2ToOddFieldOut = 1<<7 |
}; |
Image Compression Manager Function Control Flags
A number of Image Compression Manager functions take control flags that allow your application to exert greater control over the operation. In some cases, the Image Compression Manager returns status information about the results of the function in the same flags field. In general, you need to use only a few of these flags. The function descriptions in the reference section of this chapter indicate the flags that are valid for individual functions.
The CodecFlags data type defines these flag fields.
typedef unsigned short CodecFlags; |
/* Image Compression Manager function control flags */ |
#define codecFlagUseImageBuffer (1L<<0) |
/* (input) use image buffer */ |
#define codecFlagUseScreenBuffer (1L<<1) |
/* (input) use screen buffer */ |
#define codecFlagUpdatePrevious (1L<<2) |
/* (input) update previous buffer */ |
#define codecFlagNoScreenUpdate (1L<<3) |
/* (input) don't update screen */ |
#define codecFlagWasCompressed (1L<<4) |
/*(input) image was compressed */ |
#define codecFlagDontOffscreen (1L<<5) |
/* don't go offscreen */ |
#define codecFlagUpdatePreviousComp (1L<<6) |
/* (input) update previous buffer */ |
#define codecFlagForceKeyFrame (1L<<7) |
/* force key frame from image */ |
#define codecFlagOnlyScreenUpdate |
(1L<<8) |
/* (input) only update screen */ |
#define codecFlagLiveGrab (1L<<9) |
/* (input) grab live video */ |
#define codecFlagUsedNewImageBuffer |
(1L<<14) |
/* (output) new image buffer used */ |
#define codecFlagUsedImageBuffer |
(1L<<15) |
/* (output) decompressor used |
offscreen buffer */ |
enum { |
codecFlagDontUseNewImageBuffer = (1L << 10), |
codecFlagInterlaceUpdate = (1L << 11), |
codecFlagCatchUpDiff = (1L << 12) |
}; |
Constant |
Description |
|---|---|
|
Controls whether the decompressor allocates an offscreen buffer for decompression. If your application sets this flag to 1, the decompressor allocates an offscreen buffer the size of the compressed image. If you set this flag to 0, the decompressor does not use an offscreen image buffer. These image buffers are useful when decompressing sequences that were created using temporal compression. |
|
Controls whether the decompressor allocates an offscreen destination buffer during decompression. If you set this flag to 1, the decompressor allocates an offscreen buffer the size of the destination screen. If you set this flag to 0, the decompressor does not use an offscreen screen buffer. Using a screen buffer helps to reduce tearing that may result when decompressing directly to the screen. |
|
Controls whether the compressor updates the previous image buffer during compression. This flag is only used with sequences that are being temporally compressed. If you set this flag to 1, the compressor copies the current source image into the previous frame buffer at the end of the frame compression. |
|
Controls whether the decompressor updates the screen image. If you set this flag to 1, the decompressor does not write the current frame to the screen, but does write the frame to its offscreen image buffer (if one was allocated). If you set this flag to 0, the decompressor writes the frame to the screen. |
|
Indicates to the 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. Set this flag to 1 to indicate that the image was previously compressed. Set this flag to 0 if the image was not previously compressed. |
|
Controls whether the decompressor uses the offscreen buffer during sequence decompression. This flag is only used with sequences that have been temporally compressed. If this flag is set to 1, the decompressor does not use the offscreen buffer during decompression. Instead, the decompressor returns an error. This allows your application to refill the offscreen buffer. If this flag is set to 0, the decompressor uses the offscreen buffer if appropriate. |
|
Controls whether the compressor updates the previous image buffer with the decompressed image data. This flag is only used with temporal compression and is similar to the |
|
Controls whether the compressor creates a key frame from the current image. This flag is only used with temporal compression. If you set this flag to 1, the compressor makes the current image a key frame. If you set this flag to 0, the compressor decides based on other criteria, such as the key frame rate, whether to create a key frame from the current image. |
|
Controls whether the decompressor decompresses the current frame. If you set this flag to 1, the decompressor writes the contents of its offscreen image buffer to the screen, but does decompress the current frame. If you set this flag to 0, the decompressor decompresses the current frame and writes it to the screen. You can set this flag to 1 only if you have allocated an offscreen image buffer for use by the decompressor. |
|
Indicates to the compressor whether the current sequence results from grabbing live video. When working with live video, compressors operate as quickly as possible and disable some additional processing, such as compensation for previously compressed data. Set this flag to 1 when you are compressing from a live video source; the compressor then operates as quickly as it can. |
|
Indicates to your application that the decompressor used the offscreen image buffer for the first time when it processed this frame. If this flag is set to 1, the decompressor used the image buffer for this frame and this is the first time the decompressor used the image buffer in this sequence. If this flag is set to 0, the decompressor did not use the image buffer. |
|
Indicates to your application that the decompressor used the offscreen image buffer for this frame. If this flag is set to 1, the decompressor used the image buffer. If this flag is set to 0, the decompressor did not use the image buffer. |
|
Forces an error to be returned when a new image buffer would have to be allocated instead of allocating the new buffer. |
|
Updates the screen interlacing even and odd scan lines to reduce tearing artifacts (if the decompressor supports this mode). |
|
Notifies the codec that the currently displayed frame is being displayed late in an attempt to "catch up" to the current frame, which only happens with compression formats that support frame differencing, You can pass this flag to any of the |
© 2005, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-01-10)