#include <charactercontext.h>

Detailed Description

Assumes control over the character animation functionalities of a model if it contains a character definition and an animation set.

Internally, the character context is responsible for dispatching animation jobs, blending animation, and keeping track of the current time playing for each registered entity.

The character context also handles animation events, which are triggers to play when animation hits a certain time stamp.

How the context works is like this: Every character has a buffer of samples which is updated every frame. Every character has a set of tracks to play animations on, which can be blended between if requested. Tracks are blended in sequential order. Every character has a list per track of pending animations, which are ticked off whenever the current animation has finished. Animations can be played without enqueueing, which replaces the currently playing animation on that track.

Copyright: (C) 2018-2020 Individual contributors, see AUTHORS file

Inherits Graphics::GraphicsContext.

Classes
struct	AnimationRuntime

struct	AnimationTracks

Public Types
enum	LoadState { NoneLoaded = 0 , SkeletonLoaded = N_BIT(1) , AnimationLoaded = N_BIT(2) }

Public Member Functions
	CharacterContext ()
	constructor

virtual	~CharacterContext ()
	destructor

Public Member Functions inherited from Graphics::GraphicsContext
	GraphicsContext ()
	constructor

virtual	~GraphicsContext ()
	destructor

Static Public Member Functions
static void	Create ()
	setup character context

static void	Setup (const Graphics::GraphicsEntityId id, const Resources::ResourceName &skeletonResource, const IndexT skeletonIndex, const Resources::ResourceName &animationResource, const IndexT animationIndex, const Util::StringAtom &tag, bool supportBlending=true)
	setup character context, assumes there is already a model attached, by loading a skeleton and animation resource

static IndexT	GetClipIndex (const Graphics::GraphicsEntityId id, const Util::StringAtom &name)
	perform a clip name lookup

static bool	PlayClip (const Graphics::GraphicsEntityId id, const CoreAnimation::AnimSampleMask *mask, const IndexT clipIndex, const IndexT track, const EnqueueMode mode, const float weight=1.0f, const SizeT loopCount=1, const float startTime=0.0f, const float fadeIn=0.0f, const float fadeOut=0.0f, const float timeOffset=0.0f, const float timeFactor=1.0f)
	play animation on a specific track

static void	StopTrack (const Graphics::GraphicsEntityId id, const IndexT track)
	stops all animations queued on track (and resets their time)

static void	StopAllTracks (const Graphics::GraphicsEntityId id)
	stops all animations on all tracks

static void	PauseTrack (const Graphics::GraphicsEntityId id, const IndexT track)
	pause animation on track, which doesn't reset time

static void	Seek (const Graphics::GraphicsEntityId id, const float time)
	seek animation to a certain time, clamps to length

static const float	GetTime (const Graphics::GraphicsEntityId id)
	get current time of animation

static bool	IsPlaying (const Graphics::GraphicsEntityId id)
	check if any animation is playing

static void	SetTrackWeight (const Graphics::GraphicsEntityId id, const IndexT track, const float weight)
	set weight for track

static void	SetTrackTimeFactor (const Graphics::GraphicsEntityId id, const IndexT track, const float factor)
	set time factor for track

static void	QueryClips (const Graphics::GraphicsEntityId id, Util::FixedArray< CoreAnimation::AnimClip > &outClips)
	retrieve animation clip names and lengths

static void	UpdateAnimations (const Graphics::FrameContext &ctx)
	runs before frame is updated

static void	WaitForCharacterJobs (const Graphics::FrameContext &ctx)
	run after frame

static CoreAnimation::AnimSampleMask *	CreateAnimSampleMask (const Util::StringAtom &name, const Util::FixedArray< Math::scalar > &weights)
	register anim sample mask, and return pointer

static CoreAnimation::AnimSampleMask *	GetAnimSampleMask (const Util::StringAtom &name)
	get anim sample mask by name

static void	OnRenderDebug (uint32_t flags)
	debug rendering

Static Public Attributes
static Threading::AtomicCounter	ConstantUpdateCounter = 0

Private Types
enum	{ Skeleton , Animation , Loaded , TrackController , AnimTime , JointPalette , JointPaletteScaled , UserControlledJoint , JobJoints , SampleBuffer , SupportMix , EntityId , CharacterSkinNodeIndexOffset }

typedef Ids::IdAllocator< SkeletonId, CoreAnimation::AnimationId, LoadState, AnimationTracks, Timing::Time, Util::FixedArray< Math::mat4 >, Util::FixedArray< Math::mat4 >, Util::FixedArray< Math::mat4 >, Util::FixedArray< SkeletonJobJoint >, CoreAnimation::AnimSampleBuffer, bool, Graphics::GraphicsEntityId, IndexT >	CharacterContextAllocator

Private Member Functions
	__DeclareContext ()

Static Private Member Functions
static Graphics::ContextEntityId	Alloc ()
	allocate a new slice for this context

static void	Dealloc (Graphics::ContextEntityId id)
	deallocate a slice

Static Private Attributes
static const SizeT	MaxNumTracks = 16

static CharacterContextAllocator	characterContextAllocator

static Util::HashTable< Util::StringAtom, CoreAnimation::AnimSampleMask >	masks

static Threading::Event	totalCompletionEvent

Friends
struct	CharacterJobContext

const bool	IsExpired (const CharacterContext::AnimationRuntime &runtime, const Timing::Time time)

const bool	IsInfinite (const CharacterContext::AnimationRuntime &runtime)

Timing::Tick	GetAbsoluteStopTime (const CharacterContext::AnimationRuntime &runtime)

void	EvalCharacter (SizeT totalJobs, SizeT groupSize, IndexT groupIndex, SizeT invocationOffset, void *ctx)

Additional Inherited Members
Static Protected Member Functions inherited from Graphics::GraphicsContext
static void	InternalRegisterEntity (const Graphics::GraphicsEntityId id, Graphics::GraphicsContextState &&state)

static void	InternalDeregisterEntity (const Graphics::GraphicsEntityId id, Graphics::GraphicsContextState &&state)

template<class ID_ALLOCATOR >
static void	InternalDefragment (ID_ALLOCATOR &allocator, Graphics::GraphicsContextState &&state)

Member Typedef Documentation

◆ CharacterContextAllocator

Ids::IdAllocator< SkeletonId, CoreAnimation::AnimationId, LoadState, AnimationTracks, Timing::Time, Util::FixedArray<Math::mat4>, Util::FixedArray<Math::mat4>, Util::FixedArray<Math::mat4>, Util::FixedArray<SkeletonJobJoint>, CoreAnimation::AnimSampleBuffer, bool, Graphics::GraphicsEntityId, IndexT > Characters::CharacterContext::CharacterContextAllocator

private

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

private

Enumerator
Skeleton
Animation
Loaded
TrackController
AnimTime
JointPalette
JointPaletteScaled
UserControlledJoint
JobJoints
SampleBuffer
SupportMix
EntityId
CharacterSkinNodeIndexOffset

◆ LoadState

enum Characters::CharacterContext::LoadState

Enumerator
NoneLoaded
SkeletonLoaded
AnimationLoaded

Constructor & Destructor Documentation

◆ CharacterContext()

Characters::CharacterContext::CharacterContext ( )

constructor

◆ ~CharacterContext()

Characters::CharacterContext::~CharacterContext ( )

virtual

destructor

Member Function Documentation

◆ __DeclareContext()

Characters::CharacterContext::__DeclareContext ( )

private

◆ Alloc()

Graphics::ContextEntityId Characters::CharacterContext::Alloc ( )

inlinestaticprivate

allocate a new slice for this context

◆ Create()

void Characters::CharacterContext::Create ( )

static

setup character context

◆ CreateAnimSampleMask()

CoreAnimation::AnimSampleMask * Characters::CharacterContext::CreateAnimSampleMask	(	const Util::StringAtom &	name,
		const Util::FixedArray< Math::scalar > &	weights )

static

register anim sample mask, and return pointer

◆ Dealloc()

void Characters::CharacterContext::Dealloc ( Graphics::ContextEntityId id )

inlinestaticprivate

deallocate a slice

◆ GetAnimSampleMask()

CoreAnimation::AnimSampleMask * Characters::CharacterContext::GetAnimSampleMask ( const Util::StringAtom & name )

static

get anim sample mask by name

◆ GetClipIndex()

IndexT Characters::CharacterContext::GetClipIndex	(	const Graphics::GraphicsEntityId	id,
		const Util::StringAtom &	name )

static

perform a clip name lookup

◆ GetTime()

const float Characters::CharacterContext::GetTime ( const Graphics::GraphicsEntityId id )

static

get current time of animation

◆ IsPlaying()

bool Characters::CharacterContext::IsPlaying ( const Graphics::GraphicsEntityId id )

static

check if any animation is playing

◆ OnRenderDebug()

void Characters::CharacterContext::OnRenderDebug ( uint32_t flags )

static

debug rendering

◆ PauseTrack()

void Characters::CharacterContext::PauseTrack	(	const Graphics::GraphicsEntityId	id,
		const IndexT	track )

static

pause animation on track, which doesn't reset time

◆ PlayClip()

bool Characters::CharacterContext::PlayClip	(	const Graphics::GraphicsEntityId	id,
		const CoreAnimation::AnimSampleMask *	mask,
		const IndexT	clipIndex,
		const IndexT	track,
		const EnqueueMode	mode,
		const float	weight = 1.0f,
		const SizeT	loopCount = 1,
		const float	startTime = 0.0f,
		const float	fadeIn = 0.0f,
		const float	fadeOut = 0.0f,
		const float	timeOffset = 0.0f,
		const float	timeFactor = 1.0f )

static

play animation on a specific track

◆ QueryClips()

void Characters::CharacterContext::QueryClips	(	const Graphics::GraphicsEntityId	id,
		Util::FixedArray< CoreAnimation::AnimClip > &	outClips )

static

retrieve animation clip names and lengths

◆ Seek()

void Characters::CharacterContext::Seek	(	const Graphics::GraphicsEntityId	id,
		const float	time )

static

seek animation to a certain time, clamps to length

◆ SetTrackTimeFactor()

void Characters::CharacterContext::SetTrackTimeFactor	(	const Graphics::GraphicsEntityId	id,
		const IndexT	track,
		const float	factor )

static

set time factor for track

◆ SetTrackWeight()

void Characters::CharacterContext::SetTrackWeight	(	const Graphics::GraphicsEntityId	id,
		const IndexT	track,
		const float	weight )

static

set weight for track

◆ Setup()

void Characters::CharacterContext::Setup	(	const Graphics::GraphicsEntityId	id,
		const Resources::ResourceName &	skeletonResource,
		const IndexT	skeletonIndex,
		const Resources::ResourceName &	animationResource,
		const IndexT	animationIndex,
		const Util::StringAtom &	tag,
		bool	supportBlending = true )

static

setup character context, assumes there is already a model attached, by loading a skeleton and animation resource

◆ StopAllTracks()

void Characters::CharacterContext::StopAllTracks ( const Graphics::GraphicsEntityId id )

static

stops all animations on all tracks

◆ StopTrack()

void Characters::CharacterContext::StopTrack	(	const Graphics::GraphicsEntityId	id,
		const IndexT	track )

static

stops all animations queued on track (and resets their time)

◆ UpdateAnimations()

void Characters::CharacterContext::UpdateAnimations ( const Graphics::FrameContext & ctx )

static

runs before frame is updated

◆ WaitForCharacterJobs()

void Characters::CharacterContext::WaitForCharacterJobs ( const Graphics::FrameContext & ctx )

static

run after frame

Friends And Related Symbol Documentation

◆ CharacterJobContext

friend struct CharacterJobContext

friend

◆ EvalCharacter

void EvalCharacter	(	SizeT	totalJobs,
		SizeT	groupSize,
		IndexT	groupIndex,
		SizeT	invocationOffset,
		void *	ctx )

friend

◆ GetAbsoluteStopTime

Timing::Tick GetAbsoluteStopTime ( const CharacterContext::AnimationRuntime & runtime )

friend

◆ IsExpired

const bool IsExpired	(	const CharacterContext::AnimationRuntime &	runtime,
		const Timing::Time	time )

friend

◆ IsInfinite

const bool IsInfinite ( const CharacterContext::AnimationRuntime & runtime )

friend

Member Data Documentation

◆ characterContextAllocator

CharacterContext::CharacterContextAllocator Characters::CharacterContext::characterContextAllocator

staticprivate

◆ ConstantUpdateCounter

Threading::AtomicCounter Characters::CharacterContext::ConstantUpdateCounter = 0

static

◆ masks

Util::HashTable< Util::StringAtom, CoreAnimation::AnimSampleMask > Characters::CharacterContext::masks

staticprivate

◆ MaxNumTracks

const SizeT Characters::CharacterContext::MaxNumTracks = 16

staticprivate

◆ totalCompletionEvent

Threading::Event Characters::CharacterContext::totalCompletionEvent

staticprivate

The documentation for this class was generated from the following files:

/github/workspace/code/render/characters/charactercontext.h
/github/workspace/code/render/characters/charactercontext.cc

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Types

Private Member Functions

Static Private Member Functions

Static Private Attributes

Friends

Additional Inherited Members

Member Typedef Documentation

◆ CharacterContextAllocator

Member Enumeration Documentation

◆ anonymous enum

◆ LoadState

Constructor & Destructor Documentation

◆ CharacterContext()

◆ ~CharacterContext()

Member Function Documentation

◆ __DeclareContext()

◆ Alloc()

◆ Create()

◆ CreateAnimSampleMask()

◆ Dealloc()

◆ GetAnimSampleMask()

◆ GetClipIndex()

◆ GetTime()

◆ IsPlaying()

◆ OnRenderDebug()

◆ PauseTrack()

◆ PlayClip()

◆ QueryClips()

◆ Seek()

◆ SetTrackTimeFactor()

◆ SetTrackWeight()

◆ Setup()

◆ StopAllTracks()

◆ StopTrack()

◆ UpdateAnimations()

◆ WaitForCharacterJobs()

Friends And Related Symbol Documentation

◆ CharacterJobContext

◆ EvalCharacter

◆ GetAbsoluteStopTime

◆ IsExpired

◆ IsInfinite

Member Data Documentation

◆ characterContextAllocator

◆ ConstantUpdateCounter

◆ masks

◆ MaxNumTracks

◆ totalCompletionEvent