Controlling the renderer state

Ogma provides three types of renderer: WebGL, Canvas and SVG. WebGL is the default one, and offers by far the best performance. But it can happen that the WebGL renderer is unavailable, usually because of one of the following reasons:

• The browser does not support WebGL (for example IE 10 and older)
• The hardware doesn't have a GPU (even integrated), or the GPU is blacklisted by the browser
• A specific hardware/software configuration is incorrectly handled by Ogma

If the WebGL render is unavailable, Ogma will automatically switch to the Canvas renderer with a message in the console. But it can be useful to programmatically know when and why the renderer is not available. For that purpose, Ogma provides the rendererStateChange event:

ogma.events.on('rendererStateChange', function (evt) {
  console.log('renderer "' + evt.type + '" entered state "' + evt.state + '"');

  if (evt.state === 'error') {
    console.log('  - code: ' + evt.code);
    console.log('  - message: ' + evt.message);
  }
});

When ogma is initialized, if WebGL is available you should get this in the console:

renderer "webgl" entered state "requested"
renderer "webgl" entered state "ok"

If WebGL is not available (e.g IE 10), you should get this in the console:

renderer "webgl" entered state "requested"
renderer "webgl" entered state "error"
  - code: NO_WEBGL
  - message: Unable to create a WebGL context: `canvas.getContext("webgl")` and `canvas.getContext("experimental-webgl")` returned `null`
renderer "canvas" entered state "requested"
renderer "canvas" entered state "ok"

Notice that the canvas renderer is requested as soon as the WebGL renderer is unavailable.

evt.type indicates the type of renderer and can have 4 values: "webgl", "canvas", "svg" or null (headless renderer, used by default in Node.js).

evt.state can have three values:

• "requested": the renderer is not initialized yet, Ogma will try to initialize it
• "ok": the renderer has been successfully initialized and is running normally
• "error": the renderer has encountered an error and will stop

The only renderer that can be in the error state is the WebGL renderer. When that happens, evt.code gives information on why the renderer is unavailable:

• "NO_WEBGL": the browser or hardware does not support WebGL
• "NO_ANGLE_INSTANCED_ARRAYS": the browser or hardware does not support the ANGLE_instanced_arrays WebGL extension that is used by Ogma
• "OTHER": unexpected error, if that happens contact support@linkurio.us

evt.message is a string indicating the exact meaning of the error code (or the stacktrace if the error is unexpected).

Side note: it's possible to change renderer at runtime with:

ogma.setOptions({ renderer: 'canvas' });

Where the value of renderer can be "webgl", "canvas", "svg" or null.