Main Page | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | Related Pages

TePatch Class Reference

#include <TePatch.h>

List of all members.


Detailed Description

Single rectangular terrain patch.

This class is used as a representation of the terrain patches database needed by our engine. It also implements the algorithm that computes final patch heihtmap hmap using 4 so-called build maps. This method produces continuous terrain generated from separatedly computed patches.

The class provides scene graph generation too. Using getPatchGraph() and getSeamGraph() methods the landscape can be easily rendered. These methods use caching, so scene graphs are generated only once and are ready to use quickly next time they are needed.

Each patch has to be managed by the TeEngine object and is strongly recommended to use TeEngine::getPatch() method instead of hacking the patch hierarchy in another way.

Todo:
Detailed explanation of the patch hierarchy structure.


Public Types

enum  Direction {
  SOUTH_WEST = 0, SOUTH_EAST = 1, NORTH_WEST = 2, NORTH_EAST = 3,
  SOUTH = 4, WEST = 5, EAST = 6, NORTH = 7
}
enum  PatchMissedPolicy { DONT_CREATE, CREATE, LOWER_DETAIL }
enum  WhichHMap {
  HMAP_PATCH = 4, HMAP_SOUTH_WEST = 0, HMAP_SOUTH_EAST = 1, HMAP_NORTH_WEST = 2,
  HMAP_NORTH_EAST = 3
}

Public Member Functions

 TePatch (TeEngine *engine)
 ~TePatch ()
const TeHeightMapgetHMap () const
TeHeightMapgetHMap ()
void setHMap (TeHeightMap *hmap)
const TeHeightMapgetSeamMap (const Direction which) const
TeHeightMapgetSeamMap (const Direction which)
void setSeamMap (const Direction which, TeHeightMap *map)
SbBool generateSeamMap (const Direction which)
TeEnginegetEngine () const
void setEngine ()
const SbBox2f & getArea () const
int getLevel () const
TePatchgetParent () const
TePatchgetPatch (const SbVec2f &pos, const int level, PatchMissedPolicy policy=CREATE)
TePatchgetPatchRelative (const SbVec2f &pos, const int relativeLevel, PatchMissedPolicy policy=CREATE)
TePatchgetDetail (const Direction which)
void setDetail (const Direction which, TePatch *patch)
void removeDetail (TePatch *patch)
Direction getDirectionWithinParent () const
Direction getDetailDirection (const SbVec2f &point) const
const TeHeightMapgetBuildMap (const int i) const
TeHeightMapgetBuildMap (const int i)
void setBuildMap (const int i, TeHeightMap *hmap)
void setBuildMaps (TeHeightMap *nw, TeHeightMap *ne, TeHeightMap *sw, TeHeightMap *se)
void findBuildMap (const int i)
void prepareBuildMaps ()
void buildHMapFromBuildMaps ()
void generateHMapFF (WhichHMap which, const unsigned int seed, const int num_faults, const float min_delta, const float max_delta)
void makeRoot (const SbBox2f &area, TeEngine *engine)
SoSeparator * getGraph ()
SoSeparator * getPatchGraph ()
SoSeparator * getSeamGraph (const Direction which)

Static Public Member Functions

static int getOppositeDirection (const int d)
static Direction getDirectionXFromVec (const SbVec2f &vec)

Private Member Functions

TePatchgetPatchHierarch (const SbVec2f &pos, const int level, PatchMissedPolicy policy=CREATE)
TePatchgetPatchHierarchRelative (const SbVec2f &pos, const int relativeLevel, PatchMissedPolicy policy=CREATE)
void updateNeighbours ()
SoSeparator * generateGraph ()
SoSeparator * generatePatchGraph ()
SoSeparator * generateSeamGraph (const Direction which)
 TePatch ()

Static Private Member Functions

static SbVec3f calculateNormal (const TeHeightMap *map, const int x, const int y, const float sx, const float sy)
static unsigned short selectMaterial (float value)
static SoSeparator * generateGraphFromSubMap (const TeHeightMap *map, const SbVec2s &min, const SbVec2s &max, const SbBox2f &area)

Private Attributes

SbBox2f area
TeHeightMaphmap
TeHeightMapseamMap [8]
TeHeightMapbuildMap [4]
TeEngineengine
TePatchparent
TePatchdetail [4]
TePatchneighbour [8]
SoSeparator * graph
SoSeparator * seamGraph [8]

Friends

class TeEngine


Member Enumeration Documentation

enum TePatch::Direction
 

Enumerates all 8 possible directions, ASCII-art picture of axis mapping is in the TePatch.h source.

Enumeration values:
SOUTH_WEST  Axis mapping: -x, -y.
SOUTH_EAST  Axis mapping: +x, -y.
NORTH_WEST  Axis mapping: -x, +y.
NORTH_EAST  Axis mapping: +x, +y.
SOUTH  Axis mapping: 0, -y.
WEST  Axis mapping: -x, 0.
EAST  Axis mapping: +x, 0.
NORTH  Axis mapping: 0, +y.

enum TePatch::PatchMissedPolicy
 

Determines what to do when desired patch is not found in the patch-tree.

Enumeration values:
DONT_CREATE  Do not create a new one, we're just checking it, return NULL.
CREATE  We need it, create a new one and all necessary patches too.
LOWER_DETAIL  We need it, return patch matching pos, but possible with lower detail than specified; if pos falls outside the current patch root, new nodes are appended to the top of patch tree to match pos.

enum TePatch::WhichHMap
 

Enumeration used to determine which heightmap should be used at the moment, ASCII-art picture is in the TePatch.h source.

Enumeration values:
HMAP_PATCH  Patch heightmap.
HMAP_SOUTH_WEST  South-west buildmap.
HMAP_SOUTH_EAST  South-east buildmap.
HMAP_NORTH_WEST  North-west buildmap.
HMAP_NORTH_EAST  South-east buildmap.


Constructor & Destructor Documentation

TePatch::TePatch  )  [private]
 

Simple default constructor.

It does not specify the engine that manages this patch and therefore is private and shoul be never called. Documented only to explain the reason.

TePatch::TePatch TeEngine aengine  ) 
 

Constructor.

Parameters:
aengine Engine in which patch hierarchy this patch belongs.

TePatch::~TePatch  ) 
 

Destructor.

Releases memory.

Todo:
Cancel scheduled tasks at engine. ???


Member Function Documentation

void TePatch::buildHMapFromBuildMaps  ) 
 

Computes patch height map from four build maps.

All build maps have to be set before calling this method.

See also:
buildMap, setBuildMap()

Todo:
More detailed documentation.

SbVec3f TePatch::calculateNormal const TeHeightMap map,
const int  x,
const int  y,
const float  sx,
const float  sy
[static, private]
 

Calculates normal at the specified point in the heightmap.

Parameters:
map Pointer to the height map.
x X-coordinate of the point.
y Y-coordinate of the point.
sx ???
sy ???
Returns:
Normal at the specified point (x, y).

Todo:
More detailed documentation. Parameters sx, sy ???

void TePatch::findBuildMap const int  i  ) 
 

Tries to find build map by looking in the neighbours.

We suppose that correct info is in all of them, therefore we grab the first one. Info propagation is assured by setBuildMap() method.

The function returns void, the effect is visible right inside the buildMap attribute.

Parameters:
i Buildmap selector (TePatch::WhichHMap should be used here).
See also:
WhichHMap, buildMap, buildHMapFromBuildMaps()

SoSeparator * TePatch::generateGraph  )  [private]
 

Generates "raw" scene graph of the patch.

All heightmap values will be used and therefore there won't be gap between patches but visible seam artefacts will be probably over the landscape.

Note, that hmap has to be set before calling this function. If it isn't set, empty scene graph is generated.

It is recommended to use generatePatchGraph() instead and later fill gaps between paches with seams.

Returns:
"Raw" scene graph of the patch. Empty scene, if hmap is not set.
See also:
getGraph(), generatePatchGraph(), getPatchGraph()

SoSeparator * TePatch::generateGraphFromSubMap const TeHeightMap map,
const SbVec2s &  min,
const SbVec2s &  max,
const SbBox2f &  area
[static, private]
 

The function creates scene graph of the specified area of height map given by the map parameter.

The parameters min and max specifies the rectangle of the height map that will be used for scene graph generation. The parameter area gives the world-space area that will be occupied by the resulting scene graph.

Please note that normal generation algorithm tries to access height map values one point over the rectangle specified by min and max parameters. If these values can not be accessed, the normals are computed without them, but this usually results in artefacts like visible seams between patches.

Parameters:
map Pointer to the source heightmap.
min Min corner of selected heightmap region.
max Max corner of selected heightmap region.
area World-space area that will be occupied by the scene graph.
Returns:
Scene graph that represents the terrain defined by selected heightmap values.

void TePatch::generateHMapFF WhichHMap  which,
const unsigned int  seed,
const int  num_faults,
const float  min_delta,
const float  max_delta
 

Generates heightmap of this patch using fault-formation algorithm.

Which height map will be generated is specified by the which parameter.

More details about how this algorithm works can be found at TeHeightMap::generate_FaultFormation().

Parameters:
which Which height map will be generated selector.
seed Random seed that defines terrain shape.
num_faults Number of faults to be generated (number of iterations).
min_delta Minimal fault height.
max_delta Maximal fault height.
See also:
WhichHMap, hmap, buildMap

SoSeparator * TePatch::generatePatchGraph  )  [private]
 

Generates scene graph of the patch.

Not all heightmap values will be used (only those, for that the normal can be computed) and therefore there will be gap between patches that has to be filled with seam.

Note, that hmap has to be set before calling this function. If it isn't set, empty scene graph is generated.

Returns:
Scene graph of the patch. Empty scene, if hmap is not set.
See also:
getPatchGraph()

SoSeparator * TePatch::generateSeamGraph const Direction  which  )  [private]
 

Generates scene graph of the selected seam.

If the seam heightmap is not set it tries to generate it, so it is not necessary to call generateSeamMap() before calling this function.

Parameters:
which Seam selector.
Returns:
Scene graph of the seam. NULL, if it was impossible to compute seam heightmap.
See also:
getSeamGraph()

SbBool TePatch::generateSeamMap const Direction  which  ) 
 

Validates seamMap pointer in desired direction if possible.

Tries to look for the desired map in the neighbours. If not found, tries to compute it and propagate the info to all interested neighbours. This assures that each seam map will be computed only once. User does not need to worry about the way how the data are obtained. This function says if the private seam map pointer is valid or not.

Note that properly set hmap attributes of all necessary neighbours are needed to succesfully complete this task.

Parameters:
which Seam map selector.
Returns:
TRUE if the seam map pointer is valid and the graph can be created.
See also:
seamMap, getSeamMap()

const SbBox2f & TePatch::getArea  )  const
 

Private attribute accessor.

Returns:
Rectangle area occupied by the scene graph.
See also:
area

TeHeightMap * TePatch::getBuildMap const int  i  ) 
 

Private attribute accessor.

Parameters:
i Build map selector (TePatch::WhichHMap should be used here).
Returns:
Pointer to the specified build map.
See also:
WhichHMap, buildMap, setBuildMap(), buildHMapFromBuildMaps()

const TeHeightMap * TePatch::getBuildMap const int  i  )  const
 

Private attribute accessor.

Parameters:
i Buildmap selector (TePatch::WhichHMap should be used here).
Returns:
Const pointer to the specified build map.
See also:
WhichHMap, buildMap, setBuildMap(), buildHMapFromBuildMaps()

TePatch * TePatch::getDetail const Direction  which  ) 
 

Private attribute accessor.

Parameters:
which Detail selector.
Returns:
Specified detail patch.
See also:
detail

TePatch::Direction TePatch::getDetailDirection const SbVec2f &  point  )  const
 

Documentation not available.

Todo:
More detailed documentation.

TePatch::Direction TePatch::getDirectionWithinParent  )  const
 

Documentation not available.

Todo:
More detailed documentation.

TePatch::Direction TePatch::getDirectionXFromVec const SbVec2f &  vec  )  [inline, static]
 

Computes the direction from the given vector.

Parameters:
vec Given vector.
Returns:
Direction the vector is pointing.

TeEngine * TePatch::getEngine  )  const
 

Private attribute accessor.

Returns:
Pointer to the attached engine.
See also:
engine, setEngine()

SoSeparator * TePatch::getGraph  ) 
 

High-level "raw" graph request.

All heightmap values will be used and therefore there won't be gap between patches but visible seam artefacts will be probably over the landscape. This function does NOT use caching in the TePatch::graph attribute.

This rendering mode is obsolete and is recommended to use getPatchGraph() and getSeamGraph() methods instead.

Returns:
"Raw" patch graph, or empty scene if height map is not set.
See also:
getPatchGraph()

TeHeightMap * TePatch::getHMap  ) 
 

Private attribute accessor.

Returns:
Pointer to the patch heightmap.
See also:
hmap, setHMap()

const TeHeightMap * TePatch::getHMap  )  const
 

Private attribute accessor.

Returns:
Const pointer to the patch heightmap.
See also:
hmap, setHMap()

int TePatch::getLevel  )  const
 

Gets level of the patch in the hierarchy.

Returns:
Patch level in the hierarchy.

Todo:
More detailed documentation.

int TePatch::getOppositeDirection const int  d  )  [inline, static]
 

Computes opposite direction to the one in d parameter.

When called with NORTH as an argument, returns SOUTH, when called with SOUTH_EAST returns NORTH_WEST etc., complies with TePatch::Direction enum values.

Parameters:
d Given direction.
Returns:
Opposite direction to d.

TePatch * TePatch::getParent  )  const
 

Private attribute accessor.

Returns:
Parent patch in the hierarchy.
See also:
parent

Todo:
More detailed documentation.

TePatch * TePatch::getPatch const SbVec2f &  pos,
const int  level,
PatchMissedPolicy  policy = CREATE
 

Documentation not available.

Todo:
More detailed documentation.

SoSeparator * TePatch::getPatchGraph  ) 
 

High-level graph request.

Only those heightmap values, for that we can compute normals will be used, and therefore a gap between patches will occure that has to be filled with seam. The seams may be obtained using getSeamGraph() method. Produced landscape won't have any artefacts along the seam borders then.

This function uses caching in the TePatch::graph attribute, so graph is generated only once and is stored for the next time it is needed. Then it will be available very quickly.

Returns:
Patch graph, or empty scene if height map is not set.
See also:
getSeamGraph()

TePatch * TePatch::getPatchHierarch const SbVec2f &  pos,
const int  level,
PatchMissedPolicy  policy = CREATE
[private]
 

Documentation not available.

Todo:
More detailed documentation.

TePatch * TePatch::getPatchHierarchRelative const SbVec2f &  pos,
const int  relativeLevel,
PatchMissedPolicy  policy = CREATE
[private]
 

Documentation not available.

Todo:
More detailed documentation.

TePatch * TePatch::getPatchRelative const SbVec2f &  pos,
const int  relativeLevel,
PatchMissedPolicy  policy = CREATE
 

Documentation not available.

Todo:
More detailed documentation.

Todo:
Make some optimization here using neighbour list.

SoSeparator * TePatch::getSeamGraph const Direction  which  ) 
 

High-level seam graph request.

Seams are used to fill gaps between patches that occure because of the normal problem when using getPatchGraph() method.

This function uses caching in the TePatch::seamGraph attribute, so graph is generated only once and is stored for the next time it is needed. Then it will be available very quickly.

Information about the seam is propagated to all affected neighbours allowing them to share the same data and never do the same work twice.

Returns:
Seam graph, or empty scene if seam's height map is not set.
See also:
getPatchGraph()

TeHeightMap * TePatch::getSeamMap const Direction  which  ) 
 

Private attribute accessor.

Parameters:
which Seam map selector.
Returns:
Pointer to the specified seam map.
See also:
seamMap, setSeamMap()

const TeHeightMap * TePatch::getSeamMap const Direction  which  )  const
 

Private attribute accessor.

Parameters:
which Seam map selector.
Returns:
Const pointer to the specified seam map.
See also:
seamMap, setSeamMap()

void TePatch::makeRoot const SbBox2f &  area,
TeEngine engine
 

Documentation not available.

Todo:
More detailed documentation.

void TePatch::prepareBuildMaps  ) 
 

High-level function that prepares all build maps.

Tries to find build maps in the neighbours. If map is not found, asks engine to generate new one.

See also:
buildMap, TeEngine::generateHMap(), buildHMapFromBuildMaps()

void TePatch::removeDetail TePatch patch  ) 
 

Documentation not available.

Todo:
More detailed documentation.

unsigned short TePatch::selectMaterial float  value  )  [static, private]
 

This function is used to select "colour" of the terrain of given height.

This function is for internal use only and uses #defines that can be found right above it in the source code.

Parameters:
value Number representing height of the point.
Returns:
Index to the material node.

Todo:
This function should NOT use #defined values. It should guess the "levels" somehow.

void TePatch::setBuildMap const int  i,
TeHeightMap hmap
 

Sets single build map.

This function checks whether the resolution of the heightmap hmap correspondes with the one set in the engine. The resolution must be equal to the one returned by TeEngine::getBuildMapResolution() function. If the resolution is incorrect, nothing happens.

Info is propagated to all existing neighbours.

Parameters:
i Buildmap selector (TePatch::WhichHMap should be used here).
hmap Pointer to the heightmap.
See also:
setBuildMaps(), WhichHMap, buildMap, getBuildMap(), buildHMapFromBuildMaps()

void TePatch::setBuildMaps TeHeightMap sw,
TeHeightMap se,
TeHeightMap nw,
TeHeightMap ne
 

Sets all build maps in a single step.

This function simply calls setBuildMap() four times. All restrictions on the heightmaps resolution are therefore applied too.

Parameters:
sw Pointer to the heightmap, it will become south-west build map.
se Pointer to the heightmap, it will become south-east build map.
nw Pointer to the heightmap, it will become north-west build map.
ne Pointer to the heightmap, it will become north-east build map.
See also:
buildMap, getBuildMap(), buildHMapFromBuildMaps()

void TePatch::setDetail const Direction  which,
TePatch patch
 

Documentation not available.

Todo:
More detailed documentation.

void TePatch::setEngine  ) 
 

Should set the private engine attribute.

This function is not implemented yet, it looks like we don't need it...

See also:
engine, getEngine()

Todo:
Not implemented yet. Consider removing it completely, because its work is done in constructor and changing attached engines at run-time will be strange hack.

void TePatch::setHMap TeHeightMap hmap  ) 
 

Sets private hmap attribute.

This function checks if the resolution of the heightmap hmap is the same as the one set in the engine. If it is not so, nothing happens and the warning is post. If there is already some heightmap set, it is deleted.

Parameters:
hmap Pointer to the heightmap.

Todo:
When the heightmap is being deleted, we probably should unref all scene graphs and delete the seam maps too.
See also:
hmap, getHMap()

void TePatch::setSeamMap const Direction  which,
TeHeightMap map
 

Sets private seam map attribute.

This function checks if the resolution of the heightmap map corresponds with the one set in the engine and the selected seam. If it is not so, nothing happens and the warning is post.

Parameters:
which Seam map selector.
map Pointer to the heightmap.
See also:
seamMap, getSeamMap()

Todo:
If there is already some seam map set, it should be deleted. It is similar to the TePatch::setHMap() function.

void TePatch::updateNeighbours  )  [private]
 

Updates local neighbour list and references in that neighbours too.

See also:
neighbour


Member Data Documentation

SbBox2f TePatch::area [private]
 

Patch area.

Defines its rectangle on the surface in the world-space coordinates.

See also:
getArea()

TeHeightMap* TePatch::buildMap[4] [private]
 

Pointers to 4 build-maps used to create final heightmap.

See also:
getBuildMap(), setBuildMap(), prepareBuildMaps(), buildHMapFromBuildMaps()

TePatch* TePatch::detail[4] [private]
 

Pointers to the detail patches.

Todo:
More detailed documentation.

TeEngine* TePatch::engine [private]
 

Pointer to the engine that manages this patch.

See also:
getEngine(), setEngine()

SoSeparator* TePatch::graph [private]
 

Patch scene graph cache.

See also:
getPatchGraph()

TeHeightMap* TePatch::hmap [private]
 

Pointer to the patch height map.

This map will be used when creating scene graph.

See also:
getHMap(), setHMap(), buildHMapFromBuildMaps()

TePatch* TePatch::neighbour[8] [private]
 

Pointers to all 8 possible neighbour of this patch.

These are used to obtain seam maps and to find already existing build maps.

TePatch* TePatch::parent [private]
 

Pointer to the parent patch in the patch hierarchy.

Todo:
More detailed documentation.

SoSeparator* TePatch::seamGraph[8] [private]
 

Seam graphs cache.

See also:
getSeamGraph()

TeHeightMap* TePatch::seamMap[8] [private]
 

Pointers to all 8 possible seam height maps.

These maps can be computed when all necessary neighbours' maps are available. These are used when creating seam scene graph.

See also:
getSeamMap(), setSeamMap(), generateSeamMap()


Generated on Sun May 8 16:45:07 2005 for TerrainEngine by Doxygen 1.4.1