Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager / Image Compression Manager Reference

Image Compression Manager Functions / Working With Images

FCompressImage

Like the CompressImage function, the FCompressImage function allows your application to compress a single-frame image that is currently stored as a pixel map structure (PixMap).

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

src

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

srcRect

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

colorDepth

Specifies 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 (see "Getting Information About Compressor Components" on page 3-56 for more information on the GetCodecInfo function).

quality

Specifies the desired compressed image quality. See "Compression Quality Constants" on page 3-52, for valid values.

cType

Specifies a compressor type. You must set this parameter to a
valid compressor type (see Table 3-3 on page 3-59 for a list of the available compressor types).

codec

Specifies a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCode

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

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.

If you set the codec parameter to anyCodec, the Image Compression Manager chooses the first compressor it finds of the specified type.

clut

Contains 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 clut 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

Specifies flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on page 3-53, for information about CodecFlags fields. The following flag is available for this function:

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.

bufferSize

Specifies 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 a data-unloading function structure. 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 (see "Data-Unloading Functions" beginning on page 3-154 for more information on the data-unloading structure). If you have not provided 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.

progressProc

Points to a progress function structure. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions" on page 3-156 for more information about progress functions). 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.

desc

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

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 (described on page 3-63). 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. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that handle with this parameter. (See Inside Macintosh: Memory for details on StripAddress.)

The Image Compression Manager places the actual size of the compressed image into the dataSize field of the image description structure referred to by the desc parameter.

DESCRIPTION

The FCompressImage function gives your application additional control over the parameters that guide the compression operation.

RESULT CODES

noErr	0	No error
paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
noCodecErr	-8961	The Image Compression Manager could not find the specified compressor
codecSpoolErr	-8966	Error loading or unloading data
codecAbortErr	-8967	Operation aborted by the progress function

SEE ALSO

If you find that you do not need this level of compression parameter control, use the CompressImage function, described in the previous section.