| - Cal3D 0.11 API Reference - |
#include <mixer.h>
Public Member Functions | |
| virtual bool | isDefaultMixer () |
| Is the object an instance of the default mixer (i.e. | |
| 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). | |
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.
|
|
Is the object an instance of the default mixer (i.e. an instance of CalMixer) ?
|
|
|
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.
|
|
|
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. |