Getting started with WebGL

Introduced in Gecko 2.0

(Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)


WebGL enables web content to use an API based on OpenGL ES 2.0 to perform 3D rendering in an HTML canvas in browsers that support it.

This article will introduce you to the basics of using WebGL. It's assumed that you already have an understanding of the mathematics involved in 3D graphics, and this article doesn't pretend to try to teach you OpenGL itself.

Preparing to render in 3D

The first thing you need in order to use WebGL to render in 3D is a canvas. The HTML fragment below establishes a canvas and sets up an onload event handler that will be used to initialize our WebGL context.

<body onload="start()">
  <canvas id="glcanvas" width="640" height="480">
    Your browser doesn't appear to support the HTML5 <code>&lt;canvas&gt;</code> element.
  </canvas>
</body>

Preparing the WebGL context

The start() function, in our JavaScript code, is called after the document is loaded. Its mission is to set up the WebGL context and start rendering content.

function start() {
  var canvas = document.getElementById("glcanvas");

  initWebGL(canvas);      // Initialize the GL context
  
  // Only continue if WebGL is available and working
  
  if (gl) {
    gl.clearColor(0.0, 0.0, 0.0, 1.0);                      // Set clear color to black, fully opaque
    gl.enable(gl.DEPTH_TEST);                               // Enable depth testing
    gl.depthFunc(gl.LEQUAL);                                // Near things obscure far things
    gl.clear(gl.COLOR_BUFFER_BIT|gl.DEPTH_BUFFER_BIT);      // Clear the color as well as the depth buffer.
  }
}

The first thing we do here is obtain a reference to the canvas, stashing it in a variable called canvas. Obviously if you don't need to repeatedly reference the canvas, you should avoid saving this value globally, and just save it in a local variable or member field of an object.

Once we have the canvas, we call a function called initWebGL(); this is a function we'll define momentarily; its job is to initialize the WebGL context.

If the context is successfully initialized, gl is a reference to it. In this case, we set the clear color to black, then clear the context to that color. After that, the context is configured by setting parameters. In this case, we're enabling depth testing and specifying that closer objects will obscure objects that are farther away.

For the purposes of this initial pass at the code, that's all we're going to do. We'll look at how to actually start doing something a little later.

Creating a WebGL context

The initWebGL() function looks like this:

function initWebGL(canvas) {
  // Initialize the global variable gl to null.
  gl = null;
  
  try {
    // Try to grab the standard context. If it fails, fallback to experimental.
    gl = canvas.getContext("webgl") || canvas.getContext("experimental-webgl");
  }
  catch(e) {}
  
  // If we don't have a GL context, give up now
  if (!gl) {
    alert("Unable to initialize WebGL. Your browser may not support it.");
  }
}

To obtain a WebGL context for a canvas, we request the context named "webgl" from the canvas. If this fails, we try the name "experimental-webgl". If that, too, fails, we display an alert letting the user know they appear not to have WebGL support. That's all there is to it. At this point, gl is either null (meaning there is no WebGL context available) or is a reference to the WebGL context into which we'll be rendering.

Note: The context name "experimental-webgl" is a temporary name for the context for use during development of the specification; the name "webgl" will be used once the spec is finalized.

At this point, you have enough code that the WebGL context should successfully initialize, and you should wind up with a big black, empty box, ready and waiting to receive content.

Try this example live by clicking here if you're running a WebGL compatible browser.


Tags (2)

Edit tags

Attachments (1)

FileSizeDateAttached by 
sample1.html
Fix so code matches. Changed CSS to work on more browsers. Changed background to show bugs. Changed initWebGL to keep working. I feel like the gl.depthFunc is not needed but left it in for further comment
2028 bytes16:41, 9 Dec 2011arnaudbrousseauActions

Attach file