Classes¶

Animation

Brief descriptions¶

Classes
`nau::animation::AnimationManager`
`nau::animation::AnimationSceneProcessor`
`nau::animation::AutoAnimationEditor`
`nau::animation::IGraphicPropsAnimatable`
`nau::animation::IAnimationPlayer`	Provides an interface for controlling a single animation playback.
`nau::animation::Animation`	Provides basic functionality for controlling animation and keframe events.
`nau::animation::ColorAnimation`
`nau::animation::OpacityAnimation`
`nau::animation::AnimationImpl`
Structures
`nau::animation::Frame`	Encapsulates per-frame data.
`nau::animation::IAnimationEditor`	A utlity class that allows to accumulate changes to the managed animation object and then apply(commit) them all at once.
`nau::animation::AnimationState`	Describes animation playback state relevant for the current frame.

Detailed information¶

animation::AnimationManager¶

engine/core/modules/animation/include/nau/animation/animation_manager.h

class AnimationManager : public nau::scene::SceneComponent, public nau::scene::IComponentUpdate, public nau::scene::IComponentEvents ¶

Public Functions

AnimationManager()¶

~AnimationManager()¶

virtual void onComponentActivated() override¶: This function is called on component activation.

virtual void updateComponent(float dt) override¶

Updates the component.

Warning

The update loop waits for all IComponentUpdate::updateComponent and IComponentAsyncUpdate::updateComponentAsync calls completion, until it can proceed to the next frame. Consequently, all lasting operations are to be avoided within these calls. Instead, address to IComponentAsyncListener::listenComponent.

Parameters:: [int] – dt Elapsed time.

void registerAnimationComponent(AnimationComponent *animComponent)¶

void unregisterAnimationComponent(AnimationComponent *animComponent)¶

Public Static Functions

static AnimationManager *get(scene::SceneComponent *anySceneComponent)¶

Private Members

eastl::vector<scene::ObjectWeakRef<AnimationComponent>> m_animComponentsCache¶

eastl::unique_ptr<AnimationManagerImguiController> m_uiController¶

animation::AnimationSceneProcessor¶

engine/core/modules/animation/include/nau/animation/animation_scene_processor.h

class AnimationSceneProcessor : public IRefCounted, public nau::scene::ISceneProcessor, public nau::scene::IComponentsAsyncActivator, public IServiceInitialization¶

Private Functions

NAU_CLASS_(AnimationSceneProcessor, IRefCounted, scene::ISceneProcessor, scene::IComponentsAsyncActivator, IServiceInitialization) public ~AnimationSceneProcessor ()

async::Task preInitService() override¶

async::Task initService() override¶

async::Task activateComponentsAsync(Uid worldUid, eastl::span<const scene::Component*> components, async::Task<> barrier) override¶

virtual void syncSceneState() override¶

animation::AutoAnimationEditor¶

engine/core/modules/animation/include/nau/animation/edit/animation_editor.h

template<typename TKeyFrameValueType> class AutoAnimationEditor : public nau::animation::IAnimationEditor<TKeyFrameValueType>¶

A wrapper class around another IAnimationEditor instance that accumulates changes and commits them when destroyed.

Note

All modifying functions of this class actually accumulate changes and do not apply them to the underlying animation object. In order to apply the changes call commit method.

Note

All get... methods retrieve values taking all local uncommited changes in the editor. If the actual state of the managed object is required, use the corresponding API.

Template Parameters:: TKeyFrameValueType – Type of the animated parameter.

Public Functions

inline AutoAnimationEditor(IAnimationEditor<TKeyFrameValueType> *holder)¶

Initialization constructor.

Parameters:: holder – [in] IAnimationEditor object that actually manages the animation. See m_editor.

inline virtual ~AutoAnimationEditor()¶: Destructor.

inline operator bool()¶

Checks whether the editor inner state is valid.

Returns:: true is the editor inner state is valid, false otherwise.

inline virtual void commit() override¶: Passes all local changes to the wrapped editor object.

Note

This method does not actually change the underlying animation. The wrapped editor is responsible for applying the changes.

inline virtual int getKeyFrameCount() const override¶

Retrieves the number of animation keyframes.

Returns:: Number of key frames.

inline virtual KeyFrameImpl<TKeyFrameValueType> getKeyFrameAtIndex(int index) const override¶

Retrieves a keyframe by its index.

Parameters:: index – [in] Index of the keyframe among other keyframes.
Returns:: Retrieved keyframe.

inline virtual void clearKeyFrames() override¶: Removes all keyframes.

inline virtual void addKeyFrame(int frame, const TKeyFrameValueType &value) override¶

Adds a keyframe to the animation.

Parameters:

frame – [in] Index of the key frame.
value – [in] Value that the animated property should have when the playback reaches this keyframe.

inline virtual bool deleteKeyFrame(int frame) override¶

Removes the keyframe from the animation.

Parameters:: frame – [in] Index of the keyframe (among ordinary frames).

inline virtual int getFrameDataCount() const override¶

Retrieves the number of registered frame data entries.

Currently frame data encapsulates a collection of events that are triggered upon playback reaching the frame. See Frame.

Returns:: Number of frame data entries.

inline virtual Frame getFrameDataAtIndex(int index) const override¶

Retrieves a frame data entry that is assoicated with the frame.

Parameters:: index – [in] Index of the frame.
Returns:: Data entry associated with the frame.

inline virtual void clearFrameData() override¶: Removes all frame data entries.

inline virtual void addFrameData(const Frame &frameData) override¶

Adds the frame entry to the animation.

Parameters:: frameData – [in] Frame data entry to add.

inline virtual void addFrameEvent(int frame, const FrameEvent &value) override¶

Attaches the frame event to the frame.

Note

Maximal number of events attached to a frame is limited by MAX_EVENTS_PER_FRAME.

Parameters:

frame – [in] Index of the frame to attach the event to.
value – [in] Event to attach.

inline virtual bool deleteFrameEvent(int frame, const char *eventId) override¶

Detaches the frame event from the frame.

Parameters:

frame – [in] Index of the frame to detach the event from.
eventid – [in] Identifier of the event to detach.

inline virtual int getEventCount(int frame) const override¶

Retrieves the number of events attached to the frame.

Parameters:: frame – [in] Index of the frame.
Returns:: Number of events attached to the frame.

inline virtual eastl::string_view getEventId(int frame, int index) const override¶

Retrieves the identifier of the frame event.

Parameters:

frame – [in] Index of the frame the event is attached to.
index – [in] Index of the event in the event collection associated with the frame.

Returns:

Event string identifier.

inline virtual void serialize(DataBlock &blk) const override¶

Serializes keyframes (event) data into the blk object.

Parameters:: Blk – [out] object to write serialized data into.

inline virtual void deserialize(DataBlock &blk) override¶

Deserializes keyframes (event) data from the blk object.

Parameters:: Blk – [in] object to extract data from.

Private Functions

inline void touchKeyFrames()¶: Synchronizes wrapper key frames collection with the underlying animation state.

inline void touchFrameData()¶: Synchronizes wrapper frame data collection with the underlying animation state.

Private Members

IAnimationEditor<TKeyFrameValueType> *m_editor¶: A pointer to the IAnimationEditor object that actually manages the animation. It receives all accumulated changes when commit is called.

eastl::map<int, TKeyFrameValueType> m_keyFrames¶: A collection of keyframes.

eastl::map<int, Frame> m_frameData¶: A collection of frame data entries.

bool m_isKeyFramesDirty = false¶: Indicates whether the keyframes collection contains uncommitted changes.

bool m_isFrameDataDirty = false¶: Indicates whether the frame data entries collection contains uncommitted changes.

animation::IGraphicPropsAnimatable¶

engine/core/modules/animation/include/nau/animation/interfaces/animatable_graphic_props.h

class IGraphicPropsAnimatable : public nau::animation::IAnimatable ¶

Subclassed by nau::ui::UiNodeAnimator

Private Functions

virtual IAnimatable void animateColor (const math::Color3 &color)=0

virtual void animateOpacity(float opacity) = 0¶

animation::IAnimationPlayer¶

engine/core/modules/animation/include/nau/animation/interfaces/animation_player.h

class IAnimationPlayer : public virtual IRefCounted¶

Provides an interface for controlling a single animation playback.

Subclassed by nau::animation::KeyFrameAnimationPlayer

Private Types

using Ptr = nau::Ptr<IAnimationPlayer>¶

Private Functions

virtual int getDurationInFrames() const = 0¶

Retrieves the animation duration in frames.

Returns:: Number of frames composing the animation

virtual void play() = 0¶: Continues the animation playback.

virtual void pause(bool pause) = 0¶

Pauses or continues animation playback.

Parameters:: pause – [in] Indicates whether the playback should be paused or not.

virtual void stop() = 0¶: Stops the playback and resets the animation to the first frame.

virtual bool isPaused() const = 0¶

Checks whether the playback is currently paused.

Returns:: true if the animation is on pause, false otherwsise.

virtual bool isReversed() const = 0¶

Retrieves the playback direction.

Returns:: true if the playback direction is reversed, false if it is forward.

virtual void reverse(bool reverse) = 0¶

Switches the direction of the playback.

Parameters:: Indicates – [in] whether the playback direction should be forward or reversed.

virtual void setPlaybackSpeed(float speed) = 0¶

Changes the animation playback speed value.

Parameters:: Value – [in] to assign.

virtual float getPlaybackSpeed() const = 0¶

Retrieves the animation playback speed.

Returns:: Animation playback speed.

virtual int getPlayingFrame() const = 0¶

Retrieves the index of the animation frame that the player is currently playing.

Returns:: Animation played frame.

virtual void jumpToFirstFrame() = 0¶: Changes the currently played frame to the first one.

virtual void jumpToLastFrame() = 0¶

Changes the currently played frame to the last one.

This effectively finishes the playback.

virtual void jumpToFrame(int frameNum) = 0¶

Changes the currently played frame to the specified index.

Parameters:: Index – [in] of the frame the playback will continue with.

animation::Animation¶

engine/core/modules/animation/include/nau/animation/playback/animation.h

class Animation : public virtual IRefCounted¶

Provides basic functionality for controlling animation and keframe events.

Animation is a gradual change of a single parameter of an object (target, which usually is a game object component). This change is dictated by interpolation operation over a set of predefined parameter values at specified moments of time, i.e. keyframes.

This class encapsulates animation parameters that have been loaded from an animation asset and, perhaps, changed in animation editor. These parameters are keyframes and their associated data (values and events). They are shared among all animated objects which this animation is attached to. Individual settings like playback direction or animation weight are tuned via AnimationInstance which is individual for each animated object.

Subclassed by nau::animation::AnimationImpl< bool >, nau::animation::AnimationImpl< math::Color3 >, nau::animation::AnimationImpl< float >, nau::animation::AnimationImpl< int >, nau::animation::AnimationImpl< math::quat >, nau::animation::AnimationImpl< math::vec3 >, nau::animation::AnimationImpl< ISkeletonAnimatableKeyFrameType >, nau::animation::AnimationImpl< math::vec2 >, nau::animation::AnimationImpl< math::Transform >, nau::animation::AnimationImpl< TValue >

Public Functions

virtual IAnimationPlayer::Ptr createPlayer(AnimationInstance &instance) const¶

Creates an animation player object.

Parameters:: instance – [in] Animation instance to be played by the player.
Returns:: A pointer to the created player.

virtual void apply(int frame, AnimationState &animationState) const = 0¶

Animates the target according to the current animation state.

Parameters:

frame – [in] Current frame index.
animationState – [in] Animation state.

virtual int getLastFrame() const = 0¶

Retrieves the index of the last frame in the animation.

Returns:: Index of the last frame.

virtual float getDurationInFrames() const = 0¶

Retrieves the animation duration in frames.

Returns:: Animation duration in frames.

const eastl::span<const FrameEvent> getEvents(int frame) const¶

Retrieves a collection of events associated with the frame.

Parameters:: frame – [in] Index of the frame.
Returns:: A collection of the associated events.

Protected Functions

virtual void addKeyFrame(const KeyFrame *keyFrame) = 0¶

Adds the keyframe to the animation.

Parameters:: keyFrame – [in] A pointer to the keyframe to add.

void sortFrames()¶

Chronologically sorts keyframes event data.

See m_perFrameData.

Frame &getOrCreateFrameData(int frame)¶

Provides access to a data object for the specified frame. In case the object is default-initialized and added to the animation.

Parameters:: frame – [in] Index of the frame.
Returns:: Retrieved frame data.

Frame *getFrameData(int frame)¶

Provides access to a data object for the specified frame.

Parameters:: frame – [in] Index of the frame.
Returns:: A pointer to the retrieved frame data or nullptr if frame was invalid.

const Frame *getFrameData(int frame) const¶

Retrieves a corresponding data object for the specified frame.

Parameters:: frame – [in] Index of the frame.
Returns:: A pointer to the retrieved frame data or nullptr if frame was invalid.

void toBlk(DataBlock &blk) const¶

Serializes keyframes (event) data into the blk object.

Parameters:: Blk – [out] object to write serialized data into.

void fromBlk(DataBlock &blk)¶

Deserializes keyframes (event) data from the blk object.

Parameters:: Blk – [in] object to extract data from.

Protected Attributes

eastl::vector<Frame> m_perFrameData¶: Stores event data associated with each keyframe.

animation::ColorAnimation¶

engine/core/modules/animation/include/nau/animation/playback/animation_graphic_props.h

class ColorAnimation : public nau::animation::AnimationImpl<math::Color3>¶

Public Functions

virtual void apply(int frame, AnimationState &animationState) const override¶

Animates the target according to the current animation state.

Parameters:

frame – [in] Current frame index.
animationState – [in] Animation state.

Private Functions

math::Color3 interpolate(int targetFrame, const TKeyFrame &from, const TKeyFrame &to, AnimationState &animationState) const¶

animation::OpacityAnimation¶

engine/core/modules/animation/include/nau/animation/playback/animation_graphic_props.h

class OpacityAnimation : public nau::animation::FloatAnimation ¶

Public Functions

virtual void apply(int frame, AnimationState &animationState) const override¶

Animates the target according to the current animation state.

Parameters:

frame – [in] Current frame index.
animationState – [in] Animation state.

animation::AnimationImpl¶

engine/core/modules/animation/include/nau/animation/playback/animation_impl.h

template<class TValue> class AnimationImpl : public nau::animation::Animation, private nau::animation::IAnimationEditor<TValue>¶

Public Types

using TKeyFrame = KeyFrameImpl<TValue>¶

using TImpl = AnimationImpl<TValue>¶

Public Functions

inline virtual int getLastFrame() const override¶

Retrieves the index of the last frame in the animation.

Returns:: Index of the last frame.

inline virtual float getDurationInFrames() const override¶

Retrieves the animation duration in frames.

Returns:: Animation duration in frames.

inline AutoAnimationEditor<TValue> createEditor()¶

inline IAnimationEditor<TValue> &asInplaceEditor()¶

inline const TKeyFrame *getKeyFrameAt(int index) const¶

inline int getNumKeyFrames() const¶

Protected Functions

inline virtual void addKeyFrame(const KeyFrame *keyFrame) override¶

Adds the keyframe to the animation.

Parameters:: keyFrame – [in] A pointer to the keyframe to add.

Private Functions

inline virtual int getKeyFrameCount() const override¶

Retrieves the number of animation keyframes.

Returns:: Number of key frames.

inline virtual TKeyFrame getKeyFrameAtIndex(int index) const override¶

Retrieves a keyframe by its index.

Parameters:: index – [in] Index of the keyframe among other keyframes.
Returns:: Retrieved keyframe.

inline virtual void clearKeyFrames() override¶: Removes all keyframes.

inline virtual void addKeyFrame(int frame, const TValue &value) override¶

Adds the keyframe to the animation.

Parameters:: frame – [in] Index of the keyframe (among ordinary frames).

inline virtual bool deleteKeyFrame(int frame) override¶

Removes the keyframe from the animation.

Parameters:: frame – [in] Index of the keyframe (among ordinary frames).

inline virtual int getFrameDataCount() const override¶

Retrieves the number of registered frame data entries.

Currently frame data encapsulates a collection of events that are triggered upon playback reaching the frame. See Frame.

Returns:: Number of frame data entries.

inline virtual Frame getFrameDataAtIndex(int index) const override¶

Retrieves a frame data entry that is assoicated with the frame.

Parameters:: index – [in] Index of the frame.
Returns:: Data entry associated with the frame.

inline virtual void clearFrameData() override¶: Removes all frame data entries.

inline virtual void addFrameData(const Frame &frameData) override¶

Adds the frame entry to the animation.

Parameters:: frameData – [in] Frame data entry to add.

inline virtual void addFrameEvent(int frame, const FrameEvent &value) override¶

Attaches the frame event to the frame.

Note

Maximal number of events attached to a frame is limited by MAX_EVENTS_PER_FRAME.

Parameters:

frame – [in] Index of the frame to attach the event to.
value – [in] Event to attach.

inline virtual bool deleteFrameEvent(int frame, const char *eventId) override¶

Detaches the frame event from the frame.

Parameters:

frame – [in] Index of the frame to detach the event from.
eventid – [in] Identifier of the event to detach.

inline virtual int getEventCount(int frame) const override¶

Retrieves the number of events attached to the frame.

Parameters:: frame – [in] Index of the frame.
Returns:: Number of events attached to the frame.

inline virtual eastl::string_view getEventId(int frame, int index) const override¶

Retrieves the identifier of the frame event.

Parameters:

frame – [in] Index of the frame the event is attached to.
index – [in] Index of the event in the event collection associated with the frame.

Returns:

Event string identifier.

inline virtual void commit() override¶: Deliver changes to the managed animation.

inline virtual void serialize(DataBlock &blk) const override¶

Serializes keyframes (event) data into the blk object.

Parameters:: Blk – [out] object to write serialized data into.

inline virtual void deserialize(DataBlock &blk) override¶

Deserializes keyframes (event) data from the blk object.

Parameters:: Blk – [in] object to extract data from.

inline void sortFrames()¶

Private Members

std::vector<TKeyFrame> m_keyFrames¶

animation::Frame¶

engine/core/modules/animation/include/nau/animation/data/frame.h

struct Frame¶

Encapsulates per-frame data.

Public Members

int frame¶: Frame index.

eastl::vector<FrameEvent> events¶: A collection of events to be triggered at this frame.

animation::IAnimationEditor¶

engine/core/modules/animation/include/nau/animation/edit/animation_editor.h

template<typename TKeyFrameValueType> struct IAnimationEditor¶

A utlity class that allows to accumulate changes to the managed animation object and then apply(commit) them all at once.

Note

All modifying functions of this class actually accumulate changes and do not apply them to the underlying animation object. In order to apply the changes call commit method.

Note

All get... methods retrieve values taking all local uncommited changes in the editor. If the actual state of the managed object is required, use the corresponding API.

Template Parameters:: TKeyFrameValueType – Type of the animated parameter.

Subclassed by nau::animation::AutoAnimationEditor< TKeyFrameValueType >

Public Functions

virtual ~IAnimationEditor() = default¶: Destructor.

virtual int getKeyFrameCount() const = 0¶

Retrieves the number of animation keyframes.

Returns:: Number of key frames.

virtual KeyFrameImpl<TKeyFrameValueType> getKeyFrameAtIndex(int index) const = 0¶

Retrieves a keyframe by its index.

Parameters:: index – [in] Index of the keyframe among other keyframes.
Returns:: Retrieved keyframe.

virtual void clearKeyFrames() = 0¶: Removes all keyframes.

virtual void addKeyFrame(int frame, const TKeyFrameValueType &value) = 0¶

Adds the keyframe to the animation.

Parameters:: frame – [in] Index of the keyframe (among ordinary frames).

virtual bool deleteKeyFrame(int frame) = 0¶

Removes the keyframe from the animation.

Parameters:: frame – [in] Index of the keyframe (among ordinary frames).

virtual int getFrameDataCount() const = 0¶

Retrieves the number of registered frame data entries.

Currently frame data encapsulates a collection of events that are triggered upon playback reaching the frame. See Frame.

Returns:: Number of frame data entries.

virtual Frame getFrameDataAtIndex(int index) const = 0¶

Retrieves a frame data entry that is assoicated with the frame.

Parameters:: index – [in] Index of the frame.
Returns:: Data entry associated with the frame.

virtual void clearFrameData() = 0¶: Removes all frame data entries.

virtual void addFrameData(const Frame &frameData) = 0¶

Adds the frame entry to the animation.

Parameters:: frameData – [in] Frame data entry to add.

virtual void addFrameEvent(int frame, const FrameEvent &value) = 0¶

Attaches the frame event to the frame.

Note

Maximal number of events attached to a frame is limited by MAX_EVENTS_PER_FRAME.

Parameters:

frame – [in] Index of the frame to attach the event to.
value – [in] Event to attach.

virtual bool deleteFrameEvent(int frame, const char *eventId) = 0¶

Detaches the frame event from the frame.

Parameters:

frame – [in] Index of the frame to detach the event from.
eventid – [in] Identifier of the event to detach.

virtual int getEventCount(int frame) const = 0¶

Retrieves the number of events attached to the frame.

Parameters:: frame – [in] Index of the frame.
Returns:: Number of events attached to the frame.

virtual eastl::string_view getEventId(int frame, int index) const = 0¶

Retrieves the identifier of the frame event.

Parameters:

frame – [in] Index of the frame the event is attached to.
index – [in] Index of the event in the event collection associated with the frame.

Returns:

Event string identifier.

virtual void commit() = 0¶: Deliver changes to the managed animation.

virtual void serialize(DataBlock &blk) const = 0¶

Serializes keyframes (event) data into the blk object.

Parameters:: Blk – [out] object to write serialized data into.

virtual void deserialize(DataBlock &blk) = 0¶

Deserializes keyframes (event) data from the blk object.

Parameters:: Blk – [in] object to extract data from.

animation::AnimationState¶

engine/core/modules/animation/include/nau/animation/playback/animation.h

struct AnimationState¶

Describes animation playback state relevant for the current frame.

Public Functions

float getFullWeight() const¶

Retrieves the animation total weight, taking blending-in/blending-out into account.

Returns:: Animation total weight.

bool addEvent(const eastl::string &id, bool pin)¶

Adds the event to a frame event slot. It is marked as active.

Active events of the animation state are processed by AnimationInstance.

Note

A limitation on maximal number of active events per frame is determined by MAX_EVENTS_PER_FRAME. In case there are no inactive slots, the function will fail.

Parameters:

id – [in] Event identifier, i.e. a string message that will be broadcasted.
pin – [in] Indicates whether the event should be pinned. See FrameEventControl::IsPinned

Returns:

true on success, false otherwise.

bool removeEvent(const eastl::string &id)¶

Removes the event from a frame event slot.

Use this method to manually deactivate pinned events. Unpinned events perish each update and removed automatically.

Parameters:: id – [in] Identfier of the event to remove.
Returns:: true on success, false otherwise (i.e. the identifier was not found).

void clearEvents()¶: Removes events from all frame event slots.

Public Members

float time¶: Current playback time.

float playbackSpeed = 1.f¶: Current animation playback speed.

int forcedFrame = -1¶: Index of the frame this animation will be reset to at the next update. If set to negative value, no reset will occur.

int baseKeyFrameIndex = 0¶

Index of the last processed keyframe.

When we want to pinpoint the two closest keyframes a frame is located between, the API will begin search from this frame as it is expected that keyframes are animated through one by one.

IAnimatable::Ptr target¶: A pointer to the object to animate.

IAnimationPlayer::Ptr player¶: A pointer to the player controlling the animation playback.

nau::string animInstanceName¶

Identifier of the associated animation instance.

Todo:: Change identifier string representation to UID.

float weight = 1.f¶

Animation weight that is regarded as its relative contribution to the resulted value of the animated parameter when accumulating (blending) influences from multiple animations.

The less the weight of the animation is, the less impact on the resulted value of the animated parameter the animation will make.

float blendInOutWeight = 1.f¶

Animation weight that is changed during the blending-in or blending-out process.

The less the weight of the animation is, the less impact on the resulted value of the animated parameter the animation will make.

float blendInTime = 0.f¶

Duration of blending-in process for the animation.

Blending-in is a process when an animation weight gradually increases from 0 to its maximum. See blendInOutWeight.

float blendOutTime = 0.f¶

Duration of blending-out process for the animation.

Blending-out is a process when an animation weight gradually decreases from its maximum to zero. See blendInOutWeight.

AnimationInterpolationMethod interpolationMethod = AnimationInterpolationMethod::Linear ¶

AnimationBlendMethod blendMethod = AnimationBlendMethod::Mix ¶

bool isReversed = false¶

bool ignoreController = false¶

bool isPaused = false¶

bool isStopped = false¶

std::array<FrameEventInfo, MAX_EVENTS_PER_FRAME> events¶: A collection of frame events that has been triggered at this frame.