Learning 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.

Firefox

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.

Safari

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.

Chromium

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:

  ./Chromium.app/Contents/MacOS/Chromium
  

• 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:

  ./chrome
  

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:

• One of my own demos: Bouncing Mandelbrot Cubes.
• From Google: a shiny teapot (click and drag to spin it), “San Angeles“, and for the anatomically-inclined, the Google Body Browser.
• A real-world use of WebGL: ChemDoodle 3D displays molecules in web pages.
• There are more demos in the Khronos demo repository and the User contributions section of the WebGL Wiki. Also, Google’s “Chrome Experiments” site has a WebGL section; most of the demos work in other WebGL browsers too.
• Finally, if you’d like to see the best of WebGL demos every week, subscribe to this blog! Every Thursday I post a round-up of all of the WebGL news I’ve been able to find over the last seven days, and there are normally a bunch of new demos.

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 >>

Troubleshooting

Macs

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…

Windows

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.

Linux

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.

Acknowledgments

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!