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. [...] WebGL is a library that extends the capabilities inherent in Javascript to generate 3D graphics in modern web browsers – including Chrome, Firefox, Safari, and Opera. This is the the basic technology I will be [...]

  2. [...] 以下是昨天看到的一篇文章《Lesson 0: Getting started with WebGL》片段: [...]

  3. [...] 点击此处,你将看到这个WebGL现场版。如果你还没有一个支持WebGL的浏览器,你可以从这里知道如何获取它。 [...]

  4. [...] WebGL学习教程1 2012-01-13 如果你已经有了一个支持webGL的浏览器,点击此处你将看到WebGL的实时版;如果你还没有,从这里你可以获取一个。 [...]

  5. [...] · Firefox:WebGL工作在Windows、Mac OS X和Linux中每日构建(Nightly Build,也叫Daily Build),是将一个软件项目的所有最新代码取出,从头开始编译,链接,运行测试软件包对代码进行单元测试并对主要功能进行测试,发现错误并报告错误的完整过程。——译者注)的Firefox开发版上。点击此处了解如何安装支持WebGL的Firefox。如果你使用PC机,建议用Firefox。 [...]

  6. giles says:

    @Eli — you’re quite right, but Opera 12 is kind of unstable at the moment. I recommend it as something for people to try out, but not really to develop on yet. It should be pretty good when it comes out, though — early benchmarks have been pretty impressive!

  7. krueger says:

    I found this awesome blog : D

    He has found a library which allows you to do many things


  8. [...] Nu zijn er een hoop truckjes om te kijken of je browser/systeem WebGL ondersteund (hier, hier, hier). Maar een echte oplossing kwam ik pas tegen na een aantal uur [...]

  9. George says:

    We struggled with implementation on Linux and the culprit was indeed the graphics driver. Anyone considering doing this in Linux should either downgrade to a simple older graphics card or be prepared for some serious driver hunting.

  10. snoopp says:

    Hey, dont know how solve this, gl runs, but lighting,there is no lighting.

    MAC OS lion, macbook pro 13, anybody knows how to enable this? Tried Chrome, Chromium and Firefox, everywhere same shit, no lighting…

  11. [...] · Firefox:WebGL工作在Windows、Mac OS X和Linux中每日构建(Nightly Build,也叫Daily Build),是将一个软件项目的所有最新代码取出,从头开始编译,链接,运行测试软件包对代码进行单元测试并对主要功能进行测试,发现错误并报告错误的完整过程。——译者注)的Firefox开发版上。点击此处了解如何安装支持WebGL的Firefox。如果你使用PC机,建议用Firefox。 [...]

  12. [...] 如果你已经有了一个支持webGL的浏览器,点击此处你将看到WebGL的实时版;如果你还没有,从这里你可以获取一个。 [...]

  13. [...] 点击此处,你将看到这个WebGL现场版。如果你还没有一个支持WebGL的浏览器,你可以从这里知道如何获取它。 [...]

  14. [...] 以下の文章は、WebGL Lesson 5 – introducing texturesの日本語訳です。 WebGLのチュートリアルシリーズ第五回へようこそ。このチュートリアルは、第六回NeHeさんのOpenGLチュートリアルの基礎になります。チュートリアルは、分離したファイルから画像を読み込むといったものです。これは、複雑なオブジェクトを描画せずに、リアルな3D空間を表現するのにお手軽な手法です。ダンジョンゲームで岩が落下するところを想像してみてください。おそらく、ひとつひとつの岩をダンジョンの壁と別のオブジェクトとしてモデリングしたくはないでしょう。よって、壁全体はひとつのオブジェクトとして扱い、岩の画像を用意して壁を補うでしょう。 レッスンの内容をWebGLをサポートするブラウザで動かした様子です。 WebGLをサポートするブラウザ環境であれば、リンクをクリックして、WebGLの現行版をチェックしてみてください。もし持っていなければ、リンクから導入方法がわかります。 より詳しい原理を下記します。 注意点:レッスンは、プログラミングの知識を持っており、3Dグラフィックスの経験がないひとを対象にしています。できる限り早く個人の3D Webページを持てるよう、深く理解していただけると幸いです。すでに前回のチュートリアルをご覧になられていたら、この記事を読む前に読んでいただきたいです。なぜなら、このチュートリアルでは、レッスン4と新しいコードとの違いしか説明していないからです。 このチュートリアルには、バグや誤りがあるかもしれません。なにか誤りがあれば、コメントや訂正をできる限り早く教えていただきたいです。 例で紹介しているコードを手に入れるには、2つのやり方があります。表示されているものを読むようなまさにソースを見るやり方。Githubを使って、リンクのリポジトリからcloneしてくる(他のレッスンも)方法もあります。どちらかのやり方でコードを手に入れて、お気に入りのテキストエディタに読み込んで読んでみてください。 テクスチャがどのように機能しているか理解するには、3Dオブジェクト上で色の点がセットされる特有の仕組みを知ることです。レッスン2で説明したように、色がどのようにフラグメントシェーダによって指定されるかを覚えていたら、画像を読み込んで、画像をフラグメントシェーダに送るには何が必要かわかりますか。フラグメントシェーダは、フラグメントを利用して画像のどの部分を取得するのか知る必要がありましたね。 テクスチャを読み込むコードを見ていきましょう。ページ下部にあるWebGLStartのJavaScriptの実行結果を見てください。 [...]

  15. [...] Lesson 0: Getting Started shows you how to download, install and configure a web browser that can show WebGL content, and gives links to a set of pages that show what it can do. [...]

  16. Lucas says:

    Maxthon3 works with plenty of examples I checked with webGl and didnt have to install anything further, Im not a fan of it, but is worth to mention it.

  17. Alex says:

    Coming from a developer’s and programmer’s point of view, never and I do mean NEVER download beta or unstable software, known as bleeding edge. Doing so and attempting to develop / code on this platform will yield more trouble than you really need and/or want.

    Only use stable packages / downloads because, in coding and developing your work will always have bugs in it you need to work out, so having a clean stable install is a must. If you use unstable debug beta versions of software, it’s hard to tell if it’s your implementation of the code and design or if it’s the browser, extensions and plug-ins or all of the above.

    The main reason why WebGL doesn’t work isn’t because of the drivers for the video cards. WebGL by default renders on the CPU itself, yes, you can offload to the GP-GPU if you have one installed and have the correct drivers to access it.

    For example, the Intel series CPU + GPU mobile processors, such as the Atom, the Atom series has poor support in Linux and BSD, not because the drivers are bad, Intel is being lazy. They released a descent driver that worked great for Fedora 10 but haven’t done much since, they released source code for the Intel Atom CPU side and a scant amount for the GPU side, basically a skeleton to get the GPU to do very basic things in hardware acceleration but nothing like what you see in Microsoft Windows. That’s a full stack in DirectX and OpenGL drivers.

    Note: To get webGL to work in Windows, you don’t neccessarily need DirectX, after all, WebGL is a subset of OpenGL meant for the web. OpenGL is another graphics library and standard, a lot different than Microsoft DirectX. By default, the drivers in Microsoft Windows 2000 and forward may need to have to be updated by going to the OpenGL website to download new ones. Granted, the card or embedded graphics will only update to the driver for which your hardware allows.

    Note: Most Intel mobile platforms that are mobile only do OpenGL 1.1, 1.2, 1.4, 1.5, and 2.0. The Intel Atoms do 1.2 to 1.5, most of the
    WebGL is based on 2.0, some newer acceleration is based on GL 3.0 and 3.2. I haven’t seen GL 4.0 standards introduced yet into the webGL libraries and APIs.

    By the way, the amount of acceleration you will see on the Intel mobile platforms in GL will be pretty minimal, even with the correct drivers, even in Linux if Intel got off their arses to publish a full driver or release the full source.

    You get about 4 ~ 22% improvement in speed, what really kills you in webGL is your CPU speed, then your GPU speed and cores you have to use in it. Besides, only having GL 1.2 ~ 2.0 doesn’t yield that much rendering improvement quality nor speed, it’s not until you hit OpenGL 3.0 and getting into the GP-GPUs which are for the most part programmable. In the Intel Atoms and the other mobile platform unless they denote a GP-GPU you have a non programmable GPU which also affects performance, which is where that performance miss occurs and why the percentage of percentage of performance increase is so damn low.

    A message to Snoopp; Can you give me a little more information about your computer you have? What version of OpenGL and OpenCL do you have installed? What graphics option did you go with, or is it the stock Macbook Pro?

  18. Alex says:

    Oops, grammar error, my apologies.

    “In the Intel Atoms and the other mobile platform unless they denote a GP-GPU you have a non programmable GPU which also affects performance, which is where that performance miss occurs and why the percentage of percentage of performance increase is so damn low.”

    Should read as:

    “In the Intel Atoms and the other mobile platform unless they denote a GP-GPU you have a non programmable GPU which also affects performance, which is where that performance miss occurs and why the percentage of performance increase is so damn low.”

  19. Alex says:

    Another thing about OpenGL drivers, which is true for DirectX drivers as well. There are two different types of drivers in your computer system, this is true for all operating systems.

    In order for the OpenGL driver to work for your system, you need to have the correct systems device driver installed, meaning your hardware driver. Open GL is a software library that sits on top of the abstraction layer feeding data to the hardware driver to access the registers and other parts of the GPU to do it’s calculations. A hardware abstraction layer, is a virtualized port in the operating system that allows programmers of non systems files access to the hardware in a unified way.

    Now webGL is derived off the the OpenGL as a subset but it doesn’t directly interface with the abstraction layer I just spoke of, it gets filtered down to that level through a bunch of layers in the OS for which I won’t get into.

    Now, there is a compatibility OpenGL driver than can be installed in your system to emulate access to your hardware via the hardware abstraction layer (HAL) but let this be known, it’s not actually accessing your hardware, everything is being rendered by software only on the CPU and CPU alone, very slow.

    So, a summary, if you want full speed rendering in webGL, you need the correct full driver for your hardware installed, then the next driver you need is the OpenGL driver (called OpenGL Miniport driver), then you need a webGL based browser, one that matches the version of GL you have installed and can render with.

  20. Keelpijn says:

    So do i need DirectX +10.0v or can i also apply that to a windows system with a older version of directX ?

    thanks in advance

  21. [...] 厄又扯远了,如果对shader这东西不怎么了解的可以去看Learning WebGL的系列教程,但是个人更加推荐去系统的学一下OpenGL和图形学的入门知识,WebGL就是基于OpenGL ES2.0标准的,使用的shader也是GLSL_ES,具体的可以翻Specification。 [...]

  22. d0m says:

    Can anyone help?
    Previously when I copied & pasted the source code for a lesson on to a simple text editor & saved it as (for example) lesson1.html & then opened it in Chrome it worked but now I just get a black squire!
    I’m using Chrome or Firefox on Ubuntu 12.4 LTS.
    You can reply here or to my Email dominic_innocent@yahoo.co.uk.
    Have fun.

  23. d0m says:

    I’ve found something that suggests that Browsers are now locked off from viewing files on your Comp, cos of viruses. It seems you need a server on your Comp.
    Info at https://github.com/mrdoob/three.js/wiki/How-to-run-things-locally .
    Have fun.

  24. Hmm this has interesting implications for browser based gaming and entertainment purposes. Though I’m not sure what the practical application will be for web designer. I think the entertainment potential is vast. And definitely could benefit UI and navigation. I’m not convinced by this technology on mobile devices as yet though. Then again tablets and phones are the norm now. And I’ve seen Motorola tech that makes your mobile the PC, you just connect it directly to whichever monitor you are at… With this in mind, browser based technology must be the future. The logical progression for me must be that the home workstation becomes defunct as the quality of internet speed and connectivity increases. Why have an OS/HDD(ssd!) at all when all your applications, games, music and film can be accessed in real time via clod based tech. A very interesting time for gaming, entertainment and web technologies indeed!

  25. Miguel Fonseca says:

    How can i do a controller to **scale an icosahedron using dat.gui**?
    I already could put a camera controller. but now i want to change the scale from a geometry and i can’t…

Leave a Reply

Subscribe to RSS Feed Follow Learning WebGL on Twitter