Mac Developer Library

Developer

Compression and Decompression Reference for QuickTime

Options
Deployment Target:

On This Page

Compression and Decompression Reference for QuickTime

QuickTime compression and decompression APIs help applications compress and decompress movie data.

Functions

  • Aligns a specified rectangle to the strictest screen that the rectangle intersects.

    Declaration

    void AlignScreenRect ( Rect *rp, ICMAlignmentProcRecordPtr alignmentProc );

    Parameters

    rp

    A pointer to a rectangle defined in global screen coordinates.

    alignmentProc

    Points to your own alignment behavior function. Set this parameter to NIL to use the standard behavior.

    Discussion

    For a specification of your alignment function, see ICMAlignmentProc.

  • Moves a specified window to the nearest optimal alignment position.

    Declaration

    void AlignWindow ( WindowRef wp, Boolean front, const Rect *alignmentRect, ICMAlignmentProcRecordPtr alignmentProc );

    Parameters

    wp

    Points to the window to be aligned.

    front

    The frontmost window. If the front parameter is TRUE and the window specified in the wp parameter isn't the active window, AlignWindow makes it the active window.

    alignmentRect

    A pointer to a rectangle in window coordinates that allows you to align the window to a rectangle within the window. Set this parameter to NIL to align using the bounds of the window.

    alignmentProc

    Points to a function that allows you to provide your own alignment behavior. Set this parameter to NIL to use the standard behavior.

    Discussion

    For a specification of your alignment function, see ICMAlignmentProc.

  • Drags a specified gray region along an optimal alignment grid.

    Declaration

    long DragAlignedGrayRgn ( RgnHandle theRgn, Point startPt, Rect *boundsRect, Rect *slopRect, short axis, UniversalProcPtr actionProc, Rect *alignmentRect, ICMAlignmentProcRecordPtr alignmentProc );

    Parameters

    theRgn

    A handle to the specified region for this operation. When the user holds down the mouse button, DragAlignedGrayRgn pulls a gray outline of the region around following the movement of the mouse until the mouse button is released.

    startPt

    The point where the mouse button was originally pressed in the local coordinates of the current graphics port.

    boundsRect

    A pointer to the boundary rectangle of the current graphics port. The offset point follows the mouse location except that DragAlignedGrayRgn never moves the offset point outside this rectangle. This limits the travel of the region's outline, not the movements of the mouse.

    slopRect

    A pointer to the slop rectangle that completely encloses the boundary rectangle so that the user is allowed some flexibility in moving the mouse.

    axis

    Allows you to constrain the region's motion to only one axis (see constants below). See these constants:

    actionProc

    Points to a function that defines some action to be performed repeatedly as long as the user holds down the mouse button. The function should have no parameters. If the actionProc parameter is NIL, DragAlignedGrayRgn simply retains control until the mouse button is released.

    alignmentRect

    A pointer to a rectangle within the bounds of the region specified in the parameter theRgn. Pass NIL to align using the bounds of the parameter theRgn.

    alignmentProc

    A pointer to your alignment behavior function; see ICMAlignmentProc. Pass NIL to use the standard behavior.

    Return Value

    The difference between the point where the mouse button was pressed and the offset point; that is, the point in the region whose horizontal and vertical offsets from the upper-left corner of the region's enclosing rectangle are the same as the offsets of the starting point when the user pressed the mouse button. The vertical difference between the starting point and the offset point is stored in the high-order word of the return value and the horizontal difference is stored in the low-order word.

    Discussion

    This function limits the movement of the region defined by theRgn according to the constraints set by the boundsRect and slopRect parameters. While the cursor is inside the boundsRect rectangle, the region's outline follows it normally. If the mouse button is released while the cursor is within this rectangle, the return value reflects the simple distance that the cursor moved in each dimension. When the cursor moves outside the boundsRect rectangle, the offset point stops at the edge of the boundsRect rectangle. If the mouse button is released while the cursor is outside the boundsRect rectangle but inside the slopRect rectangle, the return value reflects only the difference between the starting point and the offset point, regardless of how far outside of the boundsRect rectangle the cursor may have moved. (Note that part of the region can fall outside the boundsRect rectangle, but not the offset point.) When the cursor moves outside the slopRect rectangle, the region's outline disappears from the screen. DragAlignedGrayRgn continues to track the cursor, however, and if the cursor moves back into the slopRect rectangle, the outline reappears. If the mouse button is released while the cursor is anywhere inside the slopRect rectangle, the window is redrawn in its new location, calculated from the value returned by DragAlignedGrayRgn If the mouse button is released while the cursor is outside the slopRect rectangle, both words of the return value are set to 0x8000 and the window does not move from its original location.

  • Drags the specified window along an optimal alignment grid.

    Declaration

    void DragAlignedWindow ( WindowRef wp, Point startPt, Rect *boundsRect, Rect *alignmentRect, ICMAlignmentProcRecordPtr alignmentProc );

    Parameters

    wp

    A window pointer to the window to be dragged.

    startPt

    A point that is equal to the point where the mouse button was pressed (in global coordinates, as stored in the where field of the event structure). DragAlignedWindow pulls a gray outline of the window around the screen, following the movements of the mouse until the button is released.

    boundsRect

    Points to the boundary rectangle in global coordinates. If the mouse button is released when the mouse position is outside the limits of the boundary rectangle, DragAlignedWindow returns without moving the window or making it the active window. For a document window, the boundary rectangle typically is four pixels in from the menu bar and from the other edges of the screen, to ensure that there won't be less than a four-pixel-square area of the title bar visible on the screen.

    alignmentRect

    Points to a rectangle in window coordinates that allows you to align the window to a rectangle within the window. Set this parameter to NIL to align using the bounds of the window.

    alignmentProc

    A pointer to your alignment behavior function; see ICMAlignmentProc. Pass NIL to use the standard behavior.

    Discussion

    The following code sample illustrates the use of DragAlignedWindow:

    1. // DragAlignedWindow coding example
    2. // See "Discovering QuickTime," page 265
    3. Boolean IsQuickTimeInstalled (void)
    4. {
    5. OSErr nErr;
    6. long lResult;
    7. nErr =Gestalt(gestaltQuickTime, &lResult);
    8. return (nErr ==noErr);
    9. }
    10. void MyInitialize (void)
    11. {
    12. InitGraf(&qd.thePort);
    13. InitFonts();
    14. InitWindows();
    15. InitMenus();
    16. TEInit();
    17. InitDialogs(NIL);
    18. MaxApplZone();
    19. EnterMovies();
    20. }
    21. WindowRef MakeMyWindow (void)
    22. {
    23. WindowRef pMacWnd;
    24. Rect rectWnd ={0, 0, 120, 160};
    25. Rect rectBest;
    26. // figure out the best monitor for the window
    27. GetBestDeviceRect(NIL, &rectBest);
    28. // put the window in the top left corner of that monitor
    29. OffsetRect(&rectWnd, rectBest.left + 10, rectBest.top + 50);
    30. // create the window
    31. pMacWnd =NewCWindow(NIL, &rectWnd, "\pGrabber",
    32. TRUE, noGrowDocProc, (WindowRef)-1,
    33. TRUE, 0);
    34. // set the port to the new window
    35. SetPort(pMacWnd);
    36. return pMacWnd;
    37. }
    38. main (void)
    39. {
    40. WindowRef pMacWnd;
    41. SeqGrabComponent seqGrab;
    42. SGChannel sgchanVideo, sgchanSound;
    43. Boolean bDone =FALSE;
    44. OSErr nErr;
    45. MyInitialize();
    46. pMacWnd =MakeMyWindow();
    47. seqGrab =MakeMySequenceGrabber(pMacWnd);
    48. if (seqGrab ==NIL)
    49. return;
    50. MakeMyGrabChannels(seqGrab, &sgchanVideo, &sgchanSound,
    51. &pMacWnd->
    52. portRect, FALSE);
    53. nErr =SGStartPreview(seqGrab);
    54. while (!bDone) {
    55. ICMAlignmentProcRecord apr;
    56. short nPart;
    57. WindowRef pWhichWnd;
    58. EventRecord er;
    59. GetNextEvent(everyEvent, &er);
    60. switch (er.what) {
    61. case nullEvent: // give the sequence grabber time
    62. nErr =SGIdle(seqGrab);
    63. if (nErr !=noErr)
    64. bDone =TRUE;
    65. break;
    66. case updateEvt:
    67. if (er.message ==(long)pMacWnd) {
    68. // inform the sequence grabber of the update
    69. SGUpdate(seqGrab,((WindowPeek)
    70. pMacWnd)->
    71. updateRgn);
    72. // and swallow the update event
    73. BeginUpdate(pMacWnd);
    74. EndUpdate(pMacWnd);
    75. }
    76. break;
    77. case mouseDown:
    78. nPart =FindWindow(er.where, &pWhichWnd);
    79. if (pWhichWnd !=pMacWnd)
    80. break;
    81. switch (nPart) {
    82. case inContent:
    83. // pause until mouse button is released
    84. SGPause(seqGrab, TRUE);
    85. while (StillDown())
    86. SGPause(seqGrab, FALSE);
    87. break;
    88. case inGoAway:
    89. bDone =TrackGoAway(pMacWnd, er.where);
    90. break;
    91. case inDrag:
    92. // pause when dragging window so video
    93. // doesn't draw in the wrong place
    94. SGPause(seqGrab, TRUE);
    95. SGGetAlignmentProc(seqGrab, &apr);
    96. DragAlignedWindow(pMacWnd,
    97. er.where,
    98. &screenBits.bounds,
    99. NIL, &alignProc);
    100. SGPause(seqGrab, FALSE);
    101. break;
    102. }
    103. break;
    104. }
    105. }
    106. // clean up
    107. SGStop(seqGrab);
    108. CloseComponent(seqGrab);
    109. DisposeWindow(pMacWnd);
    110. }
  • Transforms a set of fixed points through a specified matrix.

    Declaration

    OSErr TransformFixedPoints ( const MatrixRecord *m, FixedPoint *fpt, long count );

    Parameters

    m

    A pointer to the transformation matrix for this operation.

    fpt

    A pointer to the first fixed point to be transformed.

    count

    The number of fixed points to be transformed. These points must be stored immediately following the point specified by the fpt parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Transforms the upper-left and lower-right points of a rectangle through a matrix that is specified by fixed points.

    Declaration

    Boolean TransformFixedRect ( const MatrixRecord *m, FixedRect *fr, FixedPoint *fpp );

    Parameters

    m

    A pointer to the matrix for this operation.

    fr

    A pointer to the FixedRect structure that defines the rectangle to be transformed. TransformFixedRect returns the updated coordinates into the structure referred to by this parameter. If the resulting rectangle has been rotated or skewed (that is, the transformation involves operations other than scaling and translation), the function sets the returned Boolean value to FALSE and returns the coordinates of the boundary box of the transformed rectangle. The function then updates the points specified by the fpp parameter to contain the coordinates of the four corners of the transformed rectangle.

    fpp

    A pointer to an array of four fixed points. The function returns the coordinates of the four corners of the rectangle after the transformation operation. If you do not want this information, set this parameter to NIL.

    Return Value

    If the resulting rectangle has been rotated or skewed (that is, the transformation involves operations other than scaling and translation), the function returns FALSE, updates the rectangle specified by the fr parameter to define the boundary box of the resulting rectangle, and places the coordinates of the corners of the resulting rectangle in the points specified by the fpp parameter. If the transformed rectangle and its boundary box are the same, the function returns TRUE.

    Discussion

    This function does not return any error codes.

  • Transforms a set of QuickDraw points through a specified matrix.

    Declaration

    OSErr TransformPoints ( const MatrixRecord *mp, Point *pt1, long count );

    Parameters

    mp

    A pointer to the transformation matrix for this operation.

    pt1

    A pointer to the first QuickDraw point to be transformed.

    count

    The number of QuickDraw points to be transformed. These points must be stored immediately following the point specified by the pt1 parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Transforms the upper-left and lower-right points of a rectangle through a specified matrix.

    Declaration

    Boolean TransformRect ( const MatrixRecord *m, Rect *r, FixedPoint *fpp );

    Parameters

    m

    The matrix for this operation.

    r

    A pointer to the Rect structure that defines the rectangle to be transformed. The function returns the updated coordinates into the structure referred to by this parameter.

    fpp

    A pointer to an array of four fixed points. The TransformRect function returns the coordinates of the four corners of the rectangle after the transformation operation. If you do not want this information, set this parameter to NIL.

    Return Value

    If the resulting rectangle has been rotated or skewed (that is, the transformation involves operations other than scaling and translation), the function returns FALSE, updates the rectangle specified by the r parameter to define the boundary box of the resulting rectangle, and places the coordinates of the corners of the resulting rectangle in the points specified by the fpp parameter. If the transformed rectangle and its boundary box are the same, the function returns TRUE.

    Discussion

    This function does not return any error codes.

  • Applies a specified matrix to a region.

    Declaration

    OSErr TransformRgn ( MatrixRecordPtr matrix, RgnHandle rgn );

    Parameters

    matrix

    Points to the matrix for this operation. The TransformRgn function currently supports only translation and scaling operations.

    rgn

    A handle to the MacRegion structure to be transformed. The function transforms each point in the region according to the specified matrix

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Determines the maximum size an image will be after compression for a given compression sequence.

    Declaration

    OSErr GetCSequenceMaxCompressionSize ( ImageSequence seqID, PixMapHandle src, long *size );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the CompressSequenceBegin function.

    src

    A handle to the source PixMap structure. The compressor uses only the image's size and pixel depth to determine the maximum size of the compressed image.

    size

    A pointer to a field to receive the maximum size, in bytes, of the compressed image.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function is similar to GetMaxCompressionSize, but operates on a compression sequence instead of requiring the application to pass individual parameters about the source image.

    Special Considerations

    Before calling GetCSequenceMaxCompressionSize you must have already started a compression sequence with CompressSequenceBegin

  • Determines the location of the previous image buffer allocated by the compressor.

    Declaration

    OSErr GetCSequencePrevBuffer ( ImageSequence seqID, GWorldPtr *gworld );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the CompressSequenceBegin function.

    gworld

    A pointer to a field to receive a pointer to the CGrafPort structure that describes the graphics world for the image buffer. You should not dispose of this graphics world; the returned pointer refers to a buffer that the Image Compression Manager is using. If the compressor has not allocated a buffer, GetCSequencePrevBuffer returns an error result code.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Note that this function only returns information about buffers that were allocated by the compressor. You cannot use this function to determine the location of a buffer you have provided.

  • Assigns a data-unloading function to a sequence.

    Declaration

    OSErr SetCSequenceFlushProc ( ImageSequence seqID, ICMFlushProcRecordPtr flushProc, long bufferSize );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    flushProc

    A pointer to an ICMFlushProcRecord structure. If there is not enough memory to store the compressed image, the compressor calls an ICMFlushProc callback that you provide, which unloads some of the compressed data. If you have not provided such 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 to CompressSequenceFrame.

    bufferSize

    The size of the buffer to be used by the data-unloading function specified by the flushProc parameter. If you have not specified such a data-unloading function, set this parameter to 0.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Data-unloading functions allow compressors to work with images that cannot fit in memory. During the compression operation, the compressor calls the data-unloading function whenever it has accumulated a specified amount of compressed data. Your data-unloading function then writes the compressed data to some other device, freeing buffer space for more compressed data. The compressor starts using the data-unloading function with the next image in the sequence.

    Special Considerations

    There is no parameter to the CompressSequenceBegin function that allows you to assign a data-unloading function to a sequence.

  • Adjusts the key frame rate for the current sequence.

    Declaration

    OSErr SetCSequenceKeyFrameRate ( ImageSequence seqID, long keyFrameRate );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    keyFrameRate

    The maximum number of frames allowed between key frames. Set this parameter to 1 to specify all key frames, to 2 to specify every other frame as a key frame, to 3 to specify every third frame as a key frame, and so forth. The compressor determines the optimum placement for key frames based upon the amount of redundancy between adjacent images in the sequence. Consequently, the compressor may insert key frames more frequently than you have requested. However, the compressor will never place fewer key frames than is indicated by this parameter. If you set this parameter to 0, the Image Compression Manager only places key frames in the compressed sequence when you call CompressSequenceFrame, setting the codecFlagForceKeyFrame flag in the flags parameter. The compressor ignores this parameter if you have not requested temporal compression; that is, you have passed 0 for the temporalQuality parameter of CompressSequenceBegin.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Key frames provide points from which a temporally compressed sequence may be decompressed. Use this parameter to control the frequency at which the compressor places key frames into the compressed sequence. The new key frame rate takes effect with the next image in the sequence.

  • Sets the preferred packet size for a sequence.

    Declaration

    OSErr SetCSequencePreferredPacketSize ( ImageSequence seqID, long preferredPacketSizeInBytes );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    preferredPacketSizeInBytes

    The preferred packet size in bytes.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Allows the application to set the pixel map and boundary rectangle used by the previous frame in temporal compression.

    Declaration

    OSErr SetCSequencePrev ( ImageSequence seqID, PixMapHandle prev, const Rect *prevRect );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    prev

    A handle to the new previous image buffer. You must allocate this buffer using the same pixel depth and ColorTable structure as the source image buffer that you specified with the src parameter when you called CompressSequenceBegin. The compressor uses this buffer to store a previous image against which the current image is compared when performing temporal compression. The compressor manages the contents of this buffer based upon several considerations, such as the key frame rate and the degree of difference between compared images. The current image is stored in the buffer referred to by the src parameter to CompressSequenceBegin.

    prevRect

    A pointer to a Rect structure that defines the portion of the previous image to use for temporal compression. The compressor uses this portion of the previous image as the basis of comparison with the current image. This rectangle must be the same size as the source rectangle you specify with the srcRect parameter to CompressSequenceBegin. To get the boundary of a source pixel map, set this parameter to NIL.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    When you start compressing a sequence, you may assign a previous frame buffer and rectangle with the prev and prevRect parameters to CompressSequenceBegin. If you specified a NIL value for the prev parameter, the compressor allocates an offscreen buffer for the previous frame. In either case you may use this function to assign a new previous frame buffer.

    Special Considerations

    This is a very specialized function; your application should not need to call it under most circumstances.

  • Adjusts the spatial or temporal quality for the current sequence.

    Declaration

    OSErr SetCSequenceQuality ( ImageSequence seqID, CodecQ spatialQuality, CodecQ temporalQuality );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    spatialQuality

    A constant (see below) that specifies the desired compressed image quality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    temporalQuality

    A constant (see below) that specifies the desired sequence temporal quality. This parameter governs the level of compression you desire with respect to information between successive frames in the sequence. Set this parameter to 0 to prevent the compressor from applying temporal compression to the sequence.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    You originally set the default spatial and temporal quality values for a sequence with CompressSequenceBegin. The new quality parameters take effect with the next frame in the sequence.

    Special Considerations

    If you change the quality settings while processing an image sequence, you affect the maximum image size that you may receive during sequence compression. Consequently, you should call GetMaxCompressionSize after you change the quality settings. If the maximum size has increased, you should reallocate your image buffers to accommodate the larger image size.

  • Determines the location of the offscreen image buffer allocated by a decompressor.

    Declaration

    OSErr GetDSequenceImageBuffer ( ImageSequence seqID, GWorldPtr *gworld );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    gworld

    A pointer to a field to receive a pointer to the CGrafPort structure describing the graphics world for the image buffer. You should not dispose of this graphics world; the returned pointer refers to a buffer that the Image Compression Manager is using. It is disposed of for you when the CDSequenceEnd function is called. If the decompressor has not allocated a buffer, GetDSequenceImageBuffer returns an error result code.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Determines the location of the offscreen screen buffer allocated by a decompressor.

    Declaration

    OSErr GetDSequenceScreenBuffer ( ImageSequence seqID, GWorldPtr *gworld );

    Parameters

    seqID

    The unique sequence identifier that was returned by the DecompressSequenceBegin function.

    gworld

    A pointer to a field to receive a pointer to the CGrafPort structure that describes the graphics world for the screen buffer. You should not dispose of this graphics world; the returned pointer refers to a buffer that the Image Compression Manager is using. It is disposed of for you when the CDSequenceEnd function is called. If the decompressor has not allocated a buffer, GetDSequenceScreenBuffer returns an error result code.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Tests to see if a compressed image contains data at a a given point.

    Declaration

    OSErr PtInDSequenceData ( ImageSequence seqID, void *data, Size dataSize, Point where, Boolean *hit );

    Parameters

    seqID

    The unique sequence identifier that was returned by the DecompressSequenceBegin function.

    data

    Pointer to compressed data in the format specified by the desc param.

    dataSize

    Size of the compressed data referred to by the data param.

    where

    A QuickDraw Point structure of value (0,0), based at the top-left corner of the image.

    hit

    A pointer to a field to receive the Boolean indicating whether or not the image contained data at the specified point. The Boolean will be set to TRUE if the point specified by the where parameter is contained within the compressed image data specified by the data param, or FALSE if the specified point falls within a blank portion of the image.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    PtInDSequenceData allows the application to perform hit testing on compressed data.

  • Adjusts the decompression accuracy for the current sequence.

    Declaration

    OSErr SetDSequenceAccuracy ( ImageSequence seqID, CodecQ accuracy );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    accuracy

    A constant (see below) that specifies the accuracy desired in the decompressed image. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The accuracy parameter governs how precisely the decompressor decompresses the image data. Some decompressors may choose to ignore some image data to improve decompression speed. A new accuracy value takes effect with the next frame in the sequence.

  • Assigns a data-loading function to a sequence.

    Declaration

    OSErr SetDSequenceDataProc ( ImageSequence seqID, ICMDataProcRecordPtr dataProc, long bufferSize );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    dataProc

    A pointer to an ICMDataProcRecord structure. If the data stream is not all in memory when your program calls DecompressSequenceFrame, the decompressor calls an ICMDataProc callback that you provide, which loads more compressed data. If you have not provided such a data-loading function, or if you want the decompressor to stop using your data-loading function, set this parameter to NIL. In this case, the entire image must be in memory at the location specified by the data parameter to DecompressSequenceFrame.

    bufferSize

    The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Data-loading functions allow decompressors to work with images that cannot fit in memory. During the decompression operation the decompressor calls the data-loading function whenever it has exhausted its supply of compressed data.

    Special Considerations

    There is no parameter to the DecompressSequenceBegin function that allows you to assign a data-loading function to a sequence.

  • Assigns a clipping region to a sequence.

    Declaration

    OSErr SetDSequenceMask ( ImageSequence seqID, RgnHandle mask );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    mask

    A handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you want to stop masking, set this parameter to NIL. The new region takes effect with the next frame in the sequence.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The decompressor draws only that portion of the decompressed image that lies within the specified clipping region. You should not dispose of this region until the Image Compression Manager is finished with the sequence, or until you set the mask either to NIL or to a different region by calling this function again.

  • Assigns a mapping matrix to a sequence.

    Declaration

    OSErr SetDSequenceMatrix ( ImageSequence seqID, MatrixRecordPtr matrix );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    matrix

    A MatrixRecord structure that specifies how to transform the image during decompression. You can use this structure to translate or scale the image during decompression. To set the matrix to identity, pass NIL in this parameter. The new matrix takes effect with the next frame in the sequence.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The decompressor uses the matrix to create special effects with the decompressed image, such as translating or scaling the image.

  • Assigns a blend matte to a sequence.

    Declaration

    OSErr SetDSequenceMatte ( ImageSequence seqID, PixMapHandle matte, const Rect *matteRect );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    matte

    A handle to a PixMap structure that contains a blend matte. You can use the blend matte to cause the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported pixel depth; the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If you want to turn off the blend matte, set this parameter to NIL.

    matteRect

    A pointer to a Rect structure that defines the boundary rectangle for the matte. The decompressor uses only that portion of the matte that lies within the specified rectangle. This rectangle must be the same size as the source rectangle you specify with SetDSequenceSrcRect or with the srcRect parameter to DecompressSequenceBegin. To use the matte's PixMap structure bounds as the boundary rectangle, pass NIL in this parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The decompressor uses the matte to blend the decompressed image into the destination pixel map. The new matte and matte boundary rectangle take effect with the next frame in the sequence. You should not dispose of the matte until the Image Compression Manager has finished with the sequence.

  • Defines the portion of an image to decompress.

    Declaration

    OSErr SetDSequenceSrcRect ( ImageSequence seqID, const Rect *srcRect );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    srcRect

    A pointer to a Rect structure that defines the portion of the image to decompress. This rectangle must lie within the boundary rectangle of the compressed image, which is defined by (0,0) and ((**desc).width,(**desc).height), where desc refers to the ImageDescription structure you supply to DecompressSequenceBegin. If the srcRect parameter is NIL, the rectangle is set to the Rect structure in the ImageDescription.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The decompressor acts on that portion of the compressed image that lies within this rectangle. A new source rectangle takes effect with the next frame in the sequence.

  • Sets the timecode value for a frame that is about to be decompressed.

    Declaration

    OSErr SetDSequenceTimeCode ( ImageSequence seqID, void *timeCodeFormat, void *timeCodeTime );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    timeCodeFormat

    A pointer to a TimeCodeDef structure. You provide the appropriate timecode definition information for the next frame to be decompressed.

    timeCodeTime

    A pointer to a TimeCodeRecord structure. You provide the appropriate time value for the next frame in the current sequence.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    QuickTime's video media handler uses this function to set the timecode information for a movie. When a movie that contains timecode information starts playing, the media handler calls this function as it processes the movie's first frame. The Image Compression Manager passes the timecode information straight through to the image decompressor component. That is, the Image Compression Manager does not make a copy of any of this timecode information. As a result, you must make sure that the data referred to by the timeCodeFormat and timeCodeTime parameters is valid until the next decompression operation completes.

  • Sets the mode used when drawing a decompressed image.

    Declaration

    OSErr SetDSequenceTransferMode ( ImageSequence seqID, short mode, const RGBColor *opColor );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    mode

    A constant (see below) that specifies the transfer mode to be used when drawing the decompressed image. See also Graphics Transfer Modes. See these constants:

    opColor

    Contains a pointer to the color for use in addPin, subPin, blend, and transparent operations. The Image Compression Manager passes this color to QuickDraw as appropriate. If NIL, the opcolor is left unchanged.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    For any given sequence, the default opColor value is 50 percent gray and the default mode is ditherCopy. The new mode takes effect with the next frame in the sequence.

  • Obtains the data rate parameters previously set with SetCSequenceDataRateParams.

    Declaration

    OSErr GetCSequenceDataRateParams ( ImageSequence seqID, DataRateParamsPtr params );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by CompressSequenceBegin.

    params

    Points to the data rate parameters structure associated with the sequence identifier specified in the seqID parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Communicates information to compressors that can constrain compressed data in a particular sequence to a specific data rate.

    Declaration

    OSErr SetCSequenceDataRateParams ( ImageSequence seqID, DataRateParamsPtr params );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    params

    A pointer to a DataRateParams structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Returns the current scale of the given screen graphics device.

    Declaration

    OSErr GDGetScale ( GDHandle gdh, Fixed *scale, short *flags );

    Parameters

    gdh

    A handle to a screen graphics device.

    scale

    Points to a fixed-point field to hold the scale result.

    flags

    Points to a short integer that returns the status parameter flags for the video driver. Currently, 0 is always returned in this field.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Returns the closest possible scaling that a particular screen device can be set to in a given pixel depth.

    Declaration

    OSErr GDHasScale ( GDHandle gdh, short depth, Fixed *scale );

    Parameters

    gdh

    A handle to a screen graphics device.

    depth

    The pixel depth of the screen device.

    scale

    Points to a fixed-point scale value. On input, this field should be set to the desired scale value. On output, this field will contain the closest scale available for the given depth. A scale of 0x10000 indicates normal size, 0x20000 indicates double size, and so on.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function returns scaling information for a particular screen device for a requested depth. This function allows you to query a screen device without actually changing it. For example, if you specify 0x20000 but the screen device does not support it, GDHasScale returns noErr and a scale of 0x10000. Because this function checks for a supported depth, your requested depth must be supported by the screen device.

    Special Considerations

    GDHasScale references the video driver through the graphics device structure.

  • Sets a screen graphics device to a new scale.

    Declaration

    OSErr GDSetScale ( GDHandle gdh, Fixed scale, short flags );

    Parameters

    gdh

    A handle to a screen graphics device.

    scale

    A fixed-point scale value.

    flags

    Points to a short integer. It returns the status parameter flags for the video driver. Currently, 0 is always returned in this field.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Returns an ImageDescription structure you can use to help create a sample description for an effect.

    Declaration

    OSErr MakeImageDescriptionForEffect ( OSType effectType, ImageDescriptionHandle *idh );

    Parameters

    effectType

    The four-character code identifying the type of effect to make an image description for. See Effects Codes.

    idh

    The handle of an ImageDescription structure. On entry, this parameter normally points to an ImageDescription structure whose contents are NIL. On return, the structure is correctly filled out for the selected effect type.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    To create a sample description, you create and fill out a data structure of type ImageDescription. This function simplifies this process. Only sample descriptions made with this function can be used in stacked effects, where one effect track acts as a source for another.

    The following sample code creates a sample description:.

    1. // MakeImageDescriptionForEffect coding example
    2. // Return a new image description with default and specified values.
    3. ImageDescriptionHandle QTEffSeg_MakeSampleDescription (
    4. OSType theEffectType, short theWidth, short theHeight)
    5. {
    6. ImageDescriptionHandle mySampleDesc =NIL;
    7. #if USES_MAKE_IMAGE_DESC_FOR_EFFECT
    8. OSErr myErr =noErr;
    9. // create a new sample description
    10. myErr =MakeImageDescriptionForEffect(theEffectType, &mySampleDesc);
    11. if (myErr !=noErr)
    12. return(NIL);
    13. #else
    14. // create a new sample description
    15. mySampleDesc =(ImageDescriptionHandle)
    16. NewHandleClear(sizeof(ImageDescription));
    17. if (mySampleDesc ==NIL)
    18. return(NIL);
    19. // fill in the fields of the sample description
    20. (**mySampleDesc).cType =theEffectType;
    21. (**mySampleDesc).idSize =sizeof(ImageDescription);
    22. (**mySampleDesc).hRes =72L << 16;
    23. (**mySampleDesc).vRes =72L << 16;
    24. (**mySampleDesc).frameCount =1;
    25. (**mySampleDesc).depth =0;
    26. (**mySampleDesc).clutID =-1;
    27. #endif
    28. (**mySampleDesc).vendor =kAppleManufacturer;
    29. (**mySampleDesc).temporalQuality =codecNormalQuality;
    30. (**mySampleDesc).spatialQuality =codecNormalQuality;
    31. (**mySampleDesc).width =theWidth;
    32. (**mySampleDesc).height =theHeight;
    33. return(mySampleDesc);
    34. }
  • Adds a preview to a file.

    Declaration

    OSErr AddFilePreview ( short resRefNum, OSType previewType, Handle previewData );

    Parameters

    resRefNum

    The resource file for this operation. You must have opened this resource file with write permission. If there is a preview in the specified file, the Movie Toolbox replaces that preview with a new one.

    previewType

    The resource type to be assigned to the preview. This type should correspond to the type of data stored in the preview. For example, if you have created a QuickDraw picture that you want to use as a preview for a file, you should set the previewType parameter to 'PICT'.

    previewData

    A handle to the preview data. For example, if the preview data is a picture, you would provide a picture handle.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    You must have created the preview data yourself. If the specified file already has a preview defined, the AddFilePreview function replaces it with the new preview.

  • Creates a preview for a file.

    Declaration

    OSErr MakeFilePreview ( short resRefNum, ICMProgressProcRecordPtr progress );

    Parameters

    resRefNum

    The resource file for this operation. You must have opened this resource file with write permission. If there is a preview in the specified file, the Movie Toolbox replaces that preview with a new one.

    progress

    A pointer to an ICMProgressProcRecord structure. During the process of creating the preview, the Movie Toolbox may occasionally call a function you provide in order to report its progress. You can then use this information to keep the user informed.

    Set this parameter to -1 to use the default progress function. If you specify a progress function, it must comply with the interface defined for Image Compression Manager progress functions; see "Image Compression Manager" in Inside Macintosh: QuickTime for more information. Set this parameter to NIL to prevent the Movie Toolbox from calling a progress function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    You should create a preview whenever you save a movie. You specify the file by supplying a reference to its resource file. You must have opened this resource file with write permission. If there is a preview in the specified file, the Movie Toolbox replaces that preview with a new one.

  • Determines the size, in bytes, of a compressed image.

    Declaration

    ComponentResult ADD_IMAGECODEC_BASENAME() GetCompressedImageSize

    Parameters

    desc

    A handle to the ImageDescription structure that defines the compressed image for the operation.

    data

    Points to the compressed image data. This pointer must contain a 32-bit clean address.

    bufferSize

    The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

    dataProc

    Points to an ICMDataProc callback. If the data stream is not all in memory when your program calls GetCompressedImageSize, the compressor calls a function you provide that loads more compressed data. If you have not provided a data-loading callback, set this parameter to NIL. In this case, the entire image must be in memory at the location specified by the data parameter.

    dataSize

    A pointer to a field that is to receive the size, in bytes, of the compressed image.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Most applications do not need to use this function because compressed images have a corresponding ImageDescription structure with a size field. You only need to use this function if you do not have an image description structure associated with your data; for example, when you are taking a compressed image out of a movie one frame at a time.

  • Determines the estimated amount of time required to compress a given image.

    Declaration

    ComponentResult ADD_IMAGECODEC_BASENAME() GetCompressionTime

    Parameters

    src

    A handle to the source image. The source image must be stored in a pixel map structure. The compressor uses only the bit depth of this image to determine the compression time. You may set this parameter to NIL if you are interested only in information about quality settings.

    srcRect

    A pointer to a rectangle defining the portion of the source image to compress. You may set this parameter to NIL if you are interested only in information about quality settings. GetCompressionTime then uses the bounds of the source pixel map.

    colorDepth

    The depth at which the image is to be compressed. 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

    cType

    You must set this parameter to a valid compressor type constant; see Codec Identifiers.

    codec

    Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). 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. See these constants:

    spatialQuality

    A pointer to a field containing a constant (see below) that defines the desired compressed image quality. The Image Compression Manager sets this field to the closest actual quality that the compressor can achieve. If you are not interested in this information, pass NIL in this parameter. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    temporalQuality

    A pointer to a field containing a constant (see below) that defines the desired temporal quality. Use this value only with images that are part of image sequences. The Image Compression Manager sets this field to the closest actual quality that the compressor can achieve. If you are not interested in this information, pass NIL in this parameter.

    compressTime

    A pointer to a field to receive the compression time in milliseconds. If the compressor cannot determine the amount of time required to compress the image or if the compressor does not support this function, this field is set to 0. If you are not interested in this information, pass NIL in this parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function allows you to verify that the quality settings you desire are supported by a given compressor component. You specify the compression characteristics, including compression type and quality, along with the image. The Image Compression Manager returns the maximum compression time for the specified image and parameters. Note that some compressors may not support this function. If the component you specify does not support this function, the Image Compression Manager returns a time value of 0.

  • Determines the maximum size an image will be after compression.

    Declaration

    ComponentResult ADD_IMAGECODEC_BASENAME() GetMaxCompressionSize

    Parameters

    src

    A handle to the source image. The source image must be stored in a pixel map structure. The compressor uses only the image's size and pixel depth to determine the maximum size of the compressed image.

    srcRect

    A pointer to a rectangle defining the portion of the source image that is to be compressed. You may set this parameter to NIL if you are interested only in information about quality settings. GetCompressionTime then uses the bounds of the source pixel map.

    colorDepth

    The depth at which the image is to be compressed. 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 GetCodecInfo.

    quality

    A constant (see below) that defines the desired compressed image quality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    cType

    You must set this parameter to a valid compressor type constant; see Codec Identifiers.

    codec

    A compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). 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. See these constants:

    size

    A pointer to a field to receive the size, in bytes, of the compressed image.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function returns the maximum resulting size for the specified image and parameters. Your application may then use this information to allocate memory for the compression operation. The following code sample illustrates its use:

    1. // GetMaxCompressionSize coding example
    2. // See "Discovering QuickTime," page 286
    3. PicHandle GetQTCompressedPict (PixMapHandle hpmImage)
    4. {
    5. long lMaxCompressedSize =0;
    6. Handle hCompressedData =NIL;
    7. Ptr pCompressedData;
    8. ImageDescriptionHandle hImageDesc =NIL;
    9. OSErr nErr;
    10. PicHandle hpicPicture =NIL;
    11. Rect rectImage =(**hpmImage).bounds;
    12. CodecType dwCodecType =kJPEGCodecType;
    13. CodecComponent codec =(CodecComponent)anyCodec;
    14. CodecQ dwSpatialQuality =codecNormalQuality;
    15. short nDepth =0; // let ICM choose depth
    16. nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,
    17. dwSpatialQuality,
    18. dwCodecType,
    19. (CompressorComponent)codec,
    20. &lMaxCompressedSize);
    21. if (nErr !=noErr)
    22. return NIL;
    23. hImageDesc =(ImageDescriptionHandle)NewHandle(4);
    24. hCompressedData =NewHandle(lMaxCompressedSize);
    25. if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {
    26. MoveHHi(hCompressedData);
    27. HLock(hCompressedData);
    28. pCompressedData =StripAddress(*hCompressedData);
    29. nErr =CompressImage(hpmImage,
    30. &rectImage,
    31. dwSpatialQuality,
    32. dwCodecType,
    33. hImageDesc,
    34. pCompressedData);
    35. if (nErr ==noErr) {
    36. ClipRect(&rectImage);
    37. hpicPicture =OpenPicture(&rectImage);
    38. nErr =DecompressImage(pCompressedData,
    39. hImageDesc,
    40. hpmImage,
    41. &rectImage,
    42. &rectImage,
    43. srcCopy,
    44. NIL);
    45. ClosePicture();
    46. }
    47. if (theErr || (GetHandleSize((Handle)hpicPicture) ==
    48. sizeof(Picture))) {
    49. KillPicture(hpicPicture);
    50. hpicPicture =NIL;
    51. }
    52. }
    53. if (hImageDesc !=NIL)
    54. DisposeHandle((Handle)hImageDesc);
    55. if (hCompressedData !=NIL)
    56. DisposeHandle(hCompressedData);
    57. return hpicPicture;
    58. }
  • Compares a compressed image to a picture stored in a pixel map and returns a value indicating the relative similarity of the two images.

    Declaration

    ComponentResult ADD_IMAGECODEC_BASENAME() GetSimilarity

    Parameters

    src

    A handle to the noncompressed image. The image must be stored in a pixel map structure.

    srcRect

    A pointer to a rectangle defining the portion of the image to compare to the compressed image. This rectangle should be the same size as the image described by the ImageDescription structure specified by the desc parameter.

    desc

    A handle to the ImageDescription structure that defines the compressed image for the operation.

    data

    Points to the compressed image data. This pointer must contain a 32-bit clean address.

    similarity

    A pointer to a field that is to receive the similarity value. The compressor sets this field to reflect the relative similarity of the two images. Valid values range from 0 (completely different) to 1.0 (identical).

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Determines the version of the installed Image Compression Manager.

    Declaration

    OSErr CodecManagerVersion ( long *version );

    Parameters

    version

    A pointer to a long integer that is to receive the version information. The Image Compression Manager returns its version number into this location. The version number is a long integer value.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function returns the version information as a long integer value. Use this function to retrieve the version number associated with the Image Compression Manager that is installed on a particular computer.

    Special Considerations

    The Image Compression Manager provides a number of functions that allow your application to obtain information about the facilities available for image compression or about compressed images. Your application may use some of these functions to select a specific compressor or decompressor for a given operation or to determine how much memory to allocate to receive a decompressed image. In addition, your application may use some of these functions to determine the capabilities of the components that are available on the user's computer system. You can then condition the options your program makes available to the user based on the user's system configuration.

  • Disposes of the compressor name list structure you obtained by calling GetCodecNameList.

    Declaration

    OSErr DisposeCodecNameList ( CodecNameSpecListPtr list );

    Parameters

    list

    Points to the compressor name list to be disposed of. You obtain the compressor list by calling GetCodecNameList.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Determines which of the installed compressors or decompressors has been chosen to field requests made by using one of the special compressor identifiers.

    Declaration

    OSErr FindCodec ( CodecType cType, CodecComponent specCodec, CompressorComponent *compressor, DecompressorComponent *decompressor );

    Parameters

    cType

    You must set this parameter to a valid compressor type constant; see Codec Identifiers.

    specCodec

    A special codec identifier value (see below). See these constants:

    compressor

    A pointer to a field to receive the identifier for the compressor component. The Image Compression Manager returns the identifier of the compressor that meets the special characteristics you specify in the specCodec parameter. Note that this identifier may differ from the value of the field referred to by the decompressor field. The Image Compression Manager sets this field to 0 if it cannot find a suitable compressor component. Set this parameter to NIL if you do not want this information.

    decompressor

    A pointer to a field to receive the identifier for the decompressor component. The Image Compression Manager returns the identifier of the decompressor that meets the special characteristics you specify in the specCodec parameter. Note that this identifier may differ from the value of the field referred to by the compressor field. The Image Compression Manager sets this field to 0 if it cannot find a suitable decompressor component. Set this parameter to NIL if you do not want this information.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Some Image Compression Manager functions allow you to specify a particular compressor component by its identifier. For example, you may use the codec parameter to CompressSequenceBegin to specify a particular compressor to do the compression. The Image Compression Manager also supports several special identifiers (see specCodec Constants, above) that allow you to exert some control over the component for a given action without having to know its identifier.

  • Returns information about a single compressor component.

    Declaration

    ComponentResult ADD_IMAGECODEC_BASENAME() GetCodecInfo

    Parameters

    info

    A pointer to a CodecInfo structure. GetCodecInfo returns detailed information about the appropriate compressor component in this structure.

    cType

    Set this parameter to a valid compressor type constant; see Codec Identifiers. If you want information about any compressor of the type specified by this parameter, set the codec parameter to 0. The Image Compression Manager then returns information about the first compressor it finds of the type you have specified.

    codec

    Set this parameter to the component identifier of the specific compressor for the request, or to 0 for any compressor. Component identifiers are available in the CodecNameSpecList structure returned by GetCodecNameList.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Retrieves a list of installed compressor components or types.

    Declaration

    OSErr GetCodecNameList ( CodecNameSpecListPtr *list, short showAll );

    Parameters

    list

    A pointer to a field that is to receive a pointer to a CodecNameSpecList structure. The Image Compression Manager creates the appropriate list and returns a pointer to that list in the field specified by this parameter.

    showAll

    A short integer that controls the contents of the list. Set this parameter to 1 to receive a list of the names of all installed compressor components; the returned list contains one entry for each installed compressor. Set this parameter to 0 to receive a list of the types of installed compressor components; the returned list contains one entry for each installed compressor type.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The CodecType data type defines a field in the CodecNameSpec structure that identifies the compression method employed by a given compressor component. See Codec Identifiers. Apple Computer's Developer Technical Support group assigns these values so that they remain unique. These values correspond, in turn, to text strings that can identify the compression method to the user.

    Special Considerations

    GetCodecNameList creates the CodecNameSpecList structure in your application's current heap zone.

  • Signals the completion of a decompression operation.

    Declaration

    void ICMDecompressComplete ( ImageSequence seqID, OSErr err, short flag, ICMCompletionProcRecordPtr completionRtn );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    err

    Indicates whether the operation succeeded or failed. Set this parameter to 0 for successful operations. For failed operations, set the error code appropriate for the failure. For canceled operations (for example, when the ICM calls your component's ImageCodecFlush function), set this parameter to -1.

    flag

    Completion flags (see below). Note that you may set more than one of these flags to 1. See these constants:

    • codecCompletionSource

    • codecCompletionDest

    • codecCompletionDontUnshield

    completionRtn

    A pointer to an ICMCompletionProcRecord structure. That structure identifies the application's completion function and contains a reference constant associated with the frame. Your component obtains this structure as part of the CodecDecompressParams structure provided by the Image Compression Manager at the start of the decompression operation.

    Discussion

    Your component must call this function at the end of decompression operations.

    Special Considerations

    Prior to QuickTime 2.0, decompressor components called the application's completion function directly. For compatibility, that method is still supported except for scheduled asynchronous decompression operations, which must use the ICMDecompressComplete call. Newer decompressors should always use ICMDecompressComplete rather than calling the completion function directly, regardless of the type of decompression operation.

  • Hides the cursor during decompression operations.

    Declaration

    OSErr ICMShieldSequenceCursor ( ImageSequence seqID );

    Parameters

    seqID

    The unique sequence identifier, assigned by CompressSequenceBegin or DecompressSequenceBegin, for which to shield the cursor.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    For correct image display behavior, the cursor must be shielded (hidden) during decompression. By default, the Image Compression Manager handles the cursor for you, hiding it at the beginning of a decompression operation and revealing it at the end. With scheduled asynchronous decompression, however, the ICM cannot do as precise a job of managing the cursor, because it does not know exactly when scheduled operations actually begin and end. While the ICM can still manage the cursor, it must hide the cursor when each request is queued, rather than when the request is serviced. This may result in the cursor remaining hidden for long periods of time. To achieve better cursor behavior, you can choose to manage the cursor in your decompressor component. If you so choose, you can use this function to hide the cursor; the ICM displays the cursor when you call ICMDecompressComplete. In this manner, the cursor is hidden only when your component is decompressing and displaying the frame.

    Special Considerations

    This function may be called at interrupt time.

  • Disposes transcoded image data.

    Declaration

    OSErr ImageTranscodeDisposeFrameData ( ImageTranscodeSequence its, void *dstData );

    Parameters

    its

    The image transcoder sequence that was used to generate the transcoded data.

    dstData

    A pointer to the transcoded image data generated by the ImageTranscodeFrame function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    When the transcoded image data returned by ImageTranscodeFrame is no longer needed, use this function to dispose of the data. Only the image transcoder that generated the data can properly dispose of it.

  • Transcodes a frame of image data.

    Declaration

    OSErr ImageTranscodeFrame ( ImageTranscodeSequence its, void *srcData, long srcDataSize, void **dstData, long *dstDataSize );

    Parameters

    its

    The image transcoder sequence to use to perform the transcoding operation.

    srcData

    A pointer to the source data to transcode.

    srcDataSize

    The size of the compressed source image data in bytes.

    dstData

    On return, a pointer to the transcoded image data.

    dstDataSize

    On return, the size of the transcoded image data.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    After creating the image transcoder sequence, using ImageTranscodeSequenceBegin, use this function to transcode a frame of image data. The caller is responsible for disposing of the transcoded data using ImageTranscodeDisposeFrameData.

  • Initiates an image transcoder sequence operation.

    Declaration

    OSErr ImageTranscodeSequenceBegin ( ImageTranscodeSequence *its, ImageDescriptionHandle srcDesc, OSType destType, ImageDescriptionHandle *dstDesc, void *data, long dataSize );

    Parameters

    its

    The image transcoder sequence identifier. If the operation fails, the value pointed to is set to NIL.

    srcDesc

    The ImageDescription structure for the source compressed image data.

    destType

    The desired compression format into which to transcode the source data.

    dstDesc

    On return, an ImageDescription structure for the data which will be generated by the image transcoding sequence.

    data

    A pointer to first frame of compressed data to transcode. Set to NIL of not available.

    dataSize

    The size of the compressed data, in bytes. Set to 0 if no data is provided.

    Return Value

    See Error Codes. Returns noErr if there is no error. If no transcoder is available to perform the requested transcoding operation, a cantFindHandler error is returned.

    Discussion

    This function begins an image transcoder sequence operation and returns the sequence identifier in the its parameter. The caller is responsible for disposing of the ImageDescription structure that is returned in the dstDesc parameter.

  • Ends an image transcoder sequence operation.

    Declaration

    OSErr ImageTranscodeSequenceEnd ( ImageTranscodeSequence its );

    Parameters

    its

    The identifier of the image transcoder sequence to dispose. It is safe to pass a value of 0 in this parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    You must call this function to terminate an image transcoder sequence operation and dispose of the sequence.

  • Creates a thumbnail picture from a specified Picture structure.

    Declaration

    OSErr MakeThumbnailFromPicture ( PicHandle picture, short colorDepth, PicHandle thumbnail, ICMProgressProcRecordPtr progressProc );

    Parameters

    picture

    A handle to the image from which the thumbnail is to be extracted. The image must be stored in a Picture structure.

    colorDepth

    The depth at which the image is likely to be viewed. 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.

    thumbnail

    A handle to the destination Picture structure for the thumbnail image. The compressor resizes this handle for the resulting data.

    progressProc

    A pointer to an ICMProgressProcRecord structure. During the operation, the Image Compression Manager will occasionally call a function to report its progress. You can provide a function through this structure. 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.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Creates a thumbnail picture from a specified picture file.

    Declaration

    OSErr MakeThumbnailFromPictureFile ( short refNum, short colorDepth, PicHandle thumbnail, ICMProgressProcRecordPtr progressProc );

    Parameters

    refNum

    A file reference number for the PICT file from which the thumbnail is to be extracted.

    colorDepth

    The depth at which the image is likely to be viewed. 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.

    thumbnail

    A handle to the destination picture structure for the thumbnail image. The compressor resizes this handle for the resulting data.

    progressProc

    A pointer to an ICMProgressProcRecord structure. During the operation, the Image Compression Manager will occasionally call a function to report its progress. You can provide a function through this structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Creates a thumbnail picture from a specified PixMap structure.

    Declaration

    OSErr MakeThumbnailFromPixMap ( PixMapHandle src, const Rect *srcRect, short colorDepth, PicHandle thumbnail, ICMProgressProcRecordPtr progressProc );

    Parameters

    src

    A handle to the image from which the thumbnail is to be extracted. The image must be stored in a PixMap structure.

    srcRect

    A pointer to a Rect structure that defines the portion of the image to use for the thumbnail.

    colorDepth

    The depth at which the image is likely to be viewed. 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.

    thumbnail

    A handle to the destination picture structure for the thumbnail image. The compressor resizes this handle for the resulting data.

    progressProc

    A pointer to an ICMProgressProcRecord structure. During the operation, the Image Compression Manager will occasionally call a function to report its progress. You can provide a function through this structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Concatenates two matrices, combining the transformations described by both matrices into a single matrix.

    Declaration

    void ConcatMatrix ( const MatrixRecord *a, MatrixRecord *b );

    Parameters

    a

    A pointer to the source matrix.

    b

    A pointer to the destination matrix. The ConcatMatrix function performs a matrix multiplication operation on the two matrices and leaves the result in the matrix specified by this parameter.

    Discussion

    This is a matrix multiplication operation, as a result of which [B] =[B] x [A]. Note that matrix multiplication is not commutative.

  • Copies the contents of one matrix into another matrix.

    Declaration

    void CopyMatrix ( const MatrixRecord *m1, MatrixRecord *m2 );

    Parameters

    m1

    The source matrix for the copy operation.

    m2

    A pointer to the destination matrix for the copy operation. CopyMatrix copies the values from the matrix specified by the m1 parameter into this matrix.

  • Compares two matrices and returns a result that indicates whether the matrices are equal.

    Declaration

    Boolean EqualMatrix ( const MatrixRecord *m1, const MatrixRecord *m2 );

    Parameters

    m1

    A pointer to one matrix for the compare operation.

    m2

    A pointer to the other matrix for the compare operation.

    Return Value

    TRUE if the matrices are equal, FALSE otherwise.

  • Obtains information about a matrix.

    Declaration

    short GetMatrixType ( const MatrixRecord *m );

    Parameters

    m

    Points to the MatrixRecord structure for this operation.

    Return Value

    A constant (see below) that defines the type of the matrix.

  • Creates a new matrix that is the inverse of a specified matrix.

    Declaration

    Boolean InverseMatrix ( const MatrixRecord *m, MatrixRecord *im );

    Parameters

    m

    A pointer to the source MatrixRecord structure for the operation.

    im

    A pointer to a MatrixRecord structure that is to receive the new matrix. The function updates this structure so that it contains a matrix that is the inverse of that specified by the m parameter.

    Return Value

    A Boolean value of TRUE if InverseMatrix was able to create an inverse matrix, FALSE otherwise.

  • Alters an existing matrix so that it defines a transformation from one rectangle to another.

    Declaration

    void MapMatrix ( MatrixRecord *matrix, const Rect *fromRect, const Rect *toRect );

    Parameters

    matrix

    A pointer to a matrix structure. The MapMatrix function modifies this matrix so that it performs a transformation in the rectangle specified by the toRect parameter that is analogous to the transformation it currently performs in the rectangle specified by the fromRect parameter.

    fromRect

    A pointer to the source Rect structure.

    toRect

    A pointer to the destination Rect structure.

    Discussion

    MapMatrix affects only the scaling and translation attributes of the matrix.

  • Creates a matrix that performs the translate and scale operation described by the relationship between two rectangles.

    Declaration

    void RectMatrix ( MatrixRecord *matrix, const Rect *srcRect, const Rect *dstRect );

    Parameters

    matrix

    A pointer to a MatrixRecord structure. This function updates the contents of this matrix so that the matrix describes a transformation from points in the rectangle specified by the srcRect parameter to points in the rectangle specified by the dstRect parameter. The previous contents of the matrix are ignored.

    srcRect

    A pointer to the source Rect structure.

    dstRect

    A pointer to the destination Rect structure.

  • Modifies the contents of a matrix so that it defines a rotation operation.

    Declaration

    void RotateMatrix ( MatrixRecord *m, Fixed degrees, Fixed aboutX, Fixed aboutY );

    Parameters

    m

    A pointer to a MatrixRecord structure.

    degrees

    The number of degrees of rotation.

    aboutX

    The x coordinate of the anchor point of rotation.

    aboutY

    The y coordinate of the anchor point of rotation.

    Discussion

    This function updates the contents of a matrix so that the matrix describes a rotation operation; that is, it concatenates the rotation transformations onto whatever was initially in the matrix structure. You specify the direction and amount of rotation with the degrees parameter. You specify the point of rotation with the aboutX and aboutY parameters.

  • Modifies the contents of a matrix so that it defines a scaling operation.

    Declaration

    void ScaleMatrix ( MatrixRecord *m, Fixed scaleX, Fixed scaleY, Fixed aboutX, Fixed aboutY );

    Parameters

    m

    A pointer to a MatrixRecord structure. The ScaleMatrix function updates the contents of this matrix so that the matrix describes a scaling operation; that is, it concatenates the respective transformations onto whatever was initially in the matrix structure. You specify the magnitude of the scaling operation with the scaleX and scaleY parameters. You specify the anchor point with the aboutX and aboutY parameters.

    scaleX

    The scaling factor applied to x coordinates.

    scaleY

    The scaling factor applied to y coordinates.

    aboutX

    The x coordinate of the anchor point.

    aboutY

    The y coordinate of the anchor point.

  • Sets the contents of a matrix so that it performs no transformation.

    Declaration

    void SetIdentityMatrix ( MatrixRecord *matrix );

    Parameters

    matrix

    A pointer to a MatrixRecord structure. The function updates the contents of this matrix so that the matrix describes the identity matrix.

  • Modifies the contents of a matrix so that it defines a skew transformation.

    Declaration

    void SkewMatrix ( MatrixRecord *m, Fixed skewX, Fixed skewY, Fixed aboutX, Fixed aboutY );

    Parameters

    m

    A pointer to the matrix for this operation. The SkewMatrix function updates the contents of the MatrixRecord structure so that it defines a skew operation; it concatenates the respective transformations onto whatever was initially in the matrix structure. You specify the magnitude and direction of the skew operation with the skewX and skewY parameters. You specify an anchor point with the aboutX and aboutY parameters.

    skewX

    The skew value to be applied to x coordinates.

    skewY

    The skew value to be applied to y coordinates.

    aboutX

    The x coordinate of the anchor point.

    aboutY

    The y coordinate of the anchor point.

    Discussion

    A skew operation alters the display of an element along one dimension. For example, converting a rectangle into a parallelogram is a skew operation.

  • Adds a translation value to a specified matrix.

    Declaration

    void TranslateMatrix ( MatrixRecord *m, Fixed deltaH, Fixed deltaV );

    Parameters

    m

    A pointer to the MatrixRecord structure for this operation.

    deltaH

    The value to be added to the x coordinate translation value.

    deltaV

    The value to be added to the y coordinate translation value.

  • Locates and opens a graphics importer component that can be used to draw the image from specified data reference.

    Declaration

    OSErr GetGraphicsImporterForDataRef ( Handle dataRef, OSType dataRefType, ComponentInstance *gi );

    Parameters

    dataRef

    The data reference to be drawn using a graphics importer component.

    dataRefType

    The type of data reference pointed to by the dataRef parameter; see Data References. For alias-based data references, the dataRef handle contains an AliasRecord and dataRefType is set to rAliasType.

    gi

    On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found, this parameter will be set to NIL. If GetGraphicsImporterForDataRef is able to locate a graphics importer for the data reference, the returned graphics importer ComponentInstance will already be set up to draw from the specified data reference to the current port.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function tries to locate a graphics importer component for the specified data reference by checking the file extension (such as .GIF or .JPG), the Macintosh file type, and the MIME type of the file. The file extension is retrieved from the data reference by using DataHGetFileName to call the data handler associated with the data reference. If a graphics importer cannot be found using the file's type, file extension, or MIME type, GetGraphicsImporterForDataRef asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming; to bypass it, call GetGraphicsImporterForDataRefWithFlags instead.

    Special Considerations

    The caller of GetGraphicsImporterForDataRef is responsible for closing the returned ComponentInstance using CloseComponent. You must call CloseComponent when you are finished with the importer.

  • Locates and opens a graphics importer component for a data reference with flags that control the search process.

    Declaration

    OSErr GetGraphicsImporterForDataRefWithFlags ( Handle dataRef, OSType dataRefType, ComponentInstance *gi, long flags );

    Parameters

    dataRef

    The data reference to be drawn using a graphics importer component.

    dataRefType

    The type of data reference pointed to by the dataRef parameter; see Data References. For alias-based data references, the dataRef handle contains an AliasRecord and dataRefType is set to rAliasType.

    gi

    On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found, this parameter will be set to NIL. If GetGraphicsImporterForDataRefWithFlags is able to locate a graphics importer for the data reference, the returned graphics importer ComponentInstance will already be set up to draw from the specified data reference to the current port.

    flags

    Contains flags (see below) that control the graphics importer search process. See these constants:

    • kDontUseValidateToFindGraphicsImporter

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function tries to locate a graphics importer component for the specified data reference by checking the file extension (such as .GIF or .JPG), the Macintosh file type, and the MIME type of the file. The file extension is retrieved from the data reference by using DataHGetFileName to call the data handler associated with the data reference. If a graphics importer cannot be found using the file's type, file extension, or MIME type, this function asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming; to bypass it, pass kDontUseValidateToFindGraphicsImporter in the flags parameter.

  • Locates and opens a graphics importer component that can be used to draw a specified file.

    Declaration

    OSErr GetGraphicsImporterForFile ( const FSSpec *theFile, ComponentInstance *gi );

    Parameters

    theFile

    The file to be drawn using a graphics importer component.

    gi

    On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found for the specified file, the gi will be set to NIL. If GetGraphicsImporterForFile is able to locate a graphics importer for the file, the returned graphics importer ComponentInstance will already be set up to draw the specified file to the current port.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function first tries to locate a graphics importer component for the specified file based on its file type. If it is unable to locate a graphics importer component based on the Macintosh file type, or the call is made on a non-Macintosh file, GetGraphicsImporterForFile will try to locate a graphics importer component based on the file extension (such as .JPG or .GIF). If a graphics importer cannot be found using the file's type or extension, GetGraphicsImporterForFile asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming. To bypass the validation attempt, call GetGraphicsImporterForFileWithFlags instead. The following code sample illustrates the use of GetGraphicsImporterForFile:

    1. // Get a graphics importer for the image file, determine the natural size
    2. // of the image, and draw the image
    3. // See "Discovering QuickTime," page 274
    4. void drawFile(const FSSpec *fss, const Rect *boundsRect)
    5. {
    6. GraphicsImportComponent gi;
    7. GetGraphicsImporterForFile(fss, &gi);
    8. GraphicsImportSetBoundsRect(gi, boundsRect);
    9. GraphicsImportDraw(gi);
    10. CloseComponent(gi);
    11. }

    Special Considerations

    The caller of GetGraphicsImporterForFile is responsible for closing the returned ComponentInstance using CloseComponent.

  • Selects the deepest of all available graphics devices, while treating 16-bit and 32-bit screens as having equal depth.

    Declaration

    OSErr GetBestDeviceRect ( GDHandle *gdh, Rect *rp );

    Parameters

    gdh

    A pointer to the handle of the rectangle for the chosen device. If you do not need the information in this parameter returned, specify NIL.

    rp

    A pointer to the rectangle that is adjusted for the height of the menu bar if the device is the main device. If you do not need the information in this parameter returned, specify NIL.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function does not center a rectangle on a device. Rather, it returns the rectangle for the best device. The following code sample illustrates its use:

    1. // GetBestDeviceRect coding example
    2. // See "Discovering QuickTime," page 265
    3. WindowRef MakeMyWindow (void)
    4. {
    5. WindowRef pMacWnd;
    6. Rect rectWnd ={0, 0, 120, 160};
    7. Rect rectBest;
    8. // figure out the best monitor for the window
    9. GetBestDeviceRect(NIL, &rectBest);
    10. // put the window in the top left corner of that monitor
    11. OffsetRect(&rectWnd, rectBest.left + 10, rectBest.top + 50);
    12. // create the window
    13. pMacWnd =NewCWindow(NIL, &rectWnd, "\pGrabber",
    14. TRUE, noGrowDocProc, (WindowRef)-1, TRUE, 0);
    15. // set the port to the new window
    16. SetPort(pMacWnd);
    17. return pMacWnd;
    18. }
  • Creates an offscreen graphics world.

    Declaration

    ComponentResult ADD_IMAGECODEC_BASENAME() NewImageGWorld

    Parameters

    gworld

    A pointer to a graphic world created using the width, height, depth, and color table specified in the ImageDescription structure pointed to in the idh parameter.

    idh

    A handle to an ImageDescription structure that contains information for the graphics world pointed to by the gworld parameter.

    flags

    Graphics world creation flags (see below). The pixPurge, noNewDevice, useTempMem, keepLocal, pixelsPurgeable, and pixelsLocked flags are commands to this function; the others are returned by this function. See these constants:

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Adds an extension to an ImageDescription structure.

    Declaration

    OSErr AddImageDescriptionExtension ( ImageDescriptionHandle desc, Handle extension, long idType );

    Parameters

    desc

    A handle to the ImageDescription structure to add the extension to.

    extension

    The handle containing the extension data.

    idType

    A four-byte signature identifying the type of data being added to the ImageDescription.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function allows the application to add custom data to an ImageDescriptionHandle. This data could be specific to the compressor component referenced by the ImageDescription structure.

    Special Considerations

    The Image Compression Manager makes a copy of the data referred to by the extension parameter. Thus, your application should dispose its copy of the data when it is no longer needed.

  • Counts the number of extensions of a given type in an ImageDescriptionHandle.

    Declaration

    OSErr CountImageDescriptionExtensionType ( ImageDescriptionHandle desc, long idType, long *count );

    Parameters

    desc

    A handle to the ImageDescription structure with the extensions to be counted.

    idType

    Indicates the type of extension to be counted in the specified ImageDescription structure. Set the value of this parameter to 0 to match any extension, and return a count of all of the extensions.

    count

    A pointer to an integer that indicates how many extensions of the given type are in the given ImageDescription structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    When used with GetNextImageDescriptionExtensionType, this function allows the application to determine the total set of extensions present in the ImageDescription structure designated by desc.

  • Returns a new handle with the data from a specified image description extension.

    Declaration

    OSErr GetImageDescriptionExtension ( ImageDescriptionHandle desc, Handle *extension, long idType, long index );

    Parameters

    desc

    A handle to the appropriate ImageDescription structure.

    extension

    A pointer to a field to receive a handle to the returned data. The GetImageDescriptionExtension function returns the extended data for the image described by the ImageDescription structure referred to by the desc parameter. The function correctly sizes the handle for the data it returns.

    idType

    Specifies the extension's type value. Use this parameter to determine the data type of the extension. This parameter contains a four-character code, similar to an OSType field value.

    index

    The index of the extension to retrieve. This is a number between 1 and the count returned by CountImageDescriptionExtensionType.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function allows the application to get a copy of a specified image description extension. Note that each compressor type may have its own format for the extended data that is stored with an image. The extended data is similar in concept to the user data that applications can associate with QuickTime movies. Once you have added extended data to an image, you cannot delete it.

    Special Considerations

    The Image Compression Manager allocates a new handle and passes it back in the extension parameter. Your application should dispose of the handle when it is no longer needed.

  • Retrieves an image description structure extension type.

    Declaration

    OSErr GetNextImageDescriptionExtensionType ( ImageDescriptionHandle desc, long *idType );

    Parameters

    desc

    A handle to an ImageDescription structure.

    idType

    A pointer to an integer that indicates the type of the extension after which this function is to return the next extension type. Point to a value of 0 to return the first type found.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function allows your application to search for all the types of extensions in an ImageDescription structure. The idType parameter should be set to 0 to start the search. When no more extension types can be found, the function will set this field to 0.

  • For a given pixel format, returns the depth value that should be used in image descriptions.

    Declaration

    short QTGetPixelFormatDepthForImageDescription ( OSType PixelFormat );

    Parameters

    PixelFormat

    The image description's pixel format; see Pixel Formats.

    Return Value

    The pixel depth for that format.

    Discussion

    Given a pixel format, this function returns the corresponding depth value that should be used in image descriptions. Such a value is not the literal number of bits per pixel, but the closest corresponding classic QuickDraw depth. For any pixel format with an alpha channel, it is 32. For grayscale pixel formats of 8 or more bits per pixel, it is 40. For color quantized to 5 or 6 bits per component, it is 16. For all other color pixel formats, it is 24.

  • Removes a specified extension from an ImageDescription structure.

    Declaration

    OSErr RemoveImageDescriptionExtension ( ImageDescriptionHandle desc, long idType, long index );

    Parameters

    desc

    A handle to an ImageDescription structure.

    idType

    The type of extension to remove.

    index

    The index of the extension to remove. This is a number between 1 and the count returned by CountImageDescriptionExtensionType.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function allows an application to remove a specified extension from an ImageDescription structure. Note that any extensions that are present in the structure after the deleted extension will have their index numbers renumbered.

  • Compresses a single-frame image stored as a picture structure and places the result in another picture.

    Declaration

    OSErr CompressPicture ( PicHandle srcPicture, PicHandle dstPicture, CodecQ quality, CodecType cType );

    Parameters

    srcPicture

    A handle to the source image, stored as a picture.

    dstPicture

    A handle to the destination for the compressed image. The compressor resizes this handle for the result data.

    quality

    A constant (see below) that defines the desired compressed image quality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    cType

    You must set this parameter to a valid compressor identifier; see Codec Identifiers. If the value passed in is 0, or 'raw ', and the source picture is compressed, the destination picture is created as an uncompressed picture and does not require QuickTime for its display.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function compresses only image data. Any other types of data in the picture, such as text, graphics primitives, and previously compressed images, are not modified in any way and are passed through to the destination picture. This function supports parameters governing image quality and compressor type. The compressor infers the other compression parameters from the image data in the source picture.

    Special Considerations

    If a picture with multiple pixel maps and other graphical objects is passed, the pixel maps will be compressed individually and the other graphic objects will not be affected. This function does not use the graphics port.

  • Compresses a single-frame image stored as a picture file and places the result in another picture file.

    Declaration

    OSErr CompressPictureFile ( short srcRefNum, short dstRefNum, CodecQ quality, CodecType cType );

    Parameters

    srcRefNum

    A file reference number for the source 'PICT' file.

    dstRefNum

    A file reference number for the destination 'PICT' file. Note that the compressor overwrites the contents of the file referred to by dstRefNum. You must open this file with write permission. The destination file can be the same as the source file specified by the srcRefNum parameter.

    quality

    A constant (see below) that defines the desired compressed image quality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    cType

    A compressor type. You must set this parameter to a valid compressor type constant; see Codec Identifiers. If the value passed in is 0, or 'raw-', and the source picture is compressed, the destination picture is created as an uncompressed picture and does not require QuickTime to be displayed.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function supports parameters governing image quality and compressor type. The compressor infers the other compression parameters from the image data in the source picture file.

  • Draws an image from a specified picture file in the current graphics port.

    Declaration

    OSErr DrawPictureFile ( short refNum, const Rect *frame, ICMProgressProcRecordPtr progressProc );

    Parameters

    refNum

    A file reference number for the source PICT file.

    frame

    A pointer to the rectangle into which the image is to be loaded. The compressor scales the source image to fit into this destination rectangle.

    progressProc

    Points to an ICMProgressProc callback. During the operation, the draw function may occasionally call a function you provide in order to report its progress; see ICMProgressProcRecord. If you have not provided a progress function, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function draws the picture that it finds in the picture file specified by the refNum parameter within the rectangle specified by the frame parameter. The Image Compression Manager performs any spooling that may be necessary when reading the picture file. Specify a clipping region appropriate for your picture before drawing it. If the clipping region is very large (as it is when a graphics port is initialized) and you want to scale the picture, the clipping region can become invalid when DrawPictureFile scales the clipping region, in which case your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when DrawPictureFile draws it. Setting a clipping region equal to the port rectangle of the current graphics port always sets a valid clipping region.

    Special Considerations

    When it scales fonts, DrawPictureFile changes the size of the font instead of scaling the bits. However, the widths used by bitmap fonts are not always linear. For example, the 12-point width isn't exactly 1/2 of the 24-point width. This can cause lines of text to become slightly longer or shorter as the picture is scaled. The easiest way to avoid such problems is to specify a destination rectangle that is the same size as the bounding rectangle for the picture.

  • Draws an image that is stored as a picture into the current graphics port and trims that image to fit a specified region.

    Declaration

    OSErr DrawTrimmedPicture ( PicHandle srcPicture, const Rect *frame, RgnHandle trimMask, short doDither, ICMProgressProcRecordPtr progressProc );

    Parameters

    srcPicture

    A handle to the source image, stored as a picture.

    frame

    A pointer to the rectangle into which the decompressed image is to be loaded.

    trimMask

    A handle to a clipping region in the destination coordinate system. The decompressor applies this mask to the destination image and ignores any image data that fall outside the specified region. Set this parameter to NIL if you do not want to clip the source image.

    doDither

    Indicates whether to dither the image. Use this parameter if you want the image to be dithered when it is displayed on a lower-resolution screen (see below). See these constants:

    • defaultDither

    • forceDither

    • suppressDither

    progressProc

    A pointer to an ICMProgressProc callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided a progress function, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function works with compressed image data; the source data stays compressed. The function trims the image to fit the specified clipping region. Note that if you just use a clip while making a picture, the data (though not visible) is still stored in the picture.

  • Draws an image that is stored as a picture file into the current graphics port and trims that image to fit a specified region.

    Declaration

    OSErr DrawTrimmedPictureFile ( short srcRefnum, const Rect *frame, RgnHandle trimMask, short doDither, ICMProgressProcRecordPtr progressProc );

    Parameters

    srcRefnum

    A file reference number for the source PICT file.

    frame

    A pointer to the rectangle into which the decompressed image is to be loaded.

    trimMask

    A handle to a clipping region in the destination coordinate system. The decompressor applies this mask to the destination image and ignores any image data that fall outside the specified region. Set this parameter to NIL if you do not want to clip the source image. In this case, this function acts like DrawPictureFile.

    doDither

    Indicates whether to dither the image. Use this parameter if you want the image to be dithered when it is displayed on a lower-resolution screen (see below). See these constants:

    • defaultDither

    • forceDither

    • suppressDither

    progressProc

    A pointer to an ICMProgressProc callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided a progress function, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    You can use this function to save part of a picture, since the image data that is not within the trim region is ignored and is not included in the destination picture file. All the remaining objects in the resulting object are clipped.

  • Compresses a single-frame image stored as a picture structure and places the result in another picture, with added control over the compression process.

    Declaration

    OSErr FCompressPicture ( PicHandle srcPicture, PicHandle dstPicture, short colorDepth, CTabHandle ctable, CodecQ quality, short doDither, short compressAgain, ICMProgressProcRecordPtr progressProc, CodecType cType, CompressorComponent codec );

    Parameters

    srcPicture

    A handle to the source image, stored as a picture.

    dstPicture

    A handle to the destination for the compressed image. The compressor resizes this handle for the result data.

    colorDepth

    The depth at which the image is to be compressed. 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.

    ctable

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

    quality

    A constant that defines the desired compressed image quality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    doDither

    A constant (see below) that indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. See these constants:

    • defaultDither

    • forceDither

    • suppressDither

    compressAgain

    Indicates whether to recompress compressed image data in the picture. Use this parameter to control whether any compressed image data that is in the source picture should be decompressed and then recompressed using the current parameters. Set the value of this parameter to TRUE to recompress such data. Set the value of the parameter to FALSE to leave the data as it is. Note that recompressing the data may have undesirable side effects, including image quality degradation.

    progressProc

    Points to an ICMProgressProc callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided a progress callback, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

    cType

    A compressor type. You must set this parameter to a valid compressor type constant; see Codec Identifiers. If the value passed in is 0, or 'raw ', the resulting picture is not compressed and does not require QuickTime to be displayed.

    codec

    A compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). See these constants:

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    If a picture with multiple pixel maps and other graphical objects is passed, the pixel maps will be compressed individually and the other graphic objects will not be affected. FCompressPicture compresses only image data. Any other types of data in the picture, such as text, graphics primitives, and previously compressed images, are not modified in any way and are passed through to the destination picture. This function supports parameters governing image quality, compressor type, image depth, custom color tables, and dithering.

  • Compresses a single-frame image stored as a picture file and places the result in another picture file, with added control over the compression process.

    Declaration

    OSErr FCompressPictureFile ( short srcRefNum, short dstRefNum, short colorDepth, CTabHandle ctable, CodecQ quality, short doDither, short compressAgain, ICMProgressProcRecordPtr progressProc, CodecType cType, CompressorComponent codec );

    Parameters

    srcRefNum

    A file reference number for the source PICT file.

    dstRefNum

    A file reference number for the destination PICT file. Note that the compressor overwrites the contents of the file referred to by dstRefNum. You must open this file with write permissions. The destination file may be the same as the source file specified by the srcRefNum parameter.

    colorDepth

    The depth at which the image is to be compressed. 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 capability structure returned by the GetCodecInfo function.

    ctable

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

    quality

    A constant (see below) that defines the desired compressed image quality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    doDither

    Indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. The following constants are available: See these constants:

    • defaultDither

    • forceDither

    • suppressDither

    compressAgain

    Indicates whether to recompress compressed image data in the picture. Use this parameter to control whether any compressed image data that is in the source picture should be decompressed and then recompressed using the current parameters. Set the value of this parameter to TRUE to recompress such data. Set the value of this parameter to FALSE to leave the data as it is. Note that recompressing the data may have undesirable side effects, including image quality degradation.

    progressProc

    Points to an ICMProgressProc callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress.

    cType

    A compressor type. You must set this parameter to a valid compressor type constant.

    codec

    A compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). See these constants:

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function compresses only image data. Any other types of data in the file, such as text, graphics primitives, and previously compressed images, are not modified in any way and are passed through to the destination picture file. This function supports parameters governing image quality, compressor type, image depth, custom color tables, and dithering.

  • Extracts the picture frame and file header from a specified picture file.

    Declaration

    OSErr GetPictureFileHeader ( short refNum, Rect *frame, OpenCPicParams *header );

    Parameters

    refNum

    A file reference number for the source PICT file.

    frame

    A pointer to a rectangle that is to receive the picture frame rectangle of the picture file. This function places the picFrame rectangle from the picture structure into the rectangle referred to by the frame parameter. If you are not interested in this information, pass NIL in this parameter.

    header

    A pointer to an OpenCPicParams structure. The GetPictureFileHeader function places the header from the specified picture file into this structure. If you are not interested in this information, pass NIL in this parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Your program can use the information returned in the header parameter to determine how to draw an image without having to read the picture file.

    Special Considerations

    Note that this function always returns a version 2 header. If the source file is a version 1 PICT file, the GetPictureFileHeader function converts the header into version 2 format before returning it to your application. See Inside Macintosh: Imaging With QuickDraw for more information about picture headers.

  • Compresses a single-frame image that is currently stored as a pixel map structure.

    Declaration

    OSErr CompressImage ( PixMapHandle src, const Rect *srcRect, CodecQ quality, CodecType cType, ImageDescriptionHandle desc, Ptr data );

    Parameters

    src

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

    srcRect

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

    quality

    A constant (see below) that defines the desired compressed image quality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    cType

    A compressor type; see Codec Identifiers.

    desc

    A handle that is to receive a formatted ImageDescription 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. The Image Compression Manager places the actual size of the compressed image into the dataSize field of the ImageDescription structure structure referred to by the desc parameter. This pointer must contain a 32-bit clean address.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The following code sample illustrates the process of compressing and decompressing a pixel map.

    1. // CompressImage coding example
    2. // See "Discovering QuickTime," page 286
    3. PicHandle GetQTCompressedPict (PixMapHandle hpmImage)
    4. {
    5. long lMaxCompressedSize =0;
    6. Handle hCompressedData =NIL;
    7. Ptr pCompressedData;
    8. ImageDescriptionHandle hImageDesc =NIL;
    9. OSErr nErr;
    10. PicHandle hpicPicture =NIL;
    11. Rect rectImage =(**hpmImage).bounds;
    12. CodecType dwCodecType =kJPEGCodecType;
    13. CodecComponent codec =(CodecComponent)anyCodec;
    14. CodecQ dwSpatialQuality =codecNormalQuality;
    15. short nDepth =0; // let ICM choose depth
    16. nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,
    17. dwSpatialQuality,
    18. dwCodecType,
    19. (CompressorComponent)codec,
    20. &lMaxCompressedSize);
    21. if (nErr !=noErr)
    22. return NIL;
    23. hImageDesc =(ImageDescriptionHandle)NewHandle(4);
    24. hCompressedData =NewHandle(lMaxCompressedSize);
    25. if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {
    26. MoveHHi(hCompressedData);
    27. HLock(hCompressedData);
    28. pCompressedData =StripAddress(*hCompressedData);
    29. nErr =CompressImage(hpmImage,
    30. &rectImage,
    31. dwSpatialQuality,
    32. dwCodecType,
    33. hImageDesc,
    34. pCompressedData);
    35. if (nErr ==noErr) {
    36. ClipRect(&rectImage);
    37. hpicPicture =OpenPicture(&rectImage);
    38. nErr =DecompressImage(pCompressedData,
    39. hImageDesc,
    40. hpmImage,
    41. &rectImage,
    42. &rectImage,
    43. srcCopy,
    44. NIL);
    45. ClosePicture();
    46. }
    47. if (theErr || (GetHandleSize((Handle)hpicPicture) ==
    48. sizeof(Picture))) {
    49. KillPicture(hpicPicture);
    50. hpicPicture =NIL;
    51. }
    52. }
    53. if (hImageDesc !=NIL)
    54. DisposeHandle((Handle)hImageDesc);
    55. if (hCompressedData !=NIL)
    56. DisposeHandle(hCompressedData);
    57. return hpicPicture;
    58. }
  • Converts the format of a compressed image.

    Declaration

    OSErr ConvertImage ( ImageDescriptionHandle srcDD, Ptr srcData, short colorDepth, CTabHandle ctable, CodecQ accuracy, CodecQ quality, CodecType cType, CodecComponent codec, ImageDescriptionHandle dstDD, Ptr dstData );

    Parameters

    srcDD

    A handle to the ImageDescription structure that describes the compressed image.

    srcData

    Points to the compressed image data. This pointer must contain a 32-bit clean address.

    colorDepth

    The depth at which the recompressed image is likely to be viewed. Decompressors 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.

    ctable

    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 ctable 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 ImageDescription structure.

    accuracy

    A constant (see below) that defines the accuracy desired in the decompressed image. Values for this parameter are on the same scale as compression quality. For a good display of still images, you should specify at least codecHighQuality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    quality

    A constant (see below) that defines the desired compressed image quality.

    cType

    A compressor type; see Codec Identifiers.

    codec

    Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special constant (see below). Specifying a component instance 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. See these constants:

    dstDD

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

    dstData

    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 GetMaxCompressionSize. The Image Compression Manager places the actual size of the compressed image into the dataSize field of the image description referred to by the dstDD parameter. This pointer must contain a 32-bit-clean address.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The action of this function is essentially equivalent to decompressing and recompressing the image. During the decompression operation, the decompressor uses the srcDD, srcData, and accuracy parameters. During the subsequent compression operation, the compressor uses the colorDepth, ctable, cType, codec, quality, dstDD, and dstData parameters.

  • Decompresses a single-frame image into a pixel map structure.

    Declaration

    OSErr DecompressImage ( Ptr data, ImageDescriptionHandle desc, PixMapHandle dst, const Rect *srcRect, const Rect *dstRect, short mode, RgnHandle mask );

    Parameters

    data

    Points to the compressed image data. This pointer must contain a 32-bit clean address.

    desc

    A handle to the ImageDescription structure that describes the compressed image.

    dst

    A handle to the pixel map where the decompressed image is to be displayed. Set the current graphics port to the port that contains this pixel map.

    srcRect

    A pointer 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 (0,0) and ((**desc).width,(**desc).height). If you want to decompress the entire source image, set this parameter to NIL. If the parameter is NIL, the rectangle is set to the rectangle structure of the ImageDescription structure.

    dstRect

    A pointer to the rectangle into which the decompressed image is to be loaded. The compressor scales the source image to fit into this destination rectangle.

    mode

    The transfer mode for the operation, as listed in Graphics Transfer Modes.

    mask

    A handle to a clipping region in the destination coordinate system. If specified, the compressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to NIL.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Note that DecompressImage is invoked through the StdPix function. The following code sample illustrates the process of compressing and decompressing a pixel map.

    1. // DecompressImage coding example
    2. // See "Discovering QuickTime," page 286
    3. PicHandle GetQTCompressedPict (PixMapHandle hpmImage)
    4. {
    5. long lMaxCompressedSize =0;
    6. Handle hCompressedData =NIL;
    7. Ptr pCompressedData;
    8. ImageDescriptionHandle hImageDesc =NIL;
    9. OSErr nErr;
    10. PicHandle hpicPicture =NIL;
    11. Rect rectImage =(**hpmImage).bounds;
    12. CodecType dwCodecType =kJPEGCodecType;
    13. CodecComponent codec =(CodecComponent)anyCodec;
    14. CodecQ dwSpatialQuality =codecNormalQuality;
    15. short nDepth =0; // let ICM choose depth
    16. nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,
    17. dwSpatialQuality,
    18. dwCodecType,
    19. (CompressorComponent)codec,
    20. &lMaxCompressedSize);
    21. if (nErr !=noErr)
    22. return NIL;
    23. hImageDesc =(ImageDescriptionHandle)NewHandle(4);
    24. hCompressedData =NewHandle(lMaxCompressedSize);
    25. if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {
    26. MoveHHi(hCompressedData);
    27. HLock(hCompressedData);
    28. pCompressedData =StripAddress(*hCompressedData);
    29. nErr =CompressImage(hpmImage,
    30. &rectImage,
    31. dwSpatialQuality,
    32. dwCodecType,
    33. hImageDesc,
    34. pCompressedData);
    35. if (nErr ==noErr) {
    36. ClipRect(&rectImage);
    37. hpicPicture =OpenPicture(&rectImage);
    38. nErr =DecompressImage(pCompressedData,
    39. hImageDesc,
    40. hpmImage,
    41. &rectImage,
    42. &rectImage,
    43. srcCopy,
    44. NIL);
    45. ClosePicture();
    46. }
    47. if (theErr || (GetHandleSize((Handle)hpicPicture) ==
    48. sizeof(Picture))) {
    49. KillPicture(hpicPicture);
    50. hpicPicture =NIL;
    51. }
    52. }
    53. if (hImageDesc !=NIL)
    54. DisposeHandle((Handle)hImageDesc);
    55. if (hCompressedData !=NIL)
    56. DisposeHandle(hCompressedData);
    57. return hpicPicture;
    58. }
  • Compresses a single-frame image that is currently stored as a pixel map structure, with added control over the compression process.

    Declaration

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

    Parameters

    src

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

    srcRect

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

    colorDepth

    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.

    quality

    A constant (see below) that defines the desired compressed image quality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    cType

    A compressor type. You must set this parameter to a valid compressor type constant.

    codec

    A compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). Specifying a component instance 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. See these constants:

    ctable

    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 ctable 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

    Contains a flag (see below) that indicates whether or not the image was previously compressed. See these constants:

    • codecFlagWasCompressed

    bufferSize

    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 an ICMDataProc data-unloading callback. 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. If you have not provided a data-unloading callback, 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 an ICMProgressProc progress callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided a progress callback, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

    desc

    A handle that is to receive a formatted ImageDescription structure. The Image Compression Manager resizes this handle for the returned ImageDescription 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. 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. The Image Compression Manager places the actual size of the compressed image into the dataSize field of the ImageDescription structure referenced by the desc parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function acts like CompressImage, but gives your application additional control over the parameters that guide the compression operation.

  • Decompresses a single-frame image into a pixel map structure, with added control over the decompression process.

    Declaration

    OSErr FDecompressImage ( Ptr data, ImageDescriptionHandle desc, PixMapHandle dst, const Rect *srcRect, MatrixRecordPtr matrix, short mode, RgnHandle mask, PixMapHandle matte, const Rect *matteRect, CodecQ accuracy, DecompressorComponent codec, long bufferSize, ICMDataProcRecordPtr dataProc, ICMProgressProcRecordPtr progressProc );

    Parameters

    data

    Points to the compressed image data. If the entire compressed image cannot be stored at this location, your application may provide a data-loading function (see the discussion of the dataProc parameter to this function). This pointer must contain a 32-bit clean address.

    desc

    A handle to the ImageDescription structure that describes the compressed image.

    dst

    A handle to the pixel map where the decompressed image is to be displayed. Set the current graphics port to the port that contains this pixel map.

    srcRect

    A pointer 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 (0,0) and ((**desc).width,(**desc).height). If you want to decompress the entire source image, set this parameter to NIL. If the parameter is NIL, the rectangle is set to the rectangle structure of the ImageDescription structure.

    matrix

    Points to a matrix structure that specifies how to transform the image during decompression. You can use the matrix structure to translate or scale the image during decompression. If you do not want to apply such effects, set the matrix parameter to NIL.

    mode

    The transfer mode for the operation; see Graphics Transfer Modes.

    mask

    A handle to a clipping region in the destination coordinate system. If specified, the decompressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to NIL.

    matte

    A handle to a pixel map that contains a blend matte. You can use the blend matte to cause the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported pixel depth; the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If you do not want to apply a blend matte, set this parameter to NIL.

    matteRect

    A pointer to a rectangle defining a portion of the blend matte to apply. If you do not want to use the entire matte referred to by the matte parameter, use this parameter to specify a rectangle within that matte. If specified, this rectangle must be the same size as the rectangle specified by the srcRect parameter. If you want to use the entire matte, or if you are not providing a blend matte, set this parameter to NIL.

    accuracy

    A constant (see below) that defines the desired compression accuracy. For a good display of still images, you should specify at least codecHighQuality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    codec

    A decompressor identifier. Specify a particular decompressor by setting this parameter to its identifier. Alternatively, you may use a special identifier (see below). Specifying a component instance 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. See these constants:

    bufferSize

    The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, set this parameter to 0.

    dataProc

    Points to an ICMDataProc data-loading callback. If there is not enough memory to store the compressed image, the compressor calls a function you provide that loads more compressed data. If you have not provided a data-unloading callback, set this parameter to NIL. In this case, the compressor expects that the entire compressed image is in the memory location specified by the data parameter.

    progressProc

    Points to an ICMProgressProc progress callback. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided a progress callback, set this parameter to NIL. If you pass a value of -1, QuickTime provides a standard progress function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function gives your application greater control over the parameters that guide the decompression operation. If you find that you do not need this level of control, use DecompressImage. Note that this function is invoked through the StdPix function.

  • Gets the custom color table for an image.

    Declaration

    OSErr GetImageDescriptionCTable ( ImageDescriptionHandle desc, CTabHandle *ctable );

    Parameters

    desc

    A handle to the appropriate ImageDescription structure.

    ctable

    A pointer to a field that is to receive a color table handle.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function returns the color table for the image described by the ImageDescription structure that is referred to by the desc parameter. The function correctly sizes the handle for the color table it returns.

  • Updates the custom ColorTable structure for an image.

    Declaration

    OSErr SetImageDescriptionCTable ( ImageDescriptionHandle desc, CTabHandle ctable );

    Parameters

    desc

    Contains a handle to the appropriate ImageDescription structure. The function updates the size of the structure to accommodate the new ColorTable structure and removes the old color table, if one is present.

    ctable

    A handle to the new ColorTable structure. The function loads this color table into the ImageDescription structure referred to by the desc parameter. Set this parameter to NIL to remove a ColorTable structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function does not change the image data, just the color table.

    Special Considerations

    This function is rarely used. Typically, you supply the color table when your application compresses an image, and the Image Compression Manager stores the ColorTable structure with the image.

  • Adjusts a compressed image to the boundaries defined by a specified rectangle.

    Declaration

    ComponentResult ADD_IMAGECODEC_BASENAME() TrimImage

    Parameters

    desc

    A handle to the ImageDescription structure that describes the compressed image. On return, the compressor updates this structure to describe the resized image.

    inData

    A pointer to the compressed image data. This pointer must contain a 32-bit clean address. If the entire compressed image cannot be stored at this location, your application may provide an ICMDataProc callback through the dataProc parameter.

    inBufferSize

    The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If you have not specified a data-loading function, this parameter is ignored.

    dataProc

    A pointer to an ICMDataProcRecord structure that references an ICMDataProc callback. If there is not enough memory to store the compressed image, the compressor calls a function you provide that loads more compressed data. If you have not provided such a data-loading function, set this parameter to NIL. In this case, the compressor expects that the entire compressed image is in the memory location specified by the inData parameter

    outData

    A pointer to a buffer to receive the trimmed image. The Image Compression Manager places the actual size of the resulting image into the dataSize field of the ImageDescription structure referred to by the desc parameter. This pointer must contain a 32-bit clean address. Your application should create a destination buffer at least as large as the source image. 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, in which case you use the flushProc parameter to identify your data-unloading function to the compressor.

    outBufferSize

    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, this parameter is ignored.

    flushProc

    A pointer to an ICMFlushProcRecord structure that references an ICMFlushProc callback. 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. If you have not provided such 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

    trimRect

    A pointer to a Rect structure that defines the desired image dimensions. On return, the function adjusts the rectangle values so that they refer to the same rectangle in the result image. This is necessary whenever data is removed from the beginning or left side of the image.

    progressProc

    A pointer to an ICMProgressProcRecord structure that references an ICMProgressProc callback. During the operation, the compressor may occasionally call a function you provide in order to report its progress. If you have not provided such a progress function, set this parameter to NIL. If you pass a value of -1, you obtain a standard progress function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Checks the status of an asynchronous compression or decompression operation.

    Declaration

    OSErr CDSequenceBusy ( ImageSequence seqID );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by DecompressSequenceBegin or CompressSequenceBegin.

    Return Value

    If there is no asynchronous operation in progress, CDSequenceBusy returns a 0 result code. If there is an asynchronous operation in progress, the result code is 1. Negative result codes indicate an error.

  • Notifies the compressor that the image source data has changed.

    Declaration

    OSErr CDSequenceChangedSourceData ( ImageSequenceDataSource sourceID );

    Parameters

    sourceID

    Contains the source identifier of the data source.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Use this function to indicate that the image has changed but the data pointer to that image has not changed. For example, if the data pointer points to the base address of a PixMap structure, the image in the PixMap can change, but the data pointer remains constant.

  • Disposes of a data source.

    Declaration

    OSErr CDSequenceDisposeDataSource ( ImageSequenceDataSource sourceID );

    Parameters

    sourceID

    The data source identifier that was returned by the CDSequenceNewDataSource function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Use this function to dispose of a data source created by the CDSequenceNewDataSource function. All data sources are automatically disposed when the sequence they are associated with is disposed.

  • Disposes of memory allocated by the codec.

    Declaration

    OSErr CDSequenceDisposeMemory ( ImageSequence seqID, Ptr data );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    data

    Points to the previously allocated memory block.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    You call this function to release memory allocated by the CDSequenceNewMemory function.

    Special Considerations

    Do not call CDSequenceDisposeMemory at interrupt time.

  • Indicates the end of processing for an image sequence.

    Declaration

    OSErr CDSequenceEnd ( ImageSequence seqID );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by DecompressSequenceBegin or CompressSequenceBegin.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Reports whether two image descriptions are the same.

    Declaration

    OSErr CDSequenceEquivalentImageDescription ( ImageSequence seqID, ImageDescriptionHandle newDesc, Boolean *equivalent );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    newDesc

    A handle to the ImageDescription structure structure that describes the compressed image.

    equivalent

    A pointer to a Boolean value. If the ImageDescriptionHandle provided in the newDesc parameter is equivalent to the ImageDescription structure currently in use by the image sequence, this value is set to TRUE. If the ImageDescriptionHandle is not equivalent, and therefore a new image sequence must be created to display an image using the new image description, this value is set to FALSE.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function allows an application to ask whether two image descriptions are the same. If they are, the decompressor does not have to create a new image decompression sequence to display those images.

    Special Considerations

    The Image Compression Manager can only implement part of this function by itself. There are some fields in the ImageDescription structure that it knows are irrelevant to the decompressor. If the Image Compression Manager determines that there are differences in fields that may be significant to the codec, it calls the function ImageCodecIsImageDescriptionEquivalent to ask the codec.

  • Stops a decompression sequence, aborting processing of any queued frames.

    Declaration

    OSErr CDSequenceFlush ( ImageSequence seqID );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by DecompressSequenceBegin.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function is used to tell a decompressor component to stop processing of any queued scheduled asynchronous decompression. This is useful when several frames have been queued for decompression in the future and the application needs to suspend playback of the sequence.

    For any outstanding frames, your application's completion routine, passed to DecompressSequenceFrameWhen, will be called with an error result of -1, indicating that the frame was cancelled. If any frames are currently being decompressed and cannot be cancelled, CDSequenceFlush waits until the frame has finished decompressing before returning.

  • Notifies the Image Compression Manager that the destination port for the given image decompression sequence has been invalidated.

    Declaration

    OSErr CDSequenceInvalidate ( ImageSequence seqID, RgnHandle invalRgn );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by DecompressSequenceBegin.

    invalRgn

    A handle to the region specifying the invalid portion of the image.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    You call this function to force the Image Compression Manager to redraw the screen bits on the next decompression operation.

  • Creates a new data source.

    Declaration

    OSErr CDSequenceNewDataSource ( ImageSequence seqID, ImageSequenceDataSource *sourceID, OSType sourceType, long sourceInputNumber, Handle dataDescription, ICMConvertDataFormatUPP transferProc, void *refCon );

    Parameters

    seqID

    The unique sequence identifier that was returned by the DecompressSequenceBegin function.

    sourceID

    Returns the new data source identifier.

    sourceType

    A four-character code describing how the input will be used. This code is usually derived from the information returned by the codec. For example, if a mask plane was passed, this field might contain 'mask'.

    sourceInputNumber

    More than one instance of a given source type may exist. The first occurrence should have a source input number of 1, the second a source input number of 2, and so on.

    dataDescription

    A handle to a data structure describing the input data. For compressed image data, this is an ImageDescriptionHandle.

    transferProc

    A routine that allows the application to transform the type of the input data to the kind of data preferred by the codec. The client of the codec passes the source data in the form most convenient for it. If the codec needs the data in another form, it can negotiate with the client or directly with the Image Compression Manager to obtain the required data format.

    refCon

    A reference constant to be passed to the transfer procedure. Use this parameter to point to a data structure containing any information your function needs.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function returns a sourceID parameter which must be passed to all other functions that reference the source. All data sources are automatically disposed when the sequence they are associated with is disposed.

    1. // CDSequenceNewDataSource coding example
    2. // See "Discovering QuickTime," page 309
    3. {
    4. ImageSequenceDataSource lSrc1 =0;
    5. // Store a description of the first GWorld in hImageDesc1
    6. nErr =MakeImageDescriptionForPixMap(GetGWorldPixMap(gWorld1),
    7. &hImageDesc1);
    8. // Create a source from the GWorld description.
    9. nErr =CDSequenceNewDataSource(gEffectSequenceID,
    10. &lSrc1,
    11. 'srcA',
    12. 1,
    13. (Handle)hImageDesc1,
    14. NIL,
    15. 0);
    16. // Set the data for source srcA to be the pixMap of gWorld1
    17. CDSequenceSetSourceData(lSrc1,
    18. GetPixBaseAddr(GetGWorldPixMap(gWorld1)),
    19. (**hImageDesc1).dataSize);
    20. }
  • Requests codec-allocated memory.

    Declaration

    OSErr CDSequenceNewMemory ( ImageSequence seqID, Ptr *data, Size dataSize, long dataUse, ICMMemoryDisposedUPP memoryGoneProc, void *refCon );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    data

    Returns a pointer to the allocated memory.

    dataSize

    The requested size of the data buffer.

    dataUse

    A code (see below) that indicates how the memory is to be used. For example, the memory may be used to store compressed image or mask plane data, or used as an offscreen image buffer. If there is no benefit to storing a particular kind of data in codec memory, the codec should deny the request for the memory allocation. See these constants:

    memoryGoneProc

    A pointer to a callback function that will be called before disposing of the memory allocated by a codec, as described in ICMMemoryDisposedProc.

    refCon

    A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your function needs.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Because many hardware decompression boards contain dedicated on-board memory, significant performance gains can be realized if this memory is used to store data before it is decompressed. When memory is allocated, a callback function must be provided, as described in ICMMemoryDisposedProc. The decompressor can dispose of all memory it has allocated at any time, but it calls the callback routine before disposing of the memory. A callback procedure is required because memory on the hardware decompression board may be limited. If the decompressor cannot deallocate memory as required, it is possible that an idle decompressor instance may be holding a large amount of memory, denying those resources to the currently active decompressor instance. When the callback procedure is called, the memory is still available. This allows any pending reads into the block to be canceled before the block is disposed. The decompressor disposing the memory must ensure that it is not disposing a block that it is currently using (that is, a block that contains the currently decompressing frame). To dispose of the memory, use CDSequenceDisposeMemory.

    Special Considerations

    Decompressor memory must never be disposed at interrupt time.

  • Sets data in a new frame to a specific data source.

    Declaration

    OSErr CDSequenceSetSourceData ( ImageSequenceDataSource sourceID, void *data, long dataSize );

    Parameters

    sourceID

    Contains the source identifier of the data source.

    data

    Points to the data. This pointer must contain a 32-bit clean address.

    dataSize

    The size of the data buffer.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function is called to set data in a new frame to a specific source. For example, as a new frame of compressed data arrives at a source, CDSequenceSetSourceData will be called.

    1. // CDSequenceSetSourceData coding example
    2. // See "Discovering QuickTime," page 309
    3. {
    4. ImageSequenceDataSource lSrc1 =0;
    5. // Store a description of the first GWorld in hImageDesc1
    6. nErr =MakeImageDescriptionForPixMap(GetGWorldPixMap(gWorld1),
    7. &hImageDesc1);
    8. // Create a source from the GWorld description.
    9. nErr =CDSequenceNewDataSource(gEffectSequenceID,
    10. &lSrc1,
    11. 'srcA',
    12. 1,
    13. (Handle)hImageDesc1,
    14. NIL,
    15. 0);
    16. // Set the data for source srcA to be the pixMap of gWorld1
    17. CDSequenceSetSourceData(lSrc1,
    18. GetPixBaseAddr(GetGWorldPixMap(gWorld1)),
    19. (**hImageDesc1).dataSize);
    20. }
  • Signals the beginning of the process of compressing a sequence of frames.

    Declaration

    OSErr CompressSequenceBegin ( ImageSequence *seqID, PixMapHandle src, PixMapHandle prev, const Rect *srcRect, const Rect *prevRect, short colorDepth, CodecType cType, CompressorComponent codec, CodecQ spatialQuality, CodecQ temporalQuality, long keyFrameRate, CTabHandle ctable, CodecFlags flags, ImageDescriptionHandle desc );

    Parameters

    seqID

    A pointer to a field to receive the unique identifier for this sequence. You must supply this identifier to all subsequent Image Compression Manager functions that relate to this sequence.

    src

    A handle to a pixel map that will contain the image to be compressed. The image must be stored in a pixel map structure.

    prev

    A handle to a pixel map that will contain a previous image. The compressor uses this buffer to store a previous image against which the current image (stored in the pixel map referred to by the src parameter) is compared when performing temporal compression. This pixel map must be created at the same depth and with the same color table as the source image. The compressor manages the contents of this pixel map based upon several considerations, such as the key frame rate and the degree of difference between compared images. If you want the compressor to allocate this pixel map or if you do not want to perform temporal compression (that is, you have set the value of the temporalQuality parameter to 0), set this parameter to NIL.

    srcRect

    A pointer to a rectangle defining the portion of the image to compress. The compressor applies this rectangle to the image stored in the buffer referred to by the src parameter.

    prevRect

    A pointer to a rectangle defining the portion of the previous image to use for temporal compression. The compressor uses this portion of the previous image as the basis of comparison with the current image. The compressor ignores this parameter if you have not provided a buffer for previous images. This rectangle must be the same size as the source rectangle, which is specified with the srcRect parameter.

    colorDepth

    The depth at which the sequence is likely to be viewed. Compressors may use this as an indication of the color or grayscale resolution of the compressed images. 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.

    cType

    You must set this parameter to a valid compressor type constant. See Codec Identifiers.

    codec

    Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use a special identifier (see below). Specifying a component instance 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. See these constants:

    spatialQuality

    A pointer to a field containing a constant (see below) that defines the desired compressed image quality. You can change the value of this parameter for an active sequence by calling SetCSequenceQuality. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    temporalQuality

    A pointer to a field containing a constant (see below) that defines the desired temporal quality. This parameter governs the level of compression you desire with respect to information between successive frames in the sequence. Set to 0 if you do not want temporal compression. You can change the value of this parameter for an active sequence by calling SetCSequenceQuality.

    keyFrameRate

    Specifies the maximum number of frames allowed between key frames. The compressor determines the optimum placement for key frames based upon the amount of redundancy between adjacent images in the sequence. Consequently, the compressor may insert key frames more frequently than you have requested. However, the compressor never places fewer key frames than is indicated by the setting of the keyFrameRate parameter. The compressor ignores this parameter if you have not requested temporal compression (that is, you have set the temporalQuality parameter to 0). If you pass in 0 in this parameter, this indicates that there are no key frames in the sequence. If you pass in any other number, it specifies the number of non-key frames between key frames. Set this parameter to 1 to specify all key frames, to 2 to specify every other frame as a key frame, to 3 to specify every third frame as a key frame, and so forth. Your application may change the key frame rate for an active sequence by calling SetCSequenceKeyFrameRate.

    ctable

    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 ctable 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

    Contains flags (see below) that provide further control information. You must set either codecFlagUpdatePrevious or codecFlagUpdatePreviousComp to 1. Set unused flags to 0. See these constants:

    • codecFlagUpdatePrevious

    • codecFlagUpdatePreviousComp

    • codecFlagWasCompressed

    desc

    A handle that is to receive a formatted ImageDescription structure. The Image Compression Manager resizes this handle for the returned image description structure. Your application should store this image description with the compressed sequence. During the compression operation, the Image Compression Manager and the compressor component update the contents of this image description. Consequently, you should not store the image description until the sequence has been completely processed.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The Image Compression Manager prepares for a sequence-compression operation by reserving appropriate system resources. Hence you must call CompressSequenceBegin before you call CompressSequenceFrame.

  • Compresses one of a sequence of frames.

    Declaration

    OSErr CompressSequenceFrame ( ImageSequence seqID, PixMapHandle src, const Rect *srcRect, CodecFlags flags, Ptr data, long *dataSize, UInt8 *similarity, ICMCompletionProcRecordPtr asyncCompletionProc );

    Parameters

    seqID

    Unique sequence identifier that was returned by CompressSequenceBegin.

    src

    A handle to a pixel map that contains the image to be compressed. The image must be stored in a pixel map structure.

    srcRect

    A pointer to a rectangle defining the portion of the image to compress. The compressor applies this rectangle to the image stored in the buffer referred to by the src parameter.

    flags

    Specifies flags (see below) that provide further control information. You must set either codecFlagUpdatePrevious or codecFlagUpdatePreviousComp to 1. Set unused flags to 0. See these constants:

    • codecFlagUpdatePrevious

    • codecFlagWasCompressed

    • codecFlagUpdatePreviousComp

    • codecFlagForceKeyFrame

    • codecFlagLiveGrab

    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. The Image Compression Manager places the actual size of the compressed image into the field referred to by the dataSize parameter. This pointer must contain a 32-bit clean address.

    dataSize

    A pointer to a field that is to receive the size, in bytes, of the compressed image.

    similarity

    A pointer to a field that is to receive a similarity value. The CompressSequenceFrame function returns a value that indicates the similarity of the current frame to the previous frame. A value of 0 indicates that the current frame is a key frame in the sequence. A value of 255 indicates that the current frame is identical to the previous frame. Values from 1 through 254 indicate relative similarity, ranging from very different (1) to very similar (254).

    asyncCompletionProc

    Points to an ICMCompletionProc callback. The compressor calls your completion function when an asynchronous compression operation is complete. You can cause the compression to be performed asynchronously by specifying a completion function if the compressor supports asynchronous compression.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The Image Compression Manager prepares for a sequence-compression operation by reserving appropriate system resources. Hence you must call CompressSequenceBegin before you call CompressSequenceFrame.

    Special Considerations

    If you specify asynchronous operation, you must not read the compressed data until the compressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to NIL to specify synchronous compression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the compressor does not call your completion function. If the asyncCompletionProc parameter is not NIL, the following conditions are in effect: the pixels in the source image must stay valid until the completion function is called with its codecCompletionSource flag, and the resulting compressed data is not valid until it is called with its codecCompletionDest flag set.

  • Obsolete. See DecompressSequenceBeginS.

    Declaration

    OSErr DecompressSequenceBegin ( ImageSequence *seqID, ImageDescriptionHandle desc, CGrafPtr port, GDHandle gdh, const Rect *srcRect, MatrixRecordPtr matrix, short mode, RgnHandle mask, CodecFlags flags, CodecQ accuracy, DecompressorComponent codec );

  • Sends a sample image to a decompressor.

    Declaration

    OSErr DecompressSequenceBeginS ( ImageSequence *seqID, ImageDescriptionHandle desc, Ptr data, long dataSize, CGrafPtr port, GDHandle gdh, const Rect *srcRect, MatrixRecordPtr matrix, short mode, RgnHandle mask, CodecFlags flags, CodecQ accuracy, DecompressorComponent codec );

    Parameters

    seqID

    A pointer to a field to receive the unique identifier for the sequence you are creating. You should use this identifier for subsequent calls relating to this decompression sequence.

    desc

    A handle to the ImageDescription structure that describes the compressed image.

    data

    Points to the compressed image data. This pointer must contain a 32-bit clean address. Ideally, you should pass a pointer to the first frame of the compressed image data, which lets the Image Compression Manager do a better job of preflighting the decompression sequence. If the image data is not available at the time of this call, you can pass NIL for this parameter and 0 for dataSize. If you pass NIL here, then your first call to DecompressSequenceFrameWhen may require more setup time.

    dataSize

    The size of the data buffer, or 0 if you passed NIL in the data parameter.

    port

    Points to the CGrafPort structure for the destination image.

    gdh

    A handle to the GDevice structure for the destination image. You can pass NIL if the GDevice is implicit in the port selection (for example, if it is an offscreen graphics world).

    srcRect

    A pointer to a Rect structure that defines the portions of the image to decompress. Pass NIL if you want to decompress the entire source image. You can call SetDSequenceSrcRect to change the source rectangle for an active decompression sequence.

    matrix

    Points to a MatrixRecord structure that specifies how to transform the image during decompression. Pass NIL to use the identity matrix. Your application can change the matrix for an active sequence by calling SetDSequenceMatrix.

    mode

    The transfer mode for the operation. See Graphics Transfer Modes. Your application can change the transfer mode for an active sequence by calling SetDSequenceTransferMode.

    mask

    A handle to a clipping region in the destination coordinate system. If specified, the compressor applies this mask to the destination image. If you do not want to mask bits in the destination, set this parameter to NIL. Your application can change the clipping mask for an active sequence by calling SetDSequenceMask.

    flags

    Buffer allocation flags (see below). See these constants:

    • codecFlagUseScreenBuffer

    • codecFlagUseImageBuffer

    accuracy

    A constant (see below) that defines the desired compression accuracy. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    codec

    A decompressor identifier. Specify a particular decompressor by setting this parameter to its identifier. Alternatively, you may use a special identifier (see below). Specifying a component instance 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. See these constants:

    Return Value

    See Error Codes. Returns codecWouldOffscreenErr if codecFlagDontUseImageBuffer is set and the codec requires an offscreen buffer to decompress to the destination port. Returns noErr if there is no error.

    Discussion

    This function lets you pass a compressed sample so a codec can perform preflighting before the first DecompressSequenceFrameWhen call. To decompress a series of images, call it once to preflight the decompressor, make calls to DecompressSequenceFrameWhen to decompress each image in the sequence, then call CDSequenceEnd when you are done.

  • Obsolete. See DecompressSequenceFrameS.

    Declaration

    OSErr DecompressSequenceFrame ( ImageSequence seqID, Ptr data, CodecFlags inFlags, CodecFlags *outFlags, ICMCompletionProcRecordPtr asyncCompletionProc );

  • Queues a frame for decompression and specifies the size of the compressed data; new applications should use DecompressSequenceFrameWhen.

    Declaration

    OSErr DecompressSequenceFrameS ( ImageSequence seqID, Ptr data, long dataSize, CodecFlags inFlags, CodecFlags *outFlags, ICMCompletionProcRecordPtr asyncCompletionProc );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    data

    Points to the compressed image data. This pointer must contain a 32-bit clean address.

    dataSize

    The size of the data buffer.

    inFlags

    Contains flags (see below) that provide further control information. See these constants:

    • codecFlagNoScreenUpdate

    • codecFlagDontOffscreen

    • codecFlagOnlyScreenUpdate

    outFlags

    Contains status flags (see below). The decompressor updates these flags at the end of the decompression operation. See these constants:

    • codecFlagUsedNewImageBuffer

    • codecFlagUsedImageBuffer

    • codecFlagDontUseNewImageBuffer

    • codecFlagInterlaceUpdate

    • codecFlagCatchUpDiff

    asyncCompletionProc

    Points to an ICMCompletionProcRecord structure. The compressor calls your completion function when an asynchronous decompression operation is complete. You can cause the decompression to be performed asynchronously by specifying a completion function. If you specify asynchronous operation, you must not read the decompressed image until the decompressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to NIL to specify synchronous decompression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the decompressor does not call your completion function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function accepts the same parameters as the DecompressSequenceFrame function, with the addition of the dataSize parameter.

    Special Considerations

    New applications should use DecompressSequenceFrameWhen.

  • Queues a frame for decompression and specifies the time at which decompression will begin.

    Declaration

    OSErr DecompressSequenceFrameWhen ( ImageSequence seqID, Ptr data, long dataSize, CodecFlags inFlags, CodecFlags *outFlags, ICMCompletionProcRecordPtr asyncCompletionProc, const ICMFrameTimeRecord *frameTime );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    data

    Points to the compressed image data. This pointer must contain a 32-bit clean address.

    dataSize

    The size of the data buffer.

    inFlags

    Contains flags (see below) that provide further control information. See these constants:

    • codecFlagNoScreenUpdate

    • codecFlagDontOffscreen

    • codecFlagOnlyScreenUpdate

    outFlags

    Contains status flags (see below). The decompressor updates these flags at the end of the decompression operation. See these constants:

    • codecFlagUsedNewImageBuffer

    • codecFlagUsedImageBuffer

    • codecFlagDontUseNewImageBuffer

    • codecFlagInterlaceUpdate

    • codecFlagCatchUpDiff

    asyncCompletionProc

    Points to an ICMCompletionProcRecord structure. The compressor calls your completion function when an asynchronous decompression operation is complete. You can cause the decompression to be performed asynchronously by specifying a completion function. If you specify asynchronous operation, you must not read the decompressed image until the decompressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to NIL to specify synchronous decompression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the decompressor does not call your completion function.

    frameTime

    Points to an ICMFrameTimeRecord structure, which contains the frame's time information, including the time at which the frame should be displayed, its duration, and the movie's playback rate. This parameter can be NIL, in which case the decompression operation will happen immediately.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    The following code snippet shows this function being used to execute one frame of a visual effect.

    1. // DecompressSequenceFrameWhen coding example
    2. // See "Discovering QuickTime," page 310
    3. // Decompress a single step of the effect sequence.
    4. OSErr RunEffect(TimeValue lTime, int nNumberOfSteps)
    5. {
    6. OSErr nErr =noErr;
    7. ICMFrameTimeRecord ftr;
    8. // Set the timebase time to the step of the sequence to be rendered
    9. SetTimeBaseValue(timeBase, lTime, nNumberOfSteps);
    10. ftr.value.lo =lTime;
    11. ftr.value.hi =0;
    12. ftr.scale =nNumberOfSteps;
    13. ftr.base =0;
    14. ftr.duration =nNumberOfSteps;
    15. ftr.rate =0;
    16. ftr.recordSize =sizeof(ftr);
    17. ftr.frameNumber =1;
    18. ftr.flags =icmFrameTimeHasVirtualStartTimeAndDuration;
    19. ftr.virtualStartTime.lo =0;
    20. ftr.virtualStartTime.hi =0;
    21. ftr.virtualDuration =nNumberOfSteps;
    22. HLock(hEffectDesc);
    23. DecompressSequenceFrameWhen(gEffectSequenceID,
    24. StripAddress(*hEffectDesc),
    25. GetHandleSize(hEffectDesc),
    26. 0,
    27. 0,
    28. NIL,
    29. &ftr);
    30. HUnlock(hEffectDesc);
    31. }

    Special Considerations

    If the current decompressor component does not support scheduled asynchronous decompression, the Image Compression Manager returns an error code of codecCantWhenErr. In this case, the application will need to reissue the request with the frameTime parameter set to NIL. If the decompressor cannot service your request at a particular time (for example, if its queue is full), the Image Compression Manager returns an error code of codecCantQueueErr. The best way to determine whether a decompressor component supports this function is to call the function and test the result code. A decompressor's ability to honor the request may change based on screen depth, clipping settings, and so on.

  • Installs a progress procedure for a sequence.

    Declaration

    OSErr SetSequenceProgressProc ( ImageSequence seqID, ICMProgressProcRecord *progressProc );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    progressProc

    A pointer to an ICMProgressProcRecord structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function allows you to set an ICMProgressProc callback for a compression or decompression sequence, just as you can set a progress procedure when compressing or decompressing a still image.

  • Retrieves information about a compressed image.

    Declaration

    OSErr GetCompressedPixMapInfo ( PixMapPtr pix, ImageDescriptionHandle *desc, Ptr *data, long *bufferSize, ICMDataProcRecord *dataProc, ICMProgressProcRecord *progressProc );

    Parameters

    pix

    Points to a structure that holds encoded compressed image data.

    desc

    A pointer to a field that is to receive a handle to the ImageDescription structure that defines the compressed image. If you are not interested in this information, specify NIL in this parameter.

    data

    A pointer to a field that is to receive a pointer to the compressed image data. If the entire compressed image cannot be stored at this location, you can define a data-loading function for this operation. If you are not interested in this information, you may specify NIL in this parameter.

    bufferSize

    A pointer to a field that is to receive the size of the buffer to be used by the data-loading function specified by the dataProc parameter. If there is no data-loading function defined for this operation, this parameter is ignored. If you are not interested in this information, you may specify NIL in this parameter.

    dataProc

    A pointer to an ICMDataProc callback. If there is not enough memory to store the compressed image, the decompressor calls a function you provide that loads more compressed data. If there is no data-loading function for this image, the function sets the dataProc field in the function structure to NIL. If you are not interested in this information, specify NIL in this parameter.

    progressProc

    A pointer to an ICMProgressProc callback. During a decompression operation, the decompressor may occasionally call a function you provide in order to report its progress. If there is no progress function for this image, the function sets the progressProc field in the function structure to NIL. If you pass a value of -1, QuickTime provides a standard progress function. If you are not interested in progress information, specify NIL in this parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Stores information about a compressed image for StdPix.

    Declaration

    OSErr SetCompressedPixMapInfo ( PixMapPtr pix, ImageDescriptionHandle desc, Ptr data, long bufferSize, ICMDataProcRecordPtr dataProc, ICMProgressProcRecordPtr progressProc );

    Parameters

    pix

    A pointer to a PixMap structure that holds compressed image data.

    desc

    A handle to the ImageDescription structure that defines the compressed image.

    data

    A pointer to the buffer for the compressed image data. If the entire compressed image cannot be stored at this location, you may assign a data-loading function (see the dataProc parameter, below). This pointer must contain a 32-bit clean address.

    bufferSize

    The size of the buffer to be used by the data-loading function specified by the dataProc parameter. If there is no data-loading function defined for this operation, set this parameter to 0.

    dataProc

    A pointer to an ICMDataProcRecord structure. If there is not enough memory to store the compressed image, the decompressor calls an ICMDataProc callback that you provide, which loads more compressed data. If you do not want to assign a data-loading function, set this parameter to NIL.

    progressProc

    A pointer to an ICMProgressProcRecord structure. During the decompression operation, the decompressor may occasionally call an ICMProgressProc callback that you provide, in order to report its progress. If you do not want to assign a progress function, set this parameter to NIL. If you pass a value of -1, you obtain a standard progress function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Extends the grafProcs field of the CGrafPort structure to support compressed data, mattes, matrices, and pixel maps, letting you intercept image data in compressed form before it is decompressed and displayed.

    Declaration

    void StdPix ( PixMapPtr src, const Rect *srcRect, MatrixRecordPtr matrix, short mode, RgnHandle mask, PixMapPtr matte, const Rect *matteRect, short flags );

    Parameters

    src

    Contains a pointer to a PixMap structure containing the image to draw. Use GetCompressedPixMapInfo to retrieve information about this structure.

    srcRect

    Points to a Rect structure that defines the portion of the image to display. This rectangle must lie within the boundary rectangle of the compressed image or within the source image. If this parameter is set to NIL, the entire image is displayed.

    matrix

    Contains a pointer to a MatrixRecord structure that specifies the mapping of the source rectangle to the destination. It is a fixed-point, 3-by-3 matrix.

    mode

    Specifies the transfer mode for the operation; see Graphics Transfer Modes. Note that this parameter also controls the accuracy of any decompression operation that may be required to display the image. If bit 7 (0x80) of the mode parameter is set to 1, the StdPix function sets the decompression accuracy to codecNormalQuality. If this bit is set to 0, the function sets the accuracy to codecHighQuality.

    mask

    Contains a handle to a clipping region in the destination coordinate system. If specified, the compressor applies this mask to the destination image. If there is no mask, this parameter is set to NIL.

    matte

    Points to a PixMap structure that contains a blend matte. The blend matte causes the decompressed image to be blended into the destination pixel map. The matte can be defined at any supported pixel depth; the matte depth need not correspond to the source or destination depths. However, the matte must be in the coordinate system of the source image. If there is no matte, this parameter is set to NIL

    matteRect

    Contains a pointer to a Rect structure that defines a portion of the blend matte to apply. This parameter is set to NIL if there is no matte or if the entire matte is to be used.

    flags

    Contains control flags (see below). See these constants:

    • callOldBits

    • callStdBits

    • noDefaultOpcodes

  • Initiates an image field sequence operation and specifies the input and output data format.

    Declaration

    OSErr ImageFieldSequenceBegin ( ImageFieldSequence *ifs, ImageDescriptionHandle desc1, ImageDescriptionHandle desc2, ImageDescriptionHandle descOut );

    Parameters

    ifs

    On return, contains the unique sequence identifier assigned to the sequence.

    desc1

    An ImageDescription structure describing the format and characteristics of the data to be passed to ImageFieldSequenceExtractCombine through the data1 parameter.

    desc2

    An ImageDescription structure describing the format and characteristics of the data to be passed to the ImageFieldSequenceExtractCombine function through the data2 parameter. Set to NIL if the requested operation uses only one input frame.

    descOut

    The desired format of the resulting frames. Typically this is the same format specified by the desc1 and desc2 parameters.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    Use this function to set up an image field sequence operation and specify the input and output data format.

  • Ends an image field sequence operation.

    Declaration

    OSErr ImageFieldSequenceEnd ( ImageFieldSequence ifs );

    Parameters

    ifs

    The unique sequence identifier that was returned by the ImageFieldSequenceBegin function.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    You must call this function to terminate an image field sequence operation.

  • Performs field operations on video data.

    Declaration

    OSErr ImageFieldSequenceExtractCombine ( ImageFieldSequence ifs, long fieldFlags, void *data1, long dataSize1, void *data2, long dataSize2, void *outputData, long *outDataSize );

    Parameters

    ifs

    The unique sequence identifier that was returned by ImageFieldSequenceBegin.

    fieldFlags

    Flags (see below) that specify the operation to be performed. A correctly formed request will specify two input fields, mapping one to the odd output field and the other to the even output field. See these constants:

    • evenField1ToEvenFieldOut

    • evenField1ToOddFieldOut

    • oddField1ToEvenFieldOut

    • oddField1ToOddFieldOut

    • evenField2ToEvenFieldOut

    • evenField2ToOddFieldOut

    • oddField2ToEvenFieldOut

    • oddField2ToOddFieldOut

    data1

    A pointer to a buffer containing the data of input field one.

    dataSize1

    The size of the data1 buffer.

    data2

    A pointer to a buffer containing the data of input field two. Set to NIL if the requested operation uses only one input frame.

    dataSize2

    The size of the data2 buffer. Set to 0 if the requested operation uses only one input frame.

    outputData

    A pointer to a buffer to receive the resulting frame. Use GetMaxCompressionSize to determine the amount of memory to allocate for this buffer.

    outDataSize

    On output this parameter returns the actual size of the data.

    Return Value

    Returns the codecUnimpErr result code if there is no codec present in the system that can perform the requested operation. See Error Codes. Returns noErr if there is no error.

    Discussion

    This function provides a method for working directly with fields of interlaced video. You can use it to change the field dominance of an image by reversing the two fields, or to create or remove the effects of the 3:2 pulldown commonly performed when transferring film to NTSC videotape. Because this function operates directly on the compressed video data, it is faster than working with decompressed images. It also has the added benefit of eliminating any image quality degradation that might result from lossy codecs.

    This function accepts one or two compressed images as input and creates a single compressed image on output. You specify the operation to be performed using the fieldFlags parameter.

    Special Considerations

    The Apple Component Video (YUV) and Motion JPEG codecs currently support this function.

  • Undocumented

    Declaration

    OSErr CDSequenceEquivalentImageDescriptionS ( ImageSequence seqID, ImageDescriptionHandle newDesc, Boolean *equivalent, Boolean *canSwitch );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    newDesc

    A handle to the ImageDescription structure structure that describes the compressed image.

    equivalent

    A pointer to a Boolean value. If the ImageDescriptionHandle provided in the newDesc parameter is equivalent to the ImageDescription structure currently in use by the image sequence, this value is set to TRUE. If the ImageDescriptionHandle is not equivalent, and therefore a new image sequence must be created to display an image using the new image description, this value is set to FALSE.

    canSwitch

    Undocumented

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Gets a data source for a decompression sequence.

    Declaration

    OSErr CDSequenceGetDataSource ( ImageSequence seqID, ImageSequenceDataSource *sourceID, OSType sourceType, long sourceInputNumber );

    Parameters

    seqID

    The image sequence that this source is associated with.

    sourceID

    A pointer to the source reference identifying this source.

    sourceType

    A four-character code describing how the input will be used. This value is passed by CDSequenceNewDataSource when the source is created.

    sourceInputNumber

    A value passed by CDSequenceNewDataSource when the source is created.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Sets a data queue as the source for a decompression sequence.

    Declaration

    OSErr CDSequenceSetSourceDataQueue ( ImageSequenceDataSource sourceID, QHdrPtr dataQueue );

    Parameters

    sourceID

    Contains the source identifier of the data source.

    dataQueue

    A pointer to a QHdr structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Sets a time base for a decompression sequence.

    Declaration

    OSErr CDSequenceSetTimeBase ( ImageSequence seqID, void *base );

    Parameters

    seqID

    A unique sequence identifier that was returned by CompressSequenceBegin.

    base

    A pointer to the time base for this operation. Your application obtains this time base identifier from NewTimeBase.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    When you run a visual effect outside a movie, you must designate a time base that will be used when the effect is run. The following code illustrates this use of CDSequenceSetTimeBase:

    1. // CDSequenceSetTimeBase coding example
    2. // See "Discovering QuickTime," page 310
    3. timeBase =NewTimeBase();
    4. SetTimeBaseRate(timeBase, 0);
    5. CDSequenceSetTimeBase(gEffectSequenceID, timeBase);
  • Undocumented

    Declaration

    void CompAdd ( wide *src, wide *dst );

    Parameters

    src

    Undocumented

    dst

    Undocumented

  • Undocumented

    Declaration

    long CompCompare ( const wide *a, const wide *minusb );

    Parameters

    a

    Undocumented

    minusb

    Undocumented

    Return Value

    Undocumented

  • Undocumented

    Declaration

    long CompDiv ( wide *numerator, long denominator, long *remainder );

    Parameters

    numerator

    Undocumented

    denominator

    Undocumented

    remainder

    Undocumented

    Return Value

    Undocumented

  • Undocumented

    Declaration

    void CompFixMul ( wide *compSrc, Fixed fixSrc, wide *compDst );

    Parameters

    compSrc

    Undocumented

    fixSrc

    Undocumented

    compDst

    Undocumented

  • Undocumented

    Declaration

    void CompMul ( long src1, long src2, wide *dst );

    Parameters

    src1

    Undocumented

    src2

    Undocumented

    dst

    Undocumented

  • Undocumented

    Declaration

    void CompMulDiv ( wide *co, long mul, long divisor );

    Parameters

    co

    Undocumented

    mul

    Undocumented

    divisor

    Undocumented

  • Undocumented

    Declaration

    void CompMulDivTrunc ( wide *co, long mul, long divisor, long *remainder );

    Parameters

    co

    Undocumented

    mul

    Undocumented

    divisor

    Undocumented

    remainder

    Undocumented

  • Undocumented

    Declaration

    void CompNeg ( wide *dst );

    Parameters

    dst

    Undocumented

  • Undocumented

    Declaration

    void CompShift ( wide *src, short shift );

    Parameters

    src

    Undocumented

    shift

    Undocumented

  • Undocumented

    Declaration

    unsigned long CompSquareRoot ( const wide *src );

    Parameters

    src

    Undocumented

    Return Value

    Undocumented

  • Undocumented

    Declaration

    void CompSub ( wide *src, wide *dst );

    Parameters

    src

    Undocumented

    dst

    Undocumented

  • Undocumented

    Declaration

    Fixed FixExp2 ( Fixed src );

    Parameters

    src

    A fixed integer.

    Return Value

    Undocumented

  • Undocumented

    Declaration

    Fixed FixLog2 ( Fixed src );

    Parameters

    src

    A fixed integer.

    Return Value

    Undocumented

  • Undocumented

    Declaration

    Fixed FixMulDiv ( Fixed src, Fixed mul, Fixed divisor );

    Parameters

    src

    Undocumented

    mul

    Undocumented

    divisor

    Undocumented

    Return Value

    Undocumented

  • Undocumented

    Declaration

    Fixed FixPow ( Fixed base, Fixed exp );

    Parameters

    base

    Undocumented

    exp

    Undocumented

    Return Value

    Undocumented

  • Undocumented

    Declaration

    Fract FracSinCos ( Fixed degree, Fract *cosOut );

    Parameters

    degree

    Undocumented

    cosOut

    Undocumented

    Return Value

    Undocumented

  • Returns the current frame number of the specified sequence.

    Declaration

    OSErr GetCSequenceFrameNumber ( ImageSequence seqID, long *frameNumber );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by the CompressSequenceBegin function.

    frameNumber

    A pointer to the current frame number of the sequence identified by the seqID parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Determines the current key frame rate of a sequence.

    Declaration

    OSErr GetCSequenceKeyFrameRate ( ImageSequence seqID, long *keyFrameRate );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by CompressSequenceBegin.

    keyFrameRate

    A pointer to a long integer that specifies the maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Gets the matrix that was specified for a decompression sequence by a call to SetDSequenceMatrix, or that was set at DecompressSequenceBegin.

    Declaration

    OSErr GetDSequenceMatrix ( ImageSequence seqID, MatrixRecordPtr matrix );

    Parameters

    seqID

    Contains the unique sequence identifier that was returned by DecompressSequenceBegin.

    matrix

    Points to a matrix structure that specifies how to transform the image during decompression

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Returns the display direction for a decompress sequence.

    Declaration

    OSErr GetDSequenceNonScheduledDisplayDirection ( ImageSequence sequence, Fixed *rate );

    Parameters

    sequence

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    rate

    A pointer to the display direction. Negative values represent backward display and positive values represent forward display.

    Return Value

    An error code. Returns noErr if there is no error.

  • Gets the display time for a decompression sequence.

    Declaration

    OSErr GetDSequenceNonScheduledDisplayTime ( ImageSequence sequence, TimeValue64 *displayTime, TimeScale *displayTimeScale );

    Parameters

    sequence

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    displayTime

    A pointer to a variable to hold the display time.

    displayTimeScale

    A pointer to a variable to hold the display time scale.

    Return Value

    An error code. Returns noErr if there is no error.

  • Locates and opens a graphics importer component for a file with flags that control the search process.

    Declaration

    OSErr GetGraphicsImporterForFileWithFlags ( const FSSpec *theFile, ComponentInstance *gi, long flags );

    Parameters

    theFile

    The file to be drawn using a graphics importer component.

    gi

    On return, contains a pointer to the ComponentInstance of the graphics importer. If no graphics importer can be found for the specified file, the gi will be set to NIL. If GetGraphicsImporterForFileWithFlags is able to locate a graphics importer for the file, the returned graphics importer ComponentInstance will already be set up to draw the specified file to the current port.

    flags

    Contains flags (see below) that control the graphics importer search process. See these constants:

    • kDontUseValidateToFindGraphicsImporter

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function first tries to locate a graphics importer component for the specified file based on its file type. If it is unable to locate a graphics importer component based on the Macintosh file type, or the call is made on a non-Macintosh file, GetGraphicsImporterForFile will try to locate a graphics importer component based on the file extension (such as .JPG or .GIF). If a graphics importer cannot be found using the file's type or extension, GetGraphicsImporterForFile asks each graphics importer to validate the file, until it either finds an importer that can handle the file or exhausts the list of possible importers. This validation attempt can be quite time-consuming. To bypass the validation attempt, pass kDontUseValidateToFindGraphicsImporter in the flags parameter.

  • Undocumented

    Declaration

    OSErr HitTestDSequenceData ( ImageSequence seqID, void *data, Size dataSize, Point where, long *hit, long hitFlags );

    Parameters

    seqID

    The unique sequence identifier that was returned by the DecompressSequenceBegin function.

    data

    A pointer to data.

    dataSize

    The size of the data.

    where

    A Point structure that defines the hit location.

    hit

    Undocumented

    hitFlags

    Undocumented

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Undocumented

    Declaration

    OSErr ICMDecompressCompleteS ( ImageSequence seqID, OSErr err, short flag, ICMCompletionProcRecordPtr completionRtn );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    err

    Indicates whether the operation succeeded or failed. See Error Codes.

    flag

    Undocumented

    completionRtn

    A pointer to an ICMCompletionProcRecord structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Retrieves pixel format information.

    Declaration

    OSErr ICMGetPixelFormatInfo ( OSType PixelFormat, ICMPixelFormatInfoPtr theInfo );

    Parameters

    PixelFormat

    A constant that identifies the format; see Pixel Formats.

    theInfo

    A pointer to your ICMPixelFormatInfo structure in which information is returned. You should initialize the size field of this structure with sizeof (ICMPixelFormatInfo). The function will not copy more than this number of bytes into the structure. On return, the size field contains the actual size of the data structure. If this amount is greater the size you passed in, that means you didn't retrieve all of the information.

    Return Value

    Returns cDepthErr if the pixel format is not valid. For other errors, see Error Codes. Returns noErr if there is no error.

  • Undocumented

    Declaration

    OSErr ICMSequenceGetChainMember ( ImageSequence seqID, ImageSequence *retSeqID, long flags );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    retSeqID

    Undocumented

    flags

    Undocumented

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Gets multiprocessing properties for compression and decompression sequences.

    Declaration

    OSErr ICMSequenceGetInfo ( ImageSequence seqID, OSType which, void *data );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    which

    A constant (see below) that determines the property to be returned. See these constants:

    • kICMSequenceTaskWeight

    • kICMSequenceTaskName

    data

    The value of the property indicated by the which parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function determines if ICM clients have requested that multiprocessor tasks assisting compression and decompression operations use specific task weights and task names.

    Special Considerations

    Apple's multiprocessing capability supports both co-operatively scheduled tasks and preemptively scheduled tasks. The support for preemptively tasks allow applications to create symmetrically scheduled preemptive tasks that can be run on a single processor machine, and will take full advantage of multiple processors when they are installed.

  • Undocumented

    Declaration

    OSErr ICMSequenceLockBits ( ImageSequence seqID, PixMapPtr dst, long flags );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    dst

    A pointer to a PixMap structure.

    flags

    Undocumented

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Sets multiprocessing properties for compression and decompression sequences.

    Declaration

    OSErr ICMSequenceSetInfo ( ImageSequence seqID, OSType which, void *data, Size dataSize );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    which

    A constant (see below) that determines the property to be set. See these constants:

    • kICMSequenceTaskWeight

    • kICMSequenceTaskName

    data

    The value of the property to be set.

    dataSize

    The length in bytes of the data parameter.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function lets ICM clients request that multiprocessor tasks assisting compression and decompression operations use specific task weights and task names.

    Special Considerations

    Apple's multiprocessing capability supports both co-operatively scheduled tasks and preemptively scheduled tasks. The support for preemptively tasks allow applications to create symmetrically scheduled preemptive tasks that can be run on a single processor machine, and will take full advantage of multiple processors when they are installed.

  • Undocumented

    Declaration

    OSErr ICMSequenceUnlockBits ( ImageSequence seqID, long flags );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    flags

    Undocumented

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Lets you define your own pixel format.

    Declaration

    OSErr ICMSetPixelFormatInfo ( OSType PixelFormat, ICMPixelFormatInfoPtr theInfo );

    Parameters

    PixelFormat

    A pixel format constant. See Pixel Formats.

    theInfo

    A pointer to an ICMPixelFormatInfo structure containing a definition of the new pixel format.

    Return Value

    Returns paramErr if the format is already defined. See Error Codes. Returns noErr if there is no error.

  • Fills out an ImageDescription structure corresponding to a PixMap structure.

    Declaration

    OSErr MakeImageDescriptionForPixMap ( PixMapHandle pixmap, ImageDescriptionHandle *idh );

    Parameters

    pixmap

    A handle to a PixMap structure.

    idh

    The handle of an ImageDescription structure. On entry, this parameter normally points to an ImageDescription structure whose contents are NIL. On return, the structure is correctly filled out for the selected PixMap.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Gets the extension to a file name.

    Declaration

    OSErr QTGetFileNameExtension ( ConstStrFileNameParam fileName, OSType fileType, OSType *extension );

    Parameters

    fileName

    A file name string.

    fileType

    A file type; see File Types and Creators.

    extension

    A pointer to the file name extension string.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Returns the bits per pixel for a given pixel format.

    Declaration

    short QTGetPixelSize ( OSType PixelFormat );

    Parameters

    PixelFormat

    A constant that identifies the pixel format; see Pixel Formats. This function returns meaningful information only for non-planar formats.

    Return Value

    The bits per pixel. Returns 0 if the format is unknown.

  • Retrieves the current PixMap extension's gamma level setting.

    Declaration

    Fixed QTGetPixMapHandleGammaLevel ( PixMapHandle pm );

    Parameters

    pm

    A handle to a PixMap structure that has a PixMapExtension structure.

    Return Value

    On return, the gamma level previously set (or the default level) for the pixel map referenced by the pm parameter.

    Discussion

    A typical use for this function is to retrieve the gamma level of a pixel map after a codec decompresses it into a PixMap structure.

  • Retrieves the current PixMap extension's requested gamma level setting.

    Declaration

    Fixed QTGetPixMapHandleRequestedGammaLevel ( PixMapHandle pm );

    Parameters

    pm

    A handle to a PixMap structure that has a PixMapExtension structure.

    Return Value

    On return, the requested gamma level previously set (or the default level) for the pixel map referenced by the pm parameter.

    Discussion

    A typical use for this function is to retrieve the gamma level of a pixel map after a codec decompresses it into a PixMap structure. The requested gamma level is used to control what gamma conversion is attempted during decompression. The requested gamma level may differ from the actual gamma level depending on the compressed data and the capabilities of the codecs involved.

  • Gets the rowBytes value for a pixel map accessed by a handle.

    Declaration

    long QTGetPixMapHandleRowBytes ( PixMapHandle pm );

    Parameters

    pm

    A handle to a PixMap structure.

    Return Value

    The rowBytes value.

  • Retrieves the current PixMap extension's gamma level setting.

    Declaration

    Fixed QTGetPixMapPtrGammaLevel ( PixMapPtr pm );

    Parameters

    pm

    A pointer to a PixMap structure that has a PixMapExtension structure.

    Return Value

    On return, the gamma level previously set (or the default level) for the pixel map pointed to by the pm parameter.

    Discussion

    A typical use for this function is to retrieve the gamma level of a pixel map after a codec decompresses it into a PixMap structure.

  • Retrieves the current PixMap extension's gamma level setting.

    Declaration

    Fixed QTGetPixMapPtrRequestedGammaLevel ( PixMapPtr pm );

    Parameters

    pm

    A pointer to a PixMap structure that has a PixMapExtension structure.

    Return Value

    On return, the requested gamma level previously set (or the default level) for the pixel map pointed to by the pm parameter.

    Discussion

    A typical use for this function is to retrieve the gamma level of a pixel map after a codec decompresses it into a PixMap structure. The requested gamma level is used to control what gamma conversion is attempted during decompression. The requested gamma level may differ from the actual gamma level depending on the compressed data and the capabilities of the codecs involved

  • Gets the rowBytes value for a pixel map accessed by a pointer.

    Declaration

    long QTGetPixMapPtrRowBytes ( PixMapPtr pm );

    Parameters

    pm

    A pointer to a PixMap structure.

    Return Value

    The rowBytes value.

  • Creates an offscreen graphics world that may have a non-Macintosh pixel format.

    Declaration

    OSErr QTNewGWorld ( GWorldPtr *offscreenGWorld, OSType PixelFormat, const Rect *boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags );

    Parameters

    offscreenGWorld

    On return, a pointer to the offscreen graphics world created by this routine.

    PixelFormat

    The new graphics world's pixel format; see Pixel Formats. This function won't work with planar pixel formats; use QTNewGWorldFromPtr instead. See the ICMPixelFormatInfo structure for a discussion of planar and chunky formats.

    boundsRect

    A pointer to the boundary rectangle and port rectangle for the offscreen pixel map. This becomes the boundary rectangle for the GDevice structure, if this function creates one. If you specify 0 in the PixelFormat parameter, the function interprets the boundaries in global coordinates that it uses to determine which screens intersect the rectangle. It then uses the pixel format, color table, and GDevice structure from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle. Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.

    cTable

    A handle to a ColorTable structure. If you pass NIL in this parameter, the function uses the default color table for the pixel format that you specify in the PixelFormat parameter. If you set the PixelFormat parameter to 0, the function ignores the cTable parameter and instead copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If you use this function on a computer that supports only basic QuickDraw, you may specify only NIL in this parameter.

    aGDevice

    A handle to a GDevice structure that is used only when you specify the noNewDevice flag in the flags parameter, in which case the function attaches this structure to the new offscreen graphics world. If you set the PixelFormat parameter to 0, or if you do not set the noNewDevice flag, the function ignores this parameter, so you should set it to NIL. If you set the PixelFormat parameter to 0, the function uses the GDevice structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. You should pass NIL in this parameter if the computer supports only basic QuickDraw. Generally, your application should never create GDevice structures for offscreen graphics worlds.

    flags

    Constants (see below) that identify options available to your application. You can set a combination of these flags. If you don't wish to use any of them, pass 0 in this parameter. In this case the default behavior is to create an offscreen graphics world where the base address for the offscreen pixel image is unpurgeable, the graphics world uses an existing GDevice structure (if you pass 0 in the depth parameter) or creates a new GDevice structure, it uses memory in your application heap, and it allows graphics accelerators to cache the offscreen pixel image. See these constants:

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Wraps a graphics world and pixel map structure around an existing block of memory containing an image.

    Declaration

    OSErr QTNewGWorldFromPtr ( GWorldPtr *gw, OSType pixelFormat, const Rect *boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags, void *baseAddr, long rowBytes );

    Parameters

    gw

    On entry, a pointer that isn't going to change during the lifetime of the allocated graphics world. On return, this pointer references the offscreen graphics world created by this function.

    pixelFormat

    The new graphics world's pixel format; see Pixel Formats.

    boundsRect

    A pointer to the boundary rectangle and port rectangle for the offscreen pixel map. This becomes the boundary rectangle for the GDevice structure, if this function creates one. If you specify 0 in the pixelFormat parameter, the function interprets the boundaries in global coordinates that it uses to determine which screens intersect the rectangle. It then uses the pixel format, color table, and GDevice structure from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle. Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.

    cTable

    A handle to a ColorTable structure. If you pass NIL in this parameter, the function uses the default color table for the pixel format that you specify in the pixelFormat parameter. If you set the pixelFormat parameter to 0, the function ignores the cTable parameter and instead copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If you use this function on a computer that supports only basic QuickDraw, you may specify only NIL in this parameter.

    aGDevice

    A handle to a GDevice structure that is used only when you specify the noNewDevice flag in the flags parameter, in which case the function attaches this structure to the new offscreen graphics world. If you set the pixelFormat parameter to 0, or if you do not set the noNewDevice flag, the function ignores this parameter, so you should set it to NIL. If you set the pixelFormat parameter to 0, the function uses the GDevice structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. You should pass NIL in this parameter if the computer supports only basic QuickDraw. Generally, your application should never create GDevice structures for offscreen graphics worlds.

    flags

    A constant (see below) that identifies an option available to your application. If you don't wish to use this option, pass 0 in this parameter. In this case the default behavior is to create an offscreen graphics world that uses an existing GDevice structure (if you pass 0 in the depth parameter) or creates a new GDevice structure. Most constants used in creating a GWorld are irrelevant for this function, as its purpose is to wrap a GWorld around an existing block of pixels rather than to define and create a pixmap. See these constants:

    baseAddr

    The base address for the pixel data.

    rowBytes

    The total size of the pixel data divided by the height of the pixel map. In other words, the number of bytes in one row of pixels or the number of bytes between vertically adjacent pixels.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function wraps a GWorld around an existing pixel map. Note that it does not copy the pixmap. A subsequent call to DisposeGWorld will not dispose of the pixel map; it will only dispose of the GWorld wrapper. It is the caller's responsibility to dispose of the pixel map.

    You can use this call to allocate an offscreen graphics world using special memory (such as on a video card). If you have an image in memory that belong to something else (a hardware screen buffer, a 3D card, or another file format or program), you can use this function to wrap a graphics world around the image and then use QuickTime calls on that graphics world to compress it, scale it, draw to it, and so on. If your new graphics world has a planar pixel format, you must use this call instead of QTNewGWorld.

    Special Considerations

    Do not unlock the pixels of the allocated graphics world. If your original pixels are from another graphics world then you must ensure that the source pixels are locked.

  • Sets the gamma level of a pixel map.

    Declaration

    OSErr QTSetPixMapHandleGammaLevel ( PixMapHandle pm, Fixed gammaLevel );

    Parameters

    pm

    A handle to a PixMap structure that has a PixMapExtension structure.

    gammaLevel

    The new gamma level.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function does not convert the contents of the PixMap structure. A typical usage would be to set the gamma level of a pixel map before compressing it so that the codec knows if it needs to do additional gamma correcting when compressing.

  • Sets the requested gamma level of a pixel map.

    Declaration

    OSErr QTSetPixMapHandleRequestedGammaLevel ( PixMapHandle pm, Fixed requestedGammaLevel );

    Parameters

    pm

    A handle to a PixMap structure that has a PixMapExtension structure.

    requestedGammaLevel

    A specified gamma level or a constant (see below). See these constants:

    • kQTUsePlatformDefaultGammaLevel

    • kQTUseSourceGammaLevel

    • kQTCCIR601VideoGammaLevel

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function does not convert the contents of the PixMap structure. A typical usage would be to set the requested gamma level of a pixel map before decompressing so that the codec knows what gamma correction is necessary when decompressing into the PixMap structure. The resulting gamma level can then be found by calling QTGetPixMapHandleGammaLevel.

  • Sets the rowBytes value for a pixel map accessed by a handle.

    Declaration

    OSErr QTSetPixMapHandleRowBytes ( PixMapHandle pm, long rowBytes );

    Parameters

    pm

    A handle to a PixMap structure.

    rowBytes

    The rowBytes value to be set.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Sets the gamma level of a pixel map.

    Declaration

    OSErr QTSetPixMapPtrGammaLevel ( PixMapPtr pm, Fixed gammaLevel );

    Parameters

    pm

    A pointer to a PixMap structure that has a PixMapExtension structure.

    gammaLevel

    The new gamma level.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function does not convert the contents of the PixMap structure. A typical usage would be to set the gamma level of a pixel map before compressing it so that the codec knows if it needs to do additional gamma correcting when compressing.

  • Sets the requested gamma level of a pixel map.

    Declaration

    OSErr QTSetPixMapPtrRequestedGammaLevel ( PixMapPtr pm, Fixed requestedGammaLevel );

    Parameters

    pm

    A pointer to a PixMap structure that has a PixMapExtension structure.

    requestedGammaLevel

    A specified gamma level or a constant (see below). See these constants:

    • kQTUsePlatformDefaultGammaLevel

    • kQTUseSourceGammaLevel

    • kQTCCIR601VideoGammaLevel

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This function does not convert the contents of the PixMap structure. A typical usage would be to set the requested gamma level of a pixel map before decompressing so that the codec knows what gamma correction is necessary when decompressing into the PixMap structure. The resulting gamma level can then be found by calling QTGetPixMapPtrGammaLevel.

  • Sets the rowBytes value for a pixel map accessed by a pointer.

    Declaration

    OSErr QTSetPixMapPtrRowBytes ( PixMapPtr pm, long rowBytes );

    Parameters

    pm

    A pointer to a PixMap structure.

    rowBytes

    The rowBytes value to be set.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Changes the pixel depth, boundary rectangle, or color table for an existing offscreen graphics world with a non-Macintosh pixel format.

    Declaration

    GWorldFlags QTUpdateGWorld ( GWorldPtr *offscreenGWorld, OSType PixelFormat, const Rect *boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags );

    Parameters

    offscreenGWorld

    On input, a pointer to an existing offscreen graphics world; upon completion, the pointer to the updated offscreen graphics world.

    PixelFormat

    The updated graphics world's pixel format; see Pixel Formats.

    boundsRect

    A pointer to the boundary rectangle and port rectangle for the updated offscreen pixel map. This becomes the boundary rectangle for the GDevice structure, if this function creates one. If you specify 0 in the PixelFormat parameter, the function interprets the boundaries in global coordinates that it uses to determine which screens intersect the rectangle. It then uses the pixel format, color table, and GDevice structure from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle. If the rectangle you specify in this parameter differs from, but has the same size as, the previous boundary rectangle, the function realigns the pixel image to the screen for optimum performance for CopyBits. Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.

    cTable

    A handle to a ColorTable structure for the updated graphics world. If you pass NIL in this parameter, the function uses the default color table for the pixel format that you specify in the PixelFormat parameter. If you set the PixelFormat parameter to 0, the function ignores the cTable parameter and instead copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If the color table that you specify in this parameter is different from the previous color table, or if the color table associated with the GDevice structure that you specify in the aGDevice parameter is different, the function maps the pixel values in the offscreen pixel map to the new color table. If you use this function on a computer that supports only basic QuickDraw, you may specify only NIL in this parameter.

    aGDevice

    A handle to a GDevice structure that is used only when you specify the noNewDevice flag in the flags parameter, in which case the function attaches this structure to the new offscreen graphics world. If you set the PixelFormat parameter to 0, or if you do not set the noNewDevice flag, the function ignores this parameter, so you should set it to NIL. If you set the PixelFormat parameter to 0, the function uses the GDevice structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. You should pass NIL in this parameter if the computer supports only basic QuickDraw. Generally, your application should never create GDevice structures for offscreen graphics worlds.

    flags

    Constants (see below) that identify options available to your application. You can set a combination of these flags. If you don't wish to use any of them, pass 0 in this parameter. In this case the default behavior is to create an offscreen graphics world where the base address for the offscreen pixel image is unpurgeable, the graphics world uses an existing GDevice structure (if you pass 0 in the depth parameter) or creates a new GDevice structure, it uses memory in your application heap, and it allows graphics accelerators to cache the offscreen pixel image. See these constants:

    Return Value

    A constant (see below) that reports on the operation of this function.

    Discussion

    If the Memory Manager purged the base address for the offscreen pixel image, this function reallocates the memory but the pixel image is lost. You must reconstruct it.

    Special Considerations

    This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

  • Defines a matrix that maps between four input points and four output points.

    Declaration

    OSErr QuadToQuadMatrix ( const Fixed *source, const Fixed *dest, MatrixRecord *map );

    Parameters

    source

    A pointer to four input FixedPoint points.

    dest

    A pointer to four output FixedPoint points.

    map

    A pointer to a MatrixRecord structure that maps the value passed in source to the value passed in dest.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Undocumented

    Declaration

    OSErr ReplaceDSequenceImageDescription ( ImageSequence seqID, ImageDescriptionHandle newDesc );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    newDesc

    A handle to an ImageDescription structure.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Informs the compressor in use for the specified sequence that frames are being compressed out of order.

    Declaration

    OSErr SetCSequenceFrameNumber ( ImageSequence seqID, long frameNumber );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    frameNumber

    The frame number of the frame that is being compressed out of sequence.

    Return Value

    See Error Codes. Returns noErr if there is no error.

    Discussion

    This information is necessary only for compressors that are sequence-sensitive.

  • Sets data loading flags.

    Declaration

    OSErr SetDSequenceFlags ( ImageSequence seqID, long flags, long flagsMask );

    Parameters

    seqID

    The unique sequence identifier assigned by CompressSequenceBegin or DecompressSequenceBegin.

    flags

    Flags (see below) for data loading. See these constants:

    • codecDSequenceSingleField

    flagsMask

    Use this field to preserve the state of any flags you do not wish to alter. If a flag (see below) is set in this field, and is not set in the flags parameter, it will not be changed from its current setting.

    Return Value

    See Error Codes. Returns noErr if there is no error.

  • Sets the display direction for a decompress sequence.

    Declaration

    OSErr SetDSequenceNonScheduledDisplayDirection ( ImageSequence sequence, Fixed rate );

    Parameters

    sequence

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    rate

    The display direction to be set. Negative values represent backward display and positive values represent forward display.

    Return Value

    An error code. Returns noErr if there is no error.

  • Sets the display time for a decompression sequence.

    Declaration

    OSErr SetDSequenceNonScheduledDisplayTime ( ImageSequence sequence, TimeValue64 displayTime, TimeScale displayTimeScale, UInt32 flags );

    Parameters

    sequence

    Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

    displayTime

    The display time to be set.

    displayTimeScale

    The display time scale to be set.

    flags

    Not used; set to 0.

    Return Value

    An error code. Returns noErr if there is no error.

  • Performs multiplications and divisions on unsigned fixed-point numbers.

    Declaration

    Fixed UnsignedFixMulDiv ( Fixed src, Fixed mul, Fixed divisor );

    Parameters

    src

    The value to be multiplied or divided.

    mul

    The multiplier to be applied to the value in the src parameter. Pass 0x00010000 if you do not want to multiply.

    divisor

    The divisor to be applied to the value in the src parameter. Pass 0x00010000 if you do not want to divide.

    Return Value

    The fixed-point number that is the value of the src parameter, multiplied by the value in the mul parameter and divided by the value in the divisor parameter. The function performs both operations before returning.

Callbacks

Data Types

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef Component CodecComponent;

    Import Statement

  • Contains a list of CodecNameSpec structures.

    Declaration

    struct CodecNameSpecList { short count; CodecNameSpec list[1]; };

    Fields

    count

    Indicates the number of compressor name structures contained in the list array that follows.

    list

    Contains an array of compressor name structures. Each structure corresponds to one compressor component or type that meets the selection criteria your application specifies when it calls GetCodecNameList.

    Discussion

    See also DisposeCodecNameList and GetCodecNameList.

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef CodecNameSpecList * CodecNameSpecListPtr;

    Import Statement

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef ConstStr255Param ConstStrFileNameParam;

    Import Statement

  • Communicates information to compressors that can constrain compressed data to a specific data rate.

    Declaration

    struct DataRateParams { long dataRate; long dataOverrun; long frameDuration; long keyFrameRate; CodecQ minSpatialQuality; CodecQ minTemporalQuality; };

    Fields

    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.

    minSpatialQuality

    A constant (see below) that specifies the minimum spatial quality the compressor should use to meet the requested data rate. See these constants:

    • codecMinQuality

    • codecLowQuality

    • codecNormalQuality

    • codecHighQuality

    • codecMaxQuality

    • codecLosslessQuality

    minTemporalQuality

    A constant (see below) that specifies the minimum temporal quality the compressor should use to meet the requested data rate.

    Discussion

    The CodecQ data type defines a field that identifies the quality characteristics of a given image or sequence. Note that individual components may not implement all the quality levels shown here. In addition, components may implement other quality levels in the range from codecMinQuality to codecMaxQuality. Relative quality should scale within the defined value range. Values above codecLosslessQuality are reserved for use by individual components.

    See also GetCSequenceDataRateParams and SetCSequenceDataRateParams.

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef DataRateParams * DataRateParamsPtr;

    Import Statement

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef Component DecompressorComponent;

    Import Statement

  • Defines the size and location of a rectangle in fixed-point numbers.

    Declaration

    struct FixedRect { Fixed left; Fixed top; Fixed right; Fixed bottom; };

    Fields

    left

    The x coordinate of the upper-left corner of the rectangle.

    top

    The y coordinate of the upper-left corner of the rectangle.

    right

    The x coordinate of the lower-right corner of the rectangle.

    bottom

    The y coordinate of the lower-right corner of the rectangle.

    Discussion

    See also TransformFixedRect.

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef long Fract;

    Import Statement

  • Defines a pixel format.

    Declaration

    struct ICMPixelFormatInfo { long size; unsigned long formatFlags; short bitsPerPixel[14]; };

    Fields

    size

    The size of this structure. This quantity isn't necessarily equal to sizeof(ICMPixelFormatInfo) because it is dependent on whether the pixel format is chunky or planar, and, if planar, the number of components (see below).

    formatFlags

    A constant (see below) indicating the pixel format. See these constants:

    • kICMPixelFormatIsPlanarMask

    • kICMPixelFormatIsIndexed

    • kICMPixelFormatIsSupportedByQD

    bitsPerPixel

    An array that defines the number of bits for each component. The element bitsPerPixel[0] contains the number of bits for the first component, bitsPerPixel[1] the number of bits for the second component, etc. The meaning of this parameter depends on the format flag (see below).

    Discussion

    You can represent a format that has from 1 to 14 discrete components using this data structure. For ARGB, there are 4 components. RGB without an alpha channel has 3 components. A component count of 15 is reserved for future expansion.

    See also ICMGetPixelFormatInfo and ICMSetPixelFormatInfo.

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef ICMPixelFormatInfo * ICMPixelFormatInfoPtr;

    Import Statement

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef long ImageFieldSequence;

    Import Statement

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef long ImageSequenceDataSource;

    Import Statement

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef long ImageTranscodeSequence;

    Import Statement

  • Specifies resolutions when creating images.

    Declaration

    struct OpenCPicParams { Rect srcRect; Fixed hRes; Fixed vRes; short version; short reserved1; long reserved2; };

    Fields

    srcRect

    The optimal bounding rectangle for the resolution indicated by the hRes and vRes fields. To display a picture at a resolution other than that specified in the the hRes and vRes fields, your application should compute an appropriate destination rectangle by scaling the image's width and height by the destination resolution divided by the source resolution.

    hRes

    The best horizontal resolution for the picture. A value of 0x0048000 specifies a horizontal resolution of 72 dpi.

    vRes

    The best vertical resolution for the picture. A value of 0x0048000 specifies a vertical resolution of 72 dpi.

    version

    Always set this field to -2.

    reserved1

    Reserved; set to 0.

    reserved2

    Reserved; set to 0.

    Discussion

    See also GetPictureFileHeader.

  • A Windows queue header structure.

    Declaration

    struct QHdr { short qFlags; short pad; long MutexID; QElemPtr qHead; QElemPtr qTail; };

    Fields

    qFlags

    Undocumented

    pad

    Unused.

    MutexID

    Undocumented

    qHead

    Undocumented

    qTail

    Undocumented

    Discussion

    See also CDSequenceSetSourceDataQueue, Dequeue, Enqueue, InitializeQHdr, and TerminateQHdr.

  • Represents a type used by the Compression and Decompression API.

    Declaration

    typedef QHdr * QHdrPtr;

    Import Statement

Constants

  • Constants passed to StdPix.

    Declaration

    enum { callStdBits = 1, callOldBits = 2, noDefaultOpcodes = 4 };

  • Constants that represent <codeVoice>DSequence</codeVoice> flags.

    Declaration

    enum { codecDSequenceDisableOverlaySurface = (1L << 5), codecDSequenceSingleField = (1L << 6), codecDSequenceBidirectionalPrediction = (1L << 7), codecDSequenceFlushInsteadOfDirtying = (1L << 8), codecDSequenceEnableSubPixelPositioning = (1L << 9), codecDSequenceDeinterlaceFields = (1L << 10) };

  • Constants passed to FCompressImage.

    Declaration

    enum { codecFlagUseImageBuffer = (1L << 0), /* decompress */ codecFlagUseScreenBuffer = (1L << 1), /* decompress */ codecFlagUpdatePrevious = (1L << 2), /* compress */ codecFlagNoScreenUpdate = (1L << 3), /* decompress */ codecFlagWasCompressed = (1L << 4), /* compress */ codecFlagDontOffscreen = (1L << 5), /* decompress */ codecFlagUpdatePreviousComp = (1L << 6), /* compress */ codecFlagForceKeyFrame = (1L << 7), /* compress */ codecFlagOnlyScreenUpdate = (1L << 8), /* decompress */ codecFlagLiveGrab = (1L << 9), /* compress */ codecFlagDiffFrame = (1L << 9), /* decompress */ codecFlagDontUseNewImageBuffer = (1L << 10), /* decompress */ codecFlagInterlaceUpdate = (1L << 11), /* decompress */ codecFlagCatchUpDiff = (1L << 12), /* decompress */ codecFlagSupportDisable = (1L << 13), /* decompress */ codecFlagReenable = (1L << 14) /* decompress */ };

    Constants

    • codecFlagUpdatePrevious

      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.

    • codecFlagWasCompressed

      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.

    • codecFlagUpdatePreviousComp

      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.

    • codecFlagLiveGrab

      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.

    • codecFlagDiffFrame

      Decompress.

    • codecFlagSupportDisable

      Decompress.

  • Constants that represent color modes.

    Declaration

    enum { defaultDither = 0, forceDither = 1, suppressDither = 2, useColorMatching = 4 }; enum { graphicsModeStraightAlpha = 256, graphicsModePreWhiteAlpha = 257, graphicsModePreBlackAlpha = 258, graphicsModeComposition = 259, graphicsModeStraightAlphaBlend = 260, graphicsModePreMulColorAlpha = 261, graphicsModePerComponentAlpha = 272 }; enum { kQTTIFFUserDataPrefix = 0x74690000 , /* Added to some tag values in TIFF IFDs to generate user data codes. (0x7469 is 'ti'.) */ /* For example, YCbCrPositioning is tag x0213, so its user data code is 0x74690213. */ kQTTIFFExifUserDataPrefix = 0x65780000 , /* Added to tag values in Exif IFDs to generate user data codes. (0x6578 is 'ex'.) */ /* For example, DateTimeOriginal is tag x9003, so its user data code is 0x65789003. */ kQTTIFFExifGPSUserDataPrefix = 0x67700000 , /* Added to tag values in Exif GPS IFDs to generate user data codes. (0x6770 is 'gp'.) */ /* For example, GPSAltitude is tag x0006, so its user data code is 0x6770006. */ kQTAlphaMode = 'almo', /* UInt32; eg, graphicsModeStraightAlpha or graphicsModePreBlackAlpha */ kQTAlphaModePreMulColor = 'almp', /* RGBColor; used if kQTAlphaMode is graphicsModePreMulColorAlpha */ kUserDataIPTC = 'iptc' };

    Constants

    • kQTTIFFUserDataPrefix

      Added to some tag values in TIFF IFDs to generate user data codes. (0x7469 is 'ti'.).

    • kQTTIFFExifUserDataPrefix

      Added to tag values in Exif IFDs to generate user data codes. (0x6578 is 'ex'.).

    • kQTTIFFExifGPSUserDataPrefix

      Added to tag values in Exif GPS IFDs to generate user data codes. (0x6770 is 'gp'.).

    • kQTAlphaMode

      UInt32; for example, graphicsModeStraightAlpha or graphicsModePreBlackAlpha.

    • kQTAlphaModePreMulColor

      RGBColor; used if kQTAlphaMode is graphicsModePreMulColorAlpha.

  • Constants passed to GetGraphicsImporterForFileWithFlags.

    Declaration

    enum { kDontUseValidateToFindGraphicsImporter = 1L << 0 };

  • Constants passed to QTSetPixMapPtrRequestedGammaLevel.

    Declaration

    enum { kQTUsePlatformDefaultGammaLevel = 0, /* When decompressing into this PixMap, gamma-correct to the platform's standard gamma. */ kQTUseSourceGammaLevel = -1L , /* When decompressing into this PixMap, don't perform gamma-correction. */ kQTCCIR601VideoGammaLevel = 0x00023333 /* 2.2, standard television video gamma.*/ };

    Constants

    • kQTCCIR601VideoGammaLevel

      Gamma 2.2, for ITU-R BT.601 based video.