Class TransformStack

java.lang.Object
eu.svjatoslav.aukio.e3d.math.TransformStack
public class TransformStack extends Object
Stack of transforms applied to points during rendering.

Transforms are applied in reverse order (last added is applied first). This supports hierarchical scene graphs where child objects are positioned relative to their parent objects.

Example:

There is a ship in the sea. The ship moves along the sea, and every object
on the ship moves with it. Inside the ship there is a car. The car moves
along the ship, and every object on the car moves with it.

To calculate the world position of an object inside the car:
1. Apply an object's position relative to the car
2. Apply the car's position relative to the ship
3. Apply ship's position relative to the world

Implementation: eager composition. Every transform is a similarity transform (uniform scale, then rotation, then translation). Uniform scale commutes with rotation, so compositions stay closed and associative: the whole stack collapses into a single equivalent transform. The stack maintains the composed scale-rotation matrix and translation for each level: addTransform(Transform) folds the pushed transform's scale into the matrix and composes it with the previous level's composite, and transform(Point3D, Point3D) applies only the top-level composite. Per-point cost is one 3x3 matrix-vector multiply plus one addition, independent of stack depth. dropTransform() restores the parent composite for free.

Contract: composition is a snapshot taken at push time. Mutating a transform after pushing it has no effect on the stack until it is dropped and pushed again. The traversal rebuilds the stack every frame, so frame-to-frame changes are always picked up.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    TransformStack()
    Creates a new empty transform stack.
    TransformStack(TransformStack source)
    Creates a copy of another transform stack, duplicating its composed per-level transforms.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addTransform(Transform transform)
    Pushes a transform onto the stack, composing it with the current top-level composite.
    void
    clear()
    Clears all transforms from the stack.
    void
    dropTransform()
    Pops the most recently added transform from the stack.
    void
    getTopTransform(double[] out)
    Copies the fully composed top-level transform (rotations 0..8, then translations 0..2) into out (length ≥ 12), for bulk loops that apply the same matrix to thousands of vertices (TriangleMeshBlock).
    void
    loadFrom(TransformStack source)
    Reinitializes this stack as a copy of source without allocating: the fixed-size arrays are reused.
    void
    transform(Point3D coordinate, Point3D result)
    Transforms a point through the whole stack by applying the top-level composed transform.

    Methods inherited from class Object

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

  • Constructor Details

    • TransformStack

      public TransformStack()
      Creates a new empty transform stack.

    • TransformStack

      public TransformStack(TransformStack source)
      Creates a copy of another transform stack, duplicating its composed per-level transforms. Used to give each parallel transform worker its own stack preloaded with the same camera/parent state.
      Parameters:
      source - the stack to copy

  • Method Details

    • loadFrom

      public void loadFrom(TransformStack source)
      Reinitializes this stack as a copy of source without allocating: the fixed-size arrays are reused. Used by the parallel transform coordinator to hand pooled stacks to chunk tasks.
      Parameters:
      source - the stack to copy

    • addTransform

      public void addTransform(Transform transform)
      Pushes a transform onto the stack, composing it with the current top-level composite.

      If the previous composite is (Mp, tp) and the pushed transform has scale s, rotation Rn and translation tn, the new composite is M' = Mp * (s * Rn), t' = Mp * tn + tp — the pushed transform applies first, then the previous composite. Because uniform scale commutes with rotation, folding s into the pushed matrix keeps the composition closed: the stored parent matrix already carries the parent's scale. With the default scale of 1.0 the extra multiply is IEEE-exact, so rigid-motion scenes stay bit-identical.

      Parameters:
      transform - the transform to push (snapshotted at push time)

    • clear

      public void clear()
      Clears all transforms from the stack.

    • dropTransform

      public void dropTransform()
      Pops the most recently added transform from the stack. The parent level's composite is restored automatically.

    • transform

      public void transform(Point3D coordinate, Point3D result)
      Transforms a point through the whole stack by applying the top-level composed transform. Cost is independent of stack depth.
      Parameters:
      coordinate - the input coordinate (not modified)
      result - the output coordinate (receives transformed result)

    • getTopTransform

      public void getTopTransform(double[] out)
      Copies the fully composed top-level transform (rotations 0..8, then translations 0..2) into out (length ≥ 12), for bulk loops that apply the same matrix to thousands of vertices (TriangleMeshBlock). Identity when the stack is empty. Applying it with the same expression order as transform(Point3D, Point3D) yields bit-identical results.
      Parameters:
      out - destination array, length at least 12