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

class ColorBuffer in Tinman.Terrain.Buffers

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

sealed class ColorBuffer implements IBufferCodec
  IConfigurable
  extends SampleBufferInt64

Remarks

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

Configuration

Config

The configurator object for this type.

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

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.

Height

The height of the buffer, in samples.

public property Height { get }
type int32
value [>0] The height of the buffer, in samples.
inherited SampleBuffer.Height

IsPacked

Returns if this sample buffer is densely packed.

public property IsPacked { get }
type bool
value true if this buffer is densely packed, false if not.
inherited SampleBuffer.IsPacked

Remarks:

A packed sample buffer can be indexed with the following scheme:

Samples[(y * Width + x) * TupleSize + 0] := 1st value of sample at (x,y).
Samples[(y * Width + x) * TupleSize + 1] := 2nd value of sample at (x,y).
...
Samples[(y * Width + x) * TupleSize + TupleSize - 1] := last value of sample.
Thus the samples of a densely packed buffer form a contiguous region in memory.

IsPooled

Is this sample buffer being held in a pool?

public property IsPooled { get }
type bool
value true if this buffer is currently in a pool, false if not.
inherited SampleBuffer.IsPooled

Remarks:

Using a sample buffer that is being held in a pool is an error and indicates incorrect use of Delete.

After calling Delete, a sample buffer is considered to be in a pool and IsPooled will return true.

After taking a sample buffer out of the pool, Restore must be called.

MemoryConsumption

Returns the estimated memory consumption of this object.

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

Offset

Index of top-left sample in the buffer.

public property Offset { get }
type int32
value [>=0] The buffer offset.
inherited SampleBuffer.Offset

Samples

The samples of this buffer.

public property Samples { get }
type int64[]
value [not-null] The buffer sample array.
inherited SampleBuffer.Samples

Remarks:

The buffer stores TupleSize values per sample in row-major order.
The returned array can be indexed as follows:

Samples[Offset + y * Stride + x * TupleSize + 0] := 1st value of sample at (x,y).
Samples[Offset + y * Stride + x * TupleSize + 1] := 2nd value of sample at (x,y).
...
Samples[Offset + y * Stride + x * TupleSize + TupleSize - 1] := last value of sample.
where x and y are the coordinates of the sample to access.

ScanlineFormat

The PixelFormat of this sample buffer, when being read as an image.

public override property ScanlineFormat { get }
type PixelFormat
value The pixel format.

See also:

ISampleBuffer.ScanlineRead
ISampleBuffer.ScanlineWrite

ScanlineRange

The PixelRange of this buffer, where raw pixels values correspond to the buffer samples.

public property ScanlineRange { get set }
type PixelRange
value The pixel range.
inherited SampleBuffer.ScanlineRange

See also:

ISampleBuffer.ScanlineRead
ISampleBuffer.ScanlineWrite

Stride

Distance between two consecutive rows in the buffer.

public property Stride { get }
type int32
value [>0] The buffer stride, in samples.
inherited SampleBuffer.Stride

TupleSize

The tuple size of each buffer sample (i.e. the number of array elements).

public property TupleSize { get }
type int32
value [1..4] The buffer sample tuple size.
inherited SampleBuffer.TupleSize

Width

The width of the buffer, in samples.

public property Width { get }
type int32
value [>0] The width of the buffer, in samples.
inherited SampleBuffer.Width

Public / Constants

CharBaseline

Baseline height of a single character glyph, in pixels.

public constant CharBaseline = 12
type int32

CharBlock

The character of the full block glyph.

public constant CharBlock =
type char

CharHeight

Height of a single character glyph, in pixels.

public constant CharHeight = 16
type int32

CharWidth

Width of a single character glyph, in pixels.

public constant CharWidth = 9
type int32

ScanlineRangeDefault

The default value of ScanlineRange.

public static readonly field ScanlineRangeDefault
type PixelRange

Remarks:

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

Creates a new instance of ColorBuffer.

public static method Create (int32 width, int32 height)
type ColorBuffer
params width [>0] Width of the color buffer.
  height [>0] Height of the color buffer.
returns [not-null] The color buffer.

Remarks:

Instances of ColorBuffer can be pooled by calling Delete.

EncodeDistances

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

public static method EncodeDistances (DistanceBuffer red, DistanceBuffer green = null, DistanceBuffer blue = null, DistanceBuffer alpha = null, ColorBuffer buffer = null)
type ColorBuffer
params red Distance buffer to encode in red channel or null.
  green Distance buffer to encode in green channel or null. Defaults to null.
  blue Distance buffer to encode in blue channel or null. Defaults to null.
  alpha Distance buffer to encode in alpha channel or null. Defaults to null.
  buffer The output color buffer. If null a new buffer will be created. Defaults to null.
returns [not-null] The resulting color buffer.

See also:

DistanceBuffer.ToPixel
DistanceBuffer.ToDistance

FromBase85

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

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

See also:

ToBase85

Exceptions:

FromImage

Creates a new instance of ColorBuffer.

public static method FromImage (Path image)
type ColorBuffer
params image [not-null] The source image.
returns [not-null] The created ColorBuffer.

Exceptions:


Creates a new instance of ColorBuffer.

public static method FromImage (IImage image)
type ColorBuffer
params image [not-null] The source image.
returns [not-null] The created ColorBuffer.

Exceptions:


Creates a new instance of ColorBuffer.

public static method FromImage ([Owner] IImageReader image)
type ColorBuffer
params image [not-null] The source image.
returns [not-null] The created ColorBuffer.

Exceptions:


Creates a new instance of ColorBuffer.

public static method FromImage (Path image, float64 gamma)
type ColorBuffer
params image [not-null] The source image.
  gamma The value to use for Gamma.
returns [not-null] The created ColorBuffer.

Exceptions:

FromSamples

Wraps the given sample array into a ColorBuffer object.

public static method FromSamples (int64[] samples, int32 offset, int32 stride, int32 width, int32 height)
type ColorBuffer
params samples [not-null] The sample array.
  offset [>=0] Offset to top-left pixel in samples.
  stride [>0] Distance between adjacent pixels rows, in pixels.
  width [>0] Width of buffer, in pixels.
  height [>0] Height of buffer, in pixels.
returns [not-null] The ColorBuffer object.

ReadPXB

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

public static method ReadPXB (Path file)
type ColorBuffer
params file [not-null] The input file.
returns [not-null] The ColorBuffer object.

Exceptions:


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

public static method ReadPXB ([Owner] IDataStream stream)
type ColorBuffer
params stream [not-null] The input data stream.
returns [not-null] The ColorBuffer object.

Exceptions:


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

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

Exceptions:

Public / Methods

ApplyTransform

Perform an in-place Transform of the samples in the given region.

public method ApplyTransform (int32 x, int32 y, int32 width, int32 height, Transform transform)
params x [0..Width] X-coordinate of top-left sample of region.
  y [0..Height] Y-coordinate of top-left sample of region.
  width [0..Width-x] Width of region to transform.
  height [0..Height-y] Height of region to transform.
  transform The 2D transform to apply.
inherited SampleBuffer.ApplyTransform

Remarks:

For square regions (i.e. same width and height), all Transform s can be applied in-place. For rectangular regions, width and height might be swapped ( WillSwapAxes) while the top-left sample of the given region remains in the same place.

If this sample buffer is not big enough to hold the swapped width resp. height, output samples will be discarded.

This method reads samples from the given input region and writes samples to the transformed output region. No other sample are accessed by this method.

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

Clear

Clears buffer samples to their default value(s).

public method Clear (int32 x = 0, int32 y = 0, int32 countX = -1, int32 countY = -1, int32 step = 1)
params x [0..Width] X-coordinate of top-left buffer sample to clear.
  y [0..Height] Y-coordinate of top-left buffer sample to clear.
  countX [>=-1] Number of buffer samples to clear along X-axis. If -1, samples up to the right buffer edge will be cleared. Defaults to -1.
  countY [>=-1] Number of buffer samples to clear along Y-axis. If -1, samples down to the bottom buffer edge will be cleared. Defaults to -1.
  step [>=1] The step distance between buffer samples. Defaults to 1.
inherited SampleBuffer.Clear

Clone

Clones the sample buffer.

public method Clone ()
type ISampleBuffer
returns [not-null] The clones sample buffer.
inherited SampleBuffer.Clone

Remarks:

The original and cloned buffers will share the buffer samples. Use this method if you need a separate buffer instance (e.g. for configuring buffer specific properties while keeping the original buffer unmodified).

ColorAt

Samples a color value, using linear interpolation.

public method ColorAt (float64 x, float64 y)
type int64
params x Normalized X-coordinate of sample.
  y Normalized Y-coordinate of sample.
returns The interpolated sample.

Remarks:

The given coordinates are normalized, i.e. 0 refers to the top-left edge and 1 refers to the bottom-right edge.

Combine

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

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

Copy

Copies samples from this buffer to the given one.

public method Copy (SampleBuffer<int64> target, int32 targetX = 0, int32 targetY = 0, int32 countX = -1, int32 countY = -1, int32 sourceX = 0, int32 sourceY = 0, int32 sourceStep = 1, int32 targetStep = 1, Transform transform = Transform.None)
params target [not-null] The target buffer.
  targetX [0..target.Width] X-coordinate of top-left sample in target. Defaults to 0.
  targetY [0..target.Height] Y-coordinate of top-left sample in target. Defaults to 0.
  countX [>=-1] Number of buffer samples to copy along source X-axis. If -1, samples up to the nearest buffer edge (source or target) will be copied. Defaults to -1.
  countY [>=-1] Number of buffer samples to copy along source Y-axis. If -1, samples up to the nearest buffer edge (source or target) will be copied. Defaults to -1.
  sourceX [0..Width] X-coordinate of top-left sample in this buffer to copy. Defaults to 0.
  sourceY [0..Height] Y-coordinate of top-left sample in this buffer to copy. Defaults to 0.
  sourceStep [>=1] Step distance between samples in this buffer. Defaults to 1.
  targetStep [>=1] Step distance between samples in target. Defaults to 1.
  transform Optional affine transformation to apply to the copied samples. The top-left corners of the source region and transformed target region coincide. Defaults to None.
inherited SampleBuffer.Copy

Delete

Deletes this object immediately.

public override method Delete ()

Remarks:

Deletion is considered to be a notification that the object is no longer used. The implementation is then free to perform cleanup or pooling actions.

Using an object after Delete has been called will yield undefined results. The code that calls Delete must make sure that there are no shared usages of the object that is being deleted.

Downsample

Performs downsampling on the pixels of this color buffer.

public method Downsample (ColorBuffer output = null, DownsampleFilter filter = DownsampleFilter.Average, bool ceiling = true)
type ColorBuffer
params output The output buffer or null. If null a new color buffer of the required minimum size is created. Defaults to null.
  filter The filter to use for downsampling. Defaults to Average.
  ceiling Chooses the dimension reduction rule (only applies if output 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 CreateBuffer also uses the floor convention.
returns [not-null] The downsampled color buffer.

Remarks:

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 parameter) in order to get a full input pixel block for downsampling. If the output buffer is too small, overhang pixels will be discarded. The input and output buffers can be the same.

DrawBar

Draws a bar.

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

DrawChar

Draws a character using the famous VGA BIOS font.

public method DrawChar (char c, int32 x, int32 y, int64 foreground, int64 background = 0)
params c The Unicode character to draw.
  x Screen X-coordinate of top-left corner of character glyph box.
  y Screen Y-coordinate of top-left corner of character glyph box.
  foreground The foreground color, with alpha (see Colors).
  background The background color, with alpha (see Colors). Defaults to 0 (i.e. transparent black).

Remarks:

The DrawChar method uses the 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:

CharWidth
CharHeight

DrawCircle

Draws a circle.

public method DrawCircle (int32 x, int32 y, int32 radius, int64 color)
params x Screen X-coordinate of center of circle.
  y Screen Y-coordinate of center of circle.
  radius The circle radius, in screen pixels.
  color The circle color.

DrawLine

Draws a line.

public method DrawLine (int32 x1, int32 y1, int32 x2, int32 y2, int64 color)
params x1 X-coordinate of line start point (inclusive).
  y1 Y-coordinate of line start point (inclusive).
  x2 X-coordinate of line end point (inclusive).
  y2 Y-coordinate of line end point (inclusive).
  color The line color, with alpha (see Colors).

DrawPixel

Draws a single pixel.

public method DrawPixel (int32 x, int32 y, int64 color)
params x X-coordinate of pixel.
  y Y-coordinate of pixel.
  color The pixel color, with alpha (see Colors).

DrawRectangle

Draws a rectangle.

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

DrawString

Draws a multi-line text.

public method DrawString (Text text, int32 x, int32 y, int64 foreground, int64 background = 0)
params text The text to draw.
  x X-coordinate of top-left corner of text box.
  y Y-coordinate of top-left corner of text box.
  foreground The foreground color, with alpha (see Colors).
  background The background, with alpha (see Colors). Defaults to 0 (i.e. transparent black).

See also:

CharWidth
CharHeight

Draws a single-line string.

public method DrawString (string s, int32 x, int32 y, int64 foreground, int64 background = 0, int64 outline = 0)
params s The string to draw.
  x X-coordinate of top-left corner of string box.
  y Y-coordinate of top-left corner of string box.
  foreground The foreground color (with alpha).
  background The background color (with alpha). Defaults to 0 (i.e. transparent black).
  outline The outline color color (with alpha). Defaults to 0 (i.e. no outline).

Equals

Compares this object with the given one.

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

Fill

Fills buffer samples with the given value.

public method Fill (int64 value, int32 x = 0, int32 y = 0, int32 countX = -1, int32 countY = -1, int32 step = 1)
params value The value to fill with.
  x [0..Width] X-coordinate of top-left buffer sample to clear.
  y [0..Height] Y-coordinate of top-left buffer sample to clear.
  countX [>=-1] Number of buffer samples to clear along X-axis. If -1, samples up to the right buffer edge will be cleared. Defaults to -1.
  countY [>=-1] Number of buffer samples to clear along Y-axis. If -1, samples down to the bottom buffer edge will be cleared. Defaults to -1.
  step [>=1] The step distance between buffer samples. Defaults to 1.
inherited SampleBuffer.Fill

FromConfigEmbedded

Returns the embedded PXB 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 PXB file.

See also:

ToConfigEmbedded

Exceptions:

Gather

Fetches scattered samples from this sample buffer and stores them into the given array,

public method Gather ([] int64[] target, [] Vec2I[] coords, int32[] indices, int32 first, int32 count)
params target [not-null] The target array.
  coords [not-null] Buffer coordinates of samples to gather from this region.
  indices [not-null] Indices into coords, determining which samples to gather. Also output sample indices for storing results into target.
  first [0..indices.Length] Index of first element in indices to process.
  count [0..indices.Length-first] Number of samples to gather.
inherited SampleBuffer.Gather

GetPixel

Gets a pixel from the buffer.

[Pure]
public method GetPixel (int32 x, int32 y)
type int64
params x [0..Width-1] X-coordinate of pixel.
  y [0..Height-1] Y-coordinate of pixel.
returns The pixel color (see Colors).

HasTransparentPixels

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

public method HasTransparentPixels (int32 x, int32 y, int32 width, int32 height)
type bool
params x [0..Width] X-coordinate of top-left pixel in region to test.
  y [0..Height] Y-coordinate of top-left pixel in region to test.
  width [0..Width-x] Width of region to test, in pixels.
  height [0..Height-y] Height of region to test, in pixels.
returns true if there is at least one pixel in the given region that is transparent, i.e. not fully opaque,
false if all pixels in the region are fully opaque.

IsUniform

Checks if all samples of this buffer are equal to the given value.

public method IsUniform (int64 value)
type bool
params value The sample value.
returns true if all samples are equal to value, false if not.
inherited SampleBuffer.IsUniform

OffsetAt

Computes the buffer index for the given heightmap sample.

[Pure]
public method OffsetAt (int32 y)
type int32
params y [0..Height-1] Y-coordinate of the row.
returns [>=0] Buffer index of the heightmap sample.
inherited SampleBuffer.OffsetAt

Remarks:

The returned buffer index may only be used to access the heightmap samples in the specified row (see y).


Computes the buffer index for the given heightmap sample.

[Pure]
public method OffsetAt (int32 x, int32 y)
type int32
params x [0..Width-1] X-coordinate of sample.
  y [0..Height-1] Y-coordinate of sample.
returns [>=0] Buffer index of the heightmap sample.
inherited SampleBuffer.OffsetAt

Pack

Returns a densely packed sample buffer object that contains the same data as this buffer.

public method Pack ()
type ISampleBuffer
returns [not-null] The packed sample buffer object.
inherited SampleBuffer.Pack

See also:

ISampleBufferBase.IsPacked

Pad

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

public method Pad (int32 width, int32 height, int64 color = 0)
type ColorBuffer
params width [>0] The new width, in samples.
  height [>0] The new height, in samples.
  color The color (see Colors) to use for padding the right and bottom edges.
returns [not-null] The resulting color buffer.

ReadPXBInfo

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

public static method ReadPXBInfo (Path file, out Vec2I info)
type PixelFormat
params file [not-null] The input file.
  info Output for width (see X) and height (see Y).
returns [not-null] The PixelFormat.

Exceptions:


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

public static method ReadPXBInfo ([Owner] IDataStream stream, out Vec2I info)
type PixelFormat
params stream [not-null] The input data stream.
  info Output for width (see X) and height (see Y).
returns [not-null] The PixelFormat.

Exceptions:


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

public static method ReadPXBInfo (IBinaryReader reader, out Vec2I info, IPathInfo pathInfo = null)
type PixelFormat
params reader [not-null] The binary reader.
  info Output for width (see X) and height (see Y).
  pathInfo Optional IPathInfo object to use for error reporting. Defaults to null.
returns [not-null] The PixelFormat.

Exceptions:

Restore

This sample buffer has been taken out of a pool.

public method Restore ()
inherited SampleBuffer.Restore

Scale

Scales this color buffer to the given dimensions.

public method Scale (int32 width, int32 height)
type ColorBuffer
params width [>0] The new width, in pixels.
  height [>0] The new height, in pixels.
returns [not-null] The scaled color buffer.

ScaleOffset

Scales the buffer samples and adds the given offset.

public override method ScaleOffset (float64 scale, float64 offset = 0)
params scale The scale factor.
  offset The offset value. Defaults to 0.
inherited SampleBufferInt64.ScaleOffset

Remarks:

Each tuple component (see TupleSize) of each buffer sample is modified according to this formula:

v' := clamp(round(scale * v + offset))
where v is the sample value currently present in the buffer, v' is the transformed sample and clamp and round are some buffer specific functions that convert the transformed samples back to valid buffer values.

ScanlineRead

Transfers image pixels into the sample buffer.

public override method ScanlineRead (int32 y, Scanline scanline)
params y Y-coordinate of samples to transfer.
  scanline The buffer that holds the scanline pixels.

See also:

ISampleBuffer.ScanlineFormat
ISampleBuffer.ScanlineRange

ScanlineWrite

Transfers buffer samples to the image scanline.

public override method ScanlineWrite (int32 y, Scanline scanline)
params y Y-coordinate of samples to transfer.
  scanline The buffer that holds the scanline pixels.

See also:

ISampleBuffer.ScanlineFormat
ISampleBuffer.ScanlineRange

SetPixel

Sets a pixel in the buffer.

public method SetPixel (int32 x, int32 y, int64 color)
params x [0..Width-1] X-coordinate of pixel.
  y [0..Height-1] Y-coordinate of pixel.
  color The pixel color (see Colors).

SetScanlineFormat

Specifies the pixel format to use for encoding buffer samples.

public method SetScanlineFormat (PixelFormat format = PixelFormat.Unknown)
params format The pixel format to use. Defaults to Unknown.

Remarks:

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

See also:

ScanlineFormat
IBufferCodec

Shift

Shifts the samples in this buffer by the given amount.

public method Shift (int32 x, int32 y, ICollector<Box2I> callback = null)
params x Horizontal shift amount.
  y Vertical shift amount.
  callback Collector for sample buffer regions that have been invalidated by the shift.
inherited SampleBuffer.Shift

Remarks:

This method allows sample buffers to be used in a toroidal manner (i.e. as a two-dimensional ringbuffer).

Specifying a positive value for x will create space for new samples at the left buffer border, a negative value for x will create space at the right border.

Specifying a positive value for y will create space for new samples at the top buffer border, a negative value for y will create space at the bottom border.

The contents of the samples in the additional space at the buffer border is unspecified and must be set by the application.

SubBuffer

Represents an ISampleBuffer object that represents a rectangular subregion of this sample buffer.

public method SubBuffer (int32 x, int32 y, int32 width, int32 height)
type ISampleBuffer
params x [0..Width-width] X-coordinate of top-left sample of subregion.
  y [0..Height-height] Y-coordinate of top-left sample of subregion.
  width [1..Width] Width of subregion.
  height [1..Height] Height of subregion.
returns [not-null] The subregion of this sample buffer.
inherited SampleBuffer.SubBuffer

Remarks:

Modifications made to this sample buffer will be visible to the returned buffer and vice versa.

ToBase85

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

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

See also:

FromBase85

ToConfigEmbedded

Returns a config value for an embedded PXB file.

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

See also:

FromConfigEmbedded

Trim

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

public method Trim (int64 color = 0)
type ColorBuffer
params color Optional color (see Colors) to trim. Defaults to 0.
returns 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 (out Box2I bounds, int64 color = 0)
type ColorBuffer
params bounds The bounds of the returned buffer in this buffer.
  color Optional color (see Colors) to trim. Defaults to 0.
returns The trimmed buffer or null if all buffer pixels are fully transparent.

Warp

Fills a rectangular region in the given target buffer by warping target buffer coordinates to source buffer coordinates using the given transform, followed by interpolation of source buffer samples.

public method Warp (Mat3F transform, bool smooth, SampleBuffer<int64> target, int32 targetX = 0, int32 targetY = 0, int32 targetWidth = -1, int32 targetHeight = -1, int32 sourceX = 0, int32 sourceY = 0, int32 sourceWidth = -1, int32 sourceHeight = -1)
params transform The homogeneous transformation matrix that warps target buffer coordinates (relative to targetX and targetY) to source buffer coordinates (relative to sourceX and sourceY). Such a matrix can be created with Warp. Source buffer coordinates will be clamped to the specified range.
  smooth true to use smooth interpolation (UniformB), false to use accurate interpolation (CatmullRom).
  target [not-null] The target sample buffer.
  targetX [0..target.Width] X-coordinate of top-left corner of target buffer rectangle to fill. Defaults to 0.
  targetY [0..target.Height] Y-coordinate of top-left corner of target buffer rectangle to fill. Defaults to 0.
  targetWidth [>=-1] Width of of target buffer rectangle. If -1, the rectangle will reach to the right target buffer edge. Defaults to -1.
  targetHeight [>=-1] Height of of target buffer rectangle. If -1, the rectangle will reach to the bottom target buffer edge. Defaults to -1.
  sourceX [0..Width] X-coordinate of top-left corner of source buffer rectangle to use for interpolation. Defaults to 0.
  sourceY [0..Height] Y-coordinate of top-left corner of source buffer rectangle to use for interpolation. Defaults to 0.
  sourceWidth [>=-1] Width of of source buffer rectangle. If -1, the rectangle will reach to the right source buffer edge. Defaults to -1.
  sourceHeight [>=-1] Height of of source buffer rectangle. If -1, the rectangle will reach to the bottom source buffer edge. Defaults to -1.
inherited SampleBuffer.Warp

WriteImage

Writes the pixel data in this buffer to the file.

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

Remarks:

The image file format will be determined from the file suffix (see CanWrite).

Exceptions:

WritePXB

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

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

Exceptions:


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

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

Exceptions:


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

public method WritePXB (IBinaryWriter writer)
params writer [not-null] The output writer.

Exceptions:

WriteTXB

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

public method WriteTXB (Path file, TextureFormat format = null, int32 mipmaps = 1)
params file [not-null] The output file.
  format The texture format to use. If null, an appropriate format will be chosen automatically. Defaults to null.
  mipmaps [>=0] Number of mipmaps to generate.

See also:

TextureFormat.For
TexelBuffer.PixelEncodeMipmaps
TexelBuffer.WriteTXB

Exceptions: