2.5 - Canvas and GL Context¶

Getting the Canvas Element¶

Using JavaScript, you need to get the canvas element you want to draw into. If there is only one canvas element on the web page, you could get the element by its type. But a more general scheme, which supports multiple canvas elements on a single web page, is to use a unique id for the canvas. The standard HTML code for defining a canvas element is shown below. If a browser does not support canvas elements, it will display the message inside the <canvas> tags. Otherwise it will display a rectangular region on the page. Notice that the canvas element is assigned a unique ID.

<canvas id="W1_canvas">
  Please use a browser that supports "canvas"
</canvas>

In JavaScript, after a web page has been loaded, you can get a canvas element using the document.getElementById(id) function. You should handle errors appropriately, so a function like this would be typical.

/**
 * Get a canvas element given its unique id
 *
 * @param canvas_id The HTML id of the canvas to render to.
 * @return the matching canvas element
 */
function getCanvas(canvas_id) {
  var canvas;

  canvas = document.getElementById(canvas_id);
  if (!canvas || canvas.nodeName !== "CANVAS") {
    console.log('Fatal error: Canvas "' + canvas_id + '" could not be found');
  }
  return canvas;
}

Getting the WebGL Context¶

Now that we have an object that represents the canvas element, we use a method of the object called getContext('webgl') to get a WebGL object that represents the 3D graphics state and behavior of the canvas. Again we should handle errors appropriately.

/**
 * Get a WebGL context from a canvas
 *
 * @param canvas The DOM element that represents the canvas.
 * @return The WebGL context for the canvas.
 */
function getWebglContext(canvas) {
  var context;

  context = canvas.getContext('webgl');
  if (!context) {
    console.log("No WebGL context could be found.");
  }

  return context;
};

The WebGL Context¶

The WebGL context is a JavaScript object that stores the current state of the graphics library. WebGL is a state machine. That means that if you set a WebGL variable to a specific value, that value will not change until you change it. For example, you can set the color used to clear the canvas background once. You don’t need to set the color value every time you want to clear the window.

The WebGL context object also defines methods for the entire WebGL API. All WebGL functionality is accessed through the context object. The convention is to name the context object gl. Below is a typical start to a WebGL program.

// Get the rendering context for the canvas
gl = getWebglContext( getCanvas(canvas_id) );
if (!gl) {
  return null;
}

// Initialize the state of the WebGL context
gl.useProgram(program);
gl.enable(gl.DEPTH_TEST);
gl.clearColor(0.9, 0.9, 0.9, 1.0);

Notice that all WebGL functionality is accessed through the gl object.

Each canvas has its own WebGL context. If you have 4 canvas elements on a web page, you will have to store 4 separate WebGL contexts. And regrettably for WebGL 1.0, context’s can’t share data or shader programs between themselves. Supposedly future versions of WebGL will allow sharing of resources between contexts.

Glossary¶

canvas

a type of HTML element. It defines a rectangular area in a web page on which generated graphics can be displayed.

context

the environment in which something happens.

WebGL context

a JavaScript object that stores the state of a WebGL program and provides an interface to all WebGL API functions.