[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 4.10.23 Terrain Mesh Object

Written by Jorrit Tyberghein, (jorrit.tyberghein@gmail.com).

THIS MANUAL SECTION IS HEAVILY OUTDATED!

This mesh object represents a landscape engine. It features four static LOD levels and dynamic lighting for one directional light. In future it will also have support for dynamic shadows but this is still a todo at this moment.

The basic principle behind the terrain engine is that the entire terrain is divided in a number of blocks. Usually this is equal to 8x8 blocks for the terrain but this is something that you can control. The division into blocks is important for three reasons. The first reason is that LOD selection happens on a block level. i.e. every block is shown at one level of LOD independent from the other blocks. The second reason is that visibility culling for terrain engine also works on block granularity (also the visibility algo itself goes deeper for doing the actual tests). The last reason for the blocks is that every block can have a separate texture. This is important because some hardware has texture limitations and you often want to overlay a very big texture on a landscape. Since very block has its own texture you can do this easily.

The terrain engine is based on a height function (as opposed to a heightmap alone). Support for heightmaps is provided too by converting a heightmap to a height function. But in general you can feed the terrain engine with any function `height=heightfunc(x,y)`. You can also optionally give a normal function. If not given the landscape engine will calculate normals from the height function automatically.

Every block is further divided into a grid. For example, with a grid of 16x16 every block will have 16x16 quads or 16x16x2 triangles at the highest detail level. The combination of blocks and grids control how many triangles the entire terrain will have.

The terrain engine supports four levels of LOD which it will use independently for every block. Level 0 is highest detail. You can control the distance at which every LOD level kicks in and you can also control the quality of every level.

The terrain engine supports a visibility algorithm based on a quad-tree. The visibility algorithm will cull away geometry on a blocks level (i.e. either an entire block is visible or not). But internally it will use a quad-tree which can (and should) go deeper than the blocks resolution to make sure that the visibility testing is fine enough.

Every block has its own texture. You can use a big texture and split it into individual parts. One part for every block. Crystal Space also has a texture generation utility which is able to create realistic terrain textures given several base textures and a heightmap.

The terrain engine also supports one colored directional light without shadows. In the future we will have support for dynamic shadows.

#### Basic Structure

The following SCF class names are used (for `csLoadPlugin`):

- Type plugin: ``crystalspace.mesh.object.terrfunc'`
- Loader plugin: ``crystalspace.mesh.loader.terrfunc'`
- Factory loader plugin: ``crystalspace.mesh.loader.factory.terrfunc'`

Objects in this plugin implement the following SCF interfaces (get with `scfQueryInterface`):

- MeshObject
  - Implements ``iMeshObject'`
  - Implements ``iTerrFuncState'`
- MeshObjectFactory
  - Implements ``iMeshObjectFactory'`
- MeshObjectFactory
  - Implements ``iMeshObjectType'`

#### Factory State Interface

This plugin has no factory state interface.

#### Factory Loader

The fire mesh factory loader has no parameters.

#### Object State Interface

``iTerrFuncState'` is the SCF interface that you can use to set/get settings for a landscape object. The definition of this interface can be found in ``CS/include/imesh/terrfunc.h'` and that's also the include file you need to include in your applications to use this plugin. Using this interface you can access the terrain parameters.

#### Object Loader

The terrain loader recognizes the following keywords:

`<factory>factoryName</factory>`

  Name of the factory to use for creation of this instance.

`<material index="" />`

  The material to use for the given block of the terrain. The block number is 0 to the total number of blocks (see the ``blocks'` command).

`<material>materialName</material>`

  The material to use for all blocks of the terrain.

`<material start="" end="">materialName%d</material>`

  ``materialName'` is a `printf` style string containing a `%d` to indicate the number used for the material name. ``start'` and ``end'` indicate the range of materials to set (block numbers).

`<correctseams w="" h="" />`

  When the given materials are split from a big texture you can use ``correctseams'` to make sure the textures line up correctly at the borders of blocks. Here is an example. Given a terrain of 8x8 blocks (64 total) and given a texture size of 128x128 for every block you would have to generate a total big texture with horizontal and vertical dimensions equal to `(partsize-2)*8+2`. In this case (with partsize equal to 128) this would mean a total texture of 1010x1010 where every block gets a 128x128 texture where the borders are shared with the adjacent block (hence the 126x126 that is really allocated for one block). If you follow these guidelines you can then use `<correctseams w="128" h="128" />` and you will have perfectly aligned textures for all 8x8 blocks.

`<blocks x="" y="" />`

  The number of blocks in horizontal and vertical direction. Blocks are important for visibility culling and LOD selection because these happen on a block level. So you should use enough blocks to make sure that everything works smoothly. 8x8 is probably a good bet in most cases. 4x4 is a default though. Warning! Due to a current limitation in the terrain engine the number of horizontal blocks must be equal to the number of vertical blocks.

`<grid x="" y="" />`

  With ``grid'` you control the highest detail resolution of every block. For example `<grid x="16 y="16" />` means that every block will use 16x16 quads (or 16x16x2 triangles) at highest detail. The default value for ``grid'` is 8x8.

`<topleft x="" y="" z="" />`

  The top-left coordinate of the terrain. By default this is (0,0,0). For ``x'` and ``z'` the terrain will be generated from 0 to ``xblocks-1'` and ``yblocks-1'` respectively. Use ``scale'` to scale this first and then use ``topleft'` to relocate. The ``y'` value in ``topleft'` will be added to the height function (after scaling).

`<scale x="" y="" z="" />`

  Scale the entire terrain. ``x'` and ``z'` will scale the default 0 to ``xblocks-1'` and ``yblocks-1'`. The ``y'` scale will be used to multiply with the value from the height function.

`<color red="" green="" blue="" />`

  This is the base color which will be added to all triangle of the terrain. Consider this a kind of ambient lighting. Default is black. Full bright would be `1,1,1`.

`<dirlight>`

      	<position x="" y="" z="" />
      	<color red="" green="" blue="" />
      </dirlight>

  Set a directional light. `x,y,z` is a normal vector for the light. `red,green,blue` is the color of the light.

`<loddist level="" distance="" />`

  Set the distance at which we switch to the given LOD level. LOD level 0 (highest detail) is always used for very close viewpoints but you can control distance for levels 1, 2, and 3. Default values are 100, 400, and 800 for the three levels. Note that LOD happens on a block basis so for every block the distance here will be used to see what LOD level to select.

`<lodcost level="" cost="" />`

  Set the cost factor to use for going from the previous LOD level to the new one. High values for ``cost'` mean that more triangles will be removed (i.e. better LOD but worse quality). The default values are `0.03`, `0.08`, and `0.2`. So ``loddist'` controls at which distance a new LOD level is selected while ``lodcost'` controls the quality of every LOD level. The base quality (i.e. highest quality) of every block is controlled with the ``grid'` command.

`<quaddepth>quaddepthValue</quaddepth>`

  Control the depth of the quad-tree which is used for visibility culling. This depth is measured from the entire terrain. Usually you make sure that the depth is high enough so that individual blocks are at least sub-divided about three extra times. i.e. given a terrain with 8x8 blocks you would probably want to use a depth of six (which is default). Higher quadtree depth's will increase the cost of visibility culling but also increase the accuracy. So a higher depth will be more important for a slow renderer (software renderer for example).

`<vistest />`

  Enable or disable visibility culling. Default is on.

`<heightmap>`

      	<image>imageFile</image>
      	<scale>scaleValue</scale>
      	<shift>shiftValue</shift>
      </heightmap>

  Use the given image file as a heightmap for the landscape. Values from this heightmap will go between 0 and 256. You can alter the range by playing with ``scale'` (default 1) and ``shift'` (default 0).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ]

This document was generated using texi2html 1.76.