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

class TextureFormat in Tinman.Terrain.Rendering

A TextureFormat object represents a binary texel format.

[ShutdownSurvive]
abstract class TextureFormat implements IConfigurable
  extends SerializableBase
  base of Example_TextureFormat

Remarks

A custom implementation must override the FormatIdentifier methods and should provide meaningful mappings in Generalize.

Configuration

Config

The configurator object for this type.

public static property Config { get }
type IConfigurator<TextureFormat>
value [not-null] The configurator object.

ToConfig

Returns the configuration value that describes this object.

public method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
implements IConfigurable.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

Exceptions:

Public / Constants

A16B16G16R16

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

public static readonly field A16B16G16R16
type TextureFormat

A16R16G16B16

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

public static readonly field A16R16G16B16
type TextureFormat

A1B5G5R5

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

public static readonly field A1B5G5R5
type TextureFormat

A1R5G5B5

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

public static readonly field A1R5G5B5
type TextureFormat

A2B10G10R10

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

public static readonly field A2B10G10R10
type TextureFormat

A2R10G10B10

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

public static readonly field A2R10G10B10
type TextureFormat

A4B4G4R4

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

public static readonly field A4B4G4R4
type TextureFormat

A4R4G4B4

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

public static readonly field A4R4G4B4
type TextureFormat

A8B8G8R8

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

public static readonly field A8B8G8R8
type TextureFormat

A8L8

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

public static readonly field A8L8
type TextureFormat

Remarks:

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

A8R8G8B8

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

public static readonly field A8R8G8B8
type TextureFormat

B5G6R5

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

public static readonly field B5G6R5
type TextureFormat

Remarks:

The normalized alpha channel value is 1.

BC1

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

public static readonly field BC1
type TextureFormat

BC3

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

public static readonly field BC3
type TextureFormat

BC4

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

public static readonly field BC4
type TextureFormat

Remarks:

The normalized alpha channel value is 1.

BC5

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

public static readonly field BC5
type TextureFormat

Remarks:

The normalized alpha channel value is 1.

G16R16

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

public static readonly field G16R16
type TextureFormat

Remarks:

The blue channel values are undefined.

The normalized alpha channel value is 1.

G8R8

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

public static readonly field G8R8
type TextureFormat

Remarks:

The blue channel values are undefined.

The normalized alpha channel value is 1.

L16

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

public static readonly field L16
type TextureFormat

Remarks:

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

The normalized alpha channel value is 1.

L8

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

public static readonly field L8
type TextureFormat

Remarks:

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

The normalized alpha channel value is 1.

R16

16-bit channel for red (16 bits per texel, uncompressed).

public static readonly field R16
type TextureFormat

Remarks:

The green and blue channel values are undefined.

The normalized alpha channel value is 1.

R5G6B5

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

public static readonly field R5G6B5
type TextureFormat

Remarks:

The normalized alpha channel value is 1.

R8

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

public static readonly field R8
type TextureFormat

Remarks:

The green and blue channel values are undefined.

The normalized alpha channel value is 1.

Public / Attributes

All

Returns all pre-defined TextureFormat s.

public static property All { get }
type IVectorConst<TextureFormat>
value [not-null] A list of all pre-defined TextureFormat s.

BitsPerTexel

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

public property BitsPerTexel { get }
type int32
value [>0] The number of storage bits per texture pixel.

Remarks:

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.

BlockSize

The texel block size of this texture format.

public property BlockSize { get }
type int32
value [pow2] The texel block size.

Remarks:

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

Name

The name of this texture format.

public property Name { get }
type string
value [not-null] The texture format name.

PixelFormat

Returns the pixel format that best describes this texture format.

public property PixelFormat { get }
type PixelFormat
value The pixel format.

SerialType

Returns the serial type of this object.

public property SerialType { get }
type ISerialTypeInfo
value [not-null] The serial type.
inherited SerializableBase.SerialType

SerialVersion

Returns the serial data version.

public virtual property SerialVersion { get }
type int32
value [>=1] The serial data version tag.
inherited SerializableBase.SerialVersion

Remarks:

An ISerializable implementation is required to support all versions up to the one returned by SerialVersion.

See also:

ISerializable.Serialize
ISerializable.Deserialize

Public / Methods

BitsPerComponent

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

public method BitsPerComponent (int32 component)
type int32
params component The texel component:
0: red
1: green
2: blue
3: alpha
4: intensity
returns [>=0] The number of effective bits per texel component. Will be 0 iff the texel component is not present.

Remarks:

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

BlockSizeAlign

[Pure]
public method BlockSizeAlign (int32 x)
type int32
params x

CheckBlockSizeAlignment

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

[Pure]
public method CheckBlockSizeAlignment (int32 x, int32 y)
type bool
params x X-coordinate of top-left texel rectangle.
  y Y-coordinate of top-left texel rectangle.
returns true if the texel location is properly aligned to the block size, false if not.

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

[Pure]
public method CheckBlockSizeAlignment (int32 x, int32 y, int32 width, int32 height)
type bool
params x X-coordinate of top-left texel rectangle.
  y Y-coordinate of top-left texel rectangle.
  width Width of texel rectangle.
  height Height of texel rectangle.
returns true if the texel rectangle is properly aligned to the block size, false if not.

CreateBuffer

Creates a texel buffer for this texture format.

[OwnerReturn]
public method CreateBuffer (int32 width, int32 height, int32 mipmaps = 1)
type TexelBuffer
params width [>0] The buffer width, in texels.
  height [>0] The buffer height, in texels.
  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 (see MipmapLevelsRect). Defaults to 1.
returns [not-null] The created TexelBuffer object.

Deserialize

Initializes the state of this object from the given data stream.

public virtual method Deserialize (int32 serialVersion, ISerializer data)
type ISerializable
params serialVersion [>=1] The serial data version.
  data [not-null] The serial data stream.
returns [not-null] The deserialized object. This will typically be this, but in some circumstances, another instance may be returned (e.g. singletons).
inherited SerializableBase.Deserialize

Remarks:

The Deserialize method will be called immediately after the object has been instantiated via its default constructor.

The provided serialVersion number is guaranteed to be equal to or less than the SerialVersion returned by this object (i.e. ISerializable object must provide backwards compatibility).

See also:

ISerializable.Serialize
ISerializable.SerialVersion

Exceptions:

For

Returns the default TextureFormat for the given PixelFormat.

[Pure]
public static method For (PixelFormat pixelFormat)
type TextureFormat
params pixelFormat The pixel format.
returns [not-null] The default TextureFormat.

FormatIdentifier

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

public virtual method FormatIdentifier (ITextureFactory factory, bool srgb)
type int32
params factory [not-null] The texture factory.
  srgb The sRGB behaviour.
returns The texture format identifier or -1 if none.

Remarks:

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

The default implementation returns -1.

Generalize

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.

[EmptyBody]
public abstract method Generalize (IVector<TextureFormat> choices)
params choices [not-null] List of choices for alternative texture formats. The choices are probed in the order as they have been added to the list.

Remarks:

The following figure shows the generalization paths of the built-in texture formats (links without an arrowhead are bidirectional):

                       +--------------+
+--------------------- |   A1B5G5R5   |
|                      +--------------+
|                        |
|                        |
|                        |
|                      +--------------+
|                      |   A1R5G5B5   |
|                      +--------------+
|                        |
|                        |                    +--------------------------------------+
|                        v                    v                                      |
|                      +--------------------------+                                  |
|                      |                          | <---------------------------+    |
|                      |                          |                             |    |
|                      |                          |                             |    |
|                      |         A8R8G8B8         | <----------+                |    |
|                      |                          |            |                |    |
|                      |                          |            |                |    |
|                      |                          | <+         |                |    |
|                      +--------------------------+  |         |                |    |
|                                        |           |         |                |    |
|                                        |           |         |                |    |
|                                        |           |         |                |    |
|  +-------------+     +--------------+  |           |         |                |    |
|  |     R8      | <-- |     BC4      |  |           |         |                |    |
|  +-------------+     +--------------+  |           |         |                |    |
|    |                   |               |           |         |                |    |
|    |                   |               |           |         |                |    |
|    |                   v               |           |         |                |    |
|    |                 +--------------+  |           |         |                |    |
|    |                 |     BC5      |  |           |         |                |    |
|    |                 +--------------+  |           |         |                |    |
|    |                   |               |           |         |                |    |
|    |                   |               |           |         |                |    |
|    |                   v               |           |         |                |    |
|    |                 +--------------+  |           |         |                |    |
|    +---------------> |     G8R8     |  |           |         |                |    |
|                      +--------------+  |           |         |                |    |
|                        |               |           |         |                |    |
|                        |               |    +------+---------+----+           |    |
|                        v               |    v      |         |    |           |    |
|                      +--------------------------+  |         |  +----------+  |    |
+--------------------> |         A8B8G8R8         | <+----+    |  | A4B4G4R4 |  |    |
                       +--------------------------+  |    |    |  +----------+  |    |
                                                     |    |    |    |           |    |
                                                     |    |    |    |           |    |
                                                     |    |    |    |           |    |
                       +--------------+              |    |    |  +----------+  |    |
                       |      L8      |              |    |    +- | A4R4G4B4 |  |    |
                       +--------------+              |    |       +----------+  |    |
                         |                           |    |                     |    |
                         |                           |    |                     |    |
                         v                           |    |                     |    |
                       +--------------+              |    |                     |    |
                       |     A8L8     | -------------+    |                     |    |
                       +--------------+                   |                     |    |
                       +--------------+                   |                     |    |
                       |     R16      |                   |                     |    |
                       +--------------+                   |                     |    |
                         |                                |                     |    |
                         |                                |                     |    |
                         v                                |                     |    |
                       +--------------+                   |                     |    |
                       |    G16R16    |                   |                     |    |
                       +--------------+                   |                     |    |
                         |                                |                     |    |
                         |                                |                     |    |
                         v                                |                     |    |
   +-------------+     +--------------+                   |                     |    |
   | A2B10G10R10 | --> | A16B16G16R16 |                   |                     |    |
   +-------------+     +--------------+                   |                     |    |
     |                   |                                |                     |    |
     |                   |                                |                     |    |
     |                   |                                |                     |    |
   +-------------+     +--------------+     +-----+       |                     |    |
   | A2R10G10B10 | --> | A16R16G16B16 | <-- | L16 |       |                     |    |
   +-------------+     +--------------+     +-----+       |                     |    |
                       +--------------+                   |                     |    |
                       |    B5G6R5    | ------------------+                     |    |
                       +--------------+                                         |    |
                         |                                                      |    |
                         |                                                      |    |
                         |                                                      |    |
                       +--------------+                                         |    |
                       |    R5G6B5    | ----------------------------------------+    |
                       +--------------+                                              |
                       +--------------+                                              |
                       |     BC1      |                                              |
                       +--------------+                                              |
                         |                                                           |
                         |                                                           |
                         v                                                           |
                       +--------------+                                              |
                       |     BC3      | ---------------------------------------------+
                       +--------------+

Serialize

Serializes the current state of this object to the given data stream.

public virtual method Serialize (ISerializer data)
params data [not-null] The serial data stream.
inherited SerializableBase.Serialize

See also:

ISerializable.Deserialize
ISerializable.SerialVersion

Exceptions:

ToString

[Pure]
public override method ToString ()
type string

Protected / Constructors

TextureFormat

Creates a new instance of TextureFormat.

protected constructor TextureFormat (ISerialTypeInfo serialType, string name, int32 bitsPerTexel, int32 bitsPerRed, int32 bitsPerGreen = 0, int32 bitsPerBlue = 0, int32 bitsPerAlpha = 0, int32 bitsPerIntensity = 0, int32 blockSize = 1)
params serialType [not-null] The serial type ID.
  name [not-empty] The texture format name.
  bitsPerTexel [>0] Number of storage bits per texel (see BitsPerTexel).
  bitsPerRed [>=0] Number of effective bits per red component (see BitsPerComponent).
  bitsPerGreen [>=0] Number of effective bits per green component (see BitsPerComponent). Defaults to 0.
  bitsPerBlue [>=0] Number of effective bits per blue component (see BitsPerComponent). Defaults to 0.
  bitsPerAlpha [>=0] Number of effective bits per alpha component (see BitsPerComponent). Defaults to 0.
  bitsPerIntensity [>=0] Number of effective bits per intensity component (see BitsPerComponent). Defaults to 0.
  blockSize [>0] The texel block size. Defaults to 1.

Protected / Methods

CreateBuffer

Creates a texel buffer for this texture format.

[OwnerReturn]
protected abstract method CreateBuffer (int32 width, int32 height, [Owner] TexelBuffer mipmap)
type TexelBuffer
params width The buffer width, in texels.
  height The buffer height, in texels.
  mipmap The next smaller mipmap level or null.
returns [not-null] The created texel buffer.