Mile
Zero

Once Microsoft announced IE 11 will offer WebGL, that was pretty much the last straw: Apple may drag their feet at enabling it in Safari, but everyone else seems to have decided that it's secure enough and capable enough for production. I still think it's a little nutty, but I don't really have an excuse to avoid it anymore. So when an EaselJS-based visualization at work started having performance issues, I wrote a WebGL shim as a learning project.

I stand by my earlier impressions of the WebGL API--it's clumsy and ill-suited to JavaScript--but the performance is undeniably there. Rendering through EaselGL is often orders of magnitude faster than vanilla Easel, particularly when it comes to mouseover responsiveness. It's worth struggling through the learning process if you find that canvas is becoming a bottleneck for your application. I think a more interesting question is why so many WebGL tutorials are awful. And they are awful:

• They hide the WebGL boilerplate behind library code--say, a function call that loads shaders or does matrix math--and force readers to dig through the source to figure out what mat4mult() or loadShader() does.
• Even when they leave the code all in one place, they treat the often-confusing GL code as boilerplate, and don't explain it. Why do I need to call bindBuffer()? What do the six (!) parameters of vertexAttribPointer() actually control? What's the deal with all the constants, like gl.STATIC_DRAW?
• Since WebGL is not a 3D API, they require a lot of 3D math. Most people teach this badly, assuming they don't double down on the mistakes above and just hide it behind calls to library functions. As a result, it's easy to get lost, and hard to reach the "putting shapes on the screen" feedback loop that keeps students engaged.

Of course, these are not uncommon mistakes in programming tutorials. In fact, they're extremely common--I just haven't had to learn anything from scratch in a while, and had forgotten how confusing the process could be. Anyone writing for beginners would do well to keep these errors in mind.

There are a few walkthroughs that I found more helpful. As I've mentioned, Greg Tavares's series on WebGL was eye-opening, and Brandon Jones provided the only worthwhile explanation of attribute array setup that I found. Between those two, and countless Google searches, I managed to cobble together a basic understanding of how the GL state machine actually works.

As a way of distilling out that knowledge, I've assembled the WebGL demo script that I would have wanted when I started out. It uses no external code--everything's right there on the same page. It explains each parameter that's used, and what each function call does. And it's only concerned with drawing a basic 2D shape--no matrix math is involved. It's stored in a Github Gist, so feel free to file pull requests against anything you find confusing. Also, feel free to look through EaselGL: it's a bit more advanced and I need to add more comments, but as a 2D API I think it's quite a bit easier to understand than the typical game library, particularly for ex-ActionScript developers like myself.