TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

interface IPyramidBase in Tinman.Terrain.Pyramids

Non-generic base interface for classes that represent a pyramid of tile data.

interface IPyramidBase extends IMapEntity
  base of IPyramid

Remarks

A tile pyramid is organized as a cubemap, where each cubemap face defines as quad-tree. The quad-tree nodes each hold a single data tile. The data type of tiles is defined by the TData parameter of the IPyramid interface. 

The topmost level (level index 0) contains only a single data tile:
+---------------+
|               |
|               |       +---> tileX
|               |       |
|               |       |
|               |       V
|               |       tileY
|               |
+---------------+

According to quad-tree semantics, each data tile is split into four children:
+-------+-------+
|       |       |
|       |       |       +---> tileX
|       |       |       |
+-------+-------+       |
|       |       |       V
|       |       |       tileY
|       |       |
+-------+-------+

This is done until the bottommost level (level count, minus one) is reached:
+---+---+---+---+
|   |   |   |   |
+---+---+---+---+       +---> tileX
|   |   |   |   |       |
+---+---+---+---+       |
|   |   |   |   |       V
+---+---+---+---+       tileY
|   |   |   |   |
+---+---+---+---+
Tile pyramids can be sparse, i.e. some tiles can be void (see Void). The pyramid flags (see Flags, Opaque) define how void tiles shall be handled during rendering. 
+-------+-------+    +---+---+---+---+
|       |       |    |   |   |   | X |
|       |       |    +---+---+---+---+
|       |       |    |   |   |   |   |
+-------+-------+    +---+---+---+---+    X := void tiles
|       |       |    | X | X |   |   |
|   X   |       |    +---+---+---+---+
|       |       |    | X | X |   |   |
+-------+-------+    +---+---+---+---+
Tile pyramids come in two flavours: The georeference raster of a pyramid (Georef and Map) always spans the maximum pyramid level (see MaxSize), independent of the actual pyramid size (see FullSize), assuming a tile pad of zero (see TilePad): 
(0|0) : raster coordinates of top-left corner of top-left tile, on any level.
(m|m) : raster coordinates of bottom-right corner of bottom-right tile, on any level.
where m is MaxSize. This means that the georeference raster has PixelIsPoint semantics.

Attributes

CanUpdate

Does this map allow updates to its content (i.e. sample data and/or metadata)?

property CanUpdate { get }
type bool
value true if the map content can be updated, false if not.
inherited IMapEntity.CanUpdate

Flags

Additional behaviour flags of the pyramid.

property Flags { get }
type PyramidFlags
value The pyramid flags.

FullSize

The size of the bottom-most pyramid level.

property FullSize { get }
type int32
value [pow2] The pyramid size (width and height), in samples.

Georef

Returns georeferencing information.

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

Levels

The number of pyramid levels.

property Levels { get }
type int32
value [>=1] The number of pyramid levels.

LifecycleState

Returns the lifecycle state of this object.

property LifecycleState { get }
type LifecycleState
value The lifecycle state.
inherited ILifecycleState.LifecycleState

Map

Returns a MapInfo value that describes the used map raster.

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

OnUpdated

Event for listening to updates made to this pixel pyramid.

property OnUpdated { get }
type IEventGeneric<PyramidEventArgs>
value [not-null] The event object.

Remarks:

This event will be fired by the thread that performs the map update.

TilePad

The pad width of this cube pyramid.

property TilePad { get }
type int32
value [>=0] The pad width.

Remarks:

Tile padding is used to avoid color bleeding that will occur when texture samples are filtered at the edge of a pyramid tile (assuming tiles are stored in some kind of texture atlas). The tile pad width gives the number of safety pixels at the that are borrowed from neighbouring pyramid tiles: 

      8x8 tile, with a pad of 2:

    0   1   2   3   4   5   6   7
  +---+---+---+---+---+---+---+---+
0 |###|###|###|###|###|###|###|###|
  +---+---+---+---+---+---+---+---+
1 |###|###|###|###|###|###|###|###|
  +---+--(X)--+---+---+--(X)--+---+
2 |###|###|   |   |   |   |###|###|
  +---+---+---+---+---+---+---+---+
3 |###|###|   |   |   |   |###|###|
  +---+---+---+---+---+---+---+---+
4 |###|###|   |   |   |   |###|###|
  +---+---+---+---+---+---+---+---+
5 |###|###|   |   |   |   |###|###|
  +---+--(X)--+---+---+--(X)--+---+
6 |###|###|###|###|###|###|###|###|
  +---+---+---+---+---+---+---+---+
7 |###|###|###|###|###|###|###|###|
  +---+---+---+---+---+---+---+---+
The point coordinates marked with (X) will be mapped to the corner vertices of each terrain mesh sector. Only the effective region of a padded tile (i.e. the square surrounded by (X)) contains actual data. The padded pixels are sampled from neighbouring source tiles and carry redundant information.

TileSize

The size of a single map tile, in pixels.

property TileSize { get }
type int32
value [pow2] The tile size.

Methods

AcquireTry

Acquires a strong reference to this disposable object.

[OwnerReturn, ThreadSafe]
method AcquireTry ()
type IDisposable
returns this if a new strong reference has been acquired, null if this object is already being disposed.
inherited IDisposable.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.

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]
method Dispose ()
inherited IDisposable.Dispose

Remarks:

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

Flush

Flushes all cached data.

method Flush ()
inherited IFlushable.Flush

Remarks:

Performing a flush may result in I/O work. Depending on the semantics of the implementing class, this work may need to be wrapped in special Begin / End method calls. See the documentation of the implementing classes for details.

In case this object represents a read-only resource, calling the Flush method has no effect.

HasTileData

Returns if there is any data content for the given map tile.

[ThreadSafe]
method HasTileData (PyramidCoords coords)
type bool
params coords The pyramid tile coords.
returns true if data for the given map tile exists, false if not.

Returns if there is any data content for the given map tile (i.e. Ok or Empty).

[ThreadSafe]
method HasTileData (CubemapFace face, int32 level, int32 x, int32 y)
type bool
params face Cubemap face of map tile. Set to NegZ for unprojected map pyramids. Defaults to NegZ.
  level [>=0] The pyramid level.
  x Cubemap face X-coordinate of map tile in level.
  y Cubemap face Y-coordinate of map tile in level.
returns true if data for the given map tile exists, false if not.

ToConfig

Returns the configuration value that describes this object.

method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
inherited IConfigurable.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

UpdateGeoref

Updates georeferencing data of this heightmap.

[ThreadSafe]
method UpdateGeoref (Raster georef)
params georef The new georeferencing data or null.
inherited IMapEntity.UpdateGeoref

See also:

IMapEntity.CanUpdate

Extensions

LevelGeoref

Returns a georeference raster that spans the given pyramid level.

method LevelGeoref (int32 level = -1)
type Raster
params level The pyramid level. If negative, the pyramid level count (see Levels) will be added. Defaults to -1.
returns The georeference raster for level or null if Georef is null.

LevelMap

Returns the map info for the given pyramid level.

method LevelMap (int32 level = -1)
type MapInfo
params level The pyramid level. If negative, the pyramid level count (see Levels) will be added. Defaults to -1.
returns The map info for level.

LevelSize

Returns the size of the given pyramid level.

method LevelSize (int32 level)
type int32
params level [>=0] The pyramid level.
returns [>=0] The full size of the pyramid level.

ValidCoords

Checks if the given pyramid coordinates are valid for this IPyramid object.

method ValidCoords (PyramidCoords coords)
type bool
params coords The pyramid coordinates..
returns true if the pyramid coordinates are valid, false if not.

Checks if the given pyramid coordinates are valid for this IPyramidBase object.

method ValidCoords (CubemapFace face, int32 level, int32 x, int32 y)
type bool
params face The cubemap face.
  level The pyramid level.
  x X-coordinate of pyramid tile.
  y Y-coordinate of pyramid tile.
returns true if the pyramid coordinates are valid, false if not.
Tinman 3D SDK v1.0 | info@tinman3d.com | Copyright © 2012 - 2017 Matthias Englert, Fulda (Germany)