The Decompression Parameters Structure(IM: QC)

Inside Macintosh: QuickTime Components /

Chapter 4 - Image Compressor Components / Image Compressor Components Reference

The Decompression Parameters Structure
Decompressors accept the parameters that govern a decompression operation in the form of a data structure. This data structure is called a decompression parameters structure. It is used by the CDBandDecompress and CDPreDecompress functions, which are described on page 4-64 and page 4-63, respectively.
The decompression parameters structure is defined by the CodecDecompressParams data type as follows:
typedef struct {
   ImageSequence           sequenceID;       /* unique sequence ID
                                                (predecompress,
                                                band decompress) */
   ImageDescriptionHandle  imageDescription; /* handle to image description
                                                structure (predecompress,
                                                band decompress) */
   Ptr                     data;             /* compressed image data */
   long                    bufferSize;       /* size of data buffer */
   long                    frameNumber;      /* frame identifier */
   long                    startLine;        /* starting line for band */
   long                    stopLine;         /* ending line for band */
   long                    conditionFlags;   /* condition flags */
   CodecFlags              callerFlags;      /* control flags */
   CodecCapabilitiesPtr    *capabilities;    /* pointer to compressor 
                                                capability structure
                                                (predecompress,
                                                band decompress) */
   ProgressProcRecord      progressProcRecord;  
                                             /* progress function 
                                                structure */
   CompletionProcRecord    completionProcRecord;
                                             /* completion function 
                                                structure */
   DataProcRecord          dataProcRecord;   /* data-loading function 
                                                structure */
   CGrafPtr                port;             /* pointer to color
                                                graphics port for image
                                                (predecompress,
                                                band decompress) */
   PixMap                  dstPixMap;        /* destination pixel map
                                                (predecompress,
                                                band decompress) */
   BitMapPtr               maskBits;         /* update mask */
   PixMapPtr               mattePixMap;      /* blend matte pixel map */
   Rect                    srcRect;          /* source rectangle
                                                (predecompress,
                                                band decompress) */
   MatrixRecordPtr         *matrix;          /* pointer to matrix structure
                                                (predecompress,
                                                band decompress) */
   CodecQ                  accuracy;         /* desired accuracy
                                                (predecompress,
                                                band decompress) */
   short                   transferMode;     /* transfer mode(predecompress,
                                                band decompress) */
   long                    reserved[2];      /* reserved */
} CodecDecompressParams;
typedef CodecDecompressParams *CodecDecompressParamsPtr;
Field Description

sequenceID
Contains the unique sequence identifier. If the image to be decompressed is part of a sequence, this field contains the sequence identifier that was assigned by the Image Compression Manager's DecompressSequenceBegin function. If the image is not part of a sequence, this field is set to 0.
imageDescription
Contains a handle to the image description structure that describes the image to be decompressed.
data
Points to the compressed image data. This must be a 32-bit clean address. The bufferSize field indicates the size of this data buffer. If the entire compressed image does not fit in memory, the application should provide a data-loading function, identified by the dataProc field of the data-loading function structure stored
in the dataProcRecord field.

This field is used only by the CDBandDecompress function (described on page 4-64).
bufferSize
Specifies the size of the image data buffer.

This field is used only by the CDBandDecompress function.
frameNumber
Contains a frame identifier. Indicates the relative frame number within the sequence. The Image Compression Manager increments this value for each frame in the sequence.

This field is used only by the CDBandDecompress function (described on page 4-64).
startLine
Specifies the starting line for the band. This field indicates the starting line number for the band to be decompressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row in the image is row number 0.

This field is used only by the CDBandDecompress function.
stopLine
Specifies the ending line for the band. This field indicates the ending line number for the band to be decompressed. The line number refers to the pixel row in the image, starting from the top of the image. The first row is row number 0.

The image band includes the row specified by this field. So, to define a band that contains one row of pixels at the top of an image, you set the startLine field to 0 and the stopLine field to 1.

This field is used only by the CDBandDecompress function.
conditionFlags
Contains flags that identify the condition under which your component has been called (in order to save the component some work). The flags in this field are passed to the component in the CDBandCompress and CDPreDecompress functions when conditions change to save it some work. In addition, these fields contain information about actions taken by your component. Condition flags fields contain the following flags:
                           #define codecConditionFirstFrame       (1L<<2)                 
                           #define codecConditionNewDepth         (1L<<3)  
                           #define codecConditionNewTransform     (1L<<4)  
                           #define codecConditionNewSrcRect       (1L<<5)  
                           #define codecConditionNewMatte         (1L<<7)     
                           #define codecConditionNewTransferMode  (1L<<8)  
                           #define codecConditionNewClut          (1L<<9)  
                           #define codecConditionNewAccuracy      (1L<<10) 
                           #define codecConditionNewDestination   (1L<<11) 
                           #define codecConditionCodecChangedMask (1L<<31) 
The codecConditionFirstBand constant is an input flag that indicates if this is the first band in the frame. If this flag is set to 1, then your component is being called for the first time for the current frame.

The codecConditionLastBand constant is an input flag that indicates if this is the last band in the frame. If this flag is set to 1, then your component is being called for the last time for the current frame. If the codecConditionFirstBand flag is also set to 1, this is the only time the Image Compression Manager is calling your component for the current frame.

The codecConditionFirstFrame constant is an input flag that indicates that this is the first frame to be decompressed for this image sequence.

The codecConditionNewDepth constant is an input flag that indicates that the depth of the destination has changed for this image sequence.

The codecConditionNewTransform constant is an input flag that indicates that the transformation matrix has changed for this sequence.

The codecConditionNewSrcRect constant is an input flag that indicates that the source rectangle has changed for this sequence.

The codecConditionNewMatte is an input flag that indicates that the matte pixel map has changed for this sequence.

The codecConditionNewTransferMode constant is an input flag that indicates that the transfer mode has changed for this sequence.

The codecConditionNewClut constant is an input flag that indicates that the color lookup table has changed for this sequence.

The codecConditionNewAccuracy constant is an input flag that indicates to the component that the accuracy parameter has changed for this sequence.

The codecConditionNewDestination constant is an input flag that indicates to the component that the destination pixel map has changed for this sequence.

The codecConditionCodecChangedMask constant is an output flag that indicates that the component has changed the mask bits. If your image decompressor component can mask decompressed images and if some of the image pixels should not be written to the screen, set the corresponding bits in the mask (defined by the maskBits field in the decompression parameter structure) to 0. In addition, set this flag to 1. Otherwise, set this flag to 0.
callerFlags
Contains flags providing further control information. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information about the Image Compression Manager function control flags. Four flags are available:

The codecFlagUpdatePrevious flag controls whether your compressor updates the previous image during compression. This flag is only used with sequences that are being temporally compressed. If this flag is set to 1, your compressor should copy the current frame into the previous frame buffer at the end of the frame- compression sequence. Use the source image.

The codecFlagWasCompressed flag indicates to your 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. This flag is set to 1 to indicate that the image was previously compressed. This flag is set to 0 if the image was not previously compressed.

The codecFlagUpdatePreviousComp flag controls whether your compressor updates the previous image buffer with the compressed image. This flag is only used with temporal compression. If this flag is set to 1, your compressor should update the previous frame buffer at the end of the frame compression sequence, allowing your compressor to perform frame differencing against the compression results. Use the image that results from the compression operation. If this flag is set to 0, your compressor should not modify the previous frame buffer during compression.

The codecFlagLiveGrab flag indicates whether the current sequence results from grabbing live video. When working with live video, your compressor should operate as quickly as possible and disable any additional processing, such as compensation for previously compressed data. This flag is set to 1 when you are compressing from a live video source. This field is used only by the CDBandCompress function (described on page 4-63).
capabilities
Points to a compressor capability structure (described on page 4-35). The Image Compression Manager uses this parameter to determine the capabilities of your decompressor component.

This field is used only by the CDPreDecompress function (described on page 4-63).
progressProcRecord
Contains a progress function structure. During the decompression operation, your decompressor may occasionally call a function that the application provides in order to report your progress (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about progress functions). This field contains a structure that identifies the progress function. If the progressProc field of this structure is set to nil, the application did not provide a progress function.

The progress function structure is defined by the progressProcRecord data type as follows:
               struct ProgressProcRecord {
                  ProgressProcPtr progressProc;  /* pointer to
                                                    progress
                                                    function */
                  long            progressRefCon;/* reference
                                                    constant */
               };
            typedef struct ProgressProcRecord ProgressProcRecord;
            typedef ProgressProcRecord *ProgressProcRecordPtr;
This field is used only by the CDBandDecompress function (described on page 4-64).
completionProcRecord
Contains a completion function structure. This field governs whether you perform the decompression asynchronously. If the completionProc field in this structure is set to nil, perform the decompression synchronously. If this field is not nil, it specifies an application completion function. Perform the decompression asynchronously and call that completion function when your component is finished. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for information on calling completion functions. If this field has a value of -1, perform the operation asynchronously but do not call the application's completion function.

The completion function structure is defined by the CompletionProcRecord data type as follows:
               struct CompletionProcRecord {
                CompletionProcPtr completionProc;  /* pointer to
                                                      completion
                                                      function */
                long             completionRefCon; /* reference
                                                      constant */
               };
         typedef struct CompletionProcRecord CompletionProcRecord;
         typedef CompletionProcRecord *CompletionProcRecordPtr;
This field is used only by the CDBandDecompress function (described on page 4-64).
dataProcRecord
Contains a data-loading function structure. If the data stream is not all in memory, your component may call an application function that loads more compressed data (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about data-loading functions). This field contains a structure that identifies that data-loading function. If the application did not provide a data-loading function, the dataProc field in this structure is set to nil. In this case, the entire image must be in memory at the location specified by the data field.

The data-loading function structure is defined by the dataProcRecord data type as follows:
               struct DataProcRecord {
                  DataProcPtr dataProc;/* pointer to data-loading
                                          function */
                  long dataRefCon;     /* reference constant */
               };
               typedef struct DataProcRecord DataProcRecord;
               typedef DataProcRecord *DataProcRecordPtr;
This field is used only by the CDBandDecompress function.
port
Points to the color graphics port that receives the decompressed image.
dstPixMap
Points to the pixel map where the decompressed image is to be displayed. The GDevice global variable is set to the destination graphics device.

The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value--the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.
maskBits
Contains an update mask. If your component can mask result data, use this mask to indicate which pixels in the destination pixel map to update. Your component indicates whether it can mask with the codecCanMask flag in the flags field of the compressor capability structure referred to by the capabilities field. This field is updated in response to the CDPreDecompress request (described on page 4-63). See "The Compressor Capability Structure" beginning on page 4-35 for a description of the compressor capability structure.

If the mask has not changed since the last CDBandDecompress request, the codecConditionCodecChangedMask flag in the conditionFlags field is set to 0.

This field is used only by the CDBandDecompress function.
mattePixMap
Points to a pixel map that contains a blend matte. The matte can be defined at any supported pixel depth--the matte depth need not correspond to the source or destination depths. The matte must be in the coordinate system of the source image. If the application does not want to apply a blend matte, this field is set to nil.

The contents of this pixel map differ from a standard pixel map in two ways. First, the rowBytes field is a full 16-bit value--the high-order bit is not necessarily set to 1. Second, the baseAddr field must contain a 32-bit clean address.

This field is used only by the CDBandDecompress function (described on page 4-64).
srcRect
Points to a rectangle defining the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by the width and height fields of the image description structure referred to by the imageDescription field.
matrix
Points to a matrix structure that specifies how to transform the image during decompression.
accuracy
Specifies the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values.
transferMode
Specifies the QuickDraw transfer mode for the operation. For details on QuickDraw's transfer modes, see the chapter "Basic QuickDraw" in Inside Macintosh: Imaging.
reserved
Reserved for use by Apple.