This documents an old version of bs::framework. Click here to see the latest release.
AnimationClip Class Reference

Description

Contains animation curves for translation/rotation/scale of scene objects/skeleton bones, as well as curves for generic property animation.

Inherits Resource.

Methods

SPtr< AnimationCurvesgetCurves () const
 A set of all curves stored in the animation. More...
 
void setCurves (const AnimationCurves &curves)
 A set of all curves stored in the animation. More...
 
const Vector< AnimationEvent > & getEvents () const
 A set of all events to be triggered as the animation is playing. More...
 
void setEvents (const Vector< AnimationEvent > &events)
 A set of all events to be triggered as the animation is playing. More...
 
SPtr< RootMotiongetRootMotion () const
 Returns a set of curves containing motion of the root bone. More...
 
bool hasRootMotion () const
 Checks if animation clip has root motion curves separate from the normal animation curves. More...
 
void getBoneMapping (const Skeleton &skeleton, AnimationCurveMapping *mapping) const
 Maps skeleton bone names to animation curve names, and returns a set of indices that can be easily used for locating an animation curve based on the bone index. More...
 
void getCurveMapping (const String &name, AnimationCurveMapping &mapping) const
 Attempts to find translation/rotation/scale curves with the specified name and fills the mapping structure with their indices, which can then be used for quick lookup. More...
 
void getMorphMapping (const String &name, UINT32 &frameIdx, UINT32 &weightIdx) const
 Attempts to find a generic curve with the specified name and fills output with found index, which can then be used for quick lookup. More...
 
bool isAdditive () const
 Checks are the curves contained within the clip additive. More...
 
float getLength () const
 Returns the length of the animation clip, in seconds. More...
 
UINT32 getSampleRate () const
 Number of samples per second the animation clip curves were sampled at. More...
 
void setSampleRate (UINT32 sampleRate)
 Number of samples per second the animation clip curves were sampled at. More...
 
UINT64 getVersion () const
 Returns a version that can be used for detecting modifications on the clip by external systems. More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
- Methods inherited from Resource
 Resource (bool requiresGpuInitialization=true)
 
const StringgetName () const
 Returns the name of the resource. More...
 
void setName (const String &name)
 Sets the name of the resource. More...
 
SPtr< ResourceMetaDatagetMetaData () const
 Retrieves meta-data containing various information describing a resource. More...
 
virtual bool allowAsyncLoading () const
 Returns whether or not this resource is allowed to be asynchronously loaded. More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
- Methods inherited from IReflectable
bool isDerivedFrom (RTTITypeBase *base)
 Returns true if current RTTI class is derived from base (Or if it is the same type as base). More...
 
UINT32 getTypeId () const
 Returns an unique type identifier of the class. More...
 
const StringgetTypeName () const
 Returns the type name of the class. More...
 
- Methods inherited from CoreObject
virtual void destroy ()
 Frees all the data held by this object. More...
 
bool isInitialized () const
 Returns true if the object has been initialized. More...
 
bool isDestroyed () const
 Returns true if the object has been destroyed. More...
 
void blockUntilCoreInitialized () const
 Blocks the current thread until the resource is fully initialized. More...
 
UINT64 getInternalID () const
 Returns an unique identifier for this object. More...
 
SPtr< CoreObjectgetThisPtr () const
 Returns a shared_ptr version of "this" pointer. More...
 
SPtr< ct::CoreObjectgetCore () const
 Returns an object that contains a core thread specific implementation of this CoreObject. More...
 
void syncToCore ()
 Ensures all dirty syncable data is send to the core thread counterpart of this object (if any). More...
 
void _setThisPtr (SPtr< CoreObject > ptrThis)
 Sets a shared this pointer to this object. More...
 

Static methods

static HAnimationClip create (bool isAdditive=false)
 Creates an animation clip with no curves. More...
 
static HAnimationClip create (const SPtr< AnimationCurves > &curves, bool isAdditive=false, UINT32 sampleRate=1, const SPtr< RootMotion > &rootMotion=nullptr)
 Creates an animation clip with specified curves. More...
 
static RTTITypeBasegetRTTIStatic ()
 
static SPtr< AnimationClipcreateEmpty ()
 Creates an AnimationClip with no data. More...
 
Internal
static SPtr< AnimationClip_createPtr (const SPtr< AnimationCurves > &curves, bool isAdditive=false, UINT32 sampleRate=1, const SPtr< RootMotion > &rootMotion=nullptr)
 Creates a new AnimationClip without initializing it. More...
 
- Static methods inherited from Resource
static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from IReflectable
static UnorderedMap< UINT32, RTTITypeBase * > & getAllRTTITypes ()
 Returns all available RTTI types. More...
 
static SPtr< IReflectablecreateInstanceFromTypeId (UINT32 rttiTypeId)
 Creates an empty instance of a class from a type identifier. More...
 
static void _registerRTTIType (RTTITypeBase *rttiType)
 Called by each type implementing RTTITypeBase, on program load. More...
 
static RTTITypeBase_getRTTIfromTypeId (UINT32 rttiTypeId)
 Returns class' RTTI type from type id. More...
 
static bool _isTypeIdDuplicate (UINT32 typeId)
 Checks if the provided type id is unique. More...
 
static void _checkForCircularReferences ()
 Iterates over all RTTI types and reports any circular references (for example one type having a field referencing another type, and that type having a field referencing the first type). More...
 
static RTTITypeBasegetRTTIStatic ()
 Returns an interface you can use to access class' Run Time Type Information. More...
 
- Static methods inherited from CoreObject
template<class T , class MemAlloc >
static void _delete (CoreObject *obj)
 Schedules the object to be destroyed, and then deleted. More...
 

Additional Inherited Members

- Protected Types inherited from CoreObject
enum  Flags { CGO_DESTROYED = 0x01, CGO_INIT_ON_CORE_THREAD = 0x02, CGO_INITIALIZED = 0x04 }
 Values that represent current state of the core object. More...
 

Method documentation

◆ _createPtr()

static SPtr<AnimationClip> _createPtr ( const SPtr< AnimationCurves > &  curves,
bool  isAdditive = false,
UINT32  sampleRate = 1,
const SPtr< RootMotion > &  rootMotion = nullptr 
)
static

Creates a new AnimationClip without initializing it.

Use create() for normal use.

◆ buildNameMapping()

void buildNameMapping ( )
protected

Creates a name -> curve index mapping for quicker curve lookup by name.

◆ calculateLength()

void calculateLength ( )
protected

Calculate the length of the clip based on assigned curves.

◆ create() [1/2]

static HAnimationClip create ( bool  isAdditive = false)
static

Creates an animation clip with no curves.

After creation make sure to register some animation curves before using it.

◆ create() [2/2]

static HAnimationClip create ( const SPtr< AnimationCurves > &  curves,
bool  isAdditive = false,
UINT32  sampleRate = 1,
const SPtr< RootMotion > &  rootMotion = nullptr 
)
static

Creates an animation clip with specified curves.

Parameters
[in]curvesCurves to initialize the animation with.
[in]isAdditiveDetermines does the clip contain additive curve data. This will change the behaviour how is the clip blended with other animations.
[in]sampleRateIf animation uses evenly spaced keyframes, number of samples per second. Not relevant if keyframes are unevenly spaced.
[in]rootMotionOptional set of curves that can be used for animating the root bone. Not used by the animation system directly but is instead provided to the user for manual evaluation.

◆ createEmpty()

static SPtr<AnimationClip> createEmpty ( )
static

Creates an AnimationClip with no data.

You must populate its data manually followed by a call to initialize().

Note
For serialization use only.

◆ getBoneMapping()

void getBoneMapping ( const Skeleton skeleton,
AnimationCurveMapping mapping 
) const

Maps skeleton bone names to animation curve names, and returns a set of indices that can be easily used for locating an animation curve based on the bone index.

Parameters
[in]skeletonSkeleton to create the mapping for.
[out]mappingPre-allocated array that will receive output animation clip indices. The array must be large enough to store an index for every bone in the skeleton. Bones that have no related animation curves will be assigned value -1.

◆ getCurveMapping()

void getCurveMapping ( const String name,
AnimationCurveMapping mapping 
) const

Attempts to find translation/rotation/scale curves with the specified name and fills the mapping structure with their indices, which can then be used for quick lookup.

Parameters
[in]nameName of the curves to look up.
[out]mappingTriple containing the translation/rotation/scale indices of the found curves. Indices will be -1 for curves that haven't been found.

◆ getCurves()

SPtr<AnimationCurves> getCurves ( ) const

A set of all curves stored in the animation.

Returned value will not be updated if the animation clip curves are added or removed, as it is a copy of clip's internal values.

◆ getEvents()

const Vector<AnimationEvent>& getEvents ( ) const

A set of all events to be triggered as the animation is playing.

◆ getLength()

float getLength ( ) const

Returns the length of the animation clip, in seconds.

◆ getMorphMapping()

void getMorphMapping ( const String name,
UINT32 &  frameIdx,
UINT32 &  weightIdx 
) const

Attempts to find a generic curve with the specified name and fills output with found index, which can then be used for quick lookup.

Parameters
[in]nameName of the curve to look up.
[out]frameIdxIndex of the curve animating the morph shape frames, or -1 if not found.
[out]weightIdxIndex of the curve animating the channel weight, or -1 if not found.

◆ getRootMotion()

SPtr<RootMotion> getRootMotion ( ) const

Returns a set of curves containing motion of the root bone.

This allows the user to evaluate the root bone animation curves manually, instead of through the normal animation process. This property is only available if animation clip was imported with root motion import enabled.

◆ getRTTI()

RTTITypeBase* getRTTI ( ) const
overridevirtual

Returns an interface you can use to access class' Run Time Type Information.

Note

You must derive your own version of RTTITypeBase, in which you may encapsulate all reflection specific operations.

Implements IReflectable.

◆ getSampleRate()

UINT32 getSampleRate ( ) const

Number of samples per second the animation clip curves were sampled at.

This value is not used by the animation clip or curves directly since unevenly spaced keyframes are supported. But it can be of value when determining the original sample rate of an imported animation or similar.

◆ getVersion()

UINT64 getVersion ( ) const

Returns a version that can be used for detecting modifications on the clip by external systems.

Whenever the clip is modified the version is increased by one.

◆ hasRootMotion()

bool hasRootMotion ( ) const

Checks if animation clip has root motion curves separate from the normal animation curves.

◆ initialize()

void initialize ( )
overrideprotectedvirtual

Initializes all the internal resources of this object.

Must be called right after construction. Generally you should call this from a factory method to avoid the issue where user forgets to call it.

Note

If this object require initialization on core thread initialization is not done immediately, and is instead just scheduled on the core thread. Otherwise the object is initialized immediately.

Reimplemented from CoreObject.

◆ isAdditive()

bool isAdditive ( ) const

Checks are the curves contained within the clip additive.

Additive clips are intended to be added on top of other clips.

◆ setCurves()

void setCurves ( const AnimationCurves curves)

A set of all curves stored in the animation.

Returned value will not be updated if the animation clip curves are added or removed, as it is a copy of clip's internal values.

◆ setEvents()

void setEvents ( const Vector< AnimationEvent > &  events)

A set of all events to be triggered as the animation is playing.

◆ setSampleRate()

void setSampleRate ( UINT32  sampleRate)

Number of samples per second the animation clip curves were sampled at.

This value is not used by the animation clip or curves directly since unevenly spaced keyframes are supported. But it can be of value when determining the original sample rate of an imported animation or similar.

Member Data Documentation

◆ mCurves

SPtr<AnimationCurves> mCurves
protected

Contains all the animation curves in the clip.

It's important this field is immutable so it may be used on other threads. This means any modifications to the field will require a brand new data structure to be generated and all existing data copied (plus the modification).

◆ mNameMapping

UnorderedMap<String, UINT32[(int)CurveType::Count]> mNameMapping
protected

Contains a map from curve name to curve index.

Indices are stored as specified in CurveType enum.

◆ mRootMotion

SPtr<RootMotion> mRootMotion
protected

A set of curves containing motion of the root bone.

If this is non-empty it should be true that mCurves does not contain animation curves for the root bone. Root motion will not be evaluated through normal animation process but is instead provided for the user for manual evaluation.