Chevron Down
Table of Contents

Context Management

gltools provides functions to initialize, instrument and manipulate WebGL contexts.

Usage

Create a WebGL context, autocreating a canvas

import {createGLContext} from '@luma.gl/gltools';
const gl = createGLContext(); // Prefers WebGL 2 but falls back to WebGL 1

Create a WebGL 2 context.

import {createGLContext} from '@luma.gl/gltools';
const gl = createGLContext({
  webgl1: false,
  throwOnError: false
});
if (!gl) {
  console.error('WebGL 2 not supported');
}

Polyfill a WebGL context with features available in extensions.

import {polyfillContext} from '@luma.gl/gltools';

const gl = canvas.createContext('webgl'); // A WebGL 1 context
polyfillContext(gl);

// Using extension via WebGL 2 API
const vao = gl.createVertexArray();

Instrument an externally-created context to work with other luma.gl classes.

import {instrumentGLContext} from '@luma.gl/gltools';
import {Model} from '@luma.gl/engine';

const gl = canvas.createContext('webgl');

instrumentGLContext(gl);

// Instrumentation ensures the context works with higher-level classes.
const model = new Model(gl, options);

Functions

createGLContext

Creates and returns a WebGL context, both in browsers and in Node.js.

const gl = createGLContext(options);
  • options (Object) - key/value pairs containing context creation options
ParameterDefaultDescription
webgl2trueIf true, will attempt to create a WebGL 2 context. Will silently fall back to WebGL 1 contexts unless webgl1 is set to false.
webgl1trueIf true, will attempt to create a WebGL 1 context. The webgl2 flag has higher priority.
throwOnErrortrueNormally the context will throw an error on failure. If false, it will log to console instead.
break[]Insert a break point (debugger) if one of the listed gl functions is called.
manageStatetrueInstrument the context to enable state caching and withParameter calls. Leave on unless you have special reasons not to.
debugfalseWebGL API calls will be logged to the console and WebGL errors will generate JavaScript exceptions. NOTE: requires importing @luma.gl/debug.
canvasnullA string containing the id of an existing HTML element or a DOMElement instance. If null or not provided, a new canvas will be created.
alphatrueDefault render target has an alpha buffer.
depthtrueDefault render target has a depth buffer of at least 16 bits.
stencilfalseDefault render target has a stencil buffer of at least 8 bits.
antialiastrueBoolean that indicates whether or not to perform anti-aliasing.
premultipliedAlphatrueBoolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha.
preserveDrawingBufferfalseDefault render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten
failIfMajorPerformanceCaveatfalseDo not create if the system performance is low.

instrumentGLContext

Instrument an externally-created context with the same options as createGLContext. This performs WebGL 2 polyfilling (which is required for higher-level luma.gl classes) as well as optional state tracking and debug context creation.

instrumentGLContext(gl, options);
  • gl (Object) - An externally-created WebGL context.
  • options (Object) - key/value pairs containing context creation options (same as for createGLContext).

polyfillContext

Polyfill a WebGL context integrating available extensions.

polyfillContext(gl)
  • gl {WebGLRenderingContext} - A WebGL context

resizeGLContext

Resize the drawing surface.

resizeGLContext(gl, options);
  • gl (Object) - A WebGL context.
  • options (Object) - key/value pairs containing resize options.

    • width: New drawing surface width.
    • height: New drawing surface height.
    • useDevicePixels: Whether to scale the drawing surface using the device pixel ratio.

getContextDebugInfo

Get debug information about a WebGL context. Depends on WEBGL_debug_renderer_info extension.

getContextDebugInfo(gl)

  • gl (Object) - A WebGL context.

Returns (Object):

  • vendor: GPU vendor (unmasked if possible)
  • renderer: Renderer (unmasked if possible)
  • vendorMasked: Masked GPU vendor
  • rendererMasked: Masked renderer
  • version: WebGL version
  • shadingLanguageVersion: shading language version

isWebGL

Test if an object is a WebGL 1 or 2 context, including correctly identifying a luma.gl debug context (which is not a subclass of a WebGLRendringContext).

isWebGL(gl)

  • gl (Object) - Object to test. Returns true if the context is a WebGL 1 or 2 Context.

isWebGL2

Test if an object is a WebGL 1 or 2 context, including correctly identifying a luma.gl debug context (which is not a subclass of a WebGL2RendringContext).

isWebGL2(gl)

  • gl (Object) - Object to test. Returns true if the context is a WebGL 2 Context.