MSFLightOptions

Objective-C


@interface MSFLightOptions : NSObject {
  void *swigCPtr;
  BOOL swigCMemOwn;
}

Swift

class MSFLightOptions : NSObject

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.

  • Constructs a LightOptions object with default values.

    Declaration

    Objective-C

    - (id)init;

    Swift

    init!()

  • Returns the sun azimuth in degrees.

    Declaration

    Objective-C

    - (float)getSunAzimuth;

    Swift

    func getSunAzimuth() -> Float

    Return Value

    The sun azimuth in degrees, clockwise from north. The default is 315 (north-west).

  • Sets the sun azimuth in degrees, measured clockwise from north (0 = north, 90 = east).

    Declaration

    Objective-C

    - (void)setSunAzimuth:(float)azimuth;

    Swift

    func setSunAzimuth(_ azimuth: Float)

    Parameters

    azimuth

    The new sun azimuth in degrees.

  • Returns the sun altitude in degrees above the horizon.

    Declaration

    Objective-C

    - (float)getSunAltitude;

    Swift

    func getSunAltitude() -> Float

    Return Value

    The sun altitude in degrees. The default is 45.

  • Sets the sun altitude in degrees above the horizon (0 = at the horizon, 90 = zenith). Negative values put the sun below the horizon (night).

    Declaration

    Objective-C

    - (void)setSunAltitude:(float)altitude;

    Swift

    func setSunAltitude(_ altitude: Float)

    Parameters

    altitude

    The new sun altitude in degrees (clamped to -90..90).

  • Sets the sun position from a date, a time and a location, using the standard solar position algorithm; stores the computed azimuth and altitude.

    Declaration

    Objective-C

    - (void)setSunPositionFromTime:(int)year
                         month:(int)month
                           day:(int)day
                          hour:(int)hour
                        minute:(int)minute
                      latitude:(double)latitude
                     longitude:(double)longitude;

    Swift

    func setSunPositionFromTime(_ year: Int32, month: Int32, day: Int32, hour: Int32, minute: Int32, latitude: Double, longitude: Double)

    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.

  • Returns the sun (directional light) color.

    Declaration

    Objective-C

    - (MSFColor *)getSunColor;

    Swift

    func getSunColor() -> MSFColor!

    Return Value

    The sun color. The default is white.

  • Sets the sun (directional light) color.

    Declaration

    Objective-C

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

    Swift

    func setSunColor(_ color: MSFColor!)

    Parameters

    color

    The new sun color.

  • Returns the sun light intensity.

    Declaration

    Objective-C

    - (float)getSunIntensity;

    Swift

    func getSunIntensity() -> Float

    Return Value

    The sun intensity. The default is 1.

  • Sets the sun light intensity, a multiplier on the directional contribution.

    Declaration

    Objective-C

    - (void)setSunIntensity:(float)intensity;

    Swift

    func setSunIntensity(_ intensity: Float)

    Parameters

    intensity

    The new sun intensity (clamped to 0..8).

  • Returns the ambient light intensity.

    Declaration

    Objective-C

    - (float)getAmbientIntensity;

    Swift

    func getAmbientIntensity() -> Float

    Return Value

    The ambient intensity. The default is 1.

  • Sets the ambient light intensity: light reaching surfaces facing away from the sun, and the brightness floor inside shadows.

    Declaration

    Objective-C

    - (void)setAmbientIntensity:(float)intensity;

    Swift

    func setAmbientIntensity(_ intensity: Float)

    Parameters

    intensity

    The new ambient intensity (clamped to 0..1).

  • Returns the ambient light color.

    Declaration

    Objective-C

    - (MSFColor *)getAmbientColor;

    Swift

    func getAmbientColor() -> MSFColor!

    Return Value

    The ambient color. The default is white.

  • Sets the ambient light color: the tint of everything in shadow, on terrain and 3D buildings. White keeps neutral grey shading; a cool blue reads as sky-lit dusk or night.

    Declaration

    Objective-C

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

    Swift

    func setAmbientColor(_ color: MSFColor!)

    Parameters

    color

    The new ambient color.

  • Returns whether the sun intensity was set; 3D extrusions follow only a stated sun, so an unlit style’s roofs do not sum past full light. Not bound - for StyleEnvironment::resolveLighting.

    Declaration

    Objective-C

    - (BOOL)isSunIntensityStated;

    Swift

    func isSunIntensityStated() -> Bool

    Return Value

    True if setSunIntensity has been called.

  • Returns whether this sun overrides the one a style states.

    Declaration

    Objective-C

    - (BOOL)isSunOverridingStyle;

    Swift

    func isSunOverridingStyle() -> Bool

    Return Value

    True if the application’s sun wins over the style’s. The default is false.

  • Sets whether this sun’s direction overrides the one a style states (e.g. for an app-driven day/night cycle). Intensities and colours merge as before.

    Declaration

    Objective-C

    - (void)setSunOverridingStyle:(BOOL)overriding;

    Swift

    func setSunOverridingStyle(_ overriding: Bool)

    Parameters

    overriding

    True to let this object’s sun win over the style’s.

  • Returns whether the sun’s COLOURS follow its position.

    Declaration

    Objective-C

    - (BOOL)isDayCycleLightsEnabled;

    Swift

    func isDayCycleLightsEnabled() -> Bool

    Return Value

    True if the light colours are derived from the sun’s height. The default is false.

  • Sets whether the ambient and sun colours and intensities are derived from the sun’s height (the day-cycle curve), replacing what the style and this object state. The direction is unaffected.

    Declaration

    Objective-C

    - (void)setDayCycleLightsEnabled:(BOOL)enabled;

    Swift

    func setDayCycleLightsEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to derive the light colours from the sun’s height.

  • Returns the day-cycle light curve.

    Declaration

    Objective-C

    - (MSFLightStopVector *)getDayCycleLightStops;

    Swift

    func getDayCycleLightStops() -> MSFLightStopVector!

    Return Value

    The stops, sorted by sun height. Empty means the built-in MapBox Standard curve.

  • Sets the day-cycle light curve, from which every map colour at every hour derives. Clamped at the ends, interpolated in linear colour space between; empty restores the built-in (MapBox Standard) curve. Only used while DayCycleLightsEnabled is on.

    Declaration

    Objective-C

    - (void)setDayCycleLightStops:(MSFLightStopVector *)stops;

    Swift

    func setDayCycleLightStops(_ stops: MSFLightStopVector!)

    Parameters

    stops

    The stops, sorted by sun height.

  • Returns the curve used while the sun is RISING, if the app set one.

    Declaration

    Objective-C

    - (MSFLightStopVector *)getDayCycleRisingLightStops;

    Swift

    func getDayCycleRisingLightStops() -> MSFLightStopVector!

    Return Value

    The rising stops. Empty means the setting curve is used for both.

  • Sets a separate curve for a rising sun, so dawn need not look like dusk. Empty uses the one curve all day.

    Declaration

    Objective-C

    - (void)setDayCycleRisingLightStops:(MSFLightStopVector *)stops;

    Swift

    func setDayCycleRisingLightStops(_ stops: MSFLightStopVector!)

    Parameters

    stops

    The stops, sorted by sun height.

  • Returns whether the sun lights the 3D terrain surface, and whether shadows are drawn at all.

    Declaration

    Objective-C

    - (BOOL)isTerrainLightingEnabled;

    Swift

    func isTerrainLightingEnabled() -> Bool

    Return Value

    True if terrain surface lighting is enabled. The default is false.

  • Sets whether the sun lights the 3D terrain surface: a live hillshade following the sun. It also switches shadows on, with 3D terrain (needs draping) or on a map with none.

    Declaration

    Objective-C

    - (void)setTerrainLightingEnabled:(BOOL)enabled;

    Swift

    func setTerrainLightingEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to light the terrain surface with the sun.

  • Returns whether building shadows shrink with the buildings as the camera lies over.

    Declaration

    Objective-C

    - (BOOL)isShadowFollowsBuildingHeight;

    Swift

    func isShadowFollowsBuildingHeight() -> Bool

    Return Value

    True if the shadows follow the style’s building-height-view-scale. The default is false.

  • Sets whether building shadows shrink with the buildings between tilt 80 and 90, as the style’s building-height-view-scale lays them down. Off, the shadows keep the full height the buildings have, which reads true from straight above.

    Declaration

    Objective-C

    - (void)setShadowFollowsBuildingHeight:(BOOL)enabled;

    Swift

    func setShadowFollowsBuildingHeight(_ enabled: Bool)

    Parameters

    enabled

    True to let the shadows follow the drawn height.

  • Returns whether the terrain itself casts shadows.

    Declaration

    Objective-C

    - (BOOL)isTerrainShadowCastingEnabled;

    Swift

    func isTerrainShadowCastingEnabled() -> Bool

    Return Value

    True if the relief casts shadows. The default is true.

  • Sets whether the terrain itself casts shadows. Off, buildings and models still cast and the ground still receives, at a lower cost: for a flat or straight-down view, where the relief has no shadow to throw. A terrain with zero exaggeration never casts, whatever this says.

    Declaration

    Objective-C

    - (void)setTerrainShadowCastingEnabled:(BOOL)enabled;

    Swift

    func setTerrainShadowCastingEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to let the relief cast shadows.

  • Returns the shadow strength.

    Declaration

    Objective-C

    - (float)getShadowStrength;

    Swift

    func getShadowStrength() -> Float

    Return Value

    The shadow strength. The default is 1 (MapBox’s own shadow-intensity default).

  • Sets how strongly the sun’s shadows darken the terrain; requires terrain lighting. Scaled by the sun’s share of the light (0 below the horizon), so 1 is the physical (MapBox) shadow, not a maximum.

    Declaration

    Objective-C

    - (void)setShadowStrength:(float)strength;

    Swift

    func setShadowStrength(_ strength: Float)

    Parameters

    strength

    The new shadow strength (0 = off, 1 = physical; negatives clamped away).

  • Returns the shadow map resolution.

    Declaration

    Objective-C

    - (int)getShadowMapSize;

    Swift

    func getShadowMapSize() -> Int32

    Return Value

    The shadow map size in pixels, per cascade. The default is 2048.

  • Sets the shadow map resolution in pixels, per cascade; costs size * size * 4 bytes per cascade. The cascades share one texture, so the renderer also caps it at the max texture size / cascades.

    Declaration

    Objective-C

    - (void)setShadowMapSize:(int)size;

    Swift

    func setShadowMapSize(_ size: Int32)

    Parameters

    size

    The new shadow map size (clamped to 256..4096).

  • Returns the number of shadow cascades.

    Declaration

    Objective-C

    - (int)getShadowCascades;

    Swift

    func getShadowCascades() -> Int32

    Return Value

    The cascade count. The default is 2, as mapbox uses.

  • Sets how many shadow map cascades split the view distance, sharpening near shadows at a tilt. Each costs one more caster pass and one more shadow texture page.

    Declaration

    Objective-C

    - (void)setShadowCascades:(int)cascades;

    Swift

    func setShadowCascades(_ cascades: Int32)

    Parameters

    cascades

    The new cascade count (clamped to 1..4).

  • Returns the shadow distance.

    Declaration

    Objective-C

    - (float)getShadowDistance;

    Swift

    func getShadowDistance() -> Float

    Return Value

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

  • Sets how far shadows reach, in multiples of the camera-to-focus distance (as FogOptions ranges), so one value holds at every zoom. Further is coarser; beyond it shadows fade out. 0 uses 4.5.

    Declaration

    Objective-C

    - (void)setShadowDistance:(float)distance;

    Swift

    func setShadowDistance(_ distance: Float)

    Parameters

    distance

    The new shadow distance, in multiples of the camera-to-focus distance.

  • Returns the shadow caster margin in tiles.

    Declaration

    Objective-C

    - (int)getShadowCasterMargin;

    Swift

    func getShadowCasterMargin() -> Int32

    Return Value

    The caster margin. The default is 3.

  • Sets the resolution of the ring of off-screen shadow casters: its reach is the shadow throw, spanned in this many tiles. Higher is finer and costs one caster draw per tile; 0 removes the ring.

    Declaration

    Objective-C

    - (void)setShadowCasterMargin:(int)margin;

    Swift

    func setShadowCasterMargin(_ margin: Int32)

    Parameters

    margin

    The new caster margin in tiles (clamped to 0..8).

  • Returns the shadow softness.

    Declaration

    Objective-C

    - (float)getShadowSoftness;

    Swift

    func getShadowSoftness() -> Float

    Return Value

    The PCF radius in shadow-map texels. The default is 0.5.

  • Sets the shadow edge softness, as a PCF radius in shadow-map texels.

    Declaration

    Objective-C

    - (void)setShadowSoftness:(float)softness;

    Swift

    func setShadowSoftness(_ softness: Float)

    Parameters

    softness

    The new softness (clamped to 0..8).

  • Returns the shadow depth bias scale.

    Declaration

    Objective-C

    - (float)getShadowBias;

    Swift

    func getShadowBias() -> Float

    Return Value

    The scale on MapBox’s shadow bias. The default is 1 (theirs unchanged).

  • Scales MapBox’s shadow depth bias (unitless; 1 = theirs). Too small gives acne, too large detaches shadows from their casters.

    Declaration

    Objective-C

    - (void)setShadowBias:(float)bias;

    Swift

    func setShadowBias(_ bias: Float)

    Parameters

    bias

    The new shadow bias scale (clamped to 0..50).

  • Returns the shadow normal offset.

    Declaration

    Objective-C

    - (float)getShadowNormalOffset;

    Swift

    func getShadowNormalOffset() -> Float

    Return Value

    The normal offset in shadow-map texels. The default is 3.

  • Sets how far a receiver is pushed along its normal before the shadow lookup, which clears wall acne without detaching the shadow. 3D extrusions only; 0 disables it.

    Declaration

    Objective-C

    - (void)setShadowNormalOffset:(float)offset;

    Swift

    func setShadowNormalOffset(_ offset: Float)

    Parameters

    offset

    The new normal offset in shadow-map texels (clamped to 0..16).

  • Undocumented

    Declaration

    Objective-C

    -(void)dealloc;

    Swift

    func dealloc()