TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

class Cubemap in Tinman.Terrain.Mapping

The Cubemap class implements the concept of cubemaps as used by Tinman for Cube terrains.

static class Cubemap  

Remarks

The following figure shows the relation between cubemap coordinates and cubemap face coordinates: 

                                Y-  Z+        E-------F
[0,0,n]        [n,0,n]           | /         /.      /|
   E ------------ F              |/         / .     / |
   |              |         X- --+-- X+    A-------B  |
   |  o-------->  |             /|         |  G....|..H
   |  |      +fx  |            / |         | .     | /
   |  |   Y-      |          Z-  Y+        |.      |/
   |  |           |                        C-------D
   |  V +fy       |
[0,0,0]        [n,0,0]        [n,0,n]        [0,0,n]        [0,0,0]
   A ------------ B ------------ F ------------ E ------------ A
   |              |              |              |              |
   |  o-------->  |  o-------->  |  o-------->  |  o-------->  |
   |  |      +fx  |  |      +fx  |  |      +fx  |  |      +fx  |
   |  |   Z-      |  |   X+      |  |   Z+      |  |   X-      |
   |  |           |  |           |  |           |  |           |
   |  V +fy       |  V +fy       |  V +fy       |  V +fy       |
   |              |              |              |              |
   C ------------ D ------------ H ------------ G ------------ C
[0,n,0]        [n,n,0]        [n,n,n]        [0,n,n]        [0,n,0]
   |  o-------->  |
   |  |      +fx  |
   |  |   Y+      |         n       := Maximum cubemap coordinate
   |  |           |         [x,y,z] := Cubemap coordinates
   |  V +fy       |         fx      := Positive cubemap face X-axis
   |              |         fy      := Positive cubemap face Y-axis
   G ------------ H
[0,n,n]        [n,n,n]
The cross-product between the cubemap face X-axis and Y-axis point towards the interior of the cubemap cube. This figure shows the possible cubemap wrapping cases (along edges and corners): 
+--------------------+--------------------+--------------------+--------------------+
|    [E]  -fy    Y-  |    [F]  +fx    X+  |    [A]  -fy    X-  |    [B]  -fy    X+  |
|      \   \         |      \   \         |      \   \         |      \   \         |
|  -fx  \   o-- +fx  |  -fy  \   o-- +fy  |  -fy  \   o-- -fx  |  -fy  \   o-- +fx  |
|    \   \           |    \   \           |    \   \           |    \   \           |
|  X- o  [A]----[B]  |  Y- o  [B]----[D]  |  Z- o  [C]----[G]  |  Z- o  [D]----[H]  |
|    /   /           |    /   /           |    /   /           |    /   /           |
|  +fy  /   o-- +fx  |  -fx  /   o-- +fy  |  +fx  /   o-- +fy  |  -fx  /   o-- +fy  |
|      /   /         |      /   /         |      /   /         |      /   /         |
|    [C]  +fy    Z-  |    [A]  -fx    Z-  |    [D]  +fx    Y+  |    [C]  -fx    Y+  |
+--------------------+--------------------+--------------------+--------------------+
|    [G]  +fy    Z+  |    [E]  +fx    Z+  |    [E]  -fy    Z+  |    [F]  -fy    X+  |
|      \   \         |      \   \         |      \   \         |      \   \         |
|  +fy  \   o-- -fx  |  -fx  \   o-- +fy  |  -fy  \   o-- -fx  |  -fy  \   o-- -fx  |
|    \   \           |    \   \           |    \   \           |    \   \           |
|  X- o  [E]----[F]  |  Y- o  [F]----[H]  |  X- o  [G]----[H]  |  Z+ o  [H]----[D]  |
|    /   /           |    /   /           |    /   /           |    /   /           |
|  +fx  /   o-- +fx  |  +fy  /   o-- +fy  |  +fx  /   o-- +fx  |  +fx  /   o-- -fy  |
|      /   /         |      /   /         |      /   /         |      /   /         |
|    [A]  +fy    Y-  |    [B]  -fx    X+  |    [C]  -fy    Y+  |    [G]  -fx    Y+  |
+--------------------+--------------------+--------------------+--------------------+

Configuration

ConfigCubemapFace

The configurator object for this type.

public static readonly field ConfigCubemapFace
type IConfigurator<CubemapFace>

Public / Constants

FirstFace

The CubemapFace with minimal ordinal value.

public constant FirstFace = CubemapFace.PosX
type CubemapFace

Remarks:

Use this constant for iterating through cubemap faces.

See also:

LastFace

LastFace

The CubemapFace with maximum ordinal value.

public constant LastFace = CubemapFace.NegZ
type CubemapFace

Remarks:

Use this constant for iterating through cubemap faces.

See also:

FirstFace

Public / Methods

CubeToFace

Converts the given set of unit cubemap coordinates to unit cubemap face coordinates.

[Pure]
public static method CubeToFace (Vec3D coords, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceCoordsD
params coords The unit cubemap coordinates.
  n Maximum cubemap coordinate.
returns The resulting unit cubemap face coordinates.

Converts the given set of unit cubemap coordinates to unit cubemap face coordinates.

[Pure]
public static method CubeToFace (Vec3I coords, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceCoordsI
params coords The unit cubemap coordinates.
  n Maximum cubemap coordinate.
returns The resulting unit cubemap face coordinates.

Intersects the given box with a cubemap face and returns the resulting rectangle in cubemap face coordinates.

[Pure]
public static method CubeToFace (Box3I bounds, CubemapFace face, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceRect
params bounds The box using cubemap coordinates.
  face The cubemap face.
  n Maximum cubemap coordinate.
returns The resulting intersection rectangle using cubemap face coordinates.

Translates the given cubemap coordinates into cubemap face coordinates (if possible).

public static method CubeToFace (Vec3I coords, CubemapFace face, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceCoordsI
params coords The cubemap coordinates.
  face The cubemap face.
  n Maximum cubemap coordinate.
returns The cubemap face X- and Y-coordinates or Undefined if coords do not lie on face.

Translates the given cubemap coordinates into cubemap face coordinates (if possible).

public static method CubeToFace (Vec3D coords, CubemapFace face, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceCoordsD
params coords The cubemap coordinates.
  face The cubemap face.
  n Maximum cubemap coordinate.
returns The cubemap face X- and Y-coordinates or Undefined if coords do not lie on face.

Converts the given set of unit cubemap coordinates to unit cubemap face coordinates.

[Pure]
public static method CubeToFace (float64 x, float64 y, float64 z, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceCoordsD
params x X-component of unit cubemap coordinates.
  y Y-component of unit cubemap coordinates.
  z Z-component of unit cubemap coordinates.
  n Maximum cubemap coordinate.
returns The resulting unit cubemap face coordinates.

Converts the given set of unit cubemap coordinates to unit cubemap face coordinates.

[Pure]
public static method CubeToFace (int32 x, int32 y, int32 z, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceCoordsI
params x X-component of unit cubemap coordinates.
  y Y-component of unit cubemap coordinates.
  z Z-component of unit cubemap coordinates.
  n Maximum cubemap coordinate.
returns The resulting unit cubemap face coordinates.

Translates the given cubemap coordinates into cubemap face coordinates (if possible).

public static method CubeToFace (int32 x, int32 y, int32 z, CubemapFace face, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceCoordsI
params x Cubemap X-coordinate.
  y Cubemap Y-coordinate.
  z Cubemap Z-coordinate.
  face The cubemap face.
  n Maximum cubemap coordinate.
returns The cubemap face X- and Y-coordinates or Undefined if x, y and z do not lie on face.

Translates the given cubemap coordinates into cubemap face coordinates (if possible).

public static method CubeToFace (float64 x, float64 y, float64 z, CubemapFace face, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFaceCoordsD
params x Cubemap X-coordinate.
  y Cubemap Y-coordinate.
  z Cubemap Z-coordinate.
  face The cubemap face.
  n Maximum cubemap coordinate.
returns The cubemap face X- and Y-coordinates or Undefined if x, y and z do not lie on face.

CubeToGeographic

Computes geographic coordinates (i.e. latitude and longitude) from the given cubemap coordinates.

[Pure]
public static method CubeToGeographic (Vec3D coords, int32 n = HeightmapsUtil.MaxCoord)
type Vec2D
params coords The cubemap coordinates.
  n Maximum cubemap coordinate.
returns The geographic longitude (X) and latitude (Y), in radians.

Computes geographic coordinates (i.e. latitude and longitude) from the given cubemap coordinates.

[Pure]
public static method CubeToGeographic (float64 x, float64 y, float64 z, int32 n = HeightmapsUtil.MaxCoord)
type Vec2D
params x The cubemap X-coordinate.
  y The cubemap Y-coordinate.
  z The cubemap Z-coordinate.
  n Maximum cubemap coordinate.
returns The geographic longitude (X) and latitude (Y), in radians.

CubeToLinear

Translates the given cubemap coordinates into a linear storage index.

[Pure]
public static method CubeToLinear (Vec3I coords, int32 n)
type int32
params coords The cubemap coordinates.
  n Maximum cubemap coordinate. Must be less than or equal to 18918.
returns The linear storage index.

See also:

LinearCount

Translates the given cubemap coordinates into a linear storage index.

[Pure]
public static method CubeToLinear (int32 x, int32 y, int32 z, int32 n)
type int32
params x The cubemap X-coordinate.
  y The cubemap X-coordinate.
  z The cubemap X-coordinate.
  n Maximum cubemap coordinate. Must be less than or equal to 18918.
returns The linear storage offset.

See also:

LinearCount

CubeToVector

Computes a direction vector from the given cubemap coordinates.

[Pure]
public static method CubeToVector (Vec3D coords, int32 n = HeightmapsUtil.MaxCoord)
type Vec3D
params coords The cubemap coordinates.
  n Maximum cubemap coordinate.
returns The unit-length direction vector.

Computes a direction vector from the given cubemap coordinates.

[Pure]
public static method CubeToVector (float64 x, float64 y, float64 z, int32 n = HeightmapsUtil.MaxCoord)
type Vec3D
params x The cubemap X-coordinate.
  y The cubemap Y-coordinate.
  z The cubemap Z-coordinate.
  n Maximum cubemap coordinate.
returns The unit-length direction vector.

FaceToCube

Computes the bounding box in cubemap coordinates for the given bounding box in cubemap face coordinates.

[Pure]
public static method FaceToCube (CubemapFaceRect rect, int32 n = HeightmapsUtil.MaxCoord)
type Box3I
params rect The cubemap face rectangle.
  n Maximum cubemap coordinate.
returns The bounding box in cubemap coordinates.

Remarks:

The given cubemap face coordinates are allowed to lie outside the face bounds along one dimension; proper wrapping will be performed automatically.

Converts the given set of unit cubemap face coordinates to unit cubemap coordinates.

[Pure]
public static method FaceToCube (CubemapFaceCoordsI coords, int32 n = HeightmapsUtil.MaxCoord)
type Vec3I
params coords The unit cubemap face coordinates.
  n Maximum cubemap coordinate.
returns The resulting unit cubemap coordinates.

Remarks:

The given cubemap face coordinates are allowed to lie outside the face bounds along one dimension; proper wrapping will be performed automatically.

Converts the given set of unit cubemap face coordinates to unit cubemap coordinates.

[Pure]
public static method FaceToCube (CubemapFaceCoordsD coords, int32 n = HeightmapsUtil.MaxCoord)
type Vec3D
params coords The unit cubemap face coordinates.
  n Maximum cubemap coordinate.
returns The resulting unit cubemap coordinates.

Remarks:

The given cubemap face coordinates are allowed to lie outside the face bounds along one dimension; proper wrapping will be performed automatically.

Converts the given set of unit cubemap face coordinates to unit cubemap coordinates.

[Pure]
public static method FaceToCube (int32 faceX, int32 faceY, CubemapFace face, int32 n = HeightmapsUtil.MaxCoord)
type Vec3I
params faceX Unit cubemap face X-coordinate.
  faceY Unit cubemap face Y-coordinate.
  face Cubemap face index (see Face* constants).
  n Maximum cubemap coordinate.
returns The resulting unit cubemap coordinates.

Remarks:

The given cubemap face coordinates are allowed to lie outside the face bounds along one dimension; proper wrapping will be performed automatically.

If faceX and/or faceY are less than -n or greater than 2*n, the method will return Zero.

Converts the given set of unit cubemap face coordinates to unit cubemap coordinates.

[Pure]
public static method FaceToCube (float64 faceX, float64 faceY, CubemapFace face, int32 n = HeightmapsUtil.MaxCoord)
type Vec3D
params faceX Unit cubemap face X-coordinate.
  faceY Unit cubemap face Y-coordinate.
  face Cubemap face index (see Face* constants).
  n Maximum cubemap coordinate.
returns The resulting unit cubemap coordinates.

Remarks:

The given cubemap face coordinates are allowed to lie outside the face bounds along one dimension; proper wrapping will be performed automatically.

If faceX and/or faceY are less than -n or greater than 2*n, the method will return Undefined.

GeographicToCube

Computes cubemap coordinates from the given geographic coordinates (i.e. latitude and longitude).

[Pure]
public static method GeographicToCube (Vec2D geog, int32 n = HeightmapsUtil.MaxCoord)
type Vec3D
params geog The geographic longitude (X) and latitude (Y) angles, in radians.
  n Maximum cubemap coordinate.
returns The cubemap coordinates.

Computes cubemap coordinates from the given geographic coordinates (i.e. latitude and longitude).

[Pure]
public static method GeographicToCube (float64 longitude, float64 latitude, int32 n = HeightmapsUtil.MaxCoord)
type Vec3D
params longitude The geographic longitude angle, in radians.
  latitude The geographic latitude angle, in radians.
  n Maximum cubemap coordinate.
returns The cubemap coordinates.

GetFaceBounds

Returns the bounds of the given cubemap face in cubemap coordinates.

[Pure]
public static method GetFaceBounds (CubemapFace face, int32 n = HeightmapsUtil.MaxCoord)
type Box3I
params face The cubemap face.
  n Maximum cubemap coordinate.
returns The face bounds in cubemap coordinates.

GetFaceName

Returns the human-readable name of the given cubemap face.

[Pure]
public static method GetFaceName (CubemapFace face)
type string
params face The cubemap face.
returns [not-null] The human-readable name.

GetTangentSpace

Returns the tangent space orientation for a given cubemap face.

[Pure]
public static method GetTangentSpace (CubemapFace face, out Vec3I tangentFaceX, out Vec3I tangentFaceY)
params face The cubemap face (see class constants).
  tangentFaceX Output for tangent face coefficient vector (see remarks).
  tangentFaceY Output for tangent face coefficient vector (see remarks).

Remarks:

Given the three heightmap space tangent vectors tx, ty and tz (see TangentX, TangentY, TangentZ) the cubemap face tangent vectors tix and tiy for a cubemap face f can be computed as follows: 

tix =   tx * tangentFaceX.X
      + ty * tangentFaceX.Y
      + tz * tangentFaceX.Z

tiy =   tx * tangentFaceY.X
      + ty * tangentFaceY.Y
      + tz * tangentFaceY.Z

LinearCount

Returns the exclusive upper bound for linear storage indices.

[Pure]
public static method LinearCount (int32 n)
type int32
params n Maximum cubemap coordinate. Must be less than or equal to 18918.
returns xgte

LinearToCube

Translates the given linear storage index to cubemap coordinates.

[Pure]
public static method LinearToCube (int32 idx, int32 n)
type Vec3I
params idx The linear storage index.
  n Maximum cubemap coordinate. Must be less than or equal to 18918.
returns The cubemap coordinates.

PackCube

Packs the given cubemap face coordinates into a single 63-bit value.

[Pure]
public static method PackCube (Vec3I coords, int32 n = HeightmapsUtil.MaxCoord)
type int64
params coords The cubemap coordinates.
  n Maximum cubemap coordinate.
returns [>=0] The packed value.

Packs the given cubemap face coordinates into a single 63-bit value.

[Pure]
public static method PackCube (int32 x, int32 y, int32 z, int32 n = HeightmapsUtil.MaxCoord)
type int64
params x The cubemap X-coordinate.
  y The cubemap Y-coordinate.
  z The cubemap Z-coordinate.
  n Maximum cubemap coordinate.
returns [>=0] The packed value.

PackFace

Packs the given cubemap face coordinates into a single 63-bit value.

[Pure]
public static method PackFace (CubemapFaceCoordsI coords)
type int64
params coords The cubemap face coordinates.
returns [>=0] The packed value.

Packs the given cubemap face coordinates into a single 63-bit value.

[Pure]
public static method PackFace (int32 faceX, int32 faceY, CubemapFace face)
type int64
params faceX The face X-coordinate.
  faceY The face Y-coordinate.
  face The cubemap face.
returns [>=0] The packed value.

SameFace

Checks if a and b lie on the same cubemap face.

[Pure]
public static method SameFace (Vec3I a, Vec3I b, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFace
params a First cubemap coordinates.
  b Second cubemap coordinates.
  n Maximum cubemap coordinate.
returns The common cubemap face or None if the cubemap faces are different.

Checks if a and b lie on the same cubemap face.

[Pure]
public static method SameFace (Vec3D a, Vec3D b, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFace
params a First cubemap coordinates.
  b Second cubemap coordinates.
  n Maximum cubemap coordinate.
returns The common cubemap face or None if the cubemap faces are different.

Checks if a, b and c lie on the same cubemap face.

[Pure]
public static method SameFace (Vec3I a, Vec3I b, Vec3I c, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFace
params a First cubemap coordinates.
  b Second cubemap coordinates.
  c Third cubemap coordinates.
  n Maximum cubemap coordinate.
returns The common cubemap face or None if the cubemap faces are different.

Checks if a, b and c lie on the same cubemap face.

[Pure]
public static method SameFace (Vec3D a, Vec3D b, Vec3D c, int32 n = HeightmapsUtil.MaxCoord)
type CubemapFace
params a First cubemap coordinates.
  b Second cubemap coordinates.
  c Third cubemap coordinates.
  n Maximum cubemap coordinate.
returns The common cubemap face or None if the cubemap faces are different.

ToFaceDecompose

Returns the decomposition of the transformation from cubemap coordinate to cubemap face coordinates.

public static method ToFaceDecompose (CubemapFace face, int32 n, out Vec2I offset, out Vec3I x, out Vec3I y)
params face The cubemap face.
  n Maximum cubemap coordinate.
  offset Output for cubemap face offset vector.
  x Output dot product vector for extracting the cubemap face X-axis.
  y Output dot product vector for extracting the cubemap face Y-axis.

Remarks:

Cubemap face coordinates can be computed from cubemap coordinates as follows: 

cube : cubemap coordinates (X, Y, Z)
face : cubemap face coordinates (X, Z)

face.X := offset.X + dot(x, cube)
face.Y := offset.Y + dot(y, cube)
where offset, x and y are computed by this method.

UnpackCube

Unpacks a set of cubemap coordinates from the given 63-bit integer value.

[Pure]
public static method UnpackCube (int64 value, int32 n = HeightmapsUtil.MaxCoord)
type Vec3I
params value The 63-bit integer value.
  n Maximum cubemap coordinate.
returns The resulting cubemap coordinates.

UnpackFace

Unpacks a set of cubemap face coordinates from the given 63-bit integer value.

[Pure]
public static method UnpackFace (int64 value)
type CubemapFaceCoordsI
params value The 63-bit integer value.
returns The unpacked CubemapFaceCoordsI value.

VectorToCube

Computes a set of normalized cubemap coordinates from the given direction vector.

[Pure]
public static method VectorToCube (Vec3D v, int32 n = HeightmapsUtil.MaxCoord)
type Vec3D
params v The direction vector.
  n Maximum cubemap coordinate.
returns The normalized cubemap coordinates.

Computes a set of normalized cubemap coordinates from the given direction vector.

[Pure]
public static method VectorToCube (float64 x, float64 y, float64 z, int32 n = HeightmapsUtil.MaxCoord)
type Vec3D
params x X-component of direction vector.
  y Y-component of direction vector.
  z Z-component of direction vector.
  n Maximum cubemap coordinate.
returns The normalized cubemap coordinates.
Tinman 3D SDK v1.0 | info@tinman3d.com | Copyright © 2012 - 2017 Matthias Englert, Fulda (Germany)