ColorCube
Description
The ColorCube class is used to create mipmapped cubemap textures that properly wrap around between faces and conserve energy during downsampling.
Upon creation, a color cube may be put into edge fixup mode, which affects the cubemap rasterization model, which in turn needs to be taken into account by GPU shaders:
edgeFixup = true edgeFixup = false +---+---+---+---+ +-o-+-o-+-o-+-o-+ | o | o | o | o | o o +---+---+---+---+ + + | o | | o | o o o := texel center +---+ # +---+ + # + | o | | o | o o # := ray origin +---+---+---+---+ + + | o | o | o | o | o o +---+---+---+---+ +-o-+-o-+-o-+-o-+ \_______________/ \___/ cube size = 4 texel
For each cubemap face texel, a ray from the origin towards the texel center is generated and then used to compute a texel value, for example by sampling an environment map (see IEnvironmentMap). With edge fixup, adjacent texels on different cubemap faces will be identical and GPU shaders need to adjust texture coordinates before sampling, by scaling the two non-principal texture coordinate axes by 1 - 1 / cubeSize^2. Without edge fixup, adjacent texels may be different and GPU shaders may use the original texture coordinates. The former case is necessary if the GPU does not support seamless cubemap filtering (see IGraphicsContext.IsCubemapSeamless) and the latter case is applicable if seamless cubemap filtering is supported.
Public / Methods
Get
Computes an average sample value for the given output cube size.
The returned samples have pixel-is-area semantic:
0 1 2 3 4 5 6 7 8 pixel-is-point: Size, here 9
+---+---+---+---+---+---+---+---+
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | pixel-is-area: N = Size - 1, here 8
+---+---+---+---+---+---+---+---+
\_______|_______|_______|_______/ block size: N / count, here 2
0 1 2 3 block coordinate: 0..count-1, here 0..3
Load
Loads an image onto the given cubemap face.
Tinman cubemaps are right-handed (see RHS below), so they need to be mapped to left-handed cubemap textures (see LHS below), as used by Direct3D and OpenGL. The center of each cubemap faces has an associated LatLon value. Also, the sky zenith 90° is at the center of the Y- face, see ILightProvider.LightAltitude.
Face | U-Axis | V-Axis
| LHS / RHS | LHS / RHS
-----+-----------+----------
X- | +z / -z | -y / +y
X+ | -z / +z | -y / +y
Y- | +x / +x | -z / -z
Y+ | +x / +x | +z / +z
Z- | -x / +x | -y / +y
Z+ | +x / -x | -y / +y
Tinman cubemap:
Cubemap
Direct3D cubemap:
https://learn.microsoft.com/en-us/windows/win32/direct3d9/cubic-environment-mapping
OpenGL cubemap:
https://www.khronos.org/opengl/wiki/Cubemap_Texture
- IOException
-
If an I/O error has occurred.
- ValidatingException
-
If the image reader has reported an error, for example because of an unsupported file format feature.
Set
3 overloads
Sets a sample of this color cube.
The color cube samples have pixel-is-point semantic.
Sets a sample of this color cube.
The color cube samples have pixel-is-point semantic.
Sets a sample of this color cube.
The color cube samples have pixel-is-point semantic.
Texture
3 overloads
Generates a 2D texture for the given cubemap face.
The generated texture has pixel-is-area semantic and LHS orientation, see Load.
Generates a 2D texture for the given cubemap face.
The generated texture has pixel-is-area semantic and LHS orientation, see Load.
Generates a cubemap texture.
The generated texture has pixel-is-area semantic and LHS orientation, see Load.
- RenderException
-
If a graphics subsystem error has occurred.