MSFHillshadeRasterTileLayer

Objective-C


@interface MSFHillshadeRasterTileLayer : MSFCustomRasterTileLayer

Swift

class MSFHillshadeRasterTileLayer : MSFCustomRasterTileLayer

A tile layer that displays an overlay hillshading. Should be used together with corresponding data source that encodes height in RGBA image. The shading is based on the direction of the main light source, which can be configured using Options class. Note: this class is experimental and may change or even be removed in future SDK versions.

  • Constructs a HillshadeRasterTileLayer object from a data source.

    Declaration

    Objective-C

    - (id)initWithDataSource:(MSFTileDataSource *)dataSource
        elevationDecoder:(MSFElevationDecoder *)elevationDecoder;

    Swift

    init!(dataSource: MSFTileDataSource!, elevationDecoder: MSFElevationDecoder!)

    Parameters

    dataSource

    The data source from which this layer loads data.

  • Undocumented

    Declaration

    Objective-C

    - (id)initWithDataSource:(MSFTileDataSource *)dataSource;

    Swift

    init!(dataSource: MSFTileDataSource!)

  • Returns the contrast of the hillshade overlay. This is the equivalent of MapLibre’s ‘hillshade-exaggeration’ paint property: it controls the slope response curve and the overall strength of the shading, not the relief itself.

    Declaration

    Objective-C

    - (float)getContrast;

    Swift

    func getContrast() -> Float

    Return Value

    The contrast value (between 0..1). Default is 0.5.

  • Sets the contrast of the hillshade overlay. Equivalent to MapLibre’s ‘hillshade-exaggeration’; 0.5 is the neutral value.

    Declaration

    Objective-C

    - (void)setContrast:(float)contrast;

    Swift

    func setContrast(_ contrast: Float)

    Parameters

    contrast

    The contrast value (between 0..1).

  • Returns the height scale of the hillshade overlay.

    Declaration

    Objective-C

    - (float)getHeightScale;

    Swift

    func getHeightScale() -> Float

    Return Value

    The relative height scale. Default is 0.05.

  • Sets the height scale of the hillshade overlay. Baked into the normal map at decode time, so changing it reloads the tiles. See setLegacyHeightScaleEnabled for the old default.

    Declaration

    Objective-C

    - (void)setHeightScale:(float)heightScale;

    Swift

    func setHeightScale(_ heightScale: Float)

    Parameters

    heightScale

    The relative height scale. Actual height is multiplied by this values.

  • Returns the per-frame relief exaggeration factor, i.e. the vertical exaggeration of the slope. Unlike height scale this is a shader uniform applied at render time (no tile re-decode), so it can be animated smoothly.

    Declaration

    Objective-C

    - (float)getExaggeration;

    Swift

    func getExaggeration() -> Float

    Return Value

    The exaggeration factor. Default is 1.0.

  • Sets the per-frame relief exaggeration factor. Multiplies the hillshade slope in the shader without re-decoding tiles, so it can change smoothly (e.g. with zoom). 1.0 leaves the appearance unchanged.

    Declaration

    Objective-C

    - (void)setExaggeration:(float)exaggeration;

    Swift

    func setExaggeration(_ exaggeration: Float)

    Parameters

    exaggeration

    The exaggeration factor.

  • Returns the shading color of areas that face away from the light source.

    Declaration

    Objective-C

    - (MSFColor *)getShadowColor;

    Swift

    func getShadowColor() -> MSFColor!

    Return Value

    The shadow color of the layer.

  • Sets the shading color of areas that face away from the light source.

    Declaration

    Objective-C

    - (void)setShadowColor:(MSFColor *)color;

    Swift

    func setShadowColor(_ color: MSFColor!)

    Parameters

    color

    The new shadow color of the layer.

  • Returns the shading color used to accentuate rugged terrain like sharp cliffs and gorges.

    Declaration

    Objective-C

    - (MSFColor *)getAccentColor;

    Swift

    func getAccentColor() -> MSFColor!

    Return Value

    The accent color of the layer.

  • Sets the shading color used to accentuate rugged terrain like sharp cliffs and gorges.

    Declaration

    Objective-C

    - (void)setAccentColor:(MSFColor *)color;

    Swift

    func setAccentColor(_ color: MSFColor!)

    Parameters

    color

    The new accent color of the layer.

  • Returns the shading color of areas that faces towards the light source.

    Declaration

    Objective-C

    - (MSFColor *)getHighlightColor;

    Swift

    func getHighlightColor() -> MSFColor!

    Return Value

    The highlight color of the layer.

  • Sets the shading color of areas that faces towards the light source.

    Declaration

    Objective-C

    - (void)setHighlightColor:(MSFColor *)color;

    Swift

    func setHighlight(_ color: MSFColor!)

    Parameters

    color

    The new highlight color of the layer.

  • Undocumented

    Declaration

    Objective-C

    -(NSString*)getNormalMapLightingShader;

    Swift

    func getNormalMapLightingShader() -> String!

  • Sets a custom normalmap lighting shader.

    Declaration

    Objective-C

    - (void)setNormalMapLightingShader:(NSString *)shader;

    Swift

    func setNormalMapLightingShader(_ shader: String!)

    Parameters

    shader

    The custom shader.

  • Returns the illumination direction of the layer.

    Declaration

    Objective-C

    - (MSFMapVec *)getIlluminationDirection;

    Swift

    func getIlluminationDirection() -> MSFMapVec!

    Return Value

    The direction vector for the hillshade illumination

  • Sets the illumination direction. The horizontal part is read as a compass bearing (x = sin(azimuth), y = cos(azimuth), with azimuth 0 = north, increasing clockwise) pointing towards the light, and z points down towards the ground: -sin(altitude). MapLibre’s default ‘hillshade-illumination-direction’ of 335 degrees at a 45 degree altitude is therefore (-0.4226, 0.9063, -0.7071), which is the default here too.

    Declaration

    Objective-C

    - (void)setIlluminationDirection:(MSFMapVec *)direction;

    Swift

    func setIlluminationDirection(_ direction: MSFMapVec!)

  • Returns wheter the illumination direction should change with the map rotation.

    Declaration

    Objective-C

    - (BOOL)getIlluminationMapRotationEnabled;

    Swift

    func getIlluminationMapRotationEnabled() -> Bool

    Return Value

    enabled

  • Sets wheter the illumination direction should change with the map rotation.

    Declaration

    Objective-C

    - (void)setIlluminationMapRotationEnabled:(BOOL)enabled;

    Swift

    func setIlluminationMapRotationEnabled(_ enabled: Bool)

    Parameters

    enabled

    whether to enable or not.

  • Returns the normal vector tile should be exagerated based on the zoom level.

    Declaration

    Objective-C

    - (BOOL)getExagerateHeightScaleEnabled;

    Swift

    func getExagerateHeightScaleEnabled() -> Bool

    Return Value

    enabled

  • Sets wheter the normal vector tile should be exagerated based on the zoom level.

    Declaration

    Objective-C

    - (void)setExagerateHeightScaleEnabled:(BOOL)enabled;

    Swift

    func setExagerateHeightScaleEnabled(_ enabled: Bool)

    Parameters

    enabled

    whether to enable or not.

  • Returns whether the legacy (pre-MapLibre-parity) height scale formula is used.

    Declaration

    Objective-C

    - (BOOL)isLegacyHeightScaleEnabled;

    Swift

    func isLegacyHeightScaleEnabled() -> Bool

    Return Value

    True if the legacy formula is used. Default is false.

  • Sets whether to use the legacy (pre-MapLibre-parity) height scale formula, in which the relief is damped by the absolute zoom level and therefore flattens as the camera zooms in. The default formula instead follows MapLibre: the true slope from zoom 15 up, boosted below it. Styles tuned against the legacy formula should enable this and also call setHeightScale(0.09f), which was the old default height scale.

    Declaration

    Objective-C

    - (void)setLegacyHeightScaleEnabled:(BOOL)enabled;

    Swift

    func setLegacyHeightScaleEnabled(_ enabled: Bool)

    Parameters

    enabled

    Whether to use the legacy formula.

  • Returns the hillshade rendering method.

    Declaration

    Objective-C

    - (enum MSFHillshadeMethod)getHillshadeMethod;

    Swift

    func getHillshadeMethod() -> MSFHillshadeMethod

    Return Value

    The hillshade method. Default is IGOR.

  • Sets the hillshade rendering method.

    Declaration

    Objective-C

    - (void)setHillshadeMethod:(enum MSFHillshadeMethod)method;

    Swift

    func setHillshadeMethod(_ method: MSFHillshadeMethod)

    Parameters

    method

    The hillshade method to use.

  • Returns whether the normal map encodes absolute elevation (so a custom normal-map lighting shader can call getElevation()).

    Declaration

    Objective-C

    - (BOOL)isElevationEncodingEnabled;

    Swift

    func isElevationEncodingEnabled() -> Bool

    Return Value

    True if elevation encoding is enabled. Default is false.

  • Sets whether the normal map encodes absolute elevation in addition to the surface normal. Required for a custom normal-map lighting shader that reads getElevation()/getMapZoom() (e.g. to draw its own per-zoom contour lines). Enabling contour lines turns this on implicitly.

    Declaration

    Objective-C

    - (void)setElevationEncodingEnabled:(BOOL)enabled;

    Swift

    func setElevationEncodingEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to encode elevation into the normal map.

  • Returns whether GPU contour lines are drawn over the hillshade.

    Declaration

    Objective-C

    - (BOOL)isContourEnabled;

    Swift

    func isContourEnabled() -> Bool

    Return Value

    True if contour lines are enabled. Default is false.

  • Sets whether to draw anti-aliased contour lines over the hillshade, computed in the shader from the elevation data. Enabling this makes the normal map encode absolute elevation (which is also available to a custom normal-map lighting shader). Note: this class is experimental.

    Declaration

    Objective-C

    - (void)setContourEnabled:(BOOL)enabled;

    Swift

    func setContourEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to draw contour lines.

  • Returns the spacing between contour lines in meters.

    Declaration

    Objective-C

    - (float)getContourInterval;

    Swift

    func getContourInterval() -> Float

    Return Value

    The contour interval in meters. Default is 100.

  • Sets the spacing between contour lines in meters.

    Declaration

    Objective-C

    - (void)setContourInterval:(float)interval;

    Swift

    func setContourInterval(_ interval: Float)

    Parameters

    interval

    The contour interval in meters.

  • Returns the contour line color.

    Declaration

    Objective-C

    - (MSFColor *)getContourColor;

    Swift

    func getContourColor() -> MSFColor!

    Return Value

    The contour line color.

  • Sets the contour line color.

    Declaration

    Objective-C

    - (void)setContourColor:(MSFColor *)color;

    Swift

    func setContourColor(_ color: MSFColor!)

    Parameters

    color

    The contour line color.

  • Returns the contour line half-width in screen pixels.

    Declaration

    Objective-C

    - (float)getContourWidth;

    Swift

    func getContourWidth() -> Float

    Return Value

    The contour line width. Default is 0.75.

  • Sets the contour line half-width in screen pixels.

    Declaration

    Objective-C

    - (void)setContourWidth:(float)width;

    Swift

    func setContourWidth(_ width: Float)

    Parameters

    width

    The contour line width in pixels.

  • Returns whether the layer may shade the 3D terrain’s own elevation texture instead of loading a DEM tile set of its own.

    Declaration

    Objective-C

    - (BOOL)isTerrainPaintEnabled;

    Swift

    func isTerrainPaintEnabled() -> Bool

    Return Value

    True if terrain paint mode is allowed. Default is true.

  • Sets whether the layer may shade the shared 3D terrain elevation texture instead of loading, decoding and uploading a DEM tile set of its own. It applies only when the map renders 3D terrain with draped fills FROM THE SAME data source, and not while the built-in contour lines are enabled: the layer then draws one quad per terrain tile, at its own place in the layer order, and fetches nothing. In any other configuration the layer keeps its normal map tile set. Disable it to compare the two paths. Note that the shading is then computed from the TERRAIN’s elevation grid, so it does not follow this layer’s own zoom level bias, and it resolves the relief slightly differently from a magnified normal map raster.

    Declaration

    Objective-C

    - (void)setTerrainPaintEnabled:(BOOL)enabled;

    Swift

    func setTerrainPaintEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to allow terrain paint mode.

  • Returns whether the terrain paint shades from the elevation source’s own maximum zoom.

    Declaration

    Objective-C

    - (BOOL)isTerrainPaintFullDetailEnabled;

    Swift

    func isTerrainPaintFullDetailEnabled() -> Bool

    Return Value

    True if full DEM detail is used. Default is true.

  • Sets whether the terrain paint shades from the elevation source’s own maximum zoom instead of the coarser level the terrain MESH needs (one texel per half surface cell, which costs two zoom levels of relief - at high zoom, all of it). Shading is per fragment and resolves what the mesh cannot, so this is on by default; turning it off gives the terrain’s own elevation textures back and is measurably faster.

    Declaration

    Objective-C

    - (void)setTerrainPaintFullDetailEnabled:(BOOL)enabled;

    Swift

    func setTerrainPaintFullDetailEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to shade from the DEM’s own maximum zoom.

  • Undocumented

    Declaration

    Objective-C

    -(double)getElevation: (MSFMapPos*)pos;

    Swift

    func getElevation(_ pos: MSFMapPos!) -> Double

  • Undocumented

    Declaration

    Objective-C

    -(MSFDoubleVector*)getElevations: (MSFMapPosVector*)poses;

    Swift

    func getElevations(_ poses: MSFMapPosVector!) -> MSFDoubleVector!

  • Undocumented

    Declaration

    Objective-C

    -(void)dealloc;

    Swift

    func dealloc()