Image Decompressors and the wantedDestinationPixelTypes List

(OR Don't forget to put 0 at end of wantedDestinationPixelTypes)

Dispatch 7

When QuickTime needs to draw a compressed image or a sequence of compressed images, it uses the Image Compression Manager (ICM) to do so. The ICM must find and configure a suitable codec component to use. In doing this, the ICM checks the cType field of the image's ImageDescription for the codec type and then finds decompressors with a subType of the same value. After opening a candidate codec component, the ICM makes a call to the codec's ImageCodecPreDecompress component routine. This is the opportunity for the codec to determine if it can draw to the destination PixMap based upon such factors as the destination's pixel format, the destination's dimensions, and any requested transformations.

NOTE: Decompressor components based upon the Base codec perform this work in the ImageCodecPreflight routine. The Base codec implements the ImageCodecPreDecompress call which in turn does some work and calls ImageCodecPreflight in the subcodec. Otherwise, the issues are the same.

The Image Compression Manager passes a pointer to a CodecDecompressParams structure to ImageCodecPreDecompress which contains the information a codec needs to determine if it can draw to the destination. A codec inspects the parameters and sets flags and other values in this structure to indicate what it is capable of doing. For example, if the resulting image is scaled but the codec indicates it cannot draw scaled images, the Image Compression Manager will allocate a temporary GWorld and request the codec draw the image unscaled into this GWorld. The ICM will then transfer and scale this intermediate image to the final destination. This flexibility allows a codec to only implement minimal support--only a single pixel format, no scaling, no clipping, etc.--and still be guaranteed that the image will still be rendered to the destination. If the codec implements more pixel formats or implements scaling, then there may be no need for intermediate buffers and so the resulting drawing is faster. Again, it will work if the codec doesn't do this; it will just work more efficiently if the codec does the work.

Pixel Formats

Because there are so many pixel formats possible, codecs rarely implement more than a few. For example, a codec handling 32-bit source data may only support 32-bit pixel destinations. It might handle other formats but isn't required to do so. It would leave it to the ICM to handle all other pixel depths.

On the Macintosh, QuickTime supports 1, 2, 4, and 8-bit grayscale and 1, 2, 4, 8, 16, 24, and 32 bit color formats. On Windows, QuickTime adds support for formats like 16-bit little endian 555 and 565 formats, the 24-bit BGR format, and 32-bit BGRA and RGBA formats. On both platforms, there are also non-RGB formats like yuvs and yuvu available. Other formats are also possible through additions by developers.

In the codec's ImageCodecPreDecompress call, the codec should return which pixel formats it can support for the given source image data and the destination pixel format. It does this by setting the wantedDestinationPixelTypes field to be a handle to a 0-terminated list of OSTypes with all the pixel formats the codec is able to support for the given source image data and destination. This list is ordered from most preferred to least preferred format. It ends with a 0 to indicate the end of the list.

For example, if the destination pixel format was Windows 24-bit BGR, the codec might return a list of the form:

Figure. Pixels formats list

to indicate that it can handle drawing to Windows BGRA (blue, green, red, then alpha), to standard Macintosh 32-bit pixel format (alpha, red, green, then blue), to standard Macintosh 16-bit (also known as big endian 555), to little endian 555, to little endian 565 but to no other formats. In this case, the ICM now has enough information to allocate a temporary pixel format GWorld (BGRA maybe) and then have the codec draw into it. The ICM can then take care of transferring from the BGRA GWorld to the final BGR pixel format.

The wantedDestinationPixelTypes field is set to a handle owned by the codec. The ICM will copy the contents of this list when ImageCodecPreDecompress (or ImageCodecPreflight) returns to it. Because of this, it's typical for a codec to allocate a handle with a size equal to the the maximum number of formats it might return plus one times the size of an OSType. This allows the codec to reuse the already allocated list in each call to ImageCodecPreDecompress it receives. For one depth, it might set a few of the OSTypes in the list but for another it might set more or less. In both cases, it writes 0 after the last pixel format it writes.

NOTE: This list must be terminated with an OSType with value 0 to mark its end. Failing to put a 0 at the end can lead to difficult to find bugs. QuickTime uses a terminator instead of the handle's size since this allows the handle to be allocated at its maximum size and reused for different sized lists.

See Also

QuickTime 3 Reference - Imaging - Codec Components

Inside Macintosh: QuickTime Components - Image Compressors

Modification History

4/16/98 - clf - First published