From f69c37566e458f82a8bfc36aa3fcdeef44ed6f91 Mon Sep 17 00:00:00 2001 From: Olivier Guyot Date: Sat, 4 May 2019 17:26:05 +0200 Subject: [PATCH] Improve documentation on webgl and View --- src/ol/View.js | 14 +++++----- src/ol/renderer/webgl/PointsLayer.js | 2 ++ src/ol/webgl.js | 14 ++++++++++ src/ol/webgl/Buffer.js | 13 ++++++--- src/ol/webgl/Helper.js | 40 ++++++++++++++-------------- 5 files changed, 53 insertions(+), 30 deletions(-) diff --git a/src/ol/View.js b/src/ol/View.js index 9be6a06e2d..6e0a44d41a 100644 --- a/src/ol/View.js +++ b/src/ol/View.js @@ -191,6 +191,11 @@ const DEFAULT_MIN_ZOOM = 0; * This is the object to act upon to change the center, resolution, * and rotation of the map. * + * A View has a `projection`. The projection determines the + * coordinate system of the center, and its units determine the units of the + * resolution (projection units per pixel). The default projection is + * Spherical Mercator (EPSG:3857). + * * ### The view states * * An View is determined by three states: `center`, `resolution`, @@ -202,11 +207,6 @@ const DEFAULT_MIN_ZOOM = 0; * methods are available, as well as `getResolutionForZoom` and * `getZoomForResolution` to switch from one system to the other. * - * A View has a `projection`. The projection determines the - * coordinate system of the center, and its units determine the units of the - * resolution (projection units per pixel). The default projection is - * Spherical Mercator (EPSG:3857). - * * ### The constraints * * `setCenter`, `setResolution` and `setRotation` can be used to change the @@ -218,7 +218,7 @@ const DEFAULT_MIN_ZOOM = 0; * * The *resolution constraint* typically restricts min/max values and * snaps to specific resolutions. It is determined by the following - * options: `resolutions`, `maxResolution`, `maxZoom`, and `zoomFactor`. + * options: `resolutions`, `maxResolution`, `maxZoom` and `zoomFactor`. * If `resolutions` is set, the other three options are ignored. See * documentation for each option for more information. By default, the view * only has a min/max restriction and allow intermediary zoom levels when @@ -226,7 +226,7 @@ const DEFAULT_MIN_ZOOM = 0; * * The *rotation constraint* snaps to specific angles. It is determined * by the following options: `enableRotation` and `constrainRotation`. - * By default the rotation value is snapped to zero when approaching the + * By default rotation is allowed and its value is snapped to zero when approaching the * horizontal. * * The *center constraint* is determined by the `extent` option. By diff --git a/src/ol/renderer/webgl/PointsLayer.js b/src/ol/renderer/webgl/PointsLayer.js index 8b5e49b34f..37dbc27830 100644 --- a/src/ol/renderer/webgl/PointsLayer.js +++ b/src/ol/renderer/webgl/PointsLayer.js @@ -114,6 +114,7 @@ const FRAGMENT_SHADER = ` * * Points are rendered as quads with the following structure: * + * ``` * (u0, v1) (u1, v1) * [3]----------[2] * |` | @@ -124,6 +125,7 @@ const FRAGMENT_SHADER = ` * | ` | * [0]----------[1] * (u0, v0) (u1, v0) + * ``` * * This uses {@link module:ol/webgl/Helper~WebGLHelper} internally. * diff --git a/src/ol/webgl.js b/src/ol/webgl.js index 4dd68dfb57..089254f47d 100644 --- a/src/ol/webgl.js +++ b/src/ol/webgl.js @@ -58,36 +58,50 @@ export const ONE_MINUS_SRC_ALPHA = 0x0303; /** + * Used by {@link module:ol/webgl/Helper~WebGLHelper} for buffers containing vertices data, such as + * position, color, texture coordinate, etc. These vertices are then referenced by an index buffer + * to be drawn on screen (see {@link module:ol/webgl.ELEMENT_ARRAY_BUFFER}). * @const * @type {number} + * @api */ export const ARRAY_BUFFER = 0x8892; /** + * Used by {@link module:ol/webgl/Helper~WebGLHelper} for buffers containing indices data. + * Index buffers are essentially lists of references to vertices defined in a vertex buffer + * (see {@link module:ol/webgl.ARRAY_BUFFER}), and define the primitives (triangles) to be drawn. * @const * @type {number} + * @api */ export const ELEMENT_ARRAY_BUFFER = 0x8893; /** + * Used by {link module:ol/webgl/Buffer~WebGLArrayBuffer}. * @const * @type {number} + * @api */ export const STREAM_DRAW = 0x88E0; /** + * Used by {link module:ol/webgl/Buffer~WebGLArrayBuffer}. * @const * @type {number} + * @api */ export const STATIC_DRAW = 0x88E4; /** + * Used by {link module:ol/webgl/Buffer~WebGLArrayBuffer}. * @const * @type {number} + * @api */ export const DYNAMIC_DRAW = 0x88E8; diff --git a/src/ol/webgl/Buffer.js b/src/ol/webgl/Buffer.js index 42888a6eb6..21e5b25c8c 100644 --- a/src/ol/webgl/Buffer.js +++ b/src/ol/webgl/Buffer.js @@ -4,20 +4,27 @@ import {STATIC_DRAW, STREAM_DRAW, DYNAMIC_DRAW} from '../webgl.js'; /** + * Used to describe the intended usage for the data: `STATIC_DRAW`, `STREAM_DRAW` + * or `DYNAMIC_DRAW`. * @enum {number} */ -const BufferUsage = { +export const BufferUsage = { STATIC_DRAW: STATIC_DRAW, STREAM_DRAW: STREAM_DRAW, DYNAMIC_DRAW: DYNAMIC_DRAW }; - +/** + * @classdesc + * Object used to store an array of data as well as usage information for that data. + * See the documentation of [WebGLRenderingContext.bufferData](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bufferData) for more info. + * @api + */ class WebGLArrayBuffer { /** * @param {Array=} opt_arr Array. - * @param {number=} opt_usage Usage. + * @param {number=} opt_usage Usage, either `STATIC_DRAW`, `STREAM_DRAW` or `DYNAMIC_DRAW`. Default is `DYNAMIC_DRAW`. */ constructor(opt_arr, opt_usage) { diff --git a/src/ol/webgl/Helper.js b/src/ol/webgl/Helper.js index 5740fc9498..180654c25f 100644 --- a/src/ol/webgl/Helper.js +++ b/src/ol/webgl/Helper.js @@ -28,7 +28,7 @@ import {getContext} from '../webgl'; */ /** - * Shader types, either `FRAGMENT_SHADER` or `VERTEX_SHADER` + * Shader types, either `FRAGMENT_SHADER` or `VERTEX_SHADER`. * @enum {number} */ export const ShaderType = { @@ -37,9 +37,9 @@ export const ShaderType = { }; /** - * Uniform names used in the default shaders. - * @const - * @type {Object.} + * Uniform names used in the default shaders: `PROJECTION_MATRIX`, `OFFSET_SCALE_MATRIX`. + * and `OFFSET_ROTATION_MATRIX`. + * @enum {string} */ export const DefaultUniform = { PROJECTION_MATRIX: 'u_projectionMatrix', @@ -48,9 +48,9 @@ export const DefaultUniform = { }; /** - * Attribute names used in the default shaders. - * @const - * @type {Object.} + * Attribute names used in the default shaders: `POSITION`, `TEX_COORD`, `OPACITY`, + * `ROTATE_WITH_VIEW`, `OFFSETS` and `COLOR` + * @enum {string} */ export const DefaultAttrib = { POSITION: 'a_position', @@ -74,7 +74,7 @@ export const DefaultAttrib = { /** * @typedef {Object} PostProcessesOptions * @property {number} [scaleRatio] Scale ratio; if < 1, the post process will render to a texture smaller than - * the main canvas that will then be sampled up (useful for saving resource on blur steps). + * the main canvas which will then be sampled up (useful for saving resource on blur steps). * @property {string} [vertexShader] Vertex shader source * @property {string} [fragmentShader] Fragment shader source * @property {Object.} [uniforms] Uniform definitions for the post process step @@ -82,7 +82,7 @@ export const DefaultAttrib = { /** * @typedef {Object} Options - * @property {Object.} [uniforms] Uniform definitions; property namesmust math the uniform + * @property {Object.} [uniforms] Uniform definitions; property names must match the uniform * names in the provided or default shaders. * @property {Array} [postProcesses] Post-processes definitions */ @@ -113,7 +113,7 @@ export const DefaultAttrib = { * * * Varyings usually prefixed with `v_` are passed on to the fragment shader * - * Fragment shaders are used to control the actual color of the pixels rawn on screen. Their only output is `gl_FragColor`. + * Fragment shaders are used to control the actual color of the pixels drawn on screen. Their only output is `gl_FragColor`. * * Both shaders can take *uniforms* or *attributes* as input. Attributes are explained later. Uniforms are common, read-only values that * can be changed at every frame and can be of type float, arrays of float or images. @@ -150,16 +150,16 @@ export const DefaultAttrib = { * * The {@link module:ol/webgl/PostProcessingPass~WebGLPostProcessingPass} class is used internally, refer to its documentation for more info. * - * ### Binding WebGL buffers and flushing data into them: + * ### Binding WebGL buffers and flushing data into them * - * Data that must be passed to the GPU has to be transferred using `WebGLArrayBuffer` objects. - * A buffer has to be created only once, but must be bound everytime the buffer content should be used for rendering. - * This is done using `WebGLHelper.bindBuffer`. + * Data that must be passed to the GPU has to be transferred using {@link module:ol/webgl/Buffer~WebGLArrayBuffer} objects. + * A buffer has to be created only once, but must be bound every time the buffer content will be used for rendering. + * This is done using {@link bindBuffer}. * When the buffer's array content has changed, the new data has to be flushed to the GPU memory; this is done using - * `WebGLHelper.flushBufferData`. Note: this operation is expensive and should be done as infrequently as possible. + * {@link flushBufferData}. Note: this operation is expensive and should be done as infrequently as possible. * - * When binding a `WebGLArrayBuffer`, a `target` parameter must be given: it should be either {@link module:ol/webgl~ARRAY_BUFFER} - * (if the buffer contains vertices data) or {@link module:ol/webgl~ELEMENT_ARRAY_BUFFER} (if the buffer contains indices data). + * When binding an array buffer, a `target` parameter must be given: it should be either {@link module:ol/webgl.ARRAY_BUFFER} + * (if the buffer contains vertices data) or {@link module:ol/webgl.ELEMENT_ARRAY_BUFFER} (if the buffer contains indices data). * * Examples below: * ```js @@ -179,8 +179,8 @@ export const DefaultAttrib = { * ### Specifying attributes * * The GPU only receives the data as arrays of numbers. These numbers must be handled differently depending on what it describes (position, texture coordinate...). - * Attributes are used to specify these uses. Use `WebGLHelper.enableAttributeArray` and either - * the default attribute names in {@link module:ol/webgl/Helper~DefaultAttrib} or custom ones. + * Attributes are used to specify these uses. Use {@link enableAttributeArray} and either + * the default attribute names in {@link module:ol/webgl/Helper.DefaultAttrib} or custom ones. * * Please note that you will have to specify the type and offset of the attributes in the data array. You can refer to the documentation of [WebGLRenderingContext.vertexAttribPointer](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/vertexAttribPointer) for more explanation. * ```js @@ -194,7 +194,7 @@ export const DefaultAttrib = { * * ### Rendering primitives * - * Once all the steps above have been achieved, rendering primitives to the screen is done using `WebGLHelper.prepareDraw` `drawElements` and `finalizeDraw`. + * Once all the steps above have been achieved, rendering primitives to the screen is done using {@link prepareDraw}, {@link drawElements} and {@link finalizeDraw}. * ```js * // frame preparation step * this.context.prepareDraw(frameState);