SceneOptions

Description

sealed class Tinman.Engine.Scenes.SceneOptions

Derived from

Disposable abstract
IValidatable
IHeightmapProvider

Configuration options for creating a Scene.

To specify a valid set of scene options, please work through the following steps:

  1. If the scene streams raster datasets (see IHeightmap) from online sources, a local dataset cache may be used, to speed up loading of commonly used data. To enable the cache, set the DatasetCachePath property. To further customize the cache, use the DatasetCacheMaximumSize and DatasetCacheFilter properties. To utilize the configured cache, use either IHeightmapProvider.OpenHeightmapDataset or IDataset.UseCache with DatasetCache.

  2. Elevation data must be specified via the TerrainHeightmap property. If the given heightmap is not geo-referenced, the terrain geometry must be specified via TerrainGeometry. To use gravity-related heights, the TerrainGeoid and TerrainElevationMode properties must be set accordingly.

  3. In most cases, the terrain will have one or more texture layers. Texture data on the GPU is managed by TextureAtlas objects, which must be declared up-front with TextureAtlas. Later, the IScene.AtlasId method may be used to map an atlas identifier to the texture atlas index, see TerrainBufferResource.TextureAtlasAt.The second step is usually performed under the hood by the built-in ISceneEntity implementations (for example TextureLayer).

  4. If the scene streams pyramid datasets (see IPixelPyramid) from online sources, a local imagery cache may be used. To enable the cache, set the ImageryCachePath property. To further customize the cache, use the ImageryCacheOptions property.

  5. To speed up loading of terrain textures during rendering, a local texture cache may be used. To enable the cache, set the TextureCachePath. To further customize the cache, use the TextureCacheOptions property.

  6. To utilize the configured imagery and texture caches, a set of cache identifiers must be declared up-front by calling the CacheId method. Later, the IScene.CacheId method may be used to map a cache identifier to the persistent ordinal number that is used by the underlying PyramidFileCache object. The second step is usually performed under the hood by the built-in ISceneEntity implementations (for example TextureLayer). Cached imagery and texture data remains valid as long as the distinct ordered set of cache identifiers remains unchanged.

  7. Additional low-level behaviour of the underlying terrain mesh may be specified via TerrainFlags, TerrainModifier and VertexCapacity.

  8. Finally, call CreateScene to create the IScene object.

Public / Constructors

Scene​Options

public constructor SceneOptions → ()

Creates a new instance of SceneOptions.

Public / Methods

Cache​Id

public method CacheId → (1)

cacheId in : string

[not-empty]
The cache ID to declare.

returns → SceneOptions

this

Declares a cache ID.

When creating scene entities for terrain layers later, a declared cache ID must be given.

Create​Scene

[OwnerReturn] [OwnerThis]
public method CreateScene → ()

returns → Scene

The created scene.

Creates a Scene from the current options.

The following validations are performed on the scene options:

The following geo-referencing information must be available:

IOException

If an I/O error has occurred.

ValidatingException

If the scene options are invalid.

GeorefException

If the provided geo-referencing information is invalid or incomplete (see remarks).

Texture​Atlas

public method TextureAtlas → (4)

atlas in : string

[not-empty]
The texture atlas identifier.

format in : TextureFormat

[not-null]
The texture format.

tileSize in : int32

[pow2]
The tile size.

tileCount in : int32

[>=0]
The minimum tile count.

returns → SceneOptions

this

Specifies a texture atlas configuration.

Use​Dataset​Cache​Always

[Pure]
public static method UseDatasetCacheAlways → (1)

file in : IFile

The file.

returns → bool

The result value.

A PredicateDelegate that always returns true.

Use​Dataset​Cache​If​Not​Local

[Pure]
public static method UseDatasetCacheIfNotLocal → (1)

file in : IFile

The file.

returns → bool

The result value.

A PredicateDelegate that returns true for non-local files (see IFile.IsLocal).

Use​Dataset​Cache​Never

[Pure]
public static method UseDatasetCacheNever → (1)

file in : IFile

The file.

returns → bool

The result value.

A PredicateDelegate that always returns false.

Public / Attributes

Dataset​Cache

public attribute DatasetCache → (get)

value : DatasetFileCache

The dataset file cache, according to the properties configured in this object. Will be null iff the dataset file cache is disabled.

Returns the dataset file cache, creating it if necessary.

IOException

If an I/O error has occurred.

See also

SceneOptions.DatasetCacheFilter
SceneOptions.DatasetCacheMaximumSize
SceneOptions.DatasetCachePath

Dataset​Cache​Filter

public attribute DatasetCacheFilter → (get,set)

value : PredicateDelegate<IFile>

The filter delegate. If null, the dataset file cache will never be used

The filter to use for deciding whether to cache a dataset or not.

Defaults to UseDatasetCacheIfNotLocal.

See also

SceneOptions.DatasetCache

Dataset​Cache​Maximum​Size

public attribute DatasetCacheMaximumSize → (get,set)

value : int64

[>=0]
Maximum dataset file cache size, in megabytes. If 0 the dataset file cache size will be unlimited.

Maximum size of the dataset file cache.

The default value is 1024 megabytes.

See also

SceneOptions.DatasetCache

Dataset​Cache​Path

public attribute DatasetCachePath → (get,set)

value : Path

Path to the cache file or null to disable the cache.

Path to the dataset cache file.

Defaults to null.

See also

SceneOptions.DatasetCache

Imagery​Cache

public attribute ImageryCache → (get)

value : PyramidFileCache

The imagery tile cache, according to the properties configured in this object. Will be null iff the dataset file cache is disabled.

Returns the imagery tile cache, creating it if necessary.

IOException

If an I/O error has occurred.

See also

SceneOptions.ImageryCachePath
SceneOptions.ImageryCacheOptions

Imagery​Cache​Options

public attribute ImageryCacheOptions → (get,set)

value : PyramidFileCacheOptions

The imagery tile cache options. Set to null to open the imagery tile cache in locked read-only mode (see PyramidFileCache.IsReadOnly and PyramidFileCache.Locked).

Options to use for creating the imagery tile cache.

Defaults to an instance of PyramidFileCacheOptions with default values.

See also

SceneOptions.TextureCachePath

Imagery​Cache​Path

public attribute ImageryCachePath → (get,set)

value : Path

The imagery tile cache file path or null to disable the cache.

Path to the imagery tile cache file.

Defaults to null.

See also

ITexelPyramid.Cache

Terrain​Elevation​Mode

public attribute TerrainElevationMode → (get,set)

value : bool

true : Elevation values are relative to the TerrainGeoid.
false : Elevation values are relative to the ellipsoid surface.

Depicts how to interpret the elevation values in TerrainHeightmap.

Defaults to false.

See also

SceneOptions.TerrainHeightmap

Terrain​Flags

public attribute TerrainFlags → (get,set)

value : TerrainBufferFlags

The terrain buffer flags.

The terrain buffer flags to use.

Defaults to TerrainBufferFlags.Default.

Terrain​Geoid

[OwnerValue]
public attribute TerrainGeoid → (get,set)

value : IHeightmap

The gravity model or null for none.

The gravity model of the terrain.

Using a gravity model allows to distinguish between vertical coordinates of types VerticalType.Ellipsoid and VerticalType.Gravity.

Defaults to null.

See also

VerticalType.Gravity

Terrain​Geometry

public attribute TerrainGeometry → (get,set)

value : IGeometry

The geometry or null to use the default geometry of TerrainHeightmap.

The geometry to use for the terrain.

If null, a IGeometry object is created with Geometry.ForGeoref, passing TerrainHeightmap as argument.

Defaults to null.

Terrain​Heightmap

[OwnerValue]
public attribute TerrainHeightmap → (get,set)

value : IHeightmap

The terrain heightmap.

The terrain heightmap to use.

Defaults to null.

See also

SceneOptions.TerrainElevationMode

Terrain​Modifier

public attribute TerrainModifier → (get,set)

value : IMeshModifier

The terrain modifier or null.

The terrain modifier to use.

Defaults to null.

Texture​Cache​Options

public attribute TextureCacheOptions → (get,set)

value : PyramidFileCacheOptions

[not-null]
The texture tile cache options.

Options to use for creating the texture tile cache.

Defaults to an instance of PyramidFileCacheOptions with default values.

See also

SceneOptions.TextureCachePath

Texture​Cache​Path

public attribute TextureCachePath → (get,set)

value : Path

The texture tile cache file path or null to disable the cache.

Path to the texture cache file.

Defaults to null.

See also

ITexelPyramid.Cache

Vertex​Capacity

public attribute VertexCapacity → (get,set)

value : int32

[>0]
The vertex capacity.

The capacity of the vertex pool to use for CLOD terrain meshes.

Defaults to 2097152.