com.jme3.terrain.geomipmap
Class TerrainQuad

java.lang.Object
  extended by com.jme3.scene.Spatial
      extended by com.jme3.scene.Node
          extended by com.jme3.terrain.geomipmap.TerrainQuad
All Implemented Interfaces:
CloneableSmartAsset, Collidable, Savable, Terrain, java.lang.Cloneable
Direct Known Subclasses:
TerrainGrid

public class TerrainQuad
extends Node
implements Terrain

A terrain quad is a node in the quad tree of the terrain system. The root terrain quad will be the only one that receives the update() call every frame and it will determine if there has been any LOD change.

The leaves of the terrain quad tree are Terrain Patches. These have the real geometry mesh.

Heightmap coordinates start from the bottom left of the world and work towards the top right.

  +x
  ^
  | ......N = length of heightmap
  | :     :
  | :     :
  | 0.....:
  +---------> +z
 (world coordinates)
 


Nested Class Summary
protected  class TerrainQuad.LocationHeight
           
 
Nested classes/interfaces inherited from class com.jme3.scene.Spatial
Spatial.BatchHint, Spatial.CullHint
 
Field Summary
protected  NeighbourFinder neighbourFinder
           
protected  Vector2f offset
           
protected  float offsetAmount
           
protected  int patchSize
           
protected  int quadrant
           
protected  int size
           
protected  Vector3f stepScale
           
protected  int totalSize
           
 
Fields inherited from class com.jme3.scene.Node
children
 
Fields inherited from class com.jme3.scene.Spatial
batchHint, controls, cullHint, frustrumIntersects, key, localLights, localTransform, name, parent, queueBucket, queueDistance, refreshFlags, RF_BOUND, RF_LIGHTLIST, RF_TRANSFORM, shadowMode, userData, worldBound, worldLights, worldTransform
 
Constructor Summary
  TerrainQuad()
           
  TerrainQuad(java.lang.String name, int patchSize, int totalSize, float[] heightMap)
           
  TerrainQuad(java.lang.String name, int patchSize, int quadSize, int totalSize, float[] heightMap)
           
  TerrainQuad(java.lang.String name, int patchSize, int totalSize, int quadSize, Vector3f scale, float[] heightMap)
           
  TerrainQuad(java.lang.String name, int patchSize, int size, Vector3f scale, float[] heightMap)
           
protected TerrainQuad(java.lang.String name, int patchSize, int quadSize, Vector3f scale, float[] heightMap, int totalSize, Vector2f offset, float offsetAmount)
           
 
Method Summary
 void adjustHeight(java.util.List<Vector2f> xz, java.util.List<java.lang.Float> height)
          Raise/lower the height at many points.
 void adjustHeight(Vector2f xz, float delta)
          Raise/lower the height in one call (instead of getHeight then setHeight).
 void attachBoundChildren(Node parent)
          A handy method that will attach all bounding boxes of this terrain to the node you supply.
protected  void cacheTerrainTransforms()
          Caches the transforms (except rotation) so the LOD calculator, which runs on a separate thread, can access them safely.
protected  boolean calculateLod(java.util.List<Vector3f> location, java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updates, LodCalculator lodCalculator)
           
 TerrainQuad clone()
          Creates a clone of the asset.
 TerrainQuad clone(boolean cloneMaterials)
           
 int collideWith(Collidable other, CollisionResults results)
          Check collision with another Collidable.
 float[] createHeightSubBlock(float[] heightMap, int x, int y, int side)
           
protected  void createQuad(int blockSize, float[] heightMap)
          Quadrants, world coordinates, and heightmap coordinates (Y-up): -z -u | -v 1|3 -x ----+---- x 2|4 u | v z createQuad generates four new quads from this quad.
protected  void createQuadPatch(float[] heightMap)
          createQuadPatch creates four child patches from this quad.
protected  TerrainPatch findDownPatch(TerrainPatch tp)
           
protected  TerrainQuad findDownQuad()
           
protected  TerrainPatch findLeftPatch(TerrainPatch tp)
           
protected  TerrainQuad findLeftQuad()
           
protected  void findNeighboursLod(java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updated)
           
 void findPick(Ray toTest, java.util.List<TerrainPickData> results)
          Gather the terrain patches that intersect the given ray (toTest).
protected  TerrainPatch findRightPatch(TerrainPatch tp)
           
protected  TerrainQuad findRightQuad()
           
protected  TerrainPatch findTopPatch(TerrainPatch tp)
           
protected  TerrainQuad findTopQuad()
           
protected  void fixEdges(java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updated)
          Find any neighbours that should have their edges seamed because another neighbour changed its LOD to a greater value (less detailed)
protected  void fixNormalEdges(BoundingBox affectedArea)
          fix the normals on the edge of the terrain patches.
protected  void fixNormals(BoundingBox affectedArea)
          Find what terrain patches need normal recalculations and update their normals;
 void generateDebugTangents(Material mat)
           
 void generateEntropy(ProgressMonitor progressMonitor)
          Generate the entropy values for the terrain for the "perspective" LOD calculator.
 void getAllTerrainPatches(java.util.List<TerrainPatch> holder)
          Retrieve all Terrain Patches from all children and store them in the 'holder' list
 void getAllTerrainPatchesWithTranslation(java.util.Map<TerrainPatch,Vector3f> holder, Vector3f translation)
           
protected  float getHeight(int x, int z, float xm, float zm)
           
 float getHeight(Vector2f xz)
          Get the interpolated height of the terrain at the specified point.
 float[] getHeightMap()
          Get the heightmap of the entire terrain.
protected  float getHeightmapHeight(int x, int z)
          This will just get the heightmap value at the supplied point, not an interpolated (actual) height value.
 float getHeightmapHeight(Vector2f xz)
          Get the heightmap height at the specified X-Z coordinate.
 Material getMaterial()
          Returns the material that this terrain uses.
 Material getMaterial(Vector3f worldLocation)
          Returns the material that this terrain uses.
 int getMaxLod()
          This is calculated by the specific LOD algorithm.
protected  Vector3f getMeshNormal(int x, int z)
           
protected  Vector3f getNormal(float x, float z, Vector2f xz)
           
 Vector3f getNormal(Vector2f xz)
          Get the normal vector for the surface of the terrain at the specified X-Z coordinate.
 int getNumMajorSubdivisions()
           
protected  TerrainPatch getPatch(int quad)
           
 int getPatchSize()
           
protected  TerrainQuad getQuad(int quad)
           
 int getQuadrant()
           
 int getTerrainSize()
          Used for painting to get the number of vertices along the edge of the terrain.
 int getTotalSize()
           
protected  boolean isPointOnTerrain(int x, int z)
           
protected  boolean isRootQuad()
           
protected  boolean needToRecalculateNormals()
           
 void read(JmeImporter e)
           
 void recalculateAllNormals()
          Forces the recalculation of all normals on the terrain.
protected  void reIndexPages(java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updated, boolean usesVariableLod)
           
 void resetCachedNeighbours()
          Reset the cached references of neighbours.
protected  void setHeight(java.util.List<TerrainQuad.LocationHeight> locations, boolean overrideHeight)
           
 void setHeight(java.util.List<Vector2f> xz, java.util.List<java.lang.Float> height)
          Set the height at many points.
protected  void setHeight(java.util.List<Vector2f> xz, java.util.List<java.lang.Float> height, boolean overrideHeight)
           
 void setHeight(Vector2f xz, float height)
          Set the height at the specified X-Z coordinate.
 void setLocked(boolean locked)
          lock or unlock the meshes of this terrain.
protected  void setNeedToRecalculateNormals()
          This will cause all normals for this terrain quad to be recalculated
 void setNeighbourFinder(NeighbourFinder neighbourFinder)
           
protected  void setNormalRecalcNeeded(Vector2f changedPoint)
          Signal if the normal vectors for the terrain need to be recalculated.
 void setQuadrant(short quadrant)
           
protected  void split(int blockSize, float[] heightMap)
          split divides the heightmap data for four children.
protected  void updateNormals()
          update the normals if there were any height changes recently.
 void write(JmeExporter e)
           
 
Methods inherited from class com.jme3.scene.Node
attachChild, attachChildAt, breadthFirstTraversal, deepClone, depthFirstTraversal, descendantMatches, descendantMatches, descendantMatches, detachAllChildren, detachChild, detachChildAt, detachChildNamed, getChild, getChild, getChildIndex, getChildren, getQuantity, getTriangleCount, getVertexCount, hasChild, setLightListRefresh, setLodLevel, setMaterial, setModelBound, setTransformRefresh, swapChildren, updateGeometricState, updateLogicalState, updateModelBound, updateWorldBound
 
Methods inherited from class com.jme3.scene.Spatial
addControl, addLight, breadthFirstTraversal, center, checkCulling, getBatchHint, getControl, getControl, getCullHint, getKey, getLastFrustumIntersection, getLocalBatchHint, getLocalCullHint, getLocalLightList, getLocalQueueBucket, getLocalRotation, getLocalScale, getLocalShadowMode, getLocalToWorldMatrix, getLocalTransform, getLocalTranslation, getName, getNumControls, getParent, getQueueBucket, getShadowMode, getUserData, getUserDataKeys, getWorldBound, getWorldLightList, getWorldRotation, getWorldScale, getWorldTransform, getWorldTranslation, hasAncestor, localToWorld, lookAt, matches, move, move, removeControl, removeControl, removeFromParent, removeLight, rotate, rotate, rotateUpTo, runControlRender, scale, scale, setBatchHint, setBoundRefresh, setCullHint, setKey, setLastFrustumIntersection, setLocalRotation, setLocalRotation, setLocalScale, setLocalScale, setLocalScale, setLocalTransform, setLocalTranslation, setLocalTranslation, setName, setParent, setQueueBucket, setShadowMode, setUserData, toString, updateWorldLightList, updateWorldTransforms, worldToLocal
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

offset

protected Vector2f offset

totalSize

protected int totalSize

size

protected int size

patchSize

protected int patchSize

stepScale

protected Vector3f stepScale

offsetAmount

protected float offsetAmount

quadrant

protected int quadrant

neighbourFinder

protected NeighbourFinder neighbourFinder
Constructor Detail

TerrainQuad

public TerrainQuad()

TerrainQuad

public TerrainQuad(java.lang.String name,
                   int patchSize,
                   int totalSize,
                   float[] heightMap)
Parameters:
name - the name of the scene element. This is required for identification and comparison purposes.
patchSize - size of the individual patches
totalSize - the size of this entire terrain tree (on one side)
heightMap - The height map to generate the terrain from (a flat height map will be generated if this is null)

TerrainQuad

public TerrainQuad(java.lang.String name,
                   int patchSize,
                   int quadSize,
                   int totalSize,
                   float[] heightMap)
Parameters:
name - the name of the scene element. This is required for identification and comparison purposes.
patchSize - size of the individual patches
quadSize -
totalSize - the size of this entire terrain tree (on one side)
heightMap - The height map to generate the terrain from (a flat height map will be generated if this is null)

TerrainQuad

public TerrainQuad(java.lang.String name,
                   int patchSize,
                   int size,
                   Vector3f scale,
                   float[] heightMap)
Parameters:
name - the name of the scene element. This is required for identification and comparison purposes.
patchSize - size of the individual patches
size - size of this quad, can be between totalSize and patchSize
scale -
heightMap - The height map to generate the terrain from (a flat height map will be generated if this is null)

TerrainQuad

public TerrainQuad(java.lang.String name,
                   int patchSize,
                   int totalSize,
                   int quadSize,
                   Vector3f scale,
                   float[] heightMap)
Parameters:
name - the name of the scene element. This is required for identification and comparison purposes.
patchSize - size of the individual patches
totalSize - the size of this entire terrain tree (on one side)
quadSize -
scale -
heightMap - The height map to generate the terrain from (a flat height map will be generated if this is null)

TerrainQuad

protected TerrainQuad(java.lang.String name,
                      int patchSize,
                      int quadSize,
                      Vector3f scale,
                      float[] heightMap,
                      int totalSize,
                      Vector2f offset,
                      float offsetAmount)
Method Detail

setNeighbourFinder

public void setNeighbourFinder(NeighbourFinder neighbourFinder)

recalculateAllNormals

public void recalculateAllNormals()
Forces the recalculation of all normals on the terrain.


updateNormals

protected void updateNormals()
update the normals if there were any height changes recently. Should only be called on the root quad


cacheTerrainTransforms

protected void cacheTerrainTransforms()
Caches the transforms (except rotation) so the LOD calculator, which runs on a separate thread, can access them safely.


generateEntropy

public void generateEntropy(ProgressMonitor progressMonitor)
Generate the entropy values for the terrain for the "perspective" LOD calculator. This routine can take a long time to run!

Specified by:
generateEntropy in interface Terrain
Parameters:
progressMonitor - optional

isRootQuad

protected boolean isRootQuad()

getMaterial

public Material getMaterial()
Description copied from interface: Terrain
Returns the material that this terrain uses. If it uses many materials, just return the one you think is best. For TerrainQuads this is sufficient. For TerrainGrid you want to call getMaterial(Vector3f) instead.

Specified by:
getMaterial in interface Terrain

getMaterial

public Material getMaterial(Vector3f worldLocation)
Description copied from interface: Terrain
Returns the material that this terrain uses. Terrain can have different materials in different locations. In general, the TerrainQuad will only have one material. But TerrainGrid will have a different material per tile. It could be possible to pass in null for the location, some Terrain implementations might just have the one material and not care where you are looking. So implementations must handle null being supplied.

Specified by:
getMaterial in interface Terrain
Parameters:
worldLocation - the location, in world coordinates, of where we are interested in the underlying texture.

getNumMajorSubdivisions

public int getNumMajorSubdivisions()
Specified by:
getNumMajorSubdivisions in interface Terrain

calculateLod

protected boolean calculateLod(java.util.List<Vector3f> location,
                               java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updates,
                               LodCalculator lodCalculator)

findNeighboursLod

protected void findNeighboursLod(java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updated)

resetCachedNeighbours

public void resetCachedNeighbours()
Reset the cached references of neighbours. TerrainQuad caches neighbours for faster LOD checks. Sometimes you might want to reset this cache (for instance in TerrainGrid)


fixEdges

protected void fixEdges(java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updated)
Find any neighbours that should have their edges seamed because another neighbour changed its LOD to a greater value (less detailed)


reIndexPages

protected void reIndexPages(java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updated,
                            boolean usesVariableLod)

split

protected void split(int blockSize,
                     float[] heightMap)
split divides the heightmap data for four children. 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 patches are created, otherwise, quads are created.

Parameters:
blockSize - the blocks size to test against.
heightMap - the height data.

createQuad

protected void createQuad(int blockSize,
                          float[] heightMap)
Quadrants, world coordinates, and heightmap coordinates (Y-up): -z -u | -v 1|3 -x ----+---- x 2|4 u | v z createQuad 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.


generateDebugTangents

public void generateDebugTangents(Material mat)

createQuadPatch

protected void createQuadPatch(float[] heightMap)
createQuadPatch creates four child patches from this quad.


createHeightSubBlock

public float[] createHeightSubBlock(float[] heightMap,
                                    int x,
                                    int y,
                                    int side)

attachBoundChildren

public void attachBoundChildren(Node parent)
A handy method that will attach all bounding boxes of this terrain to the node you supply. Useful to visualize the bounding boxes when debugging.

Parameters:
parent - that will get the bounding box shapes of the terrain attached to

setNormalRecalcNeeded

protected void setNormalRecalcNeeded(Vector2f changedPoint)
Signal if the normal vectors for the terrain need to be recalculated. Does this by looking at the affectedAreaBBox bounding box. If the bbox exists already, then it will grow the box to fit the new changedPoint. If the affectedAreaBBox is null, then it will create one of unit size.

Parameters:
needToRecalculateNormals - if null, will cause needToRecalculateNormals() to return false

needToRecalculateNormals

protected boolean needToRecalculateNormals()

setNeedToRecalculateNormals

protected void setNeedToRecalculateNormals()
This will cause all normals for this terrain quad to be recalculated


getHeightmapHeight

public float getHeightmapHeight(Vector2f xz)
Description copied from interface: Terrain
Get the heightmap height at the specified X-Z coordinate. This does not count scaling and snaps the XZ coordinate to the nearest (rounded) heightmap grid point.

Specified by:
getHeightmapHeight in interface Terrain
Parameters:
xz - world coordinate
Returns:
the height, unscaled and uninterpolated

getHeightmapHeight

protected float getHeightmapHeight(int x,
                                   int z)
This will just get the heightmap value at the supplied point, not an interpolated (actual) height value.


getMeshNormal

protected Vector3f getMeshNormal(int x,
                                 int z)

getHeight

public float getHeight(Vector2f xz)
Get the interpolated height of the terrain at the specified point.

Specified by:
getHeight in interface Terrain
Parameters:
xz - the location to get the height for
Returns:
Float.NAN if the value does not exist, or the coordinates are outside of the terrain

getHeight

protected float getHeight(int x,
                          int z,
                          float xm,
                          float zm)

getNormal

public Vector3f getNormal(Vector2f xz)
Description copied from interface: Terrain
Get the normal vector for the surface of the terrain at the specified X-Z coordinate. This normal vector can be a close approximation. It does not take into account any normal maps on the material.

Specified by:
getNormal in interface Terrain
Parameters:
xz - the X-Z world coordinate
Returns:
the normal vector at the given point

getNormal

protected Vector3f getNormal(float x,
                             float z,
                             Vector2f xz)

setHeight

public void setHeight(Vector2f xz,
                      float height)
Description copied from interface: Terrain
Set the height at the specified X-Z coordinate. To set the height of the terrain and see it, you will have to unlock the terrain meshes by calling terrain.setLocked(false) before you call setHeight().

Specified by:
setHeight in interface Terrain
Parameters:
xz - coordinate to set the height
height - that will be set at the coordinate

adjustHeight

public void adjustHeight(Vector2f xz,
                         float delta)
Description copied from interface: Terrain
Raise/lower the height in one call (instead of getHeight then setHeight).

Specified by:
adjustHeight in interface Terrain
Parameters:
xz - world coordinate to adjust the terrain height
delta - +- value to adjust the height by

setHeight

public void setHeight(java.util.List<Vector2f> xz,
                      java.util.List<java.lang.Float> height)
Description copied from interface: Terrain
Set the height at many points. The two lists must be the same size. Each xz coordinate entry matches to a height entry, 1 for 1. So the first coordinate matches to the first height value, the last to the last etc.

Specified by:
setHeight in interface Terrain
Parameters:
xz - a list of coordinates where the hight will be set
height - the heights that match the xz coordinates

adjustHeight

public void adjustHeight(java.util.List<Vector2f> xz,
                         java.util.List<java.lang.Float> height)
Description copied from interface: Terrain
Raise/lower the height at many points. The two lists must be the same size. Each xz coordinate entry matches to a height entry, 1 for 1. So the first coordinate matches to the first height value, the last to the last etc.

Specified by:
adjustHeight in interface Terrain
Parameters:
xz - a list of coordinates where the hight will be adjusted
height - +- value to adjust the height by, that matches the xz coordinates

setHeight

protected void setHeight(java.util.List<Vector2f> xz,
                         java.util.List<java.lang.Float> height,
                         boolean overrideHeight)

setHeight

protected void setHeight(java.util.List<TerrainQuad.LocationHeight> locations,
                         boolean overrideHeight)

isPointOnTerrain

protected boolean isPointOnTerrain(int x,
                                   int z)

getTerrainSize

public int getTerrainSize()
Description copied from interface: Terrain
Used for painting to get the number of vertices along the edge of the terrain. This is an un-scaled size, and should represent the vertex count (ie. the texture coord count) along an edge of a square terrain. In the standard TerrainQuad default implementation, this will return the "totalSize" of the terrain (512 or so).

Specified by:
getTerrainSize in interface Terrain

setLocked

public void setLocked(boolean locked)
lock or unlock the meshes of this terrain. Locked meshes are uneditable but have better performance.

Specified by:
setLocked in interface Terrain
Parameters:
locked - or unlocked

getQuadrant

public int getQuadrant()

setQuadrant

public void setQuadrant(short quadrant)

getPatch

protected TerrainPatch getPatch(int quad)

getQuad

protected TerrainQuad getQuad(int quad)

findRightPatch

protected TerrainPatch findRightPatch(TerrainPatch tp)

findDownPatch

protected TerrainPatch findDownPatch(TerrainPatch tp)

findTopPatch

protected TerrainPatch findTopPatch(TerrainPatch tp)

findLeftPatch

protected TerrainPatch findLeftPatch(TerrainPatch tp)

findRightQuad

protected TerrainQuad findRightQuad()

findDownQuad

protected TerrainQuad findDownQuad()

findTopQuad

protected TerrainQuad findTopQuad()

findLeftQuad

protected TerrainQuad findLeftQuad()

fixNormals

protected void fixNormals(BoundingBox affectedArea)
Find what terrain patches need normal recalculations and update their normals;


fixNormalEdges

protected void fixNormalEdges(BoundingBox affectedArea)
fix the normals on the edge of the terrain patches.


collideWith

public int collideWith(Collidable other,
                       CollisionResults results)
Description copied from interface: Collidable
Check collision with another Collidable.

Specified by:
collideWith in interface Collidable
Overrides:
collideWith in class Node
Parameters:
other - The object to check collision against
results - Will contain the list of CollisionResults.
Returns:
how many collisions were found between this and other

findPick

public void findPick(Ray toTest,
                     java.util.List<TerrainPickData> results)
Gather the terrain patches that intersect the given ray (toTest). This only tests the bounding boxes

Parameters:
toTest -
results -

getAllTerrainPatches

public void getAllTerrainPatches(java.util.List<TerrainPatch> holder)
Retrieve all Terrain Patches from all children and store them in the 'holder' list

Parameters:
holder - must not be null, will be populated when returns

getAllTerrainPatchesWithTranslation

public void getAllTerrainPatchesWithTranslation(java.util.Map<TerrainPatch,Vector3f> holder,
                                                Vector3f translation)

read

public void read(JmeImporter e)
          throws java.io.IOException
Specified by:
read in interface Savable
Overrides:
read in class Node
Throws:
java.io.IOException

write

public void write(JmeExporter e)
           throws java.io.IOException
Specified by:
write in interface Savable
Overrides:
write in class Node
Throws:
java.io.IOException

clone

public TerrainQuad clone()
Description copied from interface: CloneableSmartAsset
Creates a clone of the asset. Please see Object.clone() for more info on how this method should be implemented.

Specified by:
clone in interface CloneableSmartAsset
Overrides:
clone in class Spatial
Returns:
A clone of this Spatial, the scene graph in its entirety is cloned and can be altered independently of the original scene graph. Note that meshes of geometries are not cloned explicitly, they are shared if static, or specially cloned if animated. All controls will be cloned using the Control.cloneForSpatial method on the clone.
See Also:
Mesh.cloneForAnim()

clone

public TerrainQuad clone(boolean cloneMaterials)
Overrides:
clone in class Node
Returns:
A clone of this Spatial, the scene graph in its entirety is cloned and can be altered independently of the original scene graph. Note that meshes of geometries are not cloned explicitly, they are shared if static, or specially cloned if animated. All controls will be cloned using the Control.cloneForSpatial method on the clone.
See Also:
Mesh.cloneForAnim()

getMaxLod

public int getMaxLod()
Description copied from interface: Terrain
This is calculated by the specific LOD algorithm. A value of one means that the terrain is showing full detail. The higher the value, the more the terrain has been generalized and the less detailed it will be.

Specified by:
getMaxLod in interface Terrain

getPatchSize

public int getPatchSize()

getTotalSize

public int getTotalSize()

getHeightMap

public float[] getHeightMap()
Description copied from interface: Terrain
Get the heightmap of the entire terrain. This can return null if that terrain object does not store the height data. Infinite or "paged" terrains will not be able to support this, so use with caution.

Specified by:
getHeightMap in interface Terrain