Canvas

Description

abstract class Tinman.Terrain.Tools.Canvas

Derived from

Disposable abstract
ICanvasBlockSize
IGeorefInfo

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

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 PixelCoverage.PixelIsPoint semantic). Same holds for unfolded canvas raster coordinates. The pixels in a canvas block (and thus the pixel layer) can have either PixelCoverage.PixelIsPoint or PixelCoverage.PixelIsArea semantic (see below).

Cubemaps are unfolded onto the canvas as follows:

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

The CubemapFaceCoordsI.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 CubemapFace.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 PixelCoverage.PixelIsPoint coverage (see ICanvasBlockSize.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 PixelCoverage.PixelIsArea coverage (see ICanvasBlockSize.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.

Public / Constants

Pixel​Size​Maximum


public static readonly attribute PixelSizeMaximum → (Vec2I)

The maximum pixel size of a canvas.

See also

Canvas.PixelSize

Public / Methods

Anchor

2 overloads


public method Anchor1 → (1)

xy in : Vec2I

The screen location.

returns → CanvasAnchor

The canvas anchor.

Creates an anchor for the given screen location.


public method Anchor2 → (2)

in : int32

X-coordinate of screen location.

in : int32

Y-coordinate of screen location.

returns → CanvasAnchor

The canvas anchor.

Creates an anchor for the given screen location.

Block


public method Block → (3)

in : int32

X-coordinate of canvas block.

in : int32

Y-coordinate of canvas block.

load opt : bool = true

true to load the canvas block if necessary, false to return already loaded blocks only.

returns → CanvasBlock

The canvas block.

Returns the cache index of a canvas block.

Block​Bounds


public method BlockBounds → (2)

in : int32

[0..Canvas.BlockCountX-1]
X-coordinate of canvas block.

in : int32

[0..Canvas.BlockCountY-1]
Y-coordinate of canvas block.

returns → CubemapFaceRect

The canvas block bounds.

Returns the map bounds of the given canvas block.

Block​Coords


public method BlockCoords → (2)

in : int32

[0..Canvas.BlockCountX-1]
X-coordinate of canvas block.

in : int32

[0..Canvas.BlockCountY-1]
Y-coordinate of canvas block.

returns → Vec2I

The pixel coordinates of the top-left block sample.

Returns the pixel coordinates of the given block.

Blocks​Preload


public method BlocksPreload → ()

Starts to load all canvas blocks in the current bounds.

Clear​Cache


public method ClearCache → ()

Clears the memory cache of this canvas.

Face​Transform


public method FaceTransform → (1)

face in : CubemapFace

The cubemap face.

returns → Transform

The face transform.

Returns the transformation from cubemap face coordinates to canvas coordinates.

Translate​Canvas​To​Map

5 overloads


public method TranslateCanvasToMap1 → (3)

canvas in : Vec2I

The input canvas coordinates.

face in : CubemapFace

The cubemap face of canvas in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsI

The output map coordinates.

returns → bool

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 TranslateCanvasToMap2 → (3)

canvas in : Vec2L

The input canvas coordinates.

face in : CubemapFace

The cubemap face of canvas in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsI

The output map coordinates.

returns → bool

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 TranslateCanvasToMap3 → (4)

canvasX in : int64

The input canvas X-coordinate.

canvasY in : int64

The input canvas Y-coordinate.

face in : CubemapFace

The cubemap face of canvasX in and canvasY in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsI

The output map coordinates.

returns → bool

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 TranslateCanvasToMap4 → (3)

canvas in : Vec2D

The input canvas coordinates.

face in : CubemapFace

The cubemap face of canvas in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsD

The output map coordinates.

returns → bool

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 TranslateCanvasToMap5 → (4)

canvasX in : float64

The input canvas X-coordinate.

canvasY in : float64

The input canvas Y-coordinate.

face in : CubemapFace

The cubemap face of canvasX in and canvasY in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsD

The output map coordinates.

returns → bool

true on success, false if the input coordinates cannot be mapped onto the map.

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

Translate​Canvas​To​Pixel

4 overloads


public method TranslateCanvasToPixel1 → (1)

canvas in : Vec2I

The input canvas coordinates.

returns → Vec2D

The output pixel coordinates.

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


public method TranslateCanvasToPixel2 → (1)

canvas in : Vec2L

The input canvas coordinates.

returns → Vec2D

The output pixel coordinates.

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


public method TranslateCanvasToPixel3 → (1)

canvas in : Vec2D

The input canvas coordinates.

returns → Vec2D

The output pixel coordinates.

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


public method TranslateCanvasToPixel4 → (2)

in : float64

The input canvas X-coordinate.

in : float64

The input canvas Y-coordinate.

returns → Vec2D

The output pixel coordinates.

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

Translate​Map​To​Canvas

4 overloads


public method TranslateMapToCanvas1 → (1)

map in : CubemapFaceCoordsI

The input map coordinates.

returns → Vec2L

The output canvas coordinates.

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


public method TranslateMapToCanvas2 → (3)

faceX in : int32

The input cubemap face X-coordinate.

faceY in : int32

The input cubemap face Y-coordinate.

face opt : CubemapFace = CubemapFace.NegZ

The input cubemap face.

returns → Vec2L

The output canvas coordinates.

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


public method TranslateMapToCanvas3 → (1)

map in : CubemapFaceCoordsD

The input map coordinates.

returns → Vec2D

The output canvas coordinates.

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


public method TranslateMapToCanvas4 → (3)

faceX in : float64

The input cubemap face X-coordinate.

faceY in : float64

The input cubemap face Y-coordinate.

face opt : CubemapFace = CubemapFace.NegZ

The input cubemap face.

returns → Vec2D

The output canvas coordinates.

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

Translate​Map​To​Pixel

4 overloads


public method TranslateMapToPixel1 → (1)

map in : CubemapFaceCoordsI

The input map coordinates.

returns → Vec2D

The output pixel coordinates.

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


public method TranslateMapToPixel2 → (3)

in : int32

The input cubemap face X-coordinate.

in : int32

The input cubemap face Y-coordinate.

face opt : CubemapFace = CubemapFace.NegZ

The input cubemap face.

returns → Vec2D

The output pixel coordinates.

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


public method TranslateMapToPixel3 → (1)

map in : CubemapFaceCoordsD

The input map coordinates.

returns → Vec2D

The output pixel coordinates.

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


public method TranslateMapToPixel4 → (3)

in : float64

The input cubemap face X-coordinate.

in : float64

The input cubemap face Y-coordinate.

face opt : CubemapFace = CubemapFace.NegZ

The input cubemap face.

returns → Vec2D

The output pixel coordinates.

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

Translate​Pixel​To​Canvas

4 overloads


public method TranslatePixelToCanvas1 → (1)

xy in : Vec2I

The input pixel coordinates.

returns → Vec2L

The output canvas coordinates.

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


public method TranslatePixelToCanvas2 → (2)

in : int32

The input pixel X-coordinate.

in : int32

The input pixel Y-coordinate.

returns → Vec2L

The output canvas coordinates.

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


public method TranslatePixelToCanvas3 → (1)

xy in : Vec2D

The input pixel coordinates.

returns → Vec2D

The output canvas coordinates.

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


public method TranslatePixelToCanvas4 → (2)

in : float64

The input pixel X-coordinate.

in : float64

The input pixel Y-coordinate.

returns → Vec2D

The output canvas coordinates.

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

Translate​Pixel​To​Map

4 overloads


public method TranslatePixelToMap1 → (3)

xy in : Vec2I

The input pixel coordinates.

face in : CubemapFace

The cubemap face of xy in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsI

The output map coordinates.

returns → bool

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 TranslatePixelToMap2 → (4)

in : int32

The input pixel X-coordinate.

in : int32

The input pixel Y-coordinate.

face in : CubemapFace

The cubemap face of in and in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsI

The output map coordinates.

returns → bool

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 TranslatePixelToMap3 → (3)

xy in : Vec2D

The input pixel coordinates.

face in : CubemapFace

The cubemap face of xy in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsD

The output map coordinates.

returns → bool

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 TranslatePixelToMap4 → (4)

in : float64

The input pixel X-coordinate.

in : float64

The input pixel Y-coordinate.

face in : CubemapFace

The cubemap face of in and in. Set to CubemapFace.None if unknown.

coords out : CubemapFaceCoordsD

The output map coordinates.

returns → bool

true on success, false if the input coordinates cannot be mapped onto the map.

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

Update


public virtual method Update → ()

returns → CanvasUpdateFlags

The update flags.

Updates the canvas content.

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

Public / Attributes

Block​Count​X


public attribute BlockCountX → (get)

value : int32

[>=0]
The horizontal block count.

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

Block​Count​Y


public attribute BlockCountY → (get)

value : int32

[>=0]
The vertical block count.

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

Block​Coverage


public attribute BlockCoverage → (get)

value : PixelCoverage

The coverage semantic.

Pixel coverage semantic of canvas blocks.

Block​Size​No​Overlap


public attribute BlockSizeNoOverlap → (get)

value : int32

[pow2]
The block size (edge length, not sample count).

Size of a canvas block, without overlap.

Busy


public attribute Busy → (get)

value : int32

The busy state:
0 : the canvas is idle.
1 : the canvas is computing map regions.
2 : the canvas is loading map tiles.

Returns the busy state of this canvas.

Cache​Size


public attribute CacheSize → (get)

value : int32

[>0]
The cache size.

The cache size, in blocks.

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

Canvas​Size


public attribute CanvasSize → (get)

value : Vec2L

The canvas size, in map samples.

The size of the virtual canvas.

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 IHeightmap.Size of the current Heightmap.

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

Center


public attribute Center → (get,set)

value : CubemapFaceCoordsI

The center coordinates.

Heightmap coordinates of the center of the current canvas bounds.

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

Grid​Lines


public attribute GridLines → (get)

value : IVectorConst<GridLine>

[not-null]
The list of map gridlines.

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

Is​Scrolling


public attribute IsScrolling → (get)

value : bool

true if scrolling is required, false if the entire virtual canvas fits into the pixel window.

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

Pixel​Size


public attribute PixelSize → (get,set)

value : Vec2I

The size, in pixels.

The pixel size of the current canvas bounds.

Regions


public attribute Regions → (get)

value : IMapRegion

[not-null]
The map regions with data.

The map regions in the current view that contain data.

Regions​Inverse


public attribute RegionsInverse → (get)

value : IMapRegion

[not-null]
The map regions with no data.

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

Step


public attribute Step → (get,set)

value : int32

The step distance.

The current sample step distance.

Step​Maximum


public attribute StepMaximum → (get)

value : int32

[pow2]
The maximum step distance.

The maximum sample step distance.

See also

Canvas.Step

Transform


public attribute Transform → (get,set)

value : Transform

The 2D transform.

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

Protected / Constructors

Canvas


protected constructor Canvas → (3)

blockSize in : int32

[>0]
The canvas block size.

map in : MapInfo

The source map.

content in : ICanvasContent own

[not-null]
The object that actually stores the contents of the generated canvas blocks.

Creates a new instance of Canvas.

Protected / Methods

Block​Dirty


protected method BlockDirty → (1)

index in : int32

The block index.

Marks the given canvas block as dirty.

Do​Block​Load


[ThreadSafe]
protected abstract method DoBlockLoad → (3)

bounds in : CubemapFaceRect

The block bounds.

step in : int32

The sample step.

transform in : Transform

The 2D transform to apply to the source data.

returns → ColorBuffer

The loaded canvas block.

Loads a canvas block.

IOException

If an I/O error has occurred.

Do​Regions​Collect


[ThreadSafe]
protected abstract method DoRegionsCollect → (3)

regions in : ICollector<CubemapFaceRect>

Output for collected data regions.

bounds in : CubemapFaceRect

The bounds for which to collect data regions.

blockSize in : int32

The block size, in samples.

Collects the data regions that intersect with the given bounds.

IOException

If an I/O error has occurred.

Regions​Dirty


protected method RegionsDirty → ()

Marks the computed dataset regions as dirty.

Protected / Attributes

content


[Owner]
protected attribute content → (ICanvasContent)

The delegate object that creates application-specific block content.

Logging

Logger


public static readonly attribute Logger → (ILogger)

The logger object of this class.