Struct MotionSynthesizer

The motion synthesizer is the actual core component of Kinematica.

Namespace: Unity.Kinematica
Syntax
public struct MotionSynthesizer
Remarks

The motion synthesizer represents the actual core implementation of Kinematica which can be used in a pure DOTS environment directly.

It provides a raw transform buffer which represents the current character pose and does not provide any infrastructure to feed the current pose to the character.

The motion synthesizer continuously "plays" an sequence of animation poses. The current time can be changed by "pushing" a new time to the synthesizer. Upon pushing a new time, the synthesizer automatically removes any deviations between the previous pose and the new pose.

The motion synthesizer also has a convenient method of creating semantic queries, which filter the poses stored in the motion library based on tags and markers.

Last but not least, the motion synthesizer contains a task graph that consist of a hierarchy of nodes that collectively can operate on a sequence of poses to perform a user defined processing step in order to arrive at a single new "push time" each frame.

Fields

self

Denotes a references to the motion synthesizer itself.

Declaration
public MemoryRef<MotionSynthesizer> self
Field Value
Type Description
MemoryRef<MotionSynthesizer>

trajectory

The trajectory model maintains a representation of the simulated character movement over the global time horizon.

Declaration
public TrajectoryModel trajectory
Field Value
Type Description
TrajectoryModel

Properties

ApproximateTransitionProgression

Declaration
public float ApproximateTransitionProgression { get; }
Property Value
Type Description
Single

Binary

Allows direct access to the underlying Kinematica runtime asset.

Declaration
public Binary Binary { get; }
Property Value
Type Description
Binary

CurrentPushIndex

Declaration
public int CurrentPushIndex { get; }
Property Value
Type Description
Int32

deltaTime

Denotes the delta time in seconds during the last update.

Declaration
public float deltaTime { get; }
Property Value
Type Description
Single

Query

Introduces a new semantic query expression.

Declaration
public Query Query { get; }
Property Value
Type Description
Query
See Also

Root

Denotes the identifier of the root task.

Declaration
public MemoryIdentifier Root { get; }
Property Value
Type Description
MemoryIdentifier
Remarks

All user defined tasks and their corresponding input and output data will be a direct or indirect child of the root task.

Time

Denotes the current sampling time of the motion synthesizer.

Declaration
public SamplingTime Time { get; }
Property Value
Type Description
SamplingTime

TrajectoryArray

Allows access to the trajectory of the motion synthesizer.

Declaration
public MemoryArray<AffineTransform> TrajectoryArray { get; }
Property Value
Type Description
MemoryArray<AffineTransform>
Remarks

The trajectory consists out of a series of transforms that correspond to the transform of the root joint over time.

The sampling frequency and length of the trajectory is defined by the sampling rate and time horizon respectively. Both parameters are defined as a global parameter in the runtime asset.

The trajectory covers a duration which is twice as long as the time horizon. The first half of the trajectory represents the past movement of the character, whereas the second half represents the future movement of the character.

All transforms stored in the trajectory are always relative to the current character root transform, i.e. the trajectory is maintained in character space.

WorldRootTransform

Denotes the world space root transform of the character.

Declaration
public AffineTransform WorldRootTransform { get; set; }
Property Value
Type Description
AffineTransform

Methods

AdjustTrajectory(AffineTransform, Boolean)

Allows for non-continuous root displacements.

Declaration
public void AdjustTrajectory(AffineTransform deltaTransform, bool bKeepPastTrajectoryInWorldSpace = false)
Parameters
Type Name Description
AffineTransform deltaTransform

Delta transform to be applied to the character root transform.
Boolean bKeepPastTrajectoryInWorldSpace

If true, past trajectory will stay at the same location in world space, otherwise it will follow the root transform
Remarks

This method can be used to teleport the character by utilizing a displacement transform.

Allocate<T>(T)

Creates a new node in the task graph. Nodes represent either data or executable tasks.

Declaration
public MemoryIdentifier Allocate<T>(T task)
    where T : struct
Parameters
Type Name Description
T task

Instance of the new node.
Returns
Type Description
MemoryIdentifier

Memory identifier that corresponds to the newly created node.
Type Parameters
Name Description
T
Remarks

The new node will always be created as a child of the task graph root node. Newly created nodes will be valid for the current frame but have to get ticked during subsequent frames in order for them to stay alive.

Allocate<T>(T, MemoryIdentifier)

Creates a new node in the task graph. Nodes represent either data or executable tasks.

Declaration
public MemoryIdentifier Allocate<T>(T task, MemoryIdentifier parent)
    where T : struct
Parameters
Type Name Description
T task

Instance of the new node.
MemoryIdentifier parent

Memory identifier of the parent for the new node.
Returns
Type Description
MemoryIdentifier

Memory identifier that corresponds to the newly created node.
Type Parameters
Name Description
T
Remarks

The new node will be created as a child of the parent node passed as argument. Newly created nodes will be valid for the current frame but have to get ticked during subsequent frames in order for them to stay alive.

Allocate<T>(NativeList<T>, MemoryIdentifier)

Creates a new data array in the task graph.

Declaration
public MemoryIdentifier Allocate<T>(NativeList<T> source, MemoryIdentifier parent)
    where T : struct
Parameters
Type Name Description
NativeList<T> source

Native list which will be copied into the newly created data array.
MemoryIdentifier parent

Memory identifier of the parent for the new node.
Returns
Type Description
MemoryIdentifier

Memory identifier that corresponds to the newly created node.
Type Parameters
Name Description
T
Remarks

The new data array will be created as a child of the parent node passed as argument. Newly created nodes will be valid for the current frame but have to get ticked during subsequent frames in order for them to stay alive.

Allocate<T>(MemoryArray<T>, MemoryIdentifier)

Creates a new data array in the task graph.

Declaration
public MemoryIdentifier Allocate<T>(MemoryArray<T> source, MemoryIdentifier parent)
    where T : struct
Parameters
Type Name Description
MemoryArray<T> source

Array which will be copied into the newly created data array.
MemoryIdentifier parent

Memory identifier of the parent for the new node.
Returns
Type Description
MemoryIdentifier

Memory identifier that corresponds to the newly created node.
Type Parameters
Name Description
T
Remarks

The new data array will be created as a child of the parent node passed as argument. Newly created nodes will be valid for the current frame but have to get ticked during subsequent frames in order for them to stay alive.

AllocateArray<T>(Int32, MemoryIdentifier)

Creates a new data array in the task graph.

Declaration
public MemoryIdentifier AllocateArray<T>(int length, MemoryIdentifier parent)
    where T : struct
Parameters
Type Name Description
Int32 length

Length of the data array to be created.
MemoryIdentifier parent

Memory identifier of the parent for the new node.
Returns
Type Description
MemoryIdentifier

Memory identifier that corresponds to the newly created node.
Type Parameters
Name Description
T
Remarks

The new data array will be created as a child of the parent node passed as argument. Newly created nodes will be valid for the current frame but have to get ticked during subsequent frames in order for them to stay alive.

BringToFront(MemoryIdentifier)

Reorders a task graph node to be the first child of its parent.

Declaration
public void BringToFront(MemoryIdentifier identifier)
Parameters
Type Name Description
MemoryIdentifier identifier

Identifier of the node that should be reordered.
Remarks

Newly created task graph nodes will be created as the last child of its parent. Subsequently, the new node will be executed after its siblings during the execution of the task graph. This method allows to override this default beahavior and allow the newly created node to be executed before its siblings.

GetArray<T>(MemoryIdentifier)

Retrieves a reference to the data array that corresponds to the memory identifier passed as argument.

Declaration
public MemoryArray<T> GetArray<T>(MemoryIdentifier identifier)
    where T : struct
Parameters
Type Name Description
MemoryIdentifier identifier

Memory identifier for which the data array should be retrieved.
Returns
Type Description
MemoryArray<T>
Type Parameters
Name Description
T

GetByType<T>(MemoryIdentifier)

Searches for a child node based on its type.

Declaration
public MemoryRef<T> GetByType<T>(MemoryIdentifier parent)
    where T : struct
Parameters
Type Name Description
MemoryIdentifier parent

The start node to be used for the search.
Returns
Type Description
MemoryRef<T>

Memory reference of the result.
Type Parameters
Name Description
T
Remarks

Retrieves a reference to a data type that is a direct or indirect child of the identifier passed as argument, subject to a type parameter.

GetRef<T>(MemoryIdentifier)

Retrieves a reference to the task or data instance that corresponds to the memory identifier passed as argument.

Declaration
public MemoryRef<T> GetRef<T>(MemoryIdentifier identifier)
    where T : struct
Parameters
Type Name Description
MemoryIdentifier identifier

Memory identifier for which the instance data should be retrieved.
Returns
Type Description
MemoryRef<T>
Type Parameters
Name Description
T

GetTrajectoryDeltaTransform(Single)

Calculates the curent root displacement transform.

Declaration
public AffineTransform GetTrajectoryDeltaTransform(float deltaTime)
Parameters
Type Name Description
Single deltaTime

Delta time in seconds.
Returns
Type Description
AffineTransform

Root displacement transform at the current sampling time.

MarkForDelete(MemoryIdentifier)

Marks an individual task graph node for deletion during the next update cycle.

Declaration
public void MarkForDelete(MemoryIdentifier identifier)
Parameters
Type Name Description
MemoryIdentifier identifier

Identifier of the node to be deleted.
Remarks

This method can be used in cases where tasks need to replace individual nodes of the task graph section. The node to be replaced can be marked for deletion and a new node can be created that replaces the old one.

Parent(MemoryIdentifier)

Retrieves the identifier of the parent node w.r.t. the identifier passed as argument.

Declaration
public MemoryIdentifier Parent(MemoryIdentifier identifier)
Parameters
Type Name Description
MemoryIdentifier identifier

Memory identifier for which the parent identifier should be retrieved.
Returns
Type Description
MemoryIdentifier

The memory identifier that corresponds to the parent node of the identifier passed as argument.
Remarks

Each node (task or data) in the task graph is uniquely identified via a memory identifier. Tasks are arranged in a hierarchical fashion.

Push(QueryResult)

Pushes a new sampling time into the pose stream.

Declaration
public void Push(QueryResult queryResult)
Parameters
Type Name Description
QueryResult queryResult

Query result obtained from a semantic query.
Remarks

This method accepts a query result (most likely obtained from a semantic query). It unconditionally extracts the first pose from the pose sequence and forwards it as the next sampling time to the internal pose stream generator.

See Also

Push(SamplingTime)

Switches the pose generation stream to read from the sampling time passed as argument.

Declaration
public void Push(SamplingTime samplingTime)
Parameters
Type Name Description
SamplingTime samplingTime

New sampling time for the pose generation.
Remarks

Animation poses are always generated continuously based on a time index. This method allows to switch to a new starting time. The motion synthesizer automatically handles any discrepancies between the old and the new pose.

Push(TimeIndex)

Switches the pose generation stream to read from the time index passed as argument.

Declaration
public void Push(TimeIndex timeIndex)
Parameters
Type Name Description
TimeIndex timeIndex

New starting time index for the pose generation.
Remarks

Animation poses are always generated continuously based on a sampling time. This method allows to switch to a new starting time. The motion synthesizer automatically handles any discrepancies between the old and the new pose.

Rewind(SamplingTime)

Retrieves the time index at the beginning of the interval that the sampling time passed as argument belongs to.

Declaration
public TimeIndex Rewind(SamplingTime samplingTime)
Parameters
Type Name Description
SamplingTime samplingTime

Sampling time for which the corresponding interval start time index should be calculated.
Returns
Type Description
TimeIndex
Remarks

This method can be used to "loop" time indices. 

[Trait, BurstCompile]
public struct Loop : Trait
{
    public void Execute(ref MotionSynthesizer synthesizer)
    {
        synthesizer.Push(synthesizer.Rewind(synthesizer.Time));
    }
}

Rewind(TimeIndex)

Retrieves the time index at the beginning of the interval that the time index passed as argument belongs to.

Declaration
public TimeIndex Rewind(TimeIndex timeIndex)
Parameters
Type Name Description
TimeIndex timeIndex

Time index for which the corresponding interval start time index should be calculated.
Returns
Type Description
TimeIndex
Remarks

This method can be used to "loop" time indices. 

[Trait, BurstCompile]
public struct Loop : Trait
{
    public void Execute(ref MotionSynthesizer synthesizer)
    {
        synthesizer.Push(synthesizer.Rewind(synthesizer.Time));
    }
}

SetWorldTransform(AffineTransform, Boolean)

Teleport character to a target transform

Declaration
public void SetWorldTransform(AffineTransform targetTransform, bool bKeepPastTrajectoryInWorldSpace = false)
Parameters
Type Name Description
AffineTransform targetTransform
Boolean bKeepPastTrajectoryInWorldSpace

If true, past trajectory will stay at the same location in world space, otherwise it will follow the root transform
Remarks

This method can be used to teleport the character by providing a target world transform

SteerRootDeltaTransform(Identifier<Trajectory>, Single, Single, Single)

Returns the interpolated transform between the root delta transform from Kinematica binary for the current frame, and the desired delta transform.

Declaration
public AffineTransform SteerRootDeltaTransform(Identifier<Trajectory> desiredTrajectory, float translationWeight, float rotationWeight, float minSpeed = 0.15F)
Parameters
Type Name Description
Identifier<Trajectory> desiredTrajectory

Memory identifier of the desired trajectory that will be sampled from time 0 to 

_deltaTime
in order to compute the desired delta transform
Single translationWeight

Interpolation weight between the root delta position at 0, and the desired delta position at 1
Single rotationWeight

Interpolation weight between the root delta rotation at 0, and the desired delta rotation at 1
Single minSpeed

Minimum character speed (m/s) at which the interpolation will be fully effective
Returns
Type Description
AffineTransform

Tick()

Ticks the entire task graph during this frame.

Declaration
public void Tick()
Remarks

The task graph can contain any number of user defined tasks and their corresponding input and output data.

Each node (task or data) has to be actively kept alive. This process is called "ticking" in the context of Kinematica and requires one of the Tick() methods to be called. Each node that does not receive a Tick() call will automatically be removed before the task graph executes.

Tick(MemoryIdentifier)

Ticks a section of the task graph.

Declaration
public void Tick(MemoryIdentifier identifier)
Parameters
Type Name Description
MemoryIdentifier identifier

Memory identifier that indicates the parent node of the task graph section to be kept alive.
Remarks

This method ensure that all nodes that are direct or indirect children of the memory identifer passed as argument are considerd to be valid in this frame.

Update(Single)

Update method that needs to be called each frame to advance the state of the motion synthesizer.

Declaration
public bool Update(float deltaTime)
Parameters
Type Name Description
Single deltaTime

Delta time in seconds.
Returns
Type Description
Boolean
Remarks

In a game object environment this method gets automatically called from the Kinematica component.

See Also

Extension Methods

See Also