MGLLight

 

@interface MGLLight : NSObject

An MGLLight object represents the light source for extruded geometries in MGLStyle.

Example

let light = MGLLight()
let position = MGLSphericalPosition(radial: 5, azimuthal: 180, polar: 80)
light.position = NSExpression(forConstantValue: NSValue(mglSphericalPosition: position))
light.anchor = NSExpression(forConstantValue: "map")
mapView.style?.light = light

See the Adjust light of 3D buildings to learn how to create and modify the light source for 3D geometries.

  • Whether extruded geometries are lit relative to the map or viewport.

    The default value of this property is an expression that evaluates to viewport.

    You can set this property to an expression containing any of the following:

    • Constant MGLAnchor values
    • Any of the following constant string values:
      • map: The position of the light source is aligned to the rotation of the map.
      • viewport: The position of the light source is aligned to the rotation of the viewport.
    • Predefined functions, including mathematical and string operators
    • Conditional expressions
    • Variable assignments and references to assigned variables
    • Step functions applied to the $zoomLevel variable

    This property does not support applying interpolation functions to the $zoomLevel variable or applying interpolation or step functions to feature attributes.

    This property corresponds to the anchor light property in the Mapbox Style Specification.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    NSExpression *_Nonnull anchor;

    Swift

    var anchor: NSExpression { get set }
    View Source on GitHub

  • Position of the MGLLight source relative to lit (extruded) geometries, in a MGLSphericalPosition struct [radial coordinate, azimuthal angle, polar angle] where radial indicates the distance from the center of the base of an object to its light, azimuthal indicates the position of the light relative to 0° (0° when MGLLight.anchor is set to MGLLightAnchorViewport corresponds to the top of the viewport, or 0° when MGLLight.anchor is set to MGLLightAnchorMap corresponds to due north, and degrees proceed clockwise), and polar indicates the height of the light (from 0°, directly above, to 180°, directly below).

    The default value of this property is an expression that evaluates to an MGLSphericalPosition struct set to 1.15 radial, 210 azimuthal and 30 polar.

    You can set this property to an expression containing any of the following:

    • Constant MGLSphericalPosition values
    • Predefined functions, including mathematical and string operators
    • Conditional expressions
    • Variable assignments and references to assigned variables
    • Interpolation and step functions applied to the $zoomLevel variable

    This property does not support applying interpolation or step functions to feature attributes.

    This property corresponds to the position light property in the Mapbox Style Specification.

    See the Adjust light of 3D buildings example to learn how to create and modify the position of value of an MGLLight object for 3D geometries.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    NSExpression *_Nonnull position;

    Swift

    var position: NSExpression { get set }
    View Source on GitHub

  • The transition affecting any changes to this layer’s position property.

    This property corresponds to the position-transition property in the style JSON file format.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    MGLTransition positionTransition;

    Swift

    var positionTransition: MGLTransition { get set }
    View Source on GitHub

  • Color tint for lighting extruded geometries.

    The default value of this property is an expression that evaluates to NSColor.whiteColor.

    You can set this property to an expression containing any of the following:

    • Constant NSColor values
    • Predefined functions, including mathematical and string operators
    • Conditional expressions
    • Variable assignments and references to assigned variables
    • Interpolation and step functions applied to the $zoomLevel variable

    This property does not support applying interpolation or step functions to feature attributes.

    This property corresponds to the color light property in the Mapbox Style Specification.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    NSExpression *_Nonnull color;

    Swift

    var color: NSExpression { get set }
    View Source on GitHub

  • The transition affecting any changes to this layer’s color property.

    This property corresponds to the color-transition property in the style JSON file format.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    MGLTransition colorTransition;

    Swift

    var colorTransition: MGLTransition { get set }
    View Source on GitHub

  • Intensity of lighting (on a scale from 0 to 1). Higher numbers will present as more extreme contrast.

    The default value of this property is an expression that evaluates to the float 0.5.

    You can set this property to an expression containing any of the following:

    • Constant numeric values between 0 and 1 inclusive
    • Predefined functions, including mathematical and string operators
    • Conditional expressions
    • Variable assignments and references to assigned variables
    • Interpolation and step functions applied to the $zoomLevel variable

    This property does not support applying interpolation or step functions to feature attributes.

    This property corresponds to the intensity light property in the Mapbox Style Specification.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    NSExpression *_Nonnull intensity;

    Swift

    var intensity: NSExpression { get set }
    View Source on GitHub

  • The transition affecting any changes to this layer’s intensity property.

    This property corresponds to the intensity-transition property in the style JSON file format.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
    MGLTransition intensityTransition;

    Swift

    var intensityTransition: MGLTransition { get set }
    View Source on GitHub