TextureFormat

Description

[ShutdownSurvive]
abstract class Tinman.Terrain.Rendering.TextureFormat

Derived from

SerializableBase abstract
IConfigurable

Extended by

Example_TextureFormat sealed

A TextureFormat object represents a binary texel format.

A custom implementation must override the FormatIdentifier methods and should provide meaningful mappings in Generalize. The following texture formats are the most common ones and will usually be supported by most graphics contexts:

The names of the pre-defined texture formats follow this Grammar:

format       := uncompressed | compressed ;

compressed   := 'BC' '1'..'5' ;
uncompressed := part[1..4] float? ;

float        := 'F' ;
part         := channel bits ;

bits         := '0'..'9'+ ;
channel      := alpha | color | luminance ;

alpha        := 'A' ;
color        := [BGR] ;
luminance    := 'L' ;

The texture format names may be interpreted as follows:

  • Names matching compressed depict a block-compressed texture format (see BlockSize).

  • Uncompressed texture formats (see uncompressed) have a block size of 1.

  • The texture format parts (see part) appear reverse order: the last part represents the least significant bits in the texel word or the texel word at the lowest memory address. Texel words use the native host byte order (see ByteBuffer.NativeOrder).

  • For each part, channel and bits specify the texel channel and precision.

  • The float suffix indicates that a floating-point format is used, instead of a normalized integer format.

Public / Constants

A16​B16​G16​R16

public static readonly attribute A16B16G16R16 → (TextureFormat)

16-bit unsigned integer channels for alpha, red, green and blue (64 bits per texel, 4 texel words, uncompressed).

This texture format generalizes to:

  1. A16R16G16B16

See also

Colors.Decode_A16B16G16R16
Colors.Encode_A16B16G16R16

A16​B16​G16​R16​F

public static readonly attribute A16B16G16R16F → (TextureFormat)

16-bit floating-point channels for alpha, red, green and blue (64 bits per texel, 4 texel words, uncompressed).

This texture format generalizes to:

  1. A16R16G16B16F

  2. A32B32G32R32F

See also

LowLevel.FloatToHalf
LowLevel.HalfToFloat

A16​R16​G16​B16

public static readonly attribute A16R16G16B16 → (TextureFormat)

16-bit unsigned integer channels for alpha, red, green and blue (64 bits per texel, 4 texel words, uncompressed).

This texture format generalizes to:

  1. A16B16G16R16F

See also

Colors.Decode_A16R16G16B16
Colors.Encode_A16R16G16B16

A16​R16​G16​B16​F

public static readonly attribute A16R16G16B16F → (TextureFormat)

16-bit floating-point channels for alpha, red, green and blue (64 bits per texel, 4 texel words, uncompressed).

This texture format generalizes to:

  1. A16B16G16R16F

  2. A32R32G32B32F

See also

LowLevel.FloatToHalf
LowLevel.HalfToFloat

A1​B5​G5​R5

public static readonly attribute A1B5G5R5 → (TextureFormat)

1-bit channel for alpha, 5-bit channels for red, green and blue (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A1R5G5B5

  2. A8B8G8R8

See also

Colors.Decode_A1B5G5R5
Colors.Encode_A1B5G5R5

A1​R5​G5​B5

public static readonly attribute A1R5G5B5 → (TextureFormat)

1-bit channel for alpha, 5-bit channels for red, green and blue (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A1B5G5R5

  2. A8R8G8B8

See also

Colors.Decode_A1R5G5B5
Colors.Encode_A1R5G5B5

A2​B10​G10​R10

public static readonly attribute A2B10G10R10 → (TextureFormat)

2-bit channel for alpha, 10-bit channels for red, green and blue (32 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A2R10G10B10

  2. A16B16G16R16

See also

Colors.Decode_A2B10G10R10
Colors.Encode_A2B10G10R10

A2​R10​G10​B10

public static readonly attribute A2R10G10B10 → (TextureFormat)

2-bit channel for alpha, 10-bit channels for red, green and blue (32 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A2B10G10R10

  2. A16R16G16B16

See also

Colors.Decode_A2R10G10B10
Colors.Encode_A2R10G10B10

A32​B32​G32​R32​F

public static readonly attribute A32B32G32R32F → (TextureFormat)

32-bit floating-point channels for alpha, red, green and blue (128 bits per texel, 4 texel words, uncompressed).

This texture format generalizes to:

  1. A32R32G32B32F

A32​R32​G32​B32​F

public static readonly attribute A32R32G32B32F → (TextureFormat)

32-bit floating-point channels for alpha, red, green and blue (128 bits per texel, 4 texel words, uncompressed).

This texture format generalizes to:

  1. A32B32G32R32F

A4​B4​G4​R4

public static readonly attribute A4B4G4R4 → (TextureFormat)

4-bit channels for alpha, red, green and blue (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A4R4G4B4

  2. A8B8G8R8

See also

Colors.Decode_A4B4G4R4
Colors.Encode_A4B4G4R4

A4​R4​G4​B4

public static readonly attribute A4R4G4B4 → (TextureFormat)

4-bit channels for alpha, red, green and blue (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A4B4G4R4

  2. A8R8G8B8

See also

Colors.Decode_A4R4G4B4
Colors.Encode_A4R4G4B4

A8​B8​G8​R8

public static readonly attribute A8B8G8R8 → (TextureFormat)

8-bit channels for alpha, red, green and blue (32 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A8R8G8B8

See also

Colors.Decode_A8B8G8R8
Colors.Encode_A8B8G8R8

A8​L8

public static readonly attribute A8L8 → (TextureFormat)

8-bit channels for alpha and luminance resp. grayscale (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A8R8G8B8

The luminance value is replicated into the red, green and blue channels.

A8​R8​G8​B8

public static readonly attribute A8R8G8B8 → (TextureFormat)

8-bit channels for alpha, red, green and blue (32 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A8B8G8R8

See also

Colors.Decode_A8R8G8B8
Colors.Encode_A8R8G8B8

B5​G6​R5

public static readonly attribute B5G6R5 → (TextureFormat)

5-bit channel for red, 6-bit channel for green, 5-bit channel for blue (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. R5G6B5

  2. A8B8G8R8

The normalized alpha channel value is 1.

See also

Colors.Decode_B5G6R5
Colors.Encode_B5G6R5

BC1

public static readonly attribute BC1 → (TextureFormat)

1-bit channel for alpha, 5-bit channels for red and blue, 5-bit channel for green (4 bits per texel, using 4x4 block compression).

This texture format generalizes to:

  1. BC3

BC3

public static readonly attribute BC3 → (TextureFormat)

8-bit channel for alpha, 5-bit channels for red and blue, 5-bit channel for green (8 bits per texel, using 4x4 block compression).

This texture format generalizes to:

  1. A8R8G8B8

BC4

public static readonly attribute BC4 → (TextureFormat)

8-bit channel for red (4 bits per texel, using 4x4 block compression).

This texture format generalizes to:

  1. R8

  2. BC5

The normalized alpha channel value is 1.

BC5

public static readonly attribute BC5 → (TextureFormat)

8-bit channels for red and green (8 bits per texel, using 4x4 block compression).

This texture format generalizes to:

  1. G8R8

The normalized alpha channel value is 1.

G16​R16

public static readonly attribute G16R16 → (TextureFormat)

16-bit unsigned integer channels for red and green (32 bits per texel, 2 texel words, uncompressed).

This texture format generalizes to:

  1. A16B16G16R16

The blue channel values are undefined.
The normalized alpha channel value is 1.

G16​R16​F

public static readonly attribute G16R16F → (TextureFormat)

16-bit floating-point channels for red and green (32 bits per texel, 2 texel words, uncompressed).

This texture format generalizes to:

  1. A16B16G16R16F

The blue channel values are undefined.
The normalized alpha channel value is 1.

G32​R32​F

public static readonly attribute G32R32F → (TextureFormat)

32-bit floating-point channels for red and green (64 bits per texel, 2 texel words, uncompressed).

This texture format generalizes to:

  1. A32B32G32R32F

The blue channel values are undefined.
The normalized alpha channel value is 1.

G8​R8

public static readonly attribute G8R8 → (TextureFormat)

8-bit channels for red and green (16 bits per texel, 2 texel words, uncompressed).

This texture format generalizes to:

  1. A8B8G8R8

The blue channel values are undefined.
The normalized alpha channel value is 1.

L16

public static readonly attribute L16 → (TextureFormat)

16-bit channel for luminance resp. grayscale (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A16R16G16B16

The luminance value is replicated into the red, green and blue channels.
The normalized alpha channel value is 1.

L8

public static readonly attribute L8 → (TextureFormat)

8-bit channel for luminance resp. grayscale (8 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. A8L8

The luminance value is replicated into the red, green and blue channels.
The normalized alpha channel value is 1.

R16

public static readonly attribute R16 → (TextureFormat)

16-bit unsigned integer channel for red (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. G16R16

The green and blue channel values are undefined.
The normalized alpha channel value is 1.

R16​F

public static readonly attribute R16F → (TextureFormat)

16-bit floating-point channel for red (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. G16R16F

The green and blue channel values are undefined.
The normalized alpha channel value is 1.

See also

LowLevel.FloatToHalf
LowLevel.HalfToFloat

R32​F

public static readonly attribute R32F → (TextureFormat)

32-bit floating-point channel for red (32 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. G32R32F

The green and blue channel values are undefined.
The normalized alpha channel value is 1.

R5​G6​B5

public static readonly attribute R5G6B5 → (TextureFormat)

5-bit channel for red, 6-bit channel for green, 5-bit channel for blue (16 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. B5G6R5

  2. A8R8G8B8

The normalized alpha channel value is 1.

See also

Colors.Decode_R5G6B5
Colors.Encode_R5G6B5

R8

public static readonly attribute R8 → (TextureFormat)

8-bit channel for red (8 bits per texel, 1 texel word, uncompressed).

This texture format generalizes to:

  1. G8R8

The green and blue channel values are undefined.
The normalized alpha channel value is 1.

Public / Constructors

For

public static method For → (1)

pixelFormat in : PixelFormat

The pixel format.

returns → TextureFormat

The default TextureFormat.

Returns the default TextureFormat for the given PixelFormat.

Public / Methods

Bits​Per​Component

public method BitsPerComponent → (1)

component in : int32

The texel component:
0 : red
1 : green
2 : blue
3 : alpha
4 : intensity

returns → int32

The number of effective bits per texel component. Will be 0 iff the texel component is not present.

Returns the effective number of bits that are used to encode the given texel component.

This value represents the number of bits that are used to encode component in as input to a possible texel compression scheme (for example BC1). In this case, the sum of BitsPerComponent will be greater than BitsPerTexel.

Block​Size​Align

[Pure]
public method BlockSizeAlign → (1)

x in : int32

The size value.

returns → int32

The aligned size value.

Aligns the given size value with the block size of this texture format.

Check​Block​Size​Alignment

2 overloads

[Pure]
public method CheckBlockSizeAlignment1 → (2)

x in : int32

X-coordinate of top-left texel rectangle.

y in : int32

Y-coordinate of top-left texel rectangle.

returns → bool

true if the texel location is properly aligned to the block size, false if not.

Checks if the given texel location is aligned to this texture formats block size.

[Pure]
public method CheckBlockSizeAlignment2 → (6)

x in : int32

X-coordinate of top-left texel rectangle.

y in : int32

Y-coordinate of top-left texel rectangle.

width in : int32

Width of texel rectangle.

height in : int32

Height of texel rectangle.

widthMax in : int32

The width of the whole texture.

heightMax in : int32

The height of the whole texture.

returns → bool

true if the texel rectangle is properly aligned to the block size, false if not.

Checks if the given texel rectangle is aligned to this texture formats block size.

Create​Buffer

[OwnerReturn]
public method CreateBuffer → (3)

width in : int32

[>0]
The buffer width, in texels.

height in : int32

[>0]
The buffer height, in texels.

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 (see RenderingUtil.MipmapLevelsRect).

returns → TexelBuffer

The created TexelBuffer object.

Creates a texel buffer for this texture format.

Format​Identifier

public virtual method FormatIdentifier → (2)

factory in : ITextureFactory

[not-null]
The texture factory.

srgb in : bool

The sRGB behaviour.

returns → Vec4I

The texture format identifier or Vec4I.Zero if none.

Returns the identifier for this texture format, as defined by the graphics API that is associated with the given texture factory.

Custom implementations of TextureFormat must override this method, in order to provide the correct format identifier.

The default implementation returns -1.

Generalize

[EmptyBody]
public abstract method Generalize → (1)

choices in : IVector<TextureFormat>

[not-null]
List of choices for alternative texture formats. The choices are probed in the order as they have been added to the list.

Returns a texture format that is capable of storing all information of this one (i.e. conversion is lossless) but is more general in terms of being supported by some GPU.

The documentation of the built-in texture formats shows the generalization list.

Public / Attributes

All

public static attribute All → (get)

value : IVectorConst<TextureFormat>

[not-null]
A list of all pre-defined TextureFormats.

Returns all pre-defined TextureFormats.

Bits​Per​Texel

public attribute BitsPerTexel → (get)

value : int32

[>0]
The number of storage bits per texture pixel.

The number of bits that must be stored per texture pixel.

This values represents the number of bits that result from applying a possible texel compression scheme (for example BC1). In this case, this value will be less than the sum of BitsPerComponent.

Block​Size

public attribute BlockSize → (get)

value : int32

[pow2]
The texel block size.

The texel block size of this texture format.

Uncompressed texture formats have a block size of 1. Texels accesses must always be aligned to the block size.

Bytes​Per​Block

public attribute BytesPerBlock → (get)

value : int32

[>0]
The number of bytes per texel block.

Returns the number of bytes per texel block.

See also

TextureFormat.BlockSize

Name

public attribute Name → (get)

value : string

[not-null]
The texture format name.

The name of this texture format.

Pixel​Format

public attribute PixelFormat → (get)

value : PixelFormat

The pixel format.

Returns the pixel format that best describes this texture format.

Protected / Constructors

Texture​Format

protected constructor TextureFormat → (9)

serialType in : ISerialTypeInfo

[not-null]
The serial type ID.

name in : string

[not-empty]
The texture format name.

bitsPerTexel in : int32

[>0]
Number of storage bits per texel (see BitsPerTexel).

bitsPerRed in : int32

[>=0]
Number of effective bits per red component (see BitsPerComponent).

bitsPerGreen opt : int32 = 0

[>=0]
Number of effective bits per green component (see BitsPerComponent).

bitsPerBlue opt : int32 = 0

[>=0]
Number of effective bits per blue component (see BitsPerComponent).

bitsPerAlpha opt : int32 = 0

[>=0]
Number of effective bits per alpha component (see BitsPerComponent).

bitsPerIntensity opt : int32 = 0

[>=0]
Number of effective bits per intensity component (see BitsPerComponent).

blockSize opt : int32 = 1

[>0]
The texel block size.

Creates a new instance of TextureFormat.

Protected / Methods

Create​Buffer

[OwnerReturn]
protected abstract method CreateBuffer → (3)

width in : int32

The buffer width, in texels.

height in : int32

The buffer height, in texels.

mipmap in : TexelBuffer own

The next smaller mipmap level or null.

returns → TexelBuffer

The created texel buffer.

Creates a texel buffer for this texture format.

Configuration

Config

public static attribute Config → (get)

value : IConfigurator<TextureFormat>

[not-null]
The configurator object.

The configurator object for this type.