ColorBuffer

Description

sealed class Tinman.Terrain.Buffers.ColorBuffer

Derived from: SampleBufferInt64 ^abstract
IBufferCodec
IConfigurable

An implementation of the ISampleBuffer interface that stores diffuse color values.

Each color buffer sample is single 64-bit ARGB color value (see Colors).

The Draw* methods can be used to perform simple drawing, for example to output debug information or other helpful information during testing.

See also: HeightmapSample.Texture
HeightmapSample.Material

Public / Constants

CharBaseline

public constant CharBaseline → (12:int32)

Baseline height of a single character glyph, in pixels.

CharBlock

public constant CharBlock → ((char) 9608:char)

The character of the full block glyph.

CharHeight

public constant CharHeight → (16:int32)

Height of a single character glyph, in pixels.

CharWidth

public constant CharWidth → (9:int32)

Width of a single character glyph, in pixels.

ScanlineRangeDefault

public static readonly attribute ScanlineRangeDefault → (PixelRange)

The default value of ISampleBuffer.ScanlineRange.

For image coding, the raw pixel value corresponds to the 16-bit color channel value (see Colors).

The default pixel range maps the color channel values 0 and 65535 to 0 resp. 16777215.

Public / Constructors

Create

public static method Create → (2)

width ⁱⁿ : int32: [>0]
Width of the color buffer.
height ⁱⁿ : int32: [>0]
Height of the color buffer.
returns → ColorBuffer: The color buffer.

Creates a new instance of ColorBuffer.

Instances of ColorBuffer can be pooled by calling IDeletable.Delete.

EncodeDistances

public static method EncodeDistances → (5)

red ⁱⁿ : DistanceBuffer: Distance buffer to encode in red channel or null.
green ^opt : DistanceBuffer = null: Distance buffer to encode in green channel or null.
blue ^opt : DistanceBuffer = null: Distance buffer to encode in blue channel or null.
alpha ^opt : DistanceBuffer = null: Distance buffer to encode in alpha channel or null.
buffer ^opt : ColorBuffer = null: The output color buffer. If null a new buffer will be created.
returns → ColorBuffer: The resulting color buffer.

Encodes up to four signed distance buffers into a color buffer (one per color channel).

See also: DistanceBuffer.ToPixel
DistanceBuffer.ToDistance

FromBase85

public static method FromBase85 → (1)

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

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

IOException: If value ⁱⁿ is malformed.

See also: ColorBuffer.ToBase85

FromImage

_4 overloads

public static method FromImage¹ → (1)

image ⁱⁿ : Path: [not-null]
The source image.
returns → ColorBuffer: The created ColorBuffer.

Creates a new instance of ColorBuffer.

IOException: If an I/O error has occurred.

ValidatingException: If the image reader has reported an error, for example because of an unsupported file format feature.

public static method FromImage² → (2)

image ⁱⁿ : Path: [not-null]
The source image.
gamma ⁱⁿ : float64: The value to use for IImageInfo.Gamma.
returns → ColorBuffer: The created ColorBuffer.

Creates a new instance of ColorBuffer.

IOException: If an I/O error has occurred.

ValidatingException: If the image reader has reported an error, for example because of an unsupported file format feature.

public static method FromImage³ → (1)

image ⁱⁿ : IImage: [not-null]
The source image.
returns → ColorBuffer: The created ColorBuffer.

Creates a new instance of ColorBuffer.

IOException: If an I/O error has occurred.

ValidatingException: If the image reader has reported an error, for example because of an unsupported file format feature.

public static method FromImage⁴ → (1)

image ⁱⁿ : IImageReader ^own: [not-null]
The source image.
returns → ColorBuffer: The created ColorBuffer.

Creates a new instance of ColorBuffer.

IOException: If an I/O error has occurred.

FromSamples

public static method FromSamples → (5)

samples ⁱⁿ : int64 [ ]: [not-null]
The sample array.
offset ⁱⁿ : int32: [>=0]
Offset to top-left pixel in samples ⁱⁿ.
stride ⁱⁿ : int32: [>0]
Distance between adjacent pixels rows, in pixels.
width ⁱⁿ : int32: [>0]
Width of buffer, in pixels.
height ⁱⁿ : int32: [>0]
Height of buffer, in pixels.
returns → ColorBuffer: The ColorBuffer object.

Wraps the given sample array into a ColorBuffer object.

ReadPXB

_3 overloads

public static method ReadPXB¹ → (1)

file ⁱⁿ : Path: [not-null]
The input file.
returns → ColorBuffer: The ColorBuffer object.

Reads a pixel buffer in PXB file format from the given file.

IOException: If an I/O error has occurred while reading file ⁱⁿ.

public static method ReadPXB² → (1)

stream ⁱⁿ : IDataStream ^own: [not-null]
The input data stream.
returns → ColorBuffer: The ColorBuffer object.

Reads a pixel buffer in PXB file format from the given data stream.

IOException: If an I/O error has occurred while reading stream ⁱⁿ.

public static method ReadPXB³ → (2)

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

Reads a pixel buffer in PXB file format from the given binary reader.

IOException: If an I/O error has occurred while reading reader ⁱⁿ.

Public / Methods

ColorAt

[Pure]
public method ColorAt → (2)

x ⁱⁿ : float64: X-coordinate of sample.
y ⁱⁿ : float64: Y-coordinate of sample.
returns → int64: The interpolated sample.

Samples a color value, using linear interpolation.

The sample coordinates (0,0) refer to the top-left corner of the top-left pixel and the sample coordinates (Width,Height) refer to the bottom-right corner of the bottom-right pixel. Sample coordinates will be clamped, if necessary. The center of the top-left pixel lies at sample coordinates (0.5,0.5), which yield the exact same color value as GetPixel for (0,0).

Combine

public method Combine → (11)

first ⁱⁿ : ColorBuffer: [not-null]
The first input color buffer.
second ⁱⁿ : ColorBuffer: [not-null]
The second input color buffer.
colorOp ⁱⁿ : ColorOp: The color operation to use.
x ^opt : int32 = 0: [0..ISampleBufferBase.Width]
X-coordinate of top-left output sample in this buffer.
y ^opt : int32 = 0: [0..ISampleBufferBase.Height]
Y-coordinate of top-left output sample in this buffer.
firstX ^opt : int32 = 0: [0..first.Width]
X-coordinate of top-left input sample in first ⁱⁿ.
firstY ^opt : int32 = 0: [0..first.Height]
Y-coordinate of top-left input sample in first ⁱⁿ.
secondX ^opt : int32 = 0: [0..second.Width]
X-coordinate of top-left input sample in second ⁱⁿ.
secondY ^opt : int32 = 0: [0..second.Height]
Y-coordinate of top-left input sample in second ⁱⁿ.
width ^opt : int32 = -1: [>=-1]
Width of region to combine. If -1, the region will be determined from the input and output buffers.
height ^opt : int32 = -1: [>=-1]
Height of region to combine. If -1, the region will be determined from the input and output buffers.

Combines the given color buffers (first ⁱⁿ and second ⁱⁿ) using the specified color operation (see ColorOp), storing the results in this buffer.

Downsample

public method Downsample → (3)

output ^opt : ColorBuffer = null: The output buffer or null. If null a new color buffer of the required minimum size is created.
filter ^opt : DownsampleFilter = DownsampleFilter.Average: The filter to use for downsampling.
ceiling ^opt : bool = true: Chooses the dimension reduction rule (only applies if output ^opt is null):
true (ceiling convention): size_smaller = size_original + 1 >> 1
false (floor convention): size_smaller = size_original >> 1
The floor convention is also used by Direct3D and OpenGL. Creating mip-mapped texel buffers via TextureFormat.CreateBuffer also uses the floor convention.
returns → ColorBuffer: The downsampled color buffer.

Performs downsampling on the pixels of this color buffer.

Each block of 2x2 input pixels is downsampled to a single output pixel.

+---+---+
| a | b |      +---+
+---+---+  =>  | x |
| c | d |      +---+
+---+---+

If this color buffer has a width and/or height that is not divisible by two, the right and/or bottom border pixels will be duplicated resp. clipped (see ceiling ^opt parameter) in order to get a full input pixel block for downsampling. If the output ^opt buffer is too small, overhang pixels will be discarded. The input and output buffers can be the same.

DrawBar

public method DrawBar → (5)

x ⁱⁿ : int32: X-coordinate of top-left corner of bar.
y ⁱⁿ : int32: Y-coordinate of top-left corner of bar.
width ⁱⁿ : int32: Width of bar, in pixels.
height ⁱⁿ : int32: Height of bar, in pixels.
color ⁱⁿ : int64: The bar color, with alpha (see Colors).

Draws a bar.

DrawChar

public method DrawChar → (5)

c ⁱⁿ : char: The Unicode character to draw.
x ⁱⁿ : int32: Screen X-coordinate of top-left corner of character glyph box.
y ⁱⁿ : int32: Screen Y-coordinate of top-left corner of character glyph box.
foreground ⁱⁿ : int64: The foreground color, with alpha (see Colors).
background ^opt : int64 = 0: The background color, with alpha (see Colors).

Draws a character using the famous VGA BIOS font.

The DrawChar method uses the CharacterEncodingSimple.Cp437 character set (yes, this is the one used by VGA BIOS - including the famous frame-building glyphs). The given Unicode character is converted to this character set (if no mapping exist, an ? will be drawn).

See also: ColorBuffer.CharWidth
ColorBuffer.CharHeight

DrawCircle

public method DrawCircle → (4)

x ⁱⁿ : int32: Screen X-coordinate of center of circle.
y ⁱⁿ : int32: Screen Y-coordinate of center of circle.
radius ⁱⁿ : int32: The circle radius, in screen pixels.
color ⁱⁿ : int64: The circle color.

Draws a circle.

DrawLine

public method DrawLine → (5)

x1 ⁱⁿ : int32: X-coordinate of line start point (inclusive).
y1 ⁱⁿ : int32: Y-coordinate of line start point (inclusive).
x2 ⁱⁿ : int32: X-coordinate of line end point (inclusive).
y2 ⁱⁿ : int32: Y-coordinate of line end point (inclusive).
color ⁱⁿ : int64: The line color, with alpha (see Colors).

Draws a line.

DrawPixel

public method DrawPixel → (3)

x ⁱⁿ : int32: X-coordinate of pixel.
y ⁱⁿ : int32: Y-coordinate of pixel.
color ⁱⁿ : int64: The pixel color, with alpha (see Colors).

Draws a single pixel.

DrawRectangle

public method DrawRectangle → (5)

x ⁱⁿ : int32: X-coordinate of top-left corner of rectangle.
y ⁱⁿ : int32: Y-coordinate of top-left corner of rectangle.
width ⁱⁿ : int32: Width of rectangle, in pixels.
height ⁱⁿ : int32: Height of rectangle, in pixels.
color ⁱⁿ : int64: The rectangle color, with alpha (see Colors).

Draws a rectangle.

DrawString

_2 overloads

public method DrawString¹ → (6)

s ⁱⁿ : string: The string to draw.
x ⁱⁿ : int32: X-coordinate of top-left corner of string box.
y ⁱⁿ : int32: Y-coordinate of top-left corner of string box.
foreground ⁱⁿ : int64: The foreground color (with alpha).
background ^opt : int64 = 0: The background color (with alpha).
outline ^opt : int64 = 0: The outline color color (with alpha).

Draws a single-line string.

public method DrawString² → (5)

text ⁱⁿ : Text: The text to draw.
x ⁱⁿ : int32: X-coordinate of top-left corner of text box.
y ⁱⁿ : int32: Y-coordinate of top-left corner of text box.
foreground ⁱⁿ : int64: The foreground color, with alpha (see Colors).
background ^opt : int64 = 0: The background, with alpha (see Colors).

Draws a multi-line text.

See also: ColorBuffer.CharWidth
ColorBuffer.CharHeight

EqualsTolerance

[Pure]
public method EqualsTolerance → (1)

other ⁱⁿ : ColorBuffer: The other color buffer.
returns → Vec4I: The color delta between the buffers:
Vec4I.X : the number of pixels with non-zero color deltas,
Vec4I.Y : the maximum color delta, in the range [0..65535],
Vec4I.Z : the average color delta, in the range [0..65535],
Vec4I.W : the relative color delta, in the range [0..1000000].
If other ⁱⁿ is null or if the buffers have different dimensions, the maximum color delta will be returned.

Compares this color buffer with the given one.

This method computes the delta between two colors as the maximum of the absolute of their alpha channels and the color distance computed by Colors.Distance_RGB_RGB, scaled by 65535 and round to the nearest integer.

FromConfigEmbedded

public static method FromConfigEmbedded → (1)

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

Returns the embedded PXB file from the given config value.

ConfigException: If value ⁱⁿ is invalid.

IOException: If the embedded PXB data is invalid.

See also: ColorBuffer.ToConfigEmbedded

GetPixel

[Pure]
public method GetPixel → (2)

x ⁱⁿ : int32: [0..ISampleBufferBase.Width-1]
X-coordinate of pixel.
y ⁱⁿ : int32: [0..ISampleBufferBase.Height-1]
Y-coordinate of pixel.
returns → int64: The pixel color (see Colors).

Gets a pixel from the buffer.

HasAlphaPixels

public method HasAlphaPixels → (6)

x ⁱⁿ : int32: [0..ISampleBufferBase.Width]
X-coordinate of top-left pixel in region to test.
y ⁱⁿ : int32: [0..ISampleBufferBase.Height]
Y-coordinate of top-left pixel in region to test.
width ⁱⁿ : int32: [0..ISampleBufferBase.Width-x]
Width of region to test, in pixels.
height ⁱⁿ : int32: [0..ISampleBufferBase.Height-y]
Height of region to test, in pixels.
alphaMin ^opt : int32 = 0: [0..65535]
Minimum alpha value of a transparent pixel (inclusive).
alphaMax ^opt : int32 = 65534: [alphaMin..65535]
Maximum alpha value of a transparent pixel (inclusive).
returns → bool: true if there is at least one pixel in the given region that is transparent,
false if all pixels in the region are not transparent.

Checks if this color buffer has matching pixels in the given region.

For this method, a matching pixels is defined as a pixel that has an alpha value which is greater than or equal to alphaMin ^opt and less than or equal to alphaMax ^opt. The default parameter values check for the presence of pixels that are not fully opaque.

PadColor

public method PadColor → (3)

width ⁱⁿ : int32: [>0]
The new width, in samples.
height ⁱⁿ : int32: [>0]
The new height, in samples.
color ^opt : int64 = 0: The color (see Colors) to use for padding the right and bottom edges.
returns → ColorBuffer: The resulting color buffer.

Resizes this color buffer to the given size by padding the right and bottom edges with the specified color.

See also: ColorBuffer.PadEdges

PadEdges

public method PadEdges → (2)

width ⁱⁿ : int32: [>0]
The new width, in samples.
height ⁱⁿ : int32: [>0]
The new height, in samples.
returns → ColorBuffer: The resulting color buffer.

Resizes this color buffer to the given size by duplicating the right and bottom edges.

See also: ColorBuffer.PadColor

ReadPXBInfo

_3 overloads

public static method ReadPXBInfo¹ → (2)

file ⁱⁿ : Path: [not-null]
The input file.
info ^out : Vec2I: Output for width (see Vec3I.X) and height (see Vec3I.Y).
returns → PixelFormat: The PixelFormat.

Reads a pixel buffer in PXB file format from the given file.

IOException: If an I/O error has occurred while reading from file ⁱⁿ.

public static method ReadPXBInfo² → (2)

stream ⁱⁿ : IDataStream ^own: [not-null]
The input data stream.
info ^out : Vec2I: Output for width (see Vec3I.X) and height (see Vec3I.Y).
returns → PixelFormat: The PixelFormat.

Reads a pixel buffer in PXB file format from the given data stream.

IOException: If an I/O error has occurred while reading from stream ⁱⁿ.

public static method ReadPXBInfo³ → (3)

reader ⁱⁿ : IBinaryReader: [not-null]
The binary reader.
info ^out : Vec2I: Output for width (see Vec3I.X) and height (see Vec3I.Y).
pathInfo ^opt : IPathInfo = null: Optional IPathInfo object to use for error reporting.
returns → PixelFormat: The PixelFormat.

Reads a pixel buffer in PXB file format from the given binary reader.

IOException: If an I/O error has occurred while reading from reader ⁱⁿ.

Scale

public method Scale → (2)

width ⁱⁿ : int32: [>0]
The new width, in pixels.
height ⁱⁿ : int32: [>0]
The new height, in pixels.
returns → ColorBuffer: The scaled color buffer.

Scales this color buffer to the given dimensions.

SetPixel

public method SetPixel → (3)

x ⁱⁿ : int32: [0..ISampleBufferBase.Width-1]
X-coordinate of pixel.
y ⁱⁿ : int32: [0..ISampleBufferBase.Height-1]
Y-coordinate of pixel.
color ⁱⁿ : int64: The pixel color (see Colors).

Sets a pixel in the buffer.

SetScanlineFormat

public method SetScanlineFormat → (1)

format ^opt : PixelFormat = PixelFormat.Unknown: The pixel format to use.

Specifies the pixel format to use for encoding buffer samples.

If format ^opt is set to PixelFormat.Unknown, the pixel format will be determined from the color values in the buffer. Once set, the format ^opt will hint all subsequent encoding / decoding steps. To avoid unintended side-effects, the format ^opt should be reset to PixelFormat.Unknown as soon as possible.

See also: ISampleBuffer.ScanlineFormat
IBufferCodec

ToBase85

public method ToBase85 → ()

returns → string: The encoded base-85 string.

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

See also: ColorBuffer.FromBase85

ToConfigEmbedded

public static method ToConfigEmbedded → (1)

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

Returns a config value for an embedded PXB file.

See also: ColorBuffer.FromConfigEmbedded

Trim

_2 overloads

public method Trim¹ → (1)

color ^opt : int64 = 0: Optional color (see Colors) to trim.
returns → ColorBuffer: The trimmed buffer or null if all buffer pixels are fully transparent.

Trims the edges of this buffer by removing all rows and columns that contain fully transparent pixels only.

public method Trim² → (2)

bounds ^out : Box2I: The bounds of the returned buffer in this buffer.
color ^opt : int64 = 0: Optional color (see Colors) to trim.
returns → ColorBuffer: The trimmed buffer or null if all buffer pixels are fully transparent.

Trims the edges of this buffer by removing all rows and columns that contain fully transparent pixels only.

WriteImage

public method WriteImage → (1)

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

Writes the pixel data in this buffer to the given file, using default writer options.

This method obtains an IImageWriter via ImageFormat.WriteImage of ImageFormat.Any and then calls IImageWriter.WriteImage, passing the result of ISampleBuffer.ReadAsImage on this sample buffer.

IOException: If an I/O error has occurred while writing to file ⁱⁿ.

WritePXB

_3 overloads

public method WritePXB¹ → (1)

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

Writes the pixel data in this buffer to the given file, using the PXB file format.

IOException: If an I/O error has occurred while writing to file ⁱⁿ.

public method WritePXB² → (1)

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

Writes the pixel data in this buffer to the given binary data stream, using the PXB file format.

IOException: If an I/O error has occurred while writing to stream ⁱⁿ.

public method WritePXB³ → (1)

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

Writes the pixel data in this buffer to the given binary writer, using the PXB file format.

IOException: If an I/O error has occurred while writing to writer ⁱⁿ.

WriteTXB

public method WriteTXB → (3)

file ⁱⁿ : Path: [not-null]
The output file.
format ^opt : TextureFormat = null: The texture format to use. If null, an appropriate format will be chosen automatically.
mipmaps ^opt : int32 = 1: [>=0]
Number of mipmaps to generate.

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

IOException: If an I/O error has occurred while writing to file ⁱⁿ.

See also: TextureFormat.For
TexelBuffer.PixelEncodeMipmaps
TexelBuffer.WriteTXB¹

Configuration

Config

public static attribute Config → (get)

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

The configurator object for this type.

ColorBuffer

Description

Public / Constants

Char​Baseline

Char​Block

Char​Height

Char​Width

Scanline​Range​Default

Public / Constructors

Create

Encode​Distances

From​Base85

From​Image

From​Samples

Read​PXB

Public / Methods

Color​At

Combine

Downsample

Draw​Bar

Draw​Char

Draw​Circle

Draw​Line

Draw​Pixel

Draw​Rectangle

Draw​String

Equals​Tolerance

From​Config​Embedded

Get​Pixel

Has​Alpha​Pixels

Pad​Color

Pad​Edges

Read​PXBInfo

Scale

Set​Pixel

Set​Scanline​Format

To​Base85

To​Config​Embedded

Trim

Write​Image

Write​PXB

Write​TXB

Configuration

Config

CharBaseline

CharBlock

CharHeight

CharWidth

ScanlineRangeDefault

EncodeDistances

FromBase85

FromImage

FromSamples

ReadPXB

ColorAt

DrawBar

DrawChar

DrawCircle

DrawLine

DrawPixel

DrawRectangle

DrawString

EqualsTolerance

FromConfigEmbedded

GetPixel

HasAlphaPixels

PadColor

PadEdges

ReadPXBInfo

SetPixel

SetScanlineFormat

ToBase85

ToConfigEmbedded

WriteImage

WritePXB

WriteTXB