468 lines
20 KiB
C++
468 lines
20 KiB
C++
/*************************************************************************/
|
|
/* File : CKCharacter.h */
|
|
/* Author : Romain Sididris */
|
|
/* */
|
|
/* Virtools SDK */
|
|
/* Copyright (c) Virtools 2000, All Rights Reserved. */
|
|
/*************************************************************************/
|
|
#if !defined(CKCHARACTER_H) || defined(CK_3DIMPLEMENTATION)
|
|
|
|
#define CKCHARACTER_H "$Id:$"
|
|
#ifndef CK_3DIMPLEMENTATION
|
|
|
|
#include "CK3dEntity.h"
|
|
|
|
|
|
#undef CK_PURE
|
|
|
|
#define CK_PURE = 0
|
|
|
|
|
|
/*************************************************
|
|
{filename:CKCharacter}
|
|
Name: CKCharacter
|
|
|
|
Summary: Representation of character
|
|
|
|
Remarks:
|
|
{Image:Character}
|
|
+ A CKCharacter is defined as an articulated hierarchical set of bodyparts.A character must be a hierarchy of object (CKBodyPart) with an unique root object giving position and orientation
|
|
(optionnal for orientation).
|
|
|
|
+ A character may have an object called Floor referencer which is used (if present)
|
|
by behaviors to make the characters detect floors. This object should be a child of
|
|
the root and contain the keywords ""Pas"","Foot" or "FloorRef" in its name to be automatically recognized
|
|
otherwise use SetFloorReferenceObject to precise a custom object.
|
|
|
|
+ It can have animations attached and provides default functionnalities to
|
|
handle these animations and their transitions. This behavior can be overriden by calling
|
|
SetAutomaticProcess(FALSE). The processing of animations on characters occurs each frame before the
|
|
processing of behaviors. The automatic processing of animation plays the active animation until its
|
|
a new animation is set to be played using SetNextActiveAnimation, when a new animation becomes active
|
|
any kind of transitions can be made (smooth,to the start of the next animation,break,etc...)
|
|
|
|
+ In addition to the active animation, secondary animations may be played concurrently.
|
|
If there are bodyparts that are used by both animations the secondary animations have
|
|
priority on the currently active animation.
|
|
|
|
+ The objects making a character are called Bodyparts (CKBodyPart which derives from CK3dObject). While names
|
|
may be pure conveniency with other objects, Bodyparts name are used by loaders to detect to which particuliar object
|
|
an animation should be attributed. If there is a bodypart that should not be modify by the character animation (for
|
|
procedural animation of the head for example), it can be disabled by using CK3dEntity::IgnoreAnimations()
|
|
|
|
+ As a child class of CKBeObject and CK3dEntity, CKCharacter inherits all their methods for
|
|
placement and behaviors gestion.
|
|
|
|
+ The class id of CKCharacter is CKCID_CHARACTER.
|
|
|
|
|
|
See also: Using Characters,Using Animations,CKAnimation,CKKeyedAnimation,CKKinematicChain
|
|
*************************************************/
|
|
class CKCharacter : public CK3dEntity {
|
|
public:
|
|
#endif
|
|
//-----------------------------------------------------
|
|
// BodyParts
|
|
|
|
/************************************************
|
|
Summary: Adds a bodypart to this character.
|
|
Arguments:
|
|
part : A pointer to the CKBodyPart to be added.
|
|
Return Value: CK_OK if successful or CKERR_ALREADYPRESENT if part is already a member of this character.
|
|
|
|
See also: RemoveBodyPart,GetRootBodyPart,GetBodyPartCount,GetBodyPart
|
|
************************************************/
|
|
virtual CKERROR AddBodyPart(CKBodyPart *part) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Removes a bodypart from this character.
|
|
Arguments:
|
|
part : A pointer to the CKBodyPart to be removed
|
|
Return Value: CK_OK if successful,CKERR_INVALIDPARAMETER otherwise.
|
|
|
|
See also: AddBodyPart,GetRootBodyPart,GetBodyPartCount,GetBodyPart
|
|
************************************************/
|
|
virtual CKERROR RemoveBodyPart(CKBodyPart *part) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the root body part.
|
|
Return value :A CKBodyPart pointer.
|
|
Remarks:
|
|
+ A character must always have only one root object which will
|
|
be used for the movement of the character.
|
|
|
|
See also: AddBodyPart,RemoveBodyPart,GetBodyPartCount,GetBodyPart
|
|
************************************************/
|
|
virtual CKBodyPart *GetRootBodyPart() CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Forces the character to use a specific bodypart as its RootBodyPart
|
|
Arguments:
|
|
part:A pointer to a CKBodyPart that should be set as the root body part.
|
|
Return Value: CK_OK if successful, error code otherwise.
|
|
Remarks:
|
|
+ When adding animations and bodyparts to a character the root bodypart is
|
|
automatically detected
|
|
+ A character must always have only one root object which will
|
|
be used for the movement of the character.
|
|
|
|
See also: GetRootBodyPart,AddBodyPart,RemoveBodyPart,GetBodyPartCount,GetBodyPart
|
|
************************************************/
|
|
virtual CKERROR SetRootBodyPart(CKBodyPart *part) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets a bodypart at a given index.
|
|
Arguments:
|
|
index : Index of the bodypart to be obtained.
|
|
Return Value: A pointer to the indexth bodypart of the character.
|
|
|
|
See also: GetRootBodyPart,AddBodyPart,RemoveBodyPart,GetBodyPartCount
|
|
************************************************/
|
|
virtual CKBodyPart* GetBodyPart(int index) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the number of bodyparts of this character.
|
|
Return Value: The number of bodyparts.
|
|
|
|
See also: GetRootBodyPart,AddBodyPart,RemoveBodyPart,GetBodyPart
|
|
************************************************/
|
|
virtual int GetBodyPartCount() CK_PURE;
|
|
|
|
//-----------------------------------------------------
|
|
// Animations
|
|
|
|
/*****************************************************
|
|
Summary: Adds an animation to the character
|
|
Arguments:
|
|
anim: A CKAnimation pointer to be added for the character.
|
|
Return Value: CK_OK if successful, CKERR_INVALIDPARAMETER otherwise.
|
|
|
|
See also: RemoveAnimation,GetAnimation,GetAnimationCount
|
|
*******************************************************/
|
|
virtual CKERROR AddAnimation(CKAnimation *anim) CK_PURE;
|
|
|
|
|
|
/*******************************************************
|
|
Summary: Removes an animation from the character
|
|
Arguments:
|
|
anim: A CKAnimation pointer to be removed from the character.
|
|
Return Value: CK_OK if successful, CKERR_INVALIDPARAMETER otherwise
|
|
|
|
See also: AddAnimation,GetAnimation,GetAnimationCount
|
|
*******************************************************/
|
|
virtual CKERROR RemoveAnimation(CKAnimation *anim) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets a specific animation given its index.
|
|
Arguments:
|
|
index : Index of the animation to be returned.
|
|
Return Value: A CKAnimation pointer.
|
|
|
|
See also: AddAnimation,GetAnimation,GetAnimationCount
|
|
************************************************/
|
|
virtual CKAnimation* GetAnimation(int index) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the number of animations in this character.
|
|
Return Value: The number of animations.
|
|
|
|
See also: RemoveAnimation,GetAnimation,GetAnimationCount
|
|
************************************************/
|
|
virtual int GetAnimationCount() CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the animation used to make transitions.
|
|
Return Value: A pointer to the animation used for transitions.
|
|
Remarks:
|
|
+ A transition animation is always created along with a character.
|
|
+ Its parameters will always be updated each time a new transition is needed and
|
|
can be retrieved with GetWarperParameters method.
|
|
|
|
See also: AddAnimation,RemoveAnimation,GetAnimation,GetAnimationCount,GetWarperParameters
|
|
************************************************/
|
|
virtual CKAnimation* GetWarper() CK_PURE;
|
|
|
|
//-----------------------------------------------------
|
|
// Playing Animations
|
|
|
|
/************************************************
|
|
Summary: Gets the animation being played.
|
|
Return Value: A pointer to the CKAnimation being played.
|
|
|
|
See also: SetActiveAnimation,SetNextActiveAnimation
|
|
************************************************/
|
|
virtual CKAnimation *GetActiveAnimation() CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the animation that will be played next.
|
|
Return Value: A pointer to the next active CKAnimation.
|
|
|
|
See also: GetActiveAnimation,SetActiveAnimation,SetNextActiveAnimation
|
|
************************************************/
|
|
virtual CKAnimation *GetNextActiveAnimation() CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Forces the current active animation
|
|
|
|
Return Value:
|
|
CK_OK
|
|
Arguments:
|
|
anim : A pointer to a CKAnimation to be set as current active animation.
|
|
Remarks:
|
|
+ This method changes the current active animation without
|
|
any transition.
|
|
See also: GetActiveAnimation,GetNextActiveAnimation,SetNextActiveAnimation
|
|
************************************************/
|
|
virtual CKERROR SetActiveAnimation(CKAnimation *anim) CK_PURE;
|
|
|
|
/*************************************************
|
|
Summary: Sets the next animation to be played by the character
|
|
|
|
Arguments:
|
|
anim: A pointer to the next CKAnimation to be played.
|
|
transitionmode : A CKDWORD containing a combination of CK_ANIMATION_TRANSITION_MODE
|
|
warplength : length in frame of the warping animation if there is one.
|
|
|
|
Return Value:
|
|
CK_OK if successful, CKERR_INVALIDPARAMETER otherwise
|
|
Remarks:
|
|
Depending on transitionmode value, this function may :
|
|
|
|
+ Create a transition animation between current position and next animation which will be played before playing anim.
|
|
+ Set anim as Active Animation immediatly (break).
|
|
+ Continue playing current animation in loop.
|
|
|
|
if transitionmode is CK_TRANSITION_FROMANIMATION then the transition mode will be taken from the
|
|
animation parameters (set with CKAnimation::SetTransitionMode
|
|
The UnlimittedController building block in the Character catagory is good sample to see the different usage of transition mode.
|
|
Examples:
|
|
// If the current active animation is anim then the function returns immediatly otherwise
|
|
// if the current active animation can be stopped then a transition animation will be created
|
|
// which will be 5 frames long then anim will be played from the frame to which the positions of
|
|
// the character and its bodyparts is the closest match to the current ones.
|
|
SetNextActiveAnimation(anim,CK_TRANSITION_LOOPIFEQUAL|CK_TRANSITION_USEVELOCITY|CK_TRANSITION_WARPBEST,5.0f);
|
|
|
|
// If the current active animation is anim then the function returns immediatly otherwise
|
|
// if the current active animation can be stopped then a transition animation will be created
|
|
// which will be 5 frames long then anim will be played from the start.
|
|
SetNextActiveAnimation(anim,CK_TRANSITION_LOOPIFEQUAL|CK_TRANSITION_USEVELOCITY|CK_TRANSITION_WARPSTART,5.0f);
|
|
|
|
See also: SetNextActiveAnimation2,GetActiveAnimation,SetActiveAnimation,CK_ANIMATION_TRANSITION_MODE
|
|
*************************************************/
|
|
virtual CKERROR SetNextActiveAnimation(CKAnimation *anim,CKDWORD transitionmode,float warplength=0.0f) CK_PURE;
|
|
|
|
//-----------------------------------------------------
|
|
// animation processing
|
|
|
|
|
|
/************************************************
|
|
Summary: Updates the character according to current active animation and secondary animations.
|
|
Arguments:
|
|
deltat : a float value giving the elapsed time since last process loop in milliseconds.
|
|
Remarks:
|
|
+ This method is automatically called by the framework on each active character before
|
|
the process loop.
|
|
|
|
See also: SetAutomaticProcess, SetActiveAnimation, SetNextActiveAnimation
|
|
************************************************/
|
|
virtual void ProcessAnimation(float deltat=1.0f) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Sets whether character animations are processed by the engine.
|
|
Arguments:
|
|
process: FALSE to prevent animations from being processed by the engine each frame.
|
|
Remarks:
|
|
|
|
See also: IsAutomaticProcess, ProcessAnimation
|
|
************************************************/
|
|
virtual void SetAutomaticProcess(CKBOOL process=TRUE) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Checks whether animations are processed by the engine.
|
|
Return Value: TRUE if animations are processed by the engine.
|
|
|
|
See also: SetAutomaticProcess, ProcessAnimation
|
|
************************************************/
|
|
virtual CKBOOL IsAutomaticProcess() CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the velocity vector of the character.
|
|
Arguments:
|
|
deltat: Time delay in milliseconds.
|
|
velocity: A pointer to a VxVector that will be filled with the velocity vector of the character.
|
|
Remarks:
|
|
+ The velocity will be filled with the estimated movement made by the character
|
|
in deltat milliseconds.
|
|
|
|
See Also:CKTimeManager
|
|
************************************************/
|
|
virtual void GetEstimatedVelocity(float deltat,VxVector* velocity) CK_PURE;
|
|
|
|
//-----------------------------------------------------
|
|
// Secondary Animations
|
|
|
|
/************************************************
|
|
Summary: Plays a secondary animation.
|
|
Arguments:
|
|
anim: A pointer to the CKAnimation to start playing.
|
|
StartingFrame: Frame to starts playing anim from.
|
|
PlayFlags: Play options (CK_SECONDARYANIMATION_FLAGS)
|
|
warplength: If play options contain CKSECONDARYANIMATION_DOWARP, length in frames of the transition animation.
|
|
LoopCount: If play options specifies CKSECONDARYANIMATION_LOOPNTIMES, number of loops.
|
|
Return Value: CK_OK if successful or an error code.
|
|
Remarks:
|
|
+ The secondary animations have priority over primary animations, they force the movement of
|
|
bodyparts that they referenced. Most of the time these animations will be specific to parts of
|
|
the characters (arms for example) and should not referenced the root bodypart as its the object
|
|
that gives the character movement.
|
|
|
|
See also: StopSecondaryAnimation
|
|
************************************************/
|
|
virtual CKERROR PlaySecondaryAnimation(CKAnimation *anim,float StartingFrame=0.0f,CK_SECONDARYANIMATION_FLAGS PlayFlags=CKSECONDARYANIMATION_ONESHOT,float warplength=5.0f,int LoopCount=0) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Stops playing a secondary animation.
|
|
Arguments:
|
|
anim : A pointer to the CKAnimation to stop.
|
|
warp: A boolean indication whether a transition should be made to stop current animation.
|
|
warplength: If warp is TRUE : duration in frames of the transition, irrelevant otherwise.
|
|
Return Value: CK_OK if successful,CKERR_INVALIDPARAMETER if the animation doesn't belong to the character.
|
|
|
|
See also: PlaySecondaryAnimation
|
|
************************************************/
|
|
virtual CKERROR StopSecondaryAnimation(CKAnimation *anim,CKBOOL warp=FALSE,float warplength=5.0f) CK_PURE;
|
|
virtual CKERROR StopSecondaryAnimation(CKAnimation *anim,float warplength=5.0f) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the number of secondary animations currently playing on this character.
|
|
Return Value: Number of secondary animations.
|
|
|
|
See also: PlaySecondaryAnimation,GetSecondaryAnimationCount, StopSecondaryAnimation
|
|
************************************************/
|
|
virtual int GetSecondaryAnimationsCount() CK_PURE;
|
|
|
|
|
|
/************************************************
|
|
Summary: Gets a secondary animation according to its index.
|
|
Arguments:
|
|
index : Index of the animation to be obtained.
|
|
Return Value: A pointer to a CKAnimation.
|
|
|
|
See also: PlaySecondaryAnimation, GetSecondaryAnimationCount, StopSecondaryAnimation
|
|
************************************************/
|
|
virtual CKAnimation* GetSecondaryAnimation(int index) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Removes all secondary animations.
|
|
Remarks:
|
|
+ Stops and removes all secondary animations of a character.
|
|
|
|
See also: PlaySecondaryAnimation, StopSecondaryAnimation
|
|
************************************************/
|
|
virtual void FlushSecondaryAnimations() CK_PURE;
|
|
|
|
|
|
/************************************************
|
|
Summary: Aligns character position and orientation with its root
|
|
Remarks:
|
|
+ This method is automatically called when automatic process
|
|
of the animations is on to align the referential of the character
|
|
with its root bodypart
|
|
|
|
See also: GetRootBodyPart, ProcessAnimation, SetAutomaticProcess
|
|
************************************************/
|
|
virtual void AlignCharacterWithRootPosition() CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the entity used to represent floor reference.
|
|
Return Value: A pointer to a CK3dEntity used as floor reference.
|
|
Remarks:
|
|
+ The floor reference object is used to identify the position of the character
|
|
relatively to a floor.
|
|
|
|
See also: GetRootBodyPart, SetFloorReferenceObject.
|
|
************************************************/
|
|
virtual CK3dEntity* GetFloorReferenceObject() CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Sets the entity used to represent floor reference.
|
|
Arguments:
|
|
FloorRef : A pointer to a CK3dEntity used as floor reference.
|
|
Remarks:
|
|
+ The floor reference object is used to identify the position of the character
|
|
relatively to a floor.
|
|
|
|
See also: GetRootBodyPart, GetFloorReferenceObject
|
|
************************************************/
|
|
virtual void SetFloorReferenceObject(CK3dEntity* FloorRef) CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Sets the level of detail for animation processing.
|
|
Arguments:
|
|
LOD : A float value between 0..1 giving the animations level of detail.
|
|
Remarks:
|
|
+ A character that is far from the viewpoint does not need all bodyparts
|
|
animations to be processed.
|
|
+ The animations of the bodyparts are sorted according to their importance in (contribution to)
|
|
the global animation of the character. You can use this level of detail to remove
|
|
the processing of the less important bodyparts animations.
|
|
+ At the minimum level of detail (0) only the root and floor reference object animations
|
|
are processed (character movement) , at the full level of detail (1.0f)
|
|
all the bodyparts animations are processed.
|
|
|
|
See also: GetRootBodyPart, GetFloorReferenceObject
|
|
************************************************/
|
|
virtual void SetAnimationLevelOfDetail(float LOD) CK_PURE;
|
|
|
|
virtual float GetAnimationLevelOfDetail() CK_PURE;
|
|
|
|
/************************************************
|
|
Summary: Gets the parameters that were used to create the warping animation.
|
|
Arguments:
|
|
TransitionMode : A pointer to a DWORD that will be filled with the transition mode (CK_ANIMATION_TRANSITION_MODE)
|
|
used to create the warping animation.
|
|
AnimSrc : Source animation
|
|
AnimDest : Destination animation
|
|
FrameSrc: Frame index in the source animation that was used as starting point for the warper.
|
|
FrameDest: Frame index in the destination animation that was used as ending point for the warper.
|
|
Remarks:
|
|
o This method retrieves the parameters that were used to create the last generated
|
|
transition animation (warper).
|
|
|
|
See also: GetWarper
|
|
************************************************/
|
|
virtual void GetWarperParameters(CKDWORD* TransitionMode,CKAnimation** AnimSrc,float* FrameSrc,CKAnimation** AnimDest,float* FrameDest) CK_PURE;
|
|
|
|
/*************************************************
|
|
Summary: Sets the next animation to be played by the character
|
|
|
|
Remarks:
|
|
This function is a extended version of the SetNextActiveAnimation
|
|
where you can give the position in which to start the destination animation.
|
|
See also: SetNextActiveAnimation,CK_ANIMATION_TRANSITION_MODE
|
|
*************************************************/
|
|
virtual CKERROR SetNextActiveAnimation2(CKAnimation *anim,CKDWORD transitionmode,float warplength=0.0f,float frameTo = 0) CK_PURE;
|
|
|
|
/*************************************************
|
|
Summary: Dynamic cast operator.
|
|
Arguments:
|
|
iO: A pointer to a CKObject to cast.
|
|
Return Value:
|
|
iO casted to the appropriate class or NULL if iO is not from the required class .
|
|
Example:
|
|
CKObject* Object;
|
|
CKAnimation* anim = CKAnimation::Cast(Object);
|
|
Remarks:
|
|
|
|
*************************************************/
|
|
static CKCharacter* Cast(CKObject* iO)
|
|
{
|
|
return CKIsChildClassOf(iO,CKCID_CHARACTER)?(CKCharacter*)iO:NULL;
|
|
}
|
|
|
|
#ifndef CK_3DIMPLEMENTATION
|
|
};
|
|
|
|
#endif
|
|
#endif
|