ColorCube

Description

sealed class Tinman.Engine.Rendering.Util.ColorCube

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 / Constructors

Color​Cube


public constructor ColorCube → (2)

size in : int32

[pow2+1]
The cubemap size.

hasEdgeFixup opt : bool = false

Enable edge fixup mode?

Creates a new instance of ColorCube.

Public / Methods

Get


[Pure]
public method Get → (4)

in : int32

Cubemap block X-coordinate.

in : int32

Cubemap block Y-coordinate.

face in : CubemapFace

The cubemap face.

count in : int32

[pow2]
The cubemap block count (see remarks).

returns → ColorF

The average cube sample value.

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


public method Load → (3)

face in : CubemapFace

The cubemap face.

image in : IImage

[not-null]
The image to load onto face in.

transform opt : Transform = Transform.None

Optional transform to apply to image in before loading it onto face in.

Loads an image onto the given cubemap face.

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


public method Set1 → (5)

in : int32

Cubemap face X-coordinate of sample.

in : int32

Cubemap face Y-coordinate of sample.

face in : CubemapFace

The cubemap face.

color in : int64

The color to set (see Colors).

scale opt : float32 = 1

Scale factor to apply to linear color channel values.

Sets a sample of this color cube.

The color cube samples have pixel-is-point semantic.


public method Set2 → (5)

in : int32

Cubemap X-coordinate of sample.

in : int32

Cubemap Y-coordinate of sample.

in : int32

Cubemap Z-coordinate of sample.

color in : int64

The color to set (see Colors).

scale opt : float32 = 1

Scale factor to apply to linear color channel values.

Sets a sample of this color cube.

The color cube samples have pixel-is-point semantic.


public method Set3 → (3)

index in : int32

The linear sample index, see Cubemap.CubeToLinear1.

color in : int64

The color to set (see Colors).

scale opt : float32 = 1

Scale factor to apply to linear color channel values.

Sets a sample of this color cube.

The color cube samples have pixel-is-point semantic.

Texture

3 overloads


[Pure]
public method Texture1 → (2)

face in : CubemapFace

The cubemap face.

buffer in : TexelBuffer

[not-null]
The output texture buffer, which width and height must be equal to Size, minus one.

Generates a 2D texture for the given cubemap face.

The generated texture has pixel-is-area semantic.


[OwnerReturn] [Pure]
public method Texture2 → (3)

face in : CubemapFace

The cubemap face.

format in : TextureFormat

[not-null]
The texture format.

srgb in : bool

The sRGB flag.

returns → TexelBuffer

The texture buffer.

Generates a 2D texture for the given cubemap face.

The generated texture has pixel-is-area semantic.


[OwnerReturn] [Pure]
public method Texture3 → (3)

context in : IGraphicsContext

[not-null]
The graphics context to use.

format in : TextureFormat

[not-null]
The texture format.

srgb in : bool

The sRGB flag.

returns → ITextureCube

The texture object.

Generates a cubemap texture.

The generated texture has pixel-is-area semantic.

RenderException

If a graphics subsystem error has occurred.

Public / Attributes

Has​Edge​Fixup


public attribute HasEdgeFixup → (get)

value : bool

true if edge fixup mode is enabled,
false if edge fixup mode is disabled.

Does this color cube have edge fixup mode enabled?

In edge fixup mode, custom rasterization rules are in place, which must be taken into account by GPU shaders. If edge fixup mode is disabled, the derived cubemap textures may be used as is.

Maximum


public attribute Maximum → (get,set)

value : float32

[>=1]
The maximum scale factor.

The maximum scale factor that has been passed to Set.

Size


[Constant]
public attribute Size → (get)

value : int32

[pow2+1]
The cubemap size.

The cubemap size.

Texture​Mipmaps


public attribute TextureMipmaps → (get)

value : int32

[>0]
The mipmap level count.

Returns the number of mipmap levels in the pixel-is-area cubemap texture.