com.massifmaps.components.TerrainOptions

public class TerrainOptions extends Object

3D terrain configuration, attached to the map via Options::setTerrainOptions.
The elevation data source can be shared with a HillshadeRasterTileLayer, in which case
both features use the same tiles (ideally the data source should be wrapped in a
MemoryCacheTileDataSource to avoid duplicate loads).
Note: this class is experimental and may change or even be removed in future SDK versions.

Constructor Summary

Constructors

Constructor

Description

TerrainOptions(TileDataSource dataSource)

Constructs a TerrainOptions object from an elevation data source.
The elevation decoder is resolved from the data source "encoding" setting
("mapbox" or "terrarium"), defaulting to the MapBox encoding.

TerrainOptions(TileDataSource dataSource, ElevationDecoder elevationDecoder)

Constructs a TerrainOptions object from an elevation data source and an explicit decoder.
Method Summary

Modifier and Type

Method

Description

float

getAutoFlattenDuration()

Returns how long the terrain takes to sink flat.

float

getAutoFlattenParallax()

Returns the screen parallax below which the terrain renders flat.

float

getAutoFlattenRiseDuration()

Returns how long the terrain takes to rise back into 3D.

float

getAutoFlattenTilt()

Returns the tilt at or above which the terrain renders flat.

Color

getBackgroundColor()

Returns the terrain background color.

float

getBillboardOcclusionTolerance()

Returns the billboard/label terrain occlusion tolerance.

float

getCameraClampDuration()

Returns the duration of the camera terrain-following correction animation.

float

getCameraClearance()

Returns the camera terrain clearance floor: an explicit minimum height the camera
is kept above the terrain surface, in meters.

TileDataSource

getDataSource()

Returns the elevation data source.

float

getDepthBias()

Returns the clip-space depth bias used when depth-testing draped 2D geometry against the terrain.

int

getDrapeCacheSize()

Returns the drape cache budget in megabytes.

int

getDrapeResolution()

Returns the per-tile drape texture resolution, 0 when it follows the screen.

int

getDrapeWorkingSet()

Returns how many drape tiles the automatic resolution assumes are cached at once.

double

getElevation(MapPos pos)

Returns the terrain elevation in meters at the given position.
The position is expected to be in WGS84 coordinates.
Note: this method may block on network/IO if the elevation tile is not cached.

ElevationDecoder

getElevationDecoder()

Returns the elevation decoder used as the source-level default.

DoubleVector

getElevations(MapPosVector poses)

Returns terrain elevations in meters at the given positions (WGS84).
One value is returned for every input position, in the input order.
Note: this method may block on network/IO if the elevation tiles are not cached.

float

getExaggeration()

Returns the terrain height exaggeration factor.

int

getFlattenMode()

Returns how far a flattened terrain goes back towards a plain 2D map.

float

getFlattenRatio()

Returns how far the terrain is flattened right now, 0 (full 3D) to 1 (flat).

int

getMaxTileZoomCoarsening()

Returns how many zoom levels below the camera a tile may coarsen to.

int

getMaxTileZoomOffset()

Returns the maximum visible tile zoom offset, relative to the camera zoom level.

int

getMeshResolution()

Returns the terrain mesh resolution.

int

getMinZoom()

Returns the minimum tile zoom level with 3D terrain.

String

getNoDrapeLayerFilter()

Returns the style layers that are kept out of the terrain drape bake.

Color

getSurfaceColorParameter(String name)

Returns the value of a terrain surface shader color parameter.

float

getSurfaceParameter(String name)

Returns the value of a terrain surface shader float parameter.

String

getSurfaceShaderSource()

Returns the custom terrain surface fragment shader source, or an empty string if
no shaded surface is drawn.

float

getTextOcclusionOpacity()

Returns the opacity a label keeps while its anchor is behind 3D content.

float

getViewDistance()

Returns the minimum view distance, in meters.

float

getViewDistanceFactor()

Returns the factor applied to the view distance.

boolean

isBackgroundBitmapEnabled()

Returns the terrain background bitmap state.

boolean

isBillboardOcclusionEnabled()

Returns the billboard/label terrain occlusion state.

boolean

isBridges3DEnabled()

Returns whether bridges and tunnels stand on their own chord (3D bridges).

boolean

isDrapeFillsEnabled()

Returns whether polygon fills are draped as a render-to-texture surface.

boolean

isDrapeLinesEnabled()

Returns whether vt tile lines are also draped (in addition to fills).

boolean

isElevationPrefetchEnabled()

Returns whether elevation tile prefetching is enabled.

boolean

isEnabled()

Returns the enabled state of the terrain.

boolean

isFlattened()

Returns whether the map is asked to render flat.

boolean

isSeamlessTileEdgesEnabled()

Returns whether seamless tile edge handling is enabled.

boolean

isSwitching()

Returns whether the switch is holding the ground flat while the tiles 3D needs load.

boolean

isTileEdgeStitchingEnabled()

Returns whether cross-LOD tile edge stitching is enabled.

void

setAutoFlattenDuration(float duration)

Sets how long the terrain takes to sink flat, and - unless setAutoFlattenRiseDuration
overrides it - to rise again.

void

setAutoFlattenParallax(float pixels)

Sets the terrain parallax, in SCREEN PIXELS, below which 3D stops being worth its cost and
the map renders flat.

void

setAutoFlattenRiseDuration(float duration)

Sets how long the terrain takes to RISE, separately from how long it takes to sink.

void

setAutoFlattenTilt(float tilt)

Sets the tilt, in degrees, at or above which the map renders flat whatever the parallax.
90 is straight down in this SDK, where the displacement is there but shows nothing worth
its cost.

void

setBackgroundBitmapEnabled(boolean enabled)

Sets the terrain background bitmap state.

void

setBackgroundColor(Color color)

Sets the terrain background color: an opaque base fill of the terrain surface
drawn under all layers.

void

setBillboardOcclusionEnabled(boolean enabled)

Sets the billboard/label terrain occlusion state.

void

setBillboardOcclusionTolerance(float tolerance)

Sets how far behind the terrain a billboard or label anchor may sit and still count
as visible, as a fraction of its distance from the camera.

void

setBridges3DEnabled(boolean enabled)

Enables or disables 3D bridges: a feature styled `line-elevation-mode: span` (or the
polygon/building variants) is laid straight between its two portals instead of draped
over the terrain, and a span deck stands as an extrusion carrying its road.

void

setCameraClampDuration(float duration)

Sets the duration of the camera terrain-following correction animation.

void

setCameraClearance(float clearance)

Sets the camera terrain clearance floor, in meters.

void

setDepthBias(float depthBias)

Sets the clip-space depth bias used when depth-testing draped 2D geometry against the terrain.
Larger values prevent draped layers from being clipped by the terrain surface itself,
at the cost of geometry slightly behind terrain ridges 'shining through' near silhouettes.

void

setDrapeCacheSize(int megabytes)

Sets how much video memory the cached drape textures may take, in megabytes.

void

setDrapeFillsEnabled(boolean enabled)

Enables or disables maplibre-style render-to-texture fill draping (experimental, spike).

void

setDrapeLinesEnabled(boolean enabled)

Enables or disables draping of vt tile lines in addition to fills (needs DrapeFillsEnabled).
Draped lines are baked into the per-tile texture: they follow the terrain exactly and cost
no per-frame geometry (a city pan runs at twice the frame rate), but they resolve at the
drape resolution rather than the screen's.

void

setDrapeResolution(int resolution)

Sets the per-tile drape texture resolution.

void

setDrapeWorkingSet(int tiles)

Sets how many drape tiles the automatic resolution (DrapeResolution 0) assumes have to
fit the budget at once: the live cover plus the generation a zoom or pan is about to need
back.

void

setElevationPrefetchEnabled(boolean enabled)

Enables or disables elevation tile prefetching.

void

setEnabled(boolean enabled)

Sets the enabled state of the terrain.

void

setExaggeration(float exaggeration)

Sets the terrain height exaggeration factor.

void

setFlattened(boolean flattened)

Switches the map between flat and 3D terrain, without detaching the elevation data the way
setEnabled does.

void

setFlattenMode(int mode)

Sets how far a flattened terrain goes back towards a plain 2D map.

void

setFlattenRatio(float ratio)

Drives the 2D/3D switch by hand, off the app's own clock: 0 is full 3D, 1 is flat.

void

setMaxTileZoomCoarsening(int levels)

Sets how far BELOW the camera's zoom the tile LOD may take a tile in terrain mode
(Options::TileLODFactor decides the rest).

void

setMaxTileZoomOffset(int offset)

Sets the maximum visible tile zoom offset, relative to the camera zoom level.
Terrain level-of-detail is distance based: tiles close to the camera (and mountain
faces rising towards it) are shown at higher tile zoom levels than flat rendering
would ever use at the same camera zoom.

void

setMeshResolution(int meshResolution)

Sets the terrain mesh resolution.

void

setMinZoom(int minZoom)

Sets the minimum tile zoom level with 3D terrain.

void

setNoDrapeLayerFilter(String filter)

Sets which style layers must NOT be baked into the drape texture, as a regular expression
over the vt layer name (which comes from the style's own rule names).

void

setSeamlessTileEdgesEnabled(boolean enabled)

Enables or disables seamless tile edge handling.

void

setSurfaceColorParameter(String name, Color color)

Sets a terrain surface shader color parameter, exposed to the shader as a vec4
uniform with components in the 0..1 range.

void

setSurfaceParameter(String name, float value)

Sets a terrain surface shader float parameter, exposed to the shader as a uniform.

void

setSurfaceShaderSource(String shaderSource)

Sets a fragment shader that paints the terrain surface itself.

void

setTextOcclusionOpacity(float opacity)

Sets the opacity a label keeps while the point it is anchored at is hidden by 3D
content - buildings, not the terrain, which occludes labels regardless (see
BillboardOcclusionTolerance).

void

setTileEdgeStitchingEnabled(boolean enabled)

Enables or disables cross-LOD tile edge stitching.

void

setViewDistance(float distance)

Sets a MINIMUM distance the map is drawn to, in METERS, whatever the camera's height or
pitch.

void

setViewDistanceFactor(float factor)

Sets how far from the camera the map is drawn and where the far plane sits, as a factor
on tangram's own rule (core/src/view/view.cpp):
far = 2 * cameraHeight / cos(pitch + fovy/2), capped by
maxTileDistance = worldTileSize(zoom) * (2^(MAX_LOD+1) - 1), with MAX_LOD 6.
A factor of 1 is that rule verbatim; smaller ends the view closer, larger extends it.
This is what makes a near-horizontal view affordable: taken from the visible ground
instead, the view reaches the horizon - hundreds of tiles, most of them a few pixels
tall, each carrying its own labels.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- TerrainOptions
  
  public TerrainOptions(TileDataSource dataSource)
  
  Constructs a TerrainOptions object from an elevation data source.
  The elevation decoder is resolved from the data source "encoding" setting
  ("mapbox" or "terrarium"), defaulting to the MapBox encoding.
  
  Parameters:
  
  dataSource - The data source with RGB-encoded elevation tiles.
- TerrainOptions
  
  public TerrainOptions(TileDataSource dataSource, ElevationDecoder elevationDecoder)
  
  Constructs a TerrainOptions object from an elevation data source and an explicit decoder.
  
  Parameters:
  
  dataSource - The data source with RGB-encoded elevation tiles.
  
  elevationDecoder - The decoder for the elevation tile encoding.
Method Details
- getDataSource
  
  public TileDataSource getDataSource()
  
  Returns the elevation data source.
  
  Returns:
  
  The elevation data source.
- getElevationDecoder
  
  public ElevationDecoder getElevationDecoder()
  
  Returns the elevation decoder used as the source-level default. Each tile resolves its
  own decoder from its "dem_encoding" meta data, so two data sources of different
  encodings can be combined behind one OrderedTileDataSource.
  
  Returns:
  
  The default elevation decoder.
- isEnabled
  
  public boolean isEnabled()
  
  Returns the enabled state of the terrain.
  
  Returns:
  
  True if 3D terrain rendering is enabled. The default is true.
- setEnabled
  
  public void setEnabled(boolean enabled)
  
  Sets the enabled state of the terrain. If disabled, the map renders flat,
  but the elevation data source stays attached.
  
  Parameters:
  
  enabled - The new enabled state.
- isFlattened
  
  public boolean isFlattened()
  
  Returns whether the map is asked to render flat. This is the 2D/3D state, whether it was
  set by the app or by auto-flattening; the switch itself is animated, so for a moment after
  a change the map is still on its way there.
  
  Returns:
  
  True if the map is flat, or on its way to flat. The default is false.
- setFlattened
  
  public void setFlattened(boolean flattened)
  
  Switches the map between flat and 3D terrain, without detaching the elevation data the way
  setEnabled does. Auto-flattening writes the same state, so an app driving this itself
  normally turns auto off (setAutoFlattenParallax(0) and setAutoFlattenTilt(0)). What the
  switch costs, and whether a flat map goes on paying for 3D, is setFlattenMode.
  An app that starts in 2D sets this before it adds its layers, so nothing decodes for 3D.
  
  Parameters:
  
  flattened - True to render flat.
- getFlattenMode
  
  public int getFlattenMode()
  
  Returns how far a flattened terrain goes back towards a plain 2D map.
  
  Returns:
  
  The flatten mode. The default is TERRAIN_FLATTEN_MODE_RENDER.
- setFlattenMode
  
  public void setFlattenMode(int mode)
  
  Sets how far a flattened terrain goes back towards a plain 2D map. RENDER is the cheap
  switch: the terrain passes stop, but the tiles keep the subdivision 3D needed, so a flat
  map still draws a 3D map's triangles. FULL drops that too - a flat map decodes, culls and
  draws as if no terrain were configured - at the price of re-decoding the visible tiles at
  every switch.
  
  That re-decode is not visible: it is made while the map is already flat, where the two
  densities draw the same picture, and the tiles being replaced stay on screen until their
  replacement arrives. Going back to 3D waits for the tiles it needs before it starts to
  rise, so the wait shows as 3D arriving late rather than as a half-built map.
  
  Parameters:
  
  mode - The new flatten mode.
- getFlattenRatio
  
  public float getFlattenRatio()
  
  Returns how far the terrain is flattened right now, 0 (full 3D) to 1 (flat).
  
  Returns:
  
  The flatten ratio.
- setFlattenRatio
  
  public void setFlattenRatio(float ratio)
  
  Drives the 2D/3D switch by hand, off the app's own clock: 0 is full 3D, 1 is flat. Writing
  this takes the ratio away from setFlattened's animation, which is what an app does to make
  the terrain match a camera flight EXACTLY - feed it the flight's own progress rather than
  hope two timers agree. Auto-flattening is suspended while the app drives, and STAYS
  suspended until setFlattened hands the ratio back - so an app that drives an animation
  writes setFlattened once at the end of it, or a later tilt gesture does nothing.
  
  Rising is still gated on the tiles 3D needs: a ratio below 1 asks for them and the ground
  is HELD flat until they arrive, because unsubdivided geometry displaced over relief is a
  road in the sky. isSwitching() is that hold - wait on it before starting the animation.
  
  Parameters:
  
  ratio - The new flatten ratio, 0 to 1.
- isSwitching
  
  public boolean isSwitching()
  
  Returns whether the switch is holding the ground flat while the tiles 3D needs load.
  
  Returns:
  
  True while the switch is waiting for tiles.
- getAutoFlattenParallax
  
  public float getAutoFlattenParallax()
  
  Returns the screen parallax below which the terrain renders flat.
  
  Returns:
  
  The parallax in screen pixels. The default is 2. 0 never flattens.
- setAutoFlattenParallax
  
  public void setAutoFlattenParallax(float pixels)
  
  Sets the terrain parallax, in SCREEN PIXELS, below which 3D stops being worth its cost and
  the map renders flat. The parallax is how far the highest ground in view moves on screen
  because it is displaced:
  
  parallax = halfScreenDiagonal * heightRange * exaggeration / cameraDistance
  
  so it falls with the camera's height and rises with how mountainous the data is - a fixed
  zoom threshold is wrong for one of the two. The rule writes the same state setFlattened
  does, without touching setEnabled; how far flattening then goes is setFlattenMode.
  Restores at 1.5x this value, so a camera sitting on the boundary does not oscillate.
  
  Parameters:
  
  pixels - The new parallax threshold in screen pixels, or 0 to never flatten. The default is 2.
- getAutoFlattenTilt
  
  public float getAutoFlattenTilt()
  
  Returns the tilt at or above which the terrain renders flat.
  
  Returns:
  
  The tilt in degrees. The default is 88. 0 never flattens.
- setAutoFlattenTilt
  
  public void setAutoFlattenTilt(float tilt)
  
  Sets the tilt, in degrees, at or above which the map renders flat whatever the parallax.
  90 is straight down in this SDK, where the displacement is there but shows nothing worth
  its cost. Restores 2 degrees below the threshold, so a tilt gesture does not oscillate.
  
  Parameters:
  
  tilt - The new tilt threshold in degrees, or 0 to never flatten. The default is 88.
- getAutoFlattenDuration
  
  public float getAutoFlattenDuration()
  
  Returns how long the terrain takes to sink flat.
  
  Returns:
  
  The duration in seconds. The default is 0.3.
- setAutoFlattenDuration
  
  public void setAutoFlattenDuration(float duration)
  
  Sets how long the terrain takes to sink flat, and - unless setAutoFlattenRiseDuration
  overrides it - to rise again. The ramp scales the heights on the GPU, so it costs no tile
  re-decode; only when it reaches flat are the terrain passes themselves dropped, by which
  point the two render identically. Does not cover the wait for the tiles 3D needs (see
  setFlattenMode) - that is not the animation.
  
  Parameters:
  
  duration - The new duration in seconds. 0 switches instantly.
- getAutoFlattenRiseDuration
  
  public float getAutoFlattenRiseDuration()
  
  Returns how long the terrain takes to rise back into 3D.
  
  Returns:
  
  The duration in seconds, or a negative value to follow getAutoFlattenDuration.
- setAutoFlattenRiseDuration
  
  public void setAutoFlattenRiseDuration(float duration)
  
  Sets how long the terrain takes to RISE, separately from how long it takes to sink. The
  two are rarely worth the same: the rise is the one an app matches to a camera flight, and
  the one that waited for its tiles first. For an exact match to a flight, drive
  setFlattenRatio instead - a duration is a second timer, not the same clock.
  
  Parameters:
  
  duration - The new duration in seconds, or a negative value to use setAutoFlattenDuration.
- getExaggeration
  
  public float getExaggeration()
  
  Returns the terrain height exaggeration factor.
  
  Returns:
  
  The exaggeration factor. The default is 1.0.
- setExaggeration
  
  public void setExaggeration(float exaggeration)
  
  Sets the terrain height exaggeration factor. 1.0 means true-to-scale heights.
  Note: changing the exaggeration triggers a re-tesselation of loaded tiles, which is a relatively expensive operation.
  
  Parameters:
  
  exaggeration - The new exaggeration factor.
- isSeamlessTileEdgesEnabled
  
  public boolean isSeamlessTileEdgesEnabled()
  
  Returns whether seamless tile edge handling is enabled.
  
  Returns:
  
  True if elevation textures take their border texels from neighbouring DEM tiles at any level. The default is true.
- setSeamlessTileEdgesEnabled
  
  public void setSeamlessTileEdgesEnabled(boolean enabled)
  
  Enables or disables seamless tile edge handling. When enabled, the 1-texel border of
  every elevation texture is taken from the neighbouring elevation tiles - same-level
  neighbours texel-exactly, coarser (ancestor) neighbours by sampling their height field.
  Adjacent terrain tiles then agree on the height along their shared edge instead of
  showing a ridge of up to one DEM texel of relief. Costs no IO, only a small amount of
  CPU when an elevation texture is built. Disable if the elevation tiles already match
  exactly across tile borders.
  
  Parameters:
  
  enabled - True to fill elevation texture borders from neighbouring tiles.
- isElevationPrefetchEnabled
  
  public boolean isElevationPrefetchEnabled()
  
  Returns whether elevation tile prefetching is enabled.
  
  Returns:
  
  True if visible tiles and their neighbours are requested from the elevation data source. The default is true.
- setElevationPrefetchEnabled
  
  public void setElevationPrefetchEnabled(boolean enabled)
  
  Enables or disables elevation tile prefetching. When enabled, every visible terrain tile
  asynchronously requests its own elevation tile and the 8 surrounding ones, so neighbouring
  terrain tiles are displaced by the same DEM level and border texels have real neighbour
  data. When disabled, elevation tiles are only loaded as a side effect of map tile fetches,
  which leaves cached map tiles (and the tiles around the viewport) on coarser ancestor
  elevation data. This is the costly option: it adds elevation tile requests, decoding and
  cache pressure. Disable to keep elevation traffic at a minimum, or if the elevation
  tileset is fully local.
  
  Parameters:
  
  enabled - True to prefetch elevation tiles for visible tiles and their neighbours.
- getMeshResolution
  
  public int getMeshResolution()
  
  Returns the terrain mesh resolution.
  
  Returns:
  
  The maximum number of grid cells per tile edge used for terrain geometry. The default is 64.
- setMeshResolution
  
  public void setMeshResolution(int meshResolution)
  
  Sets the terrain mesh resolution. Higher values give more detailed terrain
  at the cost of memory and CPU. The effective resolution is also limited by
  the resolution of the elevation tiles.
  
  Parameters:
  
  meshResolution - The new mesh resolution (clamped to 2..256).
- isTileEdgeStitchingEnabled
  
  public boolean isTileEdgeStitchingEnabled()
  
  Returns whether cross-LOD tile edge stitching is enabled.
  
  Returns:
  
  True if grid surface edges follow a coarser neighbour's lattice. The default is true.
- setTileEdgeStitchingEnabled
  
  public void setTileEdgeStitchingEnabled(boolean enabled)
  
  Enables or disables cross-LOD tile edge stitching. Neighbouring terrain tiles at
  different zoom levels interpolate the elevation between differently spaced grid
  vertices along their shared edge, which opens a thin crack. When enabled, the finer
  tile chords across the coarser neighbour's grid nodes on that edge, so both tiles
  describe the same edge. Needs an even MeshResolution, and only takes effect in GPU
  draping mode. Costs one uniform per tile - no extra geometry.
  
  Parameters:
  
  enabled - True to snap grid surface edges to a coarser neighbour's grid.
- isDrapeFillsEnabled
  
  public boolean isDrapeFillsEnabled()
  
  Returns whether polygon fills are draped as a render-to-texture surface.
  
  Returns:
  
  True if fills are baked to a per-tile texture and sampled on the surface. The default is false.
- setDrapeFillsEnabled
  
  public void setDrapeFillsEnabled(boolean enabled)
  
  Enables or disables maplibre-style render-to-texture fill draping (experimental, spike). When
  enabled, polygon fills are rendered FLAT into a per-tile offscreen texture and then sampled as
  the color of the terrain surface mesh, instead of being drawn as displaced geometry. Because the
  fills become the surface's texture they follow the terrain exactly - no chord sag, so no holes,
  no see-through, and no depth slack - at flat-render (2D) fill cost. Lines/contours and labels are
  unaffected (still drawn as sharp geometry on top). Only native (non-overzoomed) fills are draped.
  Requires GPU draping mode (vertex texture fetch, planar projection).
  
  Parameters:
  
  enabled - True to drape fills as a texture, false to draw them as geometry.
- isDrapeLinesEnabled
  
  public boolean isDrapeLinesEnabled()
  
  Returns whether vt tile lines are also draped (in addition to fills).
  
  Returns:
  
  True if tile lines are baked into the drape texture. The default is true.
- setDrapeLinesEnabled
  
  public void setDrapeLinesEnabled(boolean enabled)
  
  Enables or disables draping of vt tile lines in addition to fills (needs DrapeFillsEnabled).
  Draped lines are baked into the per-tile texture: they follow the terrain exactly and cost
  no per-frame geometry (a city pan runs at twice the frame rate), but they resolve at the
  drape resolution rather than the screen's. Layers matching NoDrapeLayerFilter stay sharp
  either way. See docs/internals/rendering/04-terrain.md.
  
  Parameters:
  
  enabled - True to drape tile lines too, false to keep them as sharp geometry.
- isBridges3DEnabled
  
  public boolean isBridges3DEnabled()
  
  Returns whether bridges and tunnels stand on their own chord (3D bridges).
  
  Returns:
  
  True if a `span` feature is lifted onto the chord between its portals and a
  span deck is drawn as an extrusion. The default is false.
- setBridges3DEnabled
  
  public void setBridges3DEnabled(boolean enabled)
  
  Enables or disables 3D bridges: a feature styled `line-elevation-mode: span` (or the
  polygon/building variants) is laid straight between its two portals instead of draped
  over the terrain, and a span deck stands as an extrusion carrying its road. Off, every
  such feature drapes like the ground and none of the span machinery runs - no chord
  resolution, no deck drape bakes, no reference tile fetches. Needs terrain.
  See docs/internals/rendering/04-terrain.md, "Bridges and tunnels: spans".
  
  Parameters:
  
  enabled - True to lift spans onto their chord, false to drape them.
- getNoDrapeLayerFilter
  
  public String getNoDrapeLayerFilter()
  
  Returns the style layers that are kept out of the terrain drape bake.
  
  Returns:
  
  A regular expression matched against vt style layer names. The default is
  "^contour.*"; an empty string drapes everything the geometry type allows.
- setNoDrapeLayerFilter
  
  public void setNoDrapeLayerFilter(String filter)
  
  Sets which style layers must NOT be baked into the drape texture, as a regular expression
  over the vt layer name (which comes from the style's own rule names). They are drawn live
  in the 3D pass at screen resolution instead. Hairline content is what the drape resolution
  costs, hence contours by default. They still take the terrain's sun and shadow, so they
  shade like the ground they lie on.
  
  Parameters:
  
  filter - The regular expression, or an empty string to drape everything.
- getDrapeResolution
  
  public int getDrapeResolution()
  
  Returns the per-tile drape texture resolution, 0 when it follows the screen.
  
  Returns:
  
  The drape texture resolution in pixels, 0 for automatic.
- setDrapeResolution
  
  public void setDrapeResolution(int resolution)
  
  Sets the per-tile drape texture resolution. Draped content is rasterized into a texture
  of this size and resampled onto the terrain surface, so this trades sharpness of thin
  content (lines, outlines) against video memory: cost is resolution^2 * 4 bytes per
  visible tile. maplibre uses twice the tile size (1024 for 512px tiles) for this reason.
  0 (the default) takes it from the SCREEN instead: the tile LOD refines a tile until it
  covers at most a 2x2 block of nominal tiles, so 2 * tileDrawSize * pixelScale texels is
  one texel per screen pixel at that bound - a fixed resolution is either coarser than the
  screen (draped fill edges stair-step as you zoom in) or finer than it can show.
  
  Parameters:
  
  resolution - The new drape texture resolution, clamped to [128, 2048], or 0 to follow the screen.
- getMinZoom
  
  public int getMinZoom()
  
  Returns the minimum tile zoom level with 3D terrain.
  
  Returns:
  
  The minimum zoom level. The default is 5.
- setMinZoom
  
  public void setMinZoom(int minZoom)
  
  Sets the minimum tile zoom level with 3D terrain. Tiles below this zoom level render flat
  and do not fetch elevation data. Terrain displacement is invisible at low zoom levels anyway,
  so this limits the number of elevation tiles fetched and processed for far-away/zoomed-out views.
  
  Parameters:
  
  minZoom - The new minimum zoom level (clamped to 0..24).
- getViewDistanceFactor
  
  public float getViewDistanceFactor()
  
  Returns the factor applied to the view distance.
  
  Returns:
  
  The view distance factor. The default is 1, which is exactly tangram's rule.
- setViewDistanceFactor
  
  public void setViewDistanceFactor(float factor)
  
  Sets how far from the camera the map is drawn and where the far plane sits, as a factor
  on tangram's own rule (core/src/view/view.cpp):
  far = 2 * cameraHeight / cos(pitch + fovy/2), capped by
  maxTileDistance = worldTileSize(zoom) * (2^(MAX_LOD+1) - 1), with MAX_LOD 6.
  A factor of 1 is that rule verbatim; smaller ends the view closer, larger extends it.
  This is what makes a near-horizontal view affordable: taken from the visible ground
  instead, the view reaches the horizon - hundreds of tiles, most of them a few pixels
  tall, each carrying its own labels. Pair a small factor with fog so the ground fades
  out instead of ending.
  It also decides the depth budget: tangram's model is calibrated on a far/near ratio of a
  few hundred, and a deeper far spends the NDC precision the per-layer depth separation
  needs.
  A style may pin an absolute distance instead, in meters, with
  "terrain-max-visible-distance".
  
  Parameters:
  
  factor - The new view distance factor. The default is 1.
- getViewDistance
  
  public float getViewDistance()
  
  Returns the minimum view distance, in meters.
  
  Returns:
  
  The view distance in meters. 0 (the default) leaves the factor rule alone.
- setViewDistance
  
  public void setViewDistance(float distance)
  
  Sets a MINIMUM distance the map is drawn to, in METERS, whatever the camera's height or
  pitch. Tangram's rule is proportional to the camera's height above the ground, so
  approaching the terrain shortens the view - which is right for a map seen from above and
  wrong for a view along the ground, where the same landscape should stay visible as the
  camera descends into it. An absolute distance keeps the ground reaching at least this far
  at any elevation and any tilt. The far plane follows it, which spends depth precision
  (see setViewDistanceFactor), so this is an explicit trade - pair it with fog so the
  ground fades out instead of ending.
  It only ever EXTENDS the factor rule: metres are zoom-independent while the rule scales
  with the camera's height, so a distance that reaches the horizon up close would end the
  ground in a disc well inside a zoomed-out screen.
  0 (the default) leaves the factor rule alone.
  
  Parameters:
  
  distance - The new minimum view distance in meters, or 0 for the factor rule alone.
- getDrapeCacheSize
  
  public int getDrapeCacheSize()
  
  Returns the drape cache budget in megabytes.
  
  Returns:
  
  The drape cache budget in megabytes. The default is 96.
- setDrapeCacheSize
  
  public void setDrapeCacheSize(int megabytes)
  
  Sets how much video memory the cached drape textures may take, in megabytes. The cache
  has to hold the LIVE cover AND the generation it just replaced: a leaf whose own bake has
  not landed stands in on the cached tiles under it, so a budget that fits only one cover
  evicts the previous generation on every frame of a zoom and those leaves are painted in
  the flat background colour instead - the ground blinking during a fast zoom.
  It also decides the automatic drape resolution (see DrapeResolution and DrapeWorkingSet),
  since the two have to agree.
  
  Parameters:
  
  megabytes - The new budget in megabytes, or 0 for the default of 96.
- getDrapeWorkingSet
  
  public int getDrapeWorkingSet()
  
  Returns how many drape tiles the automatic resolution assumes are cached at once.
  
  Returns:
  
  The assumed working set in tiles. The default is 64.
- setDrapeWorkingSet
  
  public void setDrapeWorkingSet(int tiles)
  
  Sets how many drape tiles the automatic resolution (DrapeResolution 0) assumes have to
  fit the budget at once: the live cover plus the generation a zoom or pan is about to need
  back. The resolution is halved until that many fit DrapeCacheSize.
  Lower values buy sharpness at the price of a cache that thrashes; a real cover was
  measured at 15-34 leaves, so a working set below that cannot hold even the live cover.
  
  Parameters:
  
  tiles - The assumed working set in tiles. The default is 64.
- getMaxTileZoomCoarsening
  
  public int getMaxTileZoomCoarsening()
  
  Returns how many zoom levels below the camera a tile may coarsen to.
  
  Returns:
  
  The maximum tile zoom coarsening. The default is 3.
- setMaxTileZoomCoarsening
  
  public void setMaxTileZoomCoarsening(int levels)
  
  Sets how far BELOW the camera's zoom the tile LOD may take a tile in terrain mode
  (Options::TileLODFactor decides the rest). The tile surface is the depth OCCLUDER and its
  tesselation is proportional to the tile size, so a tile that coarsens freely has its
  ridge crests chopped flat and content drawn over a finer tile of another layer - a road,
  a contour - shows through the ridge in front of it. The DEM level follows the tile zoom
  as well (one elevation texture per tile), so the same tiles also shade as blocky
  hillshade.
  Larger values give the LOD more room - fewer tiles at a tilt, at the price of both;
  0 pins every tile to the camera's own zoom.
  
  Parameters:
  
  levels - The new maximum tile zoom coarsening. The default is 3.
- getBackgroundColor
  
  public Color getBackgroundColor()
  
  Returns the terrain background color.
  
  Returns:
  
  The terrain background color. The default is transparent (no background).
- setBackgroundColor
  
  public void setBackgroundColor(Color color)
  
  Sets the terrain background color: an opaque base fill of the terrain surface
  drawn under all layers. It keeps the terrain shape visible (and its depth valid
  for vector element and billboard occlusion) even without any raster or vector
  tile layer content - without it the terrain is transparent wherever no layer
  paints. Transparent (the default) disables the fill.
  
  Parameters:
  
  color - The new terrain background color.
- isBackgroundBitmapEnabled
  
  public boolean isBackgroundBitmapEnabled()
  
  Returns the terrain background bitmap state.
  
  Returns:
  
  True if the map background bitmap is draped over the terrain as the base fill. The default is false.
- setBackgroundBitmapEnabled
  
  public void setBackgroundBitmapEnabled(boolean enabled)
  
  Sets the terrain background bitmap state. When enabled, the map background bitmap
  (Options::getBackgroundBitmap, the repeating pattern flat maps show below the tiles)
  is draped over the terrain surface as the base fill drawn under all layers,
  instead of the solid background color. Like the background color fill, it keeps
  the terrain shape visible (and its depth valid for occlusion) where no layer
  paints, and shows through translucent tile layer content.
  
  Parameters:
  
  enabled - The new background bitmap state.
- getSurfaceShaderSource
  
  public String getSurfaceShaderSource()
  
  Returns the custom terrain surface fragment shader source, or an empty string if
  no shaded surface is drawn.
  
  Returns:
  
  The custom surface shader source.
- setSurfaceShaderSource
  
  public void setSurfaceShaderSource(String shaderSource)
  
  Sets a fragment shader that paints the terrain surface itself. When set, it replaces
  the background bitmap and the background color as the terrain base fill: the surface
  is drawn as an opaque pass under all layers, so a map with no tile layer at all still
  shows shaded relief. The source must define
  
  vec4 surfaceColor();
  
  returning the non-premultiplied surface colour. These are available to it:
  
  varying vec3 v_normal; // unit surface normal, world space (x east, y north, z up)
  varying vec3 v_worldPos; // surface position in internal map units
  varying float v_elevation; // surface elevation in metres (before exaggeration)
  varying float v_dist; // distance from the camera in metres
  uniform vec3 u_sunDir; // unit vector towards the sun, world space
  uniform vec4 u_sunColor; // sun colour, rgba 0..1
  uniform float u_sunIntensity;
  uniform float u_ambientIntensity;
  uniform float u_time; // seconds since the map view was created
  uniform float u_zoom; // current fractional map zoom
  uniform vec2 u_resolution; // viewport size in pixels
  
  The surface must NOT fog itself: the SDK applies the same fog the rest of the frame gets
  to whatever this returns. The fog uniforms and helpers documented on
  FogOptions::setShaderSource are declared here too, and must not be redeclared.
  
  plus every parameter set with setSurfaceParameter (float) and setSurfaceColorParameter
  (vec4, rgba 0..1) as a uniform of that name. Redeclaring any of the above is a compile
  error, and a shader that fails to compile is dropped (the background bitmap/color is
  used instead) with the error logged.
  
  Parameters:
  
  shaderSource - The GLSL source, or an empty string for no shaded surface.
- getSurfaceParameter
  
  public float getSurfaceParameter(String name)
  
  Returns the value of a terrain surface shader float parameter.
  
  Parameters:
  
  name - The name of the parameter.
  
  Returns:
  
  The value of the parameter, or 0 if not set.
- setSurfaceParameter
  
  public void setSurfaceParameter(String name, float value)
  
  Sets a terrain surface shader float parameter, exposed to the shader as a uniform.
  
  Parameters:
  
  name - The name of the parameter (must be a valid GLSL identifier).
  
  value - The new value for the parameter.
- getSurfaceColorParameter
  
  public Color getSurfaceColorParameter(String name)
  
  Returns the value of a terrain surface shader color parameter.
  
  Parameters:
  
  name - The name of the parameter.
  
  Returns:
  
  The value of the parameter, or transparent black if not set.
- setSurfaceColorParameter
  
  public void setSurfaceColorParameter(String name, Color color)
  
  Sets a terrain surface shader color parameter, exposed to the shader as a vec4
  uniform with components in the 0..1 range.
  
  Parameters:
  
  name - The name of the parameter (must be a valid GLSL identifier).
  
  color - The new value for the parameter.
- getMaxTileZoomOffset
  
  public int getMaxTileZoomOffset()
  
  Returns the maximum visible tile zoom offset, relative to the camera zoom level.
  
  Returns:
  
  The maximum tile zoom offset. The default is 100 (no cap).
- setMaxTileZoomOffset
  
  public void setMaxTileZoomOffset(int offset)
  
  Sets the maximum visible tile zoom offset, relative to the camera zoom level.
  Terrain level-of-detail is distance based: tiles close to the camera (and mountain
  faces rising towards it) are shown at higher tile zoom levels than flat rendering
  would ever use at the same camera zoom. If the map style renders differently at
  different tile zoom levels, these LOD rings become visible as patches with hard
  boundaries. Offset 0 caps tile detail at the level flat rendering would show at
  the current camera zoom; positive values allow that many extra levels of detail
  near the camera. Values of 100 or more disable the cap.
  
  Parameters:
  
  offset - The new maximum tile zoom offset (values >= 100 disable the cap).
- getCameraClearance
  
  public float getCameraClearance()
  
  Returns the camera terrain clearance floor: an explicit minimum height the camera
  is kept above the terrain surface, in meters.
  
  Returns:
  
  The camera clearance floor in meters. The default is 0.
- setCameraClearance
  
  public void setCameraClearance(float clearance)
  
  Sets the camera terrain clearance floor, in meters. The camera is always kept a
  height above the terrain under it that scales with the zoom, as in mapbox: a
  sixteenth of its distance to sea level, so zooming in is never blocked by the
  clearance alone. This floor is added under that rule for apps that want a fixed
  minimum. A zoom in stops at the clearance; a camera pushed under it by a pan or
  by arriving elevation is lifted at a constant zoom, by reducing the tilt.
  
  Parameters:
  
  clearance - The new clearance floor in meters. 0 (the default) applies the zoom-relative rule alone.
- getCameraClampDuration
  
  public float getCameraClampDuration()
  
  Returns the duration of the camera terrain-following correction animation.
  
  Returns:
  
  The correction duration in seconds. The default is 0 (instant correction).
- setCameraClampDuration
  
  public void setCameraClampDuration(float duration)
  
  Sets the duration of the camera terrain-following correction animation.
  
  Parameters:
  
  duration - The new duration in seconds. 0 applies corrections instantly.
- getDepthBias
  
  public float getDepthBias()
  
  Returns the clip-space depth bias used when depth-testing draped 2D geometry against the terrain.
  
  Returns:
  
  The depth bias. The default is 0.0002.
- setDepthBias
  
  public void setDepthBias(float depthBias)
  
  Sets the clip-space depth bias used when depth-testing draped 2D geometry against the terrain.
  Larger values prevent draped layers from being clipped by the terrain surface itself,
  at the cost of geometry slightly behind terrain ridges 'shining through' near silhouettes.
  
  Parameters:
  
  depthBias - The new depth bias (clamped to 0..0.01).
- getBillboardOcclusionTolerance
  
  public float getBillboardOcclusionTolerance()
  
  Returns the billboard/label terrain occlusion tolerance.
  
  Returns:
  
  The relative depth tolerance. The default is 0.
- setBillboardOcclusionTolerance
  
  public void setBillboardOcclusionTolerance(float tolerance)
  
  Sets how far behind the terrain a billboard or label anchor may sit and still count
  as visible, as a fraction of its distance from the camera. 0, the default, hides a
  label the moment its anchor goes behind the relief. Larger values
  deliberately let partly hidden features label - a summit just behind a nearer ridge
  still shows its name, which is what a peak-finder view wants.
  
  Parameters:
  
  tolerance - The new relative tolerance (clamped to 0..1).
- getTextOcclusionOpacity
  
  public float getTextOcclusionOpacity()
  
  Returns the opacity a label keeps while its anchor is behind 3D content.
  
  Returns:
  
  The opacity of an occluded label. The default is 1, i.e. no occlusion.
- setTextOcclusionOpacity
  
  public void setTextOcclusionOpacity(float opacity)
  
  Sets the opacity a label keeps while the point it is anchored at is hidden by 3D
  content - buildings, not the terrain, which occludes labels regardless (see
  BillboardOcclusionTolerance). 0 hides such a label completely; 1, the default, draws it
  as if nothing were in front of it.
  
  The test is per LABEL, not per fragment: a building crossing part of a word does not cut
  it, the whole label fades by how much of a small square around its anchor is covered.
  
  Below 1 this costs one extra pass over the visible extrusions per frame (measured at
  ~0.85 ms on an Adreno 610 at a city camera); at 1 the pass does not run at all. The
  style's 'text-occlusion-opacity' wins over this value where it sets one.
  
  Parameters:
  
  opacity - The opacity of an occluded label (clamped to 0..1).
- isBillboardOcclusionEnabled
  
  public boolean isBillboardOcclusionEnabled()
  
  Returns the billboard/label terrain occlusion state.
  
  Returns:
  
  True if billboards and labels hidden behind terrain are faded out. The default is true.
- setBillboardOcclusionEnabled
  
  public void setBillboardOcclusionEnabled(boolean enabled)
  
  Sets the billboard/label terrain occlusion state.
  
  Parameters:
  
  enabled - The new occlusion state.
- getElevation
  
  public double getElevation(MapPos pos)
  
  Returns the terrain elevation in meters at the given position.
  The position is expected to be in WGS84 coordinates.
  Note: this method may block on network/IO if the elevation tile is not cached.
  
  Parameters:
  
  pos - The position to query.
  
  Returns:
  
  The elevation in meters, or -1000000 if no elevation data is available.
- getElevations
  
  public DoubleVector getElevations(MapPosVector poses)
  
  Returns terrain elevations in meters at the given positions (WGS84).
  One value is returned for every input position, in the input order.
  Note: this method may block on network/IO if the elevation tiles are not cached.
  
  Parameters:
  
  poses - The positions to query.
  
  Returns:
  
  The elevations in meters (-1000000 where no data is available).

Class TerrainOptions

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

TerrainOptions

TerrainOptions

Method Details

getDataSource

getElevationDecoder

isEnabled

setEnabled

isFlattened

setFlattened

getFlattenMode

setFlattenMode

getFlattenRatio

setFlattenRatio

isSwitching

getAutoFlattenParallax

setAutoFlattenParallax

getAutoFlattenTilt

setAutoFlattenTilt

getAutoFlattenDuration

setAutoFlattenDuration

getAutoFlattenRiseDuration

setAutoFlattenRiseDuration

getExaggeration

setExaggeration

isSeamlessTileEdgesEnabled

setSeamlessTileEdgesEnabled

isElevationPrefetchEnabled

setElevationPrefetchEnabled

getMeshResolution

setMeshResolution

isTileEdgeStitchingEnabled

setTileEdgeStitchingEnabled

isDrapeFillsEnabled

setDrapeFillsEnabled

isDrapeLinesEnabled

setDrapeLinesEnabled

isBridges3DEnabled

setBridges3DEnabled

getNoDrapeLayerFilter

setNoDrapeLayerFilter

getDrapeResolution

setDrapeResolution

getMinZoom

setMinZoom

getViewDistanceFactor

setViewDistanceFactor

getViewDistance

setViewDistance

getDrapeCacheSize

setDrapeCacheSize

getDrapeWorkingSet

setDrapeWorkingSet

getMaxTileZoomCoarsening

setMaxTileZoomCoarsening

getBackgroundColor

setBackgroundColor

isBackgroundBitmapEnabled

setBackgroundBitmapEnabled

getSurfaceShaderSource

setSurfaceShaderSource

getSurfaceParameter

setSurfaceParameter

getSurfaceColorParameter

setSurfaceColorParameter

getMaxTileZoomOffset

setMaxTileZoomOffset

getCameraClearance

setCameraClearance

getCameraClampDuration

setCameraClampDuration

getDepthBias

setDepthBias

getBillboardOcclusionTolerance

setBillboardOcclusionTolerance

getTextOcclusionOpacity