class TexelBuffer in Tinman.Terrain.Rendering

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

abstract class	TexelBuffer	extends	Disposable
		implements	IBitsPerTexel
			IBufferCodec
			IEquatable<TexelBuffer>
			IMemoryConsumption
			ITexelBufferInfo
		base of	TexelBufferBitPattern

See also:

ITexture2D

Public / Attributes

BitsPerTexel

The number of bits per texture pixel.

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

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

Format

The texture format of this texel buffer.

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

HasAlpha

Returns if texture pixels carry transparency data.

public property	HasAlpha { get }
type	bool
value		true if texture pixels can be transparent, false if all texture pixels will always be fully opaque.
implements	IBitsPerTexel.HasAlpha

Height

The texel buffer height.

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

LifecycleState

Returns the lifecycle state of this object.

public virtual 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.

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.

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

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.

---

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.

---

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.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry 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.

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

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.

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.
implements	IEquatable.Equals

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 abstract 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 abstract 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

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.

---

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.

---

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.

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.

---

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.

---

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.

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

Remarks:

This value is computed as follows:
width*bitsPerTexel/ 8

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

BufferCreateTemp

[OwnerReturn]
protected method	BufferCreateTemp ()
type	ByteBuffer

BufferDecodeInternal

protected abstract method	BufferDecodeInternal (ByteBuffer input, int32 x, int32 y, int32 width, int32 height, ByteBuffer temp)
params	input
	x
	y
	width
	height
	temp

BufferEncodeInternal

protected abstract method	BufferEncodeInternal (ByteBuffer output, int32 x, int32 y, int32 width, int32 height, ByteBuffer temp)
type	int32
params	output
	x
	y
	width
	height
	temp

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected override method	DisposeManaged ()
overrides	Disposable.DisposeManaged

Remarks:

This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.

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

The DisposeManaged method is called before the DisposeUnmanaged method.

DisposeUnmanaged

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

protected virtual method	DisposeUnmanaged ()
inherited	Disposable.DisposeUnmanaged

Remarks:

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

The DisposeUnmanaged method is called after the DisposeManaged method.