agi.foundation.terrain

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

Class RasterTerrainCache

java.lang.Object

agi.foundation.terrain.TerrainCache

agi.foundation.terrain.RasterTerrainCache

public class RasterTerrainCache
extends TerrainCache

A cache of raster terrain posts. A cache instance is associated with exactly one RasterTerrainProvider.

Constructor Summary

Constructors

Constructor and Description
RasterTerrainCache(RasterTerrainProvider provider) Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
RasterTerrainIndexExtent	getCacheRegionContainingPoint(double longitude, double latitude) Gets the extents of the cache region that contains a specified longitude and latitude.
int	getCacheTileSize() Gets the size, in posts, of a terrain region in the cache.
TerrainRegion	getLeastRecentlyUsedRegion() Gets the region in this cache that was least recently used.
TerrainPosts	getPosts(double longitude, double latitude) Gets the collection of posts containing a specified longitude and latitude.
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	setCacheTileSize(int value) Sets the size, in posts, of a terrain region in the cache.
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

RasterTerrainCache

public RasterTerrainCache(@Nonnull
                          RasterTerrainProvider 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.

getCacheTileSize

public final int getCacheTileSize()

Gets the size, in posts, of a terrain region in the cache. Some RasterTerrainProviders set this to their natural tile size during construction in order to improve read performance. It cannot be set after the cache is used for the first time. Because adjacent cache blocks share rows or columns of posts, the actual number of posts requested from the terrain provider will be one post greater than this number in each direction. For example, if the tile size is 1200, a westernmost cache block will cover posts 0 through 1200 (inclusive, for a total of 1201 posts) in the longitude direction. The next cache block to the east will cover posts 1200 through 2400 (1201 posts again).

setCacheTileSize

public final void setCacheTileSize(int value)

Sets the size, in posts, of a terrain region in the cache. Some RasterTerrainProviders set this to their natural tile size during construction in order to improve read performance. It cannot be set after the cache is used for the first time. Because adjacent cache blocks share rows or columns of posts, the actual number of posts requested from the terrain provider will be one post greater than this number in each direction. For example, if the tile size is 1200, a westernmost cache block will cover posts 0 through 1200 (inclusive, for a total of 1201 posts) in the longitude direction. The next cache block to the east will cover posts 1200 through 2400 (1201 posts again).

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.

getPosts

public final TerrainPosts getPosts(double longitude,
                                   double latitude)

Gets the collection of posts containing a specified longitude and latitude. If a region satisfying the request is in the cache, it will be returned. Otherwise, a minimal region will be loaded to satisfy the request, and a load of a larger region will be queued to the TerrainCacheGroup thread.

Parameters:

longitude - The required longitude.

latitude - The required latitude.

Returns:

A collection of posts from which the height at the specified longitude and latitude can be interpolated.

getCacheRegionContainingPoint

@Nonnull
public final RasterTerrainIndexExtent getCacheRegionContainingPoint(double longitude,
                                                                              double latitude)

Gets the extents of the cache region that contains a specified longitude and latitude.

Parameters:

longitude - The longitude of interest.

latitude - The latitude of interest.

Returns:

The extent.

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 RasterTerrainCache.unloadExtent(agi.foundation.coordinates.CartographicExtent). This method is safe to call from any thread.

Parameters:

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

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.