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

class TexelBuffer in Tinman.Terrain.Rendering

TexelBuffer objects are used to generate texel data for updating textures.

abstract class TexelBuffer extends Disposable
  implements IBufferCodec
  IConfigurable
  IDisposableGeneric<TexelBuffer>
  IEquatable<TexelBuffer>
  IMemoryConsumption
  ITexelBufferInfo
  base of Example_TexelBuffer
  TexelBufferBitPattern

See also:

ITexture2D

Configuration

Config

The configurator object for this type.

public static property Config { get }
type IConfigurator<TexelBuffer>
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:

Protected / Attributes

bitsPerTexel

Number of bits per texel.

protected readonly field bitsPerTexel
type int32

format

The texture format.

protected field format
type TextureFormat

height

The buffer height, in texels.

protected readonly field height
type int32

mipmaps

The number of mipmap levels (including this).

protected readonly field mipmaps
type int32

srgb

Does this texel buffer store compressed sRGB pixel channel values?

protected field srgb
type bool

stride

Distance between scanlines, in bytes.

protected readonly field stride
type int32

texels

The texel buffer.

[Owner]
protected field texels
type ByteBuffer

width

The buffer width, in texels.

protected readonly field width
type int32

Protected / Constructors

TexelBuffer

Creates a new instance of TexelBuffer.

protected constructor TexelBuffer (int32 width, int32 height, TextureFormat format, [Owner] TexelBuffer mipmap)
params width [>0] The buffer width, in texels.
  height [>0] The buffer height, in texels.
  format [not-null] The texture format.
  mipmap Texel buffer of next mipmap or null.

Protected / Methods

BufferDecodeInternal

Decodes a block of texels from the storage format.

protected abstract method BufferDecodeInternal (ByteBuffer input, int32 x, int32 y, int32 width, int32 height, ByteBuffer temp)
params input The encoded input texture data.
  x X-coordinate of top-left output texel.
  y Y-coordinate of top-left output texel.
  width Width of output texel block.
  height Height of output texel block.
  temp A temporary byte buffer that has been returned by BufferTemp, may be null.

Exceptions:

BufferEncodeInternal

Encodes a block of texels into the storage format.

protected abstract method BufferEncodeInternal (ByteBuffer output, int32 x, int32 y, int32 width, int32 height, ByteBuffer temp)
type int32
params output The encoded output texture data.
  x X-coordinate of top-left input texel.
  y Y-coordinate of top-left input texel.
  width Width of input texel block.
  height Height of input texel block.
  temp A temporary byte buffer that has been returned by BufferTemp, may be null.
returns >0: The number of bytes that have been written to output.
<0: The output buffer is too small, at least -1-n bytes are required, where n is the return value.

Remarks:

The storage format must be dependent on the native byte-order (see NativeOrder). The storage format may include additional compression techniques, for example RangeCompression.

BufferTemp

Creates the temporary buffer to use for BufferDecodeInternal resp. BufferEncodeInternal.

[OwnerReturn]
protected virtual method BufferTemp ()
type ByteBuffer
returns The temporary buffer or null.

Remarks:

The default implementation returns null.

DisposeResources

Disposes the resources held by a concrete subclass. This method will be called exactly once per instance.

protected override method DisposeResources ()
overrides Disposable.DisposeResources

Remarks:

This method will be called as soon as all ownership references to this instance have been relinquished by calls to the Dispose method.

The system may garbage collect an instance of IDisposable iff there are no more references to it. In this case, the DisposeResources will be called, in order to avoid dangling resources. However, it is not advisable to rely on the garbage collection of the system, as the behaviour may differ significantly between environments. Instead, ownership rules should be obeyed, which effectively removes the need for automatic garbage collection.

Overriding methods must call the DisposeResources method of their base class. The base call should be the last statement.

InitializeBegin

Begins to initialize this object.

protected method InitializeBegin ()
type bool
returns true if initialization must be performed,
false if initialization has already been performed.
inherited Disposable.InitializeBegin

InitializeRequired

Has this object been initialized?

protected method InitializeRequired ()
type bool
returns true if Initialize has already been called,
false if not.
inherited Disposable.InitializeRequired

PixelDecodeInternal

Decodes the texels in this buffer into the given pixel buffer.

protected abstract method PixelDecodeInternal (ColorBuffer target, int32 targetX, int32 targetY)
params target The color buffer that holds the decoded pixels.
  targetX X-coordinate of top-left target pixel.
  targetY Y-coordinate of top-left target pixel.

See also:

Srgb

PixelEncodeInternal

Encodes a block of pixels into this texel buffer.

protected abstract method PixelEncodeInternal (ColorBuffer source, int32 sourceX, int32 sourceY)
params source The color buffer that holds the source pixels.
  sourceX X-coordinate of top-left source pixel.
  sourceY Y-coordinate of top-left source pixel.

See also:

Srgb

Public / Attributes

BufferSize

Returns the size in bytes of the uncompressed samples in this buffer.

public property BufferSize { get }
type int32
value [>0] The uncompressed buffer size, in bytes.
implements IBufferCodec.BufferSize

Remarks:

The returned value is suitable to be used as the initial guess for the output buffer size when calling BufferEncode. If the buffer content exhibits very high entropy, BufferEncode is likely to overflow when using BufferSize. In these cases, increasing the buffer size by a factor of 6/5 will usually be enough. In any case, the return value of BufferEncode must always be inspected and the overflow case must always be handled properly.

Format

The texture format of this texel buffer.

public property Format { get }
type TextureFormat
value The texture format.
implements ITexelBufferInfo.Format

Height

The texel buffer height.

public property Height { get }
type int32
value [>0] The buffer height, in texels.
implements ITexelBufferInfo.Height

IsSoleOwnership

Will this object be disposed upon the next call to Dispose?

[ThreadSafe]
public property IsSoleOwnership { get }
type bool
value true if the object will be disposed when Dispose is called,
false if the object will not be disposed, because some other code is still holding shared ownership (see AcquireThrow).
inherited Disposable.IsSoleOwnership

LifecycleState

Returns the lifecycle state of this object.

public property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited Disposable.LifecycleState

MemoryConsumption

Returns the estimated memory consumption of this object.

public property MemoryConsumption { get }
type int64
value [>=0] The estimated memory consumption, in bytes.
implements IMemoryConsumption.MemoryConsumption

Mipmap

Returns the next smaller mipmap level of this texel buffer.

public property Mipmap { get }
type TexelBuffer
value The next smaller mipmap level buffer or null if this texel buffer is the last one in the mipmap chain.

MipmapCount

The number of mipmap levels.

public property MipmapCount { get }
type int32
value [>=1] The mipmap level count.
implements ITexelBufferInfo.MipmapCount

RawTexels

Returns a pointer to the first texel.

public property RawTexels { get }
type IntPtr
value Pointer to first texel.

See also:

RawTexelsSize
RawTexelsStride

RawTexelsStride

Returns the stride of RawTexels.

public property RawTexelsStride { get }
type int32
value [>0] The stride, in bytes.

Remarks:

The stride is the byte size of one row of texel blocks (see BlockSize).

See also:

RawTexels
RawTexelsSize

Srgb

Does this object store or process compressed sRGB pixel channel values?

public property Srgb { get set }
type bool
value true if the pixel channel values are compressed false if pixel channel values are linear.
implements ISrgb.Srgb

Remarks:

This flag is taken into account when pixels are encoded resp. decoded from resp. to a ColorBuffer, which always stores linear sRGB pixels: This object will only perform sRGB conversion if this flag is set to true.

The default value is true.

See also:

ColorF.ToSrgbF
ColorF.FromSrgbF

Width

The texel buffer width.

public property Width { get }
type int32
value [>0] The buffer width, in texels.
implements ITexelBufferInfo.Width

Public / Constructors

FromBase85

Decodes a buffer from the given base-85 encoded TXB file.

[OwnerReturn]
public static method FromBase85 (string value)
type TexelBuffer
params value [not-null] The base-85 encoded TXB file.
returns [not-null] The decoded buffer.

See also:

ToBase85

Exceptions:

ReadTXB

Reads a texel buffer in TXB file format from the given file.

[OwnerReturn]
public static method ReadTXB (Path file, bool gamma = true)
type TexelBuffer
params file [not-null] The input file.
  gamma Perform gamma correction? Defaults to true.
returns [not-null] The TexelBuffer object.

Exceptions:


Reads a texel buffer in TXB file format from the given data stream.

[OwnerReturn]
public static method ReadTXB ([Owner] IDataStream stream, bool gamma = true)
type TexelBuffer
params stream [not-null] The input data stream.
  gamma Perform gamma correction? Defaults to true.
returns [not-null] The TexelBuffer object.

Exceptions:


Reads a texel buffer in TXB file format from the given binary reader.

[OwnerReturn]
public static method ReadTXB (IBinaryReader reader, IPathInfo pathInfo = null, bool gamma = true)
type TexelBuffer
params reader [not-null] The binary reader.
  pathInfo Optional IPathInfo object to use for error reporting. Defaults to null.
  gamma Perform gamma correction? Defaults to true.
returns [not-null] The TexelBuffer object.

Exceptions:

Public / Methods

Acquire

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method Acquire ()
type TexelBuffer
returns The strong reference to this disposable object or null iff this object is no longer valid.

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls this method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

AcquireBase

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method AcquireBase ()
type IDisposable
returns The strong reference to this disposable object or null iff this object is no longer valid.
inherited Disposable.AcquireBase

Remarks:

The object will not be actually disposed by calls to IDisposable when there is at least one strong reference left. Code that calls this method is responsible for calling the IDisposable method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Using this method usually requires type casting. Subclasses may additionally implement IDisposableGeneric, in order to provide some syntactic sugar for that.

AcquireThrow

Acquires a strong reference to this disposable object.

[OwnerReturn, Pure]
public method AcquireThrow ()
type IDisposable
returns [not-null] The strong reference to this disposable object.
inherited Disposable.AcquireThrow

Remarks:

The object will not be actually disposed by calls to IDisposable when there is at least one strong reference left. Code that calls this method is responsible for calling the IDisposable method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Exceptions:

BufferDecode

Decodes a block of samples in this buffer.

public method BufferDecode (ByteBuffer input, int32 x, int32 y)
params input [not-null] The input buffer.
  x [0..Width] X-coordinate of top-left sample of block to decode.
  y [0..Height] Y-coordinate of top-left sample of block to decode.
implements IBufferCodec.BufferDecode

Exceptions:

BufferEncode

Encodes a block of samples in this buffer as a sequence of bytes, using lossless compression.

public method BufferEncode (ByteBuffer output, int32 x, int32 y, int32 width, int32 height)
type int32
params output [not-null] The output buffer.
  x [0..Width] X-coordinate of top-left sample of block to encode.
  y [0..Height] Y-coordinate of top-left sample of block to encode.
  width [0..Width-x] Width of pixel block.
  height [0..Height-y] Height of pixel block.
returns >0: The number of bytes that have been written to output.
<0: The output buffer is too small, at least -1-n bytes are required, where n is the return value.
implements IBufferCodec.BufferEncode

Convert

Converts this texel buffer to the given format.

[OwnerReturn, OwnerThis]
public method Convert (TextureFormat format)
type TexelBuffer
params format [not-null] The target format.
returns [not-null] The converted texel buffer.

CopyBytes

Copies texel data to the given buffer.

public method CopyBytes (ByteBuffer target, int32 targetBlockStride, int32 targetX = 0, int32 targetY = 0)
params target [not-null] The target buffer.
  targetBlockStride [>0] The target buffer stride, in bytes. This value gives the distance between two adjacent texel block rows.
  targetX [>=0] X-coordinate of top-left texel in target buffer. Defaults to 0.
  targetY [>=0] Y-coordinate of top-left texel in target buffer. Defaults to 0.

Remarks:

The given target X- and Y-coordinates must be a multiple of the texture format block size (see BlockSize).

CopyTexels

Copies all samples from this buffer to the given one.

public method CopyTexels (TexelBuffer target, int32 targetX = 0, int32 targetY = 0)
params target [not-null] The target buffer.
  targetX [0..target.Width-Width] X-coordinate to top-left corner of target region. Defaults to 0.
  targetY [0..target.Height-Height] Y-coordinate to top-left corner of target region. Defaults to 0.
returns [not-null] The target buffer.

Remarks:

The given target X- and Y-coordinates must be a multiple of the texture format block size (see BlockSize).

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method Dispose ()
inherited Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

Implementing methods must not throw any exceptions.

Equals

Compares this object with the given one.

[Pure]
public method Equals (TexelBuffer other)
type bool
params other The object to compare to.
returns true if this object is equal to other, false if not.

FromConfigEmbedded

Returns the embedded TXB file from the given config value.

public static method FromConfigEmbedded (ConfigValue value)
type int8[]
params value [not-null] The config value.
returns [not-null] The embedded TXB file.

See also:

ToConfigEmbedded

Exceptions:

ImportPixels

Returns an operation that imports image pixels into a TXB texture file.

[OwnerReturn]
public static method ImportPixels (IImage input, TextureFormat format, int32 mipmaps = 0, Path path = null, bool srgb = true)
type IOperation
params input [not-null] The input image.
  format [not-null] The texture format.
  mipmaps [>=0] Number of mipmap levels to compute. If 0, all mipmap levels will be computed. Defaults to 0.
  path Output path of texture file. If null, the file path of input will be used, having the file suffix replaced with .txb. Defaults to null.
  srgb The Srgb flag of the importing texel buffer. Defaults to true.
returns The import operation.

PixelDecode

Decodes the texels in this buffer into the given pixel buffer.

public method PixelDecode (ColorBuffer target, int32 targetX = 0, int32 targetY = 0)
params target [not-null] The color buffer that holds the decoded pixels.
  targetX [0..target.Width-Width] X-coordinate of top-left target pixel. Defaults to 0.
  targetY [0..target.Height-Height] Y-coordinate of top-left target pixel. Defaults to 0.

See also:

Srgb

PixelEncode

Encodes a block of pixels into this texel buffer.

public method PixelEncode (ColorBuffer source, int32 sourceX = 0, int32 sourceY = 0)
params source [not-null] The color buffer that holds the source pixels.
  sourceX [0..source.Width-Width] X-coordinate of top-left source pixel. Defaults to 0.
  sourceY [0..source.Height-Height] Y-coordinate of top-left source pixel. Defaults to 0.

See also:

Srgb

PixelEncodeMipmaps

Encodes the given pixels and fills all texels in all mipmap levels.

public method PixelEncodeMipmaps (ColorBuffer pixels, DownsampleFilter filter = DownsampleFilter.Average)
params pixels [not-null] The pixel buffer.
  filter The filter to use for downsampling. Defaults to Average.

See also:

Srgb

RawTexelsSize

Returns the size of the texel buffer.

[Pure]
public method RawTexelsSize (int32 stride = 0)
type int32
params stride [>=0] The stride, in bytes. If 0, RawTexelsStride will be used.
returns [>0] The texel buffer size, in bytes.

See also:

RawTexels
RawTexelsStride

ReadTXBInfo

Reads a texel buffer metadata in TXB file format from the given file.

public static method ReadTXBInfo (Path file)
type ITexelBufferInfo
params file [not-null] The input file.
returns [not-null] The texel buffer metadata.

Exceptions:


Reads a texel buffer metadata in TXB file format from the given data stream.

public static method ReadTXBInfo ([Owner] IDataStream stream)
type ITexelBufferInfo
params stream [not-null] The input data stream.
returns [not-null] The texel buffer metadata.

Exceptions:


Reads a texel buffer metadata in TXB file format from the given binary reader.

public static method ReadTXBInfo (IBinaryReader reader, IPathInfo pathInfo = null)
type ITexelBufferInfo
params reader [not-null] The binary reader.
  pathInfo Optional IPathInfo object to use for error reporting. Defaults to null.
returns [not-null] The texel buffer metadata.

Exceptions:

ToBase85

Encodes this buffer as a TXB file with base-85.

public method ToBase85 ()
type string
returns [not-null] The encoded base-85 string.

See also:

FromBase85

ToColorBuffer

Helper method that converts this texel buffer into a new compact color buffer.

public method ToColorBuffer ()
type ColorBuffer
returns [not-null] The color buffer.

See also:

PixelDecode

ToColorBufferOwn

Helper method that converts this texel buffer into a new compact color buffer.

[OwnerThis]
public method ToColorBufferOwn ()
type ColorBuffer
returns [not-null] The color buffer.

See also:

PixelDecode

ToConfigEmbedded

Returns a config value for an embedded TXB file.

public static method ToConfigEmbedded (int8[] txb)
type ConfigValue
params txb [not-null] The embedded TXB file.
returns [not-null] The config value.

See also:

FromConfigEmbedded

WriteTXB

Writes the texel data in this buffer to the given file, using the TXB file format.

public method WriteTXB (Path file)
params file [not-null] The output file.

Exceptions:


Writes the texel data in this buffer to the given data stream, using the TXB file format.

public method WriteTXB ([Owner] IDataStream stream)
params stream [not-null] The output data stream.

Exceptions:


Writes the texel data in this buffer to the given binary writer, using the TXB file format.

public method WriteTXB (IBinaryWriter writer)
params writer [not-null] The output data stream.

Exceptions: