TerrainGrid javadoc

git-svn-id: https://jmonkeyengine.googlecode.com/svn/trunk@8675 75d07b2b-3a1a-0410-a2c5-0572b91ccdca

engine/src/terrain/com/jme3/terrain/geomipmap/TerrainGrid.java

@@ -50,11 +50,48 @@ import com.jme3.terrain.heightmap.HeightMapGrid;
 import java.util.concurrent.Callable;
 
 /**
+ * TerrainGrid itself is an actual TerrainQuad. Its four children are the visible four tiles.
  * 
  * The grid is indexed by cells. Each cell has an integer XZ coordinate originating at 0,0.
  * TerrainGrid will piggyback on the TerrainLodControl so it can use the camera for its
  * updates as well. It does this in the overwritten update() method.
  * 
+ * It uses an LRU (Least Recently Used) cache of 16 terrain tiles (full TerrainQuadTrees). The
+ * center 4 are the ones that are visible. As the camera moves, it checks what camera cell it is in
+ * and will attach the now visible tiles.
+ * 
+ * The 'quadIndex' variable is a 4x4 array that represents the tiles. The center 
+ * four (index numbers: 5, 6, 9, 10) are what is visible. Each quadIndex value is an
+ * offset vector. The vector contains whole numbers and represents how many tiles in offset
+ * this location is from the center of the map. So for example the index 11 [Vector3f(2, 0, 1)]
+ * is located 2*terrainSize in X axis and 1*terrainSize in Z axis.
+ * 
+ * As the camera moves, it tests what cameraCell it is in. Each camera cell covers four quad tiles
+ * and is half way inside each one.
+ * 
+ * +-------+-------+
+ * | 1     |     4 |    Four terrainQuads that make up the grid
+ * |    *..|..*    |    with the cameraCell in the middle, covering
+ * |----|--|--|----|    all four quads.
+ * |    *..|..*    |
+ * | 2     |     3 |
+ * +-------+-------+
+ * 
+ * This results in the effect of when the camera gets half way across one of the sides of a quad to
+ * an empty (non-loaded) area, it will trigger the system to load in the next tiles.
+ * 
+ * The tile loading is done on a background thread, and once the tile is loaded, then it is
+ * attached to the qrid quad tree, back on the OGL thread. It will grab the terrain quad from
+ * the LRU cache if it exists. If it does not exist, it will load in the new TerrainQuad tile.
+ * 
+ * The loading of new tiles triggers events for any TerrainGridListeners. The events are:
+ *  -tile Attached
+ *  -tile Detached
+ *  -grid moved.
+ * 
+ * These allow physics to update, and other operation (often needed for loading the terrain) to occur
+ * at the right time.
+ * 
  * @author Anthyon
  */
 public class TerrainGrid extends TerrainQuad {