TexelBuffer

Description

abstract class Tinman.Terrain.Rendering.TexelBuffer

Derived from: Disposable ^abstract
IMemoryConsumption
IEquatable<TexelBuffer>
IBufferCodec
ITexelBufferInfo
IDisposableGeneric<TexelBuffer>
IConfigurable
Extended by: Example_TexelBuffer ^sealed
TexelBufferBitPattern ^abstract

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

See also: ITexture2D

Public / Constructors

FromBase85

[OwnerReturn]
public static method FromBase85 → (1)

value ⁱⁿ : string: [not-null]
The base-85 encoded TXB file.
returns → TexelBuffer: The decoded buffer.

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

IOException: If value ⁱⁿ is malformed.

See also: TexelBuffer.ToBase85

ReadTXB

_3 overloads

[OwnerReturn]
public static method ReadTXB¹ → (2)

file ⁱⁿ : Path: [not-null]
The input file.
gamma ^opt : bool = true: Perform gamma correction?
returns → TexelBuffer: The TexelBuffer object.

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

IOException: If an I/O error has occurred.

[OwnerReturn]
public static method ReadTXB² → (2)

stream ⁱⁿ : IDataStream ^own: [not-null]
The input data stream.
gamma ^opt : bool = true: Perform gamma correction?
returns → TexelBuffer: The TexelBuffer object.

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

IOException: If an I/O error has occurred.

[OwnerReturn]
public static method ReadTXB³ → (3)

reader ⁱⁿ : IBinaryReader: [not-null]
The binary reader.
pathInfo ^opt : IPathInfo = null: Optional IPathInfo object to use for error reporting.
gamma ^opt : bool = true: Perform gamma correction?
returns → TexelBuffer: The TexelBuffer object.

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

IOException: If an I/O error has occurred.

Public / Methods

Convert

_3 overloads

[OwnerReturn] [OwnerThis]
public method Convert¹ → (2)

format ⁱⁿ : TextureFormat: [not-null]
The target format.
srgb ⁱⁿ : bool: The sRGB flag of the returned texel buffer.
returns → TexelBuffer: The converted texel buffer, which may be this.

Converts this texel buffer to the given format.

[OwnerReturn] [OwnerThis]
public method Convert² → (2)

width ⁱⁿ : int32: [>0]
The new width, in texels.
height ⁱⁿ : int32: [>0]
The new height, in texels.
returns → TexelBuffer: The scaled texel buffer.

Scales this texel buffer to the given dimensions, without converting the format.

[OwnerReturn] [OwnerThis]
public method Convert³ → (4)

width ⁱⁿ : int32: [>0]
The new width, in texels.
height ⁱⁿ : int32: [>0]
The new height, in texels.
format ⁱⁿ : TextureFormat: The target format or null to use the format of this texel buffer.
srgb ⁱⁿ : bool: The sRGB flag of the returned texel buffer.
returns → TexelBuffer: The scaled texel buffer.

Scales this texel buffer to the given dimensions while converting it to the given format.

CopyBytes

public method CopyBytes → (8)

target ⁱⁿ : ByteBuffer: [not-null]
The target buffer.
targetBlockStride ⁱⁿ : int32: [>0]
The target buffer stride, in bytes. This value gives the distance between two adjacent texel block rows.
targetX ^opt : int32 = 0: [>=0]
X-coordinate of top-left texel in target buffer.
targetY ^opt : int32 = 0: [>=0]
Y-coordinate of top-left texel in target buffer.
sourceY ^opt : int32 = 0: [>=0]
Index of first texel block row in source buffer.
sourceH ^opt : int32 = -1: [>=-1]
Number of texel blocks rows in source buffer. If negative, all remaining texel block rows are used.
sourceX ^opt : int32 = 0: [>=0]
Index of first texel block column in source buffer.
sourceW ^opt : int32 = -1: [>=-1]
Number of texel block columns in source buffer. If negative, all remaining texel block columns are used.

Copies texel data to the given buffer.

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

CopyTexels

public method CopyTexels → (3)

target ⁱⁿ : TexelBuffer: [not-null]
The target buffer.
targetX ^opt : int32 = 0: [0..target.Width-ITexelBufferInfo.Width]
X-coordinate to top-left corner of target region.
targetY ^opt : int32 = 0: [0..target.Height-ITexelBufferInfo.Height]
Y-coordinate to top-left corner of target region.

Copies all samples from this buffer to the given one.

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

FromConfigEmbedded

public static method FromConfigEmbedded → (1)

value ⁱⁿ : ConfigValue: [not-null]
The config value.
returns → int8 [ ]: The embedded TXB file.

Returns the embedded TXB file from the given config value.

ConfigException: If value ⁱⁿ is invalid.

IOException: If the embedded TXB data is invalid.

See also: TexelBuffer.ToConfigEmbedded

ImportPixels

[OwnerReturn]
public static method ImportPixels → (5)

input ⁱⁿ : IImage: [not-null]
The input image.
format ⁱⁿ : TextureFormat: [not-null]
The texture format.
mipmaps ^opt : int32 = 0: [>=0]
Number of mipmap levels to compute. If 0, all mipmap levels will be computed.
path ^opt : Path = null: Output path of texture file. If null, the file path of input ⁱⁿ will be used, having the file suffix replaced with .txb.
srgb ^opt : bool = true: The ISrgb.Srgb flag of the importing texel buffer.
returns → IOperation: The import operation.

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

MipmapAt

[Pure]
public method MipmapAt → (1)

level ⁱⁿ : int32: [0..ITexelBufferInfo.MipmapCount-1]
The mipmap level.
returns → TexelBuffer: The mipmap level.

Returns the mipmap at the given level.

PixelDecode

public method PixelDecode → (3)

target ⁱⁿ : ColorBuffer: [not-null]
The color buffer that holds the decoded pixels.
targetX ^opt : int32 = 0: [0..target.Width-ITexelBufferInfo.Width]
X-coordinate of top-left target pixel.
targetY ^opt : int32 = 0: [0..target.Height-ITexelBufferInfo.Height]
Y-coordinate of top-left target pixel.

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

See also: ISrgb.Srgb

PixelEncode

public method PixelEncode → (3)

source ⁱⁿ : ColorBuffer: [not-null]
The color buffer that holds the source pixels.
sourceX ^opt : int32 = 0: [0..source.Width-ITexelBufferInfo.Width]
X-coordinate of top-left source pixel.
sourceY ^opt : int32 = 0: [0..source.Height-ITexelBufferInfo.Height]
Y-coordinate of top-left source pixel.

Encodes a block of pixels into this texel buffer.

If the given color buffer is too small (see ITexelBufferInfo.Width and ITexelBufferInfo.Height), it will be padded with Colors.Zero to fill the texel buffer, using ColorBuffer.PadColor.

See also: ISrgb.Srgb

PixelEncodeMipmaps

public method PixelEncodeMipmaps → (2)

pixels ⁱⁿ : ColorBuffer: [not-null]
The pixel buffer.
filter ^opt : DownsampleFilter = DownsampleFilter.Average: The filter to use for downsampling.

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

If the given pixel buffer is too small (see ITexelBufferInfo.Width and ITexelBufferInfo.Height), its right and bottom edges will be duplicated to fill the texel buffer, using ColorBuffer.PadEdges.

See also: ISrgb.Srgb

RawTexelsSize

[Pure]
public method RawTexelsSize → (2)

stride ^opt : int32 = 0: [>=0]
The stride, in bytes. If 0, RawTexelsStride will be used.
blocks ^opt : int32 = 0: [>=0]
The number of block rows. If 0, the total number of block rows will be used.
returns → int32: The texel buffer size, in bytes.

Returns the size of the texel buffer.

The following figure shows the case when stride ^opt is smaller than RawTexelsSize, which is used when copying a part of the texel buffer:

+---+---+---+---+   bytesPerBlock   = Format.BytesPerBlock
| X | X | ! | ! |   RawTexelsStride = 4 * bytesPerBlock
+---+---+---+---+   stride          = 2 * bytesPerBlock
| X | X | ! | ! |   blocks          = 3
+---+---+---+---+
| X | X |           X := texel block
+---+---+           ! := skipped texel block (not read)

This figure shows the case when stride ^opt is greater than RawTexelsSize, which is used to copy the texel buffer contents to a larger buffer:

+---+---+---+---+   bytesPerBlock   = Format.BytesPerBlock
| X | X | X | . |   RawTexelsStride = 3 * bytesPerBlock
+---+---+---+---+   stride          = 4 * bytesPerBlock
| X | X | X | . |   blocks          = 3
+---+---+---+---+
| X | X | X |       X := texel block
+---+---+---+       . := skipped texel block (not written)

See also: TexelBuffer.RawTexels
TexelBuffer.RawTexelsStride

ReadTXBInfo

_3 overloads

public static method ReadTXBInfo¹ → (1)

file ⁱⁿ : Path: [not-null]
The input file.
returns → ITexelBufferInfo: The texel buffer metadata.

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

IOException: If an I/O error has occurred.

public static method ReadTXBInfo² → (1)

stream ⁱⁿ : IDataStream ^own: [not-null]
The input data stream.
returns → ITexelBufferInfo: The texel buffer metadata.

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

IOException: If an I/O error has occurred.

public static method ReadTXBInfo³ → (2)

reader ⁱⁿ : IBinaryReader: [not-null]
The binary reader.
pathInfo ^opt : IPathInfo = null: Optional IPathInfo object to use for error reporting.
returns → ITexelBufferInfo: The texel buffer metadata.

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

IOException: If an I/O error has occurred.

ToBase85

public method ToBase85 → ()

returns → string: The encoded base-85 string.

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

See also: TexelBuffer.FromBase85

ToColorBuffer

public method ToColorBuffer → ()

returns → ColorBuffer: The color buffer.

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

See also: TexelBuffer.PixelDecode

ToColorBufferOwn

[OwnerThis]
public method ToColorBufferOwn → ()

returns → ColorBuffer: The color buffer.

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

See also: TexelBuffer.PixelDecode

ToConfigEmbedded

public static method ToConfigEmbedded → (1)

txb ⁱⁿ : int8 [ ]: [not-null]
The embedded TXB file.
returns → ConfigValue: The config value.

Returns a config value for an embedded TXB file.

See also: TexelBuffer.FromConfigEmbedded

WriteTXB

_3 overloads

public method WriteTXB¹ → (1)

file ⁱⁿ : Path: [not-null]
The output file.

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

IOException: If an I/O error has occurred.

public method WriteTXB² → (1)

stream ⁱⁿ : IDataStream ^own: [not-null]
The output data stream.

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

IOException: If an I/O error has occurred.

public method WriteTXB³ → (1)

writer ⁱⁿ : IBinaryWriter: [not-null]
The output data stream.

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

IOException: If an I/O error has occurred.

Public / Attributes

HeightAligned

public attribute HeightAligned → (get)

value : int32: [>0]
The buffer height, always a multiple of the block size.

The texel buffer height aligned with the format block size.

Mipmap

public attribute Mipmap → (get)

value : TexelBuffer: The next smaller mipmap level buffer or null if this texel buffer is the last one in the mipmap chain.

Returns the next smaller mipmap level of this texel buffer.

RawTexels

public attribute RawTexels → (get)

value : IntPtr: Pointer to first texel.

Returns a pointer to the first texel.

See also: TexelBuffer.RawTexelsSize
TexelBuffer.RawTexelsStride

RawTexelsStride

public attribute RawTexelsStride → (get)

value : int32: [>0]
The stride, in bytes.

Returns the stride of RawTexels.

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

See also: TexelBuffer.RawTexels
TexelBuffer.RawTexelsSize

WidthAligned

public attribute WidthAligned → (get)

value : int32: [>0]
The buffer width, always a multiple of the block size.

The texel buffer width, aligned with the format block size.

Protected / Constructors

TexelBuffer

protected constructor TexelBuffer → (4)

width ⁱⁿ : int32: [>0]
The buffer width, in texels.
height ⁱⁿ : int32: [>0]
The buffer height, in texels.
format ⁱⁿ : TextureFormat: [not-null]
The texture format.
mipmap ⁱⁿ : TexelBuffer ^own: Texel buffer of next mipmap or null.

Creates a new instance of TexelBuffer.

Protected / Methods

BufferDecodeInternal

protected abstract method BufferDecodeInternal → (6)

input ⁱⁿ : ByteBuffer: The encoded input texture data.
x ⁱⁿ : int32: X-coordinate of top-left output texel.
y ⁱⁿ : int32: Y-coordinate of top-left output texel.
width ⁱⁿ : int32: Width of output texel block.
height ⁱⁿ : int32: Height of output texel block.
temp ⁱⁿ : ByteBuffer: A temporary byte buffer that has been returned by BufferTemp, may be null.

Decodes a block of texels from the storage format.

IOException: If the binary format input ⁱⁿ is malformed.

BufferEncodeInternal

protected abstract method BufferEncodeInternal → (6)

output ⁱⁿ : ByteBuffer: The encoded output texture data.
x ⁱⁿ : int32: X-coordinate of top-left input texel.
y ⁱⁿ : int32: Y-coordinate of top-left input texel.
width ⁱⁿ : int32: Width of input texel block.
height ⁱⁿ : int32: Height of input texel block.
temp ⁱⁿ : ByteBuffer: A temporary byte buffer that has been returned by BufferTemp, may be null.
returns → int32: >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.

Encodes a block of texels into the storage format.

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

BufferTemp

[OwnerReturn]
protected virtual method BufferTemp → ()

returns → ByteBuffer: The temporary buffer or null.

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

The default implementation returns null.

PixelDecodeInternal

protected abstract method PixelDecodeInternal → (3)

target ⁱⁿ : ColorBuffer: The color buffer that holds the decoded pixels.
targetX ⁱⁿ : int32: X-coordinate of top-left target pixel.
targetY ⁱⁿ : int32: Y-coordinate of top-left target pixel.

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

See also: ISrgb.Srgb

PixelEncodeInternal

protected abstract method PixelEncodeInternal → (3)

source ⁱⁿ : ColorBuffer: The color buffer that holds the source pixels.
sourceX ⁱⁿ : int32: X-coordinate of top-left source pixel.
sourceY ⁱⁿ : int32: Y-coordinate of top-left source pixel.

Encodes a block of pixels into this texel buffer.

See also: ISrgb.Srgb

Protected / Attributes

bitsPerTexel

protected readonly attribute bitsPerTexel → (int32)

Number of bits per texel.

format

protected attribute format → (TextureFormat)

The texture format.

height

protected readonly attribute height → (int32)

The buffer height, in texels.

heightAligned

protected readonly attribute heightAligned → (int32)

The buffer height, aligned with the block size, in texels.

mipmaps

protected readonly attribute mipmaps → (int32)

The number of mipmap levels (including this).

srgb

protected attribute srgb → (bool)

Does this texel buffer store compressed sRGB pixel channel values?

stride

protected readonly attribute stride → (int32)

Distance between scanlines, in bytes.

texels

[Owner]
protected attribute texels → (ByteBuffer)

The texel buffer.

width

protected readonly attribute width → (int32)

The buffer width, in texels.

widthAligned

protected readonly attribute widthAligned → (int32)

The buffer width, aligned with the block size, in texels.

Configuration

Config

public static attribute Config → (get)

value : IConfigurator<TexelBuffer>: [not-null]
The configurator object.

The configurator object for this type.

TexelBuffer

Description

Public / Constructors

From​Base85

Read​TXB

Public / Methods

Convert

Copy​Bytes

Copy​Texels

From​Config​Embedded

Import​Pixels

Mipmap​At

Pixel​Decode

Pixel​Encode

Pixel​Encode​Mipmaps

Raw​Texels​Size

Read​TXBInfo

To​Base85

To​Color​Buffer

To​Color​Buffer​Own

To​Config​Embedded

Write​TXB

Public / Attributes

Height​Aligned

Mipmap

Raw​Texels

Raw​Texels​Stride

Width​Aligned

Protected / Constructors

Texel​Buffer

Protected / Methods

Buffer​Decode​Internal

Buffer​Encode​Internal

Buffer​Temp

Pixel​Decode​Internal

Pixel​Encode​Internal

Protected / Attributes

bits​Per​Texel

format

height

height​Aligned

mipmaps

srgb

stride

texels

width

width​Aligned

Configuration

Config

FromBase85

ReadTXB

CopyBytes

CopyTexels

FromConfigEmbedded

ImportPixels

MipmapAt

PixelDecode

PixelEncode

PixelEncodeMipmaps

RawTexelsSize

ReadTXBInfo

ToBase85

ToColorBuffer

ToColorBufferOwn

ToConfigEmbedded

WriteTXB

HeightAligned

RawTexels

RawTexelsStride

WidthAligned

TexelBuffer

BufferDecodeInternal

BufferEncodeInternal

BufferTemp

PixelDecodeInternal

PixelEncodeInternal

bitsPerTexel

heightAligned

widthAligned