class TextureAtlas in Tinman.Terrain.Rendering

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

sealed class	TextureAtlas	extends	Disposable
		implements	IEventListenerGeneric<PyramidEventArgs>
			IMemoryConsumption
			IVersioned

Remarks

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

IsIdle

Is this texture atlas idle?

public property	IsIdle { get }
type	bool
value		true if the texture atlas is idle, false if not.

Remarks:

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

LifecycleState

Returns the lifecycle state of this object.

public virtual property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Disposable.LifecycleState

MemoryConsumption

Returns the estimated memory consumption of this object.

public property	MemoryConsumption { get }
type	int64
value	[>=0]	The estimated memory consumption, in bytes.
implements	IMemoryConsumption.MemoryConsumption

TextureCount

The number of cache textures.

public property	TextureCount { get }
type	int32
value	[>=1]	The number of cache textures.

TextureNullColor

Uniform color to use for the special NULL texture, which will be used by TileSetup if the given tile is invalid.

public property	TextureNullColor { get set }
type	int64
value		The uniform texture color.

Remarks:

The default value is 0 (i.e. transparent black).

TextureSize

The size of each cache texture.

public property	TextureSize { get }
type	int32
value	[pow2]	The cache texture size.

TileFadeTime

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

public property	TileFadeTime { get set }
type	float32
value	[>=0]	The fade-in time, in seconds.

Remarks:

Defaults 0.25 seconds.

TileSize

The size of each tile texture.

public property	TileSize { get }
type	int32
value	[pow2]	The tile texture size.

See also:

IPyramidBase.TileSize

TileUpdateFrequency

Specifies the maximum overall frequency of texture tile updates during calls to TextureUpdate.

public property	TileUpdateFrequency { get set }
type	int32
value	[>=0]	The maximum texture tile update frequency, in Hz. Set to 0 to disable the limit.

Remarks:

The default value is 0 (no limit).

Version

Returns the current version of object.

public property	Version { get }
type	int32
value		The current version number.
implements	IVersioned.Version

Remarks:

For each modification, the version is incremented by at least one.

Public / Constructors

Create

Creates a new instance of TextureAtlas.

[OwnerReturn]
public static method	Create ([Owner] ITexelPyramid pyramid, ITextureFactory textureFactory, int32 videoMemoryMaximum = 0, int32 videoMemoryPercentage = 50, int32 maxTextureSize = 4096)
type	TextureAtlas
params	pyramid	[not-null]	The texture tile pyramid to use (will always have the pyramid ID 0).
	textureFactory	[not-null]	The texture factory to use.
	videoMemoryMaximum	[>=0]	Maximum amount of video memory to use, in megabytes. If 0, no upper limit is applied. Defaults to 0.
	videoMemoryPercentage	[0..100]	Amount of available video memory to use, in percent. Defaults to 50.
	maxTextureSize	[pow2]	Maximum cache texture size. Defaults to 4096.
returns		[not-null]	The created TextureAtlas object.

Remarks:

Values for TextureCount and TextureSize will be inferred from the given parameters. The TileSize and TextureFormat will be taken from the given pyramid.

See also:

ITextureFactory.AvailableVideoMemory

---

Creates a new instance of TextureAtlas.

[OwnerReturn]
public static method	Create (int32 tileSize, ITextureFactory textureFactory, TextureFormat textureFormat, int32 videoMemoryMaximum = 0, int32 videoMemoryPercentage = 50, int32 maxTextureSize = 4096)
type	TextureAtlas
params	tileSize	[pow2]	The tile size, in texels.
	textureFactory	[not-null]	The texture factory to use.
	textureFormat	[not-null]	The texture format to use.
	videoMemoryMaximum	[>=0]	Maximum amount of video memory to use, in megabytes. If 0, no upper limit is applied. Defaults to 0.
	videoMemoryPercentage	[0..100]	Amount of available video memory to use, in percent. Defaults to 50.
	maxTextureSize	[pow2]	Maximum cache texture size. Defaults to 4096.
returns		[not-null]	The created TextureAtlas object.

Remarks:

Values for TextureCount and TextureSize will be inferred from the given parameters.

See also:

ITextureFactory.AvailableVideoMemory

TextureAtlas

Creates a new instance of TextureAtlas.

public constructor	TextureAtlas (int32 tileSize, ITextureFactory textureFactory, TextureFormat textureFormat, int32 textureSize, int32 textureCount)
params	tileSize	[pow2]	The tile size, in texels.
	textureFactory	[not-null]	The texture factory to use.
	textureFormat	[not-null]	The texture format to use.
	textureSize	[pow2]	The cache texture size.
	textureCount	[>=1]	The number of cache textures.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Clear

Clears the texture atlas.

public method

Clear ()

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

NotifyEvent

The event has been triggered.

public method	NotifyEvent (PyramidEventArgs argument)
params	argument		The event argument.
implements	IEventListenerGeneric.NotifyEvent

PyramidGet

Returns the tile pyramid for the given pyramid ID.

public method	PyramidGet (int32 pyramidId = 0)
type	ITexelPyramid
params	pyramidId		The pyramid ID.
returns		[not-null]	The tile pyramid.

See also:

PyramidIdAllocate

PyramidId

Returns the pyramid ID of the given tile pyramid.

public method	PyramidId (ITexelPyramid pyramid)
type	int32
params	pyramid		The tile pyramid.
returns		[-1..1023]	The pyramid ID or -1 if pyramid is null or not allocated.

PyramidIdAllocate

Allocates a pyramid ID for the given tile pyramid.

public method	PyramidIdAllocate ([Owner] ITexelPyramid pyramid)
type	int32
params	pyramid	[not-null]	The tile pyramid.
returns		[0..1023]	The pyramid ID.

Remarks:

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 ID can be allocated and released in any order.

See also:

PyramidIdRelease

Exceptions:

• TinmanException:
  If no more pyramid IDs can be allocated, because there are already 1024 allocations.

PyramidIdRelease

Releases a previously allocated pyramid ID.

public method	PyramidIdRelease (int32 pyramidId)
type	bool
params	pyramidId		The pyramid ID.
returns			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).

Remarks:

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

Pyramid ID can be allocated and released in any order.

See also:

PyramidIdAllocate

TextureGet

Returns the index-th atlas texture.

[Pure]
public method	TextureGet (int32 index)
type	ITexture2D
params	index	[0..TextureCount-1]	Index of atlas texture.
returns		[not-null]	The atlas texture.

TextureIndex

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

[Pure]
public method	TextureIndex (int32 tile)
type	int32
params	tile		The tile texture handle, as returned by TileLookup.
returns		[-1..TextureCount-1]	The atlas texture index or -1 if the given tile texture handle is invalid.

TextureUpdate

Updates texture data.

public method	TextureUpdate (bool force = false)
type	bool
params	force		Force a full update, regardless of the TileUpdateFrequency setting? Defaults to false.
returns			true if all texture updates have been performed, false if not.

Remarks:

This method is typically called once per frame.

TileBounds

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

[Pure]
public method	TileBounds (int32 tile)
type	Box2I
params	tile		The tile texture handle, as returned by TileLookup.
returns			The tile bounds.

TileFadeFactor

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

[Pure]
public method	TileFadeFactor (int32 tile)
type	float32
params	tile		The tile texture handle, as returned by TileLookup.
returns		[0..1]	The blend factor: 0 means fully faded out, 1 is fully faded in.

See also:

TileFadeTime

TileFadeReset

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

[Pure]
public method	TileFadeReset (int32 tile)
params	tile		The tile texture handle, as returned by TileLookup.

TileLookup

Performs a tile texture lookup for the given pyramid tile.

public method	TileLookup (int32 pyramidId, PyramidCoords coords, bool doNotLoad = false)
type	int32
params	pyramidId		The pyramid ID (see PyramidIdAllocate). If invalid, all pyramid tiles will be assumed to be Void.
	coords		Coordinates of pyramid tile to lookup.
	doNotLoad		If set to true, only existing tiles will be returned. When set to false, non-existing tiles will be scheduled for being loaded asynchronously. Defaults to false.
returns			>=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 Empty). -4: The pyramid tile does not exist (see Void).

Remarks:

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

TileSetup

Sets up texturing coefficients for the given tile texture.

[Pure]
public method	TileSetup (int32 tile)
type	TextureTile
params	tile		The tile texture handle (as returned by TileLookup).
returns			The texture tile. If tile is invalid (e.g. less than zero), the texturing coefficients will be all-zero and Texture will point to a 1x1 transparent black texture.

Logging

Logger

The logger object of this class.

public static readonly field	Logger
type	ILogger