interface ISampleBuffer in Tinman.Terrain.Buffers

Base interface for classes that represent buffers for heightmap sample values.

interface	ISampleBuffer	extends	IEquatable<ISampleBuffer>
			ISampleBufferBase
		base of	SampleBuffer

Remarks

Subclasses provide an array that stores the buffer samples. This array can be accessed as follows:

Samples[Offset + y * Stride + x * TupleSize + z] := value

where x and y are the coordinates of the buffer sample and z is the index of the tuple component to access.

Attributes

Height

The height of the buffer, in samples.

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

IsPacked

Returns if this sample buffer is densely packed.

property	IsPacked { get }
type	bool
value		true if this buffer is densely packed, false if not.
inherited	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.

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

Offset

Index of top-left sample in the buffer.

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

ScanlineFormat

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

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

See also:

ScanlineRead
ScanlineWrite

ScanlineRange

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

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

See also:

ScanlineRead
ScanlineWrite

Stride

Distance between two consecutive rows in the buffer.

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

TupleSize

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

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

Width

The width of the buffer, in samples.

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

Methods

ApplyTransform

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

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.

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

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.

Clone

Clones the sample buffer.

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

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

OffsetAt

Computes the buffer index for the given heightmap sample.

[Pure]
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	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]
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	ISampleBufferBase.OffsetAt

Pack

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

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

See also:

ISampleBufferBase.IsPacked

ScaleOffset

Scales the buffer samples and adds the given offset.

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

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.

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

See also:

ScanlineFormat
ScanlineRange

ScanlineWrite

Transfers buffer samples to the image scanline.

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

See also:

ScanlineFormat
ScanlineRange

Shift

Shifts the samples in this buffer by the given amount.

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

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.

Remarks:

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

Extensions

ReadAsImage

Reads the samples in this sample buffer as an image.

[OwnerReturn]
method	ReadAsImage ()
type	IImageReader
returns		[not-null]	The IImageReader object.

ReadFromImage

Replaces the values in this sample buffer with the pixels read from the given source image.

method	ReadFromImage ([Owner] IImageReader image)
params	image	[not-null]	The source image.

Remarks:

Both Width and Height of image must be equal to the width and height of this ISampleBuffer object.