From cd83424867f054c34e6f8c6bd1b2960567b92373 Mon Sep 17 00:00:00 2001 From: Olivier Guyot Date: Thu, 9 Jun 2022 13:28:50 +0200 Subject: [PATCH] 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. --- .../render/webgl/LineStringBatchRenderer.js | 17 +++++-- src/ol/render/webgl/PointBatchRenderer.js | 14 ++++- src/ol/render/webgl/PolygonBatchRenderer.js | 11 +++- src/ol/renderer/webgl/VectorLayer.js | 51 +++++-------------- src/ol/webgl/Helper.js | 4 +- 5 files changed, 51 insertions(+), 46 deletions(-) diff --git a/src/ol/render/webgl/LineStringBatchRenderer.js b/src/ol/render/webgl/LineStringBatchRenderer.js index 08fc5a1775..1ec065ade9 100644 --- a/src/ol/render/webgl/LineStringBatchRenderer.js +++ b/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, }, diff --git a/src/ol/render/webgl/PointBatchRenderer.js b/src/ol/render/webgl/PointBatchRenderer.js index b2fef90696..3565989770 100644 --- a/src/ol/render/webgl/PointBatchRenderer.js +++ b/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, }, diff --git a/src/ol/render/webgl/PolygonBatchRenderer.js b/src/ol/render/webgl/PolygonBatchRenderer.js index d295d9139a..15a4378ccb 100644 --- a/src/ol/render/webgl/PolygonBatchRenderer.js +++ b/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, }, diff --git a/src/ol/renderer/webgl/VectorLayer.js b/src/ol/renderer/webgl/VectorLayer.js index 934fefeb68..de155b8172 100644 --- a/src/ol/renderer/webgl/VectorLayer.js +++ b/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 { /** diff --git a/src/ol/webgl/Helper.js b/src/ol/webgl/Helper.js index 9167fcd02e..b3c39e3a74 100644 --- a/src/ol/webgl/Helper.js +++ b/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 = {