MSFSkyOptions

Objective-C


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

Swift

class MSFSkyOptions : NSObject

Shader-based sky configuration, attached to the map via Options::setSkyOptions.

The sky is drawn as a single full-screen pass before everything else, so it costs one quad regardless of the camera. Type picks what that pass draws: a physical atmosphere (the default) or the older two-colour gradient. Either way the sun direction comes from Options::getLightOptions and the fog comes from Options::getFogOptions, so the sky is hazed by exactly what the ground is hazed by.

The whole appearance can be replaced with setShaderSource. The supplied GLSL must define

vec4 skyColor(vec3 rayDir);

where rayDir is the normalised world-space view ray for the fragment (x east, y north, z up), and the result is the non-premultiplied sky colour. These are available to it:

uniform vec3  u_sunDir;        // unit vector towards the sun, world space
uniform vec4  u_sunColor;      // sun colour, rgba 0..1
uniform vec4  u_skyColor;      // configured sky colour (zenith), rgba 0..1
uniform vec4  u_horizonColor;  // configured horizon colour, rgba 0..1
uniform vec4  u_groundColor;   // configured colour below the horizon, rgba 0..1
uniform float u_horizonBlend;  // gradient width in radians
uniform float u_sunIntensity;  // LightOptions sun intensity
uniform float u_sunDisc;       // 1 when the sun disc is enabled
uniform vec4  u_atmosphere;    // sun intensity, luminance, unused, unused
uniform vec4  u_atmosphereColor; // Rayleigh tint, a = strength
uniform vec4  u_haloColor;     // Mie tint, a = strength
uniform float u_starIntensity; // FogOptions star intensity
uniform float u_time;          // seconds since the map view was created
uniform float u_zoom;          // current fractional map zoom
uniform float u_cameraHeight;  // camera height above the map plane, in metres
uniform vec2  u_resolution;    // viewport size in pixels

plus the fog block documented on FogOptions::setShaderSource. Redeclaring any of them is a compile error, and the renderer then falls back to the built-in sky.

Note: this class is experimental and may change or even be removed in future SDK versions.

  • Constructs a SkyOptions object with default values.

    Declaration

    Objective-C

    - (id)init;

    Swift

    init!()

  • Returns whether the shader sky is enabled.

    Declaration

    Objective-C

    - (BOOL)isEnabled;

    Swift

    func isEnabled() -> Bool

    Return Value

    True if the shader sky is drawn. The default is true.

  • Enables or disables the shader sky. When disabled, the legacy sky bitmap band (Options::setSkyColor / the style sky bitmap) is drawn instead.

    Declaration

    Objective-C

    - (void)setEnabled:(BOOL)enabled;

    Swift

    func setEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to draw the shader sky.

  • Returns what the sky pass draws.

    Declaration

    Objective-C

    - (enum MSFSkyType)getType;

    Swift

    func getType() -> MSFSkyType

    Return Value

    The sky type. The default is SKY_TYPE_ATMOSPHERE.

  • Sets what the sky pass draws - a physical atmosphere or the two-colour gradient. SKY_TYPE_GRADIENT is what the SDK drew before the atmosphere existed and is the one to pick for a flat or stylised sky; it ignores every Atmosphere* property. Style property: “sky-type” (“gradient” or “atmosphere”).

    Declaration

    Objective-C

    - (void)setType:(enum MSFSkyType)type;

    Swift

    func setType(_ type: MSFSkyType)

    Parameters

    type

    The new sky type.

  • Returns how finely the atmosphere is integrated.

    Declaration

    Objective-C

    - (enum MSFSkyQuality)getQuality;

    Swift

    func getQuality() -> MSFSkyQuality

    Return Value

    The quality. The default is SKY_QUALITY_MEDIUM.

  • Sets how finely the atmosphere is integrated. The cost is per fragment of visible sky, so a low-tilt camera that fills the screen with sky is what this pays for. Ignored by SKY_TYPE_GRADIENT.

    Declaration

    Objective-C

    - (void)setQuality:(enum MSFSkyQuality)quality;

    Swift

    func setQuality(_ quality: MSFSkyQuality)

    Parameters

    quality

    The new quality.

  • Returns the brightness of the sun driving the atmosphere.

    Declaration

    Objective-C

    - (float)getAtmosphereSunIntensity;

    Swift

    func getAtmosphereSunIntensity() -> Float

    Return Value

    The sun intensity. The default is 10.

  • Sets how bright the sun that lights the atmosphere is - Mapbox sky-atmosphere-sun-intensity. This is the scattering model’s own sun, not LightOptions’ ground light; raising it brightens the whole sky rather than only the disc. Style property: “sky-atmosphere-sun-intensity”.

    Declaration

    Objective-C

    - (void)setAtmosphereSunIntensity:(float)intensity;

    Swift

    func setAtmosphereSunIntensity(_ intensity: Float)

    Parameters

    intensity

    The new sun intensity (clamped to 0 and above).

  • Returns the tint applied to Rayleigh scattering.

    Declaration

    Objective-C

    - (MSFColor *)getAtmosphereColor;

    Swift

    func getAtmosphereColor() -> MSFColor!

    Return Value

    The atmosphere color. The default is opaque white, i.e. no tint.

  • Sets the tint of the Rayleigh term - the blue of the sky - as Mapbox sky-atmosphere-color. The alpha channel scales how much of it there is, so a lower alpha thins the atmosphere. Style property: “sky-atmosphere-color”.

    Declaration

    Objective-C

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

    Swift

    func setAtmosphereColor(_ color: MSFColor!)

    Parameters

    color

    The new atmosphere color.

  • Returns the tint applied to Mie scattering.

    Declaration

    Objective-C

    - (MSFColor *)getHaloColor;

    Swift

    func getHaloColor() -> MSFColor!

    Return Value

    The halo color. The default is opaque white, i.e. no tint.

  • Sets the tint of the Mie term - the halo around the sun and the whiteness near the horizon - as Mapbox sky-atmosphere-halo-color. The alpha channel scales its strength. Style property: “sky-atmosphere-halo-color”.

    Declaration

    Objective-C

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

    Swift

    func setHaloColor(_ color: MSFColor!)

    Parameters

    color

    The new halo color.

  • Returns the exposure applied to the scattered light.

    Declaration

    Objective-C

    - (float)getAtmosphereLuminance;

    Swift

    func getAtmosphereLuminance() -> Float

    Return Value

    The luminance. The default is 1.

  • Sets the exposure the scattered light is tonemapped with. Lower values brighten the sky, which is what a night or a heavily tinted atmosphere needs to stay readable. Style property: “sky-atmosphere-luminance”.

    Declaration

    Objective-C

    - (void)setAtmosphereLuminance:(float)luminance;

    Swift

    func setAtmosphereLuminance(_ luminance: Float)

    Parameters

    luminance

    The new luminance (clamped to 0.01 and above).

  • Returns the zenith sky color.

    Declaration

    Objective-C

    - (MSFColor *)getSkyColor;

    Swift

    func getSkyColor() -> MSFColor!

    Return Value

    The sky color. The default is a light blue.

  • Sets the zenith sky color, used by the built-in shader at the top of the sky.

    Declaration

    Objective-C

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

    Swift

    func setSkyColor(_ color: MSFColor!)

    Parameters

    color

    The new sky color.

  • Returns the horizon color.

    Declaration

    Objective-C

    - (MSFColor *)getHorizonColor;

    Swift

    func getHorizonColor() -> MSFColor!

    Return Value

    The horizon color. The default is a pale blue-white.

  • Sets the horizon color, used by the built-in shader at the horizon line.

    Declaration

    Objective-C

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

    Swift

    func setHorizonColor(_ color: MSFColor!)

    Parameters

    color

    The new horizon color.

  • Returns the ground color.

    Declaration

    Objective-C

    - (MSFColor *)getGroundColor;

    Swift

    func getGroundColor() -> MSFColor!

    Return Value

    The color drawn below the horizon. The default is the horizon color.

  • Sets the color drawn below the horizon. The map normally covers that part of the screen, so this only shows in the wedge between the far edge of the drawn map and the mathematical horizon - it should stay close to the horizon color, which is the default. Setting it transparent leaves the clear color there.

    Declaration

    Objective-C

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

    Swift

    func setGroundColor(_ color: MSFColor!)

    Parameters

    color

    The new ground color.

  • Returns the angular blend width between the horizon color and the sky color.

    Declaration

    Objective-C

    - (float)getHorizonBlend;

    Swift

    func getHorizonBlend() -> Float

    Return Value

    The blend width in degrees. The default is 12.

  • Sets how far above the horizon, in degrees, the horizon color fades into the sky color.

    Declaration

    Objective-C

    - (void)setHorizonBlend:(float)degrees;

    Swift

    func setHorizonBlend(_ degrees: Float)

    Parameters

    degrees

    The new blend width in degrees (clamped to 0..90).

  • Returns whether the built-in shader draws a sun disc.

    Declaration

    Objective-C

    - (BOOL)isSunDiscEnabled;

    Swift

    func isSunDiscEnabled() -> Bool

    Return Value

    True if the sun disc is drawn. The default is true.

  • Enables or disables the sun disc and its glow in the built-in shader.

    Declaration

    Objective-C

    - (void)setSunDiscEnabled:(BOOL)enabled;

    Swift

    func setSunDiscEnabled(_ enabled: Bool)

    Parameters

    enabled

    True to draw the sun disc.

  • Returns the custom sky fragment shader source, or an empty string if the built-in shader is used.

    Declaration

    Objective-C

    - (NSString *)getShaderSource;

    Swift

    func getShaderSource() -> String!

    Return Value

    The custom shader source.

  • Sets a custom sky fragment shader. The source must define “vec4 skyColor(vec3 rayDir)” and may use the uniforms documented on this class. Pass an empty string to go back to the built-in shader. If the shader fails to compile, the built-in shader is used and the error is logged.

    Declaration

    Objective-C

    - (void)setShaderSource:(NSString *)shaderSource;

    Swift

    func setShaderSource(_ shaderSource: String!)

    Parameters

    shaderSource

    The GLSL source, or an empty string for the built-in shader.

  • Undocumented

    Declaration

    Objective-C

    -(void)dealloc;

    Swift

    func dealloc()