Package com.google.android.filament

Class TransformManager

  • public class TransformManager
extends java.lang.Object
    TransformManager is used to add transform components to entities.

    A transform component gives an entity a position and orientation in space in the coordinate space of its parent transform. The TransformManager takes care of computing the world-space transform of each component (i.e. its transform relative to the root).

    Creation and destruction

    A transform component is created using create(int) and destroyed by calling destroy(int). 
      Engine engine = Engine.create();
  EntityManager entityManager = EntityManager().get();
  int object = entityManager.create();

  TransformManager tcm = engine.getTransformManager();

  // create the transform component
  tcm.create(object);

  // set its transform
  float[] transform = ...; // transform to set
  EntityInstance i = tcm.getInstance(object);
  tcm.setTransform(i, transform));

  // destroy the transform component
  tcm.destroy(object);

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void commitLocalTransformTransaction()
      Commits the currently open local transform transaction.
      int create​(int entity)
      Creates a transform component and associates it with the given entity.
      int create​(int entity, int parent, double[] localTransform)
      Creates a transform component with a parent and associates it with the given entity.
      int create​(int entity, int parent, float[] localTransform)
      Creates a transform component with a parent and associates it with the given entity.
      void destroy​(int entity)
      Destroys this component from the given entity, children are orphaned.
      int getInstance​(int entity)
      Gets an EntityInstance representing the transform component associated with the given Entity.
      long getNativeObject()  
      int getParent​(int i)
      Returns the actual parent entity of an EntityInstance originally defined by setParent(int, int).
      double[] getTransform​(int i, double[] outLocalTransform)
      Returns the local transform of a transform component.
      float[] getTransform​(int i, float[] outLocalTransform)
      Returns the local transform of a transform component.
      double[] getWorldTransform​(int i, double[] outWorldTransform)
      Returns the world transform of a transform component.
      float[] getWorldTransform​(int i, float[] outWorldTransform)
      Returns the world transform of a transform component.
      boolean hasComponent​(int entity)
      Returns whether a particular Entity is associated with a component of this TransformManager
      boolean isAccurateTranslationsEnabled()
      Returns whether the high precision translation mode is active.
      void openLocalTransformTransaction()
      Opens a local transform transaction.
      void setAccurateTranslationsEnabled​(boolean enable)
      Enables or disable the accurate translation mode.
      void setParent​(int i, int newParent)
      Re-parents an entity to a new one.
      void setTransform​(int i, double[] localTransform)
      Sets a local transform of a transform component.
      void setTransform​(int i, float[] localTransform)
      Sets a local transform of a transform component.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • hasComponent

        public boolean hasComponent​(int entity)
        Returns whether a particular Entity is associated with a component of this TransformManager
        Parameters:
        entity - an Entity
        Returns:
        true if this Entity has a component associated with this manager

      • isAccurateTranslationsEnabled

        public boolean isAccurateTranslationsEnabled()
        Returns whether the high precision translation mode is active.
        Returns:
        true if accurate translations mode is active, false otherwise
        See Also:
        setAccurateTranslationsEnabled(boolean)

      • create

        public int create​(int entity)
        Creates a transform component and associates it with the given entity. The component is initialized with the identity transform. If this component already exists on the given entity, it is first destroyed as if destroy(int) was called.
        Parameters:
        entity - an Entity to associate a transform component to.
        See Also:
        destroy(int)

      • create

        public int create​(int entity,
                  int parent,
                  @Nullable @Size(min=16L)
                  float[] localTransform)
        Creates a transform component with a parent and associates it with the given entity. If this component already exists on the given entity, it is first destroyed as if destroy(int) was called.
        Parameters:
        entity - an Entity to associate a transform component to.
        parent - the EntityInstance of the parent transform
        localTransform - the transform, relative to the parent, to initialize the transform component with.
        See Also:
        destroy(int)

      • create

        public int create​(int entity,
                  int parent,
                  @Nullable @Size(min=16L)
                  double[] localTransform)
        Creates a transform component with a parent and associates it with the given entity. If this component already exists on the given entity, it is first destroyed as if destroy(int) was called.
        Parameters:
        entity - an Entity to associate a transform component to.
        parent - the EntityInstance of the parent transform
        localTransform - the transform, relative to the parent, to initialize the transform component with.
        See Also:
        destroy(int)

      • destroy

        public void destroy​(int entity)
        Destroys this component from the given entity, children are orphaned.
        Parameters:
        entity - an Entity. If this transform had children, these are orphaned, which means their local transform becomes a world transform. Usually it's nonsensical. It's recommended to make sure that a destroyed transform doesn't have children.
        See Also:
        create(int)

      • setParent

        public void setParent​(int i,
                      int newParent)
        Re-parents an entity to a new one.
        Parameters:
        i - the EntityInstance of the transform component to re-parent
        newParent - the EntityInstance of the new parent transform. It is an error to re-parent an entity to a descendant and will cause undefined behaviour.
        See Also:
        getInstance(int)

      • setTransform

        public void setTransform​(int i,
                         @NonNull @Size(min=16L)
                         float[] localTransform)
        Sets a local transform of a transform component.

        This operation can be slow if the hierarchy of transform is too deep, and this will be particularly bad when updating a lot of transforms. In that case, consider using openLocalTransformTransaction() / commitLocalTransformTransaction().

        Parameters:
        i - the EntityInstance of the transform component to set the local transform to.
        localTransform - the local transform (i.e. relative to the parent).
        See Also:
        getTransform(int, float[])

      • getTransform

        @NonNull
@Size(min=16L)
public float[] getTransform​(int i,
                            @Nullable @Size(min=16L)
                            float[] outLocalTransform)
        Returns the local transform of a transform component.
        Parameters:
        i - the EntityInstance of the transform component to query the local transform from.
        outLocalTransform - a 16 float array to receive the result. If null is given, a new suitable array is allocated.
        Returns:
        the local transform of the component (i.e. relative to the parent). This always returns the value set by setTransform().
        See Also:
        setTransform(int, float[])

      • getTransform

        @NonNull
@Size(min=16L)
public double[] getTransform​(int i,
                             @Nullable @Size(min=16L)
                             double[] outLocalTransform)
        Returns the local transform of a transform component.
        Parameters:
        i - the EntityInstance of the transform component to query the local transform from.
        outLocalTransform - a 16 float array to receive the result. If null is given, a new suitable array is allocated.
        Returns:
        the local transform of the component (i.e. relative to the parent). This always returns the value set by setTransform().
        See Also:
        setTransform(int, float[])

      • getWorldTransform

        @NonNull
@Size(min=16L)
public float[] getWorldTransform​(int i,
                                 @Nullable @Size(min=16L)
                                 float[] outWorldTransform)
        Returns the world transform of a transform component.
        Parameters:
        i - the EntityInstance of the transform component to query the world transform from.
        outWorldTransform - a 16 float array to receive the result. If null is given, a new suitable array is allocated
        Returns:
        The world transform of the component (i.e. relative to the root). This is the composition of this component's local transform with its parent's world transform.
        See Also:
        setTransform(int, float[])

      • getWorldTransform

        @NonNull
@Size(min=16L)
public double[] getWorldTransform​(int i,
                                  @Nullable @Size(min=16L)
                                  double[] outWorldTransform)
        Returns the world transform of a transform component.
        Parameters:
        i - the EntityInstance of the transform component to query the world transform from.
        outWorldTransform - a 16 float array to receive the result. If null is given, a new suitable array is allocated
        Returns:
        The world transform of the component (i.e. relative to the root). This is the composition of this component's local transform with its parent's world transform.
        See Also:
        setTransform(int, float[])

      • commitLocalTransformTransaction

        public void commitLocalTransformTransaction()
        Commits the currently open local transform transaction. When this returns, calls to getWorldTransform(int, float[]) will return the proper value.

        Failing to call this method when done updating the local transform will cause a lot of rendering problems. The system never closes the transaction automatically.

        If the local transform transaction is not open, this is a no-op.

        See Also:
        openLocalTransformTransaction(), setTransform(int, float[])

      • getNativeObject

        public long getNativeObject()