class CoverageBuffer in Tinman.Terrain.Buffers

An implementation of the ISampleBuffer interface that stores 30-bit coverage values (see MaxValue30).

sealed class	CoverageBuffer	implements	IDeletable
		extends	SampleBufferInt32

See also:

HeightmapSample.Coverage

Public / Constants

ScanlineRangeDefault

The default value of ScanlineRange.

public static readonly field	ScanlineRangeDefault
type	PixelRange

Remarks:

For image coding, the raw pixel value corresponds to the coverage value (see Elevation).

The default pixel range maps the coverage values 0 and MaxValue30 to black resp. white.

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

Create

Creates a new instance of CoverageBuffer.

public static method	Create (int32 width, int32 height)
type	CoverageBuffer
params	width	[>0]	Width of the coverage buffer.
	height	[>0]	Height of the coverage buffer.

Remarks:

Instances of CoverageBuffer can be pooled by calling Delete.

FromImage

Creates a new instance of CoverageBuffer.

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

---

Creates a new instance of CoverageBuffer.

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

---

Creates a new instance of CoverageBuffer.

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

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

Delete

Deletes this object immediately.

public method	Delete ()
implements	IDeletable.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.

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

Invert

Inverts the coverage values in this buffer.

public method

Invert ()

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

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