Pseudocode Motivations

I received a few e-mails asking about the choice of pseudocode for most algorithms in The Graphics Codex.  Presenting code in a useful form for reference is an interesting problem and like all technical writers, I struggle with it on each project.  There are three challenges for code in this project in particular:

1. What would you do with directly compilable code on an iOS device?  

2. Compilable code is rather big

3. What language/library to use?

I chose Python-like pseudocode based on my analysis of those challenges.  Read on for the details of why.

Getting Code Samples out of iOS

You can't actually program on an iOS device, except for maybe via VNC or other remote desktop software. I don't expect most readers to be in that situation frequently.  So how can I provide reference data that you might want to copy and paste into a program directly?

My solution is to add a button to e-mail large constants and code samples to yourself.  That should deal with the copy-paste problem both in terms of interface and machine.  I'm developing this for the next release at the end of March 2012.

Compilable Code is Lengthy

Code samples in The Graphics Codex aim to help you get your head around an algorithm. If the code fits on one screen, you have a chance of doing that.  It is even better if it fits on one screen with a diagram next to the code.  When the code gets lengthy, you lose the algorithm in all of the clutter.  At that point, you should pull up a code sample from elsewhere on your dev machine and walk through / single-step through it in your favorite IDE.  

The G3D Innovation Engine code that I link to in The Graphics Codex is open source and provides C++ implementations for most of the interesting code samples. I recommend going there or performing a search on the web for code using:

• http://www.koders.com/
• http://code.google.com/hosting/

Graphics uses many Languages

HLSL and GLSL have sufficiently different syntax that they are no longer interchangable.  Most graphics programmers use C++ (I think) for host code, but Cg/GL/DX are radically different on the host side.  For API-independent algorithms, C++ is so dependent on the specific templates and libraries that you're using that it isn't really portable between projects--plus, you might want to implement that algorithm in GLSL, Cg, or HLSL anyway.  For example, my:

  const Vector3& x = Vector3::uniformRandom();

isn't very helpful to you if you're in GLSL, where you probably have to say:

  vec3 x = normalize(texelFetch(randomUniform, ivec2(glFragCoord.xy), 0).xyz);

and even if you're in C++, maybe your library doesn't overload the same operators or provide the same vector methods.  

Which Pseudocode?

The specific style of the pseudocode is something I'm actively experimenting with. I chose Python-like syntax and extended it with common C++ operator overloading, comment operators, and mathematical type annotations.  Choosing a specific scripting language as a model gives me a nice default for conventions rather than inventing everything from whole cloth.  Graphics is usually written in an imperative language, and Python offers both that plus occasional elegant functional structures. It has a very economical syntax without being telegraphic or effectively encrypted like Perl, and is a language that many (although probably not most) graphics programmers are already comfortable.

There are a few topics for which pseudocode is really not appropriate, so I give explicit C++ or shading language code for those. I expect most algorithms will be in pseudocode.

As always, I welcome suggestions for new topics, ones to expand, or new ways of presenting the content of The Graphics Codex.

Morgan

http://casual-effects.com