Cubemap

Description

static class Tinman.Terrain.Mapping.Cubemap

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

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+  |
+--------------------+--------------------+--------------------+--------------------+

Public / Constants

FirstFace


public constant FirstFace → (CubemapFace.PosX:CubemapFace)

The CubemapFace with minimal ordinal value.

Use this constant for iterating through cubemap faces.

See also

Cubemap.LastFace

LastFace


public constant LastFace → (CubemapFace.NegZ:CubemapFace)

The CubemapFace with maximum ordinal value.

Use this constant for iterating through cubemap faces.

Public / Methods

CubeToFace

9 overloads


[Pure]
public static method CubeToFace1 → (3)

bounds in : Box3I

The box using cubemap coordinates.

face in : CubemapFace

The cubemap face.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceRect

The resulting intersection rectangle using cubemap face coordinates.

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


[Pure]
public static method CubeToFace2 → (2)

coords in : Vec3D

The unit cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceCoordsD

The resulting unit cubemap face coordinates.

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


[Pure]
public static method CubeToFace3 → (4)

in : float64

X-component of unit cubemap coordinates.

in : float64

Y-component of unit cubemap coordinates.

in : float64

Z-component of unit cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceCoordsD

The resulting unit cubemap face coordinates.

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


[Pure]
public static method CubeToFace4 → (2)

coords in : Vec3I

The unit cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceCoordsI

The resulting unit cubemap face coordinates.

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


[Pure]
public static method CubeToFace5 → (4)

in : int32

X-component of unit cubemap coordinates.

in : int32

Y-component of unit cubemap coordinates.

in : int32

Z-component of unit cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceCoordsI

The resulting unit cubemap face coordinates.

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


public static method CubeToFace6 → (3)

coords in : Vec3I

The cubemap coordinates.

face in : CubemapFace

The cubemap face.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceCoordsI

The cubemap face X- and Y-coordinates or CubemapFaceCoordsI.Undefined if coords in do not lie on face in.

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


public static method CubeToFace7 → (5)

in : int32

Cubemap X-coordinate.

in : int32

Cubemap Y-coordinate.

in : int32

Cubemap Z-coordinate.

face in : CubemapFace

The cubemap face.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceCoordsI

The cubemap face X- and Y-coordinates or CubemapFaceCoordsI.Undefined if in, in and in do not lie on face in.

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


public static method CubeToFace8 → (3)

coords in : Vec3D

The cubemap coordinates.

face in : CubemapFace

The cubemap face.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceCoordsD

The cubemap face X- and Y-coordinates or CubemapFaceCoordsI.Undefined if coords in do not lie on face in.

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


public static method CubeToFace9 → (5)

in : float64

Cubemap X-coordinate.

in : float64

Cubemap Y-coordinate.

in : float64

Cubemap Z-coordinate.

face in : CubemapFace

The cubemap face.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFaceCoordsD

The cubemap face X- and Y-coordinates or CubemapFaceCoordsI.Undefined if in, in and in do not lie on face in.

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

CubeToGeographic

2 overloads


[Pure]
public static method CubeToGeographic1 → (2)

coords in : Vec3D

The cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec2D

The geographic longitude (Vec2D.X) and latitude (Vec2D.Y), in radians.

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


[Pure]
public static method CubeToGeographic2 → (4)

in : float64

The cubemap X-coordinate.

in : float64

The cubemap Y-coordinate.

in : float64

The cubemap Z-coordinate.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec2D

The geographic longitude (Vec2D.X) and latitude (Vec2D.Y), in radians.

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

CubeToLinear

2 overloads


[Pure]
public static method CubeToLinear1 → (2)

coords in : Vec3I

The cubemap coordinates.

in : int32

Maximum cubemap coordinate. Must be less than or equal to 18918.

returns → int32

The linear storage index.

Translates the given cubemap coordinates into a linear storage index.


[Pure]
public static method CubeToLinear2 → (4)

in : int32

The cubemap X-coordinate.

in : int32

The cubemap X-coordinate.

in : int32

The cubemap X-coordinate.

in : int32

Maximum cubemap coordinate. Must be less than or equal to 18918.

returns → int32

The linear storage offset.

Translates the given cubemap coordinates into a linear storage index.

CubeToVector

2 overloads


[Pure]
public static method CubeToVector1 → (2)

coords in : Vec3D

The cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3D

The unit-length direction vector.

Computes a direction vector from the given cubemap coordinates.


[Pure]
public static method CubeToVector2 → (4)

in : float64

The cubemap X-coordinate.

in : float64

The cubemap Y-coordinate.

in : float64

The cubemap Z-coordinate.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3D

The unit-length direction vector.

Computes a direction vector from the given cubemap coordinates.

FaceToCube

5 overloads


[Pure]
public static method FaceToCube1 → (2)

rect in : CubemapFaceRect

The cubemap face rectangle.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Box3I

The bounding box in cubemap coordinates.

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

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


[Pure]
public static method FaceToCube2 → (2)

coords in : CubemapFaceCoordsI

The unit cubemap face coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3I

The resulting unit cubemap coordinates.

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

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


[Pure]
public static method FaceToCube3 → (2)

coords in : CubemapFaceCoordsD

The unit cubemap face coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3D

The resulting unit cubemap coordinates.

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

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


[Pure]
public static method FaceToCube4 → (4)

faceX in : int32

Unit cubemap face X-coordinate.

faceY in : int32

Unit cubemap face Y-coordinate.

face in : CubemapFace

Cubemap face index (see Face* constants).

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3I

The resulting unit cubemap coordinates.

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

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

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


[Pure]
public static method FaceToCube5 → (4)

faceX in : float64

Unit cubemap face X-coordinate.

faceY in : float64

Unit cubemap face Y-coordinate.

face in : CubemapFace

Cubemap face index (see Face* constants).

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3D

The resulting unit cubemap coordinates.

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

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

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

GeographicToCube

2 overloads


[Pure]
public static method GeographicToCube1 → (2)

geog in : Vec2D

The geographic longitude (Vec2D.X) and latitude (Vec2D.Y) angles, in radians.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3D

The cubemap coordinates.

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


[Pure]
public static method GeographicToCube2 → (3)

longitude in : float64

The geographic longitude angle, in radians.

latitude in : float64

The geographic latitude angle, in radians.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3D

The cubemap coordinates.

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

GetFaceBounds


[Pure]
public static method GetFaceBounds → (2)

face in : CubemapFace

The cubemap face.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Box3I

The face bounds in cubemap coordinates.

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

GetFaceName


[Pure]
public static method GetFaceName → (1)

face in : CubemapFace

The cubemap face.

returns → string

The human-readable name.

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

GetTangentSpace


[Pure]
public static method GetTangentSpace → (3)

face in : CubemapFace

The cubemap face (see class constants).

tangentFaceX out : Vec3I

Output for tangent face coefficient vector (see remarks).

tangentFaceY out : Vec3I

Output for tangent face coefficient vector (see remarks).

Returns the tangent space orientation for a given cubemap face.

Given the three heightmap space tangent vectors tx, ty and tz (see Semantic.TangentX, Semantic.TangentY, Semantic.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


[Pure]
public static method LinearCount → (1)

in : int32

Maximum cubemap coordinate. Must be less than or equal to 18918.

returns → int32

xgte

Returns the exclusive upper bound for linear storage indices.

LinearToCube


[Pure]
public static method LinearToCube → (2)

idx in : int32

The linear storage index.

in : int32

Maximum cubemap coordinate. Must be less than or equal to 18918.

returns → Vec3I

The cubemap coordinates.

Translates the given linear storage index to cubemap coordinates.

PackCube

2 overloads


[Pure]
public static method PackCube1 → (2)

coords in : Vec3I

The cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → int64

The packed value.

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


[Pure]
public static method PackCube2 → (4)

in : int32

The cubemap X-coordinate.

in : int32

The cubemap Y-coordinate.

in : int32

The cubemap Z-coordinate.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → int64

The packed value.

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

PackFace

2 overloads


[Pure]
public static method PackFace1 → (1)

coords in : CubemapFaceCoordsI

The cubemap face coordinates.

returns → int64

The packed value.

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


[Pure]
public static method PackFace2 → (3)

faceX in : int32

The face X-coordinate.

faceY in : int32

The face Y-coordinate.

face in : CubemapFace

The cubemap face.

returns → int64

The packed value.

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

SameFace

4 overloads


[Pure]
public static method SameFace1 → (3)

in : Vec3I

First cubemap coordinates.

in : Vec3I

Second cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFace

The common cubemap face or CubemapFace.None if the cubemap faces are different.

Checks if in and in lie on the same cubemap face.


[Pure]
public static method SameFace2 → (3)

in : Vec3D

First cubemap coordinates.

in : Vec3D

Second cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFace

The common cubemap face or CubemapFace.None if the cubemap faces are different.

Checks if in and in lie on the same cubemap face.


[Pure]
public static method SameFace3 → (4)

in : Vec3I

First cubemap coordinates.

in : Vec3I

Second cubemap coordinates.

in : Vec3I

Third cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFace

The common cubemap face or CubemapFace.None if the cubemap faces are different.

Checks if in, in and in lie on the same cubemap face.


[Pure]
public static method SameFace4 → (4)

in : Vec3D

First cubemap coordinates.

in : Vec3D

Second cubemap coordinates.

in : Vec3D

Third cubemap coordinates.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → CubemapFace

The common cubemap face or CubemapFace.None if the cubemap faces are different.

Checks if in, in and in lie on the same cubemap face.

ToFaceDecompose


public static method ToFaceDecompose → (5)

face in : CubemapFace

The cubemap face.

in : int32

Maximum cubemap coordinate.

offset out : Vec2I

Output for cubemap face offset vector.

out : Vec3I

Output dot product vector for extracting the cubemap face X-axis.

out : Vec3I

Output dot product vector for extracting the cubemap face Y-axis.

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

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


[Pure]
public static method UnpackCube → (2)

value in : int64

The 63-bit integer value.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3I

The resulting cubemap coordinates.

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

UnpackFace


[Pure]
public static method UnpackFace → (1)

value in : int64

The 63-bit integer value.

returns → CubemapFaceCoordsI

The unpacked CubemapFaceCoordsI value.

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

VectorToCube

2 overloads


[Pure]
public static method VectorToCube1 → (2)

in : Vec3D

The direction vector.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3D

The normalized cubemap coordinates.

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


[Pure]
public static method VectorToCube2 → (4)

in : float64

X-component of direction vector.

in : float64

Y-component of direction vector.

in : float64

Z-component of direction vector.

opt : int32 = HeightmapsUtil.MaxCoord

Maximum cubemap coordinate.

returns → Vec3D

The normalized cubemap coordinates.

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

Configuration

ConfigCubemapFace


public static attribute ConfigCubemapFace → (get)

value : IConfigurator<CubemapFace>

[not-null]
The configurator object.

The configurator object for this type.