Class TransformHelpers

Provides a variety of convenience functions for transforms.

Inheritance
System.Object
TransformHelpers
Namespace: Unity.Tiny.Core2D
Syntax
public static class TransformHelpers

Methods

ApplyTree(ComponentSystem, Entity, TransformHelpers.ApplyTreeDelegate, Boolean, Boolean)

Apply a delegate function to a sub-tree in the transform hierarchy.

Declaration
public static void ApplyTree(ComponentSystem callingSystem, Entity node, TransformHelpers.ApplyTreeDelegate d, bool actOnSelf = true, bool includeDisabled = false)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
TransformHelpers.ApplyTreeDelegate d
System.Boolean actOnSelf
System.Boolean includeDisabled
Remarks

This function can be very slow and should be used sparingly. Always prefer grouping entities with different mechanisms than via the hierarchy.

CloneTree(ComponentSystem, Entity)

Clones the entire hierarchy tree, including node. Returns the clone of node. All cloned descendants are in the new hierarchy. This function can be slow. Use it sparingly.

Declaration
public static Entity CloneTree(ComponentSystem callingSystem, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
Returns
Type Description
Entity

CloneTreeDeferred(ComponentSystem, EntityCommandBuffer, Entity)

Clones the entire hierarchy tree, including node. Returns the clone of node. All cloned descendants are in the new hierarchy. This function is like CloneTree, but takes an explicit entity command buffer. This function can be slow. Use it sparingly.

Declaration
public static Entity CloneTreeDeferred(ComponentSystem callingSystem, EntityCommandBuffer ecb, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
EntityCommandBuffer ecb
Entity node
Returns
Type Description
Entity

ComputeLocalMatrix(ComponentSystem, Entity)

Computes a new local matrix of the kind produced in the LocalToParent component. This function does not use LocalToParent, and can be quite resource intensive. Use it only if the cached result in LocalToParent is not available.

Declaration
public static float4x4 ComputeLocalMatrix(ComponentSystem callingSystem, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
Returns
Type Description
float4x4

ComputeWorldMatrix(ComponentSystem, Entity)

Computes a new Object to World matrix of the kind produced in the LocalToWorld component. This function does not use LocalToWorld, and can be quite resource intensive. Use it only if the cached result in LocalToParent is not available.

Declaration
public static float4x4 ComputeWorldMatrix(ComponentSystem callingSystem, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
Returns
Type Description
float4x4

ComputeWorldPosition(ComponentSystem, Entity)

Computes a transform node's world position. This function uses the computeWorldMatrix function to compute the world matrix (bypassing caching), and returns the position of that.

This function can be quite resource intensive. When possible, read the LocalToWorld component instead.

Declaration
public static float3 ComputeWorldPosition(ComponentSystem callingSystem, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
Returns
Type Description
float3

ComputeWorldRotation(ComponentSystem, Entity)

Computes a transform node's world rotation. This function uses the computeWorldMatrix function to compute the world matrix (bypassing caching), and returns the rotation of that.

This function can be quite resource intensive. When possible, read the LocalToWorld component instead.

Declaration
public static quaternion ComputeWorldRotation(ComponentSystem callingSystem, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
Returns
Type Description
quaternion

ComputeWorldScaleLossy(ComponentSystem, Entity)

Computes a transform node's world scale. This function uses the computeWorldMatrix function to compute the world matrix (bypassing caching), and returns the scale of that.

Because lossy scale does not include skew, it does not include enough information to recreate a full 4x4 matrix from rotation, position, and lossy scale in 3D.

This function can be quite resource intensive. If possible, read the LocalToWorld component instead.

Declaration
public static float3 ComputeWorldScaleLossy(ComponentSystem callingSystem, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
Returns
Type Description
float3

CountChildren(ComponentSystem, Entity)

Returns the number of children that node has. Avoid using this function in inner loops, where it can be very slow.

Declaration
public static int CountChildren(ComponentSystem callingSystem, Entity parent)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity parent
Returns
Type Description
System.Int32

DebugCheckAllNodes(ComponentSystem)

Checks for cycles in the transform hierarchy. If there is a cycle, returns the entity at which a cycle was detected. Otherwise, return Entity.Null.

Declaration
public static Entity DebugCheckAllNodes(ComponentSystem callingSystem)
Parameters
Type Name Description
ComponentSystem callingSystem
Returns
Type Description
Entity

DestroyTree(ComponentSystem, Entity, Boolean)

Destroys all of node's children recursively. The destroySelf parameter specifies whether to also destroy the entity in node along with its children.

Declaration
public static void DestroyTree(ComponentSystem callingSystem, Entity node, bool destroySelf = true)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
System.Boolean destroySelf
Remarks

This function can be very slow and should be used sparingly. Always prefer grouping entities with different mechanisms than via the hierarchy.

DestroyTreeDeferred(ComponentSystem, EntityCommandBuffer, Entity, Boolean)

Destroys all of node's children recursively. The destroySelf parameter specifies whether to also destroy the entity along with its children. This function is like DestroyTree, but takes an explicit entity command buffer. This function can be slow. Use it sparingly.

Declaration
public static void DestroyTreeDeferred(ComponentSystem callingSystem, EntityCommandBuffer ecb, Entity node, bool destroySelf = true)
Parameters
Type Name Description
ComponentSystem callingSystem
EntityCommandBuffer ecb
Entity node
System.Boolean destroySelf

DisableTree(ComponentSystem, Entity, Boolean)

Add the Disabled component to all of node's children recursively. The disableSelf parameter specifies whether to also add Disabled to the entity in node along with its children.

Declaration
public static void DisableTree(ComponentSystem callingSystem, Entity node, bool disableSelf = true)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
System.Boolean disableSelf
Remarks

There is no error if entities were already Disabled to begin with. This function can be very slow and should be used sparingly. Always prefer grouping entities with different mechanisms than via the hierarchy.

EnableTree(ComponentSystem, Entity, Boolean)

Remove the Disabled component from all of node's children recursively. The enableSelf parameter specifies whether to also remove the Disabled component from the entity in node along with its children.

Declaration
public static void EnableTree(ComponentSystem callingSystem, Entity node, bool enableSelf = true)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
System.Boolean enableSelf
Remarks

There is no error if entities were not Disabled to begin with. This function can be very slow and should be used sparingly. Always prefer grouping entities with different mechanisms than via the hierarchy.

Find(ComponentSystem, Entity, String)

Finds a child entity of node with the given name. You can search deeper in the hierarchy to find a child of a child entity, a child of that child, and so on by separating the levels with forward slashes (/) in the name.

For example Find(node, "a/b/c") is the same as Find(Find(Find(node,"a"),"b"),"c");

Initial lookups can be slow, but are cached if successful. Failed lookups are not cached.

Declaration
public static Entity Find(ComponentSystem callingSystem, Entity node, string name)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
System.String name
Returns
Type Description
Entity

GetChild(ComponentSystem, Entity, Int32)

Returns a child entity at the given index. If the index is out of range, returns Entity.NONE. Note that because the order of children can change at any time, a given index does not return the same child every time. In most cases, you can obtain better results by using the Find function or caching children locally. Avoid using this function in inner loops, where it can be very slow.

Declaration
public static Entity GetChild(ComponentSystem callingSystem, Entity parent, int index = 0)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity parent
System.Int32 index
Returns
Type Description
Entity

GetChildren(ComponentSystem, Entity, ref NativeList<Entity>, Boolean)

Adds children of a node to the children list and returns the number of children added. Children are appended to the array, so you can use it for collection. Avoid using this function in inner loops, where it can be very slow.

Declaration
public static int GetChildren(ComponentSystem callingSystem, Entity parent, ref NativeList<Entity> children, bool includeDisabled = false)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity parent
NativeList<Entity> children
System.Boolean includeDisabled
Returns
Type Description
System.Int32

GetTree(ComponentSystem, Entity, ref NativeList<Entity>, Boolean)

Appends all children of node to the children array. Returns number of children added to the array. This function can be slow. Use it sparingly.

Declaration
public static int GetTree(ComponentSystem callingSystem, Entity node, ref NativeList<Entity> children, bool includeDisabled = false)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
NativeList<Entity> children
System.Boolean includeDisabled
Returns
Type Description
System.Int32

LocalPositionFromWorldPosition(ComponentSystem, Entity, float3)

Inverse-transforms a position by the LocalToWorld matrix. This function uses the computeWorldMatrix function to compute the world matrix (bypassing caching), then transforms by that.

This function can be quite resource intensive. When possible, read the LocalToWorld component instead.

Declaration
public static float3 LocalPositionFromWorldPosition(ComponentSystem callingSystem, Entity node, float3 position)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
float3 position
Returns
Type Description
float3

LocalRotationFromWorldRotation(ComponentSystem, Entity, quaternion)

Inverse-transforms a rotation by the LocalToWorld matrix. This function uses the computeWorldMatrix function to compute the world matrix (bypassing caching), then transforms by that.

This function can be quite resource intensive. When possible, read the LocalToWorld component instead.

Declaration
public static quaternion LocalRotationFromWorldRotation(ComponentSystem callingSystem, Entity node, quaternion rotation)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
quaternion rotation
Returns
Type Description
quaternion

LocalScaleFromWorldScale(ComponentSystem, Entity, float3)

Inverse-transforms a scale by the LocalToWorld matrix. This function uses the computeWorldMatrix function to compute the world matrix (bypassing caching), then transforms by that.

This function can be quite resource intensive. When possible, read the LocalToWorld component instead.

Declaration
public static float3 LocalScaleFromWorldScale(ComponentSystem callingSystem, Entity node, float3 scale)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node
float3 scale
Returns
Type Description
float3

Unlink(ComponentSystem, Entity)

Completely removes this node from the hierarchy, and sets the parent of all of its children to NONE. Avoid using this function in inner loops, where it can be very slow.

Declaration
public static void Unlink(ComponentSystem callingSystem, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity node

UnlinkAllChildren(ComponentSystem, Entity)

Sets the parent of all of node's child entities to NONE. Avoid using this function in inner loops, where it can be very slow.

Declaration
public static void UnlinkAllChildren(ComponentSystem callingSystem, Entity parent)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity parent

UnlinkAllChildrenDeferred(ComponentSystem, EntityCommandBuffer, Entity)

Sets the parent of all of node's child entities to NONE. This function is like UnlinkAllChildren, but takes an explicit entity command buffer. Avoid using this function in inner loops, where it can be very slow.

Declaration
public static void UnlinkAllChildrenDeferred(ComponentSystem callingSystem, EntityCommandBuffer ecb, Entity parent)
Parameters
Type Name Description
ComponentSystem callingSystem
EntityCommandBuffer ecb
Entity parent

UnlinkDeferred(ComponentSystem, EntityCommandBuffer, Entity)

Completely removes this node from the hierarchy, and sets the parent of all of its children to NONE. This function is like Unlink, but takes an explicit entity command buffer. Avoid using this function in inner loops, where it can be very slow.

Declaration
public static void UnlinkDeferred(ComponentSystem callingSystem, EntityCommandBuffer ecb, Entity node)
Parameters
Type Name Description
ComponentSystem callingSystem
EntityCommandBuffer ecb
Entity node

WindowToWorld(ComponentSystem, Entity, float2, float2)

Helper function for transforming from window to world coordinates. This only works if cameraEntity has a valid LocalToWorld component. The windowPos (window position) and windowSize (window size) should be in the same coordinates. The Z coordinate is set to 0.

Declaration
public static float3 WindowToWorld(ComponentSystem callingSystem, Entity cameraEntity, float2 windowPos, float2 windowSize)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity cameraEntity
float2 windowPos
float2 windowSize
Returns
Type Description
float3

WorldToWindow(ComponentSystem, Entity, float3, float2)

Helper function for transforming from world to window coordinates. This only works if the cameraEntity has a valid LocalToWorld component. Returns windowPos (window position) and windowSize (window size) in the same coordinates.

Declaration
public static float2 WorldToWindow(ComponentSystem callingSystem, Entity cameraEntity, float3 worldPos, float2 windowSize)
Parameters
Type Name Description
ComponentSystem callingSystem
Entity cameraEntity
float3 worldPos
float2 windowSize
Returns
Type Description
float2