Package com.jme3.terrain.geomipmap

Class TerrainGrid

java.lang.Object
com.jme3.scene.Spatial
com.jme3.scene.Node
com.jme3.terrain.geomipmap.TerrainQuad
com.jme3.terrain.geomipmap.TerrainGrid
All Implemented Interfaces:
HasLocalTransform, CloneableSmartAsset, Collidable, Savable, Terrain, JmeCloneable, Cloneable
public class TerrainGrid extends TerrainQuad

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     |     3 |    Four terrainQuads that make up the grid
 |    *..|..*    |    with the cameraCell in the middle, covering
 |----|--|--|----|    all four quads.
 |    *..|..*    |
 | 2     |     4 |
 +-------+-------+

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 grid 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.

  • Field Details

    • log

      protected static final Logger log

    • currentCamCell

      protected Vector3f currentCamCell

    • quarterSize

      protected int quarterSize

    • quadSize

      protected int quadSize

    • quadIndex

      protected Vector3f[] quadIndex

    • listeners

      protected Set<TerrainGridListener> listeners

    • material

      protected Material material

    • cache

      protected LRUCache<Vector3f,TerrainQuad> cache

    • cellsLoaded

      protected int cellsLoaded

    • gridOffset

      protected int[] gridOffset

    • runOnce

      protected boolean runOnce

    • cacheExecutor

      protected ExecutorService cacheExecutor

  • Constructor Details

  • Method Details

    • isCenter

      protected boolean isCenter(int quadIndex)

    • getQuadrant

      protected int getQuadrant(int quadIndex)

    • getCamCell

      public Vector3f getCamCell(Vector3f location)
      Get the location in cell-coordinates of the specified location. Cell coordinates are integer coordinates, usually with y=0, each representing a cell in the world. For example, moving right in the +X direction: (0,0,0) (1,0,0) (2,0,0), (3,0,0) and then down the -Z direction: (3,0,-1) (3,0,-2) (3,0,-3)

    • getTileCell

      public Vector3f getTileCell(Vector3f location)
      Centered at 0,0. Get the tile index location in integer form:
      Parameters:
      location - world coordinate

    • getGridTileLoader

      public TerrainGridTileLoader getGridTileLoader()

    • getTerrainAt

      public Terrain getTerrainAt(Vector3f worldLocation)
      Get the terrain tile at the specified world location, in XZ coordinates.

    • getTerrainAtCell

      public Terrain getTerrainAtCell(Vector3f cellCoordinate)
      Get the terrain tile at the specified XZ cell coordinate (not world coordinate).
      Parameters:
      cellCoordinate - integer cell coordinates
      Returns:
      the terrain tile at that location

    • toCellSpace

      public Vector3f toCellSpace(Vector3f worldLocation)
      Convert the world location into a cell location (integer coordinates)

    • toWorldSpace

      public Vector3f toWorldSpace(Vector3f cellLocation)
      Convert the cell coordinate (integer coordinates) into world coordinates.

    • removeQuad

      protected void removeQuad(TerrainQuad q)

    • attachQuadAt

      protected void attachQuadAt(TerrainQuad q, int quadrant, Vector3f quadCell, boolean shifted)
      Runs on the rendering thread
      Parameters:
      shifted - quads are still attached to the parent and don't need to re-load

    • updateChildren

      protected void updateChildren(Vector3f camCell)
      Called when the camera has moved into a new cell. We need to update what quads are in the scene now. Step 1: touch cache LRU cache is used, so elements that need to remain should be touched. Step 2: load new quads in background thread if the camera has moved into a new cell, we load in new quads
      Parameters:
      camCell - the cell the camera is in

    • addListener

      public void addListener(TerrainGridListener listener)

    • getCurrentCell

      public Vector3f getCurrentCell()

    • removeListener

      public void removeListener(TerrainGridListener listener)

    • setMaterial

      public void setMaterial(Material mat)
      Description copied from class: Spatial
      Applies the given material to the Spatial, this will propagate the material down to the geometries in the scene graph.
      Overrides:
      setMaterial in class Node
      Parameters:
      mat - The material to set.

    • setQuadSize

      public void setQuadSize(int quadSize)

    • adjustHeight

      public void adjustHeight(List<Vector2f> xz, List<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
      Overrides:
      adjustHeight in class TerrainQuad
      Parameters:
      xz - a list of coordinates where the height will be adjusted
      height - +- value to adjust the height by, that matches the xz coordinates

    • getHeightmapHeight

      protected float getHeightmapHeight(int x, int z)
      Description copied from class: TerrainQuad
      This will just get the heightmap value at the supplied point, not an interpolated (actual) height value.
      Overrides:
      getHeightmapHeight in class TerrainQuad

    • getNumMajorSubdivisions

      public int getNumMajorSubdivisions()
      Specified by:
      getNumMajorSubdivisions in interface Terrain
      Overrides:
      getNumMajorSubdivisions in class TerrainQuad

    • 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
      Overrides:
      getMaterial in class TerrainQuad
      Parameters:
      worldLocation - the location, in world coordinates, of where we are interested in the underlying texture.

    • createExecutorService

      protected ExecutorService createExecutorService()
      This will print out any exceptions from the thread

    • read

      public void read(JmeImporter im) throws IOException
      Specified by:
      read in interface Savable
      Overrides:
      read in class TerrainQuad
      Throws:
      IOException

    • write

      public void write(JmeExporter ex) throws IOException
      Specified by:
      write in interface Savable
      Overrides:
      write in class TerrainQuad
      Throws:
      IOException