com.jmex.terrain
Class TerrainPage

java.lang.Object
  extended by com.jme.scene.Spatial
      extended by com.jme.scene.Node
          extended by com.jmex.terrain.TerrainPage
All Implemented Interfaces:
Savable, java.io.Serializable

public class TerrainPage
extends Node

TerrainPage is used to build a quad tree of terrain blocks. The TerrainPage will have four children, either four pages or four blocks. The size of the page must be (2^N + 1), to allow for even splitting of the blocks. Organization of the page into a quad tree allows for very fast culling of the terrain. The total size of the heightmap is provided, as well as the desired end size for a block. Appropriate values for the end block size is completely dependent on the application. In some cases, a large size will give performance gains, in others, a small size is the best option. It is recommended that different combinations are tried.

Author:
Mark Powell, Joshua Slack
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class com.jme.scene.Spatial
Spatial.CullHint, Spatial.LightCombineMode, Spatial.NormalsMode, Spatial.TextureCombineMode
 
Field Summary
 
Fields inherited from class com.jme.scene.Node
children
 
Fields inherited from class com.jme.scene.Spatial
cullHint, frustrumIntersects, geometricalControllers, isCollidable, lightCombineMode, localRotation, localScale, localTranslation, LOCKED_BOUNDS, LOCKED_BRANCH, LOCKED_MESH_DATA, LOCKED_NONE, LOCKED_SHADOWS, LOCKED_TRANSFORMS, lockedMode, name, normalsMode, parent, queueDistance, renderQueueMode, renderStateList, textureCombineMode, worldBound, worldRotation, worldScale, worldTranslation, zOrder
 
Constructor Summary
  TerrainPage()
          Empty Constructor to be used internally only.
  TerrainPage(java.lang.String name)
          Creates a TerrainPage to be filled later.
  TerrainPage(java.lang.String name, int blockSize, int size, Vector3f stepScale, float[] heightMap)
          Constructor instantiates a new TerrainPage object.
protected TerrainPage(java.lang.String name, int blockSize, int size, Vector3f stepScale, float[] heightMap, int totalSize, Vector2f offset, float offsetAmount)
          Constructor instantiates a new TerrainPage object.
 
Method Summary
 void addHeightMapValue(int x, int y, float toAdd)
          addHeightMapValue adds to the value of this block's height map at the given coords
static float[] createHeightSubBlock(float[] heightMap, int x, int y, int side)
           
 void fixNormals()
           
 float getHeight(float x, float z)
          getHeight returns the height of an arbitrary point on the terrain.
 float getHeight(Vector2f position)
          getHeight returns the height of an arbitrary point on the terrain.
 float getHeight(Vector3f position)
          getHeight returns the height of an arbitrary point on the terrain.
 float getHeightFromWorld(Vector3f position)
          getHeightFromWorld returns the height of an arbitrary point on the terrain when given world coordinates.
 Vector2f getOffset()
          Returns the current offset amount.
 float getOffsetAmount()
          Returns the offset amount this terrain block uses for textures.
 short getQuadrant()
           
 int getSize()
          Returns the size of this terrain page.
 Vector3f getStepScale()
          Returns the step scale that stretches the height map.
 Vector3f getSurfaceNormal(float x, float z, Vector3f store)
          getSurfaceNormal returns the normal of an arbitrary point on the terrain.
 Vector3f getSurfaceNormal(Vector2f position, Vector3f store)
          getSurfaceNormal returns the normal of an arbitrary point on the terrain.
 Vector3f getSurfaceNormal(Vector3f position, Vector3f store)
          getSurfaceNormal returns the normal of an arbitrary point on the terrain.
 int getTotalSize()
          Returns the total size of the terrain.
 void multHeightMapValue(int x, int y, float toMult)
          multHeightMapValue multiplies the value of this block's height map at the given coords by the value given.
 void read(JMEImporter e)
           
 void setDetailTexture(int unit, int repeat)
          setDetailTexture sets the detail texture coordinates to be applied on top of the normal terrain texture.
 void setHeightMapValue(int x, int y, float newVal)
          setHeightMapValue sets the value of this block's height map at the given coords
 void setModelBound(BoundingVolume v)
          setModelBound sets the model bounds for the terrain blocks.
 void setOffset(Vector2f offset)
          Sets the value for the current offset amount to use when building texture coordinates.
 void setOffsetAmount(float offsetAmount)
          Sets the offset of this terrain texture map.
 void setQuadrant(short quadrant)
           
 void setSize(int size)
          Sets the size of this terrain page.
 void setStepScale(Vector3f stepScale)
          Sets the step scale of this terrain page's height map.
 void setTotalSize(int totalSize)
          Sets the total size of the terrain .
 void updateFromHeightMap()
          updateFromHeightMap updates the verts of all sub blocks from the contents of their heightmaps.
 void updateModelBound()
          updateModelBound updates the model bounds (generates the bounds from the current vertices).
 void write(JMEExporter e)
           
 
Methods inherited from class com.jme.scene.Node
applyRenderState, attachChild, attachChildAt, childChange, detachAllChildren, detachChild, detachChildAt, detachChildNamed, draw, findCollisions, findPick, getChild, getChild, getChildIndex, getChildren, getQuantity, getTriangleCount, getVertexCount, hasChild, hasCollision, lockBounds, lockMeshes, lockShadows, lockTransforms, sortLights, swapChildren, unlockBounds, unlockMeshes, unlockShadows, unlockTransforms, updateWorldBound, updateWorldData, updateWorldVectors
 
Methods inherited from class com.jme.scene.Spatial
addController, calculateCollisions, calculatePick, clearControllers, clearRenderState, clearRenderState, getClassTag, getController, getControllerCount, getControllers, getCullHint, getLastFrustumIntersection, getLightCombineMode, getLocalCullHint, getLocalLightCombineMode, getLocalNormalsMode, getLocalRenderQueueMode, getLocalRotation, getLocalScale, getLocalTextureCombineMode, getLocalToWorldMatrix, getLocalTranslation, getLocks, getName, getNormalsMode, getParent, getRenderQueueMode, getRenderState, getRenderState, getTextureCombineMode, getUserData, getWorldBound, getWorldRotation, getWorldScale, getWorldTranslation, getZOrder, hasAncestor, isCollidable, localToWorld, lock, lock, lockBranch, lockMeshes, lookAt, onDraw, propagateBoundToRoot, propagateStatesFromRoot, removeController, removeController, removeFromParent, removeUserData, rotateUpTo, setCullHint, setIsCollidable, setLastFrustumIntersection, setLightCombineMode, setLocalRotation, setLocalRotation, setLocalScale, setLocalScale, setLocalTranslation, setLocalTranslation, setLocks, setLocks, setName, setNormalsMode, setParent, setRenderQueueMode, setRenderState, setTextureCombineMode, setUserData, setZOrder, setZOrder, toString, unlock, unlock, unlockBranch, unlockMeshes, updateGeometricState, updateRenderState, updateRenderState, updateWorldRotation, updateWorldScale, updateWorldTranslation, updateWorldVectors, worldToLocal
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.jme.util.export.Savable
getClassTag
 

Constructor Detail

TerrainPage

public TerrainPage()
Empty Constructor to be used internally only.


TerrainPage

public TerrainPage(java.lang.String name)
Creates a TerrainPage to be filled later. Usually, users don't want to call this function unless they have a terrain page already built.

Parameters:
name - The name of the page node.

TerrainPage

public TerrainPage(java.lang.String name,
                   int blockSize,
                   int size,
                   Vector3f stepScale,
                   float[] heightMap)
Constructor instantiates a new TerrainPage object. The data is then split into either 4 new TerrainPages or 4 new TerrainBlock.

Parameters:
name - the name of the page.
blockSize - the size of the leaf nodes. This is used to determine if four new TerrainPage objects should be the child or four new TerrainBlock objects.
size - the size of the heightmap for this page.
stepScale - the scale of the axes.
heightMap - the height data.

TerrainPage

protected TerrainPage(java.lang.String name,
                      int blockSize,
                      int size,
                      Vector3f stepScale,
                      float[] heightMap,
                      int totalSize,
                      Vector2f offset,
                      float offsetAmount)
Constructor instantiates a new TerrainPage object. The data is then split into either 4 new TerrainPages or 4 new TerrainBlock.

Parameters:
name - the name of the page.
blockSize - the size of the leaf nodes. This is used to determine if four new TerrainPage objects should be the child or four new TerrainBlock objects.
size - the size of the heightmap for this page.
stepScale - the scale of the axes.
heightMap - the height data.
totalSize - the total terrain size, used if the page is an internal node of a terrain system.
offset - the texture offset for the page.
offsetAmount - the amount of the offset.
Method Detail

setDetailTexture

public void setDetailTexture(int unit,
                             int repeat)
setDetailTexture sets the detail texture coordinates to be applied on top of the normal terrain texture.

Parameters:
unit - the texture unit to set the coordinates.
repeat - the number of tiling for the texture.

setModelBound

public void setModelBound(BoundingVolume v)
setModelBound sets the model bounds for the terrain blocks.

Overrides:
setModelBound in class Node
Parameters:
v - the bounding volume to set for the terrain blocks.

updateModelBound

public void updateModelBound()
updateModelBound updates the model bounds (generates the bounds from the current vertices).

Overrides:
updateModelBound in class Node

updateFromHeightMap

public void updateFromHeightMap()
updateFromHeightMap updates the verts of all sub blocks from the contents of their heightmaps.


getHeight

public float getHeight(Vector2f position)
getHeight returns the height of an arbitrary point on the terrain. If the point is between height point values, the height is linearly interpolated. This provides smooth height calculations. If the point provided is not within the bounds of the height map, the NaN float value is returned (Float.NaN).

Parameters:
position - the vector representing the height location to check.
Returns:
the height at the provided location.

getHeight

public float getHeight(Vector3f position)
getHeight returns the height of an arbitrary point on the terrain. If the point is between height point values, the height is linearly interpolated. This provides smooth height calculations. If the point provided is not within the bounds of the height map, the NaN float value is returned (Float.NaN).

Parameters:
position - the vector representing the height location to check. Only the x and z values are used.
Returns:
the height at the provided location.

getHeight

public float getHeight(float x,
                       float z)
getHeight returns the height of an arbitrary point on the terrain. If the point is between height point values, the height is linearly interpolated. This provides smooth height calculations. If the point provided is not within the bounds of the height map, the NaN float value is returned (Float.NaN).

Parameters:
x - the x coordinate to check.
z - the z coordinate to check.
Returns:
the height at the provided location.

getHeightFromWorld

public float getHeightFromWorld(Vector3f position)
getHeightFromWorld returns the height of an arbitrary point on the terrain when given world coordinates. If the point is between height point values, the height is linearly interpolated. This provides smooth height calculations. If the point provided is not within the bounds of the height map, the NaN float value is returned (Float.NaN).

Parameters:
position - the vector representing the height location to check.
Returns:
the height at the provided location.

getSurfaceNormal

public Vector3f getSurfaceNormal(Vector2f position,
                                 Vector3f store)
getSurfaceNormal returns the normal of an arbitrary point on the terrain. The normal is linearly interpreted from the normals of the 4 nearest defined points. If the point provided is not within the bounds of the height map, null is returned.

Parameters:
position - the vector representing the location to find a normal at.
store - the Vector3f object to store the result in. If null, a new one is created.
Returns:
the normal vector at the provided location.

getSurfaceNormal

public Vector3f getSurfaceNormal(Vector3f position,
                                 Vector3f store)
getSurfaceNormal returns the normal of an arbitrary point on the terrain. The normal is linearly interpreted from the normals of the 4 nearest defined points. If the point provided is not within the bounds of the height map, null is returned.

Parameters:
position - the vector representing the location to find a normal at. Only the x and z values are used.
store - the Vector3f object to store the result in. If null, a new one is created.
Returns:
the normal vector at the provided location.

getSurfaceNormal

public Vector3f getSurfaceNormal(float x,
                                 float z,
                                 Vector3f store)
getSurfaceNormal returns the normal of an arbitrary point on the terrain. The normal is linearly interpreted from the normals of the 4 nearest defined points. If the point provided is not within the bounds of the height map, null is returned.

Parameters:
x - the x coordinate to check.
z - the z coordinate to check.
store - the Vector3f object to store the result in. If null, a new one is created.
Returns:
the normal vector at the provided location.

getOffset

public Vector2f getOffset()
Returns the current offset amount. This is used when building texture coordinates.

Returns:
The current offset amount.

getTotalSize

public int getTotalSize()
Returns the total size of the terrain.

Returns:
The terrain's total size.

getSize

public int getSize()
Returns the size of this terrain page.

Returns:
The current block size.

getStepScale

public Vector3f getStepScale()
Returns the step scale that stretches the height map.

Returns:
The current step scale.

getOffsetAmount

public float getOffsetAmount()
Returns the offset amount this terrain block uses for textures.

Returns:
The current offset amount.

setOffset

public void setOffset(Vector2f offset)
Sets the value for the current offset amount to use when building texture coordinates. Note that this does NOT rebuild the terrain at all. This is mostly used for outside constructors of terrain blocks.

Parameters:
offset - The new texture offset.

setTotalSize

public void setTotalSize(int totalSize)
Sets the total size of the terrain . Note that this does NOT rebuild the terrain at all. This is mostly used for outside constructors of terrain blocks.

Parameters:
totalSize - The new total size.

setSize

public void setSize(int size)
Sets the size of this terrain page. Note that this does NOT rebuild the terrain at all. This is mostly used for outside constructors of terrain blocks.

Parameters:
size - The new size.

setStepScale

public void setStepScale(Vector3f stepScale)
Sets the step scale of this terrain page's height map. Note that this does NOT rebuild the terrain at all. This is mostly used for outside constructors of terrain blocks.

Parameters:
stepScale - The new step scale.

setOffsetAmount

public void setOffsetAmount(float offsetAmount)
Sets the offset of this terrain texture map. Note that this does NOT rebuild the terrain at all. This is mostly used for outside constructors of terrain blocks.

Parameters:
offsetAmount - The new texture offset.

fixNormals

public void fixNormals()

createHeightSubBlock

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

setHeightMapValue

public void setHeightMapValue(int x,
                              int y,
                              float newVal)
setHeightMapValue sets the value of this block's height map at the given coords

Parameters:
x -
y -
newVal -

addHeightMapValue

public void addHeightMapValue(int x,
                              int y,
                              float toAdd)
addHeightMapValue adds to the value of this block's height map at the given coords

Parameters:
x -
y -
toAdd -

multHeightMapValue

public void multHeightMapValue(int x,
                               int y,
                               float toMult)
multHeightMapValue multiplies the value of this block's height map at the given coords by the value given.

Parameters:
x -
y -
toMult -

getQuadrant

public short getQuadrant()
Returns:
Returns the quadrant.

setQuadrant

public void setQuadrant(short quadrant)
Parameters:
quadrant - The quadrant to set.

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

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