- Cal3D 0.9 API Reference -

Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | Related Pages

CalAbstractMixer Class Reference

CalAbstractMixer defines the API that CalModel relies on for blending and scheduling animations. More...

#include <mixer.h>

Inheritance diagram for CalAbstractMixer:

CalMixer List of all members.

Public Member Functions

virtual bool isDefaultMixer ()
 Is the object an instance of the default mixer (i.e.
virtual bool create (CalModel *pModel)=0
 Allocates and initializes all resources needed for the instance to operate.
virtual void destroy ()=0
 Releases all resources used by the instance and frees all allocated memory.
virtual void updateAnimation (float deltaTime)=0
 Notifies the instance that updateAnimation was last called deltaTime seconds ago.
virtual void updateSkeleton ()=0
 Updates the skeleton of the corresponding CalModel (as provided to the create method) to match the current animation state (as updated by the last call to updateAnimation).

Detailed Description

CalAbstractMixer defines the API that CalModel relies on for blending and scheduling animations.

A third party mixer must implement this API in order to register itself with the CalModel::setAbstractMixer method. The default mixer (CalMixer) is an example of such implementation.

cal3d expects a mixer to handle two tasks : scheduling and blending. Scheduling refers to everything related to time such as when an animation must run or when it must stop. Blending defines how concurrent animations influence each other: for instance walking and waving.

If CalMixer proves to be insufficient for the applications needs, an alternate mixer can be implemented and used without notifying cal3d in any way. It is not mandatory to subclass CalAbstractMixer. However, when chosing this path, one must also avoid using the CalModel::update method because it would use the default mixer instantiated by the CalModel::create method with undesirable side effects. In addition libraries based on cal3d (think NebulaDevice or OpenSceneGraph adapters) are not aware of these constraints and will keep calling the CalModel::update method of CalModel regardless.

Subclassing CalAbstractMixer when implementing an alternate mixer therefore provides a better integration with cal3d and libraries that rely on CalModel. However, an additional effort is required in order to achieve compatibility with libraries or applications that rely on the CalMixer API (i.e. that use methods such as blendCycle or executeAction). The CalMixer API is not meant to be generic and there is no reason to define an abstract class that specifies it. For historical reasons and because CalMixer is the default mixer, some applications and libraries (think Soya or CrystalSpace) depend on it. If they want to switch to a scheduler with extended capabilities it might be painfull for them to learn a completely different API. A scheduler with the ambition to obsolete CalMixer should therefore provide an API compatible with it to ease the migration process.

Short summary, if you want to write a new mixer:

1) An external mixer: ignore CalAbstractMixer and implement a mixer of your own. Avoid calling CalModel::update and any library or application that will call it behind your back. Avoid libraries and applications that rely on the default mixer CalMixer, as returned by CalModel::getMixer.

2) A mixer registered in cal3d : subclass CalAbstractMixer, register it with CalModel::setAbstractMixer. Avoid libraries and applications that rely on the default mixer CalMixer, as returned by CalModel::getMixer. CalModel::getMixer will return a null pointer if CalModel::setAbstractMixer was called to set a mixer that is not an instance of CalMixer.

3) A CalMixer replacement : same as 2) and provide a subclass of your own mixer that implements the CalMixer API so that existing applications can switch to it by calling CalModel::getAbstractMixer instead of CalModel::getMixer. The existing code using the CalMixer methods will keep working and the developper will be able to switch to a new API when convenient.


Member Function Documentation

virtual bool CalAbstractMixer::create CalModel pModel  )  [pure virtual]
 

Allocates and initializes all resources needed for the instance to operate.

When subclassing, it is recommended that the constructor does as little as possible and leaves the work to the create method. The create method must be called before any other method. It MUST support multiple calls without undesirable side effects (for instance object->create(model) called twice without a call to object->destroy() in between must not leak memory).

The CalModel::setAbstractMixer method will call create. The CalModel::create method will call create if called after the instance was set using CalModel::setAbstractMixer (otherwise an instance of CalMixer is allocated and its create method is called).

Parameters:
pModel a pointer to the CalModel instance in which the animations to be mixed are found.
Returns:
  • true if successful
  • false if an error happend

Implemented in CalMixer.

virtual void CalAbstractMixer::destroy  )  [pure virtual]
 

Releases all resources used by the instance and frees all allocated memory.

It is recommended that the destructor of a CalAbstractMixer subclass does as little as possible and leaves the work to the destroy method. The destroy method MUST support multiple calls without undesirable side effects (such as deallocating a pointer twice).

The CalModel::destroy method will call destroy if the instance was allocated by CalModel::create (in which case it is a CalMixer instance) or if the instance was set via CalModel::setAbstractMixer.

Implemented in CalMixer.

virtual bool CalAbstractMixer::isDefaultMixer  )  [inline, virtual]
 

Is the object an instance of the default mixer (i.e.

an instance of CalMixer) ?

Returns:

Reimplemented in CalMixer.

virtual void CalAbstractMixer::updateAnimation float  deltaTime  )  [pure virtual]
 

Notifies the instance that updateAnimation was last called deltaTime seconds ago.

The internal scheduler of the instance should terminate animations or update the timing information of active animations accordingly. It should not blend animations together or otherwise modify the CalModel associated to these animations.

The CalModel::update method will call updateSkeleton immediately after updateAnimation if the instance was allocated by CalModel::create (in which case it is a CalMixer instance) or if the instance was set via CalModel::setAbstractMixer.

Parameters:
deltaTime The elapsed time in seconds since the last call.

Implemented in CalMixer.

virtual void CalAbstractMixer::updateSkeleton  )  [pure virtual]
 

Updates the skeleton of the corresponding CalModel (as provided to the create method) to match the current animation state (as updated by the last call to updateAnimation).

The tracks of each active animation are blended to compute the position and orientation of each bone of the skeleton. The updateAnimation method should be called just before calling updateSkeleton to define the set of active animations.

The CalModel::update method will call updateSkeleton immediately after updateAnimation if the instance was allocated by CalModel::create (in which case it is a CalMixer instance) or if the instance was set via CalModel::setAbstractMixer.

Implemented in CalMixer.


The documentation for this class was generated from the following file:
Generated at Thu Dec 2 20:30:18 2004 by The Cal3D Team with doxygen 1.3.9.1 © 1997-2001 Dimitri van Heesch