ColorBuffer

Description

sealed class Tinman.Terrain.Buffers.ColorBuffer

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.

Public / Constants

Char​Baseline


public constant CharBaseline → (12:int32)

Baseline height of a single character glyph, in pixels.

Char​Block


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

The character of the full block glyph.

Char​Height


public constant CharHeight → (16:int32)

Height of a single character glyph, in pixels.

Char​Width


public constant CharWidth → (9:int32)

Width of a single character glyph, in pixels.

Scanline​Range​Default


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 in : int32

[>0]
Width of the color buffer.

height in : 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.

Encode​Distances


public static method EncodeDistances → (5)

red in : 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).

From​Base85


public static method FromBase85 → (1)

value in : 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 in is malformed.

From​Image

4 overloads


public static method FromImage1 → (1)

image in : 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 FromImage2 → (2)

image in : Path

[not-null]
The source image.

gamma in : 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 FromImage3 → (1)

image in : 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 FromImage4 → (1)

image in : 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.

From​Samples


public static method FromSamples → (5)

samples in : int64 [ ]

[not-null]
The sample array.

offset in : int32

[>=0]
Offset to top-left pixel in samples in.

stride in : int32

[>0]
Distance between adjacent pixels rows, in pixels.

width in : int32

[>0]
Width of buffer, in pixels.

height in : int32

[>0]
Height of buffer, in pixels.

returns → ColorBuffer

The ColorBuffer object.

Wraps the given sample array into a ColorBuffer object.

Read​PXB

3 overloads


public static method ReadPXB1 → (1)

file in : 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 in.


public static method ReadPXB2 → (1)

stream in : 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 in.


public static method ReadPXB3 → (2)

reader in : 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 in.

Public / Methods

Color​At


[Pure]
public method ColorAt → (2)

in : float64

X-coordinate of sample.

in : 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 in : ColorBuffer

[not-null]
The first input color buffer.

second in : ColorBuffer

[not-null]
The second input color buffer.

colorOp in : ColorOp

The color operation to use.

opt : int32 = 0

[0..ISampleBufferBase.Width]
X-coordinate of top-left output sample in this buffer.

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

firstY opt : int32 = 0

[0..first.Height]
Y-coordinate of top-left input sample in first in.

secondX opt : int32 = 0

[0..second.Width]
X-coordinate of top-left input sample in second in.

secondY opt : int32 = 0

[0..second.Height]
Y-coordinate of top-left input sample in second in.

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 in and second in) 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.

Draw​Bar


public method DrawBar → (5)

in : int32

X-coordinate of top-left corner of bar.

in : int32

Y-coordinate of top-left corner of bar.

width in : int32

Width of bar, in pixels.

height in : int32

Height of bar, in pixels.

color in : int64

The bar color, with alpha (see Colors).

Draws a bar.

Draw​Char


public method DrawChar → (5)

in : char

The Unicode character to draw.

in : int32

Screen X-coordinate of top-left corner of character glyph box.

in : int32

Screen Y-coordinate of top-left corner of character glyph box.

foreground in : 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).

Draw​Circle


public method DrawCircle → (4)

in : int32

Screen X-coordinate of center of circle.

in : int32

Screen Y-coordinate of center of circle.

radius in : int32

The circle radius, in screen pixels.

color in : int64

The circle color.

Draws a circle.

Draw​Line


public method DrawLine → (5)

x1 in : int32

X-coordinate of line start point (inclusive).

y1 in : int32

Y-coordinate of line start point (inclusive).

x2 in : int32

X-coordinate of line end point (inclusive).

y2 in : int32

Y-coordinate of line end point (inclusive).

color in : int64

The line color, with alpha (see Colors).

Draws a line.

Draw​Pixel


public method DrawPixel → (3)

in : int32

X-coordinate of pixel.

in : int32

Y-coordinate of pixel.

color in : int64

The pixel color, with alpha (see Colors).

Draws a single pixel.

Draw​Rectangle


public method DrawRectangle → (5)

in : int32

X-coordinate of top-left corner of rectangle.

in : int32

Y-coordinate of top-left corner of rectangle.

width in : int32

Width of rectangle, in pixels.

height in : int32

Height of rectangle, in pixels.

color in : int64

The rectangle color, with alpha (see Colors).

Draws a rectangle.

Draw​String

2 overloads


public method DrawString1 → (6)

in : string

The string to draw.

in : int32

X-coordinate of top-left corner of string box.

in : int32

Y-coordinate of top-left corner of string box.

foreground in : 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 DrawString2 → (5)

text in : Text

The text to draw.

in : int32

X-coordinate of top-left corner of text box.

in : int32

Y-coordinate of top-left corner of text box.

foreground in : int64

The foreground color, with alpha (see Colors).

background opt : int64 = 0

The background, with alpha (see Colors).

Draws a multi-line text.

Equals​Tolerance


[Pure]
public method EqualsTolerance → (1)

other in : 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 in 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.

From​Config​Embedded


public static method FromConfigEmbedded → (1)

value in : 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 in is invalid.

IOException

If the embedded PXB data is invalid.

Get​Pixel


[Pure]
public method GetPixel → (2)

in : int32

[0..ISampleBufferBase.Width-1]
X-coordinate of pixel.

in : int32

[0..ISampleBufferBase.Height-1]
Y-coordinate of pixel.

returns → int64

The pixel color (see Colors).

Gets a pixel from the buffer.

Has​Alpha​Pixels


public method HasAlphaPixels → (6)

in : int32

[0..ISampleBufferBase.Width]
X-coordinate of top-left pixel in region to test.

in : int32

[0..ISampleBufferBase.Height]
Y-coordinate of top-left pixel in region to test.

width in : int32

[0..ISampleBufferBase.Width-x]
Width of region to test, in pixels.

height in : 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.

Pad​Color


public method PadColor → (3)

width in : int32

[>0]
The new width, in samples.

height in : 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.

Pad​Edges


public method PadEdges → (2)

width in : int32

[>0]
The new width, in samples.

height in : 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.

Read​PXBInfo

3 overloads


public static method ReadPXBInfo1 → (2)

file in : 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 in.


public static method ReadPXBInfo2 → (2)

stream in : 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 in.


public static method ReadPXBInfo3 → (3)

reader in : 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 in.

Scale


public method Scale → (2)

width in : int32

[>0]
The new width, in pixels.

height in : int32

[>0]
The new height, in pixels.

returns → ColorBuffer

The scaled color buffer.

Scales this color buffer to the given dimensions.

Set​Pixel


public method SetPixel → (3)

in : int32

[0..ISampleBufferBase.Width-1]
X-coordinate of pixel.

in : int32

[0..ISampleBufferBase.Height-1]
Y-coordinate of pixel.

color in : int64

The pixel color (see Colors).

Sets a pixel in the buffer.

Set​Scanline​Format


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.

To​Base85


public method ToBase85 → ()

returns → string

The encoded base-85 string.

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

To​Config​Embedded


public static method ToConfigEmbedded → (1)

pxb in : int8 [ ]

[not-null]
The embedded PXB file.

returns → ConfigValue

The config value.

Returns a config value for an embedded PXB file.

Trim

2 overloads


public method Trim1 → (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 Trim2 → (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.

Write​Image


public method WriteImage → (1)

file in : 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 in.

Write​PXB

3 overloads


public method WritePXB1 → (1)

file in : 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 in.


public method WritePXB2 → (1)

stream in : 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 in.


public method WritePXB3 → (1)

writer in : 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 in.

Write​TXB


public method WriteTXB → (3)

file in : 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 in.

Configuration

Config


public static attribute Config → (get)

value : IConfigurator<ColorBuffer>

[not-null]
The configurator object.

The configurator object for this type.