document what buckets are

[incanus]

This goes obsolete if we eventually ship the second style version on native as well (mapbox/mapbox-gl-native#172) but if not, this needs to happen. It should draw from real examples using a vector tile and showing how buckets map data from layers in the tile, possibly filtered by a field in the layer and one or more values to match on, into stylable components.

[ghost]

From the discussion over at #11, I'm getting the idea that perhaps "bucket" just means what is commonly referred to as a "group". Could we just say "group" instead?

As an alternative, could we define bucket as something like, "A bucket is a group of {nouns} which you can do {verbs} to so that it's possible to accomplish {some-meaningful-goal}"?

/cc @mourner

[kkaefer]

“A bucket is a group of geometric features which you can render multiple times without much of a performance/memory overhead.”

[mourner]

@wsnook bucket is a selection of data (in addition to some options of how it is preprocessed) that can then be put as a layer one or more times and styled.

[ghost]

Thanks @kkaefer and @mourner, that helps! My current best understanding of how all these things fit together is:

The purpose of a GL Style is to specify how the categorically labeled geometric data in vector tiles should be filtered and translated into visually styled geometric data, in a form which is suitable for efficiently rendering into a map with OpenGL. The three main things which a GL Style specifies are:

1. How to extract visually related geometric features from vector tiles into groups called buckets
2. What the visual style for each bucket should be
3. How to build the structure of an OpenGL map scene by arranging the buckets into a z-ordering

[kkaefer]

The important thing is that there is no 1:1 mapping between a structure element and buckets. I.e. you can have multiple instances of just one buffer to render the same data multiple times.

[ghost]

multiple instances of just one buffer to render the same data multiple times

Like for road casings and building shadows?

[kkaefer]

Exactly :)

[ghost]

Okay, so maybe something more like:

The purpose of a GL Style is to specify how the categorically labeled geometric data in vector tiles should be translated into visually styled geometric data which can be efficiently rendered as a map by OpenGL. The three main things which a GL Style specifies are:

1. How to extract visually related geometric features from vector tiles into groups called buckets
2. Visual styles describing how the geometry in a bucket should appear
3. How to build the structure of an OpenGL map scene by associating styles with buckets and arranging them into a z-ordering. Note that a single bucket can be added to a scene more than once and with different styles. This enables efficient rendering of visual effects like buildings with shadows and roads with casings.

[edit: the above applies to the renderer implementation and the v0 style. The v1 style works differently.]

[mourner]

Not relevant now?