Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

Rt2dMaestro
[Rt2dAnim (inc. Maestro)]


Data Structures
struct   Rt2dMaestro

Typedefs
typedef Rt2dMaestro *(*  Rt2dMaestroAnimationsCallBack )(Rt2dMaestro *maestro, Rt2dAnim *anim, Rt2dAnimProps *props, void *pData)

Functions
Rt2dMaestro *  Rt2dMaestroCreate (void)
RwBool  Rt2dMaestroDestroy (Rt2dMaestro *maestro)
RwUInt32  Rt2dMaestroStreamGetSize (Rt2dMaestro *maestro)
Rt2dMaestro *  Rt2dMaestroStreamWrite (Rt2dMaestro *maestro, RwStream *stream)
Rt2dMaestro *  Rt2dMaestroStreamRead (Rt2dMaestro *maestro, RwStream *stream)
Rt2dMaestro *  Rt2dMaestroForAllAnimations (Rt2dMaestro *maestro, Rt2dMaestroAnimationsCallBack callback, void *data)
Rt2dMaestro *  Rt2dMaestroForAllVisibleAnimations (Rt2dMaestro *maestro, Rt2dMaestroAnimationsCallBack callback, void *data)
Rt2dMaestro *  Rt2dMaestroAddAnimations (Rt2dMaestro *maestro, RwInt32 parent, RwInt32 posInParentScene, Rt2dAnim *anim, Rt2dAnimProps *animProps, Rt2dCelList *celList, RwInt32 *index)
Rt2dAnim *  Rt2dMaestroGetAnimationsByIndex (Rt2dMaestro *maestro, RwInt32 index)
Rt2dMaestro *  Rt2dMaestroUpdateAnimations (Rt2dMaestro *maestro)
Rt2dAnimProps *  Rt2dMaestroGetAnimPropsByIndex (Rt2dMaestro *maestro, RwInt32 index)
Rt2dMaestro *  Rt2dMaestroLock (Rt2dMaestro *maestro)
Rt2dMaestro *  Rt2dMaestroUnlock (Rt2dMaestro *maestro)
Rt2dObject *  Rt2dMaestroGetScene (Rt2dMaestro *maestro)
Rt2dMaestro *  Rt2dMaestroSetScene (Rt2dMaestro *maestro, Rt2dObject *scene)
Rt2dMaestro *  Rt2dMaestroAddDeltaTime (Rt2dMaestro *maestro, RwReal deltaTime)
Rt2dObject *  Rt2dMaestroGetAnimSceneByIndex (Rt2dMaestro *maestro, RwInt32 index)
Rt2dMaestro *  Rt2dMaestroRender (Rt2dMaestro *maestro)
Rt2dBBox *  Rt2dMaestroGetBBox (Rt2dMaestro *maestro)
Rt2dMaestro *  Rt2dMaestroSetBBox (Rt2dMaestro *maestro, Rt2dBBox *bbox)

Detailed Description

Maestro functions

Rt2dMaestro Overview

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.

See also:
Rt2dMaestroCreate , Rt2dMessage , Rt2dStringLabel

Typedef Documentation

typedef Rt2dMaestro*(* Rt2dMaestroAnimationsCallBack)(Rt2dMaestro *maestro, Rt2dAnim *anim, Rt2dAnimProps *props, void * pData)
 

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.

Parameters:
maestro  Pointer to parent maestro.
anim  Pointer to the animation.
props  Pointer to the anim's props.
pData  Pointer to private data.
Returns:
Pointer to the maestro.

Function Documentation

Rt2dMaestro* Rt2dMaestroAddAnimations (  Rt2dMaestro *    maestro,
RwInt32    parent,
RwInt32    posInParentScene,
Rt2dAnim *    anim,
Rt2dAnimProps *    props,
Rt2dCelList *    celList,
RwInt32 *    index
) 
 

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.

Parameters:
maestro  Pointer to parent maestro.
parent  Index to parent animation in the maestro.
posInParentScene  Index to parent object in the maestro's scene.
anim  Pointer to the animation to be added.
props  Pointer to the associate props.
celList  Pointer to the associate cel list.
index  Pointer to a RwInt32 to return the anim's index in the maestro.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroGetAnimationsByIndex , Rt2dMaestroGetAnimPropsByIndex , Rt2dMaestroGetCelListByIndex
Rt2dMaestro* Rt2dMaestroAddDeltaTime (  Rt2dMaestro *    maestro,
RwReal    deltaTime
) 
 

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.

Parameters:
maestro  Pointer to the parent maestro.
deltaTime  The time increment amount.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroUpdateAnimations , Rt2dMaestroProcessMessages
Rt2dMaestro* Rt2dMaestroCreate (  void    ) 
 

Rt2dMaestroCreate is used to create and initialize a new maestro.

Returns:
Pointer to a maestro.
See also:
Rt2dMaestroDestroy
RwBool Rt2dMaestroDestroy (  Rt2dMaestro *    maestro ) 
 

Rt2dMaestroDestroy destroys a maestro.

Parameters:
maestro  Pointer to a maestro to destroy. Any data owned by the maestro is also destroyed.
Returns:
Returns TRUE if successful, FALSE otherwise.
See also:
Rt2dMaestroCreate
Rt2dMaestro* Rt2dMaestroForAllAnimations (  Rt2dMaestro *    maestro,
Rt2dMaestroAnimationsCallBack    callback,
void *    data
) 
 

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.

Parameters:
maestro  Pointer to parent maestro.
callback  Pointer to the callback function.
data  Pointer to private data for the callback function.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise
See also:
Rt2dMaestroAddAnimations , Rt2dMaestroGetAnimationsByIndex , Rt2dMaestroUpdateAnimations
Rt2dMaestro* Rt2dMaestroForAllVisibleAnimations (  Rt2dMaestro *    maestro,
Rt2dMaestroAnimationsCallBack    callBack,
void *    data
) 
 

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.

Parameters:
maestro  Pointer to parent maestro.
callBack  Pointer to the callback function.
data  Pointer to private data for the callback function.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise
See also:
Rt2dMaestroAddAnimations , Rt2dMaestroGetAnimationsByIndex , Rt2dMaestroUpdateAnimations
Rt2dAnim* Rt2dMaestroGetAnimationsByIndex (  Rt2dMaestro *    maestro,
RwInt32    index
) 
 

Rt2dMaestroGetAnimationsByIndex is used to return an animation in the maestro referenced by the index. This index should be the index returned by Rt2dMaestroAddAnimations.

Parameters:
maestro  Pointer to the parent maestro.
index  Animation's index in the maestro.
Returns:
Returns a pointer to an animation if successful, NULL otherwise.
See also:
Rt2dMaestroAddAnimations , Rt2dMaestroGetAnimPropsByIndex , Rt2dMaestroGetCelListByIndex
Rt2dAnimProps* Rt2dMaestroGetAnimPropsByIndex (  Rt2dMaestro *    maestro,
RwInt32    index
) 
 

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.

Parameters:
maestro  Pointer to parent maestro.
index  Index to animation prop in the maestro.
Returns:
Returns a pointer to the anim props if successful, NULL otherwise.
See also:
Rt2dMaestroAddAnimations , Rt2dMaestroGetAnimationsByIndex , Rt2dMaestroGetCelListByIndex
Rt2dObject* Rt2dMaestroGetAnimSceneByIndex (  Rt2dMaestro *    maestro,
RwInt32    index
) 
 

Rt2dMaestroGetAnimSceneByIndex is used returned the animation's scene object in the maestro by the given index.

This is the index returned by Rt2dMaestroAddAnimations.

Parameters:
maestro  Pointer to parent maestro.
index  Animation's index in the maestro.
Returns:
Pointer to the scene object if successful, NULL otherwise.
See also:
Rt2dMaestroAddAnimations , Rt2dMaestroGetAnimationsByIndex , Rt2dMaestroGetAnimPropsByIndex , Rt2dMaestroGetCelListByIndex
Rt2dBBox* Rt2dMaestroGetBBox (  Rt2dMaestro *    maestro ) 
 

Rt2dMaestroGetBBox is used return the bounding box that bounds all the objects in the maestro's scene.

Parameters:
maestro  Pointer to the maestro.
Returns:
Returns a pointer to the maestro's bounding box.
See also:
Rt2dMaestroCreate , Rt2dMaestroSetBBox
Rt2dObject* Rt2dMaestroGetScene (  Rt2dMaestro *    maestro ) 
 

Rt2dMaestroGetScene is used to retrieve the scene attached to the maestro.

Parameters:
maestro  Pointer to the parent maestro.
Returns:
Returns a pointer to a scene if successful, NULL otherwise.
See also:
Rt2dMaestroSetScene , Rt2dSceneCreate
Rt2dMaestro* Rt2dMaestroLock (  Rt2dMaestro *    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.

Parameters:
maestro  Pointer to the maestro to lock.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroUnlock , Rt2dMaestroCreate
Rt2dMaestro* Rt2dMaestroRender (  Rt2dMaestro *    maestro ) 
 

Rt2dMaestroRender is used render the scene attached to the maestro.

Parameters:
maestro  Pointer to the maestro to render.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroCreate
Rt2dMaestro* Rt2dMaestroSetBBox (  Rt2dMaestro *    maestro,
Rt2dBBox *    bbox
) 
 

Rt2dMaestroSetBBox is used set the bounding box in the maestro. The bounding box should bounds all the objects in the maestro's scene.

Parameters:
maestro  Pointer to the maestro.
bbox  Pointer to the bounding box.
Returns:
Returns a pointer to the maestro's bounding box.
See also:
Rt2dMaestroCreate , Rt2dMaestroSetBBox
Rt2dMaestro* Rt2dMaestroSetScene (  Rt2dMaestro *    maestro,
Rt2dObject *    scene
) 
 

Rt2dMaestroSetScene sets the scene used by the maestro. The maestro only creates a reference to the scene.

Parameters:
maestro  Pointer to the parent maestro.
scene  Pointer to the scene.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroSetScene , Rt2dSceneCreate
RwUInt32 Rt2dMaestroStreamGetSize (  Rt2dMaestro *    maestro ) 
 

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.

Parameters:
maestro  Pointer to a maestro
Returns:
Returns a RwUInt32 value equal to the chunk size (in bytes) of the maestro.
See also:
Rt2dMaestroStreamRead , Rt2dMaestroStreamWrite
Rt2dMaestro* Rt2dMaestroStreamRead (  Rt2dMaestro *    maestro,
RwStream *    stream
) 
 

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(stream);
       }
  
       RwStreamClose(stream, NULL);
   }
Parameters:
maestro  Pointer to a maestro which will receive the data from the stream. If one is not provided by the application (NULL is passed), then one will be created.
stream  Pointer to the stream the maestro will be read from
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroStreamWrite , Rt2dMaestroStreamGetSize , RwStreamOpen , RwStreamClose , RwStreamFindChunk
Rt2dMaestro* Rt2dMaestroStreamWrite (  Rt2dMaestro *    maestro,
RwStream *    stream
) 
 

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.

Parameters:
maestro  Pointer to the maestro to stream.
stream  Pointer to the stream to write to.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroStreamRead , Rt2dMaestroStreamGetSize , RwStreamOpen , RwStreamClose
Rt2dMaestro* Rt2dMaestroUnlock (  Rt2dMaestro *    maestro ) 
 

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.

Parameters:
maestro  Pointer to the maestro to unlock.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroLock , Rt2dMaestroCreate
Rt2dMaestro* Rt2dMaestroUpdateAnimations (  Rt2dMaestro *    maestro ) 
 

Rt2dMaestroUpdateAnimations is used update all the animations in the maestro. Updating the animation is normally required as a result of a time increment.

Parameters:
maestro  Pointer to parent maestro.
Returns:
Returns a pointer to the maestro if successful, NULL otherwise.
See also:
Rt2dMaestroAddDeltaTime , Rt2dAnimTimeUpdate
Criterion Software © 1993-2003 Criterion Software Limited. All rights reserved. Built Tue Apr 22 12:46:50 2003. Send Feedback
Converted from CHM to HTML with chm2web Pro 2.85 (unicode)