agi.foundation.terrain

(agi.foundation.terrainreaders-2025r1.jar)

Class QuantizedMeshTerrainCache

java.lang.Object

agi.foundation.terrain.TerrainCache

agi.foundation.terrain.QuantizedMeshTerrainCache

public class QuantizedMeshTerrainCache
extends TerrainCache

A cache of quantized-mesh terrain tiles. A cache instance is associated with exactly one QuantizedMeshTerrainProvider.

Constructor Summary

Constructors

Constructor and Description
QuantizedMeshTerrainCache(QuantizedMeshTerrainProvider provider) Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
TerrainRegion	getLeastRecentlyUsedRegion() Gets the region in this cache that was least recently used.
QuantizedMeshTerrainTile	getMesh(int level, int x, int y) Gets the terrain tile with specified tile coordinates.
long	getSize() Gets the approximate total memory, in bytes, used by all regions in the cache.
void	loadRegion(TerrainRegion region) Deprecated. Internal use only.
void	preloadExtent(CartographicExtent extent) Loads the terrain data in a given extent into the terrain cache.
void	removeRegion(TerrainRegion region) Deprecated. Internal use only.
void	unloadExtent(CartographicExtent extent) Unloads the cached terrain data for a given extent.

Methods inherited from class agi.foundation.terrain.TerrainCache

getGroup

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

QuantizedMeshTerrainCache

public QuantizedMeshTerrainCache(@Nonnull
                                 QuantizedMeshTerrainProvider provider)

Initializes a new instance.

Parameters:

provider - The terrain provider associated with this cache.

Throws:

ArgumentNullException - Thrown when provider is null.

Method Detail

removeRegion

public void removeRegion(TerrainRegion region)

Deprecated. Internal use only.

Removes the specified region from the cache.

Specified by:

removeRegion in class TerrainCache

Parameters:

region - The region to remove.

Throws:

ArgumentNullException - Thrown when region is null.

loadRegion

public void loadRegion(TerrainRegion region)

Deprecated. Internal use only.

Loads the specified region into the cache.

Specified by:

loadRegion in class TerrainCache

Parameters:

region - The region to load.

Throws:

ArgumentNullException - Thrown when region is null.

getSize

public long getSize()

Gets the approximate total memory, in bytes, used by all regions in the cache.

Specified by:

getSize in class TerrainCache

getLeastRecentlyUsedRegion

public TerrainRegion getLeastRecentlyUsedRegion()

Gets the region in this cache that was least recently used.

Specified by:

getLeastRecentlyUsedRegion in class TerrainCache

Returns:

The least recently used region.

getMesh

public final QuantizedMeshTerrainTile getMesh(int level,
                                              int x,
                                              int y)

Gets the terrain tile with specified tile coordinates. If a tile satisfying the request is in the cache, it will be returned. Otherwise, the tile will be loaded to satisfy the request, and then a request to add that tile to the cache will be queued to the TerrainCacheGroup thread.

Parameters:

level - The zoom level.

x - The X tile coordinate.

y - The Y tile coordinate.

Returns:

The requested terrain tile, either newly loaded or from the cache.

Throws:

ArgumentOutOfRangeException - Thrown if the tile coordinates are invalid.

preloadExtent

public final void preloadExtent(@Nonnull
                                CartographicExtent extent)

Loads the terrain data in a given extent into the terrain cache. This method does not return until the terrain data is fully loaded. All terrain data within the extent is loaded into memory even if doing so would exceed the TerrainCacheGroup's MaximumSize (get / set). Furthermore, the loaded terrain data is locked in memory (meaning it will not be unloaded) until the user calls QuantizedMeshTerrainCache.unloadExtent(agi.foundation.coordinates.CartographicExtent). This method is safe to call from any thread.

Parameters:

extent - The extent for which to load terrain data.

Throws:

ArgumentNullException - Thrown when extent is null.

unloadExtent

public final void unloadExtent(@Nonnull
                               CartographicExtent extent)

Unloads the cached terrain data for a given extent. This method unloads all cached regions where any part of the region falls within the extent. It does not return until the regions have been unloaded. However, if a region within the extent is being used in another thread while this method is executing, the region may be reloaded immediately after this method unloads it. This method is safe to call from any thread.

Parameters:

extent - The extent for which to unload terrain, in the native units of the terrain provider.

Throws:

ArgumentNullException - Thrown when extent is null.