* javadoc

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

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

@@ -70,7 +70,7 @@ import java.util.List;
 /**
  * A terrain patch is a leaf in the terrain quad tree. It has a mesh that can change levels of detail (LOD)
  * whenever the view point, or camera, changes. The actual terrain mesh is created by the LODGeomap class.
- * That uses a geo mip mapping algorithm to change the index buffer of the mesh.
+ * That uses a geo-mipmapping algorithm to change the index buffer of the mesh.
  * The mesh is a triangle strip. In wireframe mode you might notice some strange lines, these are degenerate
  * triangles generated by the geoMipMap algorithm and can be ignored. The video card removes them at almost no cost.
  * 
@@ -104,10 +104,10 @@ public class TerrainPatch extends Geometry {
     // x/z step
     protected Vector3f stepScale;
 
-    // center of the block in relation to (0,0,0)
+    // center of the patch in relation to (0,0,0)
     protected Vector2f offset;
 
-    // amount the block has been shifted.
+    // amount the patch has been shifted.
     protected float offsetAmount;
 
     protected LodCalculator lodCalculator;
@@ -137,7 +137,7 @@ public class TerrainPatch extends Geometry {
      * <code>TriMesh</code> object for rendering.
      *
      * @param name
-     *			the name of the terrain block.
+     *			the name of the terrain patch.
      * @param size
      *			the size of the heightmap.
      * @param stepScale
@@ -145,7 +145,7 @@ public class TerrainPatch extends Geometry {
      * @param heightMap
      *			the height data.
      * @param origin
-     *			the origin offset of the block.
+     *			the origin offset of the patch.
      */
     public TerrainPatch(String name, int size, Vector3f stepScale,
                     float[] heightMap, Vector3f origin) {
@@ -158,18 +158,18 @@ public class TerrainPatch extends Geometry {
      * <code>TriMesh</code> object for renderering.
      *
      * @param name
-     *			the name of the terrain block.
+     *			the name of the terrain patch.
      * @param size
-     *			the size of the block.
+     *			the size of the patch.
      * @param stepScale
      *			the scale for the axes.
      * @param heightMap
      *			the height data.
      * @param origin
-     *			the origin offset of the block.
+     *			the origin offset of the patch.
      * @param totalSize
-     *			the total size of the terrain. (Higher if the block is part of
-     *			a <code>TerrainPage</code> tree.
+     *			the total size of the terrain. (Higher if the patch is part of
+     *			a <code>TerrainQuad</code> tree.
      * @param offset
      *			the offset for texture coordinates.
      * @param offsetAmount
@@ -765,7 +765,7 @@ public class TerrainPatch extends Geometry {
     }
 	
     /**
-     * Returns the offset amount this terrain block uses for textures.
+     * Returns the offset amount this terrain patch uses for textures.
      *
      * @return The current offset amount.
      */
@@ -792,9 +792,9 @@ public class TerrainPatch extends Geometry {
     }
 
     /**
-     * Returns the size of this terrain block.
+     * Returns the size of this terrain patch.
      *
-     * @return The current block size.
+     * @return The current patch size.
      */
     public int getSize() {
         return size;
@@ -813,7 +813,7 @@ public class TerrainPatch extends Geometry {
     /**
      * Sets the value for the current offset amount to use when building texture
      * coordinates. Note that this does <b>NOT </b> rebuild the terrain at all.
-     * This is mostly used for outside constructors of terrain blocks.
+     * This is mostly used for outside constructors of terrain patches.
      *
      * @param offset
      *			The new texture offset.
@@ -823,9 +823,9 @@ public class TerrainPatch extends Geometry {
     }
 
     /**
-     * Sets the size of this terrain block. Note that this does <b>NOT </b>
+     * Sets the size of this terrain patch. Note that this does <b>NOT </b>
      * rebuild the terrain at all. This is mostly used for outside constructors
-     * of terrain blocks.
+     * of terrain patches.
      *
      * @param size
      *			The new size.
@@ -839,7 +839,7 @@ public class TerrainPatch extends Geometry {
     /**
      * Sets the total size of the terrain . Note that this does <b>NOT </b>
      * rebuild the terrain at all. This is mostly used for outside constructors
-     * of terrain blocks.
+     * of terrain patches.
      *
      * @param totalSize
      *			The new total size.
@@ -849,9 +849,9 @@ public class TerrainPatch extends Geometry {
     }
 
     /**
-     * Sets the step scale of this terrain block's height map. Note that this
+     * Sets the step scale of this terrain patch's height map. Note that this
      * does <b>NOT </b> rebuild the terrain at all. This is mostly used for
-     * outside constructors of terrain blocks.
+     * outside constructors of terrain patches.
      *
      * @param stepScale
      *			The new step scale.
@@ -863,7 +863,7 @@ public class TerrainPatch extends Geometry {
     /**
      * Sets the offset of this terrain texture map. Note that this does <b>NOT
      * </b> rebuild the terrain at all. This is mostly used for outside
-     * constructors of terrain blocks.
+     * constructors of terrain patches.
      *
      * @param offsetAmount
      *			The new texture offset.

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

@@ -138,7 +138,7 @@ public class TerrainQuad extends Node implements Terrain {
     }
 
     protected TerrainQuad(String name, int patchSize, int size,
-                            Vector3f stepScale, float[] heightMap, int totalSize,
+                            Vector3f scale, float[] heightMap, int totalSize,
                             Vector2f offset, float offsetAmount,
                             LodCalculatorFactory lodCalculatorFactory)
     {
@@ -155,7 +155,7 @@ public class TerrainQuad extends Node implements Terrain {
         this.totalSize = totalSize;
         this.size = size;
         this.patchSize = patchSize;
-        this.stepScale = stepScale;
+        this.stepScale = scale;
         this.lodCalculatorFactory = lodCalculatorFactory;
         split(patchSize, heightMap);
     }
@@ -549,9 +549,9 @@ public class TerrainQuad extends Node implements Terrain {
 
     /**
      * <code>split</code> divides the heightmap data for four children. The
-     * children are either pages or blocks. This is dependent on the size of the
+     * children are either quads or patches. This is dependent on the size of the
      * children. If the child's size is less than or equal to the set block
-     * size, then blocks are created, otherwise, pages are created.
+     * size, then patches are created, otherwise, quads are created.
      *
      * @param blockSize
      *			the blocks size to test against.
@@ -568,10 +568,20 @@ public class TerrainQuad extends Node implements Terrain {
     }
 
     /**
-     * <code>createQuadPage</code> generates four new pages from this page.
+     * Quadrants, world coordinates, and heightmap coordinates (Y-up):
+     *         x
+     *         | u
+     *        2|4 v
+     *  -z ----+---- z
+     *     -v 1|3
+     *      -u |
+     *        -x
+     * <code>createQuad</code> generates four new quads from this quad.
+     * The heightmap's top left (0,0) coordinate is at the bottom, -x,-z
+     * coordinate of the terrain, so it grows in the positive x.z direction.
      */
     protected void createQuad(int blockSize, float[] heightMap) {
-        // create 4 terrain pages
+        // create 4 terrain quads
         int quarterSize = size >> 2;
 
         int split = (size + 1) >> 1;
@@ -582,7 +592,7 @@ public class TerrainQuad extends Node implements Terrain {
         if (lodCalculatorFactory == null)
             lodCalculatorFactory = new LodDistanceCalculatorFactory(); // set a default one
 
-        // 1 upper left
+        // 1 upper left of heightmap, lower left quad
         float[] heightBlock1 = createHeightSubBlock(heightMap, 0, 0, split);
 
         Vector3f origin1 = new Vector3f(-quarterSize * stepScale.x, 0,
@@ -593,14 +603,14 @@ public class TerrainQuad extends Node implements Terrain {
         tempOffset.x += origin1.x;
         tempOffset.y += origin1.z;
 
-        TerrainQuad page1 = new TerrainQuad(getName() + "Quad1", blockSize,
+        TerrainQuad quad1 = new TerrainQuad(getName() + "Quad1", blockSize,
                         split, stepScale, heightBlock1, totalSize, tempOffset,
                         offsetAmount, lodCalculatorFactory);
-        page1.setLocalTranslation(origin1);
-        page1.quadrant = 1;
-        this.attachChild(page1);
+        quad1.setLocalTranslation(origin1);
+        quad1.quadrant = 1;
+        this.attachChild(quad1);
 
-        // 2 lower left
+        // 2 lower left of heightmap, upper left quad
         float[] heightBlock2 = createHeightSubBlock(heightMap, 0, split - 1,
                         split);
 
@@ -613,14 +623,14 @@ public class TerrainQuad extends Node implements Terrain {
         tempOffset.x += origin2.x;
         tempOffset.y += origin2.z;
 
-        TerrainQuad page2 = new TerrainQuad(getName() + "Quad2", blockSize,
+        TerrainQuad quad2 = new TerrainQuad(getName() + "Quad2", blockSize,
                         split, stepScale, heightBlock2, totalSize, tempOffset,
                         offsetAmount, lodCalculatorFactory);
-        page2.setLocalTranslation(origin2);
-        page2.quadrant = 2;
-        this.attachChild(page2);
+        quad2.setLocalTranslation(origin2);
+        quad2.quadrant = 2;
+        this.attachChild(quad2);
 
-        // 3 upper right
+        // 3 upper right of heightmap, lower right quad
         float[] heightBlock3 = createHeightSubBlock(heightMap, split - 1, 0,
                         split);
 
@@ -633,14 +643,14 @@ public class TerrainQuad extends Node implements Terrain {
         tempOffset.x += origin3.x;
         tempOffset.y += origin3.z;
 
-        TerrainQuad page3 = new TerrainQuad(getName() + "Quad3", blockSize,
+        TerrainQuad quad3 = new TerrainQuad(getName() + "Quad3", blockSize,
                         split, stepScale, heightBlock3, totalSize, tempOffset,
                         offsetAmount, lodCalculatorFactory);
-        page3.setLocalTranslation(origin3);
-        page3.quadrant = 3;
-        this.attachChild(page3);
-        // //
-        // 4 lower right
+        quad3.setLocalTranslation(origin3);
+        quad3.quadrant = 3;
+        this.attachChild(quad3);
+        
+        // 4 lower right of heightmap, upper right quad
         float[] heightBlock4 = createHeightSubBlock(heightMap, split - 1,
                         split - 1, split);
 
@@ -653,12 +663,12 @@ public class TerrainQuad extends Node implements Terrain {
         tempOffset.x += origin4.x;
         tempOffset.y += origin4.z;
 
-        TerrainQuad page4 = new TerrainQuad(getName() + "Quad4", blockSize,
+        TerrainQuad quad4 = new TerrainQuad(getName() + "Quad4", blockSize,
                         split, stepScale, heightBlock4, totalSize, tempOffset,
                         offsetAmount, lodCalculatorFactory);
-        page4.setLocalTranslation(origin4);
-        page4.quadrant = 4;
-        this.attachChild(page4);
+        quad4.setLocalTranslation(origin4);
+        quad4.quadrant = 4;
+        this.attachChild(quad4);
 
     }
 
@@ -679,10 +689,10 @@ public class TerrainQuad extends Node implements Terrain {
     }
 
     /**
-     * <code>createQuadBlock</code> creates four child blocks from this page.
+     * <code>createQuadPatch</code> creates four child patches from this quad.
      */
     protected void createQuadPatch(float[] heightMap) {
-        // create 4 terrain blocks
+        // create 4 terrain patches
         int quarterSize = size >> 2;
         int halfSize = size >> 1;
         int split = (size + 1) >> 1;
@@ -1183,12 +1193,12 @@ public class TerrainQuad extends Node implements Terrain {
         else if (tp.getQuadrant() == 2)
             return getPatch(4);
         else if (tp.getQuadrant() == 3) {
-            // find the page to the right and ask it for child 1.
+            // find the patch to the right and ask it for child 1.
             TerrainQuad quad = findRightQuad();
             if (quad != null)
                 return quad.getPatch(1);
         } else if (tp.getQuadrant() == 4) {
-            // find the page to the right and ask it for child 2.
+            // find the patch to the right and ask it for child 2.
             TerrainQuad quad = findRightQuad();
             if (quad != null)
                 return quad.getPatch(2);
@@ -1203,7 +1213,7 @@ public class TerrainQuad extends Node implements Terrain {
         else if (tp.getQuadrant() == 3)
             return getPatch(4);
         else if (tp.getQuadrant() == 2) {
-            // find the page below and ask it for child 1.
+            // find the patch below and ask it for child 1.
             TerrainQuad quad = findDownQuad();
             if (quad != null)
                 return quad.getPatch(1);
@@ -1223,7 +1233,7 @@ public class TerrainQuad extends Node implements Terrain {
         else if (tp.getQuadrant() == 4)
             return getPatch(3);
         else if (tp.getQuadrant() == 1) {
-            // find the page above and ask it for child 2.
+            // find the patch above and ask it for child 2.
             TerrainQuad quad = findTopQuad();
             if (quad != null)
                 return quad.getPatch(2);
@@ -1242,7 +1252,7 @@ public class TerrainQuad extends Node implements Terrain {
         else if (tp.getQuadrant() == 4)
             return getPatch(2);
         else if (tp.getQuadrant() == 1) {
-            // find the page above and ask it for child 2.
+            // find the patch above and ask it for child 2.
             TerrainQuad quad = findLeftQuad();
             if (quad != null)
                 return quad.getPatch(3);
@@ -1303,7 +1313,7 @@ public class TerrainQuad extends Node implements Terrain {
 
     protected TerrainQuad findTopQuad() {
         if (getParent() == null || !(getParent() instanceof TerrainQuad))
-                return null;
+            return null;
 
         TerrainQuad pQuad = (TerrainQuad) getParent();
 
@@ -1326,7 +1336,7 @@ public class TerrainQuad extends Node implements Terrain {
 
     protected TerrainQuad findLeftQuad() {
         if (getParent() == null || !(getParent() instanceof TerrainQuad))
-                return null;
+            return null;
 
         TerrainQuad pQuad = (TerrainQuad) getParent();