ashatora/openlayers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Improve documentation on webgl and View

Browse Source
This commit is contained in:
Olivier Guyot
2019-05-04 17:26:05 +02:00
parent d6485b1e94
commit f69c37566e
5 changed files with 53 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
src/ol/View.js
View File

@@ -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

2
src/ol/renderer/webgl/PointsLayer.js
View File

@@ -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.
*

14
src/ol/webgl.js
View File

@@ -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;

13
src/ol/webgl/Buffer.js
View File

@@ -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<number>=} 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) {

40
src/ol/webgl/Helper.js
View File

@@ -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.<string,string>}
* 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.<string,string>}
* 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.<string,UniformValue>} [uniforms] Uniform definitions for the post process step
@@ -82,7 +82,7 @@ export const DefaultAttrib = {
/**
* @typedef {Object} Options
* @property {Object.<string,UniformValue>} [uniforms] Uniform definitions; property namesmust math the uniform
* @property {Object.<string,UniformValue>} [uniforms] Uniform definitions; property names must match the uniform
* names in the provided or default shaders.
* @property {Array<PostProcessesOptions>} [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);