Package com.massifmaps.components

Class LightOptions

java.lang.Object
com.massifmaps.components.LightOptions
public class LightOptions extends Object
Directional light (sun) configuration, attached to the map via Options::setLightOptions.
The sun direction drives the sky shader, terrain surface lighting and shadows.
Note: this class is experimental and may change or even be removed in future SDK versions.

  • Constructor Summary

    Constructors
    Constructor
    Description
    LightOptions()
    Constructs a LightOptions object with default values.

  • Method Summary

    Modifier and Type
    Method
    Description
    Color
    getAmbientColor()
    Returns the ambient light color.
    float
    getAmbientIntensity()
    Returns the ambient light intensity.
    LightStopVector
    getDayCycleLightStops()
    Returns the day-cycle light curve - the "formula" an hour is turned into a look by.
    LightStopVector
    getDayCycleRisingLightStops()
    Returns the curve used while the sun is RISING, if the app set one.
    float
    getShadowBias()
    Returns the shadow depth bias scale.
    int
    getShadowCascades()
    Returns the number of shadow cascades.
    int
    getShadowCasterMargin()
    Returns the shadow caster margin in tiles.
    float
    getShadowDistance()
    Returns the shadow distance.
    int
    getShadowMapSize()
    Returns the shadow map resolution.
    float
    getShadowNormalOffset()
    Returns the shadow normal offset.
    float
    getShadowSoftness()
    Returns the shadow softness.
    float
    getShadowStrength()
    Returns the shadow strength.
    float
    getSunAltitude()
    Returns the sun altitude in degrees above the horizon.
    float
    getSunAzimuth()
    Returns the sun azimuth in degrees.
    Color
    getSunColor()
    Returns the sun (directional light) color.
    float
    getSunIntensity()
    Returns the sun light intensity.
    boolean
    isDayCycleLightsEnabled()
    Returns whether the sun's COLOURS follow its position.
    boolean
    isSunIntensityStated()
    Returns whether anything has SET the sun intensity, as opposed to leaving it at its
    default.
    boolean
    isSunOverridingStyle()
    Returns whether this sun overrides the one a style states.
    boolean
    isTerrainLightingEnabled()
    Returns whether the sun lights the 3D terrain surface.
    void
    setAmbientColor(Color color)
    Sets the ambient light color - the tint of the light reaching surfaces that face away
    from the sun, i.e.
    void
    setAmbientIntensity(float intensity)
    Sets the ambient light intensity, the amount of light reaching surfaces that face
    away from the sun.
    void
    setDayCycleLightsEnabled(boolean enabled)
    Sets whether the light COLOURS follow the sun's position instead of being stated.

    A map that moves its sun with the clock wants the light to change with it: warm and low
    at dawn, white overhead, orange against a blue sky at dusk, and a dim blue at night.
    void
    setDayCycleLightStops(LightStopVector stops)
    Sets the day-cycle light curve, replacing the built-in one.

    The list IS the formula: every colour on the map is derived from the light it returns -
    the grade a 2D surface takes, the sun and ambient a building and the terrain are lit
    with, and the brightness a style ramps its labels over - so one list changes the whole
    palette at every hour, in 2D and in 3D, with no second theme and no re-decode.

    Stops are read in the order given and should be sorted by sun height; below the first and
    above the last the curve holds, and between two it interpolates in linear colour space.
    Pass an empty list to go back to the built-in curve, which is MapBox Standard's own.

    Only used while DayCycleLightsEnabled is on.
    void
    setDayCycleRisingLightStops(LightStopVector stops)
    Sets a separate curve for a RISING sun, so dawn need not look like dusk.

    Nothing but the direction of travel distinguishes the two at the same sun height, and
    MapBox states them as different lights - dawn warm and bright, dusk cold.
    void
    setShadowBias(float bias)
    Scales the shadow depth bias: the depth slack that keeps a lit surface from shadowing
    itself.
    void
    setShadowCascades(int cascades)
    Sets how many shadow map cascades are rendered (1 to 4).
    void
    setShadowCasterMargin(int margin)
    Sets how many tiles wide the ring of extra shadow casters around the visible ones is.
    A mountain off screen still casts its shadow into the view, and without the ring that
    shadow disappears as you zoom in and the mountain leaves the visible set.

    The ring's REACH is not this value: it is the distance a shadow can be thrown, the
    relief over the tangent of the sun altitude.
    void
    setShadowDistance(float distance)
    Sets how far shadows reach from the camera, in multiples of the camera-to-focus
    distance - the same unit FogOptions uses for its range, and mapbox's shadow model.
    void
    setShadowMapSize(int size)
    Sets the shadow map resolution in pixels, per cascade.
    void
    setShadowNormalOffset(float offset)
    Sets how far a receiving surface is pushed along its own normal before it looks itself
    up in the shadow map, in shadow-map texels.
    void
    setShadowSoftness(float softness)
    Sets the shadow edge softness, as a radius in shadow-map texels.
    void
    setShadowStrength(float strength)
    Sets how strongly the sun's shadows darken the terrain.
    void
    setSunAltitude(float altitude)
    Sets the sun altitude in degrees above the horizon (0 = at the horizon, 90 = zenith).
    Negative values put the sun below the horizon (night).
    void
    setSunAzimuth(float azimuth)
    Sets the sun azimuth in degrees, measured clockwise from north (0 = north, 90 = east).
    The classic cartographic hillshade light comes from the north-west, which is the default.
    void
    setSunColor(Color color)
    Sets the sun (directional light) color.
    void
    setSunIntensity(float intensity)
    Sets the sun light intensity, a multiplier on the directional contribution.
    void
    setSunOverridingStyle(boolean overriding)
    Sets whether this sun overrides the one a style states.

    A style may state its own sun - a converted MapBox style does, one direction per light
    preset - and by default that is what lights the map, so it looks as its source does with
    no application code at all.
    void
    setSunPositionFromTime(int year, int month, int day, int hour, int minute, double latitude, double longitude)
    Sets the sun position from a date, a time and a location, using the standard
    solar position algorithm.
    void
    setTerrainLightingEnabled(boolean enabled)
    Sets whether the sun lights the 3D terrain surface.

    Methods inherited from class java.lang.Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • LightOptions

      public LightOptions()
      Constructs a LightOptions object with default values.

  • Method Details

    • getSunAzimuth

      public float getSunAzimuth()
      Returns the sun azimuth in degrees.
      Returns:
      The sun azimuth in degrees, clockwise from north. The default is 315 (north-west).

    • setSunAzimuth

      public void setSunAzimuth(float azimuth)
      Sets the sun azimuth in degrees, measured clockwise from north (0 = north, 90 = east).
      The classic cartographic hillshade light comes from the north-west, which is the default.
      Parameters:
      azimuth - The new sun azimuth in degrees.

    • getSunAltitude

      public float getSunAltitude()
      Returns the sun altitude in degrees above the horizon.
      Returns:
      The sun altitude in degrees. The default is 45.

    • setSunAltitude

      public void setSunAltitude(float altitude)
      Sets the sun altitude in degrees above the horizon (0 = at the horizon, 90 = zenith).
      Negative values put the sun below the horizon (night).
      Parameters:
      altitude - The new sun altitude in degrees (clamped to -90..90).

    • setSunPositionFromTime

      public void setSunPositionFromTime(int year, int month, int day, int hour, int minute, double latitude, double longitude)
      Sets the sun position from a date, a time and a location, using the standard
      solar position algorithm. This is a convenience wrapper that computes and stores
      the azimuth and the altitude; reading them back returns the computed values.
      Parameters:
      year - The year (for example 2026).
      month - The month, 1..12.
      day - The day of the month, 1..31.
      hour - The hour in UTC, 0..23.
      minute - The minute, 0..59.
      latitude - The observer latitude in degrees.
      longitude - The observer longitude in degrees.

    • getSunColor

      public Color getSunColor()
      Returns the sun (directional light) color.
      Returns:
      The sun color. The default is white.

    • setSunColor

      public void setSunColor(Color color)
      Sets the sun (directional light) color.
      Parameters:
      color - The new sun color.

    • getSunIntensity

      public float getSunIntensity()
      Returns the sun light intensity.
      Returns:
      The sun intensity. The default is 1.

    • setSunIntensity

      public void setSunIntensity(float intensity)
      Sets the sun light intensity, a multiplier on the directional contribution.
      Parameters:
      intensity - The new sun intensity (clamped to 0..8).

    • getAmbientIntensity

      public float getAmbientIntensity()
      Returns the ambient light intensity.
      Returns:
      The ambient intensity. The default is 0.35.

    • setAmbientIntensity

      public void setAmbientIntensity(float intensity)
      Sets the ambient light intensity, the amount of light reaching surfaces that face
      away from the sun. This is also the brightness floor inside shadows.
      Parameters:
      intensity - The new ambient intensity (clamped to 0..1).

    • getAmbientColor

      public Color getAmbientColor()
      Returns the ambient light color.
      Returns:
      The ambient color. The default is white.

    • setAmbientColor

      public void setAmbientColor(Color color)
      Sets the ambient light color - the tint of the light reaching surfaces that face away
      from the sun, i.e. the colour of everything in shadow. White keeps the neutral grey
      shading; a cool blue is what makes a dusk or night scene read as lit by the sky rather
      than simply darker. Applies to the terrain surface and to 3D buildings alike.
      Parameters:
      color - The new ambient color.

    • isSunIntensityStated

      public boolean isSunIntensityStated()
      Returns whether anything has SET the sun intensity, as opposed to leaving it at its
      default. 3D extrusions follow a stated sun; against the default they keep their own,
      which is what stops an unlit style's roofs summing past full light. Not part of the
      bound API - it exists for StyleEnvironment::resolveLighting.
      Returns:
      True if setSunIntensity has been called.

    • isSunOverridingStyle

      public boolean isSunOverridingStyle()
      Returns whether this sun overrides the one a style states.
      Returns:
      True if the application's sun wins over the style's. The default is false.

    • setSunOverridingStyle

      public void setSunOverridingStyle(boolean overriding)
      Sets whether this sun overrides the one a style states.

      A style may state its own sun - a converted MapBox style does, one direction per light
      preset - and by default that is what lights the map, so it looks as its source does with
      no application code at all. An application that moves the sun itself, a day/night cycle
      being the usual reason, sets this and its own azimuth and altitude win instead.

      Only the DIRECTION is affected. Intensities and colours merge as before.
      Parameters:
      overriding - True to let this object's sun win over the style's.

    • isDayCycleLightsEnabled

      public boolean isDayCycleLightsEnabled()
      Returns whether the sun's COLOURS follow its position.
      Returns:
      True if the light colours are derived from the sun's height. The default is false.

    • setDayCycleLightsEnabled

      public void setDayCycleLightsEnabled(boolean enabled)
      Sets whether the light COLOURS follow the sun's position instead of being stated.

      A map that moves its sun with the clock wants the light to change with it: warm and low
      at dawn, white overhead, orange against a blue sky at dusk, and a dim blue at night. With
      this on, the ambient and sun colours and their intensities are derived from the sun's own
      height, interpolated between the four light setups MapBox Standard ships - so an hour of
      12 renders as its `day` preset and 19 as its `dusk`, with everything in between.

      It replaces what the style and this object state for those four values; the DIRECTION is
      still whatever the sun position says. Off, nothing is derived and the values are taken as
      before.
      Parameters:
      enabled - True to derive the light colours from the sun's height.

    • getDayCycleLightStops

      public LightStopVector getDayCycleLightStops()
      Returns the day-cycle light curve - the "formula" an hour is turned into a look by.
      Returns:
      The stops, sorted by sun height. Empty means the built-in MapBox Standard curve.

    • setDayCycleLightStops

      public void setDayCycleLightStops(LightStopVector stops)
      Sets the day-cycle light curve, replacing the built-in one.

      The list IS the formula: every colour on the map is derived from the light it returns -
      the grade a 2D surface takes, the sun and ambient a building and the terrain are lit
      with, and the brightness a style ramps its labels over - so one list changes the whole
      palette at every hour, in 2D and in 3D, with no second theme and no re-decode.

      Stops are read in the order given and should be sorted by sun height; below the first and
      above the last the curve holds, and between two it interpolates in linear colour space.
      Pass an empty list to go back to the built-in curve, which is MapBox Standard's own.

      Only used while DayCycleLightsEnabled is on.
      Parameters:
      stops - The stops, sorted by sun height.

    • getDayCycleRisingLightStops

      public LightStopVector getDayCycleRisingLightStops()
      Returns the curve used while the sun is RISING, if the app set one.
      Returns:
      The rising stops. Empty means the setting curve is used for both.

    • setDayCycleRisingLightStops

      public void setDayCycleRisingLightStops(LightStopVector stops)
      Sets a separate curve for a RISING sun, so dawn need not look like dusk.

      Nothing but the direction of travel distinguishes the two at the same sun height, and
      MapBox states them as different lights - dawn warm and bright, dusk cold. Left empty, the
      one curve is used all day.
      Parameters:
      stops - The stops, sorted by sun height.

    • isTerrainLightingEnabled

      public boolean isTerrainLightingEnabled()
      Returns whether the sun lights the 3D terrain surface.
      Returns:
      True if terrain surface lighting is enabled. The default is false.

    • setTerrainLightingEnabled

      public void setTerrainLightingEnabled(boolean enabled)
      Sets whether the sun lights the 3D terrain surface. When enabled, the terrain
      surface shader computes the slope from the elevation data and shades the map with
      the current sun position - a live hillshade that follows the time of day, replacing
      the pre-baked hillshade raster layer for the common case. Requires 3D terrain with
      draping enabled (TerrainOptions.setDrapeFillsEnabled).
      Parameters:
      enabled - True to light the terrain surface with the sun.

    • getShadowStrength

      public float getShadowStrength()
      Returns the shadow strength.
      Returns:
      The shadow strength. The default is 1 (MapBox's own shadow-intensity default).

    • setShadowStrength

      public void setShadowStrength(float strength)
      Sets how strongly the sun's shadows darken the terrain. Shadows are cast by the terrain
      itself onto the terrain, so ridges shade valleys at low sun. Requires terrain lighting.

      NOT the depth drawn: a shadow only hides the direct light, so this is multiplied by the
      sun's share of the scene light, which is 0 once the sun is under the horizon. 1 is
      therefore the physically correct shadow - MapBox's - and not a maximum: values above it
      exaggerate, and are clamped where the two are resolved together.
      Parameters:
      strength - The new shadow strength (0 = off, 1 = physical; negatives clamped away).

    • getShadowMapSize

      public int getShadowMapSize()
      Returns the shadow map resolution.
      Returns:
      The shadow map size in pixels, per cascade. The default is 2048.

    • setShadowMapSize

      public void setShadowMapSize(int size)
      Sets the shadow map resolution in pixels, per cascade. Higher is sharper and costs
      more memory (size * size * 4 bytes per cascade) and fill rate. The cascades share one
      texture, so the size is clamped to what fits: 4096 / cascades.
      Parameters:
      size - The new shadow map size (clamped to 256..4096 / cascades).

    • getShadowCascades

      public int getShadowCascades()
      Returns the number of shadow cascades.
      Returns:
      The cascade count. The default is 2, as mapbox uses.

    • setShadowCascades

      public void setShadowCascades(int cascades)
      Sets how many shadow map cascades are rendered (1 to 4). One map has to cover
      everything visible, so at a tilt its texels are metres of ground and shadow edges
      become staircases. Cascades split the view distance: the near one covers a small
      region with the same number of texels, the far one - where a screen pixel is tens of
      metres of ground anyway - keeps the coarse cover. Each cascade costs one more caster
      pass and one more page of shadow texture.
      Parameters:
      cascades - The new cascade count (clamped to 1..4).

    • getShadowDistance

      public float getShadowDistance()
      Returns the shadow distance.
      Returns:
      The shadow distance, in multiples of the camera-to-focus distance. The default
      is 0 (use the built-in 4.5).

    • setShadowDistance

      public void setShadowDistance(float distance)
      Sets how far shadows reach from the camera, in multiples of the camera-to-focus
      distance - the same unit FogOptions uses for its range, and mapbox's shadow model. The
      shadow map has a fixed resolution, so the further shadows reach the coarser its texels;
      ground beyond the distance simply has no shadows, faded out over the last stretch. The
      unit is relative on purpose: the camera-to-focus distance follows the zoom, so one value
      holds from a city to a massif where a metric radius cannot. 0 uses the built-in 4.5.
      Parameters:
      distance - The new shadow distance, in multiples of the camera-to-focus distance.

    • getShadowCasterMargin

      public int getShadowCasterMargin()
      Returns the shadow caster margin in tiles.
      Returns:
      The caster margin. The default is 3.

    • setShadowCasterMargin

      public void setShadowCasterMargin(int margin)
      Sets how many tiles wide the ring of extra shadow casters around the visible ones is.
      A mountain off screen still casts its shadow into the view, and without the ring that
      shadow disappears as you zoom in and the mountain leaves the visible set.

      The ring's REACH is not this value: it is the distance a shadow can be thrown, the
      relief over the tangent of the sun altitude. This value sets the ring's RESOLUTION - the
      ring is generated at the coarsest tile zoom that still spans that throw in this many
      tiles, so the reach holds at every zoom while the count stays bounded. Raising it makes
      the distant casters finer and costs one caster draw per extra tile; 0 removes the ring.
      Parameters:
      margin - The new caster margin in tiles (clamped to 0..8).

    • getShadowSoftness

      public float getShadowSoftness()
      Returns the shadow softness.
      Returns:
      The PCF radius in shadow-map texels. The default is 1.

    • setShadowSoftness

      public void setShadowSoftness(float softness)
      Sets the shadow edge softness, as a radius in shadow-map texels. Larger values blur the
      shadow edges, which also hides the stair-stepping of a low-resolution shadow map.
      Parameters:
      softness - The new softness (clamped to 0..8).

    • getShadowBias

      public float getShadowBias()
      Returns the shadow depth bias scale.
      Returns:
      The scale on MapBox's shadow bias. The default is 1 (theirs unchanged).

    • setShadowBias

      public void setShadowBias(float bias)
      Scales the shadow depth bias: the depth slack that keeps a lit surface from shadowing
      itself. Too small gives acne (dark speckle on lit slopes), too large detaches shadows
      from what casts them.

      UNITLESS. The bias itself is MapBox's - a constant plus a term growing with the angle
      between the surface and the light, capped - in normalised light depth, so 1 is their
      shadow exactly and this only scales it.
      Parameters:
      bias - The new shadow bias scale.

    • getShadowNormalOffset

      public float getShadowNormalOffset()
      Returns the shadow normal offset.
      Returns:
      The normal offset in shadow-map texels. The default is 3.

    • setShadowNormalOffset

      public void setShadowNormalOffset(float offset)
      Sets how far a receiving surface is pushed along its own normal before it looks itself
      up in the shadow map, in shadow-map texels. This is what keeps a wall from shadowing
      itself: the sample moves sideways instead of the depth being lifted, so the shadow stays
      attached to the foot of the building that casts it, where a depth bias large enough to
      clear the same acne detaches it. Applies to 3D extrusions; the terrain surface takes its
      normal per fragment and is unaffected. 0 disables it.
      Parameters:
      offset - The new normal offset in shadow-map texels (clamped to 0..16).