TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

interface ITextureFactory in Tinman.Terrain.Rendering

Base interface for classes that create texture resources for rendering.

interface ITextureFactory base of TextureFactory

Remarks

The following figures gives an overview of the classes that are related to the ITextureFactory interface.

+-----------------+
| ITextureFactory |
+-----------------+
        |
        |
        V         +----------------+
     create <---- | TextureFormat  |  The binary texel format.
        |         +----------------+
        |                 |
        |                 | create
        |                 V
        |         +----------------+  encode  +-------------+
        |         |   TexelBuffer  |  <-----  | ColorBuffer |
        |         +----------------+          +-------------+
        |                 |                 Pixel buffer, filled
        |                 | copy            by application
        |                 V
        |         +----------------+
        +-------> | ITextureData2D |  Collects data for texture update
        |         +----------------+
        |                 |
        |                 | update
        |                 V
        |         +----------------+
        °-------> |   ITexture2D   |  Texture for GPU-based rendering
                  +----------------+

See also:

ColorBuffer
TextureFormat
TexelBuffer
ITexture2D

Attributes

AvailableVideoMemory

Returns a coarse estimate about the total amount of GPU memory (dedicated + shared).

property AvailableVideoMemory { get }
type int64
value [>=0] The total amount of GPU memory, in bytes.

Remarks:

This value should only be used for large-scale decisions regarding resources.

MaximumCount

Returns the maximum number of texture array slices.

property MaximumCount { get }
type int32
value [>=1] The maximum number of texture array slices.

See also:

ITexture2D.Count

Methods

CreateTexture2D

Creates an ITexture2D object with Dynamic access.

[OwnerReturn]
method CreateTexture2D (int32 width, int32 height, TextureFormat format, int32 mipmaps = 1, bool mappable = false, bool srgb = true, int32 count = 1)
type ITexture2D
params width [>0] The texture width, in texels.
  height [>0] The texture height, in texels.
  format [not-null] The texture format (will be returned by Format).
  mipmaps [>=0] The number of mipmap levels (including the full-resolution level). If 0 the number of levels will be inferred from width and height. Defaults to 1.
  mappable true to create a texture object with Mappable access,
false to create a texture object with Dynamic access.
Defaults to false.
  srgb The sRGB behaviour of the created texture (see IsSrgb). Defaults to true.
  count [1..MaximumCount] The number of texture array slices. Defaults to 1.
returns [not-null] The ITexture2D object.

Remarks:

The given texture size is validated (see ValidateTextureSize) before the texture is created, so the size of the returned ITexture2D object might be different to width and/or height.

See also:

ValidateTextureSize
ValidateTextureFormat

Exceptions:

CreateTexture2DStatic

Creates an ITexture2D object with Static access.

[OwnerReturn]
method CreateTexture2DStatic (TexelBuffer[] buffers, bool warn = true)
type ITexture2D
params buffers [not-null] The buffer for each texture array slice that holds the texture content. The Srgb flag of the buffers defines the sRGB behaviour of the created texture (see IsSrgb). All buffers must have the same width, height, mipmap level count, texel format and sRGB behaviour flags.
  warn Emit a warning log message if the TextureFormat of one of the given buffers needs to be converted to a supported format? Defaults to true.
returns [not-null] The ITexture2D object.

Remarks:

The texel buffer size is validated (see ValidateTextureSize) before the texture is created, so the size of the returned ITexture2D object might be different to Width and/or Height.

The ValidateTextureFormat method will be called to find a supported texture format for the given texture contents (see Format), and the texture contents will be transcoded, if necessary.

ValidateTextureFormat

Checks if this texture factory supports the given texture format. If not it returns a supported format that matches format as closely as possible.

[Pure]
method ValidateTextureFormat (TextureFormat format, bool srgb, TextureFormat fallback = null)
type TextureFormat
params format The texture format.
  srgb The sRGB behaviour of the texture (see IsSrgb).
  fallback The fallback texture format to return if format and none of its generalizations are supported. If null, A8R8G8B8 will be used. Defaults to null.
returns [not-null] The supported texture format to use.

ValidateTextureSize

Validates the given texture size by adjusting the width and height according to the texture size restrictions of this factory (e.g. must-be-square).

[Pure]
method ValidateTextureSize (int32 width, int32 height)
type Vec2I
params width The texture width.
  height The texture height.
returns The validated texture size.

Extensions

CreateTexture2DStatic

Creates an ITexture2D object with Static access.

[OwnerReturn]
method CreateTexture2DStatic (Path path)
type ITexture2D
params path [not-null] The path to a texture file (see ReadTexture).
returns [not-null] The ITexture2D object.

Remarks:

The Srgb flag of the loaded texel buffer (see ReadTexture) defines the sRGB behaviour of the created texture (see IsSrgb).

Exceptions:


Creates an ITexture2D object with Static access.

[OwnerReturn]
method CreateTexture2DStatic (TexelBuffer buffer, bool warn = true)
type ITexture2D
params buffer [not-null] The buffer that holds the texture content. The Srgb flag of this buffer defines the sRGB behaviour of the created texture (see IsSrgb).
  warn Emit a warning log message if the TextureFormat of the given buffer needs to be converted to a supported format? Defaults to true.
returns [not-null] The ITexture2D object.

Remarks:

The texel buffer size is validated (see ValidateTextureSize) before the texture is created, so the size of the returned ITexture2D object might be different to Width and/or Height.

The ValidateTextureFormat method will be called to find a supported texture format for the given texture contents (see Format), and the texture contents will be transcoded, if necessary.


Creates an ITexture2D object with Static access.

[OwnerReturn]
method CreateTexture2DStatic (int64 color = Colors.White, bool srgb = true)
type ITexture2D
params color The uniform color. Defaults to White.
  srgb The sRGB behaviour of the created texture (see IsSrgb). Defaults to true.
returns [not-null] The ITexture2D object.

Remarks:

The created texture has the A8R8G8B8 format.

DefaultTextureFormat

Returns the supported default texture format.

method DefaultTextureFormat (bool srgb = true)
type TextureFormat
params srgb The sRGB behaviour of the texture (see IsSrgb).
returns [not-null] The supported default texture format.

See also:

TextureFormat.A8R8G8B8
TextureFormat.A8B8G8R8

ValidateTextureSize

Validates the given texture size by adjusting the width and height according to the texture size restrictions of this factory (e.g. must-be-square).

[Pure]
method ValidateTextureSize (int32 size)
type int32
params size The texture size (both width and height).
returns The validated texture size.

Validates the given texture size by adjusting the width and height according to the texture size restrictions of this factory (e.g. must-be-square).

[Pure]
method ValidateTextureSize (Vec2I size)
type Vec2I
params size The texture size.
returns The validated texture size.