MSFTerrainOptions

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.

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

Returns the elevation data source.

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 enabled state of the terrain.

Sets the enabled state of the terrain. If disabled, the map renders flat, but the elevation data source stays attached.

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.

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.

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

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.

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

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.

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

Returns the screen parallax below which the terrain renders flat.

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.

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

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.

Returns how long the terrain takes to sink flat.

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.

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

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.

Returns the terrain height exaggeration factor.

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.

Returns whether seamless tile edge handling is 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.

Returns whether elevation tile prefetching is 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.

Returns the terrain mesh resolution.

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.

Returns whether cross-LOD tile edge stitching is 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.

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

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).

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

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.

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

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”.

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

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.

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

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.

Returns the minimum tile zoom level with 3D terrain.

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.

Returns the factor applied to the view distance.

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”.

Returns the minimum view distance, in meters.

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.

Returns the drape cache budget in 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.

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

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.

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

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.

Returns the terrain background 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.

Returns the terrain background bitmap state.

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.

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

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.

Returns the value of a terrain surface shader float parameter.

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

Returns the value of a terrain surface shader color parameter.

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

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

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.

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

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.

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

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

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

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.

Returns the billboard/label terrain occlusion 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.

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

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.

Returns the billboard/label terrain occlusion state.

Sets the billboard/label terrain occlusion state.

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.

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.

Undocumented