mozilla

Revision 37473 of Getting started with WebGL

  • Revision slug: WebGL/Getting_started_with_WebGL
  • Revision title: Getting started with WebGL
  • Revision id: 37473
  • Created:
  • Creator: krabsatt
  • Is current revision? No
  • Comment 3 words added, 5 words removed

Revision Content

{{ gecko_minversion_header("2.0") }}

{{ Next("WebGL/Adding 2D content to a WebGL context") }}

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.

Note: If WebGL isn't working for you, make sure the preference webgl.enabled_for_all_sites is set to true. This is the default setting starting with nightly builds from September 17th or so, as well as for Firefox 4.0 beta 8.

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) {
  gl = null;
  
  try {
    gl = 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.

{{ Next("WebGL/Adding 2D content to a WebGL context") }}

{{ languages( { "de": "de/WebGL/Einführung_in_WebGL" } ) }}

Revision Source

<p>{{ gecko_minversion_header("2.0") }}</p>
<p>{{ Next("WebGL/Adding 2D content to a WebGL context") }}</p>
<p><a class=" external" href="http://www.khronos.org/webgl/" title="http://www.khronos.org/webgl/">WebGL</a> enables web content to use an API based on <a class=" external" href="http://www.khronos.org/opengles/" title="http://www.khronos.org/opengles/">OpenGL ES</a> 2.0 to perform 3D rendering in an HTML <a href="/en/HTML/Canvas" title="en/HTML/Canvas"><code>canvas</code></a> in browsers that support it.</p>
<div class="note"><strong>Note:</strong> If WebGL isn't working for you, make sure the preference <code>webgl.enabled_for_all_sites</code> is set to <code>true</code>. This is the default setting starting with nightly builds from September 17th or so, as well as for Firefox 4.0 beta 8.</div>
<p>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.</p>
<h2>Preparing to render in 3D</h2>
<p>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 <code>onload</code> event handler that will be used to initialize our WebGL context.</p>
<pre class="brush: html">&lt;body onload="start()"&gt;
  &lt;canvas id="glcanvas" width="640" height="480"&gt;
    Your browser doesn't appear to support the HTML5 &lt;code&gt;&amp;lt;canvas&amp;gt;&lt;/code&gt; element.
  &lt;/canvas&gt;
&lt;/body&gt;
</pre>
<h3>Preparing the WebGL context</h3>
<p>The <code>start()</code> 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.</p>
<pre class="brush: js">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.
  }
}
</pre>
<p>The first thing we do here is obtain a reference to the canvas, stashing it in a variable called <code>canvas</code>. 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.</p>
<p>Once we have the canvas, we call a function called <code>initWebGL()</code>; this is a function we'll define momentarily; its job is to initialize the WebGL context.</p>
<p>If the context is successfully initialized, <code>gl</code> 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.</p>
<p>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.</p>
<h3>Creating a WebGL context</h3>
<p>The <code>initWebGL()</code> function looks like this:</p>
<pre class="brush: js">function initWebGL(canvas) {
  gl = null;
  
  try {
    gl = 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.");
  }
}

</pre>
<p>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, <code>gl</code> is either null (meaning there is no WebGL context available) or is a reference to the WebGL context into which we'll be rendering.</p>
<div class="note"><strong>Note:</strong> 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.</div>
<p>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.</p>
<p><a href="/samples/webgl/sample1/index.html" title="https://developer.mozilla.org/samples/webgl/sample1/index.html">Try this example live by clicking here</a> if you're running a WebGL compatible browser.</p>
<p>{{ Next("WebGL/Adding 2D content to a WebGL context") }}</p>
<p>{{ languages( { "de": "de/WebGL/Einführung_in_WebGL" } ) }}</p>
Revert to this revision