class DistanceBuffer in Tinman.Terrain.Buffers

A distance buffer stores signed distance values towards the border of a two-dimensional shape (negative is inside).

sealed class

DistanceBuffer

extends

SampleBufferFloat32

Remarks

Distance textures can be used for high-quality rendering of shapes (for example terrain decals). The samples in a distance buffer have a pixel-is-area semantic (see PixelIsArea): The sample value is the distance from the center of the sample area towards the nearest point on the shape border.

Public / Constants

ScanlineRangeDefault

The default value of ScanlineRange.

public static readonly field	ScanlineRangeDefault
type	PixelRange

Remarks:

The distance value range is exploited during rasterization: regions that only contain distance values below the minimum bound or above the maximum bound will be skipped.

For image coding, the raw pixel value corresponds to the signed distance value.

The default pixel range maps signed distance values as follows:
-1: 16777215 (i.e. maximum pixel channel value when inside of shape)
+1: 0 (i.e. minimum pixel channel value when outside of shape).

Public / Attributes

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.

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	T[]
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.
implements	SampleBuffer.ScanlineFormat

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 / Constructors

DistanceBuffer

Creates a new instance of DistanceBuffer.

public constructor	DistanceBuffer (int32 width, int32 height)
params	width	[>0]	The buffer width, in samples.
	height	[>0]	The buffer height, in samples.

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.

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

Copy

Copies samples from this buffer to the given one.

public method	Copy (SampleBuffer<T> 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

Downsample

Performs downsampling on the samples of this distance buffer.

public method	Downsample (DistanceBuffer output = null, DownsampleFilter filter = DownsampleFilter.Average)
type	DistanceBuffer
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.
returns		[not-null]	The downsampled color buffer.

Remarks:

Each block of 2x2 input samples is downsampled to a single output sample.

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

If this distance buffer has a width and/or height that is not divisible by two, samples will be duplicated in order to get a full input sample block for downsampling. If the output buffer is too small, overhang samples will be discarded. The input and output buffers can be the same.

EncodePixels

Encodes the signed distances in this buffer into pixels.

public method	EncodePixels (IColorRamp ramp, ColorBuffer buffer = null)
type	ColorBuffer
params	ramp	[not-null]	The color ramp to use for mapping signed distance values to pixel colors.
	buffer		The output buffer or null to create a new one. Defaults to null.
returns		[not-null]	The encoded pixel buffer.

---

Encodes the signed distances in this buffer into pixels.

public method	EncodePixels (IColorRamp ramp, ColorBuffer buffer, ColorOp colorOp)
type	ColorBuffer
params	ramp	[not-null]	The color ramp to use for mapping signed distance values to pixel colors.
	buffer		The output buffer or null to create a new one. Defaults to null.
	colorOp		The ColorOp to use to combine the samples in buffer (first) with the encoded pixels (second).
returns		[not-null]	buffer

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 (T 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

Gather

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

public method	Gather ([] T[] 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

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

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	SampleBufferFloat32.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.
implements	SampleBuffer.ScanlineRead

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.
implements	SampleBuffer.ScanlineWrite

See also:

ISampleBuffer.ScanlineFormat
ISampleBuffer.ScanlineRange

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.

ToDistance

Converts the given pixel channel value to a signed distance.

[Pure]
public method	ToDistance (int32 pixel)
type	float32
params	pixel		The pixel channel value, in the range [0..16777215].
returns			The signed distance.

See also:

Range

ToPixel

Converts the given signed distance into a pixel channel value.

[Pure]
public method	ToPixel (float32 distance)
type	int32
params	distance		The signed distance.
returns		[0..16777215]	The pixel channel value.

See also:

Range

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