TerrainDecal

Description

sealed class Tinman.Engine.Components.TerrainDecal

A terrain surface decal, to be used with TerrainMesh.DecalAdd

The Transform property returns a IMapTransform object, where dataset space corresponds to the heightmap raster of the underlying terrain and map space is a user-defined coordinate system in which the terrain decal vertices are specified via Vertex2.

Public / Constructors

Terrain​Decal


public constructor TerrainDecal → (1)

visibleMask opt : int64 = ~0

The initial value for IVisibleMask.VisibleMask.

Creates a new instance of TerrainDecal.

Public / Methods

As​Streaming​Target


public static method AsStreamingTarget → (6)

decals in : TerrainDecal [ ]

[not-null]
The stack of terrain decals, see InterpolationWithAlpha.

width in : int32

[>0]
The texture width of the streaming target.

height in : int32

[>0]
The texture height of the streaming target.

format in : TextureFormat

[not-null]
The texture format. Use ITextureFactory.DefaultTextureFormat unless a specific format is required.

mipmaps opt : bool = true

Use a full mipmap chain for the streaming target?

srgb opt : bool = true

The sRGB processing flag of the streaming target.

returns → IStreamingTarget<TexelBuffer>

The streaming target.

Creates a IStreamingTarget object that wraps the given stack of TerrainDecal objects.

The Texture of the given decals in will be reset to a dynamic model texture by the returned streaming target.

Interpolation​With​Alpha


public static method InterpolationWithAlpha → (7)

decals in : TerrainDecal [ ]

[not-null]
The stack of terrain decals.

index in : float64

The data frame interpolation index.

range in : RangeI

The index range of the data frames that have been loaded into consecutive elements of decals in, where the last element is followed by the first element (wrap-around).

first in : int32

[-1..decals.Length-1]
The index in decals in that corresponds to RangeI.Start of range in or -1 if empty.

opacity opt : float64 = 1

The opacity of the whole terrain decal stack, in the range [0..1].

mode opt : InterpolationMode = InterpolationMode.UniformB

The interpolation mode.

priority opt : int32 = 0

The base priority value to use for inactive terrain decals. Active terrain decals within the interpolation window have priorities in the range [1..4], relative to the base priority.

Computes alpha blending factors for the given stack of terrain decals in order to perform smooth interpolation between them.

This method will replace the alpha channel of Color and Priority in each TerrainDecal of decals in, which must have the same SortIndex value and opaque Texture resources.

Interpolation​With​Slices


public method InterpolationWithSlices → (5)

slices in : RangeI

The model texture slice index range that is occupied by the texture slice sequence.

index in : float64

The data frame interpolation index.

range in : RangeI

The index range of the data frames that have been loaded into texture slice sequence.

first in : int32

[-1..slices.Length-1]
The slice index in Texture that corresponds to RangeI.Start of range in.

mode opt : InterpolationMode = InterpolationMode.UniformB

The interpolation mode.

Computes values for TextureSlices and TextureWeights in order to perform smooth interpolation between the slices of Texture.

First, the model texture slices of Texture are mapped to the texture slice sequence, according to slices in and first in. Then, the given index in and range in are used to locate the interpolation window. Finally, the interpolation weights are computed from mode opt and the fractional part of index in. For example:

slices = [1..6]
index  = 100.5
range  = [99..104]
first  = 1

+---+---+---+---+---+---+---+---+
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |   model texture slices
+---+---+---+---+---+---+---+---+
    | 5 | 0 | 1 | 2 | 3 | 4 |       texture slice sequence
    +---+---+---+---+---+---+
        | A | B | C | D |           interpolation window
        +---+---+---+---+
                |
              index

This scheme allows to use separate texture slice sequences that are packed into a single IModelTexture (see ModelTexture.Slices), which is useful for rendering static content. Streaming dynamic content for rendering (for example, time-series data or video clips) can be accomplished by performing the following steps:

  1. Use ModelTexture.Dynamic to create a IModelTexture that can be updated dynamically at runtime. The slices of the dynamic model texture represent a sliding window into the whole content.

  2. Load the contents of the sliding window: a background thread or task loads the content and fills in the texture data (see IModelTextureDynamic.Content). This should be done incrementally, if possible.

  3. Once loading is complete, the render thread calls IModelTextureDynamic.Update, which makes the loaded texture data available for rendering.

  4. The render thread calls InterpolationWithSlices to set up interpolation.

If texture arrays are not available (see ITextureFactory.MaximumCount), the InterpolationWithAlpha method may be used to achieve similar results.

Vertex

2 overloads


public method Vertex1 → (1)

index in : int32

[0..3]
The vertex index, mapped to: A, B, C, D.

returns → Vec2D

The untransformed vertex coordinates.

Returns a terrain decal vertex.


public method Vertex2 → (2)

index in : int32

[0..3]
The vertex index, mapped to: A, B, C, D.

vertex in : Vec2D

The untransformed vertex coordinates.

Sets a terrain decal vertex.

Public / Attributes

Color


public attribute Color → (get,set)

value : int64

The modulation color.

The color to use for modulating the decal texture.

Defaults to Colors.White.

Coordinates


public attribute Coordinates → (get,set)

value : CoordinateSystem

The coordinate system to use for interpreting the transformed vertex coordinates or null if not specified.

The coordinate system to use for interpreting the transformed vertex coordinates.

If the coordinate system is null, the decal texture will be skipped silently during processing.

Flags


public attribute Flags → (get,set)

value : TerrainDecalFlags

The flags.

The behaviour flags of this 2D decal.

Defaults to TerrainDecalFlags.None.

Matrix


public attribute Matrix → (get,set)

value : Mat3D

The transformation matrix.

A transformation matrix that is applied to the decal vertex coordinates before rendering.

Defaults to Mat3D.Identity.

Priority


public attribute Priority → (get,set)

value : int32

The priority value; decal textures with higher priority are rendered on top of decal textures with lower priority (i.e. they are processed later and thus appear later in the list of computed decaling batches).

The priority of this decal texture.

Sort​Index


public attribute SortIndex → (get,set)

value : int32

The layer sort index value (see TerrainLayer.SortIndex). Will be clamped to TerrainLayer.SortIndexMinimum and TerrainLayer.SortIndexMaximum.

Specifies the terrain layer after which this terrain decal shall be rendered.

The decal will be rendered after the terrain layer that has the greatest sort index value which is less than or equal this value and before the subsequent terrain layer ( if existent).

The default value is TerrainLayer.SortIndexMaximum, i.e. the terrain decal is rendered on top of the topmost terrain layer.

See also

IDecal.Priority

Texture


public attribute Texture → (get,set)

value : IModelTexture

The texture or null for none.

The texture to use for the terrain decal.

Defaults to null.

Texture​Clip


public attribute TextureClip → (get,set)

value : Vec4F

The texture clip rectangle.

The texture clip rectangle.

The decal vertices A, B, C and D (see remarks) are mapped to normalized texture coordinates in the range [0..1]. The texture clip rectangle spans the texture coordinate range from (X,1-Z) to (Y,1-W). Pixels that lie outside of the clip rectangle are discarded during rendering. Using Vec4F.Zero will make the clip rectangle encompass the whole texture.

Texture​Slices


public attribute TextureSlices → (get,set)

value : Vec4I

The texture slice indices.

Chooses the slices of Texture that will be used for rendering.

Each component gets clamped to [0..ITextureFactory.MaximumCount-1] and each clamped component then chooses a texture slice. The final decal texture is the sum of the chosen texture slices, weighted by their respective weight:

decal = Texture[TextureSlices.X] * TextureWeights.X
      + Texture[TextureSlices.Y] * TextureWeights.Y
      + Texture[TextureSlices.Z] * TextureWeights.Z
      + Texture[TextureSlices.W] * TextureWeights.W

If ITextureFactory.MaximumCount is 1, separate TerrainDecal objects can be combined with InterpolationWithAlpha in order to get similar results.

Default to Vec4I.Zero.

Texture​Weights


public attribute TextureWeights → (get,set)

value : Vec4F

The texture slice weights, each in the range [0..1],

Defines the weights of the texture slices.

Defaults to (1,0,0,0).

Transform


public attribute Transform → (get)

value : IMapTransform

The IMapTransform object or null if the required geo-reference information is missing or incomplete.

Returns the IMapTransform object that represents the transformation between dataset space (the scene terrain) and map space (the terrain decal), computing it if necessary.

Logging

Logger


public static readonly attribute Logger → (ILogger)

The logger object of this class.