Getting started with WebGL

  • Revision slug: Web/WebGL/Getting_started_with_WebGL
  • Revision title: Getting started with WebGL
  • Revision id: 470149
  • Created:
  • Creator: ChaitanyaGSNR
  • Is current revision? No
  • Comment

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 without the use of plug-ins. WebGL programs consist of control code written in JavaScript and special effects code(shader code) that is executed on a computer's Graphics Processing Unit (GPU). WebGL elements can be mixed with other HTML elements and composited with other parts of the page or page background.

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.

Resizing the WebGL context

A new WebGL context will set its viewport resolution to the height and width of its canvas element, without CSS, at the instant the context was obtained. Editing the style of a canvas element will change its displayed size but will not change its rendering resolution. Editing the width and height attributes of a canvas element after the context has been created will also not change the number of pixels to be drawn. To change the resolution which WebGL renders at, such as when the user resizes the window of a full-document canvas or you wish to provide in-app adjustable graphics settings, you will need to call the WebGL context's viewport() function to acknowledge the change.

To modify the rendered resolution of a WebGL context with variables gl and canvas as used in the above example:

gl.viewport(0, 0, canvas.width, canvas.height);

A canvas that is rendered at a different resolution than its CSS style will experience scaling. Resizing with CSS is mostly useful to save resources by rendering at a low resolution and allowing the browser to upscale; downscaling is possible which would produce a super sample antialiasing effect albeit with naive results and a severe performance cost. It is often best to rely upon the MSAA and texture filtering implementations of the user's browser, if available and appropriate.

{{ Next("WebGL/Adding_2D_content_to_a_WebGL_context") }}

{{ languages( { "de": "de/WebGL/Einführung_in_WebGL", "fr": "fr/WebGL/Commencer_avec_WebGL", "ja": "ja/WebGL/Getting_started_with_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&nbsp;based on <a class="external" href="http://www.khronos.org/opengles/" title="http://www.khronos.org/opengles/">OpenGL&nbsp;ES</a> 2.0 to perform 3D rendering in an HTML&nbsp;<a class="internal" href="/en/HTML/Canvas" title="en/HTML/Canvas"><code>canvas</code></a> in browsers that support it without the use of plug-ins. WebGL programs consist of control code written in JavaScript and special effects code(shader code) that is executed on a computer's Graphics Processing Unit (GPU). WebGL elements can be mixed with other HTML elements and composited with other parts of the page or page background.</p>
<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 id="Preparing_to_render_in_3D">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&nbsp;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 id="Preparing_the_WebGL.C2.A0context">Preparing the WebGL&nbsp;context</h3>
<p>The <code>start()</code>&nbsp;function, in our JavaScript code, is called after the document is loaded. Its mission is to set up the WebGL&nbsp;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.
&nbsp; }
}
</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 id="Creating_a_WebGL.C2.A0context">Creating a WebGL&nbsp;context</h3>
<p>The <code>initWebGL()</code>&nbsp;function looks like this:</p>
<pre class="brush: js">
function initWebGL(canvas) {
  // Initialize the global variable gl to null.
  gl = null;
  
  try {
&nbsp; &nbsp;&nbsp;// Try to grab the standard context. If it fails, fallback to experimental.
&nbsp;&nbsp;&nbsp; gl = canvas.getContext("webgl") || canvas.getContext("experimental-webgl");
&nbsp; }
&nbsp; 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&nbsp;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>
<h3 id="Resizing_the_WebGL_context">Resizing the WebGL context</h3>
<p>A new WebGL context will set its viewport resolution to the height and width of its canvas element, without CSS, at the instant the context was obtained. Editing the style of a canvas element will change its displayed size but will not change its rendering resolution. Editing the width and height attributes of a canvas element after the context has been created will also not change the number of pixels to be drawn. To change the resolution which WebGL renders at, such as when the user resizes the window of a full-document canvas or you wish to provide in-app adjustable graphics settings, you will need to call the WebGL context's <code>viewport()</code> function to acknowledge the change.</p>
<p>To modify the rendered resolution of a WebGL context with variables <code>gl</code> and <code>canvas</code> as used in the above example:</p>
<pre class="brush: js">
gl.viewport(0, 0, canvas.width, canvas.height);</pre>
<p>A canvas that is rendered at a different resolution than its CSS style will experience scaling. Resizing with CSS is mostly useful to save resources by rendering at a low resolution and allowing the browser to upscale; downscaling is possible which would produce a super sample antialiasing effect albeit with naive results and a severe performance cost. It is often best to rely upon the MSAA and texture filtering implementations of the user's browser, if available and appropriate.</p>
<p>{{ Next("WebGL/Adding_2D_content_to_a_WebGL_context") }}</p>
<p>{{ languages( { "de": "de/WebGL/Einführung_in_WebGL", "fr": "fr/WebGL/Commencer_avec_WebGL", "ja": "ja/WebGL/Getting_started_with_WebGL" } ) }}</p>
Revert to this revision