ITextureFactory

Description

interface Tinman.Terrain.Rendering.ITextureFactory

Extended by: TextureFactory ^abstract

Base interface for classes that create texture resources for rendering.

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

+-----------------+
| ITextureFactory |
+-----------------+
        |
        |
        V         +----------------+
       (1) <----  | TextureFormat  |  The binary texel format.
        |         +----------------+
        |                 |
        |                 | (3)
        |                 V
        V         +----------------+    (5)   +-------------+
       (2) <----  |   TexelBuffer  |  <-----  | ColorBuffer |
        |         +----------------+          +-------------+
        |                 |                 Pixel buffer, filled
        |                 | (4)             by application
        |                 V
        |         +----------------+
        °-------> |   ITexture2D   |  Texture for GPU-based rendering
                  +----------------+

(1) : CreateTexture2D
(2) : CreateTexture2DStatic
(3) : TextureFormat.CreateBuffer
(4) : ITexture2D.SetTexels
(5) : TexelBuffer.PixelEncode

See also: ColorBuffer
TextureFormat
TexelBuffer
ITexture2D

Public / Methods

CreateTexture2D

[OwnerReturn]
public method CreateTexture2D → (7)

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

Creates an ITexture2D object with ResourceAccessPattern.Dynamic access.

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 ⁱⁿ.

RenderException: If a graphics subsystem error has occurred.

See also: ITextureFactory.ValidateTextureSize
ITextureFactory.ValidateTextureFormat

CreateTexture2DStatic

[OwnerReturn]
public method CreateTexture2DStatic → (2)

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

Creates an ITexture2D object with ResourceAccessPattern.Static access.

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 ITexelBufferInfo.Width and/or ITexelBufferInfo.Height.

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

RenderException: If a graphics subsystem error has occurred.

ValidateTextureFormat

[Pure]
public method ValidateTextureFormat → (3)

format ⁱⁿ : TextureFormat: The texture format.
srgb ⁱⁿ : bool: The sRGB behaviour of the texture (see ITexture.IsSrgb).
fallback ^opt : TextureFormat = null: The fallback texture format to return if format ⁱⁿ and none of its generalizations are supported. If null, TextureFormat.A8R8G8B8 will be used.
returns → TextureFormat: The supported texture format to use.

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

ValidateTextureSize

[Pure]
public method ValidateTextureSize → (2)

width ⁱⁿ : int32: The texture width.
height ⁱⁿ : int32: The texture height.
returns → Vec2I: 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).

Public / Attributes

AvailableVideoMemory

public attribute AvailableVideoMemory → (get)

value : int64: [>=0]
The total amount of GPU memory, in bytes.

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

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

MaximumCount

public attribute MaximumCount → (get)

value : int32: [>=1]
The maximum number of texture array slices.

Returns the maximum number of texture array slices.

See also: ITexture2D.Count

Extensions

CreateTexture2DStatic

_3 overloads

[OwnerReturn]
public static method CreateTexture2DStatic¹ → (2)

buffer ⁱⁿ : TexelBuffer: [not-null]
The buffer that holds the texture content. The ISrgb.Srgb flag of this buffer defines the sRGB behaviour of the created texture (see ITexture.IsSrgb).
warn ^opt : bool = true: Emit a warning log message if the TextureFormat of the given buffer ⁱⁿ needs to be converted to a supported format?
returns → ITexture2D: The ITexture2D object.

Creates an ITexture2D object with ResourceAccessPattern.Static access.

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

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

RenderException: If a graphics subsystem error has occurred.

[OwnerReturn]
public static method CreateTexture2DStatic² → (1)

path ⁱⁿ : Path: [not-null]
The path to a texture file (see IImage.ReadTexture).
returns → ITexture2D: The ITexture2D object.

Creates an ITexture2D object with ResourceAccessPattern.Static access.

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

IOException: If an I/O error has occurred.

ValidatingException: If the image reader has reported an error, for example because of an unsupported file format feature.

RenderException: If a graphics subsystem error has occurred.

[OwnerReturn]
public static method CreateTexture2DStatic³ → (2)

color ^opt : int64 = Colors.White: The uniform color.
srgb ^opt : bool = true: The sRGB behaviour of the created texture (see ITexture.IsSrgb).
returns → ITexture2D: The ITexture2D object.

Creates an ITexture2D object with ResourceAccessPattern.Static access.

The created texture has the TextureFormat.A8R8G8B8 format.

RenderException: If a graphics subsystem error has occurred.

DefaultTextureFormat

public static method DefaultTextureFormat → (1)

srgb ^opt : bool = true: The sRGB behaviour of the texture (see ITexture.IsSrgb).
returns → TextureFormat: The supported default texture format.

Returns the supported default texture format.

See also: TextureFormat.A8R8G8B8
TextureFormat.A8B8G8R8

ValidateTextureSize

_2 overloads

[Pure]
public static method ValidateTextureSize¹ → (1)

size ⁱⁿ : int32: The texture size (both width and height).
returns → int32: 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]
public static method ValidateTextureSize² → (1)

size ⁱⁿ : Vec2I: The texture size.
returns → Vec2I: 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).