TerrainPatch (jMonkeyEngine 3.1 jme3-terrain Javadoc)

java.lang.Object
- com.jme3.scene.Spatial
- - com.jme3.scene.Geometry
  - - com.jme3.terrain.geomipmap.TerrainPatch

All Implemented Interfaces:

com.jme3.asset.CloneableSmartAsset, com.jme3.collision.Collidable, com.jme3.export.Savable, com.jme3.util.clone.JmeCloneable, java.lang.Cloneable
```
public class TerrainPatch
extends com.jme3.scene.Geometry
```
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-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. Each patch needs to know its neighbour's LOD so it can seam its edges with them, in case the neighbour has a different LOD. If this doesn't happen, you will see gaps. The LOD value is most detailed at zero. It gets less detailed the higher the LOD value until you reach maxLod, which is a mathematical limit on the number of times the 'size' of the patch can be divided by two. However there is a -1 to that for now until I add in a custom index buffer calculation for that max level, the current algorithm does not go that far. You can supply a LodThresholdCalculator for use in determining when the LOD should change. It's API will no doubt change in the near future. Right now it defaults to just changing LOD every two patch sizes. So if a patch has a size of 65, then the LOD changes every 130 units away.

Author:

Brent Owens

Nested Class Summary
- Nested classes/interfaces inherited from class com.jme3.scene.Spatial
  com.jme3.scene.Spatial.BatchHint, com.jme3.scene.Spatial.CullHint

Field Summary

Fields
Modifier and Type	Field and Description
`protected TerrainPatch`	`bottomNeighbour`
`protected LODGeomap`	`geomap`
`protected TerrainPatch`	`leftNeighbour`
`protected int`	`lod`
`protected int`	`lodBottom`
`protected float[]`	`lodEntropy`
`protected int`	`lodLeft`
`protected int`	`lodRight`
`protected int`	`lodTop`
`protected com.jme3.math.Vector2f`	`offset`
`protected float`	`offsetAmount`
`protected int`	`previousLod`
`protected short`	`quadrant`
`protected TerrainPatch`	`rightNeighbour`
`protected boolean`	`searchedForNeighboursAlready`
`protected int`	`size`
`protected com.jme3.math.Vector3f`	`stepScale`
`protected TerrainPatch`	`topNeighbour`
`protected int`	`totalSize`
`protected com.jme3.math.Vector3f`	`worldScaleCached`
`protected com.jme3.math.Vector3f`	`worldTranslationCached`

Fields inherited from class com.jme3.scene.Geometry
cachedWorldMat, groupNode, ignoreTransform, lodLevel, material, mesh, SAVABLE_VERSION, startIndex

Fields inherited from class com.jme3.scene.Spatial
batchHint, controls, cullHint, frustrumIntersects, key, localLights, localOverrides, localTransform, name, parent, queueBucket, queueDistance, refreshFlags, RF_BOUND, RF_CHILD_LIGHTLIST, RF_LIGHTLIST, RF_MATPARAM_OVERRIDE, RF_TRANSFORM, shadowMode, userData, worldBound, worldLights, worldOverrides, worldTransform

Constructor Summary

Constructors
Constructor and Description
`TerrainPatch()`
`TerrainPatch(java.lang.String name)`
`TerrainPatch(java.lang.String name, int size)`
`TerrainPatch(java.lang.String name, int size, com.jme3.math.Vector3f stepScale, float[] heightMap, com.jme3.math.Vector3f origin)` Constructor instantiates a new `TerrainPatch` object.
`TerrainPatch(java.lang.String name, int size, com.jme3.math.Vector3f stepScale, float[] heightMap, com.jme3.math.Vector3f origin, int totalSize, com.jme3.math.Vector2f offset, float offsetAmount)` Constructor instantiates a new `TerrainPatch` object.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`averageNormalsTangents(com.jme3.math.Vector3f topPoint, com.jme3.math.Vector3f rootPoint, com.jme3.math.Vector3f leftPoint, com.jme3.math.Vector3f bottomPoint, com.jme3.math.Vector3f rightPoint, com.jme3.math.Vector3f normal, com.jme3.math.Vector3f tangent, com.jme3.math.Vector3f binormal)`
`protected void`	`cacheTerrainTransforms()` Caches the transforms (except rotation) so the LOD calculator, which runs on a separate thread, can access them safely.
`protected void`	`clearCaches()` Removes any references when the terrain is being removed.
`TerrainPatch`	`clone()`
`void`	`cloneFields(com.jme3.util.clone.Cloner cloner, java.lang.Object original)` Called internally by com.jme3.util.clone.Cloner.
`int`	`collideWith(com.jme3.collision.Collidable other, com.jme3.collision.CollisionResults results)`
`protected void`	`ensurePositiveVolumeBBox()`
`protected void`	`fixNormalEdges(TerrainPatch right, TerrainPatch bottom, TerrainPatch top, TerrainPatch left, TerrainPatch bottomRight, TerrainPatch bottomLeft, TerrainPatch topRight, TerrainPatch topLeft)` Matches the normals along the edge of the patch with the neighbours.
`void`	`generateLodEntropies()` This calculation is slow, so don't use it often.
`com.jme3.math.Triangle[]`	`getGridTriangles(float x, float z)` Get the triangles at the specified grid point.
`protected float`	`getHeight(int x, int z, float xm, float zm)`
`float[]`	`getHeightMap()`
`float`	`getHeightmapHeight(float x, float z)`
`int`	`getLod()`
`protected int`	`getLodBottom()`
`float[]`	`getLodEntropies()`
`protected int`	`getLodLeft()`
`protected int`	`getLodRight()`
`protected int`	`getLodTop()`
`int`	`getMaxLod()` The maximum lod supported by this terrain patch.
`protected com.jme3.math.Vector3f`	`getMeshNormal(int x, int z)`
`com.jme3.math.Vector2f`	`getOffset()` Returns the current offset amount.
`float`	`getOffsetAmount()` Returns the offset amount this terrain patch uses for textures.
`int`	`getPreviousLod()`
`short`	`getQuadrant()`
`int`	`getSize()` Returns the size of this terrain patch.
`com.jme3.math.Vector3f`	`getStepScale()` Returns the step scale that stretches the height map.
`com.jme3.math.Vector2f`	`getTex(float x, float z, com.jme3.math.Vector2f store)`
`int`	`getTotalSize()` Returns the total size of the terrain.
`com.jme3.math.Triangle`	`getTriangle(float x, float z)` Get the triangle of this geometry at the specified local coordinate.
`com.jme3.math.Vector3f`	`getWorldScaleCached()`
`com.jme3.math.Vector3f`	`getWorldTranslationCached()`
`void`	`lockMesh()` Locks the mesh (sets it static) to improve performance.
`void`	`read(com.jme3.export.JmeImporter im)`
`protected void`	`reIndexGeometry(java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updated, boolean useVariableLod)`
`protected void`	`setHeight(java.util.List<TerrainQuad.LocationHeight> locationHeights, boolean overrideHeight)`
`void`	`setLod(int lod)`
`protected void`	`setLodBottom(int lodBottom)`
`protected void`	`setLodLeft(int lodLeft)`
`protected void`	`setLodRight(int lodRight)`
`protected void`	`setLodTop(int lodTop)`
`void`	`setOffset(com.jme3.math.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`	`setPreviousLod(int previousLod)`
`void`	`setQuadrant(short quadrant)`
`void`	`setSize(int size)` Sets the size of this terrain patch.
`void`	`setStepScale(com.jme3.math.Vector3f stepScale)` Sets the step scale of this terrain patch's height map.
`void`	`setTotalSize(int totalSize)` Sets the total size of the terrain .
`void`	`unlockMesh()` Unlocks the mesh (sets it dynamic) to make it editable.
`protected void`	`updateNormals()` recalculate all of the normal vectors in this terrain patch
`protected com.jme3.math.Vector3f`	`worldCoordinateToLocal(com.jme3.math.Vector3f loc)`
`void`	`write(com.jme3.export.JmeExporter ex)`

Methods inherited from class com.jme3.scene.Geometry
associateWithGroupNode, breadthFirstTraversal, checkCulling, clone, computeWorldMatrix, deepClone, depthFirstTraversal, getLodLevel, getMaterial, getMesh, getModelBound, getTriangleCount, getVertexCount, getWorldMatrix, isBatched, isGrouped, isIgnoreTransform, oldClone, oldDeepClone, removeFromParent, setIgnoreTransform, setLodLevel, setMaterial, setMesh, setModelBound, setParent, unassociateFromGroupNode, updateModelBound, updateWorldBound, updateWorldTransforms

Methods inherited from class com.jme3.scene.Spatial
addControl, addLight, addMatParamOverride, breadthFirstTraversal, center, clearMatParamOverrides, forceRefresh, getBatchHint, getControl, getControl, getCullHint, getKey, getLastFrustumIntersection, getLocalBatchHint, getLocalCullHint, getLocalLightList, getLocalMatParamOverrides, getLocalQueueBucket, getLocalRotation, getLocalScale, getLocalShadowMode, getLocalToWorldMatrix, getLocalTransform, getLocalTranslation, getName, getNumControls, getParent, getQueueBucket, getShadowMode, getUserData, getUserDataKeys, getWorldBound, getWorldLightList, getWorldMatParamOverrides, getWorldRotation, getWorldScale, getWorldTransform, getWorldTranslation, hasAncestor, jmeClone, localToWorld, lookAt, matches, move, move, removeControl, removeControl, removeLight, removeMatParamOverride, rotate, rotate, rotateUpTo, runControlRender, scale, scale, setBatchHint, setBoundRefresh, setCullHint, setKey, setLastFrustumIntersection, setLightListRefresh, setLocalRotation, setLocalRotation, setLocalScale, setLocalScale, setLocalScale, setLocalTransform, setLocalTranslation, setLocalTranslation, setMatParamOverrideRefresh, setName, setQueueBucket, setRequiresUpdates, setShadowMode, setTransformRefresh, setUserData, toString, updateGeometricState, updateLogicalState, updateMatParamOverrides, updateWorldLightList, worldToLocal

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - geomap
```
protected LODGeomap geomap
```
  - lod
```
protected int lod
```
  - previousLod
```
protected int previousLod
```
  - lodLeft
```
protected int lodLeft
```
  - lodTop
```
protected int lodTop
```
  - lodRight
```
protected int lodRight
```
  - lodBottom
```
protected int lodBottom
```
  - size
```
protected int size
```
  - totalSize
```
protected int totalSize
```
  - quadrant
```
protected short quadrant
```
  - stepScale
```
protected com.jme3.math.Vector3f stepScale
```
  - offset
```
protected com.jme3.math.Vector2f offset
```
  - offsetAmount
```
protected float offsetAmount
```
  - leftNeighbour
```
protected TerrainPatch leftNeighbour
```
  - topNeighbour
```
protected TerrainPatch topNeighbour
```
  - rightNeighbour
```
protected TerrainPatch rightNeighbour
```
  - bottomNeighbour
```
protected TerrainPatch bottomNeighbour
```
  - searchedForNeighboursAlready
```
protected boolean searchedForNeighboursAlready
```
  - worldTranslationCached
```
protected com.jme3.math.Vector3f worldTranslationCached
```
  - worldScaleCached
```
protected com.jme3.math.Vector3f worldScaleCached
```
  - lodEntropy
```
protected float[] lodEntropy
```
- Constructor Detail
  - TerrainPatch
```
public TerrainPatch()
```
  - TerrainPatch
```
public TerrainPatch(java.lang.String name)
```
  - TerrainPatch
```
public TerrainPatch(java.lang.String name,
            int size)
```
  - TerrainPatch
```
public TerrainPatch(java.lang.String name,
            int size,
            com.jme3.math.Vector3f stepScale,
            float[] heightMap,
            com.jme3.math.Vector3f origin)
```
    Constructor instantiates a new TerrainPatch object. The parameters and heightmap data are then processed to generate a TriMesh object for rendering.
    
    Parameters:
    name - the name of the terrain patch.
    size - the size of the heightmap.
    stepScale - the scale for the axes.
    heightMap - the height data.
    origin - the origin offset of the patch.
  - TerrainPatch
```
public TerrainPatch(java.lang.String name,
            int size,
            com.jme3.math.Vector3f stepScale,
            float[] heightMap,
            com.jme3.math.Vector3f origin,
            int totalSize,
            com.jme3.math.Vector2f offset,
            float offsetAmount)
```
    Constructor instantiates a new TerrainPatch object. The parameters and heightmap data are then processed to generate a TriMesh object for renderering.
    
    Parameters:
    name - the name of the terrain patch.
    size - the size of the patch.
    stepScale - the scale for the axes.
    heightMap - the height data.
    origin - the origin offset of the patch.
    totalSize - the total size of the terrain. (Higher if the patch is part of a TerrainQuad tree.
    offset - the offset for texture coordinates.
    offsetAmount - the total offset amount. Used for texture coordinates.
- Method Detail
  - generateLodEntropies
```
public void generateLodEntropies()
```
    This calculation is slow, so don't use it often.
  - getLodEntropies
```
public float[] getLodEntropies()
```
  - getHeightMap
```
public float[] getHeightMap()
```
  - getMaxLod
```
public int getMaxLod()
```
    The maximum lod supported by this terrain patch. If the patch size is 32 then the returned value would be log2(32)-2 = 3 You can then use that value, 3, to see how many times you can divide 32 by 2 before the terrain gets too un-detailed (can't stitch it any further).
    
    Returns:
    the maximum LOD
  - reIndexGeometry
```
protected void reIndexGeometry(java.util.HashMap<java.lang.String,UpdatedTerrainPatch> updated,
                   boolean useVariableLod)
```
  - getTex
```
public com.jme3.math.Vector2f getTex(float x,
                            float z,
                            com.jme3.math.Vector2f store)
```
  - getHeightmapHeight
```
public float getHeightmapHeight(float x,
                       float z)
```
  - getTriangle
```
public com.jme3.math.Triangle getTriangle(float x,
                                 float z)
```
    Get the triangle of this geometry at the specified local coordinate.
    
    Parameters:
    x - local to the terrain patch
    z - local to the terrain patch
    
    Returns:
    the triangle in world coordinates, or null if the point does intersect this patch on the XZ axis
  - getGridTriangles
```
public com.jme3.math.Triangle[] getGridTriangles(float x,
                                        float z)
```
    Get the triangles at the specified grid point. Probably only 2 triangles
    
    Parameters:
    x - local to the terrain patch
    z - local to the terrain patch
    
    Returns:
    the triangles in world coordinates, or null if the point does intersect this patch on the XZ axis
  - setHeight
```
protected void setHeight(java.util.List<TerrainQuad.LocationHeight> locationHeights,
             boolean overrideHeight)
```
  - updateNormals
```
protected void updateNormals()
```
    recalculate all of the normal vectors in this terrain patch
  - fixNormalEdges
```
protected void fixNormalEdges(TerrainPatch right,
                  TerrainPatch bottom,
                  TerrainPatch top,
                  TerrainPatch left,
                  TerrainPatch bottomRight,
                  TerrainPatch bottomLeft,
                  TerrainPatch topRight,
                  TerrainPatch topLeft)
```
    Matches the normals along the edge of the patch with the neighbours. Computes the normals for the right, bottom, left, and top edges of the patch, and saves those normals in the neighbour's edges too. Takes 4 points (if has neighbour on that side) for each point on the edge of the patch: * | *---x---* | * It works across the right side of the patch, from the top down to the bottom. Then it works on the bottom side of the patch, from the left to the right.
  - averageNormalsTangents
```
protected void averageNormalsTangents(com.jme3.math.Vector3f topPoint,
                          com.jme3.math.Vector3f rootPoint,
                          com.jme3.math.Vector3f leftPoint,
                          com.jme3.math.Vector3f bottomPoint,
                          com.jme3.math.Vector3f rightPoint,
                          com.jme3.math.Vector3f normal,
                          com.jme3.math.Vector3f tangent,
                          com.jme3.math.Vector3f binormal)
```
  - getMeshNormal
```
protected com.jme3.math.Vector3f getMeshNormal(int x,
                                   int z)
```
  - getHeight
```
protected float getHeight(int x,
              int z,
              float xm,
              float zm)
```
  - lockMesh
```
public void lockMesh()
```
    Locks the mesh (sets it static) to improve performance. But it it not editable then. Set unlock to make it editable.
  - unlockMesh
```
public void unlockMesh()
```
    Unlocks the mesh (sets it dynamic) to make it editable. It will be editable but performance will be reduced. Call lockMesh to improve performance.
  - getOffsetAmount
```
public float getOffsetAmount()
```
    Returns the offset amount this terrain patch uses for textures.
    
    Returns:
    The current offset amount.
  - getStepScale
```
public com.jme3.math.Vector3f getStepScale()
```
    Returns the step scale that stretches the height map.
    
    Returns:
    The current step scale.
  - 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 patch.
    
    Returns:
    The current patch size.
  - getOffset
```
public com.jme3.math.Vector2f getOffset()
```
    Returns the current offset amount. This is used when building texture coordinates.
    
    Returns:
    The current offset amount.
  - setOffset
```
public void setOffset(com.jme3.math.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 patches.
    
    Parameters:
    offset - The new texture offset.
  - setSize
```
public void setSize(int size)
```
    Sets the size of this terrain patch. Note that this does NOT rebuild the terrain at all. This is mostly used for outside constructors of terrain patches.
    
    Parameters:
    size - The new size.
  - 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 patches.
    
    Parameters:
    totalSize - The new total size.
  - setStepScale
```
public void setStepScale(com.jme3.math.Vector3f stepScale)
```
    Sets the step scale of this terrain patch's height map. Note that this does NOT rebuild the terrain at all. This is mostly used for outside constructors of terrain patches.
    
    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 patches.
    
    Parameters:
    offsetAmount - The new texture offset.
  - getQuadrant
```
public short getQuadrant()
```
    Returns:
    Returns the quadrant.
  - setQuadrant
```
public void setQuadrant(short quadrant)
```
    Parameters:
    quadrant - The quadrant to set.
  - getLod
```
public int getLod()
```
  - setLod
```
public void setLod(int lod)
```
  - getPreviousLod
```
public int getPreviousLod()
```
  - setPreviousLod
```
public void setPreviousLod(int previousLod)
```
  - getLodLeft
```
protected int getLodLeft()
```
  - setLodLeft
```
protected void setLodLeft(int lodLeft)
```
  - getLodTop
```
protected int getLodTop()
```
  - setLodTop
```
protected void setLodTop(int lodTop)
```
  - getLodRight
```
protected int getLodRight()
```
  - setLodRight
```
protected void setLodRight(int lodRight)
```
  - getLodBottom
```
protected int getLodBottom()
```
  - setLodBottom
```
protected void setLodBottom(int lodBottom)
```
  - collideWith
```
public int collideWith(com.jme3.collision.Collidable other,
              com.jme3.collision.CollisionResults results)
                throws com.jme3.collision.UnsupportedCollisionException
```
    Specified by:
    
    collideWith in interface com.jme3.collision.Collidable
    
    Overrides:
    
    collideWith in class com.jme3.scene.Geometry
    
    Throws:
    
    com.jme3.collision.UnsupportedCollisionException
  - worldCoordinateToLocal
```
protected com.jme3.math.Vector3f worldCoordinateToLocal(com.jme3.math.Vector3f loc)
```
  - write
```
public void write(com.jme3.export.JmeExporter ex)
           throws java.io.IOException
```
    Specified by:
    
    write in interface com.jme3.export.Savable
    
    Overrides:
    
    write in class com.jme3.scene.Geometry
    
    Throws:
    
    java.io.IOException
  - read
```
public void read(com.jme3.export.JmeImporter im)
          throws java.io.IOException
```
    Specified by:
    
    read in interface com.jme3.export.Savable
    
    Overrides:
    
    read in class com.jme3.scene.Geometry
    
    Throws:
    
    java.io.IOException
  - clone
```
public TerrainPatch clone()
```
    Specified by:
    
    clone in interface com.jme3.asset.CloneableSmartAsset
    
    Overrides:
    
    clone in class com.jme3.scene.Geometry
  - cloneFields
```
public void cloneFields(com.jme3.util.clone.Cloner cloner,
               java.lang.Object original)
```
    Called internally by com.jme3.util.clone.Cloner. Do not call directly.
    
    Specified by:
    
    cloneFields in interface com.jme3.util.clone.JmeCloneable
    
    Overrides:
    
    cloneFields in class com.jme3.scene.Geometry
  - ensurePositiveVolumeBBox
```
protected void ensurePositiveVolumeBBox()
```
  - cacheTerrainTransforms
```
protected void cacheTerrainTransforms()
```
    Caches the transforms (except rotation) so the LOD calculator, which runs on a separate thread, can access them safely.
  - getWorldScaleCached
```
public com.jme3.math.Vector3f getWorldScaleCached()
```
  - getWorldTranslationCached
```
public com.jme3.math.Vector3f getWorldTranslationCached()
```
  - clearCaches
```
protected void clearCaches()
```
    Removes any references when the terrain is being removed.

Class TerrainPatch

Nested Class Summary

Nested classes/interfaces inherited from class com.jme3.scene.Spatial

Field Summary

Fields inherited from class com.jme3.scene.Geometry

Fields inherited from class com.jme3.scene.Spatial

Constructor Summary

Method Summary

Methods inherited from class com.jme3.scene.Geometry

Methods inherited from class com.jme3.scene.Spatial

Methods inherited from class java.lang.Object

Field Detail

geomap

lod

previousLod

lodLeft

lodTop

lodRight

lodBottom

size

totalSize

quadrant

stepScale

offset

offsetAmount

leftNeighbour

topNeighbour

rightNeighbour

bottomNeighbour

searchedForNeighboursAlready

worldTranslationCached

worldScaleCached

lodEntropy

Constructor Detail

TerrainPatch

TerrainPatch

TerrainPatch

TerrainPatch

TerrainPatch

Method Detail

generateLodEntropies

getLodEntropies

getHeightMap

getMaxLod

reIndexGeometry

getTex

getHeightmapHeight

getTriangle

getGridTriangles

setHeight

updateNormals

fixNormalEdges

averageNormalsTangents

getMeshNormal

getHeight

lockMesh

unlockMesh

getOffsetAmount

getStepScale

getTotalSize

getSize

getOffset

setOffset

setSize

setTotalSize

setStepScale

setOffsetAmount

getQuadrant

setQuadrant

getLod

setLod

getPreviousLod

setPreviousLod

getLodLeft

setLodLeft

getLodTop

setLodTop

getLodRight

setLodRight

getLodBottom