PyramidFileCache

Description

sealed class Tinman.Terrain.Pyramids.PyramidFileCache

An file-based cache for IPixelPyramids and ITexelPyramids.

Instances of PyramidFileCache are automatically shared between threads of the same process. This is transparent to the using code. Pyramid file caches can also be shared between multiple processes resp. machines, with the restriction that all shared pyramid file caches must be opened read-only mode (see Open), which implies that the shared pyramid file cache must have been warmed up in a pre-processing step.

The following table shows the binary layout of a pyramid cache (multibyte values are encoded as ByteOrder.LittleEndian).

Offset     | Type  | Count | Description
-----------+-------+-------+----------------------------------------------------
#0  ..  #7 |  int8 |     8 | Magic value that identifies a file used by a
           |       |       | pyramid cache:
           |       |       | 0x89 0x50 0x59 0x43 0x0D 0x0A 0x1A 0x0A
-----------+-------+-------+----------------------------------------------------
#8  ..  #9 | int16 |     1 | Binary format version (currently 1).
-----------+-------+-------+----------------------------------------------------
#10 .. #17 | int64 |     1 | Maximum file size, in bytes.
-----------+-------+-------+----------------------------------------------------
#18 .. #21 | int32 |     1 | Maximum tile age, in seconds.
-----------+-------+-------+----------------------------------------------------
#22 .. #39 |  int8 |    18 | Reserved (must be all zero).
-----------+-------+-------+----------------------------------------------------
#40 .. #47 | int64 |     1 | Block ID of root of primary tile index.
-----------+-------+-------+----------------------------------------------------
#48 .. #55 |  int8 |     8 | Reserved, must be zero.
-----------+-------+-------+----------------------------------------------------
#56 .. #63 | int64 |     1 | Block ID of root of timestamp index "LastUsed".
-----------+-------+-------+----------------------------------------------------
#64 .. EOF |  int8 |     ? | Data area of pyramid cache.
-----------+-------+-------+----------------------------------------------------

The data area of a pyramid cache dataset is managed by an embedded BlockStorage.

Public / Constructors

Create


[OwnerReturn]
public static method Create → (2)

filePath in : Path

[not-null]
Path to the cache file.

options opt : PyramidFileCacheOptions = null

The options to use. If null, the default options will be used.

returns → PyramidFileCache

The pyramid file cache.

Creates a new pyramid file cache.

IOException

If an I/O error has occurred.

Create​Or​Open


[OwnerReturn]
public static method CreateOrOpen → (2)

filePath in : Path

[not-null]
Path to the cache file.

options opt : PyramidFileCacheOptions = null

The options to use. If null, the default options will be used.

returns → PyramidFileCache

The pyramid file cache.

Opens an existing pyramid file cache or creates a new one if necessary.

If the given file path points to a non-existent file, a new pyramid file cache with the given properties will be created. If the file path refers to an existing pyramid file cache, it will be opened iff its options match options opt; otherwise a new pyramid file cache is created and the existing one is overwritten.

IOException

If an I/O error has occurred.

Open


[OwnerReturn]
public static method Open → (2)

filePath in : Path

[not-null]
Path to the cache file.

readOnly opt : bool = false

Open pyramid file cache in read-only mode? Use this for sharing warmed-up file caches between multiple processes or machines.

returns → PyramidFileCache

The pyramid file cache.

Opens an existing pyramid file cache.

IOException

If an I/O error has occurred.

Public / Methods

Clear


[ThreadSafe]
public method Clear → ()

Clears all cached pyramid tile data from the cache.

IOException

If an I/O error has occurred.

Public / Attributes

Is​Read​Only


public attribute IsReadOnly → (get)

value : bool

true if the pyramid file cache is in read-only mode,
false if the pyramid file cache is in read-write mode.

Is the pyramid file cache in read-only mode?

In read-only mode, the cache file will not be updated (e.g. add new tiles, updated timestamps, remove expired tiles). In effect, pyramid files that are not present in the cache will be loaded from the underlying pyramid, and the resulting pyramid tile will not be stored in the cache file.

Locked


public attribute Locked → (get,set)

value : bool

true if the pyramid file cache is in locked mode,
false if the pyramid file cache is in unlocked mode.

Is the pyramid file cache currently in locked mode?

In locked mode, only those pyramid files that are already present in the cache file will be returned. In effect, the underlying pyramids will never be accessed.

When property setter has returned, all pending pyramid accesses will have finished and all future pyramid accesses will honour the new flag value. After setting this property to true, the IFlushable.Flush method may be called, in order to put the cache file into a consistent state that will remain unchanged until this property is set to false again.

Defaults to false.

Configuration

Config


public static attribute Config → (get)

value : IConfigurator<PyramidFileCache>

[not-null]
The configurator object.

The configurator object for this type.

Logging

Logger


public static readonly attribute Logger → (ILogger)

The logger object of this class.