src/main/java/eu/svjatoslav/sixth/e3d/math/TransformsStack.java

   1 /*
   2  * Sixth 3D engine. Author: Svjatoslav Agejenko.
   3  * This project is released under Creative Commons Zero (CC0) license.
   4  */
   5 package eu.svjatoslav.sixth.e3d.math;
   6
   7 import eu.svjatoslav.sixth.e3d.geometry.Point3D;
   8
   9 /**
  10  * <pre>
  11  * It is used to store and apply transforms to points.
  12  * Transforms are applied in the reverse order they were added to the pipeline.
  13  *
  14  * Transforms are stacked and then every point is affected by every transform in this stack.
  15  * This is needed to support feature where objects in the world are attached to and are relative to each other.
  16  *
  17  * <b>Example:</b>
  18  * There is a ship it the sea. Ship moves along the sea and every object on the ship moves with it.
  19  * Inside the ship there is a car. Car moves along the ship and every object on the car moves with it.
  20  *
  21  * So to calculate an absolute location in the world of particular object within a car,
  22  * we must take into account object location relative to the car,
  23  * car location relative to the ship,
  24  * and ship location relative to the world.
  25  * </pre>
  26  */
  27 public class TransformsStack {
  28
  29
  30     /**
  31      * Transforms that are currently in the pipeline.
  32      * Array is used for efficiency to avoid memory allocation during the rendering
  33      * because depth of the pipeline needs to change very often.
  34      */
  35     private final Transform[] transforms = new Transform[100];
  36
  37     /**
  38      * The number of transforms in the pipeline.
  39      */
  40     private int transformsCount = 0;
  41
  42     /**
  43      * Adds a transform to the pipeline.
  44      *
  45      * @param transform The transform to add.
  46      */
  47     public void addTransform(final Transform transform) {
  48         transforms[transformsCount] = transform;
  49         transformsCount++;
  50     }
  51
  52     /**
  53      * Clears the pipeline.
  54      */
  55     public void clear() {
  56         transformsCount = 0;
  57     }
  58
  59     /**
  60      * Drops the last transform from the pipeline.
  61      */
  62     public void dropTransform() {
  63         transformsCount--;
  64     }
  65
  66     /**
  67      * Transforms a point.
  68      *
  69      * @param coordinate Coordinate to be transformed into result. Original input coordinate is not modified.
  70      * @param result     Resulting transformed point. For efficiency reasons, result is stored into preexisting object
  71      *                   that is passed here as an argument to avoid memory allocation.
  72      */
  73     public void transform(final Point3D coordinate, final Point3D result) {
  74
  75         result.clone(coordinate);
  76
  77         // Apply transforms in reverse order.
  78         for (int i = transformsCount - 1; i >= 0; i--)
  79             transforms[i].transform(result);
  80     }
  81 }