IEnvironmentMap

Description

interface Tinman.Engine.Components.IEnvironmentMap

Derived from

IVersioned
ILightProvider
IResourceHandle

Extended by

EnvironmentMap abstract

Base interface for classes that compute color samples of an environment map.

An environment map uses a horizontal coordinate system with altitude and azimuth coordinates, interpreted as follows, with respect to the view direction:

  • altitude = +90° : towards zenith of upper hemisphere

  • altitude = 0° : towards horizon

  • altitude = -90° : towards zenith of lower hemisphere

  • azimuth = 0° : northwards

  • azimuth = +90° : eastwards

  • azimuth = +/- 180° : southwards

  • azimuth = -90° : westwards

Usually, environment maps are associated with some topocentric coordinate system in a 3D scene.

Environment maps are used to render background skies and to model the visual appearance of material reflectivity and gloss. For this purpose, an environment map is rasterized into a ColorCube and then encoded as a mipmapped cubemap texture, which in turn is used during rendering. Ambient lighting is computed from the smallest mipmaps, thus mimicking (almost) hemispheric sampling. If an environment map contains a single prominent light feature, it may expose it via the ILightProvider.LightAltitude, ILightProvider.LightAzimuth and ILightProvider.LightSize properties. These will be then used for directional lighting.

IEnvironmentMap objects act as resource handles and produce EnvironmentMapResource resource objects.

Public / Methods

Compute​Environment​Color

[Pure]
public method ComputeEnvironmentColor → (2)

altitude in : float64

Altitude angle of the view direction, in the range [-90..90] degrees.

azimuth in : float64

Azimuth angle of the view direction, in the range [-180..180] degrees.

returns → int64

The computed low-dynamic range environment map color (see Colors). Apply MaximumEnvironmentColor afterwards to obtain the high-dynamic range environment map color.

Computes the environment color at the given coordinates.

See also

IEnvironmentMap.ComputeEnvironmentColorPrepare

Compute​Environment​Color​Prepare

public method ComputeEnvironmentColorPrepare → ()

returns → IEnvironmentMap

this

Prepares computation of environment colors via ComputeEnvironmentColor.

When this method is called, the IEnvironmentMap object makes local copies of all parameters that affect the result of ComputeEnvironmentColor, so that subsequent parameter modifications will have no influence. This ensures consistency when calling ComputeEnvironmentColor from multiple threads.

It is not necessary to call this method after creating a new IEnvironmentMap object. It need to be called only after modifying the map properties.

Public / Attributes

Maximum​Environment​Color

public attribute MaximumEnvironmentColor → (get)

value : float64

[>=0]
The color scale factor.

The scale factor to apply to the low-dynamic range color channel values (0..1) returned by ComputeEnvironmentColor, in order to obtain high-dynamic range color channel (0..M). values.

Maximum​Texture​Size

public attribute MaximumTextureSize → (get)

value : int32

[pow2]
The cubemap texture size.

Returns the smallest cubemap texture size that represents all detail in this environment map reasonably well.

Extensions

Rasterize

2 overloads

public static method Rasterize1 → (1)

width in : int32

[>0]
The color buffer width, in pixels.

returns → ColorBuffer

The color buffer.

Rasterizes this environment map into a color buffer.

This method calls IEnvironmentMap.ComputeEnvironmentColorPrepare.

public static method Rasterize2 → (2)

cube in : ColorCube

[not-null]
The output color cube.

scale opt : float32 = 0

[>=0]
The color scale to use or 0 to use the current value of IEnvironmentMap.MaximumEnvironmentColor.

Rasterizes this environment map into the given color cube.

This method does not call IEnvironmentMap.ComputeEnvironmentColorPrepare. The edge fixup mode of cube in will be taken into account. The mapping from cubemap faces to altitude/azimuth angles for IEnvironmentMap.ComputeEnvironmentColor is the same as the mapping to latitude/longitude, see LatLon.