Rt2dMaestro is a high level coordinator of the playback of user-interactive animations incorporating buttons and hierarchical animations of 2d scenes.
It makes use of several lower level features within the Rt2dAnim toolkit such as Rt2dAnim and Rt2dKeyFrameList.
Many of the other components of the Rt2dAnim toolkit are intended as subcomponents of Rt2dMaestro. These include Rt2dMessage, Rt2dStringLabel, Rt2dCel and Rt2dButton. Out of these subcomponents Rt2dMessage and Rt2dStringLabel are the most useful for leveraging Rt2dMaestro with external code.
An Rt2dMaestro is usually created with an import tool of some description. It is then read in with the usual RenderWare streaming functions and the Rt2dMaestroStreamRead function.
A string label table lookup facility allows content to be accessed by name. These are carried out via the Rt2dStringLabel group of functions. After streaming in an Rt2dMaestro, strings of interest should be searched for within the maestro's string label table. Once the string label has been found, it may be referred to by index within the Rt2dMaestro it was found in.
Sequencing is implemented via a message passing model. The different messages are mapped within the Rt2dMessage structure. A custom message handler may be chained before the default message handler. This allows user code to be notified of events internal to the animation. The user may also post external events into the animation via the message passing interface.
User handles may also be registered within the string label table. In combination with the ability to hook a custom message handler, user events may be triggered by events internal to the director.
An example could be a callback to be used when a particular animation is 'stopped' by a button action. The callback could be registered within the label table against the name of that animation. A custom message handler would then watch for the rt2dMESSAGETYPESTOP message. If the message target matches the desired animation, the stored callback could then be activated.
|
|
Rt2dMaestroAnimationsCallBack Rt2dMaestroAnimationsCallBack represents the function called from Rt2dMaestroForAllAnimations for all animations in the maestro. This function should return the current maestro to indicate success. The callback may return NULL to terminate further callbacks on the maestro.
|
|
||||||||||||||||||||||||||||||||
|
Rt2dMaestroAddAnimations is used to add a new animation to the maestro. The associated props and cel list must also be given at the same time. The maestro maintains a list of animations that are to be played. The new animation is copied into maestro's animation list, rather than creating a reference. This allows the maestro to own the animation in the list and the given animation can be destroyed. The other parameters, props and cel list, are also copied. The parent index is the animations's parent's animation index in the maestro. If it is the root animation, then the parent index can be set to -1. The posInParentScene is an index to the animation's scene in the parent's scene. The animation's index is returned in the index parameter if not NULL.
|
|
||||||||||||
|
Rt2dMaestroAddDeltaTime increments the time in all the maestro's animations by the specified amount. If the time increments takes the animation to the next frame, then any messages at the start of the next frame are posted and processed.
|
|
|
Rt2dMaestroCreate is used to create and initialize a new maestro.
|
|
|
Rt2dMaestroDestroy destroys a maestro.
|
|
||||||||||||||||
|
Rt2dMaestroForAllAnimations is a utility function to apply the given callback to all the animations in the maestro. The callback function is defined as Rt2dMaestroAnimationsCallBack. The animation and its props are passed to the function. Additional private data can be passed via the data parameter. The callback function should return the Rt2dAnim anim if successful or NULL on error. Returning NULL from the callback will terminate the loop immediately.
|
|
||||||||||||||||
|
Rt2dMaestroForAllVisibleAnimations is a utility function to apply the given callback to all the visible animations in the maestro. The callback function is defined as Rt2dMaestroAnimationsCallBack. The animation and its props are passed to the function. Additional private data can be passed via the data parameter. The callback function should return the Rt2dAnim anim if successful or NULL on error. Returning NULL from the callback will terminate the loop immediately.
|
|
||||||||||||
|
Rt2dMaestroGetAnimationsByIndex is used to return an animation in the maestro referenced by the index. This index should be the index returned by Rt2dMaestroAddAnimations.
|
|
||||||||||||
|
Rt2dMaestroGetAnimPropsByIndex is used to return an animation's props in the maestro referenced by the index. This index should be the index returned by Rt2dMaestroAddAnimations.
|
|
||||||||||||
|
Rt2dMaestroGetAnimSceneByIndex is used returned the animation's scene object in the maestro by the given index. This is the index returned by Rt2dMaestroAddAnimations.
|
|
|
Rt2dMaestroGetBBox is used return the bounding box that bounds all the objects in the maestro's scene.
|
|
|
Rt2dMaestroGetScene is used to retrieve the scene attached to the maestro.
|
|
|
Rt2dMaestroLock is used to lock a maestro for modification. The maestro's animations, scene and cel lists are also locked. A maestro can only be locked once. Attempts to lock a locked maestro will do nothing.
|
|
|
Rt2dMaestroRender is used render the scene attached to the maestro.
|
|
||||||||||||
|
Rt2dMaestroSetBBox is used set the bounding box in the maestro. The bounding box should bounds all the objects in the maestro's scene.
|
|
||||||||||||
|
Rt2dMaestroSetScene sets the scene used by the maestro. The maestro only creates a reference to the scene.
|
|
|
Rt2dMaestroStreamGetSize is used to determine the size in bytes of the binary representation of a maestro. This value is used in the binary chunk header to indicate the size of the chunk. The size includes the size of the chunk header.
|
|
||||||||||||
|
Rt2dMaestroStreamRead reads a maestro from a binary stream. If the maestro argument is NULL then a new maestro is created, otherwise the specified one is over-written. Note that prior to this function call a binary maestro chunk must be found in the stream using the RwStreamFindChunk API function. The sequence to locate and read a maestro from a binary stream is as follows: RwStream *stream; Rt2dMaestro *newMaestro; stream = RwStreamOpen(rwSTREAMFILENAME, rwSTREAMREAD, "mybinary.xxx"); if( stream ) { if( RwStreamFindChunk(stream, rwID_2DMAESTRO, NULL, NULL) ) { newMaestro = Rt2dMaestroStreamRead((Rt2dMaestro *)NULL, stream); } RwStreamClose(stream, NULL); }
|
|
||||||||||||
|
Rt2dMaestroStreamWrite is used to write the specified maestro to the given binary stream. Note that the stream will have been opened prior to this function call.
|
|
|
Rt2dMaestroUnlock is used to unlock a maestro after modification. The maestro's animations, scene and cel lists are also unlocked. Only a locked maestro can be unlocked. Attempts to unlock an unlocked maestro will do nothing.
|
|
|
Rt2dMaestroUpdateAnimations is used update all the animations in the maestro. Updating the animation is normally required as a result of a time increment.
|
© 1993-2004 Criterion Software Limited. All rights reserved. Built Thu Feb 12 13:47:07 2004.
Send Feedback