TextureAtlas

Description

sealed class Tinman.Terrain.Rendering.TextureAtlas

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

Texture​Atlas


public constructor TextureAtlas → (8)

tileSize in : int32

[pow2]
The tile size, in texels.

textureFactory in : ITextureFactory

[not-null]
The texture factory to use.

textureFormat in : TextureFormat

[not-null]
The texture format to use.

textureSize in : int32

[pow2]
The cache texture size.

textureCount in : 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.

Pyramid​Get


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.

Pyramid​Id


public method PyramidId → (1)

pyramid in : ITexelPyramid

The tile pyramid.

returns → int32

The pyramid ID or -1 if pyramid in is null or not allocated.

Returns the pyramid ID of the given tile pyramid.

Pyramid​Id​Allocate


public method PyramidIdAllocate → (2)

pyramid in : 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 in:
< 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.

Pyramid​Id​Release


public method PyramidIdRelease → (1)

pyramidId in : int32

The pyramid ID.

returns → bool

true if the given pyramidId in is invalid, false if the pyramidId in 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).

Texture​Get


[Pure]
public method TextureGet → (1)

index in : int32

[0..TextureAtlas.TextureCount-1]
Index of cache texture.

returns → ITexture2D

The texture object.

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

Texture​Index


[Pure]
public method TextureIndex → (1)

tile in : 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.

Texture​Slice


public method TextureSlice → (1)

index in : 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 in -th cache texture.

Texture​Update


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.

Texture​Update​Bytes


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.

Tile​Bounds


[Pure]
public method TileBounds → (1)

tile in : 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.

Tile​Fade​Factor


[Pure]
public method TileFadeFactor → (1)

tile in : 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.

Tile​Fade​Reset


public method TileFadeReset → (1)

tile in : int32

The tile texture handle, as returned by TileLookup.

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

Tile​Lookup


public method TileLookup → (3)

pyramidId in : int32

The pyramid ID (see PyramidIdAllocate). If invalid, all pyramid tiles will be assumed to be TileDataResult.Void.

coords in : 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.

Tile​Lookup​Reverse


public method TileLookupReverse → (3)

texture in : int32

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

tileX in : int32

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

tileY in : int32

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

returns → Pair<int32, PyramidCoords>

The tile texture information:

Performs a reverse tile texture lookup.

Tile​Setup


[Pure]
public method TileSetup → (1)

tile in : int32

The tile texture handle (as returned by TileLookup).

returns → TextureTile

The texture tile. If tile in 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

Is​Idle


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).

Is​Overflow


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?

Is​Srgb


public attribute IsSrgb → (get)

value : bool

The sRGB behaviour flag.

The sRGB behaviour of this texture atlas.

See also

ITexture.IsSrgb

Texture​Count


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).

Texture​Format


public attribute TextureFormat → (get)

value : TextureFormat

[not-null]
The texture format.

Returns the texture format of this atlas.

Texture​Mipmaps


public attribute TextureMipmaps → (get)

value : int32

[>0]
The number of mipmap levels.

Returns the number of texture mipmap levels.

Texture​Size


public attribute TextureSize → (get)

value : int32

[pow2]
The cache texture size.

The size of each cache texture.

Texture​Slice​Count


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.

Tile​Count


public attribute TileCount → (get)

value : int32

[pow2]
The number of tiles per texture axis.

The number of tiles per texture axis.

Tile​Fade​Time


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.

Tile​Size


public attribute TileSize → (get)

value : int32

[pow2]
The tile texture size.

The size of each tile texture.

Logging

Logger


public static readonly attribute Logger → (ILogger)

The logger object of this class.