Graphics Codex version 1.7 Released

[This is a guest post from Morgan McGuire. His Graphics Codex is a pretty great thing for anyone who wants just about all graphics formulae and algorithms at their fingertips. It’s not a perfect venue yet, but I think this is an extremely interesting alternative to books, since the app can be constantly updated and improved. With links to working code for many of the algorithms, my first question, “how do I copy and paste?”, is covered. – Eric]

The Graphics Codex 1.7 costs $9.99 on the App Store. You can install it on multiple iOS devices (I use both an iPad and an iPhone). You also receive free (approximately-) monthly updates of new content and features. It supports all iPads, iPhones, and iPod touches with iOS 5 or later [my experience is that you need iOS 6 – there’s a refresh problem with anything older; evidently Apple has changed its scrolling support], although I recommend at least an iPad 2, iPhone 3, or iPod 4.

The Graphics Codex contains about 200 entries on essential computer graphics equations, algorithms, data, and figures. These span quite a range. For example, they include: the formal definition of the BSDF, source code for a shadow map pixel shader, LaTeX commands for image formatting, and figures commonly used in teaching. For me, the historical figures are particularly fun. The staff at the Chapin rare books library helped me to track down first editions of books including Newton’s Opticks, Durer’s perspective manuscripts, and even Lambert’s work. I then scanned these so that you can get Lambert’s law from his original derivation–a kind of vicarious graphics tourism. When lecturing, I connect my iPad to the classroom projector to display these; the students use their iPhones and iPads to pull up equations and details of what I’m writing on the board.

Every month I add new entries based on what I use in my own graphics work and requests that I receive by e-mail. I read all reviews posted on iTunes as well and respond to them with changes. I currently have a queue of 44 new entries to be added. For each one, I cite a primary source and actually implement the algorithm to ensure correctness. The citations include links to canonical (e.g., ACM Digital Library) and free (e.g., author version) PDFs in most cases, so you can quickly jump directly to the source to learn more. Since many functions are also supported under various APIs, I link to DirectX, OpenGL, Mitsuba, etc., documentation as well.

In addition to the reference material, version 1.7 includes “Lecture Notes on Rendering”: twelve long-form chapters suitable for use in an introductory (ray tracing) computer graphics course. This semester I taught graphics at Williams College using this as the primary reading material. I supplemented it with a few chapters from Fundamentals of Computer Graphics 3rd edition, Computer Graphics: Principles & Practice 3rd edition [to be released May 6, 2013 – Morgan is a coauthor], and two research papers: Kajiya’86 and Jensen ’96. The next three chapters I will add in future updates are deep explanations of Photon Mapping, Importance Sampling, and Color Theory. All of these can be used with any API, but are explicitly supported by the open source G3D Innovation Engine graphics library. G3D now includes a complete photon mapping ray tracer that matches the notation and structure of the renderers described in the lecture notes.

On the technical side, I completely rewrote the layout and scrolling engine for this release. The new GPU-accelerated version allows scrolling before layout completes, making even the longest chapters respond nearly instantly. The underlying code uses LaTeX for math typesetting and that runs on a second thread, so if you scroll really fast you’ll see the equations inserted as they are completed. I use dynamic layout instead of static (e.g., PDF) so that content can respond to changing device orientation and re-layout on font change rather than forcing the reader to scroll horizontally. This version also includes support for iPhone 5, iPod 5, and iPad mini resolutions and processors. I recommend using the latest iOS version 6.0.1 because that has the best GPU drivers, but the app supports everything back to iOS 5.1.

I can’t stress enough how liberating and rewarding it has been as an author to release material as an app instead of a book. There are no delays because I release content incrementally instead of in discrete editions, and the quality remains uncompromised by artificial publishing and marketing deadlines–I only release material when it is polished. Direct feedback from readers allows me to support them with appropriate content, and there are zero known errors; as soon as errata is collected, I simply patch the content and push it out to everyone. Selling for 10-20% of the cost of a textbook allows me to reach the hobbyists, indie developers, and students who will be tomorrow’s great developers and researchers. The down side, of course, is that I rely on “word of mouth” (e.g., blogs and Twitter) to promote the app, whereas traditional publications have marketing budgets and campaigns. Now that the app has a critical mass of content, I’m starting to promote it more actively. I look forward to readers letting me know what new features and entries to add in future months.

[p.s. here are links for the Graphics Codex homepage, and Morgan’s twitter feed (actually, he has two) and blog.]

Setting up a Windows Server for WebGL

While it’s fresh in my mind, I’m going to write down the steps for setting up a simple server on your local machine to help run WebGL. 99% of readers won’t care, so begone! Or actually, see the power of WebGL by trying out a zillion demos on the three.js page (you’ll need to use Chrome or Firefox or properly-prepared Safari – try this page if you have problems getting going, it points to the information you’ll need). Whoever’s left might be on Mac or Linux – you could use LAMP on Mac, Apache on Linux, or whatever else you like. Update: I found some further instructions here for other platforms and other server setup methods.

Now, for whoever’s really left…

Why would you want to set up a server for webpages? Well, you need this only if:

  • You want to develop WebGL applications.
  • You plan on loading textures or model files.
  • You don’t want to set up some tricksy settings that open up security holes in your browser.
  • You don’t have a server running on your machine and are as clueless as I am about setting such things up.

Background: if you want to load a texture image to use in a WebGL program, then you need the texture to be on the same machine (barring cleverness) and to have both your web page and the texture somewhere in the “documents” area of the same server. This is needed for security reasons.

On Firefox you can get around this security feature by typing “about:config” in the URL. You’ll get a security warning; say “OK”. Now search on “strict_” and you’ll find “security.fileuri.strict_origin_policy”. Double-click to set this to “false”.

On Chrome you can do it two ways: each time on the command line, or once with the program icon itself; I recommend the latter.

First method, command line: start a command window (“Start” button, type “cmd”), go to the directory where chrome.exe is located, (e.g., “cd C:\Users\hainese\AppData\Local\Google\Chrome\Application”) then type:

chrome.exe --allow-file-access-from-files

to start up Chrome. Key tip: make sure to close down all copies of Chrome before restarting it this way, otherwise it doesn’t work (thanks to Patrick Cozzi for this “obvious in retrospect” tip).

Second method: made a shortcut to Chrome, right-click on it and select Properties. Then, add

    --allow-file-access-from-files

to the end of Target, which will be something like “C:\Users\hainese\AppData\Local\Google\Chrome\Application\chrome.exe”.

Server Creation Instructions

These previous methods are nice, in that you can then just double-click on a WebGL html page and it’ll run. Downside is you’re opening up a security hole. If you’d rather just set up a local server and be safer (AFAIK), it’s pretty easy and less scary that I thought. Lighttpd (pronounced “lighty”, go figure) is a lightweight server. There are others, but this one worked for me and was trivial to set up for Windows (vs. Microsoft’s involved “install, open, create” steps for its IIS server for Windows, which I’m told is “easy” but looked more like a treasure hunt).

Edit: I’ve been told the wamp server is also nice.

Here’s the whole deal:

1.  Download from WLMP Project – the link to download the .exe is near the bottom (Google’s Developer Network hosts one, so it’s safe), here’s the link.
2.  Run the .exe and install. Use the defaults. You may get a “reinstall with recommended settings” warning at the end; I did.
3.  Edit the text file “C:\Program Files (x86)\LightTPD\conf\lighttpd.conf” (or wherever you put it) and comment out the line (by adding a “#” in front of it):

server.document-root        = server_root + "/htdocs"

and add this line after:

server.document-root        = "C:/Users/<yourname>/Documents/WebGLStuff"

substituting “<yourname>” and “WebGLStuff” with whatever user directory you want. Important: note that the directory path has “/”, not “\”. It might work both ways, but I know “/” works. Everything in this directory and below will be in view of the server. Save the file. Key tip: don’t make this directory in some semi-protected area of your computer like “C:/Program Files (x86)”, make it in your user directory area.

4.  Go to “C:\Program Files (x86)\LightTPD\service” and run Service-Install.exe, then answer “Y”:

You may get a “reinstall with recommended settings” here, too – just agree and do it again.

You have a server running on your machine! You can see it running by ctrl-alt-delete and in the Task Manager you’ll see it under “Services” as “lighttpd”.

Now you can put any and all WebGL code, images, etc. in any location or subdirectory below “C:/Users/<yourname>/Documents/WebGLStuff” and be able to run it. You’ll run by actually typing “localhost” and then clicking on down into the directory you want. That’s important: you can’t just double-click on an HTML page in a directory but have to use the path “localhost/” as the prefix to the URL.

For example, if you put the code for three.js (which is entirely awesome, in the “awesome” sense of the word, not in the “pancakes? awesome!” sense of the word) in a directory, you’ll see something like this as you find it in your tree:

Click on an HTML file and you run it. For example, if I clicked on the last file shown, it would run and the URL shown would be “http://localhost/three.js/examples/canvas_interactive_voxelpainter.html”.

This all sounds like a PITA, but the cool thing about it all is that WebGL pages you make let you put interactive 3D demos and whatnot on the web without requiring much by the viewer (just any browser other than Internet Explorer, pretty much) – no program download, no plugin, no permissions requirements, nothing. I plan on using this functionality heavily in the web course I’m designing.

There’s lots more you can do with the lighttpd .conf configuration files, but the change detailed above is the minimal thing to do. If you ever later change your .conf configure file options, first run Service-Remove.exe in “C:\Program Files (x86)\LightTPD\service”, make your changes, then run Service-Install.exe again.

(Thanks to Diego Hernando Cantor Rivera with his help in getting me past some roadblocks. You’d be amazed at how many ways you can mess up steps 3 & 4.)

Seven Things for October 28, 2012

Books: The Good, The Bad, and Some Third Category

Due to a long plane flight, this week I started reading up on WebGL in earnest, going beyond the various tutorials on the web. The two books recommended to me that I’ve started on (and skimmed through in their entirety – I need to sit down with each in front of a computer):

WebGL: Up and Running, by Tony Parisi, O’Reilly Press, August 2012. More info about the book here, including a sample. I recall Tony from way back in the days of VRML, he had one of the first viewers for that file format, so he’s been working in this area of 3D graphics for the web for a long time. This looks to be a good book if your goal is indeed to get something on the screen fast. It’s readable, and I appreciate his use of URLs to WebGL demos and resources and (properly credited) Wikimedia images. The code samples for the book are here on github.

It uses the popular three.js library to insulate you from the OpenGL ES roots of WebGL and hide its raw API nature. The author of three.js, Mr.doob (I don’t make these names up), notes that his work is “a lightweight 3D library with a very low level of complexity — in other words, for dummies”. Which is a fine thing, and I think I’ll be using it myself to teach introductory computer graphics. However, if you want to gaze at the occult pulsing mutation spawned of JavaScript + OpenGL ES + DOM + JSON + HTML 5, I mean, unleash the full power of WebGL itself, you’ll want to read the next book instead.

WebGL Beginner’s Guide, by Diego Cantor and Brandon Jones, Packt Publishing, June 2012 (code here). This is a pretty impressive book overall. The authors deal with WebGL directly, adding only the glMatrix library on github to make matrix manipulation easier (this is about as minimal as you can get). This book walks through much of what WebGL does (essentially, the same as OpenGL, of course), giving lots of code examples and worthwhile illustrations. Some example programs are quite nice, with useful user interfaces allowing you to twiddle values and see the effect. The book deals with more advanced topics towards the end, such as how to render offscreen and sample the results (their example is for performing picking). There are a few minor problems with layout on my iPad (a few illustrations don’t fit and there’s an awkward scrolling interface that doesn’t quite work), and some occasional lapses in grammar, but overall the book is fine. Occasionally the authors will get distracted by side topics, like a full derivation of why you use the inverse transpose of the matrix for transforming normals, or explaining a shader that does simple ray tracing. In general, however, the book works through the key areas of the WebGL API and warns you of potential problems along the way. WebGL itself exposes you directly to vertex and fragment shaders, so if you are planning to do some serious work in this area, this book is perhaps a better choice that Parisi’s (that said, three.js itself gives you easy access to shaders).

Personally, these two WebGL books were cheap enough on Kindle that I bought them both. The Beginner’s Guide in particular is a much better deal on Kindle – a third the physical book’s price. They’re actually better on Kindle, in that they’re in color; the physical books are printed with grayscale images. There are other books on WebGL, but these were the two recommended to me and they are both reasonable choices, depending on your goals. I would not recommend either if your primary goal is learning the fundamentals of computer graphics (though there’s a bit of that type of material in each). For learning WebGL itself and the basics of what it offers, both books are fine, with the “WebGL Beginner’s Guide” being aimed at the more “to the metal” programmer.

JavaScript: The Good Parts, by Douglas Crockford, O’Reilly Press, May 2008. If you use WebGL, you’ll have to know at least a bit about JavaScript. Patrick Cozzi mentioned this as a reasonable guide, along with other writings by the author. I’ve only started it, but it’s pretty amusing. The book’s approach is to indeed teach only the good parts about the language and not let you know how to use the bad parts. The author recommends only one of the dozens of books on JavaScript, JavaScript: The Definitive Guide. He feels the rest are, to quote, “quite awful.”

Update: I finished this book and thought it got better as it went along. It starts out a bit language-wonkish, too much about grammar. Skip that chapter. The most useful parts were the appendices, where he explains the various parts of JavaScript clearly and succinctly, calls out the dangerous and evil parts of the language, and explains how to steer clear of them. The author came up with JSLint, which checks your code for badness, but to be honest it’s way too a strict schoolmarm for me, hitting me on the knuckles whenever I put a left brace “{” on the wrong line. I recommend JSHint instead.

Enough on WebGL and JavaScript, my current interests. I’ll mention just two more books that I’ve only just glanced at and so can jump to conclusions.

Real-Time Graphics Rendering Engine (Advanced Topics in Science and Technology in China), by Hujun Bao and Wei Hua, Springer Publishing. Shame on you, Springer, for shame. A 300 page book for $169 is bad enough, but this one has a slap-dash translation that could probably have been done better by Google Translate. I’m judging only from the “Look Inside” text I can access on the Amazon listing, but I see things like a section labelled “Rending Modle” on page 5. This might be a fine book in its native Chinese, the bits of material I tried to read seemed sound enough, but the translation is, well, judge for yourself. Here’s the end of chapter summary, a section I picked at random:

“Real-time rendering is always formed as a pipeline composed of consequential data processing and graphics calculations to generate final rasterized images. In order to achieve amazing rendering effects as well as real-time performance, GPU techniques, especially shader techniques, are introduced to utilize programmable pipelines and the parallel computing structure. Virtual geometric 3D models are transformed to be located in a virtual scene by geometrical transformation matrices. Material and/or other visual properties are then attached to those geometrical models to compute visually pleasant rendering results. As the performance of real-time rendering applications is highly emphasized, tailored shading techniques and BRDF models are employed to achieve real-time rendering results with balanced visual effects.”

I feel terrible for these authors whose work has been so shabbily thrown between two covers.

However, there is certainly a worse book out there, and I have to give the full-sized cover from its Amazon listing, since I expect it to disappear any day now and I want to keep it as a memento.


Suck it, bizzatches, I got me my own book on Amazon. Yes, the title is my name, it’s ostensibly a biography; I’m not the author. I ran across it yesterday morning, and it almost made me laugh. Almost, because I hate these “books”. It’s clearly by the same people who came up with all those other automated offerings, VDM Publishing.

I’ve posted about this so-called publisher before, here and here. VDM now has a new imprint, “Cel Publishing” (one of seventy-nine!), I expect because the Alphascript and Betascript Publisher books are fast disappearing from Amazon’s catalog as the complaints and returns roll in. The short version is that this firm has a program that grabs a random Wikipedia page and follow links from it. Once there’s enough material for a book-sized book, it spits out the contents. Some human – in this case allegedly one “Iustinus Tim Avery” (anagram server’s first hit is “Autism University”) – slaps a cover on it and it’s put in the catalog, to be published on demand.

The most creative part of the process used to be the cover choice. In the past they were sometimes pretty amusing, but it looks like Cel Publishing has removed that fun part of the job for the “editor” and instead just uses random abstract patterns. I personally think of myself as more of a splash of chartreuse paint, but so be it. Also, the book is clearly underpriced at $38 for 60 pages. What did make me laugh is that there’s now a review of the book (thanks, Matt!).

WebGL Browser Editors

I asked Patrick Cozzi if he knew of any WebGL editors working in the browser. There turn out to be quite a few, each with their own focus:

Enjoy! And let us know of any others you find.

Note: we’ve added a resource page for WebGL-related information.

SIGGRAPH 2012 Course Notes, so far

Edit: wow, this page has almost everything from SIGGRAPH 2012 (thanks, Sebastian, and especially Stephen Hill!).

Just two course notes links I happen to have, though I’m sure Naty has considerably more:

Beyond Programmable Shading – an interesting course as usual. The introductory talk by Aaron Lefohn points to the rise of the ComputeShader, and Johan Andersson’s “5 Major Challenges” talk gives a thorough overview of the graphics problems currently facing cutting-edge game developers such as DICE.

Unity: iOS and Android – Cross-Platform Challenges and Solutions – from the Mobile session, these are the slides from Renaldas Zioma’s presentation about what they found while moving Unity 3D to mobile devices. I liked this talk so much I asked to host it at our site. Here’s an introduction by Renaldas to the talk itself, with some surprising audience stats.

Eventually the course notes for Advances in Real-Time Rendering in 3D Graphics and Games should also be available.