MediaSetMatrix(IM: QC)

Inside Macintosh: QuickTime Components /

Chapter 10 - Derived Media Handler Components / Derived Media Handler Components Reference

Functions / Graphics Data Management

MediaSetMatrix
The MediaSetMatrix function allows the Movie Toolbox to tell your media handler about changes to either the movie matrix or the track matrix.
pascal ComponentResult MediaSetMatrix (ComponentInstance ci,
                           const MatrixRecord *trackMovieMatrix);
ci
Identifies the Movie Toolbox's connection to your derived media handler.
trackMovieMatrix

Contains a pointer to the matrix that transforms your media's pixels into the movie's coordinate system. The Movie Toolbox obtains this matrix by concatenating the track matrix and the movie matrix. You should use this matrix whenever you are displaying graphical data from your media.

DESCRIPTION
The Movie Toolbox calls your derived media handler's MediaSetMatrix function whenever either the movie matrix or track matrix changes. The toolbox provides you with a matrix that concatenates the transformations defined by both the movie and track matrices. You can use this matrix to map your media's display representation into the movie's coordinate system. For example, by applying this matrix to the track rectangle, you can determine the display boundaries of your media (the track rectangle is defined by the width and height fields in the movie parameter structure that you obtain when the toolbox calls your MediaInitialize function).
You obtain the initial matrix from the trackMovieMatrix field of the movie parameter structure that the Movie Toolbox provides to your MediaInitialize function.
Your derived media handler should support this function if you draw during playback.
The Movie Toolbox calls this function only if you have set the handlerHasSpatial flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function (described on page 10-36).

SPECIAL CONSIDERATIONS
Before you try to use this matrix, you should make sure that your media handler can accommodate its transformations. You can use the Movie Toolbox's GetMatrixType function to learn about the matrix. If the matrix includes transformations that are beyond the capabilities of your media handler, you can direct the base media handler to do display processing on your behalf. Call the MediaSetHandlerCapabilities function and set the handlerNeedsBuffer flag to 1 in the flags parameter. This forces the base media handler to draw your media into an offscreen buffer.

RESULT CODES
Any Component Manager result code

SEE ALSO
The Movie Toolbox uses the MediaSetDimensions function to tell your media handler about changes to the rectangle that surrounds the graphical representation of your media; this function is described in the previous section. In addition, your media handler's MediaSetClip function allows you to learn about changes to your media's clipping region. This function is discussed next.