Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase Class Reference

The database class that acquires and manages terrain data. More...

#include <PhxTerrainDatabase.h>

Inheritance diagram for Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase:

List of all members.

Public Types
typedef uint64_t	QuadIdentifier
	A code type that is used to identify quads within the database.
typedef uint32_t	ChildIndex
typedef float	HeightValue
Public Member Functions
virtual Vector3	rootCorner (QuadIdentifier identifier, ChildIndex which)=0
	Returns a corner of the root quad containing identifier.
virtual double	ellipsoidRadius (const Vector3 &v)=0
	Returns the radius of the "ellipsoid" beneath the vector v.
virtual Ptr< const Buffer< HeightValue > >	newHeightBuffer (QuadIdentifier identifier, uint32_t resolution)=0
virtual Ptr< const Buffer< uint8_t > >	newColorBuffer (QuadIdentifier identifier, uint32_t resolution)=0
virtual Ptr< const Buffer< uint8_t > >	newBandBuffer (QuadIdentifier identifier, const String &band, uint32_t resolution)=0
Static Public Member Functions
static bool	isRootIdentifier (QuadIdentifier identifier)
	Returns whether a valid identifier is a root identifier.
static QuadIdentifier	rootIdentifier (QuadIdentifier quad)
	Returns the root identifier contained in a quad identifier.
static QuadIdentifier	childIdentifier (QuadIdentifier parent, ChildIndex c)
	Returns the identifier for a child of parent.
static QuadIdentifier	parentIdentifier (QuadIdentifier quad)
	Returns the parent identifier of quad.
static Rectangle< float >	uvCoords (QuadIdentifier identifier)
	Computes the UV coordinates of a quad within its root quad.
Static Public Attributes
static const ChildIndex	LL = 0
static const ChildIndex	UL = 1
static const ChildIndex	LR = 2
static const ChildIndex	UR = 3
static const ChildIndex	CHILD_COUNT = 4
static const QuadIdentifier	INVALID_IDENTIFIER = ((uint64_t)-1)
	An identifier returned when an operation fails.
static const uint32_t	ROOT_IDENTIFIER_BITS = 24
	Every identifier is composed of a "root" identifier which is an even number of leading bits.
static const uint32_t	QUAD_IDENTIFIER_BITS = 64 - ROOT_IDENTIFIER_BITS
	The number of bits used to identify a quad within a tree.
static const QuadIdentifier	MIN_ROOT_IDENTIFIER = ((uint64_t)1)<<(ROOT_IDENTIFIER_BITS-2)
	Every root identifier must have a 1 in one of the two leading bits; this implies a minimum value of such an identifier.
static const QuadIdentifier	MAX_ROOT_IDENTIFIER = (((uint64_t)1)<<ROOT_IDENTIFIER_BITS)-1
	This is the largest possible root identifier, given the choice of ROOT_IDENTIFIER_BITS.

---

Detailed Description

The database class that acquires and manages terrain data.

The TerrainDatabase maintains all of the information for a terrain dataset. Each dataset is composed of a set of "root" level quadrangles stretched between four corner points. Each of these root quads is assigned an identifier. The root quads are then subdivided into four child quads, each of which has its own identifier derived from its parent's identifier. A local surface coordinate system is attached to each root quad. (0,0) corresponds to the "lower left" corner of the root quad, and (1,1) corresponds to the "upper right" corner. These designations are arbitrary, but consistent. Within the root quad, its 4 children share the interior point (0.5, 0.5) as their corner. We call these "UV coordinates", as they are like texture coordinates. One can use the uvCoords() method to find the UV coordinates of a quad, relative to the root quad, from its identifier.

This hierarchy of quads is a "forest" -- a collection of quad trees. Each identifier corresponds to a node in one of these trees, with a root identifier designating the root of a particular tree. The database implementation should respond quickly to requests for terrain information covering any of these quads.

The public interface provides a number of inline static methods, that are concurrently accessible, to allow the manipulation of the quad identifiers. The primary client of the database (typically the object that constructed the TerrainGeometry) also has the ability to perform queries using these codes, getting buffers of data in return.

---

Member Function Documentation

static QuadIdentifier Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::childIdentifier (  QuadIdentifier  parent, ChildIndex  c )  [inline, static]

Returns the identifier for a child of parent. Parameters: parent  The identifier of the parent quad. c  The index of the child. Returns: The identifier of child c of quad parent.

virtual double Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::ellipsoidRadius (  const Vector3 &  v  )  [pure virtual]

Returns the radius of the "ellipsoid" beneath the vector v. More accurately, this is the distance from the "mean sea level" surface at a point below v to the center of the planet. The surface defined by equal-radius points (as given by this function) need not necessarily be an ellipsoid. In practice, the internal database will choose a different surface to simplify some computations. Parameters: v  The query point. Returns: The distance of the origin from the "ellipsoid" surface beneath the point v.

static bool Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::isRootIdentifier (  QuadIdentifier  identifier  )  [inline, static]

Returns whether a valid identifier is a root identifier. Returns: True if no bits above the first ROOT_IDENTIFIER_BITS are set.

static QuadIdentifier Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::parentIdentifier (  QuadIdentifier  quad  )  [inline, static]

Returns the parent identifier of quad. Parameters: quad  The identifier for the quad whose parent identifier will be returned. Returns: The identifier for the parent of identifier, or INVALID_IDENTIFIER if identifier is a root identifier (i.e., it has no parent).

virtual Vector3 Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::rootCorner (  QuadIdentifier  identifier, ChildIndex  which )  [pure virtual]

Returns a corner of the root quad containing identifier. Specifically, each root quad has four corners (corresponding to the four children: LL, UL, LR, UR). This method determines the root identifier of identifier and then returns the corner point corresponding to child which. Note: The corner of the patch is an artificial location used for defining the terrain patches. It is not necessary a point on the terrain, or even a point on the underlying ellipsoid. Parameters: identifier  The identifier of the the quad whose root corner should be computed. which  The corner of the root quad to be returned. Returns: The Earth-Centered-Earth-Fixed coordinate of the requested corner.

static QuadIdentifier Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::rootIdentifier (  QuadIdentifier  quad  )  [inline, static]

Returns the root identifier contained in a quad identifier. Contained in the most significant nonzero bits, on 2-bit boundaries, of the identifier quad is the identifier of the root quad for the tree in which quad resides. This function retrieves this root identifier for any quad. Parameters: quad  The quad identifier whose root identifier should be retrieved. Returns: The root identifier for the tree containing quad. Note: If quad is not a valid identifier (i.e., it has value < MIN_ROOT_IDENTIFIER), this method simply returns quad.

static Rectangle<float> Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::uvCoords (  QuadIdentifier  identifier  )  [static]

Computes the UV coordinates of a quad within its root quad. Parameters: quad  The identifier of the quad. Returns: A Rectangle where (x1,y1) is the lower left UV coordinate and (x2,y2) is the upper right UV coordinate of the quad.

---

Member Data Documentation

const QuadIdentifier Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::MAX_ROOT_IDENTIFIER = (((uint64_t)1)<<ROOT_IDENTIFIER_BITS)-1 [static]

This is the largest possible root identifier, given the choice of ROOT_IDENTIFIER_BITS. This is essentially ROOT_IDENTIFIER_BITS 1's in the QuadIdentifier's LSBs. Hence, it can be used as a mask to determine if an identifier is a root identifier: if !(identifier & ~MAX_ROOT_IDENTIFIER) then identifier is a root identifier. Use the isRootIdentifier() call for this test.

const QuadIdentifier Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::MIN_ROOT_IDENTIFIER = ((uint64_t)1)<<(ROOT_IDENTIFIER_BITS-2) [static]

Every root identifier must have a 1 in one of the two leading bits; this implies a minimum value of such an identifier. The "leading 1 requirement" guarantees that, after shifts by two bits, there is no ambiguitity with identifiers starting at another root identifier. Thus, the smallest root identifier is one that has a '1' in the second bit of its most-significant two bits.

const uint32_t Phx::GraphicsEngine::TerrainGeometry::TerrainDatabase::ROOT_IDENTIFIER_BITS = 24 [static]

Every identifier is composed of a "root" identifier which is an even number of leading bits. The choice of root identifier length is based on the underlying system. IEEE floats allow precision of 2^-23, and hence 23 levels per tree (if implemented perfectly). For elbow room, we allow 20 levels per tree, requiring 40 bits for the identifier of each tree. Thus, we use the remaining 24 bits for the root identifier, which designates the tree to which an identifier pertains.

---

The documentation for this class was generated from the following file:

• PhxTerrainDatabase.h

---