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 (unlike setEnabled). Auto-flattening writes the same state, so an app driving this normally sets both AutoFlatten thresholds to 0. 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 only stops the terrain passes; FULL also drops the 3D subdivision, re-decoding the visible tiles at each switch (invisibly, while flat). Going back to 3D waits for the tiles it needs before it starts to rise.

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

Drives the 2D/3D switch by hand (0 full 3D, 1 flat), e.g. from a camera flight’s own progress. Auto-flattening stays suspended until setFlattened hands the ratio back, so call it once at the end. Below 1 the ground is held flat until the 3D tiles arrive; wait on isSwitching() 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 parallax in screen pixels (halfScreenDiagonal * heightRange * exaggeration / cameraDistance) below which the map renders flat; it writes the same state setFlattened does. 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 to rise unless setAutoFlattenRiseDuration overrides it. The ramp scales heights on the GPU (no re-decode); the wait for the tiles 3D needs is not included.

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

Sets how long the terrain takes to rise, separately from sinking. To match a camera flight exactly, drive setFlattenRatio instead: a duration is a second timer.

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 edges: each elevation texture’s 1-texel border is taken from the neighbouring DEM tiles (coarser ones sampled), so adjacent tiles agree on edge height. No IO, a little CPU. Disable if the elevation tiles already match exactly across tile borders.

Returns whether elevation tile prefetching is enabled.

Enables or disables elevation prefetching: each visible terrain tile requests its own elevation tile and the 8 around it, so neighbours share a DEM level; off, cached map tiles stay on coarser ancestor data. Costs requests, decoding and cache pressure; disable for minimal traffic or a fully local tileset.

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 the distance geo-three’s terrain LOD subdivides at.

Cuts and meshes the terrain the way geo-three’s webapp does, so the two render the same picture: a tile at zoom z subdivides while the camera is closer than distance * 2^(20 - z) Mercator metres (geo-three’s desktop value is 70), with no tile budget and bilinear DEM heights.

Returns the resolution the elevation node field is built at.

Sets the resolution of the height field the terrain is displaced from, per DEM tile edge, independently of the mesh drawn over it. Overzoomed, this field limits the relief, not the mesh. Costs memory per cached DEM grid, not frames. The default 0 follows MeshResolution. Applied to the elevation manager at once, not on the first 3D frame, so no decoded grid is dropped mid-switch.

Returns the downscale factor of the packed depth/normal texture post-process effects read.

Sets the downscale factor of the packed depth/normal texture that post-process effects read. The default 2 suits shading; an effect that differentiates the normals (ridge lines) shows blocky texels, which 1 removes at four times the fill. The occlusion read-back is unaffected.

Returns whether cross-LOD tile edge stitching is enabled.

Enables or disables cross-LOD edge stitching: the finer tile chords across a coarser neighbour’s grid nodes, closing the crack between them. Needs an even MeshResolution and GPU draping mode; costs one uniform per tile.

Returns how many terrain surface meshes may be cached.

Sets how many terrain surface meshes may be cached; the visible cut holds half as many tiles. The default 0 keeps the built-in 160/80, a map’s working set. Raise it for a panorama, whose wider cut otherwise rebuilds meshes while turning and keeps dropping a zoom level.

Returns whether the shared ground pass draws the terrain a second time.

Enables or disables the flat shared-ground draw when DrapeFillsEnabled is false. The default is true. Disable it only when a surface shader plus labels/billboards is all the map draws; fills and lines need that ground to composite onto.

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

Enables or disables maplibre-style fill draping (experimental): fills render flat into a per-tile texture sampled by the terrain surface, so they follow it exactly at 2D fill cost. Only native (non-overzoomed) fills drape; lines need DrapeLinesEnabled. Requires GPU draping mode (vertex texture fetch, planar).

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

Enables or disables draping of tile lines too (needs DrapeFillsEnabled): they follow the terrain exactly at no per-frame geometry cost, but resolve at the drape resolution. Layers matching NoDrapeLayerFilter stay sharp. 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 line-elevation-mode: span feature (or polygon/building variant) is laid straight between its portals and a span deck stands as an extrusion; off, spans drape and no span work runs. 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 are not baked into the drape texture, as a regular expression over the vt layer name; they are drawn live at screen resolution, still sun and shadow shaded. Meant for hairlines such as contours.

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

Sets the per-tile drape texture resolution, trading thin-content sharpness against video memory (resolution^2 * 4 bytes per visible tile). 0 (the default) follows the screen: 2 * tileDrawSize * pixelScale, one texel per pixel at the tile LOD bound, halved until DrapeWorkingSet tiles fit DrapeCacheSize.

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 maximum tile zoom level the terrain mesh is cut at.

Caps the tile zoom the terrain mesh is cut at and the elevation tiles selected to feed it, so the ground settles once instead of refining under labels and camera (a panorama). The default 0 leaves both to the distance rule, the tile budget and the source maximum.

Returns the factor applied to the view distance.

Sets the view distance and far plane as a factor on tangram’s rule (far = 2 * cameraHeight / cos(pitch + fovy/2), capped at worldTileSize(zoom) * 127); smaller ends the view closer (pair with fog), larger costs depth precision. 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, at any camera height or tilt, for views along the ground. It only ever extends the factor rule and spends depth precision, so pair it with fog. 0 (the default) leaves the factor rule alone.

Returns the maximum view distance, in meters.

Sets a maximum distance the map is drawn to, in meters, capping culling, the tile walk and the far plane; it also caps setViewDistance. Independent of the fog, which a summit may stand above. 0 (the default) is no ceiling.

Returns the drape cache budget in megabytes.

Sets how much video memory the cached drape textures may take, in megabytes. It must hold the live cover and the generation it replaced, or the ground blinks during a fast zoom. It also bounds the automatic drape resolution (see DrapeResolution and DrapeWorkingSet).

Returns the elevation grid cache budget in megabytes, 0 for the SDK’s own rule.

Sets how much memory the decoded elevation grids may take, in megabytes (a 512-texel grid is ~1.8 MB). The default 0 keeps 192 grids, a map’s working set; raise it for a wide view, where a full cache refetches every eviction and keeps the decode threads busy.

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

Sets how many drape tiles the automatic resolution (DrapeResolution 0) assumes must fit DrapeCacheSize at once (live cover plus the next generation). Lower is sharper but thrashes below a real cover’s 15-34 leaves.

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. The surface is the depth occluder and its DEM level follows the tile, so coarse tiles chop ridge crests (content shows through) and shade blocky; larger values mean fewer tiles at a tilt. 0 pins every tile to the camera’s own zoom.

Returns the terrain background color.

Sets the terrain background color: an opaque base fill under all layers that keeps the terrain shape (and its depth, for occlusion) where 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) is draped as the base fill under all layers instead of the background color.

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

Sets a fragment shader defining “vec4 surfaceColor()” (non-premultiplied, not fogged) that paints the terrain surface as the base fill, replacing the background bitmap/color. On compile error it is dropped and logged. Varyings, uniforms and parameters: docs/internals/rendering/04-terrain.md, “The surface shader”.

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. Distance-based terrain LOD shows near tiles finer than flat rendering would, exposing zoom-dependent styling as hard-edged rings; 0 caps at the flat level, positive values allow that many extra levels. 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, added under the zoom-relative rule (as in mapbox, a share of the camera’s altitude, see CameraClearanceFraction). A zoom in stops at the clearance; a camera pushed under it by a pan or arriving elevation is lifted at a constant zoom, by reducing the tilt.

Returns the share of the camera’s altitude that the terrain clearance takes.

Sets the share of the camera’s altitude the clearance takes (default 1/16). 0 leaves CameraClearance alone as a fixed height above the ground, as a first-person view needs.

Returns the height the viewpoint is lifted above the ground-following focus, in meters.

Sets the height the viewpoint is lifted above the ground under it, in meters, added to the ground-following rule (a focus z is recomputed every frame). For a first-person viewpoint standing above the ridge in front of it.

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. The default is 0.05; 0 hides a label the moment its anchor goes behind the relief; larger values let a summit just behind a nearer ridge keep its name.

Returns the ground distance the surface normals are measured over, in meters.

Sets the ground distance the per-vertex surface normals are measured over, in meters. The default 0 uses the mesh spacing, which differs across LOD boundaries and draws them as lines in a normal- differentiating effect; 60-150 m reads ridges. Planar surfaces only.

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

Sets the opacity a label keeps while its anchor is hidden by buildings (terrain occludes regardless), faded per label by how much of a small square around the anchor is covered. 1, the default, disables it; below 1 costs one extra pass over visible extrusions. The style’s ‘text-occlusion-opacity’ wins 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.

Returns whether tiles are decoded for terrain even while the terrain is disabled.

Sets whether tiles are decoded for terrain, and the elevation data warmed, while the terrain is disabled. Costs the terrain tile set and the elevation fetches in 2D, saves the re-decode on setEnabled.

Undocumented