[core] Add another explanatory comment to PaintPropertyBinder

1 files changed, 31 insertions, 0 deletions

diff --git a/src/mbgl/style/paint_property_binder.hpp b/src/mbgl/style/paint_property_binder.hpp
index e6e957958c..7e44b509a1 100644
--- a/src/mbgl/style/paint_property_binder.hpp
+++ b/src/mbgl/style/paint_property_binder.hpp
@@ -49,6 +49,37 @@ std::array<float, N*2> zoomInterpolatedAttributeValue(const std::array<float, N>
     return result;
 }
 
+/*
+   PaintPropertyBinder is an abstract class serving as the interface definition for
+   the strategy used for constructing, uploading, and binding paint property data as
+   GLSL attributes.
+
+   It has three concrete subclasses, one for each of the three strategies we use:
+
+   * For _constant_ properties -- those whose value is a constant, or the constant
+     result of evaluating a camera function at a particular camera position -- we
+     don't need a vertex buffer, and can instead use a constant attribute binding
+     via the `glVertexAttrib*` family of functions.
+   * For source functions, we use a vertex buffer with a single attribute value,
+     the evaluated result of the source function for the given feature.
+   * For composite functions, we use a vertex buffer with two attributes: min and
+     max values covering the range of zooms at which we expect the tile to be
+     displayed. These values are calculated by evaluating the composite function for
+     the given feature at strategically chosen zoom levels. In addition to this
+     attribute data, we also use a uniform value which the shader uses to interpolate
+     between the min and max value at the final displayed zoom level. The use of a
+     uniform allows us to cheaply update the value on every frame.
+
+   Note that the shader source is the same regardless of the strategy used to bind
+   the attribute -- in all cases the attribute is declared as a vec2, in order to
+   support composite min and max values (color attributes use a vec4 with special
+   packing). When the constant or source function strategies are used, the
+   interpolation uniform value is set to zero, and the second attribute element is
+   unused. This differs from the GL JS implementation, which dynamically generates
+   shader source based on the strategy used. We found that in WebGL, using
+   `glVertexAttrib*` was unnacceptably slow. Additionally, in GL Native we have
+   implemented binary shader caching, which works better if the shaders are constant.
+*/
 template <class T, class A>
 class PaintPropertyBinder {
 public: