Mac Developer Library

Developer

Frameworks Framework Reference Compression and Decompression Reference for QuickTime

Options
Deployment Target:

On This Page
Language:

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

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • AlignWindow AlignWindow (OS X v10.9)

    Moves a specified window to the nearest optimal alignment position.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Drags the specified window along an optimal alignment grid.

    Declaration

    Objective-C

    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:

    • // DragAlignedWindow coding example
    • // See "Discovering QuickTime," page 265
    • Boolean IsQuickTimeInstalled (void)
    • {
    • OSErr nErr;
    • long lResult;
    • nErr =Gestalt(gestaltQuickTime, &lResult);
    • return (nErr ==noErr);
    • }
    • void MyInitialize (void)
    • {
    • InitGraf(&qd.thePort);
    • InitFonts();
    • InitWindows();
    • InitMenus();
    • TEInit();
    • InitDialogs(NIL);
    • MaxApplZone();
    • EnterMovies();
    • }
    • WindowRef MakeMyWindow (void)
    • {
    • WindowRef pMacWnd;
    • Rect rectWnd ={0, 0, 120, 160};
    • Rect rectBest;
    • // figure out the best monitor for the window
    • GetBestDeviceRect(NIL, &rectBest);
    • // put the window in the top left corner of that monitor
    • OffsetRect(&rectWnd, rectBest.left + 10, rectBest.top + 50);
    • // create the window
    • pMacWnd =NewCWindow(NIL, &rectWnd, "\pGrabber",
    • TRUE, noGrowDocProc, (WindowRef)-1,
    • TRUE, 0);
    • // set the port to the new window
    • SetPort(pMacWnd);
    • return pMacWnd;
    • }
    • main (void)
    • {
    • WindowRef pMacWnd;
    • SeqGrabComponent seqGrab;
    • SGChannel sgchanVideo, sgchanSound;
    • Boolean bDone =FALSE;
    • OSErr nErr;
    • MyInitialize();
    • pMacWnd =MakeMyWindow();
    • seqGrab =MakeMySequenceGrabber(pMacWnd);
    • if (seqGrab ==NIL)
    • return;
    • MakeMyGrabChannels(seqGrab, &sgchanVideo, &sgchanSound,
    • &pMacWnd->
    • portRect, FALSE);
    • nErr =SGStartPreview(seqGrab);
    • while (!bDone) {
    • ICMAlignmentProcRecord apr;
    • short nPart;
    • WindowRef pWhichWnd;
    • EventRecord er;
    • GetNextEvent(everyEvent, &er);
    • switch (er.what) {
    • case nullEvent: // give the sequence grabber time
    • nErr =SGIdle(seqGrab);
    • if (nErr !=noErr)
    • bDone =TRUE;
    • break;
    • case updateEvt:
    • if (er.message ==(long)pMacWnd) {
    • // inform the sequence grabber of the update
    • SGUpdate(seqGrab,((WindowPeek)
    • pMacWnd)->
    • updateRgn);
    • // and swallow the update event
    • BeginUpdate(pMacWnd);
    • EndUpdate(pMacWnd);
    • }
    • break;
    • case mouseDown:
    • nPart =FindWindow(er.where, &pWhichWnd);
    • if (pWhichWnd !=pMacWnd)
    • break;
    • switch (nPart) {
    • case inContent:
    • // pause until mouse button is released
    • SGPause(seqGrab, TRUE);
    • while (StillDown())
    • SGPause(seqGrab, FALSE);
    • break;
    • case inGoAway:
    • bDone =TrackGoAway(pMacWnd, er.where);
    • break;
    • case inDrag:
    • // pause when dragging window so video
    • // doesn't draw in the wrong place
    • SGPause(seqGrab, TRUE);
    • SGGetAlignmentProc(seqGrab, &apr);
    • DragAlignedWindow(pMacWnd,
    • er.where,
    • &screenBits.bounds,
    • NIL, &alignProc);
    • SGPause(seqGrab, FALSE);
    • break;
    • }
    • break;
    • }
    • }
    • // clean up
    • SGStop(seqGrab);
    • CloseComponent(seqGrab);
    • DisposeWindow(pMacWnd);
    • }

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • TransformRgn TransformRgn (OS X v10.9)

    Applies a specified matrix to a region.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Assigns a data-unloading function to a sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Adjusts the key frame rate for the current sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sets the preferred packet size for a sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Adjusts the decompression accuracy for the current sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Assigns a data-loading function to a sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Assigns a clipping region to a sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Assigns a mapping matrix to a sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Assigns a blend matte to a sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Defines the portion of an image to decompress.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sets the mode used when drawing a decompressed image.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Obtains the data rate parameters previously set with SetCSequenceDataRateParams.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • GDGetScale GDGetScale (OS X v10.9)

    Returns the current scale of the given screen graphics device.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • GDHasScale GDHasScale (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • GDSetScale GDSetScale (OS X v10.9)

    Sets a screen graphics device to a new scale.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

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

    • // MakeImageDescriptionForEffect coding example
    • // Return a new image description with default and specified values.
    • ImageDescriptionHandle QTEffSeg_MakeSampleDescription (
    • OSType theEffectType, short theWidth, short theHeight)
    • {
    • ImageDescriptionHandle mySampleDesc =NIL;
    • #if USES_MAKE_IMAGE_DESC_FOR_EFFECT
    • OSErr myErr =noErr;
    • // create a new sample description
    • myErr =MakeImageDescriptionForEffect(theEffectType, &mySampleDesc);
    • if (myErr !=noErr)
    • return(NIL);
    • #else
    • // create a new sample description
    • mySampleDesc =(ImageDescriptionHandle)
    • NewHandleClear(sizeof(ImageDescription));
    • if (mySampleDesc ==NIL)
    • return(NIL);
    • // fill in the fields of the sample description
    • (**mySampleDesc).cType =theEffectType;
    • (**mySampleDesc).idSize =sizeof(ImageDescription);
    • (**mySampleDesc).hRes =72L << 16;
    • (**mySampleDesc).vRes =72L << 16;
    • (**mySampleDesc).frameCount =1;
    • (**mySampleDesc).depth =0;
    • (**mySampleDesc).clutID =-1;
    • #endif
    • (**mySampleDesc).vendor =kAppleManufacturer;
    • (**mySampleDesc).temporalQuality =codecNormalQuality;
    • (**mySampleDesc).spatialQuality =codecNormalQuality;
    • (**mySampleDesc).width =theWidth;
    • (**mySampleDesc).height =theHeight;
    • return(mySampleDesc);
    • }

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Adds a preview to a file.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Creates a preview for a file.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    OSErr GetCompressedImageSize ( ImageDescriptionHandle desc, Ptr data, long bufferSize, ICMDataProcRecordPtr dataProc, long *dataSize );

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    OSErr GetCompressionTime ( PixMapHandle src, const Rect *srcRect, short colorDepth, CodecType cType, CompressorComponent codec, CodecQ *spatialQuality, CodecQ *temporalQuality, unsigned long *compressTime );

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    OSErr GetMaxCompressionSize ( PixMapHandle src, const Rect *srcRect, short colorDepth, CodecQ quality, CodecType cType, CompressorComponent codec, long *size );

    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:

    • // GetMaxCompressionSize coding example
    • // See "Discovering QuickTime," page 286
    • PicHandle GetQTCompressedPict (PixMapHandle hpmImage)
    • {
    • long lMaxCompressedSize =0;
    • Handle hCompressedData =NIL;
    • Ptr pCompressedData;
    • ImageDescriptionHandle hImageDesc =NIL;
    • OSErr nErr;
    • PicHandle hpicPicture =NIL;
    • Rect rectImage =(**hpmImage).bounds;
    • CodecType dwCodecType =kJPEGCodecType;
    • CodecComponent codec =(CodecComponent)anyCodec;
    • CodecQ dwSpatialQuality =codecNormalQuality;
    • short nDepth =0; // let ICM choose depth
    • nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,
    • dwSpatialQuality,
    • dwCodecType,
    • (CompressorComponent)codec,
    • &lMaxCompressedSize);
    • if (nErr !=noErr)
    • return NIL;
    • hImageDesc =(ImageDescriptionHandle)NewHandle(4);
    • hCompressedData =NewHandle(lMaxCompressedSize);
    • if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {
    • MoveHHi(hCompressedData);
    • HLock(hCompressedData);
    • pCompressedData =StripAddress(*hCompressedData);
    • nErr =CompressImage(hpmImage,
    • &rectImage,
    • dwSpatialQuality,
    • dwCodecType,
    • hImageDesc,
    • pCompressedData);
    • if (nErr ==noErr) {
    • ClipRect(&rectImage);
    • hpicPicture =OpenPicture(&rectImage);
    • nErr =DecompressImage(pCompressedData,
    • hImageDesc,
    • hpmImage,
    • &rectImage,
    • &rectImage,
    • srcCopy,
    • NIL);
    • ClosePicture();
    • }
    • if (theErr || (GetHandleSize((Handle)hpicPicture) ==
    • sizeof(Picture))) {
    • KillPicture(hpicPicture);
    • hpicPicture =NIL;
    • }
    • }
    • if (hImageDesc !=NIL)
    • DisposeHandle((Handle)hImageDesc);
    • if (hCompressedData !=NIL)
    • DisposeHandle(hCompressedData);
    • return hpicPicture;
    • }

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • 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

    Objective-C

    OSErr GetSimilarity ( PixMapHandle src, const Rect *srcRect, ImageDescriptionHandle desc, Ptr data, Fixed *similarity );

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Determines the version of the installed Image Compression Manager.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • FindCodec FindCodec (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • GetCodecInfo GetCodecInfo (OS X v10.9)

    Returns information about a single compressor component.

    Declaration

    Objective-C

    OSErr GetCodecInfo ( CodecInfo *info, CodecType cType, CodecComponent codec );

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Retrieves a list of installed compressor components or types.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Signals the completion of a decompression operation.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Hides the cursor during decompression operations.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Disposes transcoded image data.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Transcodes a frame of image data.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Initiates an image transcoder sequence operation.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Ends an image transcoder sequence operation.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Creates a thumbnail picture from a specified Picture structure.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Creates a thumbnail picture from a specified picture file.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Creates a thumbnail picture from a specified PixMap structure.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • ConcatMatrix ConcatMatrix (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CopyMatrix CopyMatrix (OS X v10.9)

    Copies the contents of one matrix into another matrix.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • EqualMatrix EqualMatrix (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Obtains information about a matrix.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • MapMatrix MapMatrix (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • RectMatrix RectMatrix (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • RotateMatrix RotateMatrix (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • ScaleMatrix ScaleMatrix (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • SkewMatrix SkewMatrix (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Adds a translation value to a specified matrix.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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:

    • // Get a graphics importer for the image file, determine the natural size
    • // of the image, and draw the image
    • // See "Discovering QuickTime," page 274
    • void drawFile(const FSSpec *fss, const Rect *boundsRect)
    • {
    • GraphicsImportComponent gi;
    • GetGraphicsImporterForFile(fss, &gi);
    • GraphicsImportSetBoundsRect(gi, boundsRect);
    • GraphicsImportDraw(gi);
    • CloseComponent(gi);
    • }

    Special Considerations

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

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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:

    • // GetBestDeviceRect coding example
    • // See "Discovering QuickTime," page 265
    • WindowRef MakeMyWindow (void)
    • {
    • WindowRef pMacWnd;
    • Rect rectWnd ={0, 0, 120, 160};
    • Rect rectBest;
    • // figure out the best monitor for the window
    • GetBestDeviceRect(NIL, &rectBest);
    • // put the window in the top left corner of that monitor
    • OffsetRect(&rectWnd, rectBest.left + 10, rectBest.top + 50);
    • // create the window
    • pMacWnd =NewCWindow(NIL, &rectWnd, "\pGrabber",
    • TRUE, noGrowDocProc, (WindowRef)-1, TRUE, 0);
    • // set the port to the new window
    • SetPort(pMacWnd);
    • return pMacWnd;
    • }

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Creates an offscreen graphics world.

    Declaration

    Objective-C

    OSErr NewImageGWorld ( GWorldPtr *gworld, ImageDescriptionHandle idh, GWorldFlags flags );

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Adds an extension to an ImageDescription structure.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Retrieves an image description structure extension type.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Removes a specified extension from an ImageDescription structure.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • 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

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • 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

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • 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

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    • // CompressImage coding example
    • // See "Discovering QuickTime," page 286
    • PicHandle GetQTCompressedPict (PixMapHandle hpmImage)
    • {
    • long lMaxCompressedSize =0;
    • Handle hCompressedData =NIL;
    • Ptr pCompressedData;
    • ImageDescriptionHandle hImageDesc =NIL;
    • OSErr nErr;
    • PicHandle hpicPicture =NIL;
    • Rect rectImage =(**hpmImage).bounds;
    • CodecType dwCodecType =kJPEGCodecType;
    • CodecComponent codec =(CodecComponent)anyCodec;
    • CodecQ dwSpatialQuality =codecNormalQuality;
    • short nDepth =0; // let ICM choose depth
    • nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,
    • dwSpatialQuality,
    • dwCodecType,
    • (CompressorComponent)codec,
    • &lMaxCompressedSize);
    • if (nErr !=noErr)
    • return NIL;
    • hImageDesc =(ImageDescriptionHandle)NewHandle(4);
    • hCompressedData =NewHandle(lMaxCompressedSize);
    • if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {
    • MoveHHi(hCompressedData);
    • HLock(hCompressedData);
    • pCompressedData =StripAddress(*hCompressedData);
    • nErr =CompressImage(hpmImage,
    • &rectImage,
    • dwSpatialQuality,
    • dwCodecType,
    • hImageDesc,
    • pCompressedData);
    • if (nErr ==noErr) {
    • ClipRect(&rectImage);
    • hpicPicture =OpenPicture(&rectImage);
    • nErr =DecompressImage(pCompressedData,
    • hImageDesc,
    • hpmImage,
    • &rectImage,
    • &rectImage,
    • srcCopy,
    • NIL);
    • ClosePicture();
    • }
    • if (theErr || (GetHandleSize((Handle)hpicPicture) ==
    • sizeof(Picture))) {
    • KillPicture(hpicPicture);
    • hpicPicture =NIL;
    • }
    • }
    • if (hImageDesc !=NIL)
    • DisposeHandle((Handle)hImageDesc);
    • if (hCompressedData !=NIL)
    • DisposeHandle(hCompressedData);
    • return hpicPicture;
    • }

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • ConvertImage ConvertImage (OS X v10.9)

    Converts the format of a compressed image.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    • // DecompressImage coding example
    • // See "Discovering QuickTime," page 286
    • PicHandle GetQTCompressedPict (PixMapHandle hpmImage)
    • {
    • long lMaxCompressedSize =0;
    • Handle hCompressedData =NIL;
    • Ptr pCompressedData;
    • ImageDescriptionHandle hImageDesc =NIL;
    • OSErr nErr;
    • PicHandle hpicPicture =NIL;
    • Rect rectImage =(**hpmImage).bounds;
    • CodecType dwCodecType =kJPEGCodecType;
    • CodecComponent codec =(CodecComponent)anyCodec;
    • CodecQ dwSpatialQuality =codecNormalQuality;
    • short nDepth =0; // let ICM choose depth
    • nErr =GetMaxCompressionSize(hpmImage, &rectImage, nDepth,
    • dwSpatialQuality,
    • dwCodecType,
    • (CompressorComponent)codec,
    • &lMaxCompressedSize);
    • if (nErr !=noErr)
    • return NIL;
    • hImageDesc =(ImageDescriptionHandle)NewHandle(4);
    • hCompressedData =NewHandle(lMaxCompressedSize);
    • if ((hCompressedData !=NIL) && (hImageDesc !=NIL)) {
    • MoveHHi(hCompressedData);
    • HLock(hCompressedData);
    • pCompressedData =StripAddress(*hCompressedData);
    • nErr =CompressImage(hpmImage,
    • &rectImage,
    • dwSpatialQuality,
    • dwCodecType,
    • hImageDesc,
    • pCompressedData);
    • if (nErr ==noErr) {
    • ClipRect(&rectImage);
    • hpicPicture =OpenPicture(&rectImage);
    • nErr =DecompressImage(pCompressedData,
    • hImageDesc,
    • hpmImage,
    • &rectImage,
    • &rectImage,
    • srcCopy,
    • NIL);
    • ClosePicture();
    • }
    • if (theErr || (GetHandleSize((Handle)hpicPicture) ==
    • sizeof(Picture))) {
    • KillPicture(hpicPicture);
    • hpicPicture =NIL;
    • }
    • }
    • if (hImageDesc !=NIL)
    • DisposeHandle((Handle)hImageDesc);
    • if (hCompressedData !=NIL)
    • DisposeHandle(hCompressedData);
    • return hpicPicture;
    • }

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Compresses a single-frame image that is currently stored as a pixel map structure, with added control over the compression process.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Gets the custom color table for an image.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Updates the custom ColorTable structure for an image.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • TrimImage TrimImage (OS X v10.9)

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

    Declaration

    Objective-C

    OSErr TrimImage ( ImageDescriptionHandle desc, Ptr inData, long inBufferSize, ICMDataProcRecordPtr dataProc, Ptr outData, long outBufferSize, ICMFlushProcRecordPtr flushProc, Rect *trimRect, ICMProgressProcRecordPtr progressProc );

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Disposes of a data source.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Disposes of memory allocated by the codec.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Indicates the end of processing for an image sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Reports whether two image descriptions are the same.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Creates a new data source.

    Declaration

    Objective-C

    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.

    • // CDSequenceNewDataSource coding example
    • // See "Discovering QuickTime," page 309
    • {
    • ImageSequenceDataSource lSrc1 =0;
    • // Store a description of the first GWorld in hImageDesc1
    • nErr =MakeImageDescriptionForPixMap(GetGWorldPixMap(gWorld1),
    • &hImageDesc1);
    • // Create a source from the GWorld description.
    • nErr =CDSequenceNewDataSource(gEffectSequenceID,
    • &lSrc1,
    • 'srcA',
    • 1,
    • (Handle)hImageDesc1,
    • NIL,
    • 0);
    • // Set the data for source srcA to be the pixMap of gWorld1
    • CDSequenceSetSourceData(lSrc1,
    • GetPixBaseAddr(GetGWorldPixMap(gWorld1)),
    • (**hImageDesc1).dataSize);
    • }

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Requests codec-allocated memory.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    • // CDSequenceSetSourceData coding example
    • // See "Discovering QuickTime," page 309
    • {
    • ImageSequenceDataSource lSrc1 =0;
    • // Store a description of the first GWorld in hImageDesc1
    • nErr =MakeImageDescriptionForPixMap(GetGWorldPixMap(gWorld1),
    • &hImageDesc1);
    • // Create a source from the GWorld description.
    • nErr =CDSequenceNewDataSource(gEffectSequenceID,
    • &lSrc1,
    • 'srcA',
    • 1,
    • (Handle)hImageDesc1,
    • NIL,
    • 0);
    • // Set the data for source srcA to be the pixMap of gWorld1
    • CDSequenceSetSourceData(lSrc1,
    • GetPixBaseAddr(GetGWorldPixMap(gWorld1)),
    • (**hImageDesc1).dataSize);
    • }

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Signals the beginning of the process of compressing a sequence of frames.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Compresses one of a sequence of frames.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Obsolete. See DecompressSequenceBeginS.

    Declaration

    Objective-C

    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 );

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sends a sample image to a decompressor.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Obsolete. See DecompressSequenceFrameS.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    • // DecompressSequenceFrameWhen coding example
    • // See "Discovering QuickTime," page 310
    • // Decompress a single step of the effect sequence.
    • OSErr RunEffect(TimeValue lTime, int nNumberOfSteps)
    • {
    • OSErr nErr =noErr;
    • ICMFrameTimeRecord ftr;
    • // Set the timebase time to the step of the sequence to be rendered
    • SetTimeBaseValue(timeBase, lTime, nNumberOfSteps);
    • ftr.value.lo =lTime;
    • ftr.value.hi =0;
    • ftr.scale =nNumberOfSteps;
    • ftr.base =0;
    • ftr.duration =nNumberOfSteps;
    • ftr.rate =0;
    • ftr.recordSize =sizeof(ftr);
    • ftr.frameNumber =1;
    • ftr.flags =icmFrameTimeHasVirtualStartTimeAndDuration;
    • ftr.virtualStartTime.lo =0;
    • ftr.virtualStartTime.hi =0;
    • ftr.virtualDuration =nNumberOfSteps;
    • HLock(hEffectDesc);
    • DecompressSequenceFrameWhen(gEffectSequenceID,
    • StripAddress(*hEffectDesc),
    • GetHandleSize(hEffectDesc),
    • 0,
    • 0,
    • NIL,
    • &ftr);
    • HUnlock(hEffectDesc);
    • }

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Installs a progress procedure for a sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Retrieves information about a compressed image.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Stores information about a compressed image for StdPix.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • StdPix StdPix (OS X v10.9)

    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

    Objective-C

    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

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Ends an image field sequence operation.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Performs field operations on video data.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Undocumented

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Gets a data source for a decompression sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sets a time base for a decompression sequence.

    Declaration

    Objective-C

    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:

    • // CDSequenceSetTimeBase coding example
    • // See "Discovering QuickTime," page 310
    • timeBase =NewTimeBase();
    • SetTimeBaseRate(timeBase, 0);
    • CDSequenceSetTimeBase(gEffectSequenceID, timeBase);

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompAdd CompAdd (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

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

    Parameters

    src

    Undocumented

    dst

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompCompare CompCompare (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

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

    Parameters

    a

    Undocumented

    minusb

    Undocumented

    Return Value

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompDiv CompDiv (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

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

    Parameters

    numerator

    Undocumented

    denominator

    Undocumented

    remainder

    Undocumented

    Return Value

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompFixMul CompFixMul (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

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

    Parameters

    compSrc

    Undocumented

    fixSrc

    Undocumented

    compDst

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompMul CompMul (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

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

    Parameters

    src1

    Undocumented

    src2

    Undocumented

    dst

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompMulDiv CompMulDiv (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

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

    Parameters

    co

    Undocumented

    mul

    Undocumented

    divisor

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Undocumented

    Declaration

    Objective-C

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

    Parameters

    co

    Undocumented

    mul

    Undocumented

    divisor

    Undocumented

    remainder

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompNeg CompNeg (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

    void CompNeg ( wide *dst );

    Parameters

    dst

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompShift CompShift (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

    void CompShift ( wide *src, short shift );

    Parameters

    src

    Undocumented

    shift

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Undocumented

    Declaration

    Objective-C

    unsigned long CompSquareRoot ( const wide *src );

    Parameters

    src

    Undocumented

    Return Value

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • CompSub CompSub (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

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

    Parameters

    src

    Undocumented

    dst

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • FixExp2 FixExp2 (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

    Fixed FixExp2 ( Fixed src );

    Parameters

    src

    A fixed integer.

    Return Value

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • FixLog2 FixLog2 (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

    Fixed FixLog2 ( Fixed src );

    Parameters

    src

    A fixed integer.

    Return Value

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • FixMulDiv FixMulDiv (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

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

    Parameters

    src

    Undocumented

    mul

    Undocumented

    divisor

    Undocumented

    Return Value

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • FixPow FixPow (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

    Fixed FixPow ( Fixed base, Fixed exp );

    Parameters

    base

    Undocumented

    exp

    Undocumented

    Return Value

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • FracSinCos FracSinCos (OS X v10.9)

    Undocumented

    Declaration

    Objective-C

    Fract FracSinCos ( Fixed degree, Fract *cosOut );

    Parameters

    degree

    Undocumented

    cosOut

    Undocumented

    Return Value

    Undocumented

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Returns the current frame number of the specified sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Determines the current key frame rate of a sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Returns the display direction for a decompress sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Gets the display time for a decompression sequence.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Undocumented

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Undocumented

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Retrieves pixel format information.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Undocumented

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Gets multiprocessing properties for compression and decompression sequences.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Undocumented

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sets multiprocessing properties for compression and decompression sequences.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Undocumented

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Lets you define your own pixel format.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Gets the extension to a file name.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    long QTGetPixMapHandleRowBytes ( PixMapHandle pm );

    Parameters

    pm

    A handle to a PixMap structure.

    Return Value

    The rowBytes value.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    long QTGetPixMapPtrRowBytes ( PixMapPtr pm );

    Parameters

    pm

    A pointer to a PixMap structure.

    Return Value

    The rowBytes value.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • QTNewGWorld QTNewGWorld (OS X v10.9)

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Wraps a graphics world and pixel map structure around an existing block of memory containing an image.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sets the gamma level of a pixel map.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sets the requested gamma level of a pixel map.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sets the gamma level of a pixel map.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.

  • Sets the requested gamma level of a pixel map.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import QuickTime;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

    Not available to 64-bit applications.