Covariance and contravariance are things you’ll probably ignore until you start using generics in ernest. Then one day you’ll want to pass an enumerable to a function that takes a slightly different yet related type of enumerable and then BAM – you’re hit with some crazy error messages and then all of a sudden you’re up to your elbows in browser tabs of StackOverflow articles.

To cut straight to the chase, this is the problem:

1
2

Base rawBase = new Derived(); // this works
MyType<Base> wrappedBase = new MyType<Derived>(); // ERROR!

Sometimes we want the OO polymorphism substitution rules (AKA Liskov’s substitution principle) to apply to generic types too. Covariance and contravariance provide us a mechanism to allow this substitution to take place.

To be more specific, [co|contra]variance are necessitated due to the interaction of two different forms of polymorphism – object inheritance and generic typing. And yet sometimes you want to combine the two – while MyType<T> and MyType<U> share no inheritance relationship and therefore are not substitutable for each other, sometimes you want to treat them as if they are substitutable if T and U are themselves related.

So a covariant or contravariant generic type (e.g., a IEnumerable<T>) might be bound to other references of that type (e.g., IEnumerable<U>) when there is an inheritance relationship between the two predicated types. This allows you to pass your IEnumerable<Employee> to a function that actually accepts an IEnumerable<Person> without the compiler complaining that they are different types.

The rule of thumb with inheritance is that if U inherits from T you could say that U is-a-kind-of T. With covariant and contravariant types, I like to think of them in terms of can-be-used-as-a relationship. To determine if MyType should be covariant or contravariant you could ask if Dog is-a-kind-of Animal, is it true that MyType<Dog> can-be-used-as-a MyType<Animal>?

Covariance and contravariance are two different ways that differently specialised generic types should themselves be substitutable for each other like derived types are:

Covariance: MyType<T> is covariant if typing MyType<Base> x = new MyType<Derived>() makes sense (this looks very much like standard substitution rules.)

An example of this is an IEnumerable-derived type, and is classified as having methods that return the predicated type, or getters (hence C# uses the out keyword.)

The implication is that the relationship between the covariant generic types is the same as the relationship between their predicated types, e.g.:

1
2
3
4
5

Base b = new Derived(); // OK because of Liskov substitution

IEnumerable<Derived> ds = new List<Derived>();
IEnumerable<Base> bs = ds; // OK because IEnumerable is covariant
Base first = bs.First();

Contravariance: MyType<T> is contravariant if typing MyType<Derived> x = new MyType<Base>() makes sense.

An example of this is the .Net generic Action type, and is classified as having methods that accept the predicated type as a parameter, or setters (hence C# uses the in keyword.)

Contravariant types are probably less common than covariant types, and imply that the relationship between the generic types is the inverse of the relationship between their predicated types. E.g.:

1
2
3

Action<Base> b = _ => {};
Action<Derived> d = b; // OK because Action is contravariant
d.Invoke(new Derived()); // invoke alias 'd', actually invokes 'b'

Why they’re helpful

Covariance and contravariance are useful in all the ways that Liskov’s substitution principle is useful with regular polymorphic types – they are a mechanism that lets you inform the compiler when it’s safe to bind an instance of one generic type to a reference of the same generic type with a different generic parameter.

If you’re writing an application you’ll often have one library or area of your code where you deal with heterogeneous types of one category, lets say Animals, yet in another area of your code you’ll deal exclusively with another related type, lets say Dogs. (Note that in math these are called categories and there is a whole set of theories in how to reason about them. See Thomas Patricek’s blog for more details.)

To be very clear, covariance and contravariance only applies to:

• generic types
• where the predicated types have an inheritence relationship
• where a concrete object of that generic type is being bound to a reference (e.g., a passed as a parameter) of a different specialisation of that type

Liskov substitution without generics

For example as a reminder of the standard substitution rules:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class Animal {};
class Dog : Animal {};
class Poodle : Dog {};

void SaveDog(Dog dog) { ... }
Dog LoadDog() { ... }

Animal myAnimal = ... ;
SaveDog(myAnimal); // ERROR - myAnimal might be a cat!
Animal myAnimal2 = LoadDog(); // OK - dog is a kind of animal

Poodle myPoodle = ...;
SaveDog(myPoodle); // OK - poodle is a kind of dog
Poodle myPoodle2 = LoadDog(); // ERROR - LoadDog might return a non-poodle dog!

OK cool, this is just how polymorphism works in OO languages. But here’s where it gets confusing – what about generic types that are predicated on those types? E.g., a IEnumerable<Dog> or a Action<Dog>?

Liskov’s substitution of generic types

Covariance and Contravariance hints tell the compiler to allow references to generic types to obey the same rules as polymorphic types! It doesn’t affect how you can use a particular type directly, but it affects what other types of that generic object it can be bound to (when being passed to or returned from functions, for example).

To extend the previous example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// should be covariant but is not
interface IReader<T> {
  T Read() {...}; // simplified interface
};

// should be contravariant but is not
interface IWriter<T> {
  void Write(T entity); // simplified interface
}

void PrintDogFrom(IReader<Dog> dogReader) {
  Dog dog = dogReader.Read();
  // ... print dog info or something
}

void WriteDogTo(IWriter<Dog> dogWriter) {
  dogWriter.Write(new Poodle());
}

// demonstrating a typical 'reading' usage scenario
// that should work ideally

IReader<Poodle> poodleReader = ...; // init somehow
PrintDogFrom(poodleReader); // ERROR! (IReader<Poodle> != IReader<Dog>)
// BUT it should be OK (poodles are dogs)

// demonstrating a typical 'writing' usage scenario
// that should work ideally

IWriter<Animal> animalWriter = ...; // init somehow
WriteDogTo(animalWriter); // ERROR! (IWriter<Animal> != IWriter<Dog>)
// BUT it should be OK (writer holds animals, can write dogs)

We recognise that a IReader<Poodle> instance should be able to be bound to a IReader<Dog> reference if Poodle is a subclass of Dog. This is known as covariance and is denoted in C# by labeling the generic type with the out keyword:

We can also see that IWriter<Dog> should be able to be bound to IWriter<Animal> if Animal is a superclass of Dog. This is known as contravariance and is denoted in C# by labeling the generic type with the in keyword.

1
2
3
4
5
6
7
8
9

// IReader is covariant on T
interface IReader<out T> {
  ... // as before
}

// IWriter is contravariant on T
interface IWriter<in T> {
  ... // as before
}

The difference in the two interfaces is simple – covariance is used when the dependent type is retrieved out of the generic type (an example would be how an IEnumerable<T> returns objects of type T and therefore is covariant on T). A generic type should be contravariant if it accepts the dependent type as input into its interface (an example would be how an Action<T> takes an instance of T as input when it is run, therefore it is contravariant on T).

Here’s an attempt to visually represent valid type conversions for a cass hierarchy, a representative covariant type (IReader) and a representative contravariant type (IWriter):

When should my interfaces be covariant or contravariant?

I only add this when its needed, but one thing you’ll find is that you cannot have a covariant or contravariant type if you are both returning and accepting the dependent type in your interface. This is why in C# IEnumerable is covariant but IList is not – because IList allows you to add elements to the collection as well as retrieve the elements in the collection.

Sometimes you will be forced to make your type covariant if you want to use it in certain ways. In this case you may have to separate out the reading part of your interface into a separate interface and have the generic parameter be covariant there only.

A few language-specific quirks you might run across

Although the samples here might suggest otherwise, C# only allows interfaces, not concrete classes, to be specified as covariant or contravariant.

Java never used to support variance specifications much to its detriment. Java arrays behave in a covariant way, but because the interface supports both retrieving and setting elements, the following compiles (or at least used to, I havent tried it recently:)

1
2
3

Dog[] dogs = new Dog[10]; // ...
Animal[] dogsAsAnimals = dogs;
dogsAsAnimals[0] = new Cat(); // whaa?

Note: in researching this I discovered that C# arrays suffer from the same problem! Arrays in both languages will throw runtime exceptions when used illegally like this

C# has supported variance for a long time, but unfortunately there are some corners where they have not yet added it. I recently found out that Task<T> is not covariant, and so if you were implementing your own covariant type, its interface cannot return generic Task<> types, which is frustrating because thats what Microsoft strongly recommend you to do.

Example:

1
2
3
4

interface IReader<out T> {
  T GetNext();
  Task<T> GetNextAsync(); // compile error! although this should be idiomatic!
}

The official answer to this (well, Jon Skeet’s word is very highly considered) was that adding variance to your interfaces quickly gets complicated in some way and so try to make your types invariant, and I cannot answer to that. My solution was to have the interface return a non-generic Task and dynamically downcast it to the generic type when I used it. This is not great, but its also quite safe as you know for certain the type of the task.

C++ generics (templates) do not directly support the notion of covariance or contravariance, but they don’t need to – templates are specialised at compile time to generate separate instances for each required specialisation, so generic types are often not required to be coerced into other generic types.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

template <typename T>
void printBases(vector<T*> & bases) {
  foreach (auto * b : bases) {
    cout << b->Name() << endl;
  }
}

vector<Derived*> ds {};
printBases(ds); // works as long as Derived has Name() method

template <typename T>
void addDerived(vector<T> & deriveds) {
  deriveds.push_back(new Derived{});
}

vector<Base*> bs {};
addDerived(bs);

The above code shows that C++’s templates are generally sufficient for performing generic operations on generically encapsulated types. The only constraings put on the type passed to the function is that it has a Name() method (this is known as ‘duck-typing’). Note that these are completely type-safe, as the compiler generates fully typed code at compile time. If I tried to add a Base type to a Derived vector, for example, you would get the expected error because the compiler would recognise the type mismatch.

On a related topic, it is also worth noting that C++ allows a derived class’ overridden virtual methods to have covariant return types such that:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

struct Base {};
struct Derived : Base {};

struct BaseFactory {
  virtual Base * create() { return new Base{}; }
};

struct DerivedFactory : BaseFactory {
  override Derived * create() { return new Derived{}; }
};

DerivedFactory * ds = new DerivedFactory();
Derived * d = ds->create();

BaseFactory * bs = ds;
Base * b = bs->create();

Java also supports covariant return types, but C# does not.

What a daunting task!

If you have any recommendations on how this could be more beginner-friendly please tell me.

Also thanks Gregg Tavares for pointing out my various errors!

Things I wish I knew when learning OpenGL

The most important thing a programmer should know before deciding whether to learn OpenGL is that OpenGL is very low level, poorly documented and extremely crufty. This is because it is an API specification and not a product library per-se. It is up to the many various vendors to implement the API spec as best they can.

In its various incarnations OpenGL spans almost 20 years and at least 7 major revisions, including the embedded versions. Anyone looking to learn to use OpenGL will face a constant battle with finding relevant documentation for their chosen version on their chosen platform with their chosen extensions.

The next thing to know about modern OpenGL is that these days it does very little legwork for you other than allowing you to run a program on the GPU. You will have to write the GPU shader programs that do everything from transforming your own application data into screen-space coordinates, to calculating the exact colour of every pixel on the screen incorporating lighting and shading algorithms that you implement yourself (fortunately linear algebra makes this stuff a lot simpler than it sounds!) So OpenGL will not do any inherently 3D stuff for you – most OpenGL commands and types are capable of describing 3D positions, directions and transformations but you have to do the grunt work yourself.

The third immediate concern – OpenGL does not work out of the box! An annoying truth is that OpenGL realistically requires supporting libraries in order to function, most importantly to create a context within which the rendering operations can work. It is very common to incorporating at least three libraries – one to generate a GL context into which you render, a matrix and vector manipulation library, and an extension loader for when you need a little more functionality than your platform provides.

So why would you even consider it?! Why would you write a series of articles on a technology that scares you so much? The reason it has kept its relevance is because OpenGL is the only low-level graphics API supported on pretty much all platforms you’d want to render graphics on. Because it is so very widely adopted it is still the defacto standard for developers wanting a powerful low-level intrinsics that work on multiple platforms.

If you are only targeting Windows you might consider DirectX. If you don’t need to interact directly with your shaders, and are happy to work at a higher level of abstraction and not with the GPU directly, perhaps a higher level graphics library such as Unity or UDK would work better for you.

So assuming you still want to start using OpenGL, this article might be helpful to you. My intention is to mention a lot of stuff I had to hunt around for that seemed pretty important to me while I was trying to learn it myself. I will not be doing a step-by-step guide to performing specific OpenGL tasks however – for a good getting started guide check out open.gl which is both modern and easy to follow.

To use OpenGL effectively I figure you’d need to understand:

• opening an OpenGL window (i.e., creating a context)
• the basics of rendering:
  • primitives, vertices and fragments
  • coordinate systems:
    • built-in normalised device coordinates (NDC) and clip coordinates
    • 3D model, view and perspective coordinates
  • shaders and the render pipeline (how data gets from your app to the screen):
    • vertex and fragment shaders
    • passing uniforms and attributes into the pipeline
    • vertex buffers (VBOs)
    • passing varying data from the vertex shader to the fragment shader
  • the fixed-function pipeline (now deprecated)
• linear algebra (the magical language of graphics programming)
• a rundown on all the different major OpenGL versions
• major challenges that you certainly will face moving forward

I’ll leave more advanced core concepts such as framebuffers and textures for a later article.

Starting a new project

I suppose this is the most important thing to a lot of people, so I’ll show how I bootstrap a new OpenGL project. I haven’t been at it long so take it with a grain of salt, but I tried to focus on building a cross-platform solution.

I generally depend on four libraries. Although technically you could get away without any supporting libraries, these save a lot of time and effort. The libraries are:

• Google’s ANGLE project provides an OpenGL ES 2.0 (soon 3.0) driver library for Windows that wraps Direct3D. This is useful so you don’t have to depend on the user downloading the OpenGL drivers for their graphics card on Windows.
• GLFW to create a window and otherwise interact with the OS and other devices. Many people prefer SDL2 or GLUT. Alternatively you could use the standard low-level supporting libraries supported by your operating system – WGL, GLX or EGL.
• GLM is a widely used vector and matrix library. It’s particularly nice because it mirrors GLSL standard types and operations as much as possible, so hopefully there’s some learning synergies there. I have tried using Eigen which is more of a general linear algebra library focusing on performance, but it has a lot of limitations on how you can use (passing or storing types by value is complicated) it because it uses low-level processor vector operations under the covers. Of course you could always write your own matrix classes, but it’s a pretty big task.
• GLEW is a commonly used extension loader. Unfortunately extension loaders in general don’t seem to work with ANGLE so I haven’t used it much. glbinding and glLoadGen are both code generators that create loaders for specific target versions of OpenGL. These don’t seem to be able to target OpenGL ES versions however.

I have created a simple GL application on GitHub that I intended to be used as a starting point for OpenGL ES 2 experimentation. It should work on Windows, Linux and OSX, and the only external dependency should be CMake which is pretty easy to install. Then, hopefully, getting it running is a matter of (depending on your platform of choice):

1
2
3
4
5
6

git clone https://github.com/seshbot/new-gl-app
cd new-gl-app
mkdir build && cd build
cmake ..

./glapp

Alternatively you could try copying my sample GL HTML page and copy the webgl-utils.js file into a subdirectory called ‘js’ under that. Run the HTML file in your browser and you’ll have a WebGL app!

Understanding the OpenGL API

Note: I’m using OpenGL ES 2 GLSL syntax in my examples because I believe that’s probably got the broadest platform support, and is most similar to WebGL. The concepts are the same for later versions, aside from the syntactic differences. As I am focusing on explaining core concepts only OpenGL ES 2 should be fine for my purposes.

Take a moment to read some OpenGL specifications – they are probably easier to understand than you’d think. Here’s the OpenGL ES 2.0 Spec if you want a definitive source for all this stuff.

I will probably mention the Khronos Group a lot throughout this article. The Khronos Group is a consortium of companies such as Sun Microsystems, NVidia and Silicon Graphics who work on standardising graphics APIs, including OpenGL. Part of their OpenGL standardisation process is to provide reference interfaces (header files) for each version of the API that vendor implementations should conform to.

Here’s a bit of a glossary of terms and concepts that are necessary to become familiar with in order to be an effective OpenGL programmer.

The OpenGL API – commands, enums and objects

The OpenGL API consists entirely of commands (e.g., glDrawElements()), enums (e.g., GL_COLOR_BUFFER_BIT) and, conceptually, objects.

The commands and enums are described in the specification but can also be browsed on the Khronos API header files – have a look at GLES2/gl2.h for the standard GLES2 header. Most vendor implementations use these exact files as the entry point for their libraries.

OpenGL objects are the conceptual entities you create using the API, such as vertex buffers (VBOs), vertex arrays (VAOs), shaders, programs, textures and framebuffers. OpenGL has commands to create, bind and delete each of the different types of objects. Note that the objects you create are only valid with the context that was active when you created them!

OpenGL commands that operate on OpenGL objects require those objects to be bound. For example when you call glDrawElements() you don’t pass the program, the target framebuffer or the vertex or index buffer IDs to the function, it just operates on whichever program, framebuffer and vertex buffers are currently bound (through the glUseProgram(), glBindFramebuffer() and glBindBuffer() commands.) Many people feel this is a confusing and error-prone way to do things; it means that if you call some library or function that uses OpenGL there is no way to determine whether it has modified the current context in any way, so you have to re-bind all your stuff. It’s unfortunate but that’s the API we are stuck with :(

Note: it is interesting to note that the glCreate-type functions don’t actually create or allocate anything! They give you back a free handle, but that handle isn’t actually allocated until it is bound. This means that technically you’re free to keep track of these IDs yourself and allocate them according to whatever scheme you most desire, though I’m not sure why you’d do that.

OpenGL context

Here I’ll describe the concepts involved in creating and using OpenGL contexts. For a more tutorial-type approach have a look at this guide that shows how to use several different popular context management libraries.

The context encapsulates the rendering view, its rendering settings and which OpenGL objects are currently active (such as which shader will be invoked during rendering). When starting your application you will need to create a context and set the capabilities you want the driver will use while rendering, such as whether the renderer will perform scissor, stencil, depth or alpha testing, how the renderer will blend fragments into final pixel colours and what part of the window to render into (the viewport). Contexts are not thread-safe (unfortunately!) and are essentially global in scope (even more unfortunately!) and are the cause of most of the grief people have with OpenGL.

You should avoid querying the state of the context too much if possible (i.e., querying information about bound objects, or even constantly querying error state) – it is apparently quite slow. You should also avoid accessing context from multiple different threads. I believe you are supposed to create separate contexts in each thread you wish to render from, or more preferably not render from multiple threads at all.

It is also possible to create a shared context where objects created on one context are available in another. This can be tricky so proceed with caution – for example, according to the spec shared contexts may not share framebuffer objects for some reason. I found that out the hard way.

Unfortunately the creation of an OpenGL context is not defined by the OpenGL spec. If you want to create one you’ll either have to look up how to do this on your platform of choice (for example Windows provides WGL, while OSX and Linux systems use GLX) or use another third-party library that does this for you (I like GLFW, but SDL2 is very popular, and some people still use the older GLUT.) These libraries often give you access to keyboard and mouse input as well as various other utilities you might need when making your app (such as buffer swapping, text, audio and the like.)

Below is a simple example of creating a context using GLFW in C or C++. For a line-by-line explanation of this see the official GLFW docs.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

#include <GLFW/glfw3.h>

static void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods) {
    if (key == GLFW_KEY_ESCAPE && action == GLFW_PRESS)
        glfwSetWindowShouldClose(window, GL_TRUE);
}

int main() {
  if (!glfwInit())
      exit(EXIT_FAILURE);

  // create context (unfortunately GLFW bundles this in with window creation)
  GLFWwindow* window = glfwCreateWindow(640, 480, "Simple example", NULL, NULL);
  if (!window) {
    glfwTerminate();
    exit(EXIT_FAILURE);
  }
  glfwMakeContextCurrent(window);
  glfwSwapInterval(1); // wait for a vsync before swapping to avoid 'tearing'

  // tell GLFW to notify us when keys are pressed (esc will exit)
  glfwSetKeyCallback(window, key_callback);

  /////
  // OpenGL configure context capabilities
  glClearColor(1., 0., 0., 1.);
  glEnable(GL_DEPTH_TEST);
  glEnable(GL_BLEND);
  glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);

  // TODO: create OpenGL objects (shader programs, vertex buffers, etc) here
  ///

  // main loop
  while (!glfwWindowShouldClose(window)) {
    int width, height;
    glfwGetFramebufferSize(window, &width, &height);

    /////
    // OpenGL render
    glViewport(0, 0, width, height);
    glClear(GL_COLOR_BUFFER_BIT);

    // TODO: draw your primitives here!
    ///

    glfwSwapBuffers(window);
  }

  // TODO: destroy OpenGL objects here

  glfwDestroyWindow(window);
  glfwTerminate();

  exit(EXIT_SUCCESS);
}

Most OpenGL context management libraries are very similar in usage to this.

Primitives, Vertices and Fragments

Each time you call an OpenGL drawing function you are drawing a primitive. You can think of a primitive as a shape of some kind that can be either 2D or 3D and rendered as a collection of points, lines or triangles.

You specify the primitive type you want to draw when invoking glDrawElements() or glDrawArrays(). Among the valid types are:

• GL_TRIANGLES, which uses each 3 vectors to create a triangle. If you provide 9 vertices you will draw 3 triangles.
• GL_TRIANGLE_STRIP is more complicated in that it will use each set of 3 consecutive vertices to draw a triangle. In other words if you supply 4 vertices it will draw 2 triangles – one from v0, v1 and v2, another from v2, v1, v3. Notice that the first two vertices of every second triangle are re-ordered – this is to ensure that the triangles all face the same direction, as triangle direction is derived from which direction the triangle’s vertices appear to be counter-clockwise in order (relevant if face culling is enabled.)
• GL_POINTS, which renders unconnected dots. You can control the size of the points by calling the glPointSize() command in desktop GL or by setting the gl_PointSize GLSL variable in OpenGL ES. You can also apply a texture to the point to render more complex particles (the GPU passes your fragment a gl_PointCoord variable to indicate which texture UV coordinates you should render.)
• GL_LINES is useful for quickly drawing a wireframe of your model.
• there are also GL_LINE_STRIP, GL_LINE_LOOP, GL_TRIANGLE_FAN, GL_QUADS, GL_QUAD_STRIP and GL_POLYGON.

You will describe your primitives as collections of vertices. These vertices are passed to the GPU and it then transforms them to triangles then rasterises those triangles into fragments. These fragments may be filtered, blended and anti-aliased and ultimately may be drawn as pixels on your screen. So technically fragments are not pixels.

Coordinate systems

The OpenGL coordinate system is simple but requires some explanation – put simply, the range of visible coordinates within the viewport goes from -1.0 to 1.0 in the X, Y and Z directions. This coordinate space is known as normalized device coordinates or NDC, and anything falling outside of this range will not be rendered. The X and Y coordinates describe the horizontal and vertical component of the pixel (-1, -1 corresponds with the bottom left corner of the viewport) and the Z axis is the depth component that is used for depth testing (if enabled.) By default the NDC Z coordinates move away from the viewer, so +Z is into the screen.

But you won’t be using NDC directly – you will be rendering your primitives in what is known as clip coordinates, which are very similar to NDC except with a 4th dimension (x, y, z and w). You might be somewhat confused when you write your vertex shader, when setting the mandatory gl_Position variable with the vertex coordinates (described later) you’ll notice it is a vec4. What’s the 4th dimension for? It turns out the 4th dimension w is used for perspective division, which is super useful for 3D graphics but useless for 2D. For now you just have to know that when the GPU transforms from clip coordinates to NDC it calculates something like this: ndc_coords = clip_coords.xyz / clip_coords.w. So if rendering 2D stuff to the screen just set gl_Position.w to 1.0.

When programming in 2D you may choose to draw all your primitives using these NDC coordinates to avoid having to convert between coordinate spaces at all. The samples in this article draw primitives using normalised device coordinates directly.

3D coordinate systems are more complicated and I will discuss them in depth in a later article. For now it is interesting to note two things: first, by convention OpenGL coordinate systems other than NDC generally have the Z axis moving towards the viewer, so the negative Z axis goes into the screen.

Secondly, when rendering 3D primitives the verticies that describe the primitive are usually transformed in between a well defined sequence of coordinate spaces. The coordinates in the model’s local model space are first moved to world space where their position and orientation is given relative to all other objects in a scene (the same model may be used many times in the one scene, but each will look different if they have different model space transformations.) Then the coordinates are transformed to view space where their position and orientation are relative to the viewer’s eye. Then they are transformed into clip coordinates and finally NDC as before. I hope to go into more detail on this process in a later article – I just wanted to list the terms here for completeness.

One final thing I will mention about 3D coordinates is that it is common to specify 3D positions, directions and transformations using 4 dimensional vectors and matricies. I won’t go into it now but it is very useful to remember that positional coordinates generally have a 4th dimension w set to 1.0 and directions generally have w set to 0. This makes the linear algebra work out nicely when multiplying against transformation matricies as the 4th dimension in the vector usually controls the translation factor of the transformation, which is not relevant for directions (i.e., a ‘north’ pointing vector is stil pointing north no matter where the vector is located in space.)

Shaders and the render pipeline

Every time you call an OpenGL draw operation (the glDrawArrays() or glDrawElements() commands) you invoke the entire render pipeline. This is when the GPU passes the verticies in your primitives to your vertex shader, clips the resulting coordinates, generates triangles from the vertices, rasterises them into fragments, passes those fragments to your fragment shader then tests visibility, blends and dithers those fragments into pixels on your screen (or some other framebuffer.)

The difference between glDrawArrays() and glDrawElements() is in how the GPU knows which vertices to use when transforming your vertices into triangles. glDrawArrays() is simpler in that it builds triangles using the vertices in their given order – in a GL_TRIANGLES primitive, triangle T0 will be built from vertices V0, V1 and V2, triangle T1 built from V3, V4, V5 and so on.

glDrawElements() is more complex but often more performant. Instead of using the vertex data strictly in the order you declared them, it uses a separate buffer called the index buffer (also known as the element buffer) to determine which vertices to use in which triangles. This is great because it allows you to reuse vertices to create multiple triangles – an index buffer of [0, 1, 2, 2, 1, 3, 1, 0, 4] will construct 3 triangles from only 5 vertices! The first triangle will be using v0, v1 and v2, the second using v2, v1, v3 and the third using v1, v0 and v4.

Note: Vertex buffers are bound by invoking glBindBuffer(GL_ARRAY_BUFFER, my_buff_loc) and index buffers are bound with glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, my_buff_loc). Don’t ask me about the names.

Pipeline summary

To draw a primitive, the GPU first needs your vertex data. The GPU will decode your vertex data to extract vertex attributes and pass those into your vertex shader once for each vertex. Your vertex shader is expected to output clip coordinates for that vertex so the GPU knows where on the screen to show it (if at all,) and information that the GPU should pass on to your fragment shader for fragments derived from this vertex.

Once the GPU has processed all vertices the GPU can clip the vertices to within the NDC area only, it transforms those vertices into triangles and then rasterises the triangles into fragments which sort-of represent the pixels of the primitive being drawn. The GPU will then call your fragment shader for each fragment, passing it the relevant output data of your vertex shader. Your fragment shader is expected to output a colour and optionally a new depth-value for the fragment.

The GPU then processes, blends and dithers the fragments to the output framebuffer, as described under how the GPU writes fragments to the framebuffer a few pages down.

You invoke the rendering pipeline by calling either the glDrawArrays() or glDrawElements() commands (or one of their variations.) Unless you’re using the fixed function pipeline you’ll have to have a shader program bound so the GPU knows which vertex shader and fragment shader to invoke. You will also have to specify the vertex data (the vertex positions and perhaps other information such as the vertex normals and colours) of the primitive you are rendering. The ‘basic shader program’ a few pages down shows one way to do both of these things.

Once again, if you want more details on how this works have a look at the specs, like the OpenGL ES 2.0 Spec.

Passing data to the GPU – uniforms, attributes and varyings

There are two ways your application can pass data to your shaders – uniforms that are set only once per glDraw* call and and attributes that may be different per-vertex. In addition, fragment shaders receive per-fragment input derived from the output of the vertex shader in varyings (see the rendering pipeline diagram above.)

Sending uniform data to the GPU

A uniform represents a variable that remains the same for the rendering of an entire primitive. This might be something like the object material or the position of the sun. The pattern for setting a uniform is to first get a handle to the uniform with glGetUniformLocation(my_program, "my_uniform"). Pass this handle to the glUniform* functions to set the uniform (for example glUniform3f() will set a uniform of type vec3 in your shader.) Setting a uniform will make it available in any of the shaders in the bound program that are want to use it.

In the code example a few pages down you can see how the unifrom data is bound and updated:

1
2

  auto time_loc = glGetUniformLocation(shaderProgram, "time");
  glUniform1f(time_loc, glfwGetTime());

Uniforms may also be structures and arrays – the syntax to declare and use structs and arrays in GLSL (the shader code) is very similar to C, but setting them from the client application is a little tricky.

To set uniform values in a structure: you essentially treat the variable as if it is in the namespace of the structure name. E.g., if the shader contains the code struct Point { float x; float y; }; uniform Point p1; you can access p1.x with exactly that syntax: auto u_p1x = glGetUniformLocation(my_program, "p1.x").

To set uniform values in an array: you access the specific array element using standard C syntax. If the shader contains the code float xs[10]; you can get the location of a particluar element of xs with auto u_xs = glGetUniformLocation(my_program, "xs[0]"). You can use this uniform location to either set a single element using glUniform*() or set a number of the elements using glUniform*v().

Note: that you cannot apply offsets to the returned uniform location to access specific array elements – in the above example, I cannot call glUniform1f(u_xs + 2, 1.) as that could be the location of a totally different uniform. In this case you would either have to find the location of the element you want to access directly (in this case glGetUniformLocation(my_program, "xs[2]")) or set multiple elements (using glUniform*v()) in the array starting from the index we retrieved.

Sending vertex attribute data to the GPU

An attribute represents data related to the current vertex being processed. You specify where the GPU can find vertex data by calling the glVertexAttribPointer* functions for each vertex attribute in your vertex shader. This process is very different to specifying uniforms!

The standard form for using a vertex attribute is something like:

1
2
3
4
5
6
7
8
9
10
11
12
13

// ... first bind the appropriate shader

// during initialisation
GLint position_loc = glGetAttribLocation(shaderProgram, "position");
glEnableVertexAttribArray(position_loc);
const float vertex_buffer[] = { 0., 0., 0., ... }; // x, y, z positions
glVertexAttribPointer(position_loc, 3, GL_FLOAT, false, 0, vertex_buffer);
glDisableVertexAttribArray(position_loc);

// at render time
glEnableVertexAttribArray(position_loc);
glDrawArrays(GL_TRIANGLES, 0, 4); // draw verts 0..4 as triangles
glDisableVertexAttribArray(position_loc);

The above code snippet illustrates how to passing a raw pointer to your vertex data to the GPU. This is not the usual case, because quite often your buffered data will interleave more than one attribute’s worth of information (such as normals, vertex colours etc.) Usually you will create a vertex buffer object (VBO) and use glVertexAttribPointer() to dictate how the GPU should extract the vertex info from that.

vertex buffer objects are created, bound and destroyed like any other OpenGL object. You specify the data to buffer by calling the glBindBuffer() command with a pointer to the buffer. While this buffer is bound, any calls to glVertexAttribPointer() with a non-pointer in the final parameter will implicitly be referring to the bound buffer, using the final parameter instead as an offset into the buffer where the data may be found. This is necessary for interleaving vertex data in the same buffer.

Having a single buffer with different types of vertex information interleaved is very common. Your two tools for describing how this buffer data is formatted are the above-mentioned offset parameter and the stride parameter. While the offset describes the starting byte of an attribute in the buffer, the stride describes the total distance (in bytes!) between the start of that attribute and the start of the next instance of that attribute. A stride of 0 is considered special – it is used if the attribute is ‘tightly packed’, meaning the buffer contains only that attribute with no space between them.

This is best illustrated with an example:

1
2
3
4
5
6
7
8
9
10
11
12
13

float positions_and_colours_buffer[] = {
  -1., 0.,   1., 0., 0.,   // x, y,   r, g, b
  -1., -1.,  0., 1., 0.,   // x, y,   r, g, b
  // ...
};
glBindBuffer(GL_ARRAY_BUFFER, positions_and_colours_buffer);

auto position_offset = 0U;  // positions start 0 bytes in
auto colour_offset = 2 * sizeof(GLfloat); // normals start 8 bytes in
int stride = 5 * sizeof(GLfloat);  // each vertex is total 10 bytes

glVertexAttribPointer(position_loc, 3, GL_FLOAT, false, stride, (void*)position_offset);
glVertexAtrirbPointer(colour_loc, 3, GL_FLOAT, false, stride, (void*)colour_offset);

Note: in OpenGL 3.0 and above you will want to use vertex array objects (VAOs) to speed up your rendering process. A VAO offers you shorthand for binding vertex bufffers and the related vertex attributes for those buffers. This means that glBindVertexArray() can replace a number of glBindBuffer() and glEnableVertexAttribArray() commands.

The pattern for using this is:

1
2
3
4
5
6
7
8
9
10
11
12
13

// at init time when creating buffers
glBindVertexArray(my_vao);
  glBindBuffer(my_vbo);
  GLfloat verts[] = {0., 0.,  .5, .5,  0., .5 };
  glBufferData(GL_ARRAY_BUFFER, sizeof(verts), verts, GL_STATIC_DRAW);
  glEnableVertexAttribArray(position_loc);
  glVertexAttribPointer(position_loc, ...);
glBindVertexArray(0);

// at render time
glBindVertexArray(my_vao);
  glDrawElements(...);
glBindVertexArray(0);

I won’t be illustrating those here because I am focusing on OpenGL ES 2.0 for this article.

Sending per-fragment varyings to the fragment shader

Varyings are per-fragment data the fragment shader uses to calculate the output colour of a fragment. Examples of this might be the normal of the surface at that point, or the material colour interpolated from the material colours of the surrounding vertices. A 3D program will often use this information along with the location of the sun (passed through a uniform) in its lighting calculations – a fragment on a surface directly facing a light source will have a brighter colour than one not.

The calculation of what value is passed into a varying is a little bit tricky. Fragment shaders get their per-fragment input indirectly from the vertex shaders through variables called varyings. Of course for any three vertices forming a triangle you could have hundreds of fragments, so the GPU takes the varyings coming out of the vertex shader for each vertex influencing a fragment and interpolates them before passing them into the fragment shader.

The Vertex Shader

Below is a simple vertex shader that expects two input variables from the application: the uniform time and the vertex attribute vert_position.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// per-primitive variables passed in from your application
uniform float time;

// per-vertex variables passed in from your application
attribute vec4 vert_position;

// output data to send to the fragment shader for each fragment derived from this vertex
varying vec4 frag_colour;

void main() {
  // mandatory! calculate the NDC coordinates of this vertex
  gl_Position = vec4(0.01 * sin(time), 0., 0., 0.) + vert_position;
  // frags go from black on the left side to red on the right side of the viewport
  frag_colour = vec4((vert_position.x + 1.) / 2., 0., 0., 1.);
}

Note: GLSL (the shader language) allows the specification of precision for floating-point values, including all vec and mat types. Some versions of GLSL (at least GLSL ES) require variable precisions to be specified in all declarations and parameter lists (I have omitted these for brevity in my examples.) Valid precision values are lowp, mediump and highp. In general mediump is what you want, although for colours you can use lowp without any problems.

The Fragment Shader

The fragment shader captures all the logic required to determine the colour of a fragment. This might be as simple as just returning a uniform RGBA value or might involve complex 3D shading calculations incorporating a number of light sources and shadow maps. I will explore the 3D stuff in a later article.

A simple fragment shader that works with the above vertex shader might look like this:

1
2
3
4
5
6
7
8
9

// per-primitive variables passed in from your application
uniform float time;

// interpolated from output data of vertex shader
varying vec4 frag_colour;

void main() {
  gl_FragColor = frag_colour;
}

Note that the varying variables are not passed directly from the vertex shader but is actually interpolated from the results of all vertex shader invocations for the vertices surrounding this fragment. This means that, for example, colour gradients look smooth between vertices.

How the GPU writes fragments to the FrameBuffer

In this context the framebuffer is the rendering target, which is usually either the viewport or a texture. (Framebuffers are also used for other purposes such as combining multiple rendering passes that I will go into in a later article.) When the GPU has collected all the fragments it is going to render, it goes through a series of per-fragment operations to determine what gets written to the framebuffer.

First the GPU checks to ensure this bit of the viewport is actually owned by this framebuffer, because is possible to have one viewport obscuring another. Next the fragment is tested against the scissor test region, the stencil buffer, then the depth buffer, if those capabilities are enabled in current context. If a fragment fails one of these tests it is discarded. Then the GPU performs a blending operation if enabled on the context, blending the fragment against what is read from the framebuffer before the render operation began. The resultant fragment is finally written to the framebuffer. Furthermore, if the framebuffer has multisampling enabled (for anti-aliasing) it may merge multiple fragment colours (or samples as they are called now) into a single pixel.

Basic shader program example

The partial application code below shows a basic vertex shader, fragment shader being invoked to render a square in the middle of the window.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

  // just define our shader in-line
  const char vertex_src[] = "\
    uniform float time;       // passed in for whole primitive \n
    attribute vec2 position;  // passed in with vertex data \n
    attribute vec3 colour;    // passed in with vertex data \n
    varying vec4 frag_colour; // passed out to frag shader  \n
    void main() {                                           \n
      // this is where we would transform to NDC, but  our coordinates are already NDC
      // so just pass the position through as-is with a little animation \n
      gl_Position = vec4(position * sin(time), 0., 1.);     \n
      frag_colour = vec4(colour, 1.);
  }";
  const char fragment_src[] = "\
    varying vec4 frag_colour; // passed in from vert shader (and interpolated) \n
    void main() {                              \n
      // fragment colour is dark gray          \n
      gl_FragColor = frag_colour;
  }";

  // create shaders
  auto vertexShader = glCreateShader(GL_VERTEX_SHADER);
  glShaderSource(vertexShader, 1, &vertex_src, NULL);
  glCompileShader(vertexShader);
  auto fragmentShader = glCreateShader(GL_FRAGMENT_SHADER);
  glShaderSource(fragmentShader, 1, &fragment_src, NULL);
  glCompileShader(fragmentShader);

  // create shader program using the shaders
  GLuint shaderProgram = glCreateProgram();
  glAttachShader(shaderProgram, vertexShader);
  glAttachShader(shaderProgram, fragmentShader);
  glLinkProgram(shaderProgram);    // link the program
  glUseProgram(shaderProgram);    // and select it for usage

  // these are the NDC coordinates of a square on the viewport
  static const float vertexArray[] = {
     0.0, 0.5,   1., .5, .5,    // x, y,  r, g, b,
     -0.5, 0.0,  .5, 1., .5,    // x, y,  r, g, b,
     0.0, 0.5,   1., .5, .5,    // x, y,  r, g, b,
     0.0, -0.5,  .9, .9, .9,    // x, y,  r, g, b,
     0.5, 0.0,   .5, .5, 1.,    // x, y,  r, g, b,
  };

  // we need this to pass the 'time' uniform to the shaders
  auto time_loc = glGetUniformLocation(shaderProgram, "time");
  // we need this to pass the 'position' and 'colour' attributes in to the vertex shader
  auto position_loc = glGetAttribLocation(shaderProgram, "position");
  auto colour_loc = glGetAttribLocation(shaderProgram, "colour");
  glEnableVertexAttribArray(position_loc);
  glEnableVertexAttribArray(colour_loc);
  // glVertexAttribPointer allows you to specify vertices in many ways, so its pretty complicated
  glVertexAttribPointer(position_loc, 2, GL_FLOAT, false, sizeof(GLfloat) * 5, sizeof(GLfloat) * vertexArray);
  glVertexAttribPointer(position_loc, 3, GL_FLOAT, false, sizeof(GLfloat) * 5, sizeof(GLfloat) * (vertexArray + 2));
  glDisableVertexAttribArray(position_loc);
  glDisableVertexAttribArray(colour_loc);

  while (!quit) {
    // ... clear viewport etc 

    glUniform1f(time_loc, glfwGetTime());

    glEnableVertexAttribArray(position_loc);
    glEnableVertexAttribArray(colour_loc);
    glDrawArrays(GL_TRIANGLE_STRIP, 0, 5);
    glDisableVertexAttribArray(position_loc);
    glDisableVertexAttribArray(colour_loc);

    // ... swap buffers etc
  }

This should look something like this:

Immediate mode and the fixed function pipeline

I discuss this more when discussing the different OpenGL versions below, but OpenGL 1 was much simpler to use than later versions, though much less powerful. OpenGL 1 operated using a fixed-function pipeline using an immediate mode API, where the programmer not only describes high-level primitives’ individual vertices but also describe the lighting model to use, define several lights and set up materials to use during rendering. Retained mode allows all of this functionality to be executed on a shader program, which is written by the developer but run on the GPU directly. This is much more performant but requires a lot of extra work on the part of the developer.

The term immediate mode means that the drawing operations are explicitly executed in your client application each frame, which is considered slower because it ties the client application logic too closely with the GPU rendering operations, so the GPU is not able to make as many optimisations as it would if the instructions were on the GPU itself (retained mode.)

Linear algebra (magic!)

Linear algebra is the language of graphics programming. You need to learn some basics if you’re going to tackle this stuff. I won’t go into what a vector or matrix is here but you will have to learn the basics of their form and function if you don’t already know them.

The most basic understanding you should have is that vectors are usually used to describe coordinates in space and directions, and matricies are used to describe transformations (translation, scale, rotation, shear etc) to those vectors. Another thing to note is that a single matrix may represent an accumulation of many different transformations performed in sequence, so if I said (in pseudo-code) auto m = translate * scale * rotate, then any time I multiply m by a vector it will have the same effect as performing all of those transformations at once – amazing!

Once again, the OpenGL API does not help you in dealing with matricies or vectors, but there is a great supporting library that does – GLM.

There are two ways the elements in a matrix may be stored – OpenGL programmers often use column-major matrix layouts. This is a convention only, but is generally used in the official documentation and in OpenGL support libraries such as GLM. The reason this is important is that unlike scalar multiplication, matrix multiplication is not commutative, meaning A * B does not equal B * A. The main impact of using column-major vs row-major matricies is the order of multiplications must be reversed to have the same effect. In column-major (the most usual) you would accumulate your transformations to the left, so if you want to first rotate (R) then scale (S) then translate (T) last, you would execute T * S * R. A more common example would be when calculating the model view projection matrix it would be accumulated as mat4 mvp = P * V * M. When calculating this with a row-major library you would be expected to accumulate it as mat4 mvp = M * V * P. Converting a matrix to or from column-major to row-major is known as transposing the matrix.

A common term in linear algebra is the identity matrix. This is a matrix I where multiplying it with another matrix A gives that matrix (I * A = A.) It is easily recognisable as it is entirely made of 0s with 1s on the diagonal.

Another generally useful matrix operation is the inverse of a matrix. The inverse of a matrix A is the matrix required to multiply with A so that the result is the identity matrix. In other words, Ai * A = I. This is useful when rolling back a matrix multiplication. If you have the model view projection matrix mat4 mvp = proj * view * model, you can find the model view matrix by calculating the inverse projection inv_proj and calculating: mat4 mv = inv_proj * mvp.

Vector operations are even more interesting. A few things I want to point out here are dot product, cross product and the difference between positional coordinates and directional coordinates.

The dot product operation (sometimes known as the inner product) is used for many purposes; the dot product of two vectors A and B is a scalar (not a vector) number that is the sum of the products of their components (e.g., auto a_dot_b = A.x * B.x + A.y * B.y + A.z * B.z). It turns out that this simple formula gives you the cosine of the angle between those vectors multiplied by their magnitudes (|A||B|cos(Ɵ)), which is really useful because:

• if the vectors are unit vectors (they each have magnitude of 1) the dot product will just give you cos(Ɵ) which is a number between 0 and 1, where 0 implies that they are perpendicular to each other (at 90 degrees) and 1 implies they are parallel. This is great for calculating how much light should bounce off a surface if the light direction is one vector and the surface normal is the other.
• if the vectors are both unit vectors you can inverse cos the dot product to find the angle between the vectors (auto angle = acos(dot(A, B)))
• you can find the projection of vector A onto vector B by finding the dot product of A and B then dividing the result by the length of A.
• calculating the dot product of a vector with itself will give you the distance squared. If you are checking to see which vector is longer, you can just compare their squared distances (saving you a square root operation)

The cross product is another simple formula that gives you a vector that is perpendicular to two given vectors. In other words, if you have vectors A and B that both lie along the same surface, calculating cross(A, B) will give a vector that represents the normal to that surface. This normal vector will also follow the right-hand rule as pictured below (Note: you will usually want to normalise your normal before using it, so lighting calculations can dot product them straight out of the box!)

OpenGL versions and extensions

A constant frustration when reading documentation and code examples is that OpenGL 1.0 is worlds apart from OpenGL 2.0. Many of us would have been well served if they had given it a totally different name, so different are the products!

OpenGL 1 functions in what is now called immediate mode and is considered deprecated. In this version the programmer describes the scene lights, materials and fog, then notifies the driver of each polygon explicitly. The driver would then render the scene using its own internal lighting model using the described lights and materials. This is called the fixed function pipeline.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// configure light
glEnable(GL_LIGHTING);     // deprecated
glEnable(GL_LIGHT0);       // deprecated
glLightfv(GL_LIGHT0, GL_AMBIENT, {.4f, .1f, .1f}); // deprecated

// draw a primitive
glPushMatrix();            // deprecated
// matrix operations will apply to all vertices until glPopMatrix()
glLoadIdentity();          // deprecated
glRotatef(3.14f, 0., 0., 1.); // deprecated
glBegin(GL_TRIANGLE);      // deprecated
  glVertex3f(.0, .0., .0); // deprecated
  glVertex3f(.1, .0., .0); // deprecated
  glVertex3f(.1, .1., .0); // deprecated
glEnd();                   // deprecated
glPopMatrix();             // deprecated
glFlush();

OpenGL 2 introduced shaders, yet still provided compatability with the above described model. Shaders had access to the state declared in the fixed function pipeline through standard global variables (such as the gl_LightSource[] array and the gl_FrontMaterial variable sent from the client and the gl_ModelViewProjection matrix which was generated by the driver.) The vertex shader can invoke the standard fixed-function pipeline functionality by callling gl_Position = ftransform();.

OpenGL 3 completely deprecated the immediate mode fixed-function pipeline. Of course this introduced backwards-compatability issues so they also introduced several profiles to allow backward compatability to be optionally compiled in. The compatability profile can be requested to enable deprecated features, while the core profile disallows the use of these features.

Since OpenGL 2 however there have been no truly large architectural changes (unfortunately.) Changes have focused around adding features (new types of shaders, for example) to provide better performance and more generally useful aspects of existing functionality. This is a shame because there are still a lot of problems with OpenGL that many developers want addressed – the original goal of OpenGL 3 was to include massive refactorings to remove all the global state (more on this later) but vendors objected so strenuously that this work was put off until GLNext which is now known as Vulkan.

OpenGL shaders are written in their own language – GLSL. GLSL has its own varied syntax between versions, and to make things even more complicated they support the notion of extensions. The best bet is to decide on which version of OpenGL you will be learning and learn the GLSL appropriate to that version. They are all quite similar in form but are syntactically incompatible with each other.

Some mention should be made regarding extensions. Extensions are often touted as a great feature in OpenGL not available in other graphics libraries such as DirectX. New commands and enumerations are often added to the OpenGL API by vendors as extensions, and then if this functionality proves popular it becomes formalised as part of the API in a later version.

Each OpenGL version has a known set of extensions. These can be browsed in the Khronos reference implementations – for example the OpenGL ES 2 extensions are in the GLES2/gl2ext.h header file. There are idiomatic ways to detect support for and load these extensions using system calls but most people use an extension loader of some type. A very popular extension loader is the OpenGL Extension Wrangler Library (also known as GLEW.)

If you want some functionality not natively available in your chosen version of the OpenGL API you will often find an extension that provides that functionality. The problem is, extensions are not supported uniformly on all platforms with all drivers, so quite often you’ll have to work around the missing functionality in some platform anyway. This severely limits the usefulness of extensions, and in general you should try to do without them if possible.

I personally do use a few extensions in a few circumstances: either to get around eccentricities of a particular platform (e.g., some Windows platforms use BGRA instead of RGBA framebuffer formats, which are only available through the GL_EXT_texture_format_BGRA8888 extension) or if I have through experimentation determined that an extension is very broadly supported.

Here’s a quick summary of what I understand of the different OpenGL versions:

OpenGL 1 – high level and slow but simple

• Immediate mode only (fixed function pipeline)
• no shaders
• a lot of people still use this when demonstrating functionality
• only version natively supported by Windows

OpenGL 2 – shaders run on the GPU

• first shader-based version
• vertex and fragment shaders
• still have access to the fixed function pipeline – even within shaders

OpenGL 3 – a controversial release

• framebuffers for rendering to non-screen targets (e.g., render to a texture)
• vertex array objects (VAOs) allow great performance boosts by quickly binding and unbinding whole groups of buffers and attribute bindings
• geometry shaders (modify/extend geometry of primitives)
• significant (breaking!) changes to GLSL shader language
• deprecated most 1.0 functionality (immediate mode stuff) introducing compatability and core modes
  • compatability mode gives access to the old fixed function pipeline
  • core mode does not

OpenGL 4 – modernisation, performance and professional enhancements

• OpenGL 4.0 goal was to achieve parity with Direct3D 11
• OpenGL 4.5 goal was to achieve parity with Direct3D 12
• tesselation shaders introduce extra polygons for ‘denser’ meshes with smoother curves
• compute shaders for using the GPU for non-graphics computations (GPGPU stuff)
• GPGPU compute shader uses SPIR – an intermediate language based on LLVM
• Direct State Access – mitigate long-standing architectural problems with immediate mode
• modern OSX supports up to OpenGL 4.1

OpenGL ES – simplified for embedded systems

• OpenGL ES 1.0 based on OpenGL 1.3
• OpenGL ES 1.1 based on OpenGL 1.5
• OpenGL ES 2.0 based on OpenGL 2.0
  • WebGL is based on OpenGL ES 2.0
  • Google ANGLE project provides OpenGL ES 2.0 support on Windows (wraps DirectX API)
• OpenGL ES 3.0 full subset of OpenGL 4.3
  • GLSL ES 3.0 based on GLSL 3.3
  • similar to OpenGL 3 but without geometry shaders
  • supported by modern iOS and Android devices
  • experimental support in Google ANGLE project

WebGL

• based on OpenGL ES 2.0
• I don’t know much about this yet, but WebGL Fundamentals is a great resource

Vulkan – GLNext, lots of hype but not much information yet

• get away from immediate mode single-threaded global state context heritage
• allow shaders to be written in a variety of languages
• http://arstechnica.com/gadgets/2015/03/khronos-unveils-vulkan-opengl-built-for-modern-systems/

I have chosen to do most of my experimentation in OpenGL ES 2. This should give me the broadest platform availability as well as being compatible with WebGL for web demonstrations. I have resorted to using a few extensions that are supported on the platforms I use where necessary (e.g., to get anti aliasing), though I try to avoid this where possible.

Challenges you will face

• Having to learn support libraries in addition to the OpenGL API
• Cross platform support is difficult as many features are not uniformly supported
• Debugging GL state in different platforms – OpenGL debugging tools are not great, and there are none that work cross-platform
• Multithreading correctly is extremely difficult – if possible just do all your rendering on one thread!
• Managing extensions can be a pain in the ass
• State management – OpenGL uses global state, so it is impossible to write optimal abstractions because cannot encapsulate state, and state querying is prohibitively expensive. So you end up redundantly setting state that has often already been set.
• lots of problems: http://richg42.blogspot.jp/2014/05/things-that-drive-me-nuts-about-opengl.html

Documentation and tutorials

As I mentioned there’s not a lot of great documentation out there. I started to create my own responsive OpenGL documentation and then discovered that there’s already a pretty sweet one out there called docs.gl. Docs.gl is great because it makes it clear which commands are supported in which versions of OpenGL – something that’s hard to figure out from the more official sources.

A great beginner tutorial is open.gl – it’s modern, minimalistic and well written. A very similar-seeming tutorial series that goes into more advanced techniques is Learn OpenGL. There used to be a fantastic series called the ArcSynthesis tutorials but they seem to have died. There is a PDF version of their content that seems pretty good though.

OGLdev is a series of tutorials that go into more depth than the open.gl site above, and is in bite-sized chunks for easier consumption.

If you want to step through some sample code, download the OpenGL-Examples github repository. It seems pretty easy to use and goes into fairly advanced topics.

If you want really really detailed runthrough of the graphics pipeline, have a look at the ryg blog. I haven’t made my way through it yet but I really want to. Fabien Gleson seems to be pretty knowledgable about not only low level rendering details but also general low level computing concepts in general.

Finally, if you’re into WebGL you should check out Gregg Tavares’ WebGL Fundamentals. Gregg has a lot of experience working on WebGL in Chrome and game programming in general and has made some fantastic javascript support libraries that make every-day WebGL much simpler.

As I mentioned before though, you can easily try reading the specs yourself. Google is your friend here – search for the specific version + ‘spec’ and it will usually be the first hit.

Debugging

There are many different OpenGL debugging tools on different platforms and they are all generally pretty bad. I haven’t spent a lot of time with any of them so please tell me if you find a good one!

If you’re on OSX you can give the OpenGL Profiler a go – it allows you to set breakpoints on certain GL calls, look at frame buffers (though I found this difficult to do) and much more.

Windows users should check out RenderDoc, which allows you to track API calls, view render buffers and a lot of other stuff, for both OpenGL and DirectX. You can also invoke the DLL directly to dump various information from within your application. I haven’t used it myself though so I won’t go on further.

It’s also a great idea to have some macros that optionally call glGetError() after every OpenGL call you make so you can easily track down where things begin to go awry. Unfortunately though querying the context can be fairly expensive so you should make it easy to disable this macro when things are not going awry.

Feel free to copy-paste this into your codebase:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// #define DEBUG_OPENGL_COMMANDS // uncomment this to enable error checking

#ifdef DEBUG_OPENGL_COMMANDS
  void checkOpenGLError(const char* function, const char* file, int line) {
    auto err = glGetError(); if (err == GL_NO_ERROR) return;
    const char * err_msg = "unrecognised";
    switch (err) {
      case GL_INVALID_ENUM: err_msg = "GL_INVALID_ENUM"; break;
      case GL_INVALID_VALUE: err_msg = "GL_INVALID_VALUE"; break;
      case GL_INVALID_OPERATION: err_msg = "GL_INVALID_OPERATION"; break;
      case GL_STACK_OVERFLOW: err_msg = "GL_STACK_OVERFLOW"; break;
      case GL_STACK_UNDERFLOW: err_msg = "GL_STACK_UNDERFLOW"; break;
      case GL_OUT_OF_MEMORY: err_msg = "GL_OUT_OF_MEMORY"; break;
      case GL_INVALID_FRAMEBUFFER_OPERATION: err_msg = "GL_INVALID_FRAMEBUFFER_OPERATION"; break;
      default:
    }
    // on Windows call ::OutputDebugString 
    fprintf(stderr, "OpenGL error '%s' (0x%04x) called from %s in file %s line %d\n",
      err_msg, err, function, file, line);
  }

#  define GL_VERIFY(stmt) do { stmt; checkOpenGLError(#stmt, __FUNCTION__, __FILE__, __LINE__); } while (0)
#  define GL_CHECK() do { checkOpenGLError(__FUNCTION__, __FILE__, __LINE__); } while (0)
#  define GL_IGNORE(stmt) do { GL_CHECK(); stmt; glGetError(); } while (0)
#else
#  define GL_VERIFY(stmt) stmt
#  define GL_CHECK()
#  define GL_IGNORE(stmt) stmt
#endif

Then you just wrap all your function calls like so: GL_VERIFY(glDrawElements(...)). If you want to just check for errors at a particular point in your code, just call GL_CHECK().

One final interesting note about debugging OpenGL: If you are using a Google’s ANGLE OpenGL driver that you compiled yourself you can step into it, so if you start getting vague sounding errors like GL_INVALID_FRAMEBUFFER_OPERATION but want to know specifically what the problem is, you can step into the ANGLE DLLs yourself to see which part of their validation fails. It’s like running a own fully-compliant validation layer in your own client code.

Upcoming

Now that I’ve gotten all the basic stuff out of the way I’d like to go into a bunch of other more advanced things that I thought wasn’t particularly easy to get help with. In no particular order:

• Pros and cons of writing an OpenGL wrapper library (my glpp library)
• Building and using Google’s ANGLE library
• Using OpenGL for 2D:
  • setting up the GL context (depth buffer)
  • basic 2D coords
  • drawing primitives
  • simple texture
  • using orthographic projection with 2D
• Using OpenGL for 3D:
  • setting up the GL context (blending, face culling)
  • 3d coordinate system (plus MVP, normal matrix)
  • drawing primitives
  • perspective projection and the frustum
• 3D lighting
• 3D shadows
• Particle systems
• Texturing (textures, texture unit and samplers), sampling, blending, alpha discard, stencil testing, glTexStorage
• Multi pass rendering (using FrameBuffers):
  • Render scene –> FBO –> texture colour buffer –> screen rectangle –> post effect frag shader –> screen
  • Post processing (HSV and gamma correction)
• Loading models and animations (using assimp)
• Rendering text (using stb)
• Using Qt/QML with OpenGL
• Object Picking in a 3D scene

BUT I have done a lot. Below the fold I talk about starting a C++ OpenGL library, creating some nicer OpenGL documentation, learning Blender 3D, setting up a new computer and moving country.

On the side I’ve been helping a mate out set up an e-commerce site for his new Japanese brewery – more information to come when it is released in a few months!

Australian lifestyle

Things are really breezy here – it is a great relief to be in a country where I can just pick up a medicare card, or drivers licence, or bank card, or ANYTHING that involves beurocracy and signing documents without worrying about not understanding or sitting through hours of pawing through contracts and legalese, or running up against brick walls because I’m a foreigner. Although the service is generally not as nice as that in Japan, people are more willing to take the initiative when helping you out.

Everything is a long drive away. The computer store PLE is easily a 30 minute drive away, out in one of Perth’s industrial areas. Oh and speaking of that, there are very very few good computer stores around here. PLE is fantastic however, all staff members I’ve spoken with are really knowledgable about hardware and have been super helpful.

Pretty soon I’ll set up an ABN (business entity) because its easy to do and I would like to make some business cards…

My new office

I’m currently living in Kalamunda – a beautiful area in the hills east of Perth, although it’s a bit far from anywhere (as is everything else in WA!) As predicted the internet in Australia has been nothing but trouble, but we are close to the exchange so once I get some technical stuff sorted out we should have OK speeds (although with a download cap which feels very 90s).

The big lesson I’ve learned is that no company that provides a utility (e.g., telephony) should ever be privatised. They live in a privileged state of natural monopoly and will always screw their customers by providing the cheapest possible service, if any service at all.

My new computer

To celebrate moving to Australia, and because my old office computer is in a box on the ocean somewhere, I decided to get a new well-spec’d machine. Having last built a machine about 15 years ago I decided to trust in the most recent ArsTechnica system guide by largely basing my decisions on the Hot-Rod specifications contained therein.

It features:

• CPU: Intel Core i5-4590
• Motherboard: Asus H97M-E
• RAM: 16GB (2x 8GB) DDR3-1600 (can’t recall brand)
• SSD: Samsung 840 EVO 250GB
• Case: Corsair Obsidian 350D
• GPU: I reused my NVidia 550 GTX from my previous machine
• PSU: I also brought my old 750W power unit from Japan

Windows 8 boots up really quickly and the machine in general is just super speedy and a pleasure to use. I am especially happy with the case, it pops open and closed easily without tools and has fantastic airflow and filtering.

New OpenGL work

I have put aside the game stuff I was doing to focus on my core OpenGL knowledge a bit. OpenGL is crufty and problematic to use, and often if you make a mistake it can take hours or days to figure out what the problem is.

As such I begun work on glpp – a C++ library that provides a strongly-typed interface to OpenGL that also features utilities to easly create rendering pipelines, typed buffers, and under the covers utilises third-party libraries to provide context creation, image loading and 3d model loading. It also builds on OSX and Windows (using ANGLE so you dont have to install your own OpenGL drivers!) and targets OpenGL ES 2.0 to ensure maximum support across platforms.

I want to try automatically generating my type-safe versions of the OpenGL API (enums, bit fields and functions), and would like to somehow transform the Khronos OpenGL API Registry to reduce the amount of manual work required. In considering this I came up with another idea – how about making some nice interactive documentation that doesn’t suck as much as all the other docs!?

So with this in mind I have started experimenting with creating a static single-page-app with Ember.js that will source a set of auto-generated JSON docs of my own fashioning, using the ‘fixture adapter’ instead of loading data from some REST-ful service. I created a github repo called gldoc which I’ll be pushing my efforts into. For now it’s just a small skeleton Ember app though, as I struggle to recall how Ember works.

Of course instead of writing an ember app and generating the JSON data I could just generate a bunch of static pages (or maybe make it single page with creative uses of divs, jQuery and handlebars), but I would like to mess with ember a bit more so I’ll go down that route.

In other news however, Microsoft has release Visual Studio 13 ‘community edition’ which is totally free to use! This is fantastic news as the ‘express edition’ was missing a bunch of features I really like using such as performance profiling and the interactive command window, among other things.

3D modelling with Blender

To cut a long story short, Blender is a very nice 3D modelling application. If you want to learn it I would highly recommend starting with the Blender Cookie introduction for beginners series of videos. Also, install the ‘pie menus’ (look it up) – they make switching between states super simple.

Games

I went a bit crazy and decided to start playing Dark Souls and the new Elite: Dangerous.

Dark Souls is so awesome I am considering making a lets play video as I’ve seen others do. I downloaded OBS and am excited to give it a try.

Elite: Dangerous is a fantastic successor to the Elite games of the 80s, made by the same guy via KickStarter. The feel of the game is fantastic, but the multiplayer aspect is quite lackluster at the moment – it is very difficult to locate your friends or help them out in battles etc. But at least it HAS a multiplayer aspect!

In fact I enjoy the game so much I purchased a ThrustMaster T-Flight HOTAS X which makes the experience much better. I am seriously considering an Oculus Rift as well, as in addition to the natural synergies with this game, I’d love to try making some software for it.

Finally, I headed into Tactics in Perth and purchased Ticket to Ride, Munchkin and an Adventure Time card game as well.

Blogging

I have learned so much about OpenGL over the last few months that I can envisage a 4 or 5 part series of articles on the subject. Specifically exploring what OpenGL is and how to get started, how to set up a simple 2D scene, how to set up a typical 3D scene (including shading), shadows and stencils, frame buffers and render pipelines, and texturing.

Most attention on the new C++ has focused on the changes that provide functionality and performance that was previously not possible, both library enhancements (chrono, regex, smart pointers, and stuff to help with lambdas for example) and core language enhancements (perfect forwarding, variadic templates, the new memory model and threading capabilities, initialiser lists and the like). This functionality will impact us all in helping to write more correct code and efficient libraries, but often will only be relevant in certain parts of our code.

But the first thing that struck me when I started using C++11 was the smaller features that I could take advantage of every time I put my fingers to the keyboard. These are the things that make code more concise and simple and allow me to present my intentions more clearly.

Stuff I take advantage of every day:

• more concise general coding:
  • lambdas for scoped initialisation or inline ‘builder’ functions
  • new standard library functionality for string manipulation, particularly std::to_string() and std::stoi() etc
  • range-based for loop
• clearer declarations:
  • inline member initialisation,
  • the override, default and delete keywords
  • delegating constructors,
  • uniform initialisation, especially when invoking or returning from functions
  • auto type deduction everywhere!
• far fewer dependencies on boost

These are the things I think all C++ programmers should learn first, because they benefit you straight away and confer very little risk of being learned wrong.

At the very end I also mention a few upcoming features that I’m really excited about as they will be game-changers.

More concise coding

These are the most obvious every-day enhancements, mostly focusing on making code easier to write and to read. Some of the most pleasing languages to use (like F#) are so because the ratio between language constructs and code relating to logic is very low.

use the auto keyword where possible

The auto keyword should be used wherever possible. Functions should be short and readable, so don’t pollute your code with unneccessary type declarations! Curmudgeons often claim they prefer to see the type written with the declaration, but I think readability and maintainability trumps this. Yes, maintainability – you want to be able to change return values, template signatures, class names and such, and auto adapts without complaint.

Scott Meyers dedicates a chapter to this in his new ‘Effective Modern C++’ book (the item is Item 4: Prefer auto to explicit type declarations) – also have a look at his presentation also entitled Effective Modern C++ where he covers the matter.

If you’re still unconvinced, academican helpfully pointed out on the reddit discussion of this article that Herb Sutter wrote a series of GOTW articles on this topic last year which defend the principle of “Almost Always Auto”. He does a much better job than I could . The third article explores this topic particularly thoroughly.

These articles are a real treasure-trove, where Herb concludes that:

• Guideline: Prefer to declare local variables using auto x = expr; when you don’t need to explicitly commit to a type. It is efficient by default and guarantees that no implicit conversions or temporary objects will occur
• Guideline: Prefer to declare local variables using auto. It guarantees that you get the exact type and so is the simplest way to portably spell the implementation-specific type of arithmetic operations on built-in types, which vary by platform, and ensure that you cannot accidentally get narrowing conversions when storing the result
• Guideline: Remember that preferring auto variables is motivated primarily by correctness, performance, maintainability, and robustness—and only lastly about typing convenience

If you still don’t agree with Scott and Herb, two of the most influential C++ gurus out there, then perhaps it would be well worth exploring why – if you know something they don’t you’re probably able to make a lucrative living lecturing!

other uses for lambdas

Lambdas are of course a fantastic feature that helps us all out in so many ways. But I tend to use it in general day-to-day stuff for what I call inline builder functions. This is when you want to perform some complicated ritual to create some resource but don’t like setting your resources to some default ‘uninitialised’ state.

For example:

1
2
3
4
5
6
7
8
9

// create an immutable type or one that has no 'uninitialised' state
const int calculated = [&] {
   auto l = lock();
   auto first = stage1();
   auto second = stage2();
   return combine(first, second);
}(); // notice I invoke the lambda here!

// ... use the calculated value

Of course you could put this functionality in a function somewhere but this means you don’t pollute your class namespace, and the functionality is localised to the place you use it.

range-based for loops

The range-based for loop is also a no-brainer. It is not as useful as it could be – for example you often want to maintain some index as you iterate over something, and the standard library (and even boost range) don’t provide a nice wrapper around iterators to help with this.

As a side note (I don’t actually do this very often,) you can extend any type to be range-based for loop-compatible by providing specialisations of std::begin() and std::end() for that type. For example, I suppose one could do:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

struct irange { int First; int Last; };
struct irange_iterator {
   int Val;

   // minimalistic forward-iterator implementation
   int operator*()                            { return Val;          }
   bool operator!=(irange_iterator const & r) { return Val != r.Val; }
   irange_iterator operator++()               { return {++Val};      }
};

// begin() and end() are invoked by range-based for
irange_iterator begin(irange const & r) { return { r.First }; }
irange_iterator end(irange const & r) { return { r.Last + 1 }; }

int main() {
   for (auto v : irange{10,20})
      std::cout << v << ", ";
}

// prints '10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,'

…but don’t do it – the iterator is incomplete (and non-const-correct, and probably buggy) and it doesn’t cover reverse ranges for starters. Plus there are some cool libraries out there, like CPPItertools perhaps?

Many new basic STL utilities

But one thing people dont mention much is that the standard library now includes a bunch of small helper functions for basic string conversions! Previously one might use boost lexical_cast<>() for this sort of thing, but now you can generally rely on std::to_string() overloads and std::stoi() and its variants to do the simple stuff for you.

The standard library also has new container types and algorithms. If you haven’t familiarised yourself with the new std::unordered_map and std::array containers you really should. And new algorithms that you’d kick yourself for reimplementing include all_of()/any_of()/none_of(), iota(), minmax(), is_permutation() (as well as all the other is_ functions) and shuffle. See this well-known Sean Parent’s talk on C++ Seasoning for some great discussion on using C++ algorithms to their fullest.

Clearer declarations

Initialisation is the backbone of C++ – typically all resources should be allocated and initialised in constructors and released deterministically in destructors according to very specific rules, ensuring exception safety and preventing resource leaks.

Initialisation is much simpler

C++11 allows us to focus on our intents more than focusing on our types. For example, the auto keyword and uniform initialisation both make code far clearer:

For example, we can expect to use a nice 3D mesh API like so:

1
2
3
4

auto square = create_triangle_mesh({
   {-1, 1, 1}, {-1, -1, 1}, {1, -1, 1},
   {-1, 1, 1}, { 1, -1, 1}, {1,  1, 1},
});

This smacks of ‘struct initialisation’ which I really liked:

1
2
3
4
5
6
7
8
9

struct TcpHeader {
   uint16_t src_port; uint16_t dst_port;
   uint32_t seq;
   uint32_t ack;
   // ... plus other stuff
}

// this works in C++03 as well
TcpHeader hdr = {10012, 8088, 0x01, 0x01, /* ... */ };

Construction is much more flexible

Now for trivial types you sometimes don’t need a constructor:

1
2
3
4
5
6
7

// no constructor needed!
struct counter {
   int last_ { 0 };
   int step_ { 1 };

   int next() { last_ += step_; return last_; }
};

Now there’s a way to share construction code without resorting to a private init() function:

1
2
3
4
5
6
7
8
9
10

struct counter {
   int last_;
   int step_;
   counter()
   : counter { 0, 1 } { } // delegating constructor!
   counter(int last, int step)
   : last_(last), step_(step) { }

   int next() { last_ += step_; return last_; }
};

More explicit inheritance

I have always been jealous of languages that have the override keyword, because a common trap when refactoring is to rename a virtual base method – the compiler cannot warn you that you forgot to replace the overridden methods in specialised classes (unless it is pure virtual, which it really should be, but anyway…)

1
2
3
4
5
6
7
8

struct base {
  virtual string name() { return "default"; }
};

struct derived : public base {
   // compile error - xname() is not an inherited member! 
   virtual string xname() override { return "derived!" }
};

The default keyword can be a godsend to the concientious coder who likes to always obey the ‘rule of three’ (or now the rule of five, or rule of zero as of lately.) Again the benefit is in reducing code that you need to write and maintain – the best code is no code at all.

To illustrate, imagine you have a class that encapsulates some resource handle. The resource will of course be destroyed in the destructor, and we choose to disallow copying to ensure that resource isn’t double-destroyed. We want to allow moving however, because we don’t want to force clients to wrap the resource in pointer types to pass it around…

The problem is that when one disables the copy constructor, one also disables the move constructor. The default keyword allows us to re-enable it without actually maintaining it as we update the class in future:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

struct Handle {
   Handle(int h) : impl_(100000000, h) { }
   ~Handle() = default; // just for 'rule of five' completeness

   // disallow copying, it would be super inefficient 
   Handle(Handle const &) = delete;
   Handle & operator=(Handle const &) = delete;

   // ...but allow moving, it is super fast!
   Handle(Handle &&) = default;
   Handle & operator=(Handle &&) = default;

   std::vector<int> impl_ = 0;
};

I also use this to ensure my base class destructors are virtual, a simple virtual ~MyType() = default; makes my intentions clear.

Far fewer Boost dependencies

Boost is fantastic, but it’s a beast and can really slow down compile times. C++11 and onward have made it so I no longer feel it necessary to include boost when starting out with a new project – I will often add it at a much later stage.

Essential functionality that has been taken from boost that I use all the time:

• chrono for time measurement: e.g., using clock = std::chrono::steady_clock; auto now = clock::now(); auto later = now + std::chrono::seconds(10);
• smart pointer libraries
• lambda helpers std::bind and std::function
• new thread library, although std::future still needs a lot of work (to get a then() function equivalent)
• std::optional to make our interfaces more explicit when invalid data may be returned
• the <cstdint> header for precise platform-independent types (for example uint32_t instead of unsigned int)

Of note as well are the new regex, random and type index libraries, though they didn’t make the list because I don’t use them as often.

Functionality that I wish they had taken from boost, or that I would still use boost for :

• program options: it’s a bit complicated to use, but it gives very high quality functionality and catches all the corner cases I’ve ever needed
• the new log library (there are probably better ones out there, but as long as I’m using boost I might as well use this one)
• similarly, the boost unit test library is simple but effective, and you might as well use it if you’re already using boost
• filesystem, although that is coming in C++17
• asio, which has also been proposed for C++17
• the range library is a hot topic, people are still trying to figure out how to get this right but boost has had a pretty good stab at it (though sadly range::indexed doesnt play well with range-based for yet)
• I often expose basic event attributes on my classes using the signals2 library
• the string manipulation and string formatting libraries can be pretty sweet as well

I will generally end up including boost in my apps because I really like these libraries.

Hope for the future

The C++ language committee is known for being very conservative, with the explicit objective of only adding to the language features they think will still be relevant in the distant future. Created in 1983, the first standard was released in 1998, and with a relatively minor update in 2003 you could be forgiven for saying it was a relatively stagnant language.

But in the last 5 years the landscape has changed dramatically. C++11, although released years later than intended, brings massive changes to both the core language and standard libraries, and the language committee has resolved to release new standards every few years, with C++14 almost released and C++17 well underway. Today even the most knowledgable C++ consultants are feeling their way around the language ; how to most effectively use the new range-based for loops (prefer for (auto && x: xs)!) and whether perhaps movable types should be passed by value or by rvalue reference.

C++17 is probably even more exciting for me than C++11 was, because it solves a couple of C++’s greatest problems: complicated error messages and crazy compile times. Concepts will allow programmers to write template code without even knowing it is template code !. And we will all be able to create template overloads without resorting to those crazy SFINAE techniques that are so ugly I generally don’t use them at all.

But the real truly beautiful feature will be modules. Apple have been heading up a team that will allow us to import modules without causing the pre-processor to continually parse massive compilation units, which is the vast majority of what it does these days. Apple have already implemented the beginnings of this in ObjectiveC, so they have a good grip on the problems. Check out this fantastic presentation on modules for more details.

A great summary of the current state of C++17 is the notes of the last standards committee meeting . Within you will find such goodies as:

• Herb Sutter’s proposal to make return values explicit . This will make returning unique_ptr types as simple as return {new Thing}.
• a proposal for better nested namespace syntax (e.g., namespace pcx::gl { /* my declarations */ } )
• the proposal for enhanced ranged-based for syntax to prevent accidental misuse (currently the recommended syntax is actuall for (auto && x : xs), but this will allow us to use for (x : xs))

My wishlist for future enhancements include:

• better functional constructs (I found a youtube clip of some guy fantasising about piping data ranges around ).
• declarative computation expressions: python, C# and every functional language ever have great consise declarative formats for generating series of data that I would love in C++.
• new primitives to make async programming easier – (async and await are apparently on the way, boost already has a coroutines library!)
• stable C++ ABI allowing portable libraries (compilation units from different compilers or even platforms), would mean header-only types can be used in library interfaces/boundaries (e.g., currently cant have boost::any<> in an exported header because it would turn into different code on client and library.) This is already proposed by Herb Sutter here

Generally when using C++ in an IDE it can be a hassle to create a small test application for, say, verifying a new language feature works the way you think it does, or creating a test bed to create a self-contained but complicated algorithm. In such cases, when I am using an OS that supports make, I generally do this:

1
2
3
4
5

vim blah.cpp
# write your small app
make blah
# make magically runs 'c++ tmp.cpp -o tmp'
./blah

… and that’s it. It turns out make, when no makefile is present, will try a bunch of stuff that includes searching for .c and .cpp candidate files for generating your target. If the target (in this case ‘blah’) ended instead in .o it would sensibly generate an object file without linking it into an executable!

There is no easy way to make it automatically detect dependencies and include them, so all your source has to be within that one file. But there are some further tricks you can do…

Compilation options

By default on my OSX at the moment, make will call my CLang compiler:

1
2
3

echo "int main() {}" > tmp.cpp
make tmp
# c++ tmp.cpp -o tmp

But without any special flags, CLang will compile without C++14 support, which I really want!

An easy workaround to this is to set your CXXFLAGS environment variable that contains the flags you always want to be passed to your C++ compiler by default. In my machine I have added to my ~/.bash_profile file: CXXFLAGS='-std=c++1y -stdlib=libc++'. Now when I run this command I get:

1
2

make tmp
# c++ -std=c++1y -stdlib=libc++    tmp.cpp   -o tmp

Thats pretty cool. Of course you can set any of make’s implicit variables to ensure your app is built with these flags by default. For example, the compiler can be changed to GCC by setting CXX=gcc.

You can also include default include paths and libraries to link against, so that your small apps are able to incorporate boost or even your own library that you are developing.

Note 2: I am using a beta of XCode, and it has caused me some trouble (a mysterious service it starts keeps crashing, filling my HDD up with core files.) I would recommend waiting for the non-beta if I were you.

Apple recently announced the support of a new language targeted at the same application programming space as Objective C. It’s called Swift and it seems to me a very good summary of the features all modern imperative languages are striving for.

The last decade or so has seen a strong resurgence in functional programing evangelism. Languages like F#, Scala, Clojure and even Erlang for a while re-introduced to mainstream programmers high-level concepts that imperative programmers were largely unfamiliar with. A short experiment with a language supporting algebraic data types, type inference, higher order functions, closures, or the standard foundational map, reduce and fold functions will convince any programmer that their language would be far better off being more declarative.

For a comprehensive guide to the Swift language see the Swift tour.

I have wanted two write another iOS app for a while now, and so I’m thinking Swift may be the way forward for me there. To that end I’ve spent all this morning going through docs and messing with XCode to get a feel for the various idioms and coding styles it encourages…

Syntactic niceties

Swift is a very much streamlined language, and for low friction it seems to take a lot from F#. Like F#, a programmer can seemingly almost approach swift as a scripting language – the first line in your source file can be functioning application code, no boilerplate required! And the ‘playground’ concept is very familiar to anyone who has used Scala Workspaces or F# interactive mode.

The clarity of syntax is quite impressive – type inference introduces var and let common to many modern languages, and bracket-less control flow operations and optional semicolons make your code look a lot cleaner (and a bit like golang).

Structure types may be initialised in-line at the point of instantiation: val vga = VideoMode(width: 800, height: 600). Once you see this you think of course, why would it be otherwise?

Syntactically there is a lot of shorthand available for interacting with fundamental data types:

1
2
3
4
5
6
7
8
9
10
11

// create an Array[Int]
var xs = [1, 2, 3]

// create a Dictionary<String,Double>
var menu = ["Coffee": 3.5, "Bacon": 5.1]

// create a tuple of two strings
var location = ("Tokyo", "TYO")

// shorthand for iterating over Sequences
for x in xs { println("x is \(x)") }

And anyone who loves Scala’s string interpolation operators will appreciate the ability to write println("hi, my age is \(me.age - 5)").

As a special treat, Swift also supports Objective-C style named parameters. This can make some functions arguments more clear when they have the same type:

1
2
3
4
5
6

func replace(inString str: String, #value: String, #withValue: String) -> String {
  // ... 
}

// then later call it:
val simplified = replace(inString: url, value: "http://", withValue: "");

OK perhaps that is not a great example, but I think the concept has a lot of merit.

Functional concepts

In addition to type inference and closures, Swift has obviously been checking out the Scala and F# and the like for ideas, much to its credit.

First, fret not because higher-order operations are all available to you, and included in the standard library are standard set of foundational functions you’d expect in a functional language such that it is possible to write var ys = map([1,2,3], {i in i * 2}).

But one thing that seems quite interesting to me is the extended syntax available to enumerations (known as ‘associated types’) that make them almost seem like algebraic data types…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

enum Shape {
    case Circle(Double)
    case Ellipse(Double, Double)
    case Square(Double)
}

func area(s : Shape) -> Double {
    switch (s) {
    case .Circle(let radius): return 3.14159 * radius * radius
    case .Ellipse(let min, let maj): return 3.14159 * min * maj
    case .Square(let width): return width * width
    }
}

area(Shape.Circle(10))

…plus, if you add a new value (say, Rectangle) to the enumeration the area() function will fail to compile, as the compiler will complain that the switch must be exhaustive. Take that scala!

Tuples can be pattern matched using placeholders, bound parameters and where clauses, which is a fairly awesome thing:

1
2
3
4
5
6

switch (bounds) {
   case (0, 0): println("zero bounds!")
   case (0, _): println("x == 0")
   case (_, 0): println("y == 0")
   case let (x, y) where x < 0 || y < 0: println("invalid bounds!")
   case let (x, y) : println("bounds are [\(x),\(y)]")

There is no true currying though of course it can be simulated by having functions return other functions – garbage collection + closures means that you can create generators along the lines of:

1
2
3
4
5
6
7
8
9
10
11
12

func makeGenerator(increment: Int) -> () -> Int {
    var x = 0
    return {
        x += increment
        return x
    }
}

var gen = makeGenerator(10)
for var n = 0; n < 100; n = gen() {
    println(n) // prints 0, 10, 20, 30...
}

On a side note, Scala’s currying leaves a lot to be desired, as does it’s support of ADTs – one must explicitly make structures a case class before you get functionality approaching an ADT.

Optional types are also supported in the library but also with nice syntactic sugar. The ? operator defines an optional type (similar to C#) and also allows operations on that type to be optionally unwound. The ! operator forces unwinding, and causes an error if the optional type is not set.

Also, there is some fancy syntax for switching on an optional type:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

struct Job {
    var  title: String
}
struct Person {
    var name: String
    var job: Job?
}

// create a person with no job!
var paul = Person(name: "Paul")

if let title = paul.job?.title {
    println("you are a \(title)!")
}
else { // fallthrough because there was a nil optional
    println("you have no title!")
}

Note: this doesn’t currently compile – the current XCode 6 beta does not compile the samples provided by the documentation. I’ll leave this here though because it still captures the intent of the optionals feature

Notice how the if`` resolves the expression as false because the?“` operator did not resolve.

I haven’t even touched on a few other cool features like @lazy annotation, generics, variadic parameters, or the myriad ways closures can be specified (it turns out {$0} is a valid closure, with inferred argument and return value!)

OO niceties

I’ll describe some features based on where I find them most familiar from:

• C# – struct and class types. Classes are reference-counted (see below) while structs have value semantics (are destroyed automatically.)
• C# – extensions and computed properties remind me of C# extension methods
• Objective-C – Automatic Reference Counting (ARC) provides a kind of semi-manual garbage collection. Essentially whenever you set a reference type to nil it will be collected. (The language also supports weak references.) This system is similar to using shared_ptrs in C++ in that you can end up with circular references, but unlike C++ there don’t seem to be any automatic scoping facilities that relinquish resources as they move out of scope. I might be wrong about this.
• Objective-C – Swift supports the notion of protocols for polymorphic behaviour
• ? – Object identity can be compared (i.e., are these references to the same object?) using the === operator.

Does it go far enough?

In many ways this is a fairly conservative language – Swift is clean and nice to use, and I think would make a good replacement for Objective-C, but most other modern languages are focusing on higher level concepts that don’t seem to be getting a showing here.

The main thing that comes to mind is the lack of language features to help out with thread synchronisation and concurrency. Other languages are focusing on lightweight thread-like structures or coroutines, asynchronous actors or asynchronous computation expressions/monad type syntax (think F# async {}.)

This is the first release of this language and I think some initial conservatism might be sensible. Typically I think compiled and C-based languages have preferred to put new functionality into libraries and only reluctantly add keywords and syntax to the existing base language. On the other hand, other languages (C# 5, F#, Haskell) have shown that without syntactic sugar (like async { }, do { }, yield and the like) it is seemingly implausible to make async-friendly code look super readable and imperative, avoiding what is often known as callback hell.

So here’s hoping this project keeps the steam it’s started off with.

Do we need another language?

Swift is certainly more approachable than Objective-C, which I very much appreciate. Apple have always been quite good at providing an environment where different languages interoperate seamlessly, so there really seems no downside – if you have a lot invested in Objective-C you can still leverage all your previous work with Swift, or presumably use other peoples swift libraries in your own Objective-C applications.

There will always be curmudgeons of course, but they should be ignored. The lengths that some will go to to justify not having to learn new concepts is always amazing to me, especially when doing so is the best way to progress in our industry!

Apple takes the development of programming languages quite seriously. They are heading up some of the more interesting additions to new versions of C++, most anticipated (by me) being the ‘modules’ concept that promise to bring C++ compile times and binary interfaces in line with more modern high-level languages. They play this role of innovator well here because the concepts outlined in their proposal are drawn directly from practical experience in implementing said features in the Objective C language itself.

OK I could have spent a bit longer on the screenshot – I haven’t made any models yet other than cubes, and I’m not using any textures, and I should have adjusted the angle and colour of the directional light to make it look like evening or morning or something, to show off some of the immediate benefits of going to 3D.

I did spend some time making the camera zoom in from a map-like view to a chase-cam view:

In general however I’m hoping to ramp-down on the OpenGL stuff and go back to working on the core functionality. The last week was actually pretty productive:

Also I’ve been spending a fair amount of time in PicoPico Cafe when it’s open, and I’m guessing I’ll be spending more time there in the coming weeks as a bunch of construction is scheduled outside my house during business hours when nobody is supposed to be home.

World Building

The 3D functionality in my game so far is provided by a thin layer that invokes the exact same service layer (game, player, mobile and prop unit services) used by the 2D client. I took the time to finally make some extensive refactorings that I’ve been planning for some time:

Infinte Terrain!

The terrain now runs effectively infinitely, in that it can cache any combination of arbitrary regions. The complicating factor was the fact that I want the regions to be stored in a sensible way that provides for really fast lookups many times per second as entities roam around the countryside, even outside of the player’s view. More work needs to be done on this to unload cached regions that are no longer relevant.

Infinte Entities!

The entity service, responsible for facilitating rapid interactions with many geographically-local entities, can now scale out exponentially more efficiently than before. Entity ‘moment’ information is stored contiguously in memory for super cache friendly iteration. Unfortunately this encourages the programmer to pre-allocate large portions of memory to allow the number of entities to fluctuate without large re-allocations.

Because of this obsession with data locality, every region was previously allocating enough space for all entities in the game to coexist at once so I could trivially say auto moment = entities_[entityId].moment; (or something kinda like that.) Now I changed it so there is a single ledger shared outside the specific regions with lookup instructions for each entity indicating that entity’s region and index within that region. This means that the regions can be much smaller, reducing the region-to-memory relationship from exponential to linear, which is HUGE. (Of course, the old scheme was never meant to stay in there.)

I now have 1,000,000 entities pre-allocated without straining memory or computational resources at all (about 100MB memory for the whole app) whereas before I was settling for about 10,000 lest I run into gigabytes for a game with a relatively small number of regions.

Lots more stuff of course

I also made an interesting change to the core ‘entity moment’ structure so it includes a ‘facing direction’ as well as the existing velocity vector that indicates which direction and at what speed the entity is moving. I was having trouble determining the direction an entity should face when it is not moving (the velocity is 0,0 so has no implicit direction.) This wasnt a problem when I was rendering all entities as circles.

Back to OpenGL 2 again

The more I learn about the troubles people have with OpenGL the more concerned I became about getting my app to work on Windows. Through a fine bit of serendipity I met the always helpful Greggman at PicoPico, who was one of the devs who implemented WebGL in Google Chrome. He gave me some great advice that lined up with a few things I’d found on the internet and convinced me to move to OpenGL ES 2.0.

As I mentioned last week OpenGL support in Windows is lacking due to MS pushing their own DirectX 3D stack. But fortunately Google have written a library called ANGLE that is a ‘conformant implementation of the OpenGL ES 2.0 specification that is hardware‐accelerated via Direct3D.’ This means that if you write conformant OpenGL ES 2.0 code you get DirectX compliance for free (at least that is the idea.)

Another advantage of OpenGL ES (other than the widespread support, including on mobile devices) is that it is much more stringently standardised. Apparently standard OpenGL does not come with conformance tests of any kind, so vendors don’t have a mechanical way of verifying that they have implemented conformant drivers. ES does have such tests however so anecdotally provides a much cleaner integration experience.

Of course I’m effectively going back to OpenGL 2 syntax and functionality which is a bit of a drag, but I wasn’t really using geometry shaders or complex alternative rendering pipelines anyway.

Object Picking with the mouse

If someone clicks on a pixel on the screen (in pixel coordinates), how do you discover which object they were clicking on? This is deceptively difficult! The old way of doing it involved using a special part of OpenGL called selection buffers that allows you to assign a name to each entity being rendered, and query a pixel for the name of the entity rendered therein. That is deprecated however.

The modern analog of this is a manual process called colour picking, which involves rendering identifying values instead of colours to a special buffer that is not rendered. This image can be queried via glReadPixels(), the returned result is the identifying value of the object at that pixel. I chose not to go down this route though.

Instead, I chose to do it entirely on the CPU by performing the rendering calculations in reverse, in a process often known as raycasting. The rendering process involves taking each entity in your scene and multiply its coordinates by a model matrix, then a view matrix and then a projection matrix, transforming it into world space, then into camera space, and then into screen space. To figure out what object is at a pixel, I perform these operations in reverse by passing those pixel coordinates to the inverted perspective matrix and then to an inverted view matrix. This gives you the location of a point in space corresponding to that point on the screen. If you draw a line from the location of the camera through that point, you have a ray into 3D space that is every point behind that pixel! The object picked is the object intersecting with that ray that is closest to the camera (I’m just iterating through every object near the camera for now.)

For more information on this have a look at this article on raycasting. I like this because it is purely algorithmic and doesn’t require special shader code or anything.

Qt Quick and OpenGL

I continue to be happy with Qt – they are so active, they’re always releasing interesting new tech. It is hard to catch them for feedback but it can be done and when they are on IRC they are very helpful.

Unfortunately the OpenGL support in Qt Quick is still in a great state of flux, so finding the correct way to use OpenGL ES was quite tricky. Turns out however that simply not specifying an OpenGL version, and using the default function pointers their utility library provides is the proper way of using OpenGL ES in a portable fashion, even when your platform does not provide it (it falls back on the ‘desktop’ 2.0 functions.)

Up Next

My representation of the world in the core code is still effectively 2D in that all entities have an x and a y but no altitude component. For rendering purposes that is extracted from the terrain service by the rendering engine for visual effect only. But if I am to allow jumping and have some notion of visual occlusion I will soon have to add a z component to the velocity and the position of each entity. This will also mean that the entity service will need to be dependent on the terrain service.

I also want to implement a proper day/night cycle and some fancy controls in the GUI, like a slider that allows you to choose the time of day. This will hopefully provide a large ambiance improvement at little cost.

As far as blogging goes, last week I was intending my next post to be about my adventures in OpenGL and to provide a clear roadmap for others who want to follow the same path I took, but it is such a huge topic, and I am still not certain I have all the facts right, that I have put it off so far. We’ll see how that goes…

Over the last many weeks I have been ploughing through a whole lot of new stuff I’ve never used before. As mentioned in my last post I decided to up the graphics a bit, but specifically I wanted to figure out a system for a extensible UI for menus and other 2D overlays, and 3D or pseudo-3D graphics. Creating a decent UI controls library I have learned is very difficult (if kind of fun to be honest.) Making something that is flexible enough to automatically layout your controls in a sensible way where everything resizes based on the content contained within is a very difficult problem that nobody should have to re-solve in this day and age. So I wanted to re-use one that I also wanted to learn for myself.

In order to add these to my existing framework I took on the (it turns out) monumental task of learning OpenGL and integrating it with Qt/QtQuick/QML.

So far things are looking OK, but I have found the learning curve greater than I’d originally anticipated – OpenGL in particular is a rabbit warren of deprecation and messy global state idioms. That said, I currently have:

• the UI menu/control system is entirely QML based and very simple to extend and use
• the game terrain is constructed using PolyVox because I wanted to avoid having to figure out mesh generation along with all this other stuff
• the OpenGL shaders incorporate basic lighting and not much else

The main value I’ve gained is a fairly decent understanding of what it takes to create modern OpenGL applications (though how useful that knowledge is in this day and age I am not sure.) I have not tried porting any of this across to Windows yet (I’ve written it all in OSX) but hopefully the fact that I’m using entirely cross-platform technologies will help a little there – though Windows is known to have very dodgy OpenGL support so I suspect that will be the cause of most of my porting troubles.

The Qt Stack

I’ve always been interested in Qt – I don’t know of any more highly polished user interface libraries for C++ out there, and they’ve been producing really interesting technologies out that seem like they were created by people who actually understand C++. As a developer who opted to buy in to the Microsoft WPF UI framework, I find the QtQuick and QML libraries to be thoroughly refreshing and intuitive.

QML is a clean and simple markup language for writing user interfaces in a declarative fashion. The most apparent advantages over WPF for me were that the syntax is not XML based and that the property bindings may be declared in javascript, within which any properties are automatically dynamically bound so that property updates are detected and cascade automatically through the entire scene graph. In addition to that, the C++ to QML binding mechanism entirely leverages the Qt metadata system that they’ve tooled out and honed over the last more-than-a-decade, so everything just seems to work!

QML basics

Here’s a simple QML example:

1
2
3
4
5
6
7
8
9
10
11
12

import QtQuick 1.0

Rectangle {
   width: 200
   height: 200
   color: "blue"

   Image {
      source: "pics/logo.png"
      anchors.centerIn: parent
   }
}

C++ QML components are essentially just regular C++ classes that use the Qt metadata system to expose properties, signals and slots – there really is no special QML magic required. These types are exposed to the QML engine through a single C++ commmand qmlRegisterType<MyCoolControl>("com.seshbot", 1, 0, "CoolControl");. This can then be consumed from within your QML by first import com.seshbot 1.0 and then declaring your CoolControl { } just like the Rectangle in the above example. All properties declared in the C++ class are immediately available from within QML – any changes made from the QML file will automatically call your setters, and any updates from within your C++ class will automatically propogate out to the QML file. MAGIC!

QML with OpenGL

As of Qt Quick 2.0, QML internally uses OpenGL to do all its own rendering so rendering your own OpenGL should theoretically not be too difficult. In fact, check out this awesome demo of a guy messing with an OpenGL shader in QML in real time. In the end however it took a few weeks to iron out, largely because this technology is pretty new and still has some kinks, and is not well documented yet (at least the stuff I wanted to do.)

There are three ways I know of putting your OpenGL content into a QML scene:

• create a custom Qt control that does all the OpenGL stuff internally and include that control in your QtQuickView
• extend QtQuickView and do the OpenGL stuff in its constructor
• rendering your OpenGL to a frame buffer and having Qt inject that into its own layout. This is what Ogre integration does, but I haven’t explored this

There’s not much difference between the two approaches – I went with the second because creating a control that is invoked from QML raises questions of how you inject your game state into the view. I wanted to just pass my game data into the constructor.

The Qt libraries come with an example called ‘Scene Graph – OpenGL under QML’ that I found very helpful.

I did encounter a few problems:

• the QtQuick Controls library (which provides native-looking controls you can use in your QML files) don’t seem to work with OpenGL versions older than OpenGL 4. After consulting the Qt guys on their IRC channel (#qt-quick on freenode) I filed a bug, so hopefully it will be addressed in future versions.
• my specialised QtQuickView class (that renders my game in the background under the QML stuff) didn’t want to render any of my immediate mode OpenGL code – this is probably OK because immediate mode has been deprecated since version 1. (more on OpenGL versions and immediate mode and such in the future!)
• all of the demos use older versions of OpenGL (probably to minimise compatability issues on Windows) so I had a bunch of surprises when I tried modernising it (basically had to learn each version of OpenGL as I progressed)

The Qt quick guys are on the #qt-quick IRC channel around 9pm japan time by the looks, so that’s generally the best time to get live help if you need it.

OpenGL

My god, OpenGL is a mess. Each version of OpenGL (there are 4) seemed to deprecate the old way of doing things and introduce entirely new idioms:

• OpenGL 1 was all about ‘immediate mode’ because there were no shaders yet. You just tell OpenGL (in your C++ code) where the primitives and lights are and it takes care of all the rendering details
• OpenGL 2 introduced the GLSL shader language for writing ‘vertex’ and ‘fragment’ shaders. This was a huge step forward in performance because you pipe all your vertex data into the graphics card in one go, but it meant that you have to do all the lighting and model/view/perspective transformations yourself in the shader. This makes it a lot harder to pick up for newbies.
• OpenGL 3 totally messed with the GLSL syntax, and added the notion of vertex buffer objects (VBOs) which I found out are mandatory to use although nothing will warn you if you do not use them. Things just wont show up. Also there is a new type of shader – the ‘geometry’ shader.
• OpenGL 4 introduced the ‘tessellation’ shader. I have no idea what that does yet as I have not started down the OpenGL 4 road.

In addition to this, Windows only natively supports OpenGL 1, because they follow their whole DirectX thing. You can ask your users to upgrade their video drivers, or you can use an OpenGL –> DirectX translation layer to get around this problem (Qt apparently offers optional compatability via Googles ANGLE library.)

Plus, any platform may support any number of ‘extensions’ which provide capabilities on top of the ‘core’ functionality offered by that OpenGL version. A good application will check the availability of all extensions they are using, which seems like a massive hassle to me at this point. Theres a library called the GL Extension Wrangler (GLEW) thats supposed to help with this, and Qt has its own set of helpers to ensure that youre only able to invoke functionality thats actually provided by your chosen GL version.

Oh, there are also the ‘embedded’ versions of OpenGL – OpenGL ES. These are apparently much smaller and well supported so I think I will migrate towards using some OpenGL ES version in the near future – probably OpenGL ES 2.0, which is supposed to be compatible with OpenGL 4.1 I believe.

In general I’d say stay away from writing your own graphics drivers at this level – use higher level stuff that abstracts your OpenGL vs DirectX decisions from you. I went with OpenGL because I was suffering the delusion that it would make my experience with my QML layer simpler, but looking at the incompatabilities and weird differences between platforms I can see a lot of trouble in my future if I continue down this route.

I plan to write a more thorough map of the path I took through this so that hopefully others do not have to make the same mistakes I did.

PolyVox voxel mesh generation

I didn’t want to also have to figure out how to generate meshes for my game at this point, so I decided to go with a library that allows the easy generation of voxel meshes.

PolyVox is actively being developed by a couple of pretty smart guys. A lot of it has the feel of a university thesis project, but it seems to work quite well, which is the most important thing. Most helpfully for me, they seem to be writing their examples using Qt in Windows and Linux, so I can learn from their mistakes with OpenGL on Windows (something I’ll have to do soon.)

I plan to try generating some models in Blender and use something like AssImp to import them into my game soon.

General application design

I really want to put my stuff on github but I’m finding myself a bit recalcitrant on that front, because its still got so much half-baked experimental stuff in it. I will push myself to do it soon however because I’d like to link to parts of the code when writing these blog posts.

It was somewhat satisfying to realise that all of the changes and work I’ve done in the last couple of months has had no effect on the core modules I established for the 2D version of my game. All the terrain and entity management, along with the core module message passing mechanisms have remained the same.

I spent some time discovering an intuitive way to describe my 3D scene for rendering in OpenGL (i.e., for encapsulating all the OpenGL buffers, shader programs and shader program attribute bindings.) Of course this has been done many times before but OpenGLs ‘stateless’ approach (or whatever they call having to bind your objects to global state) makes this a challenge.

The fundamental types in my scene description are:

• camera encapsulates the perspective and view matrices (mapping world-space coordinates to pixels in the view). This has a render() method which tells the scene to render itself using this camera’s view data
• scene contains all the entities and light data that may be rendered into the view, as well as the active shader program. The scene invokes each entitys render() method
• entity encapsulates a model that is to be rendered as well as the model matrix which maps the mesh from local ‘model coordinates’ into the world coordinates, oriented the correct way and all that jazz
• model encapsulates all the buffers and VBOs required to render a mesh

My system is also pretty dynamic – changes to the shader program files on disk immediately cause the application to re-compile and start using the new shader in the application, which helps speed things up on occasion.

This is just a catch-up on my experiences over the last few weeks, a few discoveries and surprises, and perhaps my plans for the immediate future. I decided at the last moment to include a screenshot here, but I’m sure we’ve all seen brown circles on green backgrounds before…

I also created a (low framerate) animated gif of this in action.

Making a game/engine

The general advice people give new game developers is to never make a game engine – focus on just getting your game concept out. I will largely be ignoring this advice because I don’t have a specific idea for a game yet, just a general notion that it will be client/server and a kind of town-builder. Based on this alone I believe that careful work now will be necessary to ensure the scale of the world I have in mind will be possible – the virtual world will almost certainly need geo-spatial partitioning to ensure location-based entity lookups and collision detections can be performed in decent time, and because only a small portion of the virtual world will likely be viewed, and likely only viewed in a separate client application altogether, there is no reason to have the core game logic mixed in with rendering logic at all.

Modularity and the basic framework

I intend to write a separate article on this, but first a quick rundown on my PCX library. I actually spent a lot of time trying to bring some of the nicer IOC container abstractions I’ve grown used to in .Net and Java to my C++ environment. Breaking an application up into abstract services is a great way to ensure minimal coupling and well designed boundaries around modules of code. This usually involves a lot of reflection in newer languages. My solution in C++ involves run-time type identification (RTTI) which is generally considered anathema in C++, but it can facilitate the creation of libraries that deal in terms of interdependent types, and have nothing to do with the functionality of those types per se.

I decided on these core high-level abstractions:

• services are the core contracts that different sections of code use to communicate with each other. If you want to work with the weather, get yourself a hold of the weather service
• commands are messages sent into the application as a whole from outside – services can advertise which commands they can respond to, and the client application can bind keys or whatever to these commands. This abstraction is probably more focused on games
• modules provide concrete implementations of a bunch of specifically configured services and expose commands. The application mainline only interacts with modules – it starts them up and shuts them down, and the modules provide all the functionality of the application
• message bus provides singleton channels for application-wide cross-cutting concerns. I have not yet found a particular use for this, but intend to use it for sending ‘hints’ out that have no true affect on the state of the application, such as dump debug information now.

The central idea is that different abstract concepts such as geography, creature behaviour, economy, weather, client UI etc are all provided by separate modules. When started up, a module can publish services they provide and consume services provided by other modules via a ‘service locator’. It is very important that the ‘service locator’ is only used by the high-level module code directly to ensure they’re not used to hide globals and introduce crazy interdependencies. The module creation mechanism provides a fluid dependency syntax that ensure each module is initialised after the modules on which it depends (i.e., publishes services which this module consumes.)

I created a core library (I named pcx after my own initials and the letter ‘x’ which is super cool) that I intend to be useful as a general-purpose C++ library for anyone wanting to add these concepts to their own application.

Deciding on core abstractions

I’ve been thinking about making a game for a long long time now, and have had a myriad of thoughts on how I would create all the major abstractions, modularise the code, and manage multiple clients, network latency, sharding, etc. But when I actually sat down and put hands to keyboard, the first problems I ran into were hugely and unexpectedly daunting – how should position and rotation be stored? And time? Should position be a vector of floating point numbers or integers? And should velocity be another vector, or polar coordinates (rotation and magnitude). Should rotation be implicit from velocity, or should entities be able to face one direction but move in another?

These are all decisions that will affect the application in almost every way, and doubtless create deep-seeded performance and functionality trade-offs, and as this is my first game I wasn’t really sure what those might be. For example, if I choose to represent velocity as a vector (x, y components), then I lose the ability to determine the direction a stationary unit is facing ([0,0] gives no information in that aspect). Polar coordinates do not suffer this problem however. But the calculation for moving an entity with cartesian vector velocities is so trivial! Just newPos = pos + velocity * time… It’s very tempting to go with that!

And if I store latitude/longitude of an entity as floating point numbers, I expect I might run into rounding problems with entities far from the origin point. Or when comparing entities close to the origin with those far from the origin. But floating point numbers allow me to say ‘all distances are in meters’ which makes thinking about and configuring the application that much easier for me.

In the end I kind of arbitrarily chose to store locations and velocities as vectors of doubles, and will probably store a ‘facing direction’ as a float in radians. Real-time time is likewise a double, indicating fractions of a second. I have not yet implemented any concept of in-game time however.

Discovering engine capabilities

I quickly found it very important to keep a close eye on the performance impact of all my decisions as well. It was quite exciting to get my original simple framework up (a ‘world’ module that holds all the entities and their locations/momentums in the game) and determine the maximum number of visible entities it could support. I found it started dropping frames at around 40,000 moving entities in the world, but I quickly realised however that I have no idea what a good number is – how many entities should it be able to support?

Most engines I’ve looked at (e.g., Quake and Source engines) suport the low 1000’s of entities, but most of those are client-only frameworks. I couldn’t find a lot of info on MMOs (not that I’m making an MMO but I would like to get a feel for scale), and could only find indirect references to EVE online supporting up to 30K entities in some of their major battles, but they apparently do all sorts of crazy stuff to support that such as slowing down time and moving entities not directly involved out onto other shards.

In the end it’s all moot however, as my game is still very trivially implemented and is not a real-world example of how it will eventually work. For one, all moving entities in the world just walk in an anti-clockwise circle and don’t look at the world around them (this will add a lot of complexity to say the least!). Secondly, the game currently updates every entity in the game 60 times per second. I should definitely make entities further from the player ‘stupider’ and less frequently updated, and there is actually no good reason to update all entities 60 times per second anyway – that number was chosen because that is the framerate of the GUI and I have currently tightly bound the world update logic to the core game loop. I will be decoupling these soon.

I have found it’s very interesting to keep a good feel for the performance of the application as I work on its foundation – every time I make a significant modification I run it with varying conditions and check how it performs relative to previous iterations. This has led to some interesting discoveries regarding performance of iterators and iterator adapters, and some very puzzling edge-cases where the Clang optimiser seems to suddenly start borking. But more on that some other time.

The ‘modules’ abstraction is really helpful in monitoring performance – the core game loop just iterates over each module, effectively saying for each module m, m.update(timeSinceLastUpdate). I put a basic metrics counter around this tight loop and get some pretty useful output that shows how many milliseconds each module consumes per tick:

1
2
3
4
5
6
7

Job time accumulations in 1000ms:
 -               client - 60 ticks, avg: 0ms max: 0 total: 0ms (0%)
 -                 mobs - 60 ticks, avg: 0ms max: 3 total: 9ms (27%)
 -                props - 60 ticks, avg: 0ms max: 0 total: 0ms (0%)
 -                world - 60 ticks, avg: 0ms max: 0 total: 23ms (72%)
 -      render entities - 58 ticks, avg: 5ms max: 8 total: 339ms
 -   update all modules - 58 ticks, avg: 0ms max: 3 total: 33ms

From this output it is obvious that the ‘render entities’ step is taking a long time – I should really investigate this!

C++ development experiences

Regarding the choice of C++ as a language, it is sometimes a boon and often times a bane. The absolute major pain I’m trying to avoid is massive compile and link times. These can only be mitigated through careful control of modularity and inter-dependencies. This is something one should struggle to achieve in any case, but it is constantly undermined by the use of templates and libraries that use templates.

And the Eigen C++ matrix library seemed like a good choice, but it comes with a harrying legacy – it prefers to use special high-performance instruction sets available on some machines that require your objects to be defined in a certain way (with special alignment specifications when memory is allocated.) These are known as fixed-sized vectorisable types and can cause segmentation faults if used incorrectly. Fixed-size vectorisable types cannot be passed by-value to functions or methods, and all classes that contain such types must themselves specially override the new operator to ensure these alignment requirements are maintained. And STL classes that contain these types must take this into account, so Eigen provides its own implementation of the STL vector that you must use. PLUS all of these restrictions apply to types that you create that have eigen members, and I think also to classes that aggregate THOSE types! It is a huge pain in the ass if you like creating abstract interfaces, to say the least.

I suspect that Eigen will cause all sorts of problems when I move to Windows, so I want to try that out sooner rather than later. The special vectorisation can be disable at compile time but I’d rather see if it causes problems first.

Qt Creator and CMake

I was originally going to go with XCode for development on OSX – I’d really love to learn how to use that well as it seems quite different to most other editors and not intuitive for me. Ultimately however I decided against it because it doesn’t work well with CMake (I think I would have to constantly be re-loading the project) and, at the time anyway, I was thinking that I really wanted to work with QT Quick and other Qt technologies.

So I decided to go with Qt Creator as a development IDE. It is certainly a huge pleasure to use, and has more than the usual amount of high-level functionality one would expect in a C++ development environment. As a bonus it has fairly decent integration with CMake – the only missing aspect here is that it doesn’t allow you to easily add files to your CMake project, but I have made a few tools that allow me to do this easly from the command prompt (more below.)

The main problem I’ve had so far is that in order to use the latest C++11 functionality I went with Clang over GCC as a compiler. While Qt Creator supports this, it still seems to try to use the GDB and GProf etc for debugging and profiling, which don’t work with Clang. I am going to spend some time soon figuring out how to fix this, but it seems to involve creating a new ‘kit’ that defines which dev tools the IDE should invoke. It seems complicated however…

OSX Development

I really enjoy working on OSX – it has all the goodness of a good linux development environment along with some really smooth apps.

One of the worst aspects of Windows development is the extremely weak command line environment. The history of the command line shell (MS-DOS prompt) still seems mired in its QDOS (Quick and Dirty Operating System) origins from the very early ‘80s. While it supports basic pipes and has a few commands like find and… erm… anyway, while it has some limited functionality available, it is not a scratch on the highly evolved GNU/Linux environment that has been continually improved over the last 30 years or so. If you want a tool that does anything moderately complex in Windows you need to find one on the internet generally, whereas in Linux there is no limit to what can be accomplished with sed, grep, find, cut, awk, tr and the like.

For instance, one real annoying aspect of C++ development for me has always been the relative difficulty of creating new projects. Java IDEs can easily provide the ability to create new projects and packages through a simple right-click in your project tree, because Java is very opinionated about where such files go. C++ just requires the symbols to exist at link time, so they could come from anywhere, and there are limitless conventions about how to manage header files in your filesystem.

I have my own conventions for managing my hierarchy of source and header files, and decided to create template projects and modules (my own abstraction for this project) and create shell scripts that allow me to set up entirely new projects with a simple x.new-module thing Thing, which will create all the necessary headers, source files and CMake files, with default sensible names and namespaces, and include them into my current project. This would have been a nightmare to put together in Windows but has been trivial in OSX.

Next steps

I recently added the all-important geo-spatial partitioning in a very simple way, but this seemed to cause some significant performance penalties. I have decided to take the plunge and figure out how to get the profiler working properly with Qt Creator to help me investigate this, because working on a large project without a profiler is like driving a car with a map but no windows – it’s hard to tell if you’re still on the road.

I really want to get some graphics in there but I have no experience with that, so am considering messing around with shaders to see if I can get a good lighting model in there first. This should really help me figure out the environmental aesthetic I’m going for.

At some stage I’ll need to figure out how I’m going to make the game overlays such as menus, dialogs, text boxes etc. Previously I’ve used SFGUI (works well with SFML which is the C++ GUI library I’m using) but I would like to see if I can get QT Quick and QML working with SFML. I don’t want to spend too long on this however because I intend to move the GUI code to perhaps another language (C# and Unity) so effort spent on the GUI might be ultimately wasted.

Over the last few weeks I’ve had a growing realisation that the foundation of web programming is still immature, and I am doubting the value in investing too much time learning the high-level technologies. I am not really one for learning frameworks in general actually – I much prefer learning languages and idioms – and modern web programming is all about rapidly changing high-level frameworks.

That said however, I feel that I’m finally at a point where I can start making useful stuff in Ember and Rails without feeling like I’m misusing the tools or spending most of my time in Google. So last week I knocked off a few high-level features in my app to show the basic scaffolding I was considering (it only took a few hours in the end!), and then set it aside.

There is a very duct-tape and chicken-wire feel to web technologies, but once you’re familiar with the tech you can pump stuff out pretty quickly. Because of the immediate and ethereal nature of the web it can be a fantastic way of creating a product that is immediately globally available. All of the magic we see however is still largely magic however, and magic doesn’t bode well in any application. The web as a platform for applications is still unbaked and young, and I feel that unless you’re forging new territory on the frontier you’re probably working with technologies that won’t be interesting in a few years time.

The Web as a Software Platform

HTTP, HTML, JavaScript and CSS have been around for a while now, so why have all the useful standards for building proper web applications (like WebGL, WebSockets, local storage, drag-and-drop and all those other HTML5 goodies) only started coming along recently?

It turns out that for a long time web standards were committee-driven by a group of beard-stroking high-falutin non-visionaries called W3C. I still recall fairly recent times when the latest advances in the web were all about creating HTML that was also standards-conforming XML for some reason (so that perhaps machines could deal with it more easily or something?) and very little practical advancement was being made. (Side note: the same thing seems to be happening with OAuth, which is a morass of unproven ideas and conflicting ideals.)

At some stage however another working group arose called WHATWG, formed of people that were actually interested in pushing practical new technologies onto the web, and they pretty much ignored the W3C’s direction.

The WHATWG formed in 2004 in response to the stagnating web standards, and in 2007 the W3C finally got on board and standardised HTML5 based on a whole bunch of the WHATWG’s tools. They pretty much totally abandoned their whole XHTML thing, which I don’t think anyone really regrets.

All of a sudden there have been bursts of innovation on the web, but without a fully baked platform on which to create them. So all these high-level frameworks have temporarily filled the gaps while the HTML spec catches up. In fact, Google’s Angular framework (an alternative to Ember.js) has the explicit goal of becoming obsolete when Google manages to get their tools into the standard – it’s a kind of proof-of-concept of Google’s vision for client-side application development.

I chose Ember because if you’re going with a framework, you might as well go with one that provides abstractions that make sense to you. But I don’t have high hopes for it’s long-term availability as the web matures, and so feel that there is limited long-term value in becoming some kind of Ember guru.

My Web App

The current proof of concept is at http://seshbot.herokuapp.com. It still doesn’t have the meat in it but it has the authentication, some mobile-friendliness, and sorta models the notions of ‘games’ and ‘players’ in games.

I was much surprised to find out that there is not much of a story yet for how to provide a real-time connection between the backend and the Ember application, where updates on the server are actively pushed out to the client. This is probably the next big thing I’ll have to do – create an adapter that connects to the server (probably using server-side events and one of the Rails4 streaming APIs) and injects incoming updates into the model using the Ember Data API, similar to the EmberFire Firebase library.

Other than that, the two remaining things I can think of are: making it look like a gaming application (nice rose-wood tabletop look or something?) and adding a few components that I want to have in there like a chat client, a dice area and some kind of card game. This is the nice bit where I get to play around with things, I’m looking forward to experimenting with the interactivity side of things, perhaps dragging cards around or having some sound built into it.

I have put this aside however because I don’t want to burn out on it. I think it’s time to take a break so that I can come back with a fresh set of eyes – perhaps I’ll decide it’s not worth continuing at all in lieu of some other app.

New C++ App

I’ve been wanting to mess around with C++11 for a long time now, and have made a lot of little sample applications that allow me to get a feel for it. I really want to try creating a real application that is:

• cross platform
• uses built-in C++11 stuff like chrono, threads, lambdas, auto etc
• provides a few services I’ve come to enjoy in newer languages such as dependency containers (if feasible!)
• allows me to experiment with GL shaders, which I’ve wanted to play with for years.

So I spent a few days writing a basic app in QT Creator using CMake as the build system. There were a few hurdles but it didn’t take long to get up and running. Because I’m limiting myself to core C++, boost and a couple of cross-platform libraries (SFML for graphics and Eigen for linear algebra stuff) it’s still pretty versatile. And because I’m using CMake I’ll be able to use Visual Studio to develop in Windows and QT Creator or XCode or whatever I want in OSX. I’ll try to stick with QT Creator where possible though for consistency.

I am a bit worried about Windows compatability – Visual C++ has always lagged behind in standards conformance, but they have picked up their pace somewhat in the recent future. I am avoiding some of the more esoteric stuff however, such as variadic templates, because of VC++.

I would also really like to try messing around with QML – Qt’s DSL for writing GUI applications. It reminds me of WPF only in a much cleaner, less hacky way, with JavaScript capabilities built straight into it. Ideally I will figure out a way to use Qt Quick/QML seamlessly with the OpenGL stuff provided by SFML, though I am less optimistic about that. Previous experience tells me that you don’t want to be re-creating GUI widget libraries because layout management is a complete bitch, but I think QML is still a bit young to work in arbitrary circumstances.

Blogging

I found it very difficult to blog about my experiences with Ember and Rails. There is a lot of stuff out there covering the same stuff I would cover, only terribly out of date. This made me feel that my posts too would just become so much flotsam on a sea of irrelevant minutiae.

The main value I was really getting though was as a reference for myself so I could close some of my browser tabs without worrying that I wouldn’t be able to find that one piece of information again, and also so that I could distill my thoughts on something before putting it aside.

I have about 3 unpublished posts on my experience over the last few weeks – I’ll probably put them together under one post about Ember development, but not for a little while now I’m guessing.

I am much more certain of my opinion on C++ related matters, so I imagine that there will be a few long rants in that general direction coming up.

I have been interviewing programmers for many years and reckon the best way to find great programmers is by giving them some control over the interview topic, and then going deep into a few questions instead of broad across many topics. This takes a lot of guts however – it requires the interviewer to pay attention, and ideally (though not necessarily) to have a fairly broad knowledge base themselves.

I believe this advice applies to all programmers – of course interviewing is rarely in your job description, but it is definitely in your best interest to make sure interviews get done well at your company. Unfortunately most companies will allow anyone to interview and won’t have a good way to tell that they’re not doing it well, ultimately damaging the work environment.

The mediocre way

Typically interviewers will be given a list of questions to ask and some criteria by which to judge the answers to these questions. Perhaps the interview will follow some format of scripted grilling, perhaps a practical section, and some kind of open two-way forum. Following a script is supposed to allow the candidates to be compared fairly on a level playing field. The practical section might consist of taking apart a printed code sample or even writing some code, and the forum provides the candidate the opportunity to explain their situation and determine if they actually want to work at the company themselves.

This has a lot of problems however:

• if the interviewer completely controls the questions the candidate may come across poorly because they don’t happen to have experience in the specific fields chosen, or because he or she is just very nervous
• it promotes a one-size-fits-all mentality, which will lead to a homogenous work environment
• it is too easy for the interviewer to just phone it in without truly probing for deeper knowledge. In fact this becomes more likely as the interviewer becomes bored of the questions
• it is too easy for candidates to blag – some people can sound like experts when all they have is brash confidence and a few keywords. Plus, recruitment companies often coach candidates on what questions might be asked so those keywords are likely to be there
• quiz-type interviews often fail to test higher-level proficiencies, such as communicating architecture and design information

I think it’s well worth throwing away the ‘standardised’ approach to testing technical capabilities. There is too much risk of false negatives and false positives along this approach – a poor programmer may have been well coached, and a good programmer might have an unfortunate gap right where your questions probe (surely I could have worded that better…)

The Seshbot way

While it is important to cover several bases in an interview, the most important question I always ask is ‘what was the most recent interesting project in which you were heavily involved?’ I almost always spend most of the interview going deep into a few questions that branch off the answers to this question.

This question puts the ball firmly in the candidate’s court, and largely eliminates the problems outlined above. If a programmer can’t talk throughly about a topic about which they chose themselves and are purportedly very interested, they probably aren’t right for the job (at whatever company I’m working for anyway!)

Once the candidate has explained the project, the interviewer can then challenge the details of that project as a way of testing the candidate’s knowledge of that system and the reasoning behind its design. The types of question would vary depending on the workplace, but at my last job for example I probably would have asked:

• architecture: please outline for me (ideally on a whiteboard or paper) how the whole system hangs together. I might expect the candidate to talk about the systems involved, data flows, security considerations, or data storage and integrity for example.
• design quality attributes and compromises: how does this system provide, or how would you adjust this architecture to provide, various quality attributes (high availability, reliability, scalability, performance, security)? What compromises would these changes entail?
• design: if I were a new developer working on this team, how would you describe the design of this system to me?
• specifics: I also spend a lot of time asking ‘what is the purpose of that service/component/class’

Pros: This addresses all of the problems I outlined with the more traditional approach:

• the candidate is talking about something they are presumably proud of and know inside-out. If they can’t talk happily on this subject they won’t be able to talk about any subject
• the candidate is more able to show you what their particular skill set entails, and what they believe is their forte without them awkwardly spelling it out (through stupid ‘what are your strengths and weaknesses’ questions)
• the interviewer must be engaged in the process in order to ask relevant questions. It is in fact a great way to keep the interviewing process more interesting – and even educational – for the interviewer
• because it is a ‘deep’ and detailed question, it is very difficult to blag. Someone might be able to re-draw arcitectural diagrams they had to become familiar with in the past, but they would still need to know why the system was configured that way to answer the questions
• the test focuses on communication of ideas, which I believe is the most important skill for a team member to have. You may or may not agree with this, but you certainly want to have tested it

Cons: There are some caveats however:

• do not let the candidate run the interview. It can be too easy to tackle a question by diverting into another topic – make sure that the candidate answers the questions you ask to your satisfaction
• keep an eye on the time, because although you want to go deep on few questions, there’s no point going deeper into a topic once the candidate has demonstrated their knowledge in that area
• it can be difficult to recall what you discussed later when you’re trying to make a decision about the candidate. Take notes constantly, and summarise the interview in an email directly after you finish it
• if the candidate chooses to talk about technologies with which you’re not very familiar yourself you’ll be forced to ask largely high-level questions. This is not terrible as I believe you can still figure out if they know their stuff, but you might end up having to take their word on a few things

How to measure success

Other than retention rates I am not certain of how to measure if your technique is successful, but in my experience most prospective programmers in the job market are not very good (something like 1-in-10), and so if you’re hiring a high percentage of applicants you’re probably letting in a few duds.

This might seem depressing and I feel bad about saying that, but this is my blog and I want to put my honest opinion up here. Take it as you will. Others agree with me however.

Because of this it is a very good idea to have a basic pre-screening done before the proper interview. It should be very simple and not take too long – a simple test should be sufficient to weed out most of the poor programmers, and you need to remain respectful of the candidate’s time as they are interviewing you as well.

What about live coding?

Here’s an anecdote: once while applying for a job at a large investment bank I was given an almost purely practical interview. On arriving I sat down with the lead developer and chatted for a bit before heading into the programming room to do some pair programming. Sweet right?

Anyway I sat at this Windows box with Visual Studio on it (this was for a largely .Net job) and was given the basic fizzbuzz test. There is a lot of controversy around this interview technique but I actually enjoy practical questions so didn’t have a problem with the idea. The interview was a shambles however, and although I did well I count it as a terrible interview that did not serve its purpose at all.

First I had trouble with their development environment. The machines at this bank were ridiculously slow – they were running a special (presumably super-secure) build of Windows 95 that was by now literally something like 13 years old, and they couldn’t change because it would be too costly to get a special build of a more modern Windows. So we sat there for a long time waiting to get all the software up and running, and every button click seemed to require the human genome to be re-calculated.

The next problem was that making sure that the interviewer and I were on the same page took way too long. I did the fizz-buzz program, and decided to show him how I would do it declaratively (with LINQ) so we could talk about the benefits of declarative programming. Of course if I were interviewing someone I would want them to solve the problem as simply as possible first, then make it more complicated later. I know through experience that many candidates think that they are expected to say things like I would never start programming without a firm set of requirements! or some other approach showing that they know about all areas of software development.

Turns out this guy wanted me to demonstrate some test-driven development, and so was expecting me to have started by writing tests. So OK, I figured I’d download SpecFlow because I had used it successfully recently and really liked it. But no, this is a bank I’m sitting in so we can’t just download stuff – things have to go through a days-long process of scanning and justification before new software is installed. So I ask what they use and he mentioned some package or other. So I had to read the docs on that, and we had trouble actually running it on this machine in the end because we had to configure some directories in Visual Studio or something, and much more time was wasted.

I’m not saying it can’t work, but in my opinion live coding is fraught with dangers. A much better alternative is to browse the applicant’s source code online for projects they have worked on. Realistically though the number of people I have interviewed that had online code I could evaluate was exactly 1 (I did hire him though!)

General interviewing advice

Obviously interviewing is a difficult thing to do well. You have a small amount of time to decide whether to commit your company to filling a permanent seat on your team, which is a huge deal. Probably practice is the only thing that helps mitigate this (and the Seshbot technique of course) but here’s a few other pointers that come to mind:

• take notes constantly!
  One of the problems you can encounter with a less scripted interview is that when summarising how the interview went, it can be difficult to recount all the things you talked about. I tend to fill a couple of pages in my notebook with bullet-pointed scribbles during each interview
• know when you know
  The best interview I ever gave was a really nice guy called Phil. Only a few minutes into the interview I realised that he had probably handled my questions better than I could have. So I just sat back and told him ‘I don’t think we really need to go any further’, then I walked out and asked HR to give him an offer on the spot. I was always happy that I did that.
• do basic screening
  If no screening has been performed it is worthwhile asking a couple of basic language-specific technical questions to make sure you’re not wasting your time
• the interviewer doesn’t need to know the answer to all the questions he or she asks
  You can choose to pretend that you really know and are just testing their knowledge, but if I don’t know something I usually don’t mind asking questions in an outright manner – there’s no need to maintain a facade of superiority and being honest helps promote a candid atmosphere
• have a standard approach to summarising the interview
  At the end of the day you need to provide some quantifiable metric by which to decide who to hire. Plus HR and the recruiter usually require some specific information. At my last place HR was happy with just the name, date, my decision/recommendation, and justification for that decision
• if you’re doing a phone interview (unfortunate!) follow a script for the scaffolding for the interview
  This keeps you from spending too much time on the plesantries and keeps you from waffling on
• I usually like to ask if there’s any good books a person would recommend, and ask what they got from it
  It may be curmudgeonly of me but I don’t think a person can learn fundamentals very well from Stack Overflow alone
• Work with your recruiter, but assume they are coaching the candidates
  A cool side-effect of this techinique is that it doesn’t matter if candidates are coached – I told our recruitment agencies to feel free sharing information about our interviews with candidates

I do not want to implement authentication and authorization myself. It is tricky to get right and tends to cause huge damage when it goes wrong in production.

So I have spent at least three full days looking at various solutions I can build into my simple Ember/Rails application and spent a lot of time experimenting.

This post describes my current understanding of authentication for web applications, and the approach I used to implement a basic authentication system I put up on heroku at http://seshbot.herokuapp.com

If you want to see the source code, have a look at https://github.com/seshbot/new-ember-rails-app

NOTE: this is very text-heavy because after three full days I decided not to spend too long on this blog post. Therefore there are no images at this time. I may update it later to have some nice UML or screenshots, but that time is not now.

Learning the basic concepts

I found a few very detailed introductions to client-side authentication with ember which helped me through all stages of implementation of my system. I highly recommending going through the following resources and comparing the different approaches’ overlaps and differences. I also got a lot of value out of re-visiting them after I finished implementing my own solution, because it made me think about some of the trade offs I had made.

Watch these awesome client-side suthentication videos

http://www.embercasts.com/ covers the client-side concepts of authentication with Ember in part 1 and part 2 of their ‘Client Side Authentication’ videos. Specifically:

• client token authentication concepts
• sending auth request to the server and saving the token (in a ‘login’ controller)
• setting up controllers
• catching ‘unauthorised’ error responses and redirecting to login pages
• keeping a sane workflow so the login transitions the user back to their original page
• storing the auth token in local storage so page refresh doesn’t reset it (note: I used cookies instead of local storage)
• preventing the unauthorized server request if client knows it doesn’t yet have a token

This doesn’t cover the server side, or anything to do with Rails or any other authenticating server specifically – he used a home-grown demonstration Node.js server for the demonstration. Also doesn’t specifically cover authorization (I can see users but can’t see their emails for example.) The ember front-end polish in there is all nice though, and I found it very helpful to revisit these videos after I had a basic system in place, in order to add nice error messages and improving the ‘view page/redirect to login/return to page’ workflow.

Read about SimpLabs’ experience making Ember.SimpleAuth

SimpLabs wrote a blog post detailing their experiences getting ember authentication to work sensibly and according to the various standards.

They wrapped this functionality up in an ember plugin called Ember.SimpleAuth (and wrote about how to use it). There’s even a demo rails app that uses it.

Follow the very detailed ember-auth + devise tutorial

Someone else has written a rails plugin called ember-auth that presumably takes care of both sides (rails server and ember client) of the problem. The true value for learning is in the demo application’s tutorial however, which covers:

• setting up your rails app
• setting up devise for rails
• modeling the server entities and API endpoints
• writing tests for all of the above
• setting up your ember app
• creating front-end UIs for authentication with ember

It also has a separate page that goes into security concerns that highlights a few best practices to keep in mind that frameworks will probably not implement for you:

• always use https
• authentication checks in the client are a convenience only and should never replace auth validation in the server
• do not use the ‘current user’ ID when retrieving priveleged resources (i.e., don’t use client-provided data when performing authorization related functionality)
• never store any credential information in cookies – generally just store the server token, which is expendable
• do not rely on the client framework alone to clear caches etc when logging out – ember data for example doesn’t offer a way to clear the data store

A few other side-notes while we’re talking theoretical

ember-beercan seems to explore a different approach that I don’t really like, but does have some interesting information on using rails and devise on the server side that I might look at later.

A general concern to keep in mind is that for security reasons if the client-side application is not running on the same url/port as the server application the browser might refuse to let them communicate. In this case apparently you should add Rack::Cors to your app (haven’t looked into that yet.)

There is also a lot of discussion around whether the client side should be involved at all in the auth negotiation, and perhaps leaving that up to a separate set of pages served by the server, and the server refuse access to the app at all until that time. This makes the client app much simpler as it can always assume that the user is authenticated (see stack overflow questions how to access store from app object, session cookie based auth with rails and devise.)

When looking into server-side authentication information I found this description of a simple hand-rolled solution to be quite helpful, because it is quite short and covers only the rails side.

What we want from an auth system

A minimal authentication system should provide:

• create user: an interface for creating users
• login user: an interface for authenticating a user based on username or email address and password
• error handling: the interface should provide nice handling for errors (if there’s an error message it should be printed nicely)
• allow session to persist for some amount of time so the user doesn’t have to log in every time they come back

In addition however, we want the system to provide authrisation:

• separation of user roles (administrators, regular users, guests/unauthenticated users)
• authorisation of access to server resources – the server should send a 401 unauthorized response to unauthorised requests
• sensible UI workflow for logging in and unauthorised access attempts
  • when a server responds with a 401 response, the UI should take the user to the login screen
  • after login, the user should be returned to a sensible page, possibly based on what they were trying to achieve before being redirected to the login page

Of course the system has to follow industry practices and where possible use well-established technologies to offload all the dangerous stuff like dealing with passwords and hashing.

Building an Authenticating app

I spent a lot of time experimenting with the various options, generally with little success. The executive summary is that most high-level plugins are generally not production ready, or don’t work well together with the latest versions of other parts of the architecture. I ended up following a great tutorial on how to hand-roll your own authentication framework in Ember and Rails, using only a single bcrypt Rails gem for the password stuff.

Failed attempt 1: ember-auth-easy Rails gem

I was quite hopeful when I found ember-auth-easy which was made to work with ember-auth-rails to provide a full Rails backend/Ember frontend token based authentication solution.

Unfortunately as with so many things in Rails these days, lots of stuff doesn’t work with lots of other stuff if you’re trying to use the latest versions of things. The devise rails integration was found to be lacking for some reason and there was some mass change involved that broke backwards compatability, and many slightly older gems don’t seem to work well anymore. I think it was made to work with Rails 3 as well (I’m on Rails 4.)

In addition, there’s a whole lot of gems up there and I’m starting to get pissed off at having to learn 5 new buzzword-riddled technologies for every one new one I learn.

Before I decided to abandon it I created the following steps (I write it here in case I decide to go back to it later)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

vim Gemfile
# add the following: # gem 'ember_auth_rails', :git => git://github.com/seshbot/ember_auth_rails.git
# gem 'ember-data-source', '>= 1.0.0.beta.3', '< 2.0' # ember-data not yet out of beta
# gem 'emblem-rails', '~> 0.1' # easier to write templates
# 
# gem 'ember-auth-rails', '~> 5.0' # client-side authentication
# gem 'ember-auth-request-jquery-rails', '~> 1.0' # auth requests via jQuery.ajax
# gem 'ember-auth-response-json-rails', '~> 1.0' # responses in json
# gem 'ember-auth-strategy-token-rails', '~> 1.0' # token authentication
# gem 'ember-auth-session-cookie-rails', '~> 1.0' # use cookies
# gem 'ember-auth-module-ember_data-rails', '~> 1.0' # ember-data integration
#
# gem 'devise'

vim config/application.rb
# add "require 'devise'" to bottom

bundle install # install new gems
bundle exec rake ember_auth_rails_engine:install:migrations
rails g devise:install
bundle exec rake db:migrate

So I hand-rolled my solution

I eventually found a great post called authentication with ember.js by a dude who seems to really know what he’s talking about. It seems to be a culmination of several weeks of work, and a collaboration with a few other developers. It also includes a link to Rails::API, which I really want to use in the future.

The Rails server in the tutorial provides an API that allows creation of a new user, authenticates a user/password combination, and provides admin information to authenticated users. The rails implementation code consists of:

• router exposes a user resource (for creation and reading) and a session creation post route
• user model is composed of multiple api-keys – when the model is loaded, it will create a new api-key if there are no remaining active session keys
  • the user model also invokes the has_secure_password security method that provides an authenticate method (this is built into the Rails framework and uses the bcrypt gem)
• api-key model is composed of an access token and an exipiry time
• all controllers have access to an ensure_authenticated_user function that searches for an active API session key that is associated with the current HTTP_AUTHORIZATION HTTP header
• the user controller allows an unauthenticated client to show or create a new user record, but requires an authenticated session to show all users
• the session controller (invoked via HTTP post from the session creation route) provides login functionality (session creation)
  • first it looks up a user associated with the given username or email
  • it then invokes the user object’s authenticate method with the given password
  • if either of these steps fail a HTTP 401 response is returned, otherwise a 201 response with the user’s session API key

In the implementation provided in this system, the notion of a session is not actually stored anywhere in the server – it is merely an access point to a secure token associated with an api-key the user has (a new api-key is created if the session creation request is valid but no current active session key is available.)

An interesting thing I noticed while re-reading the SimpLabs blog post I mentioned previously is that this scheme does not allow a user to delete their access token from the server at all. Logging out just means clearing the token cookie – if the user re-authenticates the server will just dish them out the same token. If I extended the logout action to clear the token from the server however, all of the user’s sessions would become invalidated, so I’d have to change the scheme to create new access tokens for every separate login. I’ll leave it as is for now and have a think about it.

As with all other ember things, the instructions were written with a prior version of ember and so don’t work anymore. I had a bit of fun getting it working but a couple of things to keep in mind:

• use latest version of bcrypt
• use ‘jquery-cookie-rails’ gem
• demo uses the Rails::API gem instead of creating a whole Rails application with views etc. Because I previously used the ember-rails gem I didn’t do this
• retrieving data from the store is done differently now – see the ember docs
• accessing the store from anything other than a router can be difficult. I get it with this hackery: var store = GameTableServer.__container__.lookup('store:main') (see http://stackoverflow.com/questions/19401087/ember-js-how-to-get-access-to-store-from-app-object)
  • TRICK! another problem – store returns an async promise, so you need to wait for that! god dammit. var self = this; store.get(...).then(function(user) { self.set('apiKey', ...)})
• if something doesn’t seem to be working, keep an eye on your browser’s javascript console, net traffic and your rails logs (in heroku you can do this with heroku logs or something)

You can have a look at the app as it currently stands (as of Jan 2014) on seshbot.herokuapp.com. If you’re reading this much after Jan 2014 however it probably wont be there any longer.

Alternative: Use ‘devise’ gem directly

Devise seems like a very mature and comprehensive rails ‘authentication solution’ that seems to handle a lot of authentication related problems out of the box in a very configurable way. It takes care of a lot of stuff like sending password reset emails, locking accounts after failed validations, connecting to various auth providers, and lots of other stuff. I will probably end up moving towards it if I ever make an app that warrants that kind of thoroughness.

I found a pretty useful comment on stack overflow that details how to get it running quickly with Rails 4 – not sure if thats more useful than the docs.

I started following this very detailed tutorial on using rails + ember + devise and found it very useful. Again, I couldn’t get things working well together and had to abandon it. If I were to revisit I might also consider following these very detailed instructions on devise + ember.

Alternative: Use SimpleAuth for client-side stuff

SimpLabs’ SimpleAuth (discussed in this SimpLabs blog and mentioned previously in this post) looks pretty cool, and is recently very active. It is still v0.1.0 so I’d prefer to keep away from it for now, but if I wanted OAuth integration (to have a ‘login with Facebook’ or whatever) I might look into using this for the client-side code.

My current conclusion

It is laughable that Ember and Rails are in such states of flux that it was easier to hand-roll a solution (although based on a very detailed set of instructions!) than it was to use existing gems and plugins. I hope that changes in the future.

If I ever decide I want a more complex auth solution using rails and ember, I’d probably look at using devise for the Rails side and SimpleAuth for the ember side. I would expect a lot of heart-ache along the way though.

Heroku is an ‘application platform’ in the cloud, meaning that you can push certain kinds of apps (written in Ruby, Python, Java and Node.js) and it will ensure all the correct infrastructure is in place. When you sign up you get to host one app for free so it’s easy to try out.

Later I will probably move to Amazon Web Services, which provides a basic virtual machine in the cloud that you can do anything with. This will allow me to host multiple applications without having to worry about paying money. Heroku does offer some pretty nice scaling, monitoring and deployment tools though (the admin panel literally has a slider to allow you to spin up new application instances.)

This post shows how I went through all steps, including setting up the PostgreSQL database on OSX, creating a skeleton Rails app, and deploying to Heroku. It is a culmination of having gone through several sources:

• much was taken from this useful step-by-step ‘Rails + Ember blog post’ and this follow up post that incorporates changes for newer versions of the frameworks.
• when I got to the part involving installing the ‘ember-rails’ gem, I found that the ember-rails documentation was pretty useful.
• some of the Heroku stuff came from the Heroku Code School lesson summary.

Choosing a database

By default Rails will use sqlite3 for its database, and this isn’t by default available in Heroku. As I’m going to have to do some configuration anyway, I might as well choose a nicer database.

I was deciding between MongoDb and PostgreSQL. MongoDb offers flexibility when it comes to managing file assets in your database, while PostgreSQL is much more well established in existing hosting infrastructures (AWS and Heroku), so can make initial deployment much simpler. Mongo is also more amenable to schema changes because it’s a NoSQL schema-less document database, but I think Rails is supposed to make schema changes easy anyway with the various db: commands.

As Heroku comes with PostgreSQL support out of the box, for now I’ll go with Postgres. I’m as yet not very familiar with Heroku and want to make things easier on myself.

The following installation instructions came from a blog entry on installing PostgreSQL on OSX with HomeBrew:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# easiest if you have homebrew installed
brew install postgresql

# ensure it starts up when your machine starts
ln -sfv /usr/local/opt/postgresql/*.plist ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

# ensure you don't accidentally run the older version
echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bash_profile && . ~/.bash_profile

# create a database user for the application to use
# (alternatively you should be able to run 'createuser -d myapp')
psql postgres `whoami`
create role myapp with CREATEDB login password 'password1';

Notes:

• the createuser command can replace the psql command stuff: createuser -d myapp
• if the DB username is different to the application name (below) you’ll need to change the rails configuration later so it knows which username to use
• I assume Heroku doesn’t require you to manage the database at all

Creating a simple Rails app

Creating a Rails app is really simple once you know the commands. So from scratch, if you include all the learning involved behind each command, it’s actually not very simple. But these steps make it simple for me.

TIPS: I read somewhere that you should always run bundle exec before running a rails command to ensure that you’re only working with gems in your Gemfile. Technically you could run all the commands below without prepending bundle exec however.

1
2
3
4
5
6
7

rails new myapp --database=postgresql
cd myapp
vim config/database.yml # set the database username and password, and on OSX un-comment the 'local' setting
bundle exec rake db:create    # create databases
bundle exec rails generate scaffold Thing name:string # generate model/views/controllers
bundle exec rake db:migrate   # update database with model data
bundle exec rails s           # start rails server localhost:3000

Note: I had to uncomment the ‘local’ setting from my database.yml file because rails couldn’t connect due to permission problems on the local socket file. I could have reconfigured postgres instead but meh.

OSX users can also use POW! or Anvil (which uses POW! under the covers) to set up a fake URL pointing to their local rails app directories, so in my case I can visit http://myapp.dev and it will actually show me the app running on my local machine. It makes the testing cycle a lot quicker.

Add some simple static content:

1
2
3
4

rails generate controller StaticPages home about --no-test-framework

# set root '/' route to point to static home page
vim config/routes.rb # add "root 'static_pages#home'" beneath other routes

Now you should be able to visit localhost:3000 and see a generic ‘home’ page message.

Check in to git

This creates a local git repository, but during the heroku deployment step I’ll push it over there too. I’ll also push it to GitHub when it looks like more of an app. So in git parlance, this is what I’ll have on my local machine:

1
2
3
4

rake tmp:clear
git init .
git add -f *
git commit -a -m"Initial commit"

I regularly run those git commands to make it easier to revert any mistakes I happen to make.

Adding ember framework

I have tried two alternative approaches to creating a new rails app for ember.

Alternative 1: use the ember ‘edge template’

I think this one is probably the best as it was demonstrated by Yehuda Katz (main Ember guy) in this live demonstration video. I ran a diff on projects created with and without and it seems to:

• adds some ember gems to the Gemfile: active_model_serializers, ember-rails and ember-source
• remove the rails ‘application view layout’ (app/views/layouts/application.html.erb)
• create an ember ‘application template’ (app/assets/javascripts/templates/application.handlebars)
• creates a ‘view asset’ that generates an index.html with the ember application.js in it (app/views/assets/index.html.erb)
• sets up a rails route pointing to the assets controller ‘index’ action (config/routes.rb)
• create empty assets controller and helper files (not sure why)
• create a rails ActiveModel ‘application serializer’ (app/serializers/application_serializer.rb) that does a few things ember requires

Installing using the edge template is simple. Just replace the rails new step above with the following:

1
2
3
4

rails new myapp --database=postgresql -m http://emberjs.com/edge_template.rb
cd myapp

# edit your database config and Gemfile as before...

Note: I had problems using the remote edge template, so downloaded it and used my local copy instad.

Alternative 2: add ember to an existing rails app

You could also just add the ember-rails gem directly to your Gemfile, then run rails generate ember:bootstrap and you get a basic Ember framework in your app/assets directory. I also prefer to use javascript directly (as opposed to CoffeeScript, which is the default), so add -g --javascript-engine js

1
2

vim Gemfile
# add 'gem "ember-rails", github: "emberjs/ember-rails"'

Following this approach I believe you’ll have to manually set up the Ember ActiveModel Serializer which was written by the Ember guys, and ensures your Ember app understands the format of your Rails app’s JSON data. The first alternative does this for you.

Common to both approaches

After you have created and updated your Gemfile, you still need to bootstrap the ember environment, and then ensure Ember is running in ‘development’ mode when Rails is.

Note: you can Set ‘developer mode’ (which enables developer-centric error messages and is apparently quite useful) by updating your config/environments/development.rb with: config.ember.variant = :development. By default running locally will run in dev mode, and running on Heroku will run production mode however.

1
2
3
4
5

bundle install
bundle exec rails g ember:bootstrap -g --javascript-engine js
bundle exec rails g ember:install --head

vim config/environments/development.rb # add config.ember.variant = :development

Deploying to Heroku

Heroku requires a few rails settings to be modified to work properly:

1
2
3
4
5

vim config/environments/production.rb # heroku runs in prod mode by default
# change 'config.serve_static_assets' to true

vim Gemfile
# add "gem 'rails_12factor'"

I have already gone through the Heroku sign up process and installed the toolbelt appropriate for OSX (the toolbelt provides the heroku command line tool), so I won’t outline that here.

Installing my rails application on Heroku was then a simple matter of:

1
2
3
4
5
6
7
8
9

heroku login
heroku create --stack cedar
git push heroku master

# whenever you make database changes
heroku run rake db:migrate

# if you want to push your local database contents to heroku
heroku db:push # requires the 'taps' gem ('gem install taps')

This creates an image with a particular configuration of applications and adds a heroku git remote to the git configuration.

Now you can visit the heroku app online (in my case at http://seshbot.herokuapp.com/).

TODO: use gem rails_12factor? This alters the rails app a little to make it 12 factor, which is a set of guidelines for how one should build an application to make it easier to administer and deploy. Not really important right now though.

Troubleshooting and administering Heroku

1
2
3

heroku ps    # list running apps
heroku logs  # show application logs
heroku run console # run interactive ruby console

1
2
3
4

heroku config  # configure remote app through environment variables
heroku apps    # overview of apps
heroku destroy # deallocate remote server
heroku run rake db:migrate

heroku config sets environment variables for things you don’t want to commit to git (e.g., passwords). Configure your Rails apps to use ENV['MY_VAR'] instead of your super secret key, then run heroku config:add MY_VAR=blahblah.

There are also various heroku pg: commands for updating the application database. The application itself doesn’t have full admin access to the database so you can’t for example write heroku run rake db:drop. Instead you should run heroku pg:reset if you want to clear the database.

I dedicated this morning to learning some Ruby and Ruby on Rails (RoR). For my purposes, RoR provides the server-side API to a web application, like this:

To my delight, I quickly discovered that Ember (which I have been messing around with quite a bit) is modelled directly on Rails – not just in the generic they-are-both-MVC-architectures-way, but down to their usages being identical in many respects. I think many new webby techs follow this same style (Meteor seems to, for example.)

This post outlines the core concepts I have picked up from the various tutorials. I also included a RoR cheat-sheet I created while doing the Rails tutorial.

To get started on Windows/Mac, I’m guessing the easiest way is by downloading the RailsInstaller.

Learning Ruby

For an absolute beginner, Try Ruby takes about 30 minutes, and will show the very basics:

• basic syntax
• standard data structures (strings, arrays, hashes)
• defining methods
• defining classes (basics on attributes and initialize method)

It stays very high-level, but obviously that’s the intention. It avoids going into language features such as reflection, lambdas, string manipulation (mystring = "var is #{my-var}"), and doesn’t talk about administration etc.

See the Ruby core documentation for reference material.

Learning Rails

First, some language references: Rails API docs or API Dock or the other seachable Rails API docs can be downloaded and used locally.

I chose to follow the Rails for Zombies tutorial, as it is often quoted as being helpful as a fully interactive online tutorial. It takes a few hours, but does seem to cover all the fundamentals, namely:

• Rails conventions
  • syntax for creation, read, update and delete of entities in the database
  • naming conventions for database table, view, and controller lookup
• Models
  • model class structure
  • invoking CRUD operations on the models
  • how relationships between entities are expressed, and how they map to the database structure
• Views
  • syntax (<% %> and <%= %>)
  • lookup from URL (searches app/assets folder before trying to run rails routes)
  • helpers (link_to, edit_thing_path etc)
• Controllers
  • controller class structure
  • rendering alternative views
  • rendering alternative formats (json, xml)
  • session variables (used for basic auth checks)
  • factoring out and configuring common code performed on all actions
• Routes
  • defining RESTful resources (automatically direct requests to controllers/views)
  • defining custom routes
  • creating helpers for link_to when creating custom routes

The main thing it doesn’t cover is the administration (installation, deployment) and command-line usage (e.g., automatic generation of controllers and models.) This isn’t a big deal however, as the standard getting started guide does this very well.

I think there are a few bugs in the programme however:

• the tutorial videos are a bit out of date (for pre-3.0 versions of RoR) but the practical exams use post-3.0 RoR it seems
• the last prac exam requires different syntax than that in the tutorial:
  • redirect controller#action case is different (tut vids say Zombies#undead prac requires zombies#undead)
  • redirect in prac requires prefix ‘/’ (‘/zombies => ’/undead’). Tutorial vids did not.

Rails Cheat Sheet

I created this while going through the Zombies tutorial. There’s probably better cheat sheets out there, but I highly recommend creating your own as a learning experience.

RoR’s Ruby API syntax

• Entity creation syntax (note, Rails will generate an ID for you):
  • t = Thing.new; t.status = "something"; t.save
  • t = Thing.new(:status => "something"); t.save
  • Thing.create(:status => "something")
• Entity query syntax:
  • Thing.find(1) (by ID)
  • many alternate query methods: first, last, all, count, order(:status), limit(n), where(:status => "good")
  • performance note: queries are performed on DB
  • syntax note: may also chain methods
• Entity update syntax:
  • t = Thing.find(id); t.status = "bad"; t.save
  • ...; t.attributes = { :status => "bad"; ... }; save
  • ...; t.update_attributes(:status => "bad"; ...} (no save)
• Entity deletion syntax:
  • t = Thing.find(id); t.destroy
  • Thing.destroy_all
• on save failure, try t.errors to investigate what went wrong

Models

Default model definition goes in app/models/thing.rb

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class Thing < ActiveRecord::Base
   # validation
   #
   validates_presence_of :status # mandatory fields
   # many other validations: e.g., uniqueness, format, conf/acceptance, etc

   # alternative validation syntax:
   validates :status, :presence => true #, :length => { :minimum => 3 }

   # relationships (reflected in DB)
   #
   belongs_to :person
   # the Person will have 'has_many :things' (note plural)
end

Views

• thing default view definition goes in app/views/things/index.html.erb and app/views/things/show.html.erb):
  • alternatives actions to show can be added as myaction.html.erb
• evaluate code with <% ruby code %>, eval and print with <%= ruby code %>
• shared application stuff (header/footer) goes in app/views/layouts/application.html.erb (use <%= yield %> for body placeholder)
  • <%= stylesheet_link_tag :all %> renders stylesheet links for all files in app/assets/stylesheets/
  • <%= javascript_include_tag :defaults %> renders script tags for all files in app/public/javascripts/
  • `<%= csrf_meta_tag %> adds some stuff to prevent cross-site-meta-request-forgery hacking (people injecting their own HTML into comments etc)
  • <%= link_to thing.name, thing_path(thing) %> (first param is link text, second URL). Can use the entity itself instead of thing_path(thing)

Sample index.html.erb (create a link to this with things_path):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<ul>
<!-- @things set up in controller -->
<%= link_to "Home", root_path %>
<% if @things.empty? %>
   No things yet
<% else %>
   <% @things.each do |thing| %>
      <li>
         <%= link_to thing.status, thing %>
         <%= link_to "Edit", edit_thing_path(thing) %>
         <%= link_to "Delete", thing, :method => :delete %>
      </li>
   <% end %>
<% end %>
<%= link_to "+", new_thing_path %>
</ul>

Controllers

• thing controller definition goes in app/controllers/things_controller.rb_

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

class ThingsController < ApplicationController
   # common code, called by all actions
   before_filter :get_thing, :only => [:edit, :update, :destroy]
   before_filter :check_auth, :only => [:edit, :update, :destroy]

   def get_thing # called by before_filter
      @thing = Thing.find(params[:id]) # all URL query params are available
   end

   def check_auth # called by before_filter
      # do auth verification (check 'if flash[:notice]' in rendering page)
      if session[:user_id] != @thing.user_id
         # flash[:notice] = "Not authorized!" 
         redirect_to(things_path, :notice => "Not authorized!")
      end
   end

   def show         # show single 
      # set view state before rendering view

      render :action => 'myaction' # to render different view (default 'show')

      respond_to do |format| # optional
         format.html # myaction.html.erb
         format.xml { render :xml => @thing }
         format.json { render :json => @thing }
      end
   end

   def edit; end    # show 'edit' form

   def index        # list all
      if params[:status]
         @things = Thing.where(:status => params[:status])
      else
         @things = Thing.all
      end
   end

   def new; end     # show 'new' form

   def create       # create new
      # expects params of the form { thing: {status: 'good', name: 'xxx'} }
      @thing = Thing.create(params[:thing])

      redirect_to(@thing)
   end

   def update; end  # update

   def destroy; end # delete
end

Routes

• application routes defined in app/config/routes.rb
• resources directive creates a full RESTful resource. This means that it will automatically create the following helpers and routes:
  • things_path (/things ‘index’ action)
  • thing (/thing/id ‘show’ action)
  • new_thing_path (/things/new ‘new’ action)
  • edit_thing_path(thing) (/things/[id]/edit ‘edit’ action)
  • … plus more

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

MyApp::Application.routes.draw do
   resources :things

   match 'new_thing' => "Things#new" # path => ControllerName=>actionName
   match 'all' => "Things#index", :as "all_things" # create all_things_path helper for link_to etc
   # alternative:
   match 'all' => redirect('/things')

   # TODO: case sensitive? the tutorial seems confused on this
   root :to => "Things#index" # sets up '/' route to '/things'

   match 'status_things/:status' => 'Things#index' # add :status controller params
   match ':username' => 'Things#index', :as => 'user_things'
   # in view: <%= link_to 'seshbot things', user_things_path('seshbot') %>
end

1. trying to build a simple ‘gaming table’ application in Ember.js,
2. styling with Twitter bootstrap,
3. messing with plugins in my blog (trying unsuccessfully to fix code highlighting, and adding a UML tool – see below)

I spent most of my time learning about Ember. Ember.js is a very nice looking front-end MVC framework that has a very appealing getting started guide that make it look super simple to create a reactive application. Three things that people will not tell you however:

• demo videos only ever show the main usage scenario of that framework
• most new frameworks change so often that they’re either unstable or very little up-to-date documentation exists, and
• many of the benefits they offer you probably won’t end up using anyway, for various reasons

For now though I’ll go ahead with it because I feel that I’m just about to start doing cool stuff in it (it kinda always feels like this though.)

Next week I’m thinking of switching back to some C++ stuff so I can dabble in a realm I’m more comfortable with for a while… Monday is a public holiday in Japan though so I’ll probably be wandering around and not programming much.

Problem 1: binding non-nested components was difficult

I figured I would devote my first day last week to creating the framework for a small Gaming Table application. Perhaps just start off with a quick chat client or sketching app. I was not accounting however for the vagaries of modern web application development, and I ended up messing around with stupid little problems for most of the week. Looking back I feel it was quite frustrating overall – it seems that many of these new techs do not quite work as advertised, if at all.

Most tutorials and documentation will usually only tell you about one way to make an ember app – showing the details of a single entity or collection of entities of the same type at a time. Perhaps it might be some blogging application that lets you dig down into various blog entries, or perhaps it will involve showing all the tweets from a particular tweeter. Whatever the demo, I’m sure it will show you how to explore a single concept.

The first thing I wanted to do was to show your online friends on the left side and allow you to create or enter an existing chat room. I immediately got stuck on a stupid little problem however that I stubbornly refused to get past, leading to several wasted days.

My specific problem was how can I make the nav bar show the name of the current gaming table (kind of like a chat room), but show some placeholder message if I’m not in a room. The problem being that the region dedicated to showing information about the current table (players, cards etc) is not a descendent hierarchically of the nav bar.

Long story short, the correct way seems to involve: 1) modifying the ‘Nav Bar’ controller to add a dependency to the ‘Game Table’ controller; 2) add to the Nav Bar controller an alias or dynamic property pointing to the Game Table controller (this is conceptually the last table loaded); and 3) creating another dynamic property in the Nav Bar controller that is updated whenever currentPath is updated, and returns null if the route (currentRouteName) is no longer a table.

This might make sense, but it was a pain in the ass to discover. (Side note: I’m working on a general ‘getting to know Ember.js’ post that goes into a lot more detail on this so others tackling the same problem might not have to spend as long as I spent on it.)

I’m not saying the framework is terrible, but all of the Ember help I found is out of date, and none of the code samples I found worked. Ember only reached v1.0 4 months ago (Sept 2013) so any advice from before that period is probably out of date. Code samples will not work, and jsfiddle/jsbin apps will probably not run, which is a huge problem because that is how people communicate working code samples with each other in this community.

I’m concerned that the Ember docs might not cover enough real world scenarios that ‘proper’ applications might encounter (e.g., several regions dedicated to different information.)

Live Help in IRC! 1980’s tech to the rescue

The IRC channel is pretty awesome – the #emberjs channel of freenode.org is one of the most populated channels on the server, and I’ve saved a lot of time by asking for help there.

I spent a long time digging through documentation on how to solve this problem before I turned to IRC. Then within 10 minutes I had someone giving me meaningful advice that I ended up using. The secret was that I went in there with a minimalistic example of my problem that they could mark up and fix for me. Here’s the code I gave them and here’s what they gave me.

Hosting a backend

I have been mainly concentrating on the front end functionality so far, so didn’t want to spend too long messing around with the server side. I had originally decided that I’d learn some rails, but decided to try out a ‘no backend’ solution – in this case deployd. The two criteria I was after were a simple REST API and some kind of authentication, both of which deployd ostensibly offers. There were a few hiccups though.

The first was that deployd is still actively being developed, so the web UI isn’t totally intuative. I won’t go too far into it but it has been a hassle.

The next problem is that although both Ember and Deployd declare that they speak standard REST JSON language, it turns out they don’t agree on how that language should look. I had to mess around a fair amount and ask around on IRC before discovering that you need to apply your own serializer, that intercepts all remote data transfers and allows you to ‘munge’ it a little into a format that Ember is happy with.

Again, I’ll include the details of all this in a post dedicated to Ember later.

Given these two facts, I would have to think a whole lot of myself to give advice on programming to other programmers. I happen to know however that I am in fact a better programmer than most, and am therefore uniquely qualified to offer such advice.

So here’s some of the things I feel I’ve learned the hard way – at least enough that every time I work on a project they jump to mind and guide my actions.

Which are the best technologies?

Programming languages are tricky to learn, and programmers have a vested interest in believing that the technologies they know best are the most appropriate technologies to use for every task. For the purposes of this article, those people will be known as curmudgeons.

Curmudgeons often avoid learning more than their one favourite language. I spent about 8 years programming exclusively in C++ before I finally took the jump to another language, and that point represented a refreshingly great learning curve for me. I love C++ but there’s features that it simply does not have, so I’ll demonstrate by talking about C++ from a curmudgeonly perspective.

C++ does not have reflection, and I used to (and still do) think that reflection can make code hard to understand and follow. However reflection is valuable during application bootstrapping for stringing together components at the highest level using dependency injection containers, for example.

C++ does not have garbage collection. I believe languages that use GC tend to make managing resources other than memory (locks, databases, etc) difficult, which in turn makes a lot of code difficult to deal with. However dealing with certain problems without GC can be very tricky or even impossible – typically anything where the lifetime of an entity cannot be easily identified at coding time, such as lambdas with closures, or ‘persistent’ data structures (a la clojure’s data structures), or often many other situations in multi-threaded applications.

C++’s standard libraries are incredibly low-level (you’d look long and never find the word ‘web’, ‘service’ or ‘actor’) and the standard is incredibly slow moving (only recently got threading support, lambdas or regular expressions!) However this is a side-effect of the fact that the language is intended to be long-lived, clearly something it’s been very successful at.

So while I believe the functionality of these ‘friendlier’ languages are often misused or are considered to solve problems they do not in fact solve well, I also know first-hand how awesome they can be in certain specific scenarios. I now believe that there are no crappy technologies – only situations where technologies are perhaps not applicable.

Need super high performance? C or C++ is great if you know it really well, as an explicit goal of the language is that all features should come at no hidden cost, which is often a detriment to the language’s simplicity. If you or the majority of your team is not familiar with the language however, it will probably not go well. If you are writing a large application, or need to quickly pump out a web service or componentised application, it simply might not be the right tool for the job.

It might be surprising but there are an equal number of curmudgeons using newer languages such as Java, JavaScript and Scala as well. While C++ curmudgeons will tell you that high-level facilities offered by new generation languages (GC etc) are not truly useful, higher-level language curmudgeons will tell you that the performance of their tools are equal, or somehow better than, lower-level languages. Actually, from the perspective that a well-maintained application tends to run smoother this is sometimes true. However from the truest apples-to-apples sense this is rarely the case.

As an example, an often-cited comparison is that between garbage collecting heap allocated memory and the typical semi-manual approach taken by C++. The argument comes down to the observation that scheduled mass-collection of heap memory is generally more efficient than many individual object heap de-allocations. But many programmers that rely on garbage collection would not be aware of stack-based allocation (the default in C++, unavailable in Java) which offers effectively free memory allcation and de-allocation. Or custom allocators, which are a kind of ad-hoc custom garbage collection which can also offer similar benefits in specific circumstances.

A smart programmer would believe that if a language was created, still exists and has a large user base, it probably has a good reason to be around. A programmer that understands more languages is almost by definition more well equipped to effectively tackle more varied problems.

What’s the difference between Analysis and Design?

Many programmers don’t separate the notion of analysis from design. In fact, it would be less charitable but more realistic to say that most programmers don’t fully know what analysis is for.

The first step in any project is to understand the requirements – a process that requires a very thorough analysis phase. A thorough analysis will capture all requirements in a language comfortable to the client, create a domain model that the client agrees captures all of the concepts (entities, events, roles, etc) in the system, and give a good representation of the scope that is being tackled (a complete list of actors interacting and their useage scenarios the application will satisfy.) If you tackle a problem without this knowledge, you don’t fully understand the problem and therefore are not yet qualified to fix it.

The agile principle of avoiding ‘big design up-front’ leads people to avoid performing full analysis up front, which is very misguided. Every requirement accurately captured represents a significant amount of effort saved in large refactorings, or worse yet continual effort working around poorly designed systems.

Analysis is important and should be done as completely as possible, lest the wrong application get built. Design is incremental but continual. While analysis documents tend to be fairly static and only change if the actual requirements change, design documents are often not useful much past the development of the code they relate to. For this reason they’re usually only used for reasoning about and communicating a plan of attack for an upcoming component being created or worked on.

Have we estimated enough time?

Estimation is said to be the hardest part of programming. It is fricken hard. But usually it becomes much more approachable once the complete scope has been explored – if every piece of functionality to be delivered is decomposed into the smallest deliverable increments that the client can verify (often known as user stories in agile terminology), and these dozens or sometimes hundreds of stories can be individually and honestly estimated, a rough estimate may be reached.

More importantly however, when you find yourself part-way through stories of a project, you have the ability to re-evaluate your estimate of the remaining portion based on how long the first bit took. This process should replace all these ‘double and add your grandmothers age’ type estimates, though they require some bravery both on behalf of the developers and the business people.

As a bonus, if the stories were separated into must-, should-, and might-haves, a certain amount of flexibility is built into the system where the portion to be delivered becomes negotiable based on revised estimates.

Have we completed our design?

Every time I design a new component I go through a few steps. I find that these are often not considered when estimating the time required to implement new functionality.

• most importantly, for every entity in the system consider how the entity will change over time – it’s simple to represent an order in an online shopping system, but what if it gets cancelled or amended? What if the user account is deleted? What if an item is recalled by the manufacturer?
• how will the new component be administered and configured? This means APIs and user interfaces, which are not glamorous but need to be made.
• when modeling the major entities, model all incoming commands and events as well – a good way to tell if there’s an event missing is if two entities are relating directly to each other. This also yields heaps of other benefits (see event sourcing for example).
• separate each entity from the value data associated with that entity. Entities have identity and usually a long lifetime, and are changed many times throughout their life. Values can be compared trivially, serialised and deserialised and are thread-safe by virtue of being immutable facts.

These topics are actually huge but these most readily to mind, expressed as minimalistically as I thought possible.

Is UML necessary?

This concept might be a little anachronystic these days as I don’t see many people jumping on the UML bandwagon anymore – if anything it’s swung the other way, which is no better really. But it can seem sometimes that UML is some kind of all-or-none proposition.

Many treat UML as a kind of process, when in fact it is a collection of languages. And like any language, it is there to be used primarily for communication. It makes little sense to have a process that revolves around UML per se, but I find that certain diagrams are arguably the best way to express certain ideas.

During analysis: use-case diagrams are great for outlining scope; domain models are fantastic for discovering the main concepts in a system and are great to carry to early client meetings; and state diagrams can really save a lot of time later on down the line (entity states are deceptively tricky to discover.)

During design: these are totally situational, but component diagrams show how all the services and applications hang together, where message busses are and how high-availability and how other such architectural concerns are handled; I often find myself sketching out class diagrams aplenty to provoke discussions on my immediate plans; and I email tons of sequence diagrams around indicating the intricate details on how components coordinate their interactions.

In all, UML is neither good nor bad, it is a set of tools you may decide to use when communicating about software. Objecting to them on principle is like objecting to the written language on principle.

Will Design Patterns save us?

There are a lot of good books out there detailing a lot of good design patterns. These patterns take many forms but there is a common unifying factor of all of them – they don’t actually do anything by themselves (otherwise they’d be applications or services.) They can be very useful for two purposes – describing the design of a system to others, or reason about how a part of a problem might decompose into a set of entities, values and relationships.

The problem comes in when the design patterns book comes out as the first step in creating a new application. No matter the problem, the first step should always be to understand the problem through analysis, and then the first step of design should be something like figuring out the major components in the system or the data in/out and transforms, depending on the situation. The design patterns emerge from this process, and the books are useful for recognising them, not guiding the design process.

Interestingly, design patterns are more important to imperative languages than declarative ones – imperative languages are by their nature higher level and the abstractions that design pattern books enumerate tend to fall out much more naturally without a lot of effort. Functional language curmudgeons are oft quoted as saying that design patterns are missing language features. I’m not entirely convinced of this perspective, but it does show how genuinely powerful those languages are at expressing high level concepts simply.

People now create web applications instead of individual pages. Web apps look a lot like native applications, are responsive and dynamic, and have very high-level frameworks that provide application-wide abstractions for business models and the abstraction of the view logic.

This article describes my current understanding of the technologies used in constructing modern web applications, largely based on a few years’ lurking on Hacker News and a couple weeks’ not-so-intense investigations.

The importance of JavaScript

Javascript is said to be the assembly language of the internet. It was created circa 1995 for Netscape Navigator 2.0 as part of a much grander vision for a global web platform. It is supported by all web browsers, and until recently was the only language broadly enough available to do so.

Modern web applications are built many layers of abstraction on top of this. An extreme and relevant example of this is the XMLHttpRequest (hereafter XHR) function. Prior to HTML5 WebSockets, all single-page web applications used this single function to receive dynamic updates from a remote server, through a technique commonly known as AJAX. Likely few web apps actually use the function directly however – most these days use high-level MVC frameworks (more on these below) to connect the visual elements the user sees in their browser (the view) to entity abstractions updated from a remote server (the model).

It makes sense to me that any understanding of modern web applications would need to be partly underpinned by a solid understanding of JavaScript. It seems like a pretty icky language however, with a lot of weird behaviour ready to trip those unaware of its stupid idiosyncracies. Perhaps because it was rushed out in 10 days.

Here’s a few reading recommendations I would like to read one day:

• Eloquent JavaScript – basically an ebook that starts from the basics
• Learning Advanced JavaScript – similar to above only presented as a slide deck with code samples
• Ask HN – JavaScript Dev Tools – debugging in JavaScript
• MVC Architecture for JS – building an MVC framework in JS from scratch
• Large-Scale JS Application Architecture – a guy who knows his stuff on various approaches to building ‘large’ web apps
• Mozilla Developer Network – Intro to OO JS – everything you need to know on how prototype and new provide OO on top of simple JS function
• JavaScript Garden – a kind of FAQ on all the idiosyncracies of JS (how this works, for example)
• JavaScript Patterns – a very nice looking reference on all facets of modern JS (including frameworks)
• Learning JavaScript Design Patterns – not sure if this is really useful yet, especially compared to the one directly above

JavaScript in the browser

It’s very difficult to figure out which of the myriad JS frameworks are worth investing in, as they come and go and are easily replacable. However some toolsets and frameworks have become totally indispensable timesavers to anyone making a web application.

• jQuery – a low-level toolset that vastly simplifies common JS tasks such as manipulating the DOM and using XHR
• RequireJS – a library that makes including third party modules simple
• Handlebars – a very popular template parser that uses {{this}} syntax
• Backbone.js – allows user-defined model objects to be dynamically linked up to HTML elements for automatic updates
• Ember.js – an exciting MVC framework that I think is built on top of Handlebars and Backbone, or something like it. More below
• Angular.js – a Google library that promises to deliver similar functionality as Ember.js, but with a syntax that is meant to look more like a natural extension of HTML

JavaScript on the server

For some reason JavaScript has become a very popular language for performing server-side tasks as well. I think this has something to do with the recent popularity of the Node.js JavaScript web application platform. Node was simplistic enough for people to write small but highly capable tools in a language with which they were already familiar. Regardless of the purpose, it is important to note that the fact that its use on the server side is largely unrelated to its use in the browser.

I think I’ll likely want to look into at least these frameworks:

• npm for javascript package installation
• Yeoman provides a set of tools for creating and manipulating a web app on a workflow level
• Bower for application dependency management. It automatically downloads and configures dependent frameworks for an app
• Grunt for running preconfigured tasks from a Gruntfile. For example running, testing and previewing web apps

As an example of these technologies, here’s what it takes to create a basic Ember.js application (a more in-depth starter can be found here):

1
2
3
4
5
6
7
8
9
10
11

# install pre-requisite apps to your machine
apt-get install npm
npm install -g yo grunt-cli bower
npm install -g grunt-contrib-compass
npm install -g generator-ember
npm install -g grunt-mocha

mkdir myapp && cd myapp
yo ember       # create the application framework
bower install  # download pre-requisite libraries
grunt server   # start app on localhost:8000

Serving and hosting web apps

I’ve been concentrating mostly on the browser end of the web application architecture equation. So far my thoughts on the matter of hosting haven’t really gone too far. Two obvious options come to mind however.

A Yeoman-generated Application that I think by default uses a simple web server like Unicorn, started from a Grunt script. There are plenty of instructions on the web for deploying these applications to Heroku or other hosting services.

A Rails RESTful Application hosted on something like AWS. Ruby on Rails is a hefty web framework that also follows the MVC framework. I think it’s a full-stack framework in its own right and prefers its own HTML templating engine. I intend to use it to expose a REST API instead of HTML however so I can totally separate the server logic from the UI framework, and perhaps write separate front-ends altogether.

I intend to spend the next six to twelve months attempting to see what happens when I have time to myself.

So far….

This is only the first week of my grand experiment. So far I have spent most of it gaming with my other unemployed friends (Pathfinder card game is awesome.) I did set up this blog however, and register seshbot.com, so I suppose it’s not a complete loss work-wise.

Blogging

I’m excited about following an open development process. Source code is only a part of an application however, the analysis and design are integral pieces that I would like to make visible. I am concerned that setting up this blog before I have anything to show is setting the cart before the horse, but it seemed like the smallest most approachable project I could scope out for the first week.

The Octopress platform seems very developer-friendly. I can trivially embed syntax highlighted source code snippets and extend the framework through a simple plugin mechanism (I think.) There is no fancy web UI for composing posts – its all authoring markup on your local machine then pushing the generated code to github and letting github pages take care of the rest. Writing a new blog post is a matter of:

1
2
3
4
5
6
7
8
9
10
11

> cd seshbot
> rake new_post['My New Post!']
# Creating new post: source/_posts/2013-12-20-my-new-post.markdown
> vim source/_posts/2013-12-20-my-new-post.markdown
> rake generate
# Successfully generated site: source -> public
> rake deploy
# Generating Site with Jekyll
# Copying public to _deploy
# Pushing generated _deploy website
# Github Pages deploy complete

There’s of course so much more you can do (preview it locally before uploading for example) but that’s the basic workflow.

Project

I have a bunch of stuff I want to mess with, but I intend to start writing a few simple web applications. I have in mind some kind of Ruby-on-Rails stack using Ember.js for the browser’s UI modeling. A shared drawing application perhaps?

Also, I would love to mess around more with C++11/C++14, I have played a little so far and have been very impressed with the productivity and conciseness it affords (it’s about time!) A little network game perhaps? I really would love to make a little modular adventure game at some stage. Who knows, perhaps I will be the one to finally make a nice graphical Dwarf Fortress clone? That seems to be the indy gaming unicorn.

Japan Lifestyle

So far I have been fortunate but it can be frustrating at times. Living in Japan without a job is a little challenging, though I suspect that would be true in most countries. The immediate challenges are keeping my house (I must renew my lease and they weren’t too impressed with the blank ‘employment’ section of the document) and preparing to pay the various taxes – most notably residential tax and health insurance, both of which are means-based on the previous years income.

I was very happy to discover that just around the corner from my house is a little cafe run by a very friendly independent game-developer – PicoPico cafe. Once a month they hold ‘PicoTachi’, an event for independent developers (and anyone else really) to show off stuff they’ve been working on. That seems almost too fortuitous! I am also looking forward to working in the cafe by myself, it has a very nice ambiance.