class SampleBuffer in Tinman.Terrain.Buffers

Abstract base class for ISampleBuffer implementations.

abstract class	SampleBuffer	with	<T>	as	struct
		implements	ISampleBuffer
		base of	SampleBufferFloat32
			SampleBufferInt32
			SampleBufferInt64

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.
implements	ISampleBufferBase.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.
implements	ISampleBufferBase.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.
implements	IMemoryConsumption.MemoryConsumption

Offset

Index of top-left sample in the buffer.

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

Samples

The samples of this buffer.

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

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 abstract property	ScanlineFormat { get }
type	PixelFormat
value		The pixel format.
implements	ISampleBuffer.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.
implements	ISampleBuffer.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.
implements	ISampleBufferBase.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.
implements	ISampleBuffer.TupleSize

Width

The width of the buffer, in samples.

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

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.
implements	ISampleBuffer.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.
implements	ISampleBuffer.Clear

Clone

Clones the sample buffer.

public method	Clone ()
type	ISampleBuffer
returns		[not-null]	The clones sample buffer.
implements	ISampleBuffer.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.

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.
implements	IEquatable.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.

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.

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.
implements	ISampleBufferBase.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.
implements	ISampleBufferBase.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.
implements	ISampleBuffer.Pack

See also:

ISampleBufferBase.IsPacked

ScaleOffset

Scales the buffer samples and adds the given offset.

public abstract method	ScaleOffset (float64 scale, float64 offset = 0)
params	scale		The scale factor.
	offset		The offset value. Defaults to 0.
implements	ISampleBuffer.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 abstract method	ScanlineRead (int32 y, Scanline scanline)
params	y		Y-coordinate of samples to transfer.
	scanline		The buffer that holds the scanline pixels.
implements	ISampleBuffer.ScanlineRead

See also:

ISampleBuffer.ScanlineFormat
ISampleBuffer.ScanlineRange

ScanlineWrite

Transfers buffer samples to the image scanline.

public abstract method	ScanlineWrite (int32 y, Scanline scanline)
params	y		Y-coordinate of samples to transfer.
	scanline		The buffer that holds the scanline pixels.
implements	ISampleBuffer.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.
implements	ISampleBufferBase.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.
implements	ISampleBuffer.SubBuffer

Remarks:

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

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.

Protected / Attributes

BytesPerTuple

Returns the number of bytes per buffer sample tuple element.

protected abstract property	BytesPerTuple { get }
type	int32
value	[>0]	The number of bytes per buffer sample tuple element.

height

Height of this sample buffer.

protected readonly field	height
type	int32

offset

Offset of top-left sample of this sample buffer in buffer array.

protected readonly field	offset
type	int32

pixelOffset

protected readonly field	pixelOffset
type	Vec2D

samples

The buffer sample array.

protected readonly field	samples
type	T[]

scanlineToPixel

Linear transformation from buffer samples to scanline pixel channel values.

protected field	scanlineToPixel
type	Vec2D

See also:

PixelRange.Transform

scanlineToSample

Linear transformation from pixel channel values to buffer samples.

protected field	scanlineToSample
type	Vec2D

See also:

PixelRange.Transform

stride

The stride of this sample buffer.

protected readonly field	stride
type	int32

tupleSize

The buffer sample tuple size.

protected readonly field	tupleSize
type	int32

width

Width of this sample buffer.

protected readonly field	width
type	int32

Protected / Constructors

SampleBuffer

Creates a new instance of SampleBuffer.

protected constructor	SampleBuffer (int32 width, int32 height, int32 tupleSize)
params	width	[>0]	Width of this sample buffer.
	height	[>0]	Height of this sample buffer.
	tupleSize	[1..4]	The tuple size of each buffer sample.

Remarks:

A new sample buffer array will be allocated.

---

Creates a new instance of SampleBuffer.

protected constructor	SampleBuffer (int32 width, int32 height, int32 offset, int32 stride, int32 tupleSize, T[] samples)
params	width	[>0]	Width of this sample buffer.
	height	[>0]	Height of this sample buffer.
	offset	[>=0]	Offset of top-left sample of this sample buffer in buffer array.
	stride	[>0]	The stride of this sample buffer.
	tupleSize	[1..4]	The tuple size of each buffer sample.
	samples	[not-null]	The buffer samples.

Remarks:

This sample buffer will use the given data array.

Protected / Methods

ClearInternal

Clears array elements to their default values.

protected abstract method	ClearInternal (T[] samples, int32 offset, int32 count)
params	samples		The array.
	offset		Offset into samples.
	count		Number of array elements to clear.

CopyInternal

Copies array elements from source to target.

protected abstract method	CopyInternal (T[] source, int32 sourceOffset, T[] target, int32 targetOffset, int32 count)
params	source		The source array.
	sourceOffset		Offset into source.
	target		The target array.
	targetOffset		Offset into target.
	count		Number of array elements to copy.

EqualsInternal

Compares array elements in source with those in target for equality.

protected abstract method	EqualsInternal (T[] source, int32 sourceOffset, T[] target, int32 targetOffset, int32 count)
type	bool
params	source		The source array.
	sourceOffset		Offset into source.
	target		The target array.
	targetOffset		Offset into target.
	count		Number of array elements to compare.
returns			true if the array elements are equal, false if not.

Interpolate4

Interpolates a sample value from the given sample block.

[Pure]
protected abstract method	Interpolate4 (T a, T b, T c, T d, int32 f, bool smooth)
type	T
params	a		Sample block value.
	b		Sample block value.
	c		Sample block value.
	d		Sample block value.
	f		Interpolation factor, in the range [0..65536].
	smooth		true to use smooth interpolation (UniformB), false to use accurate interpolation (CatmullRom).
returns			The interpolated value.

Remarks:

Interpolation occurs between b, c:

+---+---+---+---+
| a | b | c | d |
+---+---+---+---+

The interpolation factors are mapped as follows:

• f = 0 =>b
• f = 65536 =>c

Interpolate4x4

Interpolates a sample value from the given sample block.

[Pure]
protected abstract method	Interpolate4x4 (int32 offset, int32 fx, int32 fy, bool smooth)
type	T
params	offset		Offset to a in samples.
	fx		Horizontal interpolation factor, in the range [0..65536].
	fy		Vertical interpolation factor, in the range [0..65536].
	smooth		true to use smooth interpolation (UniformB), false to use accurate interpolation (CatmullRom).
returns			The interpolated value.

Remarks:

Interpolation occurs between f, g, j and k:

+---+---+---+---+
| a | b | c | d |
+---+---+---+---+
| e | f | g | h |
+---+---+---+---+
| i | j | k | l |
+---+---+---+---+
| m | n | o | p |
+---+---+---+---+

The interpolation factors are mapped as follows:

• (fx = 0, fy = 0) =>f
• (fx = 65536, fy = 0) =>g
• (fx = 0, fy = 65536) =>j
• (fx = 65536, fy = 65536) =>k

InterpolateFix

[EmptyBody]
protected virtual method	InterpolateFix (int32 x, int32 y, int32 width, int32 height)
params	x
	y
	width
	height

NewBuffer

Creates a new sample buffer of the same type as this buffer.

protected abstract method	NewBuffer (int32 width, int32 height)
type	SampleBuffer<T>
params	width		Width of the buffer.
	height		Height of the buffer.
returns		[not-null]	The ISampleBuffer object.

NewSharedBuffer

Creates a new sample buffer that shares a subregion of this sample buffer.

protected abstract method	NewSharedBuffer (int32 width, int32 height, int32 offset, int32 stride)
type	SampleBuffer<T>
params	width		Width of the sub buffer.
	height		Height of the sub buffer.
	offset		Offset of top-left sample of sub buffer.
	stride		Stride of this sample buffer.
returns		[not-null]	The ISampleBuffer object.

ScaleOffsetClamp

protected abstract method	ScaleOffsetClamp (float64 scale, float64 offset, T minimum, T maximum)
params	scale
	offset
	minimum
	maximum