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.

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

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 function.

minSpatialQuality

Specifies the minimum spatial quality the compressor should use to meet the requested data rate.

minTemporalQuality

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

typeName

Indicates the compression algorithm used by the component; for example, 'Animation'. This Pascal string may be used to identify the compression algorithm to the user. The string always takes up 32 bytes no matter how long it is. The 32 bytes consist of 31 bytes plus one length byte. Apple Computer's Developer Technical Support group assigns these type names. The value of this field should correspond to the value of the typeName field in the appropriate compressor name structure returned by the GetCodecNameList function.

version

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.

revisionLevel

Indicates the version of the component; for example, 0x00010001 (1.0.1). Developers of compressors assign these version numbers.

vendor

Identifies the developer of the component; for example, 'appl'. The value of this field corresponds to the manufacturer code or application signature assigned to the developer.

decompressFlags

Contains flags that specify the decompression capabilities of the component. Typically, these flags are of interest only to developers of image decompressors.

compressFlags

Contains flags that specify the compression capabilities of the component. Typically, these flags are of interest only to developers of image compressors.

formatFlags

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.

compressionAccuracy

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 compressionAccuracy field can only approximate the accuracy of a compression algorithm. Typically, compression algorithms produce results of varying quality based on a variety of parameters, including image size and content. Since this information is not available until a compression request is issued, a precise measure of accuracy is not possible. However, the value of this field should still give a rough idea of the accuracy of the supported algorithm.

decompressionAccuracy

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 decompressionAccuracy field can only approximate the accuracy of a decompression algorithm. Typically, decompression algorithms produce results of varying quality based on a variety of parameters, including image size and content. Since this information is not available until a decompression request is issued, a precise measure of accuracy is not possible. However, the value of this field should still give a rough idea of the accuracy of the supported algorithm.

compressionSpeed

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.

decompressionSpeed

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.

compressionLevel

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 compressionLevel field can only approximate the effectiveness of a compression algorithm. Typically, compression algorithms produce results of varying quality based on a variety of parameters, including image size and content. Since this information is not available until a compression request is issued, a precise measure of compression is not possible. However, the value of this field should still give a rough idea of the effectiveness of the supported algorithm.

resvd

Reserved for Apple. This field must be set to 0.

minimumHeight

Specifies the height in pixels of the smallest image the component can handle. Together with the minimumWidth field, this field defines the block size for the component. The Image Compression Manager does not issue compression or decompression requests for images smaller than the block size.

minimumWidth

Specifies the width in pixels of the smallest image the component can handle. Together with the minimumHeight field, this field defines the block size for the component. The Image Compression Manager does not issue compression or decompression requests for images smaller than the block size.

decompressPipelineLatency

Reserved for future use. This field must be set to 0.

compressPipelineLatency

Reserved for future use. This field must be set to 0.

privateData

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

codec

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 codec field in each compressor name structure contains the component ID for that compressor. If your application requests a list of component types, the codec field is set to 0 in each compressor name structure.

cType

Contains the type identifier for the compressor. The value of this field indicates the compression algorithm supported by the component. See the documentation for GetCodecNameList for a list of valid values.

typeName

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 typeName field in the appropriate compressor information structure returned by the component in response to a GetCodecInfo function.

name

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.

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

alignmentProc

Points to your alignment function.

alignmentRefCon

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

dataProc

Contains a pointer to your data-loading function.

dataRefCon

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

flushProc

Contains a pointer to your data-unloading function.

flushRefCon

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

progressProc

Contains a pointer to your progress function.

progressRefCon

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

completionProc

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.

completionRefCon

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

codecFlagUseImageBuffer

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.

codecFlagUseScreenBuffer

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.

codecFlagUpdatePrevious

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.

codecFlagNoScreenUpdate

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.

codecFlagWasCompressed

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.

codecFlagDontOffscreen

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.

codecFlagUpdatePreviousComp

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 codecFlagUpdatePrevious flag. As with the codecFlagUpdatePrevious flag, if you set this flag to 1, the compressor updates the previous frame buffer at the end of the frame compression. However, this flag causes the Image Compression Manager to update the frame buffer using an image obtained by decompressing the results of the most recent compression operation, rather than the source image.

codecFlagForceKeyFrame

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.

codecFlagOnlyScreenUpdate

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.

codecFlagLiveGrab

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.

codecFlagUsedNewImageBuffer

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.

codecFlagUsedImageBuffer

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.

codecFlagDontUseNewImageBuffer

Forces an error to be returned when a new image buffer would have to be allocated instead of allocating the new buffer.

codecFlagInterlaceUpdate

Updates the screen interlacing even and odd scan lines to reduce tearing artifacts (if the decompressor supports this mode).

codecFlagCatchUpDiff

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 DecompressSequenceFrame calls.


Copyright © 2005, 2006 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2006-01-10