Skip to content

Kuesa::Qt3D::AnimationPlayer

Module: Kuesa Qt 3D API

Play animations defined in glTF files. More...

#include <Kuesa/Qt3D/api/animationplayer.h>

Inherits from Kuesa::Qt3D::KuesaNode, Qt3DCore::QNode

Inherited by Kuesa::Qt3D::AnimationPulse

Public Types

Name
enum Loops { Infinite = -1}

Public Slots

Name
void setClip(const QString & clip)
void setMapper(const QString & mapper)
void setRunning(bool running)
void setLoopCount(int loops)
void setClock(Qt3DAnimation::QClock * clock)
void setNormalizedTime(float timeFraction)
void start(int delay =0)
void stop()
void reset()
void restart(int delay =0)
void run(float fromTimeFraction, float toTimeFraction)

Public Signals

Name
void statusChanged(Kuesa::Qt3D::AnimationPlayer::Status status)
void clipChanged(const QString & clip)
void mapperChanged(const QString & mapper)
void runningChanged(bool running)
void loopCountChanged(int loops)
void clockChanged(Qt3DAnimation::QClock * clock)
void normalizedTimeChanged(float index)
void durationChanged(float duration)
void currentLoopChanged(int currentLoop)

Public Functions

Name
Q_ENUM(Loops )
Q_ENUM(Status) explicit AnimationPlayer(Qt3DCore ~AnimationPlayer()
Status status() const
QString clip() const
QString mapper() const
bool isRunning() const
int loopCount() const
int currentLoop() const
Qt3DAnimation::QClock * clock() const
float normalizedTime() const
float duration() const
QVector< Qt3DCore::QNode * > targets() const
AnimationPlayer::targets returns the list of currently defined targets for animations.
void addTarget(Qt3DCore::QNode * target)
AnimationPlayer::addTarget adds a node target as a target for the animation.
void removeTarget(Qt3DCore::QNode * target)

Public Properties

Name
Status status
the current status of the player
QString clip
the name of the clip asset.
QString mapper
the name of the mapper asset.
bool running
controls if the animation is running or not
int loops
controls the number of time the animation should repeat.
int currentLoop
Qt3DAnimation::QClock * clock
instance of Qt3DAnimation::QClock used to control animation speed and direction
float normalizedTime
progress of the animation as a uniform value between 0. and 1.
float duration
duration of the animation in secconds

Additional inherited members

Public Slots inherited from Kuesa::Qt3D::KuesaNode

Name
void setSceneEntity(Kuesa::Qt3D::SceneEntity * sceneEntity)

Public Signals inherited from Kuesa::Qt3D::KuesaNode

Name
void sceneEntityChanged(Kuesa::Qt3D::SceneEntity * sceneEntity)

Public Functions inherited from Kuesa::Qt3D::KuesaNode

Name
KuesaNode(Qt3DCore::QNode * parent =nullptr)
SceneEntity * sceneEntity() const

Public Properties inherited from Kuesa::Qt3D::KuesaNode

Name
Kuesa::Qt3D::SceneEntity * sceneEntity

Protected Attributes inherited from Kuesa::Qt3D::KuesaNode

Name
SceneEntity * m_sceneEntity

Detailed Description

1
class Kuesa::Qt3D::AnimationPlayer;

Play animations defined in glTF files.

Since: Kuesa 2.0

AnimationPlayer is a utility class designed to easily control animations where the clip and mapping data is stored in a collections (typically loaded from glTF files).

Clip and mapper data are referenced by name. These will be used to look up actual assets in the appropriate collection.

AnimationPlayer internally uses an instance of Qt3DAnimation::QClipAnimator and mirrors it's api.

Additionally, AnimationPlayer can be used to map clip data to other target objects than those specified in a mapper. For example, an animation where the clip data affect transformation properties, can be applied to any Qt3DCore::QTransform instance, not just the one specified in the mapper data.

Public Types Documentation

enum Loops

Enumerator Value Description
Infinite -1

Public Slots Documentation

slot setClip

1
2
3
void setClip(
    const QString & clip
)

slot setMapper

1
2
3
void setMapper(
    const QString & mapper
)

slot setRunning

1
2
3
void setRunning(
    bool running
)

slot setLoopCount

1
2
3
void setLoopCount(
    int loops
)

slot setClock

1
2
3
void setClock(
    Qt3DAnimation::QClock * clock
)

slot setNormalizedTime

1
2
3
void setNormalizedTime(
    float timeFraction
)

slot start

1
2
3
void start(
    int delay =0
)

Starts the animation after delay in msec. delay defaults to 0.

slot stop

1
void stop()

Stops the animation

slot reset

1
void reset()

Stops the animation and resets the normalised time to 0. The next time the animation plays it will start from 0 rather than the current normalised time.

slot restart

1
2
3
void restart(
    int delay =0
)

Sets the normalised to 0 and runs the animation after delay in msec. delay defaults to 0.

slot run

1
2
3
4
void run(
    float fromTimeFraction,
    float toTimeFraction
)

Run the animation from fromTimeFraction to toTimeFraction. Both times are normalized time.

Public Signals Documentation

signal statusChanged

1
2
3
void statusChanged(
    Kuesa::Qt3D::AnimationPlayer::Status status
)

signal clipChanged

1
2
3
void clipChanged(
    const QString & clip
)

signal mapperChanged

1
2
3
void mapperChanged(
    const QString & mapper
)

signal runningChanged

1
2
3
void runningChanged(
    bool running
)

signal loopCountChanged

1
2
3
void loopCountChanged(
    int loops
)

signal clockChanged

1
2
3
void clockChanged(
    Qt3DAnimation::QClock * clock
)

signal normalizedTimeChanged

1
2
3
void normalizedTimeChanged(
    float index
)

signal durationChanged

1
2
3
void durationChanged(
    float duration
)

signal currentLoopChanged

1
2
3
void currentLoopChanged(
    int currentLoop
)

Public Functions Documentation

function Q_ENUM

1
2
3
inline Q_ENUM(
    Loops 
)

function ~AnimationPlayer

1
Q_ENUM(Status) explicit AnimationPlayer(Qt3DCore ~AnimationPlayer()

function status

1
Status status() const

function clip

1
QString clip() const

function mapper

1
QString mapper() const

function isRunning

1
bool isRunning() const

function loopCount

1
int loopCount() const

function currentLoop

1
int currentLoop() const

function clock

1
Qt3DAnimation::QClock * clock() const

function normalizedTime

1
float normalizedTime() const

function duration

1
float duration() const

function targets

1
QVector< Qt3DCore::QNode * > targets() const

AnimationPlayer::targets returns the list of currently defined targets for animations.

See: AnimationPlayer::addTarget, AnimationPlayer::removeTarget

function addTarget

1
2
3
void addTarget(
    Qt3DCore::QNode * target
)

AnimationPlayer::addTarget adds a node target as a target for the animation.

See: AnimationPlayer::removeTarget

Note:

  • When specifying targets, a valid object matching the specified AnimationPlayer::mapper property must exist (even though it won't be affected by the animation) as it will contain information required to establish valid mappings for the new targets.
  • Kuesa::Qt3D::SceneEntity::transformForEntity can be useful to map animations that control transformations from one entity to another. The returned transform can be used as a target for the animation.

If targets are added to the list, the mapping defined by the AnimationPlayer::mapper property will be ignored and the clip data will be mapped to the specified target nodes.

The target node needs to have properties which match the ones defined by the clips.

function removeTarget

1
2
3
void removeTarget(
    Qt3DCore::QNode * target
)

See: AnimationPlayer::addTarget

Removes a node target from the list of targets

Public Property Documentation

property status

1
Status status;

the current status of the player

See: GLTF2Importer::status()

property clip

1
QString clip;

the name of the clip asset.

This will be used to lookup the asset in the AnimationClipCollection instance of the SceneEntity.

property mapper

1
QString mapper;

the name of the mapper asset.

This will be used to lookup the asset in the AnimationMappingCollection instance of the SceneEntity.

If empty (default), the name of the clip will be used as it is a common convention that they should match.

property running

1
bool running;

controls if the animation is running or not

This reflects the state of the internal Qt3DAnimation::QClipAnimator instance.

property loops

1
int loops;

controls the number of time the animation should repeat.

If the value is 0 (default), the animation will run only once.

If the value is AnimationPlayer::Infinite, the animation will loop indefinitly until explicitly stopped.

Otherwise, it will repeat the specified number of times.

This reflects the state of the internal Qt3DAnimation::QClipAnimator instance.

property currentLoop

1
int currentLoop;

property clock

1
Qt3DAnimation::QClock * clock;

instance of Qt3DAnimation::QClock used to control animation speed and direction

A Qt3DAnimation::QClock can be used to control the speed (by setting the playBackRate) and direction (like reversing by setting negative playBackRate values) of the animation.

This reflects the state of the internal Qt3DAnimation::QClipAnimator instance.

property normalizedTime

1
float normalizedTime;

progress of the animation as a uniform value between 0. and 1.

This reflects the state of the internal Qt3DAnimation::QClipAnimator instance.

property duration

1
float duration;

duration of the animation in secconds


Updated on 2023-07-03 at 11:02:09 +0000