Parameter Setting

luma.gl simplifies the usage of WebGL parameters by providing a unified API for setting and getting values. Any GL parameter can be queried or set using getParameters and setParameters (no need to keep track of what underlying WebGL calls are required), and luma.gl also provide setting names that allow the normal WebGL setter functions (like gl.blendEquation or gl.clearColor) to be specified as keys in a setParameters call.

In addition, state queries are done towards cached values and are thus much faster than working directly with the WebGL API, where synchronous WebGL queries can be a performance bottleneck.

The following functions are provided:

• getParameters - Returns the values of some or all GL context parameters
• setParameters - Sets a the value(s) of the specified GL context parameters
• resetParameters - Resets all gl context parameters to default values

Usage

Set a global parameter value using a WebGL GLenum

const value = setParameters(gl, {
  [gl.DEPTH_TEST]: true
});

Set a global parameter value using a luma.gl setting function name

const value = setParameters(gl, {
  depthTest: true
});

Get all gl parameter values (values will be an object map keyed with parameter names)

const values = getParameters(gl);

Set parameters temporarily for a function call (automatically restoring them after the call)

const returnValue = withParameters(gl, {
  depthTest: true
}, () = {
  // execute code with new parameters temporarily applied
  program.draw(...);
  // ...
  // parameters will be restored even the function throws an exception
  if (...) {
    throw new Error('Exception after setting parameters');
  }

  // Return value of the function will be returned from `withParameters`
  return true;
});

// previous parameters are restored here

Functions

getParameters

Gets the values of a gl context parameter.

getParameters(gl, values)

• gl {WebGLRenderingContext} - context
• values= {Object | GLenum[] | null} - parameters, either as keys in object or elements of array. Defaults to all parameters. Returns {Object} - object with keys and values corresponding to supplied parameter names and the current values of those parameters.

setParameters

Sets a number of parameters.

setParameters(gl, {key: value, ...})

• gl {WebGLRenderingContext} - context
• key {String} - parameter names, (, either )luma.gl setting name or a GL parameter constants
• value {} - parameter value Returns {} - "normalized" parameter value after assignment

Note:

• If both luma.gl setting names and GL parameter constants representing the same value are submitted the results are undefined.
• value may be "normalized" (in case a short form is supported). In that case the normalized value is returned.

resetParameters

resetParameters(gl)

Resets all gl context parameters to default values.

• gl {WebGLRenderingContext} - context Returns no value.

Note that technically, resetting context parameters does not fully reset the context, as buffer binding, z buffer values etc are not reset.

withParameters

Executes a function after temporarily setting the parameters. Will restore the parameters to their previously value after the completion of the function, even if the function exits with an exception.

withParameters(gl, {...params}, func)

• gl {WebGLRenderingContext} - context
• params {Object} - any parameter names accepted by setParameters

Returns: the value returned by func, if any.

Parameters

Describes luma.gl setting names and values

Blending

Clear Color

Color Mask

Depth Test

Derivative Hints (WebGL 2 or extension)

Requires WebGL 2 or OES_standard_derivatives.

Hints

Dithering

• Note: Dithering is driver dependent and typically has a stronger effect when the color components have a lower number of bits.

Face Culling

Cull Face Modes

Face orientation

MipmapHint

Hint for quality of images generated with glGenerateMipmap

Mipmap Hints

LineWidth

Line widths are between 1 and GL.ALIASEDLINEWIDTH_RANGE.

Example:

// Set viewport to maximum supported size
const lineWidthRange = getLimits(gl)[GL.ALIASED_LINE_WIDTH_RANGE];
setState(gl, {
  lineWidth: lineWidthRange[1]
});

• Note: Line widths will be clamped to [1, GL.ALIASED_LINE_WIDTH_RANGE]. This is different from gl.lineWidth which generates errors on lineWidth 0.
• Caution: line aliasing is driver dependent and GL.LINES may not give desired results.

PolygonOffset

Add small offset to fragment depth values (by factor × DZ + r × units) Useful for rendering hidden-line images, for applying decals to surfaces, and for rendering solids with highlighted edges.

• Note: The semantics of polygon offsets are loosely specified by the WebGL standard and results can thus be driver dependent.

Rasterization (WebGL 2)

Primitives are discarded immediately before the rasterization stage, but after the optional transform feedback stage. gl.clear() commands are ignored.

Sampling

Specify multisample coverage parameters

Scissor Test

Settings for scissor test and scissor box.

Stencil Test

Setting any value will enable stencil testing (i.e. enable GL.STENCIL_TEST).

Stencil Test Functions

Values for GL.STENCIL_TEST

Stencil Operations

Action when the stencil test fails, front and back.

• stencil test fail action,
• depth test fail action,
• pass action

Viewport

Specifies the transformation from normalized device coordinates to window/framebuffer coordinates. The maximum supported value, is defined by the GL.MAX_VIEWPORT_DIMS limit.

Example:

// Set viewport to maximum supported size
const maxViewport = getLimits(gl)[GL.MAX_VIEWPORT_DIMS];
setState(gl, {
  viewport: [0, 0, maxViewport[0], maxViewport[1]]
});

Pixel Pack/Unpack Modes

Specifies how bitmaps are written to and read from memory

Pixel Pack/Unpack Modes WebGL 2

Specifies how bitmaps are written to and read from memory

Remarks

WebGL State Management can be quite complicated.

• A large part of the WebGL API is devoted to parameters. When reading, querying individual values using GL constants is the norm, and when writing, special purpose functions are provided for most parameters. luma.gl supports both forms for both reading and writing parameters.
• Reading values from WebGL can be very slow if it requires a GPU roundtrip. To get around this, luma.gl reads values once, caches them and tracks them as they are changed through luma functions. The cached values can get out of sync if the context is shared outside of luma.gl.
• luma.gl's state management enables "conflict-free" programming, so that even when setting global state, one part of the code does not need to worry about whether other parts are changing the global state.
• Note that to fully support the conflict-free model and detect changes done e.g. in other WebGL libraries, luma.gl needs to hook into the WebGL context to track state changes.