Package eu.svjatoslav.sixth.e3d.math

Class TransformStack

java.lang.Object
eu.svjatoslav.sixth.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 rigid motion (rotation then translation), and compositions of rigid motions are closed and associative, so the whole stack collapses into a single equivalent transform. The stack maintains the composed rotation matrix and translation for each level: addTransform(eu.svjatoslav.sixth.e3d.math.Transform) composes the pushed transform with the previous level's composite, and transform(eu.svjatoslav.sixth.e3d.geometry.Point3D, eu.svjatoslav.sixth.e3d.geometry.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 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

    • 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 (Rp, tp) and the pushed transform is (Rn, tn), the new composite is R' = Rp * Rn, t' = Rp * tn + tp — the pushed transform applies first, then the previous composite.

      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)