Animation player. More...

#include <user/common/kzu_user.h>
#include <core/util/collection/kzc_dynamic_array.h>
#include <system/kzs_types.h>
#include <system/debug/kzs_error.h>
#include <system/kzs_header.h>

Macros
#define	KZU_ANIMATION_PLAYER_PROFILING_SAMPLE_COMPOSE_REGULAR
	Profiling constant string for regular animation samples. More...

#define	KZU_ANIMATION_PLAYER_PROFILING_SAMPLE_COMPOSE_BLEND
	Profiling constant string for blended animation samples. More...

#define	KZU_ANIMATION_PLAYER_PROFILING_UPDATE
	Profiling constant string for updating whole animation player. More...

#define	KZU_ANIMATION_PLAYER_PROFILING_UPDATE_ENTRIES
	Profiling constant string for updating entries. More...

#define	KZU_ANIMATION_PLAYER_PROFILING_SORT_ENTRIES
	Profiling constant string for sorting entries. More...

#define	KZU_ANIMATION_PLAYER_PROFILING_GRAPH_CACHE
	Profiling constant string for building graph cache. More...

#define	KZU_ANIMATION_PLAYER_PROFILING_IS_INVALIDATED
	Profiling constant string for player invalidation. More...

Functions
kzsError	kzuAnimationPlayerCreate (const struct KzcMemoryManager memoryManager, struct KzuUIDomain uiDomain, struct KzuObjectNode attachedObjectNode, struct KzuAnimationPlayer *out_animationPlayer)
	Allocates memory for animation player and initializes it. More...

kzsError	kzuAnimationPlayerDelete (struct KzuAnimationPlayer *animationPlayer)
	Deallocates memory reserved for animation player. More...

struct KzuUIDomain *	kzuAnimationPlayerGetUIDomain (const struct KzuAnimationPlayer *player)
	Gets UI domain associated to animation player. More...

kzsError	kzuAnimationPlayerUpdate (struct KzuAnimationPlayer *player, kzFloat deltaTime)
	Updates animations in player. More...

void	kzuAnimationPlayerSetTime (struct KzuAnimationPlayer *player, kzFloat time)
	Sets the animation player to the given time. More...

void	kzuAnimationPlayerSetPaused (struct KzuAnimationPlayer *player, kzBool paused)
	Sets pause state of the animation player. More...

kzBool	kzuAnimationPlayerIsPaused (const struct KzuAnimationPlayer *player)
	Check whether or not the animation player is paused. More...

void	kzuAnimationPlayerSetPausingEnabled (struct KzuAnimationPlayer *player, kzBool pausingEnabled)
	Sets pausing enabled for player. More...

kzFloat	kzuAnimationPlayerGetTime (const struct KzuAnimationPlayer *player)
	Returns current time of the animation player. More...

void	kzuAnimationPlayerSetEnabled (struct KzuAnimationPlayer *player, kzBool enabled)
	Sets animation player enabled, so that all its animations will be effectively executed and child players will be evaluated. More...

kzBool	kzuAnimationPlayerIsEnabled (const struct KzuAnimationPlayer *player)
	Returns if animation player is enabled. More...

kzsError	kzuAnimationPlayerAddTimeLineEntry (struct KzuAnimationPlayer player, struct KzuTimeLineEntry timeLineEntry)
	Adds new time line entry to the player. More...

kzsError	kzuAnimationPlayerRemoveTimeLineEntry (struct KzuAnimationPlayer player, struct KzuTimeLineEntry timeLineEntry, kzBool removeRecursively)
	Removes time line entry from the player if entry is found. More...

kzsError	kzuAnimationPlayerSetTimeLineSequence (struct KzuAnimationPlayer player, struct KzuTimeLineSequence timeLineSequence)
	Sets a time line sequence to the player. More...

struct KzuTimeLineSequence *	kzuAnimationPlayerGetTimeLineSequence (const struct KzuAnimationPlayer *player)
	Returns time line sequence from the player. More...

kzsError	kzuAnimationPlayerAddAnimationItem (struct KzuAnimationPlayer player, struct KzuPropertyManager propertyManager, struct KzuAnimationItem animationItem, kzBool reverse, kzInt repeatCount, struct KzuTimeLineEntry *out_entry)
	Adds animation clip to player's current time. More...

kzsError	kzuAnimationPlayerFindAnimationItem (struct KzuAnimationPlayer player, const struct KzuAnimationItem animationItem, struct KzuAnimationPlayer out_animationPlayer, struct KzuTimeLineEntry out_timeLineEntry)
	Finds animation item from player, returns the first found hit. More...

kzBool	kzuAnimationPlayerGetTimeLineEntryFinished (const struct KzuAnimationPlayer player, const struct KzuTimeLineEntry timeLineEntry)
	Returns boolean indicating if given time line entry is finished on the animation players time line. More...

kzsError	kzuAnimationPlayerAddChildPlayer (struct KzuAnimationPlayer parentPlayer, struct KzuAnimationPlayer childPlayer)
	Adds child animation player for parent animation player. More...

kzsError	kzuAnimationPlayerRemoveFromParent (struct KzuAnimationPlayer *player)
	Removes child player from parent. More...

void	kzuAnimationPlayerRemoveFromChildren (struct KzuAnimationPlayer *player)
	Removes player from all its child players. More...

struct KzcDynamicArrayIterator	kzuAnimationPlayerGetChildPlayers (const struct KzuAnimationPlayer *player)
	Gets child animation players from player. More...

struct KzuAnimationPlayer *	kzuAnimationPlayerGetParentPlayer (const struct KzuAnimationPlayer *player)
	Returns the parent player. More...

struct KzuAnimationPlayer *	kzuAnimationPlayerGetRootPlayer (struct KzuAnimationPlayer *player)
	Gets root player from animation player. More...

void	kzuAnimationPlayerInvalidateEntryGraph (struct KzuAnimationPlayer *player)
	Invalidates cached entry graph of the animation player. More...

kzsError	kzuAnimationPlayerClearTimeLineEntries (struct KzuAnimationPlayer *player, kzBool clearChildren)
	Clears timeline entries from the animation player. More...

void	kzuAnimationPlayerRefreshPropertyDrivenAnimations (const struct KzuAnimationPlayer *player)
	Refresh all property driven animations recursively. More...

struct KzuObjectNode *	kzuAnimationPlayerGetAttachedObjectNode (const struct KzuAnimationPlayer *player)
	Private function for getting attached object node from animation player. More...

struct KzuMessageDispatcher *	kzuAnimationPlayerGetMessageDispatcher (const struct KzuAnimationPlayer *player)
	Gets message dispatcher from animation player. More...

struct KzcMemoryManager *	kzuAnimationPlayerGetQuickMemoryManager (struct KzuAnimationPlayer *player)
	Returns quick memory manager from animation player. More...

Detailed Description

Animation player.

KzuAnimationPlayer contains a collection of time line entries (KzuTimeLineEntry), which are used to track when to play the animations and how to blend animation values together when there are multiple simultaneous animations for the same property. The time line entries are automatically created when calling kzuAnimationPlayerAddAnimationItem() for adding a KzuAnimation, KzuAnimationClip or KzuTimeLineSequence to the animation player. Every KzuUIDomain has an animation player that is called the root player (accessible by using kzuUIDomainGetTaskScheduler() and kzuTaskSchedulerGetAnimationPlayer()). An animation player should be added as a child of the root player (by using kzuTaskSchedulerAttachAnimationPlayer()) when the animation player should start playing immediately. It is also possible to use the player manually by calling kzuAnimationPlayerUpdate() with desired delta times.

KzuAnimationPlayer stores all of its time line entries into a KzuTimeLineSequence. This collection can be accessed with kzuAnimationPlayerGetTimeLineSequence() and replaced with kzuAnimationPlayerSetTimeLineSequence().

A KzuAnimationPlayer is automatically created and added to the root player when attaching an animation to an object node with kzuObjectNodeAddAnimationItem(). This animation player can be accessed with kzuObjectNodeGetAnimationPlayer(). It is also possible to create and run an animation player manually as the following example code shows.

Animation Player Example Code

The following example code demonstrates how it is possible to use an animation player manually for maximum control. Notice that in most cases using kzuObjectNodeAddAnimationItem() is enough (see the example code in kzu_animation_clip.h and kzu_animation.h).

kzsError KzuAnimationPlayerExample()
{
    kzsError result;
    kzFloat timesAndValues[10] = { 0.0f, 0.0f,
                                   1.0f, 2.0f,
                                   2.0f, 10.0f,
                                   3.0f, 2.0f,
                                   4.0f, 0.0f };
    struct KzuAnimation* animation;
    kzUint i;
    struct KzuObjectNode* objectNode;
    struct KzuAnimationPlayer* animationPlayer;
    struct KzuTimeLineEntry* entry1, *entry2;
    result = kzuAnimationCreateFloatTarget(memoryManager, uiDomain, kzuPropertyTypeGetName(KZU_PROPERTY_TYPE_TRANSFORMATION),
                                           KZU_PROPERTY_FIELD_TRANSLATION_X, &animation);
    kzsErrorForward(result);
    for (i = 0; i < 10; i += 2)
    {
        struct KzuAnimationKeyFloat* key;
        struct KzuAnimationKey* animationKey;
        result = kzuAnimationKeyFloatCreate(memoryManager, timesAndValues[i], timesAndValues[i + 1],
                                            KZU_ANIMATION_INTERPOLATION_LINEAR, &key);
        kzsErrorForward(result);
        animationKey = kzuAnimationKeyFloatToAnimationKey(key);
        result = kzuAnimationAddKeyFrame(animation, animationKey);
        kzsErrorForward(result);
    }
    // Create a sphere to animate.
    {
        struct KzuMesh* mesh;
        struct KzuMeshNode* meshNode;
        result = kzuMeshCreateSphere(kzuUIDomainGetResourceManager(uiDomain), "Sphere", 7.0f, 32, 32, KZ_NULL, &mesh);
        kzsErrorForward(result);
        result = kzuMeshNodeCreate(memoryManager, "mesh node", uiDomain, mesh, &meshNode);
        kzsErrorForward(result);
        result = kzuResourceRelease(kzuMeshToResource(mesh));
        kzsErrorForward(result);
        objectNode = kzuMeshNodeToObjectNode(meshNode);
        result = kzuObjectNodeAddChild(kzuSceneToObjectNode(scene), objectNode);
        kzsErrorForward(result);
    }
    // Create an animation player and add the animation to it.
    result = kzuAnimationPlayerCreate(memoryManager, uiDomain, objectNode, &animationPlayer);
    kzsErrorForward(result);
    result = kzuAnimationPlayerAddAnimationItem(animationPlayer, kzuUIDomainGetPropertyManager(uiDomain),
                                                kzuAnimationToAnimationItem(animation), KZ_FALSE, 1, &entry1);
    kzsErrorForward(result);
    // Add another animation 0.5s after the first animation.
    kzuAnimationPlayerSetTime(animationPlayer, 0.5f);
    result = kzuAnimationPlayerAddAnimationItem(animationPlayer, kzuUIDomainGetPropertyManager(uiDomain),
                                                kzuAnimationToAnimationItem(animation), KZ_FALSE, 1, &entry2);
    kzsErrorForward(result);
    // When the animations are played at the same time, add their values together.
    kzuTimeLineEntrySetWeightBlendMode(entry1, KZU_TIME_LINE_ENTRY_WEIGHT_BLEND_MODE_ADDITIVE);
    kzuTimeLineEntrySetWeightBlendMode(entry2, KZU_TIME_LINE_ENTRY_WEIGHT_BLEND_MODE_ADDITIVE);
    // Start playing from 0s
    kzuAnimationPlayerSetTime(animationPlayer, 0.0f);
    // Verify that the animation changes the X translation of the sphere.
    for (i = 0; i < 6; ++i)
    {
        struct KzcMatrix4x4 transform;
        struct KzcVector3 translation;
        result = kzuAnimationPlayerUpdate(animationPlayer, i == 0 ? 0.0f : 1.0f); // the first step is 0
        kzsErrorForward(result);
        transform = kzuObjectNodeGetMatrix4x4PropertyDefault(objectNode, KZU_PROPERTY_TYPE_TRANSFORMATION);
        kzcMatrix4x4GetTranslation(&transform, &translation);
        switch (i)
        {
            case 0: // first and second animation has played for 0s
                kzsAssert(kzsFabsf(translation.data[0] - 0.0f) < 0.001f);
                break;
            case 1: // first animation has played for 1s, the second for 0.5s
                kzsAssert(kzsFabsf(translation.data[0] - 3.0f) < 0.001f);
                break;
            case 2: // first animation has played for 2s, the second for 1.5s
                kzsAssert(kzsFabsf(translation.data[0] - 16.0f) < 0.001f);
                break;
            case 3: // first animation has played for 3s, the second for 2.5s
                kzsAssert(kzsFabsf(translation.data[0] - 8.0f) < 0.001f);
                break;
            case 4: // first animation has played for 4s (end), the second for 3.5s
                kzsAssert(kzsFabsf(translation.data[0] - 1.0f) < 0.001f);
                break;
            case 5: // first animation has ended, the second for 4s (end)
                kzsAssert(kzsFabsf(translation.data[0] - 0.0f) < 0.001f);
                break;
            default:
                kzsAssert(KZ_FALSE);
        }
    }
    result = kzuAnimationPlayerDelete(animationPlayer);
    kzsErrorForward(result);
    result = kzuResourceRelease(kzuAnimationItemToResource(kzuAnimationToAnimationItem(animation)));
    kzsErrorForward(result);
    kzsSuccess();
}

See Also: kzu_time_line_entry.h, kzu_time_line_sequence.h.

Macro Definition Documentation

#define KZU_ANIMATION_PLAYER_PROFILING_SAMPLE_COMPOSE_REGULAR

Profiling constant string for regular animation samples.

#define KZU_ANIMATION_PLAYER_PROFILING_SAMPLE_COMPOSE_BLEND

Profiling constant string for blended animation samples.

#define KZU_ANIMATION_PLAYER_PROFILING_UPDATE

Profiling constant string for updating whole animation player.

#define KZU_ANIMATION_PLAYER_PROFILING_UPDATE_ENTRIES

Profiling constant string for updating entries.

#define KZU_ANIMATION_PLAYER_PROFILING_SORT_ENTRIES

Profiling constant string for sorting entries.

#define KZU_ANIMATION_PLAYER_PROFILING_GRAPH_CACHE

Profiling constant string for building graph cache.

#define KZU_ANIMATION_PLAYER_PROFILING_IS_INVALIDATED

Profiling constant string for player invalidation.

Function Documentation

kzsError kzuAnimationPlayerCreate	(	const struct KzcMemoryManager *	memoryManager,
		struct KzuUIDomain *	uiDomain,
		struct KzuObjectNode *	attachedObjectNode,
		struct KzuAnimationPlayer **	out_animationPlayer
	)

Allocates memory for animation player and initializes it.

Parameters

memoryManager	The memory manager to use.
uiDomain	The UI domain to use.
attachedObjectNode	Object node that owns the animation player. KZ_NULL if none, in this case message dispatching is not supported.
out_animationPlayer	A pointer that is set to point to the new animation player on success.

Returns: KZS_SUCCESS on success.

kzsError kzuAnimationPlayerDelete ( struct KzuAnimationPlayer * animationPlayer)

Deallocates memory reserved for animation player.

struct KzuUIDomain* kzuAnimationPlayerGetUIDomain ( const struct KzuAnimationPlayer * player)

Gets UI domain associated to animation player.

kzsError kzuAnimationPlayerUpdate	(	struct KzuAnimationPlayer *	player,
		kzFloat	deltaTime
	)

Updates animations in player.

Parameters

player	The animation player.
deltaTime	Seconds elapsed since the last update.

Returns: KZS_SUCCESS on success.

void kzuAnimationPlayerSetTime	(	struct KzuAnimationPlayer *	player,
		kzFloat	time
	)

Sets the animation player to the given time.

Parameters

player	The animation player.
time	The time in seconds.

void kzuAnimationPlayerSetPaused	(	struct KzuAnimationPlayer *	player,
		kzBool	paused
	)

Sets pause state of the animation player.

kzBool kzuAnimationPlayerIsPaused ( const struct KzuAnimationPlayer * player)

Check whether or not the animation player is paused.

Parameters

player The animation player.

Returns: KZ_TRUE if the player is currently paused. KZ_FALSE if not.

void kzuAnimationPlayerSetPausingEnabled	(	struct KzuAnimationPlayer *	player,
		kzBool	pausingEnabled
	)

Sets pausing enabled for player.

Disabling pausing can be useful for players that are not wanted to be paused when main player pauses, such as preview camera animations.

kzFloat kzuAnimationPlayerGetTime ( const struct KzuAnimationPlayer * player)

Returns current time of the animation player.

void kzuAnimationPlayerSetEnabled	(	struct KzuAnimationPlayer *	player,
		kzBool	enabled
	)

Sets animation player enabled, so that all its animations will be effectively executed and child players will be evaluated.

kzBool kzuAnimationPlayerIsEnabled ( const struct KzuAnimationPlayer * player)

Returns if animation player is enabled.

kzsError kzuAnimationPlayerAddTimeLineEntry	(	struct KzuAnimationPlayer *	player,
		struct KzuTimeLineEntry *	timeLineEntry
	)

Adds new time line entry to the player.

kzsError kzuAnimationPlayerRemoveTimeLineEntry	(	struct KzuAnimationPlayer *	player,
		struct KzuTimeLineEntry *	timeLineEntry,
		kzBool	removeRecursively
	)

Removes time line entry from the player if entry is found.

Parameters

removeRecursively Removes and inspects entry also child players.

kzsError kzuAnimationPlayerSetTimeLineSequence	(	struct KzuAnimationPlayer *	player,
		struct KzuTimeLineSequence *	timeLineSequence
	)

Sets a time line sequence to the player.

struct KzuTimeLineSequence* kzuAnimationPlayerGetTimeLineSequence ( const struct KzuAnimationPlayer * player)

Returns time line sequence from the player.

kzsError kzuAnimationPlayerAddAnimationItem	(	struct KzuAnimationPlayer *	player,
		struct KzuPropertyManager *	propertyManager,
		struct KzuAnimationItem *	animationItem,
		kzBool	reverse,
		kzInt	repeatCount,
		struct KzuTimeLineEntry **	out_entry
	)

Adds animation clip to player's current time.

kzsError kzuAnimationPlayerFindAnimationItem	(	struct KzuAnimationPlayer *	player,
		const struct KzuAnimationItem *	animationItem,
		struct KzuAnimationPlayer **	out_animationPlayer,
		struct KzuTimeLineEntry **	out_timeLineEntry
	)

Finds animation item from player, returns the first found hit.

kzBool kzuAnimationPlayerGetTimeLineEntryFinished	(	const struct KzuAnimationPlayer *	player,
		const struct KzuTimeLineEntry *	timeLineEntry
	)

Returns boolean indicating if given time line entry is finished on the animation players time line.

kzsError kzuAnimationPlayerAddChildPlayer	(	struct KzuAnimationPlayer *	parentPlayer,
		struct KzuAnimationPlayer *	childPlayer
	)

Adds child animation player for parent animation player.

kzsError kzuAnimationPlayerRemoveFromParent ( struct KzuAnimationPlayer * player)

Removes child player from parent.

void kzuAnimationPlayerRemoveFromChildren ( struct KzuAnimationPlayer * player)

Removes player from all its child players.

struct KzcDynamicArrayIterator kzuAnimationPlayerGetChildPlayers ( const struct KzuAnimationPlayer * player)

Gets child animation players from player.

struct KzuAnimationPlayer* kzuAnimationPlayerGetParentPlayer ( const struct KzuAnimationPlayer * player)

Returns the parent player.

KZ_NULL if no parent.

struct KzuAnimationPlayer* kzuAnimationPlayerGetRootPlayer ( struct KzuAnimationPlayer * player)

Gets root player from animation player.

Returns self if this is the root.

void kzuAnimationPlayerInvalidateEntryGraph ( struct KzuAnimationPlayer * player)

Invalidates cached entry graph of the animation player.

kzsError kzuAnimationPlayerClearTimeLineEntries	(	struct KzuAnimationPlayer *	player,
		kzBool	clearChildren
	)

Clears timeline entries from the animation player.

Parameters

clearChildren are the children cleared recursively.

void kzuAnimationPlayerRefreshPropertyDrivenAnimations ( const struct KzuAnimationPlayer * player)

Refresh all property driven animations recursively.

struct KzuObjectNode* kzuAnimationPlayerGetAttachedObjectNode ( const struct KzuAnimationPlayer * player)

Private function for getting attached object node from animation player.

struct KzuMessageDispatcher* kzuAnimationPlayerGetMessageDispatcher ( const struct KzuAnimationPlayer * player)

Gets message dispatcher from animation player.

struct KzcMemoryManager* kzuAnimationPlayerGetQuickMemoryManager ( struct KzuAnimationPlayer * player)

Returns quick memory manager from animation player.

Macros

Functions

Detailed Description

Animation Player Example Code

Macro Definition Documentation

Function Documentation