Add "cover" layer type

From @jfirebaugh on December 19, 2016 22:58

Add a new layer type: cover.

This layer requires a source property, and prohibits the source-layer and filter properties. It has the paint properties cover-color, cover-pattern, cover-opacity, which behave the same as the equivalent background layer properties. In addition, it has a cover-type paint property, which is an enumeration with the following values:

• "tile-loaded" (default) -- The layer is rendered wherever a tile for the specified source is in the "loaded" state: a request for the tile has received a successful response, including responses indicating no data is present in the tile.
• "tile-loading" -- The layer is rendered wherever a tile for the specified source is in the process of being loaded: it's known to be needed for rendering, but not yet successfully or unsuccessfully loaded.
• "tile-failed" -- The layer is rendered wherever a tile for the specified source has failed to load: a request for the tile has produced a 4xx or 5xx HTTP status response (excluding legacy 404 responses interpreted as "no data"), or failed at the network level.

The cover-type paint property does not support property or zoom-and-property functions.

This proposal aims to satisfy two distinct use cases.

Use case: show a pattern or color in lieu of a loading or errored raster tile (https://github.com/mapbox/mapbox-gl-js/pull/3694). When raster tiles use fully transparent pixels to represent "no data", it is difficult or impossible to distinguish between an area fully without data, an area in which a tile or tiles have yet to be loaded, and an area in which tiles have failed to load due to network or other errors. The cover layer type provides a means to do so. To distinguish areas that have yet to be loaded, one can add a cover layer at the desired z-index with cover-type: "tile-loading". Likewise cover-type: "tile-failed" to distinguish areas where tiles have failed to load.

Use case: allow a platform- or application-defined "matte" color or pattern to show through areas of the map where no tile data has been loaded (https://github.com/mapbox/mapbox-gl-native/issues/119). For example:

A background layer does not suffice for this use case for two reasons:

• The matte pattern must be renderable prior to even the style itself being loaded.
• Once the style is loaded, a background layer is rendered across the whole canvas, including areas of the map where no tile data has been loaded.

However, the combination of a platform- or application-defined background rendering step, plus cover layer does suffice:

• The application or platform SDK is responsible for rendering the matte pattern.
• The style omits any background layers.
• The style includes a cover layer with cover-type: "tile-loaded" (or no cover-type per the default value) and other properties which produce the desired rendering for loaded tiles. For vector tilesets consisting of an implicit "land" background and explicit "water" polygons, this would mean a cover-color value indicative of land.

Implementation notes and future directions.

Implementing a cover layer type provides us with a pathway, in a future revision of the specification, to replace the background layer type with a single set of top-level style properties nested under a background key (in the style of light). The background then would then be defined statically, with multiple instances, or interleaving with other layers, being prohibited.

This would simplify the rendering implementations, which currently rely on analysis of all style layers to determine if the background can be rendered with a simple glClear operation or not.

This would also lead to better clarity in naming (https://github.com/mapbox/mapbox-gl-style-spec/issues/219): "background" would refer to a portion of the rendering that is truly in the background, behind all layers, and "cover" to layers which can be arbitrarily z-ordered but do behave relative to layers underneath them as their name suggests.

It would also provide a clearer path to adding rendering support for a sky color distinct from the ground (https://github.com/mapbox/mapbox-gl-native/issues/2190).

Copied from original issue: mapbox/mapbox-gl-style-spec#626

Start by reviewing the existing background layer behavior and the style specification and rendering architecture relevant to layer types; the issue does not name specific files or tests. Done means adding the cover layer with its source restrictions, paint properties, tile-state behavior, and documented cover-type constraints, with coverage for the specified cases.