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

Create​Texture2​D

[OwnerReturn]
public method CreateTexture2D → (6)

width in : int32

[>0]
The texture width, in texels.

height in : int32

[>0]
The texture height, in texels.

format in : 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 in and height in.

srgb opt : bool = true

The sRGB behaviour of the created texture (see ITexture.IsSrgb).

count opt : int32 = 1

[>=1]
The number of texture array slices.

returns → ITexture2D

The ITexture2D object, which might have a size (see ITexture2D.Width / ITexture2D.Height) that is greater than the given width in / height in.

Creates a ITexture2D object with ResourceAccessPattern.Dynamic access.

If the given combination of width in, height in, format in and srgb opt is not supported (see ValidateTextureSize and ValidateTextureFormat), a RenderException is thrown.

RenderException

If a graphics subsystem error has occurred.

Create​Texture2​DStatic

[OwnerReturn]
public method CreateTexture2DStatic → (2)

buffers in : 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, texture format and sRGB behaviour flags.

warn opt : bool = true

Emit a warning log message if the given buffers in need to be converted to a supported format and/or scaled to a supported size?

returns → ITexture2D

The ITexture2D object, which might have a different size and/or format than the given texel buffers in (see remarks).

Creates a ITexture2D object with ResourceAccessPattern.Static access.

The ValidateTextureSize method will be called to determine supported texture dimensions (see ITexelBufferInfo.Width / ITexelBufferInfo.Height), and the texture contents will be scaled, if necessary (see TexelBuffer.Convert3).

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 converted, if necessary (see TexelBuffer.Convert1).

RenderException

If a graphics subsystem error has occurred.

Validate​Texture​Format

[Pure]
public method ValidateTextureFormat → (3)

format in : TextureFormat

The texture format.

srgb in : bool

The sRGB behaviour of the texture (see ITexture.IsSrgb).

fallback opt : TextureFormat = null

The fallback texture format to return if format in and none of its generalizations are supported. If null, ITextureFactory.DefaultTextureFormat 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 in as closely as possible.

Implementations usually need to perform render API calls in order to determine texture format support, which may include creation of dummy resources. However, implementations will cache validation results for each (format in,srgb in) tuple, to avoid unnecessary work at runtime.

Validate​Texture​Size

[Pure]
public method ValidateTextureSize → (2)

width in : int32

The texture width.

height in : 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).

Texture size validation does not require render API calls, so calling this method has minimal performance overhead.

Public / Attributes

Available​Video​Memory

[Constant]
public attribute AvailableVideoMemory → (get)

value : int64

[>=0]
The estimated total amount of (dedicated) GPU memory, in bytes.

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

This value should only be used for large-scale decisions regarding use of resource sets and can never be used to decide whether a specific resource will fit into free memory.

Maximum​Count

[Constant]
public attribute MaximumCount → (get)

value : int32

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

Returns the maximum number of texture array slices.

If a texture factors does not support texture arrays, this property will always return 1.

See also

ITexture2D.Count

Maximum​Size

[Constant]
public attribute MaximumSize → (get)

value : int64

[>=0]
The maximum texture size, in bytes. Will be 0 is there is no specific limit.

Returns the maximum size of a single texture resource.

Extensions

Compute​Texture​Count

[Pure]
public static method ComputeTextureCount → (7)

format in : TextureFormat

[not-null]
The texture format.

width in : int32

[>0]
The texture width.

height in : int32

[>0]
The texture height.

count in : int32

[>0]
The logical texture count.

mipmaps in : int32

[>0]
The number of mipmap levels.

textures opt : int32 = Maths.MaxInt

[>0]
The maximum number of texture resources to use.

slices opt : int32 = Maths.MaxInt

[>0]
The maximum number of slices per texture to use.

returns → Vec2I

The texture resource and slice count:
Vec2I.X : number of texture resources, see textures opt
Vec2I.Y : number of slices per texture, see slices opt
The product of Vec2I.X and Vec2I.Y will be equal to count in.

Translates the given logical texture count in a supported combination of texture resource count and texture slice count.

Create​Texture2​DStatic

3 overloads

[OwnerReturn]
public static method CreateTexture2DStatic1 → (2)

buffer in : 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 given buffer in needs to be converted to a supported format and/or scaled to a supported size?

returns → ITexture2D

The ITexture2D object, which might have a different size and/or format than the given texel buffer in (see remarks).

Creates a ITexture2D object with ResourceAccessPattern.Static access.

The ITextureFactory.ValidateTextureSize method will be called to determine supported texture dimensions (see ITexelBufferInfo.Width / ITexelBufferInfo.Height), and the texture contents will be scaled, if necessary (see TexelBuffer.Convert3).

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 converted, if necessary (see TexelBuffer.Convert1).

RenderException

If a graphics subsystem error has occurred.

[OwnerReturn]
public static method CreateTexture2DStatic2 → (1)

path in : Path

[not-null]
The path to a texture file (see IImage.ReadTexture).

returns → ITexture2D

The ITexture2D object.

Creates a 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 CreateTexture2DStatic3 → (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 a ITexture2D object with ResourceAccessPattern.Static access.

The created texture has the default format, see DefaultTextureFormat.

RenderException

If a graphics subsystem error has occurred.

Default​Texture​Format

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

Validate​Texture​Size

2 overloads

[Pure]
public static method ValidateTextureSize1 → (1)

size in : 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 ValidateTextureSize2 → (1)

size in : 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).