WebGL / improve doc for Helper and VectorLayerRenderer

Also created enums for attributes (like uniforms), in an attempt to clarify
what is accessible to the vertex shaders.

src/ol/render/webgl/LineStringBatchRenderer.js

@@ -5,6 +5,17 @@ import AbstractBatchRenderer from './BatchRenderer.js';
 import {AttributeType} from '../../webgl/Helper.js';
 import {transform2D} from '../../geom/flat/transform.js';
 
+/**
+ * Names of attributes made available to the vertex shader.
+ * Please note: changing these *will* break custom shaders!
+ * @enum {string}
+ */
+export const Attributes = {
+  SEGMENT_START: 'a_segmentStart',
+  SEGMENT_END: 'a_segmentEnd',
+  PARAMETERS: 'a_parameters',
+};
+
 class LineStringBatchRenderer extends AbstractBatchRenderer {
   /**
    * @param {import("../../webgl/Helper.js").default} helper WebGL helper instance
@@ -19,17 +30,17 @@ class LineStringBatchRenderer extends AbstractBatchRenderer {
     // vertices for lines must hold both a position (x,y) and an offset (dx,dy)
     this.attributes_ = [
       {
-        name: 'a_segmentStart',
+        name: Attributes.SEGMENT_START,
         size: 2,
         type: AttributeType.FLOAT,
       },
       {
-        name: 'a_segmentEnd',
+        name: Attributes.SEGMENT_END,
         size: 2,
         type: AttributeType.FLOAT,
       },
       {
-        name: 'a_parameters',
+        name: Attributes.PARAMETERS,
         size: 1,
         type: AttributeType.FLOAT,
       },

src/ol/render/webgl/PointBatchRenderer.js

@@ -6,6 +6,16 @@ import AbstractBatchRenderer from './BatchRenderer.js';
 import {AttributeType} from '../../webgl/Helper.js';
 import {apply as applyTransform} from '../../transform.js';
 
+/**
+ * Names of attributes made available to the vertex shader.
+ * Please note: changing these *will* break custom shaders!
+ * @enum {string}
+ */
+export const Attributes = {
+  POSITION: 'a_position',
+  INDEX: 'a_index',
+};
+
 class PointBatchRenderer extends AbstractBatchRenderer {
   /**
    * @param {import("../../webgl/Helper.js").default} helper WebGL helper instance
@@ -20,12 +30,12 @@ class PointBatchRenderer extends AbstractBatchRenderer {
     // vertices for point must hold both a position (x,y) and an index (their position in the quad)
     this.attributes_ = [
       {
-        name: 'a_position',
+        name: Attributes.POSITION,
         size: 2,
         type: AttributeType.FLOAT,
       },
       {
-        name: 'a_index',
+        name: Attributes.INDEX,
         size: 1,
         type: AttributeType.FLOAT,
       },

src/ol/render/webgl/PolygonBatchRenderer.js

@@ -5,6 +5,15 @@ import AbstractBatchRenderer from './BatchRenderer.js';
 import {AttributeType} from '../../webgl/Helper.js';
 import {transform2D} from '../../geom/flat/transform.js';
 
+/**
+ * Names of attributes made available to the vertex shader.
+ * Please note: changing these *will* break custom shaders!
+ * @enum {string}
+ */
+export const Attributes = {
+  POSITION: 'a_position',
+};
+
 class PolygonBatchRenderer extends AbstractBatchRenderer {
   /**
    * @param {import("../../webgl/Helper.js").default} helper WebGL helper instance
@@ -19,7 +28,7 @@ class PolygonBatchRenderer extends AbstractBatchRenderer {
     // By default only a position attribute is required to render polygons
     this.attributes_ = [
       {
-        name: 'a_position',
+        name: Attributes.POSITION,
         size: 2,
         type: AttributeType.FLOAT,
       },

src/ol/renderer/webgl/VectorLayer.js

@@ -53,48 +53,23 @@ import {listen, unlistenByKey} from '../../events.js';
 
 /**
  * @classdesc
- * Experimental WebGL vector renderer. Supports polygons and lines.
+ * Experimental WebGL vector renderer. Supports polygons, lines and points:
+ *  * Polygons are broken down into triangles
+ *  * Lines are rendered as strips of quads
+ *  * Points are rendered as quads
  *
- * You need to provide vertex and fragment shaders for rendering. This can be done using
- * {@link module:ol/webgl/ShaderBuilder} utilities.
+ * You need to provide vertex and fragment shaders as well as custom attributes for each type of geometry. All shaders
+ * can access the uniforms in the {@link module:ol/webgl/Helper~DefaultUniform} enum.
+ * The vertex shaders can access the following attributes depending on the geometry type:
+ *  * For polygons: {@link module:ol/render/webgl/PolygonBatchRenderer~Attributes}
+ *  * For line strings: {@link module:ol/render/webgl/LineStringBatchRenderer~Attributes}
+ *  * For points: {@link module:ol/render/webgl/PointBatchRenderer~Attributes}
  *
- * To include variable attributes in the shaders, you need to declare them using the `attributes` property of
- * the options object like so:
- * ```js
- * new WebGLPointsLayerRenderer(layer, {
- *   attributes: [
- *     {
- *       name: 'size',
- *       callback: function(feature) {
- *         // compute something with the feature
- *       }
- *     },
- *     {
- *       name: 'weight',
- *       callback: function(feature) {
- *         // compute something with the feature
- *       }
- *     },
- *   ],
- *   vertexShader:
- *     // shader using attribute a_weight and a_size
- *   fragmentShader:
- *     // shader using varying v_weight and v_size
- * ```
+ * Please note that the fragment shaders output should have premultiplied alpha, otherwise visual anomalies may occur.
  *
- * To enable hit detection, you must as well provide dedicated shaders using the `hitVertexShader`
- * and `hitFragmentShader` properties. These shall expect the `a_hitColor` attribute to contain
- * the final color that will have to be output for hit detection to work.
+ * Note: this uses {@link module:ol/webgl/Helper~WebGLHelper} internally.
  *
- * The following uniform is used for the main texture: `u_texture`.
- *
- * Please note that the main shader output should have premultiplied alpha, otherwise visual anomalies may occur.
- *
- * Polygons are broken down into triangles using the @mapbox/earcut package.
- * Lines are rendered into strips of quads.
- *
- *
- * This uses {@link module:ol/webgl/Helper~WebGLHelper} internally.
+ * @api
  */
 class WebGLVectorLayerRenderer extends WebGLLayerRenderer {
   /**

src/ol/webgl/Helper.js

@@ -38,8 +38,8 @@ export const ShaderType = {
 };
 
 /**
- * Uniform names used in the default shaders: `PROJECTION_MATRIX`, `OFFSET_SCALE_MATRIX`.
- * and `OFFSET_ROTATION_MATRIX`.
+ * Names of uniforms made available to all shaders.
+ * Please note: changing these *will* break custom shaders!
  * @enum {string}
  */
 export const DefaultUniform = {