Creating WebGL context with IEWebGL plugin tutorial
We provide simple and very small WebGLHelper.js library to hide little difference between native WebGL and IEWebGL plugin.
WebGLHelper.js is very convenient - you should not think about stuff like feature detection,
plugin downloading and installation, browser support, plugin updates and error handling.
Let's learn how to use it.
Example 0. How it works
In IE with IEWebGL installed, you create an object element, instead of canvas element as shown below. Then you can get webgl context from that element as usually:
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript">
function InitWebGLContext() {
var glCanvas = document.getElementById("glCanvas");
// first, try standard WebGL context
var gl = glCanvas.getContext("webgl");
if (!gl) {
// if failed, try experimental one
gl = glCanvas.getContext("experimental-webgl");
}
if (!gl) {
alert("Your browser does not support WebGL");
return;
}
// here we get WebGL context -
// for demonstation let's show some info
alert(
"WebGL version=" + gl.getParameter(gl.VERSION) + "\n" +
"WebGL vendor=" + gl.getParameter(gl.VENDOR) + "\n" +
"WebGL renderer=" + gl.getParameter(gl.RENDERER) + "\n"
);
}
</script>
</head>
<body onload="InitWebGLContext()">
<object style="width:100%;height:100%" id="glCanvas"
type="application/x-webgl"></object>
</body>
</html>
Example 1. Inlining into markup
Consider the very simple page with canvas and WebGL context:
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript">
function InitWebGLContext() {
var glCanvas = document.getElementById("glCanvas");
// first, try standard WebGL context
var gl = glCanvas.getContext("webgl");
if (!gl) {
// if failed, try experimental one
gl = glCanvas.getContext("experimental-webgl");
}
if (!gl) {
alert("Your browser does not support WebGL");
return;
}
// here we get WebGL context -
// for demonstation let's show some info
alert(
"WebGL version=" + gl.getParameter(gl.VERSION) + "\n" +
"WebGL vendor=" + gl.getParameter(gl.VENDOR) + "\n" +
"WebGL renderer=" + gl.getParameter(gl.RENDERER) + "\n"
);
}
</script>
</head>
<body onload="InitWebGLContext()">
<canvas style="width:100%;height:100%" id="glCanvas"></canvas>
</body>
</html>
Now lets turn it to use IEWebGL or native WebGL, depending on whether it is supported.
(Note: webglhelper.js is designed so, that if in the future Internet Explorer will support WebGL
natively - the library will choose native WebGL instead of IEWebGL plugin,
so you will not have to change your code to support new browser):
<!DOCTYPE html>
<html>
<head>
<!-- required to use WebGLHelper object -->
<script src="/scripts/webglhelper.js"
type="text/javascript">
</script>
<script type="text/javascript">
function InitWebGLContext() {
var glCanvas = document.getElementById("glCanvas");
// first, try standard WebGL context
var gl = glCanvas.getContext("webgl");
if (!gl) {
// if failed, try experimental one
gl = glCanvas.getContext("experimental-webgl");
}
if (!gl) {
alert("Your browser does not support WebGL");
return;
}
// here we get WebGL context, let's show some info
alert(
"WebGL version=" + gl.getParameter(gl.VERSION) + "\n" +
"WebGL vendor=" + gl.getParameter(gl.VENDOR) + "\n" +
"WebGL renderer=" + gl.getParameter(gl.RENDERER) + "\n"
);
}
function OnGLCanvasCreated(canvasElement, elementId) {
InitWebGLContext();
}
function OnGLCanvasFailed(canvasElement, elementId) {
alert("Your browser does not support WebGL");
}
</script>
</head>
<body>
<script id="WebGLCanvasCreationScript" type="text/javascript"
style="width:100%;height:100%">WebGLHelper.CreateGLCanvasInline(
'glCanvas', OnGLCanvasCreated, OnGLCanvasFailed)
</script>
</body>
</html>
Here we replaced the original <canvas> element with special <script> element. This script creates <canvas> or
<object> in place of itself. It detects if the browser supports WebGL, and if it isn't and browser is IE, it creates <object>
element, that loads IEWebGL plugin.
You see two new functions OnGLCanvasCreated and OnGLCanvasFailed. They are handlers for successful and unsuccessful canvas/object
creation result. The reason for fail can be user's cancellation of the plugin installation in IE.
The handlers are very convenient. All handling of plugin installation, updates and initialization is hidden inside WebGLHelper.js
library, you don't have to worry about all that stuff.
Also, as you see, you can still use style attribute on <script> element, although it can't be applied to <script>
element directly, it is applied (copied) to <canvas> or <object> element by the script.
Separate CSS definitions can also be applied to <canvas> or <object> element, using id ("glCanvas" in this example),
you pass to WebGLHelper.CreateGLCanvasInline().
Using WebGLHelper.js is very easy. If you already have existing WebGL pages and want your site to
work in Internet Explorer and with IEWebGL, only few lines of code are needed! If your user hasn't installed IEWebGL plugin yet, or if
newer IEWebGL plugin version is available, the browser will propose to install or update plugin.
In all other WebGL capable browsers there will be no superfluous messages.
Example 2. Creating canvas and getting WebGL context from JavaScript
The Example 1 shows declarative style of creating canvas, but you may decide to create canvas from JavaScript. Lets look the sample page code:
<!DOCTYPE html>
<html>
<head>
<script src="/scripts/webglhelper.js"
type="text/javascript">
</script>
</head>
<script type="text/javascript">
function InitWebGLContext() {
var glCanvas = document.getElementById("glCanvas");
// first, try standard WebGL context
var gl = glCanvas.getContext("webgl");
if (!gl) {
// if failed, try experimental one
gl = glCanvas.getContext("experimental-webgl");
}
if (!gl) {
alert("Your browser does not support WebGL");
return;
}
// here we get WebGL context, let's show some info
alert(
"WebGL version=" + gl.getParameter(gl.VERSION) + "\n" +
"WebGL vendor=" + gl.getParameter(gl.VENDOR) + "\n" +
"WebGL renderer=" + gl.getParameter(gl.RENDERER) + "\n"
);
}
function OnGLCanvasCreated(canvasElement, elementId) {
InitWebGLContext();
}
function OnGLCanvasFailed(canvasElement, elementId) {
alert("Your browser does not support WebGL");
}
function Init() {
var cnv = WebGLHelper.CreateGLCanvas(
document.getElementById('renderArea'),
'glCanvas', false, OnGLCanvasCreated, OnGLCanvasFailed);
}
</script>
</head>
<body onload="Init()">
<div id="renderArea">
<!-- we want to create canvas inside this div, using JavaScript -->
</div>
</body>
</html>
This example creates child element (<canvas> or <object>, depending of browser capabilities) inside parent <div>.
Init() function is executed after browser finished loading the page body and WebGLHelper.CreateGLCanvas() creates
canvas using the same handlers as in previous sample.
Example 3. Creating WebGL context with helper
Different browser vendors use the "exprimental-" prefix while their WebGL implementations evolve, so to be ready for final implementations,
we should write code, that tries to create WebGL context, using standard context name that is "webgl", and "experimental-webgl".
WebGLHelper.js have the utility function for that. Let's look the sample code.
<!DOCTYPE html>
<html>
<head>
<!-- required to use WebGLHelper object -->
<script src="/scripts/webglhelper.js"
type="text/javascript">
</script>
<script type="text/javascript">
function InitWebGLContext() {
var gl = WebGLHelper.GetGLContext(
document.getElementById("glCanvas"));
if (!gl) {
alert("Your browser does not support WebGL");
return;
}
// here we get WebGL context, let's show some info
alert(
"WebGL version=" + gl.getParameter(gl.VERSION) + "\n" +
"WebGL vendor=" + gl.getParameter(gl.VENDOR) + "\n" +
"WebGL renderer=" + gl.getParameter(gl.RENDERER) + "\n"
);
}
function OnGLCanvasCreated(canvasElement, elementId) {
InitWebGLContext();
}
function OnGLCanvasFailed(canvasElement, elementId) {
alert("Your browser does not support WebGL");
}
</script>
</head>
<body>
<script id="WebGLCanvasCreationScript" type="text/javascript"
style="width:100%;height:100%">WebGLHelper.CreateGLCanvasInline(
'glCanvas', OnGLCanvasCreated, OnGLCanvasFailed)
</script>
</body>
</html>
This example is slightly modified version of the Example 2.
If neither standard, nor experimental WebGL context can be created, WebGLHelper.CreateGLContext() returns null;
Example 4. Styling plugin loading screen
When IE user comes to IEWebGL compatible site for the first time, he sees the plugin loading splash screen,
you can adapt this screen to your site's look and feel, by using special property of WebGLHelper object.
<!DOCTYPE html>
<html>
<head>
<!-- required to use WebGLHelper object -->
<script src="/scripts/webglhelper.js"
type="text/javascript">
</script>
<script type="text/javascript">
function OnGLCanvasCreated(canvasElement, elementId) {
}
function OnGLCanvasFailed(canvasElement, elementId) {
}
</script>
</head>
<body>
<script id="WebGLCanvasCreationScript" type="text/javascript"
style="width:100%;height:100%">
WebGLHelper.autoLoadScreen.innerHTML = "DEMO DESIGN HERE";
WebGLHelper.CreateGLCanvasInline(
'glCanvas', OnGLCanvasCreated, OnGLCanvasFailed);
</script>
</body>
</html>
Non-standard behaviour
1. Texturing
IE6, IE7 and IE8 browsers do not support HTML5 video and canvas so textures can't be created from that objects.
2. Events
In IE6, IE7 and IE8 WebGL's "webglcontextcreationerror", "webglcontextlost" and "webglcontextrestored" events are
emulated using "onerror" event. To distinguish WebGL event from others, check the "webglEventType" property of
the event object, it contains the name of WebGL event.
3. Draw canvas to canvas
HTML canvas specification says that you can draw image from one canvas to another canvas using 2d context's
drawImage() method. As specification says drawImage() can draw image, canvas or video elements. As you know,
IEWebGL plugin is actually an object element, so it can't be drawn to regular canvas directly.
Here we show the way how to use non-standard IEWebGL extension to achieve the same result.
function CopyCanvas() {
var nativeCnv = document.getElementById("nativeCanvas");
nativeCnv.width = nativeCnv.scrollWidth;
nativeCnv.height = nativeCnv.scrollHeight;
var webglCnv = document.getElementById("webglCanvas");
var ctx2D = nativeCnv.getContext("2d");
// standard way
// ctx2D.drawImage(webglCnv, 0, 0);
// IEWebGL extension way
webglCnv.updateNativeCanvas();
ctx2D.drawImage(webglCnv.getNativeCanvas(), 0, 0);
}
The webglCnv.updateNativeCanvas() call updates hidden canvas created by IEWebGL plugin with current IEWebGL plugin picture.
The webglCnv.getNativeCanvas() method returns the hidden canvas object, and you can use it anythere as any other native canvas.
4. Read binary data from XMLHTTPRequest object in IE8 and IE9 (as they do not support .responseType="arraybuffer")
Using IEWebGL you can create any TypedArray object from xhr.responseBody:
function loadArrayBuffer(uri, callback) {
var xhr = new XMLHttpRequest();
xhr.open('GET', uri, true);
//xhr.responseType = "arraybuffer"; // for modern browsers
xhr.onreadystatechange = function(e) {
if (xhr.readyState == 4 && xhr.status == 200) {
var byteView = new Uint8Array(xhr.responseBody); // for IE8 and IE9
callback(byteView.buffer);
//callback(xhr.response); // for modern browsers
}
}
xhr.send(null);
}
