Setting Context Attributes in WebGL

When initializing a WebGL rendering context, you can customize performance, graphics capabilities, and buffer behavior by passing an optional configuration object to the canvas context retrieval method. This guide details how to supply context attributes using JavaScript, explores the most commonly used configuration properties, and demonstrates how to verify which attributes your graphics hardware successfully applied.

Passing Context Attributes

To specify context attributes, pass a configuration object as the second argument to canvas.getContext(). This applies to both WebGL 1.0 ("webgl") and WebGL 2.0 ("webgl2").

const canvas = document.getElementById("glCanvas");

const contextAttributes = {
  alpha: false,
  antialias: true,
  depth: true,
  stencil: false,
  premultipliedAlpha: true,
  preserveDrawingBuffer: false,
  powerPreference: "high-performance",
  failIfMajorPerformanceCaveat: false,
  desynchronized: false
};

const gl = canvas.getContext("webgl2", contextAttributes) || canvas.getContext("webgl", contextAttributes);

if (!gl) {
  console.error("WebGL is not supported or initialization failed with the given attributes.");
}

Key Context Attributes

The configuration dictionary accepts several standard properties:

  • alpha (Boolean, default: true): Determines whether the drawing buffer has an alpha channel for compositing with the rest of the web page. Setting this to false can improve rendering performance if transparency behind the canvas is not needed.
  • antialias (Boolean, default: true): Requests multi-sample anti-aliasing (MSAA) for smoother edges. If the hardware does not support it or resources are limited, anti-aliasing may remain disabled.
  • depth (Boolean, default: true): Creates a 16-bit or 24-bit depth buffer to enable depth testing (gl.DEPTH_TEST). Disable this if your application renders purely 2D graphics to save memory.
  • stencil (Boolean, default: false): Allocates an 8-bit stencil buffer for masking and stencil operations (gl.STENCIL_TEST).
  • preserveDrawingBuffer (Boolean, default: false): Controls whether the buffers retain their values after being displayed. If set to false, the buffer is cleared automatically before each compositing step. Set to true if you need to capture screenshots using canvas.toDataURL().
  • powerPreference (String, default: "default"): Provides a hint to the user agent on dual-GPU systems (such as laptops). Accepts "default", "high-performance" (dedicated GPU), or "low-power" (integrated GPU).
  • failIfMajorPerformanceCaveat (Boolean, default: false): When set to true, context creation will fail if the system only supports software emulation or a significantly slow fallback driver.
  • desynchronized (Boolean, default: false): Reduces rendering latency by bypassing the traditional compositor synchronization pipeline, often useful for drawing or stylus applications.

Querying the Actual Attributes

Supplying attributes is considered a request; the underlying platform may override settings based on driver limitations. You can verify the final configuration using gl.getContextAttributes():

const actualAttributes = gl.getContextAttributes();
console.log("Antialiasing enabled:", actualAttributes.antialias);
console.log("Depth buffer available:", actualAttributes.depth);