 |
#include <Terrain.h>
Public Types | |
| enum | Flags { DEBUG_PATCHES = 1, FRUSTUM_CULLING = 2, LEVEL_OF_DETAIL = 8 } |
Public Member Functions | |
| bool | isFlagSet (Flags flag) const |
| void | setFlag (Flags flag, bool on) |
| unsigned int | getPatchCount () const |
| TerrainPatch * | getPatch (unsigned int index) const |
| const BoundingBox & | getBoundingBox () const |
| float | getHeight (float x, float z) const |
| bool | setLayer (int index, const char *texturePath, const Vector2 &textureRepeat=Vector2::one(), const char *blendPath=NULL, int blendChannel=0, int row=-1, int column=-1) |
| unsigned int | draw (bool wireframe=false) |
Static Public Member Functions | |
| static Terrain * | create (const char *path) |
| static Terrain * | create (Properties *properties) |
| static Terrain * | create (HeightField *heightfield, const Vector3 &scale=Vector3::one(), unsigned int patchSize=32, unsigned int detailLevels=1, float skirtScale=0.0f, const char *normalMapPath=NULL, const char *materialPath=NULL) |
Protected Member Functions | |
| void | setNode (Node *node) |
| Drawable * | clone (NodeCloneContext &context) |
Defines a Terrain that is capable of rendering large landscapes from 2D heightmap images.
Terrains can be constructed from several different heightmap sources:
1. Basic intensity image (PNG), where the intensity of pixel represents the height of the terrain. 2. 24-bit high precision heightmap image (PNG), which can be generated from a mesh using gameplay-encoder. 3. 8-bit or 16-bit RAW heightmap image using PC byte ordering (little endian), which is compatible with many external tools such as World Machine, Unity and more. The file extension must be either .raw or .r16 for RAW files.
Physics/collision is supported by setting a rigid body collision object on the Node that the terrain is attached to. The collision shape should be specified using PhysicsCollisionShape::heightfield(), which will utilize the internal height array of the terrain to define the collision shape. Define a collision object in this way will allow the terrain to automatically interact with other rigid bodies, characters and vehicles in the scene.
Surface detail is provided via texture splatting, where multiple texture layers can be added along with blend maps to define how different layers blend with each other. These layers can be defined in terrain properties files, as well as with the setLayer method. The number of supported layers depends on the target hardware, although typically 2-3 levels is sufficient. Multiple blend maps for different layers can be packed into different channels of a single texture for more efficient texture utilization. Levels can be applied across the entire terrain, or in more complex cases, for individual patches only.
Surface lighting is achieved with either vertex normals or with a normal map. If a normal map is used, it should be an object-space normal map containing normal vectors for the entire terrain, encoded into the red, green and blue channels of the texture. This is useful as a replacement for vertex normals, especially when using level-of-detail, since it allows you to provide high quality normal vectors regardless of the tessellation or LOD of the terrain. This also eliminates lighting artifacts/popping from LOD changes, which commonly occurs when vertex normals are used. A terrain normal map can only be specified at creation time, since it requires omission of vertex normal information in the generated terrain geometry data.
Internally, Terrain is broken into smaller, more manageable patches, which can be culled separately for more efficient rendering. The size of the terrain patches can be controlled via the patchSize property. Patches can be previewed by enabling the DEBUG_PATCHES flag via the setFlag method. Other terrain behavior can also be enabled and disabled using terrain flags.
Level of detail (LOD) is supported using a technique that is similar to texture mipmapping. A distance-to-camera based test, using a simple screen-space error metric is used to decide the appropriate LOD for a terrain patch. The number of LOD levels is 1 by default (which means only the base level is used), but can be specified via the detailLevels property. Using too large a number for detailLevels can result in excessive popping in the distance for very hilly terrains, so a smaller number (2-3) often works best in these cases.
Finally, when LOD is enabled, cracks can begin to appear between terrain patches of different LOD levels. If the cracks are only minor (depends on your terrain topology and textures used), an acceptable approach might be to simply use a background clear color that closely matches your terrain to make the cracks much less visible. However, often that is not acceptable, so the Terrain class also supports a simple solution called "vertical skirts". When enabled (via the skirtScale parameter in the terrain file), a vertical edge will extend down along the sides of all terrain patches, which fills in the crack. This is a very fast approach as it adds only a small number of triangles per patch and requires zero extra CPU time or draw calls, which are often needed for more complex stitching approaches. In practice, the skirts are often not noticeable at all unless the LOD variation is very large and the terrain is excessively hilly on the edge of a LOD transition.
Terrain flags.
| DEBUG_PATCHES |
Draw terrain patches different colors (off by default). |
| FRUSTUM_CULLING |
Enables view frustum culling (on by default). Frustum culling uses the scene's active camera. The terrain must be attached to a node that is within a scene for this to work. |
| LEVEL_OF_DETAIL |
Enables level of detail (on by default). This flag enables or disables level of detail, however it does nothing if "detailLevels" was not set to a value greater than 1 in the terrain properties file at creation time. |
| Drawable* gameplay::Terrain::clone | ( | NodeCloneContext & | context | ) | [protected, virtual] |
Implements gameplay::Drawable.
| static Terrain* gameplay::Terrain::create | ( | const char * | path | ) | [static] |
Loads a Terrain from the given properties file.
The specified properties file can contain a full terrain definition, including a heightmap (PNG, RAW8, RAW16), level of detail information, patch size, layer texture details and vertical skirt size. A custom terrain material file can also be specified, otherwise the terrain will look for a material file at res/materials/terrain.material.
| path | Path to a properties file describing the terrain. |
| static Terrain* gameplay::Terrain::create | ( | Properties * | properties | ) | [static] |
Creates a new terrain definition from the configuration in the specified Properties object.
| properties | Properties object containing the terrain definition. |
| static Terrain* gameplay::Terrain::create | ( | HeightField * | heightfield, |
| const Vector3 & | scale = Vector3::one(), |
||
| unsigned int | patchSize = 32, |
||
| unsigned int | detailLevels = 1, |
||
| float | skirtScale = 0.0f, |
||
| const char * | normalMapPath = NULL, |
||
| const char * | materialPath = NULL |
||
| ) | [static] |
Creates a terrain from the given heightfield.
Terrain geometry is loaded from the given height array, using the specified parameters for size, patch size, detail levels and skirt scale.
The newly created terrain increases the reference count of the HeightField.
| heightfield | The heightfield object containing height data for the terrain. |
| scale | A scale to apply to the terrain along the X, Y and Z axes. The terrain and any associated physics heightfield is scaled by this amount. Pass Vector3::one() to use the exact dimensions and heights in the supplied height array. |
| patchSize | Size of terrain patches (number of quads). |
| detailLevels | Number of detail levels to generate for the terrain (a value of one generates only the base level, resulting in no LOD at runtime. |
| skirtScale | A positive value indicates that vertical skirts should be generated at the specified scale, which is relative to the height of the terrain. For example, a value of 0.5f indicates that vertical skirts should extend down by half of the maximum height of the terrain. A value of zero disables vertical skirts. |
| normalMapPath | Path to an object-space normal map to use for terrain lighting, instead of vertex normals. |
| materialPath | Optional path to a material file to use for the terrain (if not specified, looks for a material file at res/materials/terrain.material. |
| unsigned int gameplay::Terrain::draw | ( | bool | wireframe = false | ) | [virtual] |
Implements gameplay::Drawable.
| const BoundingBox& gameplay::Terrain::getBoundingBox | ( | ) | const |
Gets the local bounding box for this terrain.
| float gameplay::Terrain::getHeight | ( | float | x, |
| float | z | ||
| ) | const |
Gets the world-space height of the terrain at the specified position on the X,Z plane.
The specified X and Z coordinates should be in world units and may fall between height values. In this case, an interpolated value will be returned between neighboring heightfield heights. If the specified point lies outside of the terrain, it is clamped to the terrain boundaries.
| x | The X coordinate, in world space. |
| z | The Z coordinate, in world space. |
| TerrainPatch* gameplay::Terrain::getPatch | ( | unsigned int | index | ) | const |
Gets a terrain patch
| unsigned int gameplay::Terrain::getPatchCount | ( | ) | const |
Gets the total number of terrain patches.
| bool gameplay::Terrain::isFlagSet | ( | Flags | flag | ) | const |
Determines if the specified terrain flag is currently set.
| void gameplay::Terrain::setFlag | ( | Flags | flag, |
| bool | on | ||
| ) |
Enables or disables the specified terrain flag.
| flag | The terrain flag to set. |
| on | True to turn the flag on, false to turn it off. |
| bool gameplay::Terrain::setLayer | ( | int | index, |
| const char * | texturePath, | ||
| const Vector2 & | textureRepeat = Vector2::one(), |
||
| const char * | blendPath = NULL, |
||
| int | blendChannel = 0, |
||
| int | row = -1, |
||
| int | column = -1 |
||
| ) |
Sets the detail textures information for a terrain layer.
A detail layer includes a color texture, a repeat count across the terrain for the texture and a region of the texture to use.
Optionally, a layer can also include a blend texture, which is used to instruct the terrain how to blend the new layer with the layer underneath it. Blend maps use only a single channel of a texture and are best supplied by packing the blend map for a layer into the alpha channel of the color texture. Blend maps are always stretched over the entire terrain
The lowest/base layer of the terrain should not include a blend map, since there is no lower level to blend with. All other layers should normally include a blend map. However, since no blend map will result in the texture completely masking the layer underneath it.
Detail layers can be applied globally (to the entire terrain), or to one or more specific patches in the terrain. Patches are specified by row and column number, which is dependent on the patch size configuration of your terrain. For layers that span the entire terrain, the repeat count is relative to the entire terrain. For layers that span only specific patches, the repeat count is relative to those patches only.
| index | Layer index number. Layer indexes do not necessarily need to be sequential and are used simply to uniquely identify layers, where higher numbers specify higher-level layers. |
| texturePath | Path to the color texture for this layer. |
| textureRepeat | Repeat count for the color texture across the terrain or patches. |
| blendPath | Path to the blend texture for this layer (optional). |
| blendChannel | Channel of the blend texture to sample for the blend map (0 == R, 1 == G, 2 == B, 3 == A). |
| row | Specifies the row index of patches to use this layer (optional, -1 means all rows). |
| column | Specifies the column index of patches to use this layer (optional, -1 means all columns). |
| void gameplay::Terrain::setNode | ( | Node * | node | ) | [protected, virtual] |
Reimplemented from gameplay::Drawable.
1.7.6.1
