Merge branch 'release-ios-v3.5.0-android-v5.0.0' into boundsj-merge-release-branch

# Conflicts:
#	cmake/core-files.cmake
#	mapbox-gl-js
#	platform/android/CHANGELOG.md
#	platform/ios/CHANGELOG.md
#	platform/macos/CHANGELOG.md
#	platform/qt/bitrise-qt5.yml
#	src/mbgl/gl/attribute.hpp
#	src/mbgl/gl/context.cpp
#	src/mbgl/gl/program.hpp
#	src/mbgl/map/map.cpp
#	src/mbgl/programs/program.hpp
#	src/mbgl/renderer/painter.cpp

12 files changed, 76 insertions, 64 deletions

diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 92ce4c1594..86f8c46f53 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -240,30 +240,6 @@ whose names differ from the style specification are listed below:
 <% for (const type in renamedProperties) { -%>
 <% if (renamedProperties.hasOwnProperty(type)) { -%>
 
-### <%- camelize(type) %> style functions
-
-The runtime styling API introduces `MGLStyleFunction` to the <%- os %> SDK.
-[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction`.
-Individual style property documentation includes which subclasses of
-`MGLStyleFunction` are enabled for that property. You can use `MGLStyleValue`
-methods to create a `MGLStyleFunction`.
-
-In style specification | In the SDK                    | [MGLStyleValue valueWithInterpolationMode:...]
------------------------|-------------------------------|-------------
-`zoom function`        | `MGLCameraStyleFunction`      | `cameraStops:options:`
-`property function`    | `MGLSourceStyleFunction`      | `sourceStops:attributeName:options:`
-`zoom-and-property functions`| `MGLCompositeStyleFunction` | `compositeStops:attributeName:options:`
-
-Data-driven styling also introduces interpolation mode, which defines the
-relationship between style values and attributes or zoom levels.
-
-In style specification       | In the SDK
------------------------------|-----------
-`exponential`                | `MGLInterpolationModeExponential`
-`interval`                   | `MGLInterpolationModeInterval`
-`categorical`                | `MGLInterpolationModeCategorical`
-`identity`                   | `MGLInterpolationModeIdentity`
-
 ### <%- camelize(type) %> style layers
 
 In style JSON | In Objective-C | In Swift
@@ -280,10 +256,12 @@ In style JSON | In Objective-C | In Swift
 
 Each property representing a layout or paint attribute is set to an
 `MGLStyleValue` object, which is either an `MGLConstantStyleValue` object (for
-constant values) or an `MGLStyleFunction` object (for zoom level functions). The
+constant values) or an `MGLStyleFunction` object (for style functions). The
 style value object is a container for the raw value or function parameters that
 you want the attribute to be set to.
 
+### Constant style values
+
 In contrast to the JSON type that the style specification defines for each
 layout or paint property, the style value object often contains a more specific
 Foundation or Cocoa type. General rules for attribute types are listed below.
@@ -326,6 +304,39 @@ translation downward. This is the reverse of how `CGVector` is interpreted on
 iOS.
 
 <% } -%>
+### Style functions
+
+A _style function_ allows you to vary the value of a layout or paint attribute
+based on the zoom level, data provided by content sources, or both. For more
+information about style functions, see “[Using Style Functions at Runtime](using-style-functions-at-runtime.html)”.
+
+Each kind of style function is represented by a distinct class, but you
+typically create style functions as you create any other style value, using
+class methods on `MGLStyleValue`:
+
+In style specification     | SDK class                   | SDK factory method
+---------------------------|-----------------------------|-------------------
+zoom function              | `MGLCameraStyleFunction`    | `+[MGLStyleValue valueWithInterpolationMode:cameraStops:options:]`
+property function          | `MGLSourceStyleFunction`    | `+[MGLStyleValue valueWithInterpolationMode:sourceStops:attributeName:options:]`
+zoom-and-property function | `MGLCompositeStyleFunction` | `+[MGLStyleValue valueWithInterpolationMode:compositeStops:attributeName:options:]`
+
+The documentation for each individual style layer property indicates the kinds
+of style functions that are enabled for that property.
+
+When you create a style function, you specify an _interpolation mode_ and a
+series of _stops_. Each stop determines the effective value displayed at a
+particular zoom level (for camera functions) or the effective value on features
+with a particular attribute value in the content source (for source functions).
+The interpolation mode tells the SDK how to calculate the effective value
+between any two stops:
+
+In style specification       | In the SDK
+-----------------------------|-----------
+`exponential`                | `MGLInterpolationModeExponential`
+`interval`                   | `MGLInterpolationModeInterval`
+`categorical`                | `MGLInterpolationModeCategorical`
+`identity`                   | `MGLInterpolationModeIdentity`
+
 ## Filtering sources
 
 You can filter a shape or vector source by setting the
diff --git a/platform/darwin/docs/guides/Data-Driven Styling.md.ejs b/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs
index 820f71f594..bd477042c7 100644
--- a/platform/darwin/docs/guides/Data-Driven Styling.md.ejs
+++ b/platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs
@@ -10,46 +10,47 @@
   Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 -->
 
-# Data-Driven Styling
+# Using Style Functions at Runtime
 
-Mapbox’s data-driven styling features allow you to use data properties to style your maps. You can style map features automatically based on their individual attributes. 
+[Runtime Styling](runtime-styling.html) enables you to modify every aspect of the map’s appearance dynamically as a user interacts with your application. Much of the runtime styling API allows you to specify _style functions_ instead of constant values. A style function allows you to specify in advance how a layout or paint attribute will vary as the zoom level changes or how the appearance of individual features vary based on metadata provided by a content source.
 
-Vary POI icons, transit route line colors, city polygon opacity, and more based on any attribute in your data. Need to visualize hotel data by price? You can have your map’s point radii and colors change automatically with your data.
+Style functions spare you the inconvenience of manually calculating intermediate values between different zoom levels or creating a multitude of style layers to handle homogeneous features in the map content. For example, if your content source indicates the prices of hotels in an area, you can color-code the hotels by price, relying on a style function to smoothly interpolate among desired colors without having to specify the color for each exact price.
 
-![available bikes](img/data-driven-styling/citibikes.png) ![subway lines](img/data-driven-styling/polylineExample.png)
+_Data-driven styling_ specifically refers to the use of style functions to vary the map’s appearance based on data in a content source.
+
+You can also specify style functions in a style JSON file, to be applied automatically when the map loads. See the [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-js/style-spec/#types-function) for details.
 
-# How to use Data-Driven Styling
-This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) to style a map based on attributes. For more information about how to work with GeoJSON data in our iOS SDK, please see our [working with GeoJSON data](working-with-geojson-data.html) guide.
+![available bikes](img/data-driven-styling/citibikes.png) ![subway lines](img/data-driven-styling/polylineExample.png)
 
-`MGLStyleFunction`
+This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) and data-driven styling to style a map based on attributes. For more information about how to work with GeoJSON data in our iOS SDK, please see our [working with GeoJSON data](working-with-geojson-data.html) guide.
 
-There are three subclasses of `MGLStyleFunction`:
+A style function is represented at runtime by the `MGLStyleFunction` class. There are three subclasses of `MGLStyleFunction`:
 
-* `MGLCameraStyleFunction` - For a style value that changes with zoom level. For example, you can make the radius of a circle increase according to zoom level. 
-* `MGLSourceStyleFunction` - For a style value that changes with the attributes of a feature. For example, you can adjust the radius of a circle based on the magnitude of an earthquake.
-* `MGLCompositeStyleFunction` - For a style value that changes with both zoom level and attribute values. For example, you can add a circle layer where each circle has a radius based on both zoom level and the magnitude of an earthquake.
+* `MGLCameraStyleFunction` is a style value that changes with zoom level. For example, you can make the radius of a circle increase according to zoom level.
+* `MGLSourceStyleFunction` is a style value that changes with the attributes of a feature. For example, you can adjust the radius of a circle based on the magnitude of an earthquake.
+* `MGLCompositeStyleFunction` is a style value that changes with both zoom level and attribute values. For example, you can add a circle layer where each circle has a radius based on both zoom level and the magnitude of an earthquake.
 
-The documentation for individual style properties will note which style functions are enabled for that property.
+The documentation for each individual style layer property notes which style functions are enabled for that property.
 
 ## Stops
 
 Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key.
 
 ```swift
-let stops = [0: MGLStyleValue(rawValue: UIColor.yellow),
-             2.5: MGLStyleValue(rawValue: UIColor.orange),
-             5: MGLStyleValue(rawValue: UIColor.red),
-             7.5: MGLStyleValue(rawValue: UIColor.blue),
-             10: MGLStyleValue(rawValue: UIColor.white)]
+let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow),
+             2.5: MGLStyleValue(rawValue: .orange),
+             5: MGLStyleValue(rawValue: .red),
+             7.5: MGLStyleValue(rawValue: .blue),
+             10: MGLStyleValue(rawValue: .white)]
 ```
 
-## Interpolation Mode
+## Interpolation mode
 
 The effect a key has on the style value is determined by the interpolation mode. There are four interpolation modes that can be used with a source style function: exponential, interval, categorical, and identity. You can also use exponential and interval interpolation modes with a camera style function.
 
 ### Linear
 
-`MGLInterpolationModelExponential` interpolates linearly or exponentially between style function stop values. By default, the `MGLStyleFunction` options parameter `MGLStyleFunctionOptionInterpolationBase` equals `1`, which represents linear interpolation, and doesn’t need to be included in the options dictionary.
+`MGLInterpolationModeExponential` interpolates linearly or exponentially between style function stop values. By default, the `MGLStyleFunction` options parameter `MGLStyleFunctionOptionInterpolationBase` equals `1`, which represents linear interpolation and doesn’t need to be included in the options dictionary.
 
 The stops dictionary below, for example, shows colors that continuously shift from yellow to orange to red to blue to white based on the attribute value.
 
@@ -61,11 +62,11 @@ let symbolLayer = MGLSymbolStyleLayer(identifier: "place-city-sm", source: symbo
 let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil)
 style.addSource(source)
 
-let stops = [0: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.yellow),
-             2.5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.orange),
-             5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.red),
-             7.5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.blue),
-             10: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.white)]
+let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow),
+             2.5: MGLStyleValue(rawValue: .orange),
+             5: MGLStyleValue(rawValue: .red),
+             7.5: MGLStyleValue(rawValue: .blue),
+             10: MGLStyleValue(rawValue: .white)]
 
 let layer = MGLCircleStyleLayer(identifier: "circles", source: source)
 layer.circleColor = MGLStyleValue(interpolationMode: .exponential,
@@ -80,7 +81,7 @@ style.insertLayer(layer, below: symbolLayer)
 
 ### Exponential
 
-`MGLInterpolationModelExponential` combined with any `MGLStyleFunctionOptionInterpolationBase` greater than `0`, you can interpolate between values exponentially, create an accelerated ramp effect.
+By combining `MGLInterpolationModeExponential` with an `MGLStyleFunctionOptionInterpolationBase` greater than `0` (other than `1`), you can interpolate between values exponentially, create an accelerated ramp effect.
 
 Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](working-with-mapbox-studio.html)) comparing interpolation base values of `1.5` and `0.5` based on zoom.
 
@@ -106,11 +107,11 @@ layer.circleRadius = MGLStyleValue(interpolationMode: .exponential,
 When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on.
 
 ``` swift
-let stops = [0: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.yellow),
-             2.5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.orange),
-             5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.red),
-             7.5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.blue),
-             10: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.white)]
+let stops = [0: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .yellow),
+             2.5: MGLStyleValue(rawValue: .orange),
+             5: MGLStyleValue(rawValue: .red),
+             7.5: MGLStyleValue(rawValue: .blue),
+             10: MGLStyleValue(rawValue: .white)]
 
 layer.circleColor = MGLStyleValue(interpolationMode: .interval,
                                   sourceStops: stops,
@@ -122,19 +123,19 @@ layer.circleColor = MGLStyleValue(interpolationMode: .interval,
 
 ### Categorical
 
-Returns the output value that is equal to the stop for the function input. We’re going to use a different stops dictionary than we did for the previous two modes.
+At each stop, `MGLInterpolationModeCategorical` produces an output value equal to the function input. We’re going to use a different stops dictionary than we did for the previous two modes.
 
-There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of green to catch any events that do not fall into any of those categories.
+There are three main types of events in the dataset: earthquakes, explosions, and quarry blasts. In this case, the color of the circle layer will be determined by the type of event, with a default value of blue to catch any events that do not fall into any of those categories.
 
 ``` swift
-let categoricalStops = ["earthquake": MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.orange),
-                        "explosion": MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.red),
-                        "quarry blast": MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.yellow)]
+let categoricalStops = ["earthquake": MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .orange),
+                        "explosion": MGLStyleValue(rawValue: .red),
+                        "quarry blast": MGLStyleValue(rawValue: .yellow)]
 
 layer.circleColor = MGLStyleValue(interpolationMode: .categorical,
                                   sourceStops: categoricalStops,
                                   attributeName: "type",
-                                  options: [.defaultValue: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.blue)])
+                                  options: [.defaultValue: MGLStyleValue<<%- cocoaPrefix %>Color>(rawValue: .blue)])
 
 ```
 
diff --git a/platform/darwin/docs/img/data-driven-styling/categorical1.png b/platform/darwin/docs/img/data-driven-styling/categorical1.png
new file mode 100644
index 0000000000..969846b41b
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/categorical1.png
diff --git a/platform/darwin/docs/img/data-driven-styling/categorical2.png b/platform/darwin/docs/img/data-driven-styling/categorical2.png
new file mode 100644
index 0000000000..5008c522ed
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/categorical2.png
diff --git a/platform/darwin/docs/img/data-driven-styling/citibikes.png b/platform/darwin/docs/img/data-driven-styling/citibikes.png
new file mode 100644
index 0000000000..a616672a32
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/citibikes.png
diff --git a/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png b/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png
new file mode 100644
index 0000000000..6aa129a305
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/exponential-function-1.png
diff --git a/platform/darwin/docs/img/data-driven-styling/exponential-function.png b/platform/darwin/docs/img/data-driven-styling/exponential-function.png
new file mode 100644
index 0000000000..c14969f0a8
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/exponential-function.png
diff --git a/platform/darwin/docs/img/data-driven-styling/exponential.png b/platform/darwin/docs/img/data-driven-styling/exponential.png
new file mode 100644
index 0000000000..87ddc1350e
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/exponential.png
diff --git a/platform/darwin/docs/img/data-driven-styling/identity.png b/platform/darwin/docs/img/data-driven-styling/identity.png
new file mode 100644
index 0000000000..632ccdf3d5
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/identity.png
diff --git a/platform/darwin/docs/img/data-driven-styling/interval.png b/platform/darwin/docs/img/data-driven-styling/interval.png
new file mode 100644
index 0000000000..d15aff2025
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/interval.png
diff --git a/platform/darwin/docs/img/data-driven-styling/polylineExample.png b/platform/darwin/docs/img/data-driven-styling/polylineExample.png
new file mode 100644
index 0000000000..cd9b39bae4
--- /dev/null
+++ b/platform/darwin/docs/img/data-driven-styling/polylineExample.png
diff --git a/platform/darwin/scripts/generate-style-code.js b/platform/darwin/scripts/generate-style-code.js
index 9c4569709d..7e798154e4 100644
--- a/platform/darwin/scripts/generate-style-code.js
+++ b/platform/darwin/scripts/generate-style-code.js
@@ -528,7 +528,7 @@ const layerH = ejs.compile(fs.readFileSync('platform/darwin/src/MGLStyleLayer.h.
 const layerM = ejs.compile(fs.readFileSync('platform/darwin/src/MGLStyleLayer.mm.ejs', 'utf8'), { strict: true});
 const testLayers = ejs.compile(fs.readFileSync('platform/darwin/test/MGLStyleLayerTests.mm.ejs', 'utf8'), { strict: true});
 const guideMD = ejs.compile(fs.readFileSync('platform/darwin/docs/guides/For Style Authors.md.ejs', 'utf8'), { strict: true });
-const ddsGuideMD = ejs.compile(fs.readFileSync('platform/darwin/docs/guides/Data-Driven Styling.md.ejs', 'utf8'), { strict: true });
+const ddsGuideMD = ejs.compile(fs.readFileSync('platform/darwin/docs/guides/Using Style Functions at Runtime.md.ejs', 'utf8'), { strict: true });
 
 const layers = _(spec.layer.type.values).map((value, layerType) => {
     const layoutProperties = Object.keys(spec[`layout_${layerType}`]).reduce((memo, name) => {
@@ -615,9 +615,9 @@ fs.writeFileSync(`platform/macos/docs/guides/For Style Authors.md`, guideMD({
     renamedProperties: renamedPropertiesByLayerType,
     layers: layers,
 }));
-fs.writeFileSync(`platform/ios/docs/guides/Data-Driven Styling.md`, ddsGuideMD({
+fs.writeFileSync(`platform/ios/docs/guides/Using Style Functions at Runtime.md`, ddsGuideMD({
     os: 'iOS',
 }));
-fs.writeFileSync(`platform/macos/docs/guides/Data-Driven Styling.md`, ddsGuideMD({
+fs.writeFileSync(`platform/macos/docs/guides/Using Style Functions at Runtime.md`, ddsGuideMD({
     os: 'macOS',
 }));