Lesson 0: Getting started with WebGL

Lesson 1 >>

[This post has been updated several times since it was originally written, as things have moved on a bit since it was originally published in October 2009... to the best of my knowledge, information is correct as of 17 January 2012.]

The first step in trying out WebGL is to get a browser that supports it. How you do that depends on whether you want to look at cool WebGL demos or develop your own.

Keeping it simple

In general, I recommend that if you want to take a look at cool WebGL demos and aren’t really worried about developing your own, and don’t really care that some of the very latest stuff might not work, then:

  • If you’re on Windows, make sure you have the Microsoft DirectX runtime installed — this is a free download from Microsoft.
  • Once you’ve done that, make sure that you’ve got the very latest versions of the drivers for your graphics card.
  • Next, choose your browser:
    • Firefox: just make sure you have version 4 or higher.
    • Chrome: all you need to do is install it, or if you’re already using it, just check whether it’s updated itself to version 10 — this will almost certainly have happened automatically (it was released in March 2011), but you can check from the “About Google Chrome” option on the tools menu to confirm.
    • Safari: on Macs, OS X 10.7 has WebGL support, but it’s switched off by default. To switch it on, enable the developer menu and check the “Enable WebGL” option. (Thanks to Blah for the heads-up on this one.)

That’s it! You should be good to go. Next, click here to try out some WebGL pages.

Doing it the hard way

If you’re developing WebGL yourself, or if you need the latest features, then nothing beats having the very latest browser. And WebGL is supported in development versions of all of the main browsers apart from Internet Explorer, so all you need to do is get the appropriate version for your machine. How easy this is depends on what kind of computer you have:

  • Windows: If you haven’t already done so, make sure you have the DirectX runtime installed — this is a free download from Microsoft. Once you’ve done that, install either Firefox or Chromium, whichever you prefer — if it doesn’t work, check out the troubleshooting guide. (Stop press: a pre-beta version of Opera that supports WebGL on Windows is now available; it’s less stable than the other browsers, though, so don’t rely on it as your only WebGL implementation. It will also only work if your graphics card supports OpenGL 2.0, so it might be a pain to get working.)
  • Macintosh: if you’re running Snow Leopard (OS X 10.6), things should be fine; I recommend that you use the development version of WebKit, which will run as an alternative version of Safari. If you’re running Leopard (OS X 10.5), then you won’t be able to use that version of WebKit, but you can run either Firefox or Chromium. Snow Leopard users can use Firefox or Chromium too, of course. If you’ve got an older version of OS X, unfortunately I don’t know of any WebGL browser you can use right now :-(
  • Linux: quite a large number of Linux graphics drivers are, sadly, not good enough to work with WebGL. The same used to be the case under Windows, but the browser makers worked around it using DirectX; unfortunately there’s no such escape route for Linux. Here’s what I’ve managed to gather:
    • If you’ve got Nvidia graphics, and recent drivers, then things should work just fine with either Firefox or Chromium.
    • If you have ATI graphics, you’re probably best off with Firefox.
    • If you have Intel graphics, you’re likely to have to use slow software rendering, which sucks but at least lets you see some WebGL stuff; try Firefox or Chromium, but they probably won’t work with the default (hardware rendering) setup. To use software rendering on Linux, you need to make sure that Mesa is installed (you should just be able to get the latest version using your distro’s package manager) and then you can use the latest Firefox with a few extra settings.

    There’s more detail about this in the troubleshooting section below.


The “unstable” development release of Firefox is called Minefield. It’s updated every night, and it’s actually pretty solid right now: I’ve not seen it crash recently (and I use it for everything). It can be installed alongside a regular version of Firefox, too, so you don’t need to worry about uninstalling it if you give up on it, or just want to switch back to the regular version for a while.

To get Minefield:

  • Go to the nightly builds page and get the appropriate version for your machine. Look out! There might be various versions there, with names like firefox-10.0a1something or firefox-10.0a2something. You want the most recent, which will be with the highest number after the ‘a’ (alpha) or ‘b’ (beta).
  • Install it (you’ll need to quit any running Firefox instances while this happens).
  • Start Minefield.

A useful tip — if you want to run Minefield side-by-side with the regular Firefox, you can do this by adding the following command-line parameters: -P Minefield -no-remote. The first parameter makes it run with a separate profile (so that you keep separate histories and sets of active tabs in each browser) and the second means that when you start Minefield while Firefox is already running, it won’t just open a new window in the currently-running Firefox. You might also want to add -P default -no-remote to the parameters for your normal Firefox to do the same there too. Windows users: you can set the command-line parameters for each application by right-clicking on the icon you use to launch it, selecting “Properties”, and adding the parameters to the end of the “Target” field. Mac and Linux users — I don’t know how you do it, but you probably know anyway ;-)

Next, click here to try out some WebGL pages.

Running Minefield with Software Rendering on Linux

If your graphics hardware or — more likely — driver doesn’t support OpenGL 2.0, then right now the only way to get WebGL working on Linux is to use a library called Mesa. Mesa basically emulates a graphics card in software, so it’s a bit slow — but it’s better than nothing. It integrates with Minefield, the “unstable” development release of Firefox, and it’s normally part of your Linux distro. Here’s how to get it working.

  • Download the latest version of Minefield.
  • Install it (you’ll need to quit any running Firefox instances while this happens).
  • Using your Linux distro’s package manager, make sure that you have Mesa installed and updated to the latest version.
  • Start Minefield.
  • Go to the page “about:config”
  • Filter for “webgl”
  • Switch the value “webgl.enabled_for_all_sites” to “true”.
  • Switch the value “webgl.software_rendering” to “true”.
  • Set the “webgl.osmesalib” setting to the location of your OSMesa shared library (normally something like /usr/lib/libOSMesa.so).

Once you’ve done all that, you should be set. Click here to try out some WebGL pages.


Remember, Safari only supports WebGL on Macs running Snow Leopard (OS X 10.6); if you’re on Leopard (10.5), Windows or Linux then you’ll have to use Firefox or Chromium. (If you’re on an older version of OS/X, I don’t know of any browser you can use :-( )

If you are on Snow Leopard, to get it running, you need to:

  • Make sure you have at least version 4 of Safari.
  • Download and install the WebKit nightly build.
  • Start up a Terminal, and in it run this command:
    defaults write com.apple.Safari WebKitWebGLEnabled -bool YES
  • Run the freshly-installed WebKit application.

Next, click here to try out some WebGL pages.


The way the Chrome developers currently recommend you get WebGL in Chrome, if you’re doing WebGL development, is to use a nightly build of Chromium, the open source browser on which Chrome is based. The procedure is a little different for each supported operating system; here are instructions for Windows, Macintosh, and Linux. (A warning — I’ve only tried the Windows version myself, but I’m told the other versions work fine too. Leave a comment below if I’m wrong on that :-)

For Windows

  • Go to the continuous integration page, scroll down to the most recent build (at the bottom), click on the link, and get chrome-win32.zip
  • Unzip the file somewhere convenient.
  • Inside the unpacked directory, double-click the chrome.exe file.

For the Macintosh

  • Go to the continuous integration page, scroll down to the most recent build (at the bottom), click on the link, and get chrome-mac.zip
  • Unzip the file somewhere convenient.
  • Open a Terminal window, and go to the chrome-mac directory that you unzipped.
  • Make sure you’re not running Chrome already
  • Run the following command:
  • Once you’ve checked that it works, you might want to automate things a bit so that you don’t have to type the command line every time; in the comments, Julien Limoges has provided a useful shell script to handle that.

For Linux

  • Go to the 32-bit or the the 64-bit continuous integration page as appropriatescroll down to the most recent build (at the bottom), click on the link, and get chrome-linux.zip.
  • Unzip the file somewhere convenient, and go to the chrome-linux directory that you unzipped in a terminal window.
  • Make sure you’re not running Chrome already
  • Run the following command:

Next, click here to try out some WebGL pages.

Some first examples

Once your browser is installed, you should be able to see WebGL content.  Here’s a first sanity check; WebGL Report, which gives details of the WebGL features enabled on your browser. If it tells you that your browser doesn’t support WebGL, check out the troubleshooting guide below.

If it did work, everything should be set up! Unfortunately some recent changes to WebGL broke many of the demos out there, but here are some that have been updated:

That’s it for my first post on getting started with WebGL. If you want to go further and learn about how to create your own WebGL pages, you can check out my first WebGL lesson.

Lesson 1 >>



I don’t have any useful hints and tips for getting WebGL running on Macs, because no-one’s ever asked me for help and I don’t think I’ve ever seen questions in the forums. I can only assume that this means that Everything Just Works on OS X…


The most common problem for Windows users is that you don’t have the DirectX runtime installed — this is a free download from Microsoft, so give it a go. It might also be worth seeing if there are more up-to-date drivers for your graphics card — check out Windows Update, or perhaps the website of your graphics card manufacturer. If that doesn’t work, it might be that your graphics driver is on a “blacklist”. This is rarer under Windows than under Linux, but has been known to happen. See the Linux instructions below for some hints.


The most common reason for WebGL not working under Linux is problems with graphics drivers. All current Linux browser implementations of WebGL are based on OpenGL, and OpenGL support is something that is provided by your graphics driver. WebGL needs at least OpenGL 2.0 in order to run; in particular, owners of Intel graphics cards have problems because Intel haven’t released drivers for most of their graphics hardware with support for that. If you have Intel graphics, try using Mesa software rendering. If it’s still not working, leave a comment below and I’ll try to help.

If you have ATI or Nvidia graphics, the first thing to do is check the version of OpenGL you have on your machine. To do this, run glxinfo and look for the line headed “OpenGL version string”. If the version number you see is less than 2.0, you’ll need to update your drivers. Check out your computer/graphics card manufacturer’s website, and have a look at distro’s package manager.

If you still can’t get things running, it may be that the browser makers have “blacklisted” your driver; this is because some of them are unstable enough to cause machines to crash, which is understandably not behaviour people want associated with the browser…

In the comments to this post, Nardon gives this update as of 6 October 2011 “Google blacklisted all Linux Drivers, except for the official nVidia Drivers … Firefox 6 and above whitelisted most newer ATI drivers for Linux so you should be able to use WebGL with this browser.”

If you want to risk crashes, and use a blacklisted driver, you can start Chrome with the command-line flag –ignore-gpu-blacklist and see what happens (thanks to Jonas Antunes da Silva for that tip). If it doesn’t fix things, it may just be that a decent Linux OpenGL driver isn’t available for your graphics hardware. Your best bet for now is probably to use software rendering. Once again here are the instructions.


Thanks to Vladimir Vukićević, Mohamed Mansour, Ehsun Amanolahi, and Chris Marrin for the information that made up this page, and all of its many previous incarnations!

You can leave a response, or trackback from your own site.

225 Responses to “Lesson 0: Getting started with WebGL”

  1. cmarrin says:

    I discussed this with the Mozilla developers and they will be changing their implementation to use clearDepth (which is what the current spec says) rather than clearDepthf. So hopefully once the Mozilla impl. is changed and the content here is updated, content will work on both browsers.

  2. smfr says:

    WebGL is enabled in recent nightly builds, on Leopard and SnowLeopard, but has to be turned on via a ‘defaults’ pref. To turn it on, quit Safari, open Terminal and paste this:

    defaults write com.apple.Safari WebKitWebGLEnabled -bool YES

    then press the Return key. Now relaunch the WebKit nightly build, and you should have WebGL enabled.

    Note that many of the examples here unfortunately don’t work because of differences between the Firefox and WebKit WebGL implementations at present.

    [UPDATE from Giles in March 2010] Please do note that smfr is talking about the situation back in October 2009 — the list of demos above should work in all WebGL-enabled browsers nowadays.

  3. giles says:

    @cmarrin — thanks! Vladimir Vukićević also gave me a heads-up about clearDepth. I’ve put in temporary code so that my examples can handle both that and clearDepthf, which I will simplify down to just clearDepth in a week or so.

  4. Martin says:

    Hi. I have Intel GMA 950. It is posible to run webgl without software mode (true)? Please. Help.

  5. giles says:

    @Martin — your best bet is to make sure you have the very latest drivers (download them from Intel), switch off software rendering, and then try looking at a simple WebGL page — for example, the results of lesson 1: http://learningwebgl.com/lessons/lesson01/index.html

    [EDITED TO ADD] Looks like the Intel GMA950’s drivers don’t support OpenGL 2.0, so unfortunately you’re stuck with software rendering.

  6. Very nice post! Looking forward for others :)

  7. Luqman Ahmad says:

    WebGL is more cooler than I thought. For sure better than VRML/X3D.

  8. [...] Ahora si quieres ver algunos ejemplos mira estos: http://learningwebgl.com/blog/?p=11#examples [...]

  9. [...] this only runs on the latest Chromium nightlies on Windows. Check out LearningWebGL for instructions on getting it set [...]

  10. Alvin Ngo says:

    I successfully installed Minefield for windowx32, but the browser kept poping up message saying that “Could not initialize the webGL, sorry :-( “.
    anyone knows why?

  11. giles says:

    Hey Alvin,

    Did you set “webgl.enabled_for_all_sites” to “true”?



  12. Alvin Ngo says:

    To Giles,

    Thank you, It was my mistake, I didn’t read the instruction carefully. I fixed the problem by switching the webgl.enabled_for_all_sites to true.



  13. giles says:

    Great, glad you could get it working — and thanks for letting me know that fixed it!

  14. Vidya P says:


    I’ve followed all the installation instructions (including setting preferences in about:config). When I run an example, the alert “Could not initialize webGL, sorry!” pops up.

    Please let me know how this can be fixed.

  15. giles says:

    Hi Vidya — I assume from what you say that you’re using Minefield. Which example are you looking at? And is there anything in the error console? (You can display that from the “Tools” menu.)

  16. Vidya P says:

    Hi Giles,

    Yeah, I’m using Minefield.

    I’ve clicked on the examples link given under Firefox section above. Then I clicked on ‘the results of my second WebGL lesson’ under ‘Some first examples’ in the next page.

    The error console shows the following when the alert pops up :

    Error: gl is undefined
    Source File: http://learningwebgl.com/lessons/lesson02/index.html
    Line: 92

  17. giles says:

    That’s really strange! The error console text you see is just an after-effect of the problem that’s being reported by the dialog box; the page hasn’t been able to get a GL context from the canvas, even though it tried using three different context names.

    When was the Minefield you’re using built? That is, is it the most recent nightly build? And, come to think of it, what do you see if you go to this page: http://learningwebgl.com/tests/cruftcheck20100104.html …?

  18. Youdaman says:

    * Checking WebGL… array types vs Canvas… array types: OK (found WebGLFloatArray)
    * Checking context name: Failed (couldn’t get using any name I know about)

  19. giles says:

    @Youdaman — hmmm, that looks like WebGL isn’t enabled in about:config — could you check?

  20. Fatman says:

    Same problem as Youdaman – “Checking context name: Failed (couldn’t get using any name I know about)” – and Vidya P – “gl is undefined”.

    I’ve flipped “webgl.enabled_for_all_sites” and “webgl.software_render” back and forth a fair bit. I tried getting the DLL, that doesn’t seem to help at all.

    This is Minefield 3.7a1 alpha pre.

  21. giles says:

    That’s very strange. You’re on Windows, right? (I assume so from the fact you’re trying the DLL.)

  22. [...] dobbiamo installare le versioni nightly che sono quelle attualmente in development. Ecco un tutorial completo per l’installazione dei vari browser, ma riassumendo [...]

  23. [...] least if the development of WebGL browsers will proceed as it currently does. If you already use a WebGL enabled browser and had a look at one of the several examples as they appear constantly on [...]

  24. [...] least if the development of WebGL browsers will proceed as it currently does. If you already use a WebGL enabled browser and had a look at one of the several examples as they appear constantly on [...]

  25. Elio says:

    I’m using Chromium nightly build and I can’t try the examples. Windows keep crashing Chromium using DEP (Data Execution Prevention). Do you know any way around this?

  26. giles says:

    Ouch, that sounds nasty. It might be that you don’t have OpenGL 2 compatible drivers. What kind of graphics card do you have? And do you have the latest drivers?

  27. I’ve downloaded Minefield 3.7a2pre and set webgl enabled for all sites to true, then I set software rendering to true since I’m using an Intel GMA 950 on a Ubuntu. But I still get no webgl. What did I do wrong?

  28. giles says:

    Hi Manuel,

    Do you have the MESA library installed?

  29. Michael B. says:

    Same problem as Youdaman on Windows 7 a64 with Minefield 3.7a2pre. I changed the value in about:config and already installed the latest driver for my Nvidia 9700M GT.

  30. Michael B. says:

    Update: Works on Windows XP x86 with Minefield 3.7a2pre and on Windows 7 only with software rendering.

  31. giles says:

    That’s very odd. Do you know what OpenGL version your drivers support? You can find out with this tool: http://www.realtech-vr.com/glview/download.html

  32. [...] Artykuł powstał przy wsparciu learningwebgl.com. [...]

  33. Michael B. says:

    Glview says, my driver supports everything from 1.1 to 3.2.

    getContext throws this exception:
    Component returned failure code: 0×80004005 (NS_ERROR_FAILURE) [nsIDOMHTMLCanvasElement.getContext]” nsresult: “0×80004005 (NS_ERROR_FAILURE) … data: no

    I’ll take a closer look this weekend and test some settings within Windows 7.

  34. giles says:

    Right, so you definitely have the right OpenGL versions. Very strange! If you do work it out I’d be really interested in knowing what the problem is.

  35. Michael B. says:

    I grabbed the source and found an hardcoded path (C:\Windows\System32\opengl32.dll), but i installed everything on D:\. I created a new partition C and copied the dll into C:\Windows\System32 but the same error. The same error appears too, if i delete the opengl32.dll on the XP machine. FF tries to create a buffer with hardware modes (which failes), tries the software renderer as a fallback, and throw an error if no mesa dll path is specified. Now i’m adding some log output into FF to find the exact place, where this error happens.

  36. Michael B. says:

    No idea why FF can’t load the dll from my other partition, but i changed the path in nsGLPbufferWGL.cpp to D:\Windows\System32\opengl32.dll and now everything works fine.

  37. giles says:

    That’s good news! Perhaps it opengl32.dll had some kind of dependency on another DLL, and it was using the hardcoded path for that as well and failing there. Anyway, this sounds like a good one for Bugzilla: https://bugzilla.mozilla.org/enter_bug.cgi

  38. mk says:

    I’m trying to use the latest nightly build of Chromium with Windows 7, but I can’t open any of the examples. All I get is “Aw, snap!” page..

  39. giles says:

    Hi mk — what kind of graphics card do you have?

  40. mk says:

    Hi Giles, I have Asus EEE PC, it’s Intel something. I made Firefox work only with installing extra DLL, so I assume my graphics card doesn’t support it? Thanks!

  41. giles says:

    That sounds like it, yes. The problem is that a browser needs OpenGL 2.1 in order to run WebGL. Apparently some Intel laptop graphics cards don’t have drivers that support that version. Minefield can use MESA, which supports 2.1 by software rendering, but Chromium doesn’t have that feature. They should probably improve the error message :-)

    I should update the installation instructions to explain all that, though!

  42. [...] would mean you could develop your WebGL applications in C#, Visual Basic or F#. The trick is to get it working on my machine. It seems my graphics card does not support OpenGL ES [...]

  43. Ayu says:

    Hi everyone,
    let’s hope they complete WebGL as standard soon and implement it in the major browsers. I would really love to build some of my next projects with it.
    And yeah I too get some errors in the newest Minefield version(3.7a3pre). For example things like “gl.Shaderi() not defined…”, but these are WebGL syntax-implementation-change related errors.
    So if you’re getting that, you’re using old deprecated syntax in your projects. Well it’s not like much of it, is real standart anyways?
    Great tutorials by the way, thanks!

  44. giles says:

    Hi Ayu — glad you have it working now, anyway, and doubly glad that you like the tutorials! As you’ve worked out (but for the benefit of anyone else reading these comments later) getShaderi is the old name for a function that was renamed getShaderParameter when they released the draft specification; unfortunately a few older demos haven’t been updated. I’ve removed the ones that don’t work from my recommended list, so hopefully other people coming to WebGL now won’t get that disappointment.

    (It’s a pity, because some of the demos in question are particularly cool — so I’ve emailed their creators and suggested they update them to the latest spec.)

  45. Jordan says:

    Little note: nightly.mozilla.org is a bit friendlier, and the ipc stuff seems to have been fixed up in the last couple months.

  46. Anthony says:

    Wow, this looks really great! I had troubles with firefox but its working on chrome right now and its complete eye candy. :D

  47. giles says:

    @Jordan — thanks! I’ll re-enable the IPC stuff and see how I get on; if it works, I’ll stop recommending that people disable it :-) Thanks also for the link to nightly.mozilla.org, I’ll switch over to that.

    @Anthony — yup, and there are more and more cool demos coming all the time.

  48. Peter says:

    I tried the latest build of Chromium and
    I have the same problem which Giles outlined above:
    I updated to the latest driver of my Intel 945 GM Video – it got me only to version 1.4 of the OpenGL – there is no way to download an Intel driver with OpenGL 2.0 for this type of device.
    Maybe I should try with Firefox?!?

  49. giles says:

    Hi Peter — yes, Firefox with the MESA software rendering DLL should work; the article describes how to get MESA and to set it up. Unfortunately it’ll be a bit slow. The good news is that Google’s ANGLE project was created entirely to help out people in your situation; I don’t know how far away they are from getting something that works, though.

Leave a Reply

Subscribe to RSS Feed Follow Learning WebGL on Twitter