TextureAtlas

Description

sealed class Tinman.Terrain.Rendering.TextureAtlas

Derived from: ResourceBase ^abstract
IVersioned
IEventListenerGeneric<PyramidEventArgs>
IMemoryConsumption
ICapacity

The TextureAtlas class provides GPU-caching for texture tiles that have been fetched from one or more texel pyramids.

A texture atlas maintains a series of square textures, all having the same size, mipmap level count and texture format. Each texture is divided into equally sized slots, which store tiles that have been fetched from texel pyramids.

      +---+---+---+---+
      | V | S | T | U |
   +---+---+---+---+ -+
   | R | W | N | P |  |       A..X := Texel pyramid tiles,
+---+---+---+---+ -+ -+               stuffed into cache textures
| A | D | F | I |  |  |
+---+---+---+---+ -+ -+
| J | B | C | H |  |  |
+---+---+---+---+ -+ -+    \
| K | E | G | L |  |       |
+---+---+---+---+ -+       |  textureCount
| X | M | O | Q |          |
+---+---+---+---+          /
            \___/
           tileSize
\_______________/
   textureSize

Texel pyramids must be registered with a texture atlas before they can be used (see PyramidIdAllocate and PyramidIdRelease). Pyramid tiles can then be requested via TileLookup. For rendering, use the TileSetup method to obtain texturing coefficients. Tiles are loaded in background tasks; call the TextureUpdate method from the render thread to incrementally upload new texture data to the GPU.

Public / Constructors

TextureAtlas

public constructor TextureAtlas → (8)

tileSize ⁱⁿ : int32: [pow2]
The tile size, in texels.
textureFactory ⁱⁿ : ITextureFactory: [not-null]
The texture factory to use.
textureFormat ⁱⁿ : TextureFormat: [not-null]
The texture format to use.
textureSize ⁱⁿ : int32: [pow2]
The cache texture size.
textureCount ⁱⁿ : int32: [>=1]
The number of cache textures.
srgb ^opt : bool = true: The sRGB behaviour flag.
textureSliceCount ^opt : int32 = 1: [>=1]
The number of cache textures per texture object.
textureNullColor ^opt : int64 = 0: Uniform color to use for the special NULL texture, which will be used by TileSetup if the given tile is invalid.

Creates a new instance of TextureAtlas.

RenderException: If a graphics subsystem error has occurred.

Public / Methods

Clear

public method Clear → ()

Clears the texture atlas.

PyramidGet

public method PyramidGet → (1)

pyramidId ^opt : int32 = 0: The pyramid ID.
returns → ITexelPyramid: The tile pyramid or null if not found.

Returns the tile pyramid for the given pyramid ID.

See also: TextureAtlas.PyramidIdAllocate

PyramidId

public method PyramidId → (1)

pyramid ⁱⁿ : ITexelPyramid: The tile pyramid.
returns → int32: The pyramid ID or -1 if pyramid ⁱⁿ is null or not allocated.

Returns the pyramid ID of the given tile pyramid.

PyramidIdAllocate

public method PyramidIdAllocate → (2)

pyramid ⁱⁿ : ITexelPyramid ^own: [not-null]
The tile pyramid.
srgb ^opt : int32 = 0: Defines the value of ISrgb.Srgb that will be set when getting texels from pyramid ⁱⁿ:
< 0 : set to false
= 0 : set to IsSrgb
> 0 : set to true
returns → int32: The pyramid ID or -1 iff all available pyramid IDs have already been allocated.

Allocates a pyramid ID for the given tile pyramid.

The first pyramid ID is always 0. Pyramid IDs that have been released can be reused later.

If a pyramid ID has already been allocated for the given tile pyramid, the same ID will be returned. The PyramidIdRelease must be called once for each call to PyramidIdAllocate in this case.

Pyramid IDs can be allocated and released in any order.

See also: TextureAtlas.PyramidIdRelease

PyramidIdRelease

public method PyramidIdRelease → (1)

pyramidId ⁱⁿ : int32: The pyramid ID.
returns → bool: true if the given pyramidId ⁱⁿ is invalid, false if the pyramidId ⁱⁿ is still valid and needs to be release at least once more (because PyramidIdAllocate has been called more than once).

Releases a previously allocated pyramid ID.

If the given pyramid ID is not valid, the method silently returns.

Pyramid IDs can be allocated and released in any order.

The TextureAtlas will retain ownership on the released ITexelPyramid as long as there are still background tasks running which are using it. If there are no such tasks, ownership will be released when PyramidIdRelease or TextureUpdate is called. To further control disposal of the released ITexelPyramid, the calling code can keep ownership on it and use IDisposable.IsSoleOwnership: if the code holds the sole ownership, it may safely proceed with disposal (for example calling IDisposable.Dispose in a separate thread, to avoid blocking).

See also: TextureAtlas.PyramidIdAllocate

TextureGet

[Pure]
public method TextureGet → (1)

index ⁱⁿ : int32: [0..TextureAtlas.TextureCount-1]
Index of cache texture.
returns → ITexture2D: The texture object.

Returns the texture object that contains the index ⁱⁿ-th cache texture.

See also: TextureAtlas.TextureSlice

TextureIndex

[Pure]
public method TextureIndex → (1)

tile ⁱⁿ : int32: The tile texture handle, as returned by TileLookup.
returns → int32: The cache texture index or -1 if the given tile texture handle is invalid.

Returns the index of the cache texture that contains the given tile texture.

TextureSlice

public method TextureSlice → (1)

index ⁱⁿ : int32: [0..TextureAtlas.TextureCount-1]
Index of cache texture.
returns → int32: The texture slice index.

Returns the slice index in the texture object that contains the index ⁱⁿ -th cache texture.

See also: TextureAtlas.TextureSliceCount
TextureAtlas.TextureGet

TextureUpdate

public method TextureUpdate → ()

returns → bool: true if texture updates have been performed, false if not.

Updates texture data.

This method is typically called once per frame.

See also: TextureAtlas.IsOverflow

TextureUpdateBytes

public method TextureUpdateBytes → ()

returns → int64: The amount of uploaded texture data, in bytes.

Polls the amount of texture data that has been uploaded via TextureUpdate so far.

This method will clear the byte counter, i.e. calling this method twice will return zero the second time.

TileBounds

[Pure]
public method TileBounds → (1)

tile ⁱⁿ : int32: The tile texture handle, as returned by TileLookup.
returns → Box2I: The tile bounds.

Returns the bounds of the given tile in the containing cache texture.

TileFadeFactor

[Pure]
public method TileFadeFactor → (1)

tile ⁱⁿ : int32: The tile texture handle, as returned by TileLookup.
returns → float32: The blend factor: 0 means fully faded out, 1 is fully faded in.

Computes the fade-in factor for the given texture tile, based on its birthday.

See also: TextureAtlas.TileFadeTime

TileFadeReset

public method TileFadeReset → (1)

tile ⁱⁿ : int32: The tile texture handle, as returned by TileLookup.

Resets the birthday of the given texture tile to now (see LowLevel.TickCount).

TileLookup

public method TileLookup → (3)

pyramidId ⁱⁿ : int32: The pyramid ID (see PyramidIdAllocate). If invalid, all pyramid tiles will be assumed to be TileDataResult.Void.
coords ⁱⁿ : PyramidCoords: Coordinates of pyramid tile to lookup.
doNotLoad ^opt : bool = false: If set to true, only existing tiles will be returned. When set to false, non-existing tiles will be scheduled for being loaded asynchronously.
returns → int32: >=0 : Handle of the pyramid tile in the texture atlas.
-1 : The pyramid tile is not present in the texture atlas.
-2 : The pyramid tile is being loaded into the texture atlas.
-3 : The pyramid tile is empty (see TileDataResult.Empty).
-4 : The pyramid tile does not exist (see TileDataResult.Void).

Performs a tile texture lookup for the given pyramid tile.

The tile texture handles that are returned by this method are valid until the next call to TextureUpdate is made.

TileLookupReverse

public method TileLookupReverse → (3)

texture ⁱⁿ : int32

[0..TextureAtlas.TextureCount-1]
The atlas texture.

tileX ⁱⁿ : int32

[0..TextureAtlas.TileCount-1]
X-coordinate of tile.

tileY ⁱⁿ : int32

[0..TextureAtlas.TileCount-1]
Y-coordinate of tile.

returns → Pair<int32, PyramidCoords>

The tile texture information:

Pair.First:
The pyramid ID, as returned by PyramidIdAllocate. Will be -1 iff the texture slot is not used yet.
Pair.Second:
The pyramid coordinates. Will be PyramidCoords.Undefined iff the texture slot is not used yet.

Performs a reverse tile texture lookup.

TileSetup

[Pure]
public method TileSetup → (1)

tile ⁱⁿ : int32: The tile texture handle (as returned by TileLookup).
returns → TextureTile: The texture tile. If tile ⁱⁿ is invalid (e.g. less than zero), the texturing coefficients will be all-zero and TextureTile.Texture will point to a 1x1 transparent black texture.

Sets up texturing coefficients for the given tile texture.

Public / Attributes

IsIdle

public attribute IsIdle → (get)

value : bool: true if the texture atlas is idle, false if not.

Is this texture atlas idle?

Idle means that there are no buffered texture tile updates (i.e. the next call to TextureUpdate will do nothing and always return true), that there are no pending background tasks which are loading texture tiles from a ITexelPyramid (i.e. TileLookup will never return -2).

IsOverflow

public attribute IsOverflow → (get)

value : bool: true if at least one texture tile update has been discarded because it had already been evicted from the texture atlas cache,
false if all texture tile updates have been applied.

Has a capacity overflow occurred during the last call to TextureUpdate?

IsSrgb

public attribute IsSrgb → (get)

value : bool: The sRGB behaviour flag.

The sRGB behaviour of this texture atlas.

See also: ITexture.IsSrgb

TextureCount

public attribute TextureCount → (get)

value : int32: [>=1]
The number of cache textures.

The number of cache textures.

Each cache texture contains N*N tile textures, where N is given by TextureSize/TileSize. Cache textures are packed into texture objects with a fixed number of texture array slices (see TextureSliceCount).

See also: TextureAtlas.TextureSliceCount

TextureFormat

public attribute TextureFormat → (get)

value : TextureFormat: [not-null]
The texture format.

Returns the texture format of this atlas.

TextureMipmaps

public attribute TextureMipmaps → (get)

value : int32: [>0]
The number of mipmap levels.

Returns the number of texture mipmap levels.

TextureSize

public attribute TextureSize → (get)

value : int32: [pow2]
The cache texture size.

The size of each cache texture.

TextureSliceCount

public attribute TextureSliceCount → (get)

value : int32: [>=1]
The number of cache textures per texture object.

The number of slices per texture object.

One or more cache textures may be packed into a single texture object (see ITexture2D). The number of cache textures per texture object must be specified when constructing a TextureAtlas object.

See also: TextureAtlas.TextureCount

TileCount

public attribute TileCount → (get)

value : int32: [pow2]
The number of tiles per texture axis.

The number of tiles per texture axis.

TileFadeTime

public attribute TileFadeTime → (get,set)

value : float32: [>=0]
The fade-in time, in seconds.

Duration of fade-in effect for newly loaded texture tiles.

Defaults 0.25 seconds.

TileSize

public attribute TileSize → (get)

value : int32: [pow2]
The tile texture size.

The size of each tile texture.

See also: IPyramidBase.TileSize

Logging

Logger

public static readonly attribute Logger → (ILogger)

The logger object of this class.

TextureAtlas

Description

Public / Constructors

Texture​Atlas

Public / Methods

Clear

Pyramid​Get

Pyramid​Id

Pyramid​Id​Allocate

Pyramid​Id​Release

Texture​Get

Texture​Index

Texture​Slice

Texture​Update

Texture​Update​Bytes

Tile​Bounds

Tile​Fade​Factor

Tile​Fade​Reset

Tile​Lookup

Tile​Lookup​Reverse

Tile​Setup

Public / Attributes

Is​Idle

Is​Overflow

Is​Srgb

Texture​Count

Texture​Format

Texture​Mipmaps

Texture​Size

Texture​Slice​Count

Tile​Count

Tile​Fade​Time

Tile​Size

Logging

Logger

TextureAtlas

PyramidGet

PyramidId

PyramidIdAllocate

PyramidIdRelease

TextureGet

TextureIndex

TextureSlice

TextureUpdate

TextureUpdateBytes

TileBounds

TileFadeFactor

TileFadeReset

TileLookup

TileLookupReverse

TileSetup

IsIdle

IsOverflow

IsSrgb

TextureCount

TextureFormat

TextureMipmaps

TextureSize

TextureSliceCount

TileCount

TileFadeTime

TileSize