Class: WebGLHelper

ol/webgl/Helper~WebGLHelper

import WebGLHelper from 'ol/webgl/Helper';

This class is intended to provide low-level functions related to WebGL rendering, so that accessing directly the WebGL API should not be required anymore.

Several operations are handled by the WebGLHelper class:

Define custom shaders and uniforms

Shaders are low-level programs executed on the GPU and written in GLSL. There are two types of shaders:

Vertex shaders are used to manipulate the position and attribute of vertices of rendered primitives (ie. corners of a square). Outputs are:

gl_Position: position of the vertex in screen space
Varyings usually prefixed with v_ are passed on to the fragment shader

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.

Shaders must be compiled and assembled into a program like so:

// here we simply create two shaders and assemble them in a program which is then used
// for subsequent rendering calls
const vertexShader = new WebGLVertex(VERTEX_SHADER);
const fragmentShader = new WebGLFragment(FRAGMENT_SHADER);
const program = this.context.getProgram(fragmentShader, vertexShader);
helper.useProgram(this.program);

Uniforms are defined using the uniforms option and can either be explicit values or callbacks taking the frame state as argument. You can also change their value along the way like so:

helper.setUniformFloatValue('u_value', valueAsNumber);

Defining post processing passes

Post processing describes the act of rendering primitives to a texture, and then rendering this texture to the final canvas while applying special effects in screen space. Typical uses are: blurring, color manipulation, depth of field, filtering...

The WebGLHelper class offers the possibility to define post processes at creation time using the postProcesses option. A post process step accepts the following options:

fragmentShader and vertexShader: text literals in GLSL language that will be compiled and used in the post processing step.
uniforms: uniforms can be defined for the post processing steps just like for the main render.
scaleRatio: allows using an intermediate texture smaller or higher than the final canvas in the post processing step. This is typically used in blur steps to reduce the performance overhead by using an already downsampled texture as input.

The module:ol/webgl/PostProcessingPass~WebGLPostProcessingPass class is used internally, refer to its documentation for more info.

Binding WebGL buffers and flushing data into them

Data that must be passed to the GPU has to be transferred using 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 bindBuffer. When the buffer's array content has changed, the new data has to be flushed to the GPU memory; this is done using flushBufferData. Note: this operation is expensive and should be done as infrequently as possible.

When binding an array buffer, a target parameter must be given: it should be either module:ol/webgl.ARRAY_BUFFER (if the buffer contains vertices data) or module:ol/webgl.ELEMENT_ARRAY_BUFFER (if the buffer contains indices data).

Examples below:

// at initialization phase
const verticesBuffer = new WebGLArrayBuffer([], DYNAMIC_DRAW);
const indicesBuffer = new WebGLArrayBuffer([], DYNAMIC_DRAW);

// when array values have changed
helper.flushBufferData(ARRAY_BUFFER, this.verticesBuffer);
helper.flushBufferData(ELEMENT_ARRAY_BUFFER, this.indicesBuffer);

// at rendering phase
helper.bindBuffer(ARRAY_BUFFER, this.verticesBuffer);
helper.bindBuffer(ELEMENT_ARRAY_BUFFER, this.indicesBuffer);

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. Specify the attribute names with enableAttributes() (see code snippet below).

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 for more explanation.

// here we indicate that the data array has the following structure:
// [posX, posY, offsetX, offsetY, texCoordU, texCoordV, posX, posY, ...]
helper.enableAttributes([
  {
     name: 'a_position',
     size: 2
  },
  {
    name: 'a_offset',
    size: 2
  },
  {
    name: 'a_texCoord',
    size: 2
  }
])

Rendering primitives

Once all the steps above have been achieved, rendering primitives to the screen is done using prepareDraw, drawElements and finalizeDraw.

// frame preparation step
helper.prepareDraw(frameState);

// call this for every data array that has to be rendered on screen
helper.drawElements(0, this.indicesBuffer.getArray().length);

// finalize the rendering by applying post processes
helper.finalizeDraw(frameState);

For an example usage of this class, refer to module:ol/renderer/webgl/PointsLayer~WebGLPointsLayerRenderer.

new WebGLHelper(opt_options) webgl/Helper.js, line 308

Name Type Description

options

Options.

Name	Type	Description
`uniforms`	Object.<string, module:ol/webgl/Helper~UniformValue> \| undefined	Uniform definitions; property names must match the uniform names in the provided or default shaders.
`postProcesses`	Array.<module:ol/webgl/Helper~PostProcessesOptions> \| undefined	Post-processes definitions
`canvasCacheKey`	string \| undefined	The cache key for the canvas.

Extends

module:ol/Disposable~Disposable

Methods

bindBuffer(buffer) webgl/Helper.js, line 489

Just bind the buffer if it's in the cache. Otherwise create the WebGL buffer, bind it, populate it, and add an entry to the cache.

Name	Type	Description
`buffer`	module:ol/webgl/Buffer~WebGLArrayBuffer	Buffer.

createTexture(size, opt_data, opt_texture){WebGLTexture} webgl/Helper.js, line 1061

Will create or reuse a given webgl texture and apply the given size. If no image data specified, the texture will be empty, otherwise image data will be used and the size parameter will be ignored. Note: wrap parameters are set to clamp to edge, min filter is set to linear.

Name	Type	Description
`size`	Array.<number>	Expected size of the texture
`data`	ImageData \| HTMLImageElement \| HTMLCanvasElement \| undefined	Image data/object to bind to the texture
`texture`	WebGLTexture \| undefined	Existing texture to reuse

Returns:

The generated texture

drawElements(start, end) webgl/Helper.js, line 624

Execute a draw call based on the currently bound program, texture, buffers, attributes.

Name	Type	Description
`start`	number	Start index.
`end`	number	End index.

enableAttributes(attributes) webgl/Helper.js, line 1019

Will enable the following attributes to be read from the currently bound buffer, i.e. tell the GPU where to read the different attributes in the buffer. An error in the size/type/order of attributes will most likely break the rendering and throw a WebGL exception.

Name	Type	Description
`attributes`	Array.<module:ol/webgl/Helper~AttributeDescription>	Ordered list of attributes to read from the buffer

flushBufferData(buffer) webgl/Helper.js, line 510

Update the data contained in the buffer array; this is required for the new data to be rendered

Name	Type	Description
`buffer`	module:ol/webgl/Buffer~WebGLArrayBuffer	Buffer.

getAttributeLocation(name){number} webgl/Helper.js, line 914

Will get the location from the shader or the cache

Name	Type	Description
`name`	string	Attribute name

Returns:

attribLocation

getCanvas(){HTMLCanvasElement} webgl/Helper.js, line 665

Returns:

Canvas.

getGL(){WebGLRenderingContext} webgl/Helper.js, line 674

Get the WebGL rendering context

Returns:

The rendering context.

getProgram(fragmentShaderSource, vertexShaderSource){WebGLProgram} webgl/Helper.js, line 848

Create a program for a vertex and fragment shader. Throws if shader compilation fails.

Name	Type	Description
`fragmentShaderSource`	string	Fragment shader source.
`vertexShaderSource`	string	Vertex shader source.

Returns:

Program

getUniformLocation(name){WebGLUniformLocation} webgl/Helper.js, line 898

Will get the location from the shader or the cache

Name	Type	Description
`name`	string	Uniform name

Returns:

uniformLocation

makeProjectionTransform(frameState, transform){module:ol/transform~Transform} webgl/Helper.js, line 932

Modifies the given transform to apply the rotation/translation/scaling of the given frame state. The resulting transform can be used to convert world space coordinates to view coordinates.

Name	Type	Description
`frameState`	module:ol/PluggableMap~FrameState	Frame state.
`transform`	module:ol/transform~Transform	Transform to update.
`frameState.pixelRatio`	number	The pixel ratio of the frame.
`frameState.time`	number	The time when rendering of the frame was requested.
`frameState.viewState`	module:ol/View~State	The state of the current view.
`frameState.animate`	boolean	Animate.
`frameState.coordinateToPixelTransform`	module:ol/transform~Transform	CoordinateToPixelTransform.
`frameState.declutterTree`	module:rbush	DeclutterTree.
`frameState.extent`	null \| module:ol/extent~Extent	Extent.
`frameState.nextExtent`	module:ol/extent~Extent \| undefined	Next extent during an animation series.
`frameState.index`	number	Index.
`frameState.layerStatesArray`	Array.<module:ol/layer/Layer~State>	LayerStatesArray.
`frameState.layerIndex`	number	LayerIndex.
`frameState.pixelToCoordinateTransform`	module:ol/transform~Transform	PixelToCoordinateTransform.
`frameState.postRenderFunctions`	Array.<module:ol/PluggableMap~PostRenderFunction>	PostRenderFunctions.
`frameState.size`	module:ol/size~Size	Size.
`frameState.tileQueue`	module:ol/TileQueue~TileQueue	TileQueue.
`frameState.usedTiles`	Object.<string, Object.<string, boolean>>	UsedTiles.
`frameState.viewHints`	Array.<number>	ViewHints.
`frameState.wantedTiles`	Object.<string, Object.<string, boolean>>	WantedTiles.
`frameState.mapId`	string	The id of the map.
`frameState.renderTargets`	Object.<string, boolean>	Identifiers of previously rendered elements.

Returns:

The updated transform object.

prepareDraw(frameState, opt_disableAlphaBlend) webgl/Helper.js, line 556

Clear the buffer & set the viewport to draw. Post process passes will be initialized here, the first one being bound as a render target for subsequent draw calls.

Name	Type	Description
`frameState`	module:ol/PluggableMap~FrameState	current frame state
`disableAlphaBlend`	boolean \| undefined	If true, no alpha blending will happen.
`frameState.pixelRatio`	number	The pixel ratio of the frame.
`frameState.time`	number	The time when rendering of the frame was requested.
`frameState.viewState`	module:ol/View~State	The state of the current view.
`frameState.animate`	boolean	Animate.
`frameState.coordinateToPixelTransform`	module:ol/transform~Transform	CoordinateToPixelTransform.
`frameState.declutterTree`	module:rbush	DeclutterTree.
`frameState.extent`	null \| module:ol/extent~Extent	Extent.
`frameState.nextExtent`	module:ol/extent~Extent \| undefined	Next extent during an animation series.
`frameState.index`	number	Index.
`frameState.layerStatesArray`	Array.<module:ol/layer/Layer~State>	LayerStatesArray.
`frameState.layerIndex`	number	LayerIndex.
`frameState.pixelToCoordinateTransform`	module:ol/transform~Transform	PixelToCoordinateTransform.
`frameState.postRenderFunctions`	Array.<module:ol/PluggableMap~PostRenderFunction>	PostRenderFunctions.
`frameState.size`	module:ol/size~Size	Size.
`frameState.tileQueue`	module:ol/TileQueue~TileQueue	TileQueue.
`frameState.usedTiles`	Object.<string, Object.<string, boolean>>	UsedTiles.
`frameState.viewHints`	Array.<number>	ViewHints.
`frameState.wantedTiles`	Object.<string, Object.<string, boolean>>	WantedTiles.
`frameState.mapId`	string	The id of the map.
`frameState.renderTargets`	Object.<string, boolean>	Identifiers of previously rendered elements.

setUniformFloatValue(uniform, value) webgl/Helper.js, line 958

Give a value for a standard float uniform

Name	Type	Description
`uniform`	string	Uniform name
`value`	number	Value

setUniformMatrixValue(uniform, value) webgl/Helper.js, line 977

Give a value for a standard matrix4 uniform

Name	Type	Description
`uniform`	string	Uniform name
`value`	Array.<number>	Matrix value

useProgram(program){boolean} webgl/Helper.js, line 811

Use a program. If the program is already in use, this will return false.

Name	Type	Description
`program`	WebGLProgram	Program.

Returns:

Changed.