You can specify a callback function to be executed each time a frame is advanced. This is useful if you need to synchronize a special effect with the playback or execute a function at a particular frame. A frame-callback function also allows an application to monitor script-channel text. The MMPLAY sample application includes a script-parsing feature that recognizes break, goto, loop, and close commands.
The frame-callback function is called with each frame advance. Frame advances occur when mmpAnimate is called after sufficient time has elapsed for the display of the current frame (if sufficient time has not elapsed, mmpAnimate returns without advancing the frame and without calling the callback function). The callback function is not called with the mmpGoToFrame, mmpSetStage, and mmpStartAnimating functions. Although these functions can draw a frame to the stage window, they don't advance the frame.
With each frame advance, the Movie Player sends two messages to the callback function:
| Message | Description |
| MMP_HOOK_FRAME | Sent after the frame counter is advanced but before the new frame is drawn. |
| The Movie Player supplies the current frame and subframe number with the message. | |
| MMP_HOOK_SCRIPT | Sent just before the next frame is advanced. Before sending this message, the Movie Player advances the frame counter, draws the frame, and waits for the frame tempo period to expire. |
| The Movie Player supplies the frame number and the contents of the script channel with the message. The return value from the callback function deter-mines whether the Movie Player processes the script-channel text; the function returns TRUE if it has processed the script-channel text, or FALSE if the Movie Player should process the text. |
Use the following functions to hook a callback function into the playback:
mmpSetFrameHook
Specifies a function the Movie Player calls after advancing each frame.
mmpGetFrameHook
Gets a pointer to the function called after each frame is advanced.
The callback function is associated with a Movie Player instance, not a movie file. You can keep the callback function hooked into the Movie Player instance regardless of whether a movie file is loaded.