class Canvas in Tinman.Terrain.Tools

The Canvas maps a rectangular map or a cubemap onto a contiguous pixel layer.

abstract class	Canvas	extends	Disposable
		implements	ICanvasBlockSize
			IGeorefInfo

Remarks

Putting a rectangular map or a cubemap onto a pixel layer involves these steps:

• Unfolding of the cubemap faces faces (see below).
• Mapping to coverage of pixel layer:
  Coordinates on the rectangular map resp. cubemap always refer to infinitesimal points (see PixelIsPoint semantic). Same holds for unfolded canvas raster coordinates. The pixels in a canvas block (and thus the pixel layer) can have either PixelIsPoint or PixelIsArea semantic (see below).

Cubemaps are unfolded onto the canvas as follows:

         +--------+
         |        |
         |        |
         |        |
+--------+--------+--------+--------+
|        |        |        |        |
|        | Center |        |        |
|        |        |        |        |
+--------+--------+--------+--------+
         |        |
         |        |
         |        |
         +--------+

The Face of Center depicts which cubemap face will be the Center one (see figure). By default, the canvas X- and Y-axis correspond to the cubemap face axes. An optional simple coordinate transform for the Center face can be specified via Transform. The other faces will be unfolded and displayed accordingly. When the map rectangular, only the Center face (always NegZ) will be displayed.

The pixel layer contents are generated lazily when a block is first requested. Generated blocks are cached with an LRU scheme. An aggregated ICanvasContent is used for creating the cached content. By providing the content object, the application can create its own representation for canvas block content, depending on the API used.

When the pixel layer has a PixelIsPoint coverage (see BlockSize), blocks are mapped onto the canvas as follows:

0   4   8   12  16  20  24  28  32     .-->
+---+---+---+---+---+---+---+---+      | Canvas X- and Y-axis
|   |   |   |   |   |   |   |   |      V
+---+---oooo#oooo---ooooo---+---+ 4
|   |   o   #   o   o   o   |   |      o := Block edge samples
+---+---oooo#oooo---#####---+---+ 8    # := Shared edge samples
|   |   |   |   |   o   o   |   |
+---+---+---+---+---ooooo---+---+ ...

The block size is always a power of two plus one. Adjacent blocks have overlapping edges (one raster sample). Pixel coordinates are mapped directly to canvas raster coordinates.

When the pixel layer has a PixelIsArea coverage (see BlockSize), blocks are mapped onto the canvas as follows:

0   4   8   12  16  20  24  28  32     .-->
+---+---+---+---+---+---+---+---+      | Canvas X- and Y-axis
|   |   |   |   |   |   |   |   |      V
+---+---+---+---+---+---+---+---+ 4
|   |   |###|###|   |###|   |   |      # := Block samples
+---+---+---+---+---+---+---+---+ 8
|   |   |   |   |   |###|   |   |
+---+---+---+---+---+---+---+---+ ...

The block size is always a power of two. Adjacent blocks are disjoint. Pixel coordinates are mapped to the top-left corner of the corresponding pixel on the canvas raster.

See also:

IHeightmap
IPixelLayer

Public / Constants

PixelSizeMaximum

The maximum pixel size of a canvas.

public static readonly field	PixelSizeMaximum
type	Vec2I

See also:

PixelSize

Public / Attributes

BlockCountX

The number of map blocks along the canvas X-axis that intersect the current canvas bounds.

public property	BlockCountX { get }
type	int32
value	[>=0]	The horizontal block count.

BlockCountY

The number of map blocks along the canvas Y-axis that intersect the current canvas bounds.

public property	BlockCountY { get }
type	int32
value	[>=0]	The vertical block count.

BlockCoverage

Pixel coverage semantic of canvas blocks.

public property	BlockCoverage { get }
type	PixelCoverage
value		The coverage semantic.

See also:

BlockSize

BlockSize

Size of a canvas block.

public property	BlockSize { get }
type	int32
value	[>0]	The block size, in canvas raster samples.
implements	ICanvasBlockSize.BlockSize

Remarks:

For PixelIsPoint semantics, the block size is a power of two plus one. For PixelIsArea semantics, the block size is a power of two.

See also:

BlockCoverage

BlockSizeNoOverlap

Size of a canvas block, without overlap.

public property	BlockSizeNoOverlap { get }
type	int32
value	[pow2]	The block size (edge length, not sample count).

Busy

Returns the busy state of this canvas.

public property	Busy { get }
type	int32
value		The busy state: 0: the canvas is idle. 1: the canvas is computing map regions. 2: the canvas is loading map tiles.

CacheSize

The cache size, in blocks.

public property	CacheSize { get }
type	int32
value	[>0]	The cache size.

Remarks:

This is the same value that has been passed to Reset.

CanvasSize

The size of the virtual canvas.

public property	CanvasSize { get }
type	Vec2L
value		The canvas size, in map samples.

Remarks:

For cubic heightmaps, the virtual canvas has the following layout:

Cubic heightmaps:
         +--------+
         |        |  width  := 4 * n + 1
         |        |  height := 3 * n + 1
         |        |  n      := size - 1
+--------+--------+--------+--------+
|        |        |        |        |
|        | Center |        |        |
|        |        |        |        |
+--------+--------+--------+--------+
         |        |
         |        |
         |        |
         +--------+

where size is the internal Size of the current Heightmap.

For rectangular heightmaps, the virtual canvas is also rectangular and has the same dimensions as the map (see Width and Height).

Center

Heightmap coordinates of the center of the current canvas bounds.

public property	Center { get set }
type	CubemapFaceCoordsI
value		The center coordinates.

Remarks:

For rectangular heightmaps, the Face will be set to NegZ.

Georef

Returns georeferencing information.

public abstract property	Georef { get }
type	Raster
value		The georeferencing object or null if no georeferencing is available.
implements	IGeorefInfo.Georef

GridLines

The map gridlines (longitude and latitude, in degrees).

public property	GridLines { get }
type	IVectorConst<GridLine>
value	[not-null]	The list of map gridlines.

IsScrolling

Checks if the current settings of Center, Step and PixelSize create a view of the virtual canvas that required scrolling.

public property	IsScrolling { get }
type	bool
value		true if scrolling is required, false if the entire virtual canvas fits into the pixel window.

LifecycleState

Returns the lifecycle state of this object.

public virtual property	LifecycleState { get }
type	LifecycleState
value		The lifecycle state.
inherited	Disposable.LifecycleState

Map

Returns a MapInfo value that describes the used map raster.

public property	Map { get }
type	MapInfo
value		The map info value.
implements	IMapInfo.Map

PixelSize

The pixel size of the current canvas bounds.

public property	PixelSize { get set }
type	Vec2I
value		The size, in pixels.

See also:

PixelSizeMaximum

Regions

The map regions in the current view that contain data.

public property	Regions { get }
type	IMapRegion
value	[not-null]	The map regions with data.

RegionsInverse

The map regions in the current view that contain no data.

public property	RegionsInverse { get }
type	IMapRegion
value	[not-null]	The map regions with no data.

Step

The current sample step distance.

public property	Step { get set }
type	int32
value		The step distance.

See also:

StepMaximum

StepMaximum

The maximum sample step distance.

public property	StepMaximum { get }
type	int32
value	[pow2]	The maximum step distance.

See also:

Step

Transform

The 2D transform to apply to the cubemap face of Center.

public property	Transform { get set }
type	Transform
value		The 2D transform.

Public / Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
public method	AcquireTry ()
type	IDisposable
returns			this if a new strong reference has been acquired, null if this object is already being disposed.
inherited	Disposable.AcquireTry

Remarks:

The object will not be actually disposed by calls to Dispose when there is at least one strong reference left. Code that calls the AcquireTry method is responsible for calling the Dispose method accordingly.

This method is not intended to be used in performance-critical code. It should only be used to high-level resource management.

Anchor

public method	Anchor (Vec2I xy)
type	CanvasAnchor
params	xy

---

public method	Anchor (int32 x, int32 y)
type	CanvasAnchor
params	x
	y

Block

Returns the cache index of a canvas block.

public method	Block (int32 x, int32 y, bool load = true)
type	CanvasBlock
params	x		X-coordinate of canvas block.
	y		Y-coordinate of canvas block.
	load		true to load the canvas block if necessary, false to return already loaded blocks only.
returns			The canvas block.

BlockBounds

Returns the map bounds of the given canvas block.

public method	BlockBounds (int32 x, int32 y)
type	CubemapFaceRect
params	x	[0..BlockCountX-1]	X-coordinate of canvas block.
	y	[0..BlockCountY-1]	Y-coordinate of canvas block.
returns			The canvas block bounds.

BlockCoords

Returns the pixel coordinates of the given block.

public method	BlockCoords (int32 x, int32 y)
type	Vec2I
params	x	[0..BlockCountX-1]	X-coordinate of canvas block.
	y	[0..BlockCountY-1]	Y-coordinate of canvas block.
returns			The pixel coordinates of the top-left block sample.

BlocksPreload

Starts to load all canvas blocks in the current bounds.

public method

BlocksPreload ()

ClearCache

public method

ClearCache ()

Dispose

Releases all resources held by this object if there are no more strong references to it, decrements the reference counter by one otherwise.

[Dispose, OwnerThis, ThreadSafe]
public method	Dispose ()
inherited	Disposable.Dispose

Remarks:

The Dispose method silently returns if the object has already been disposed.

FaceTransform

Returns the transformation from cubemap face coordinates to canvas coordinates.

public method	FaceTransform (CubemapFace face)
type	Transform
params	face		The cubemap face.
returns			The face transform.

TranslateCanvasToMap

Translates canvas coordinates (see CanvasSize) to map coordinates (see Center).

public method	TranslateCanvasToMap (Vec2I canvas, CubemapFace face, out CubemapFaceCoordsI coords)
type	bool
params	canvas		The input canvas coordinates.
	face		The cubemap face of canvas. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

---

Translates canvas coordinates (see CanvasSize) to map coordinates (see Center).

public method	TranslateCanvasToMap (Vec2L canvas, CubemapFace face, out CubemapFaceCoordsI coords)
type	bool
params	canvas		The input canvas coordinates.
	face		The cubemap face of canvas. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

---

Translates canvas coordinates (see CanvasSize) to map coordinates (see Center).

public method	TranslateCanvasToMap (Vec2D canvas, CubemapFace face, out CubemapFaceCoordsD coords)
type	bool
params	canvas		The input canvas coordinates.
	face		The cubemap face of canvas. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

---

Translates canvas coordinates (see CanvasSize) to map coordinates (see Center).

public method	TranslateCanvasToMap (int64 canvasX, int64 canvasY, CubemapFace face, out CubemapFaceCoordsI coords)
type	bool
params	canvasX		The input canvas X-coordinate.
	canvasY		The input canvas Y-coordinate.
	face		The cubemap face of canvasX and canvasY. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

---

Translates canvas coordinates (see CanvasSize) to map coordinates (see Center).

public method	TranslateCanvasToMap (float64 canvasX, float64 canvasY, CubemapFace face, out CubemapFaceCoordsD coords)
type	bool
params	canvasX		The input canvas X-coordinate.
	canvasY		The input canvas Y-coordinate.
	face		The cubemap face of canvasX and canvasY. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

TranslateCanvasToPixel

Translates canvas coordinates (see CanvasSize) to pixel coordinates (see PixelSize).

public method	TranslateCanvasToPixel (Vec2I canvas)
type	Vec2D
params	canvas		The input canvas coordinates.
returns			The output pixel coordinates.

---

Translates canvas coordinates (see CanvasSize) to pixel coordinates (see PixelSize).

public method	TranslateCanvasToPixel (Vec2L canvas)
type	Vec2D
params	canvas		The input canvas coordinates.
returns			The output pixel coordinates.

---

Translates canvas coordinates (see CanvasSize) to pixel coordinates (see PixelSize).

public method	TranslateCanvasToPixel (Vec2D canvas)
type	Vec2D
params	canvas		The input canvas coordinates.
returns			The output pixel coordinates.

---

Translates canvas coordinates (see CanvasSize) to pixel coordinates (see PixelSize).

public method	TranslateCanvasToPixel (float64 x, float64 y)
type	Vec2D
params	x		The input canvas X-coordinate.
	y		The input canvas Y-coordinate.
returns			The output pixel coordinates.

TranslateMapToCanvas

Translates map coordinates (see Center) to canvas coordinates ( CanvasSize).

public method	TranslateMapToCanvas (CubemapFaceCoordsI map)
type	Vec2L
params	map		The input map coordinates.
returns			The output canvas coordinates.

---

Translates map coordinates (see Center) to canvas coordinates ( CanvasSize).

public method	TranslateMapToCanvas (CubemapFaceCoordsD map)
type	Vec2D
params	map		The input map coordinates.
returns			The output canvas coordinates.

---

Translates map coordinates (see Center) to canvas coordinates (see CanvasSize).

public method	TranslateMapToCanvas (int32 faceX, int32 faceY, CubemapFace face = CubemapFace.NegZ)
type	Vec2L
params	faceX		The input cubemap face X-coordinate.
	faceY		The input cubemap face Y-coordinate.
	face		The input cubemap face. Defaults to NegZ.
returns			The output canvas coordinates.

---

Translates map coordinates (see Center) to canvas coordinates (see CanvasSize).

public method	TranslateMapToCanvas (float64 faceX, float64 faceY, CubemapFace face = CubemapFace.NegZ)
type	Vec2D
params	faceX		The input cubemap face X-coordinate.
	faceY		The input cubemap face Y-coordinate.
	face		The input cubemap face. Defaults to NegZ.
returns			The output canvas coordinates.

TranslateMapToPixel

Translates map coordinates (see Center) to pixel coordinates (see PixelSize).

public method	TranslateMapToPixel (CubemapFaceCoordsI map)
type	Vec2D
params	map		The input map coordinates.
returns			The output pixel coordinates.

---

Translates map coordinates (see Center) to pixel coordinates (see PixelSize).

public method	TranslateMapToPixel (CubemapFaceCoordsD map)
type	Vec2D
params	map		The input map coordinates.
returns			The output pixel coordinates.

---

Translates map coordinates (see Center) to pixel coordinates (see PixelSize).

public method	TranslateMapToPixel (int32 x, int32 y, CubemapFace face = CubemapFace.NegZ)
type	Vec2D
params	x		The input cubemap face X-coordinate.
	y		The input cubemap face Y-coordinate.
	face		The input cubemap face. Defaults to NegZ.
returns			The output pixel coordinates.

---

Translates map coordinates (see Center) to pixel coordinates (see PixelSize).

public method	TranslateMapToPixel (float64 x, float64 y, CubemapFace face = CubemapFace.NegZ)
type	Vec2D
params	x		The input cubemap face X-coordinate.
	y		The input cubemap face Y-coordinate.
	face		The input cubemap face. Defaults to NegZ.
returns			The output pixel coordinates.

TranslatePixelToCanvas

Translates pixel coordinates (see PixelSize) to canvas coordinates (see CanvasSize).

public method	TranslatePixelToCanvas (Vec2I xy)
type	Vec2L
params	xy		The input pixel coordinates.
returns			The output canvas coordinates.

---

Translates pixel coordinates (see PixelSize) to canvas coordinates (see CanvasSize).

public method	TranslatePixelToCanvas (Vec2D xy)
type	Vec2D
params	xy		The input pixel coordinates.
returns			The output canvas coordinates.

---

Translates pixel coordinates (see PixelSize) to canvas coordinates (see CanvasSize).

public method	TranslatePixelToCanvas (int32 x, int32 y)
type	Vec2L
params	x		The input pixel X-coordinate.
	y		The input pixel Y-coordinate.
returns			The output canvas coordinates.

---

Translates pixel coordinates (see PixelSize) to canvas coordinates (see CanvasSize).

public method	TranslatePixelToCanvas (float64 x, float64 y)
type	Vec2D
params	x		The input pixel X-coordinate.
	y		The input pixel Y-coordinate.
returns			The output canvas coordinates.

TranslatePixelToMap

Translates pixel coordinates (see PixelSize) to map coordinates (see Center).

public method	TranslatePixelToMap (Vec2I xy, CubemapFace face, out CubemapFaceCoordsI coords)
type	bool
params	xy		The input pixel coordinates.
	face		The cubemap face of xy. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

---

Translates pixel coordinates (see PixelSize) to map coordinates (see Center).

public method	TranslatePixelToMap (Vec2D xy, CubemapFace face, out CubemapFaceCoordsD coords)
type	bool
params	xy		The input pixel coordinates.
	face		The cubemap face of xy. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

---

Translates pixel coordinates (see PixelSize) to map coordinates (see Center).

public method	TranslatePixelToMap (int32 x, int32 y, CubemapFace face, out CubemapFaceCoordsI coords)
type	bool
params	x		The input pixel X-coordinate.
	y		The input pixel Y-coordinate.
	face		The cubemap face of x and y. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

---

Translates pixel coordinates (see PixelSize) to map coordinates (see Center).

public method	TranslatePixelToMap (float64 x, float64 y, CubemapFace face, out CubemapFaceCoordsD coords)
type	bool
params	x		The input pixel X-coordinate.
	y		The input pixel Y-coordinate.
	face		The cubemap face of x and y. Set to None if unknown.
	coords		The output map coordinates.
returns			true on success, false if the input coordinates cannot be mapped onto the map.

Update

Updates the canvas content.

public virtual method	Update ()
type	CanvasUpdateFlags
returns			The update flags.

Remarks:

All canvas blocks that have finished loading in the background will be provided to Create.

Protected / Attributes

content

The delegate object that creates application-specific block content.

[Owner]
protected field	content
type	ICanvasContent

Protected / Constructors

Canvas

Creates a new instance of Canvas.

protected constructor	Canvas (int32 blockSize, MapInfo map, [Owner] ICanvasContent content)
params	blockSize	[>0]	The canvas block size.
	map		The source map.
	content	[not-null]	The object that actually stores the contents of the generated canvas blocks.

Protected / Methods

BlockDirty

protected method	BlockDirty (int32 index)
params	index

DisposeManaged

Disposes the managed resources held by a concrete subclass. This method will be called at most once per subclass.

protected override method	DisposeManaged ()
overrides	Disposable.DisposeManaged

Remarks:

This method will only be called when a disposable object is explicitly destroyed by user code calling the Dispose method. It will not be called when the object is collected as garbage by the system.

Overriding methods must call the DisposeManaged method of their base class. The base call should be the last statement.

The DisposeManaged method is called before the DisposeUnmanaged method.

DisposeUnmanaged

Disposes the unmanaged resources held by a concrete subclass. This method will be called exactly once per subclass.

protected virtual method	DisposeUnmanaged ()
inherited	Disposable.DisposeUnmanaged

Remarks:

Overriding methods must call the DisposeUnmanaged method of their base class. The base call should be the last statement.

The DisposeUnmanaged method is called after the DisposeManaged method.

DoBlockLoad

[ThreadSafe]
protected abstract method	DoBlockLoad (CubemapFaceRect bounds, int32 step, Transform transform)
type	ColorBuffer
params	bounds
	step
	transform

DoRegionsCollect

[ThreadSafe]
protected abstract method	DoRegionsCollect (ICollector<CubemapFaceRect> regions, CubemapFaceRect bounds, int32 blockSize)
params	regions
	bounds
	blockSize

RegionsDirty

protected method

RegionsDirty ()

Logging

Logger

The logger object of this class.

public static readonly field	Logger
type	ILogger