2D Procedural Generation with Dither

Dither's standard library for 2D graphics, gx, has an easy-to-use interface that resembles that of Processing/p5.js. So if you're familiar with these platforms, you already know how to do draw in 2D with Dither. Nevertheless, this tutorial goes through the basics by writing a small but interesting project together with the reader. The hope is that we learn not only Dither, but also some useful ideas in procedural generation.

Overview

The gx library uses native rendering on each platform: Direct2D on windows, Coregraphics on mac, canvas API on the web... in order to give you the fastest and nicest-looking 2D graphics wherever you are.

Our example project is a generative building facade inspired by old apartment buildings in some parts of China.

Getting Started

Let's start by initializing an empty window and filling it with a background:

We use the size function to initialize a window and 2D context given width and height (it calls win.init from "std/win" internally). background function takes RGB values in 0-1.0 range and fills the background with given color.

The poll function refreshes the display and listens for user events. We call it once per iteration in the main loop. This is one of the major differences from Processing/p5.js — instead of having predefined magic functions setup/draw, you're responsible for maintaining your own draw loop.

Next, let's sketch up the “scaffold” for our building facade project. We divide the problem up by drawing 1 apartment (or cell as we call it here) at a time. We write a randomized draw_cell() function, and use a nested for loop to call it once for each cell, positioning it correctly along the way.

As the first step we just make width and height of each cell slightly different, as well as color. We randomize the color by giving rand.random function vector arguments (min and max), and thanks to template matching in Dither it selects the correct function to use. Since width and height are also randomized, we keep counters x and y to dynamically place the cells, since we don't know where each is going to end up before time.

In gx.fill(...bc), ... is the spread operator that puts components of a vector or tuple into arguments, it is as if writing out gx.fill(bc.b, bc.g, bc.b).

Functions of interest here include gx.push_matrix() and gx.pop_matrix(), which saves the current transformation state (and restores it later), and gx.translate which modifies the transformation state by applying a translation (movement) to it. The no_stroke and fill function styles subsequent draw calls, and rect simply draws a rectangle given left, top, width, height arguments.

Next up, let's add some windows to each cell.

We added a few new randomized variables for the windows (not the application window, nor microsoft Windows, I mean the real apartment windows), such as coordinates, size, and number of panes. In draw_cell, we first stroke a big frame, and use a for loop to stroke and fill individual panes and their (thinner) frames. We use a random muddy colors for the panes, with some “light” muddy ones and “dark” extra muddy ones.

There's also a chance to add a horizontal bar/beam/divider to somewhere near the middle of the panes. For this, we use gx.line, which takes start X, start Y, end X, end Y and draws a line.

A word about organizing code. As you might have noticed, our strategy is to have a few shared global variables for the main parameters of each cell, which gets randomized each time before we invoke the cell-drawing function. The minor, inconsequential parameters are generated within the subroutine. You can, of course, organize it some other, more pedantic way, for example, pass all parameters to the subroutine (maybe even packed together in a struct), or, have a class called Cell with the parameters as fields, and so on — You can do whatever you like, here, for simplicity's sake, we're doing it this way.

Adding Details

Next, let's add the outdoor AC units, which is a central visual element to Chinese urban landscape.

First, we calculate whether there's enough left-over space from drawing the windows, then we find a good location for the AC. We create an illusion of 3D by drawing 2 rectangles of different shades on top of each other, then decorate the box with fan, logo and brackets.

Functions of interest includes gx.circle, which draws a circle given center X, center Y, and diameter. It has a “sister” function (not shown here) called ellipse, which has diameter X (width) and diameter Y (height) in place of circle's last argument.

Next, we are going to add some metal bars/“cages” to some of the windows. Don't worry! they're only for keeping burglars out.

The code for drawing the cages are pretty straightforward — we make extensive use of gx.line. A for loop is used to arrange the individual bars in a horizontal array evenly spaced.

Next, let's add the colorful hanging clothes, which are an iconic sight in the region where I grew up.

The clothes are basically distorted pentagons on a slanted line. We randomly pick between two coloring schemes: white-ish color, or full random color, which seems to be a good enough model of the real world. We use begin_shape again to draw the inverted pentagon. We use a pentagon because it is complex enough to represent “draped” shape or “pants” shape, but not too complex that it starts introducing degeneracies. There're multiple poles per frame, and multiple clothes per pole, controlled again by nested for loops.

Now let's add some organic stuff to the scene, to imbue it with liveliness. We're going to add some plants to the windowsills. First, we're going to forget about the buildings for a moment, and focus on just getting the plants right. We use this technique a lot when generating self-contained sub-component of a larger system. We scale everything up 2x and layout a bunch of plants in a nice grid, so we can see all the varieties.

We use a crude but effective technique for the leaves — A bunch of rotated squares randomly stacked on top of each other. Turns out when you have enough squares, they can give you an interesting overall outline without having things that are too sharp or smooth. We give each square a slightly different shade of green, to add depth and realism.

If it is a flowering plant, we'll add a little circle of reddish color for each leaf. Other leaves might naturally occlude the flowers, thanks for our bunch-of-squares model of leaves.

We draw the pot with a brown-ish color, as is common with pots. We sandwich the pot between leaves, so it gets naturally occluded by some leaves but not all of them, again for depth and realism.

Now let's insert the plants into the scene. We want to draw the plant between the pane background color and the pane frame, so we had to break up the pane-drawing code a little.

As you can see our scene is looking pretty good, if I might say so myself. Time to add some finishing touches and call it a day!

Finishing Touches

Many building facades are made out of some sort of tiles or bricks, instead of just cement. So we want to model that. Also, some buildings have exposed pipes.

Whether or not we have tiles or pipes are each determined by a random chance. The pipe is just two lines, thick dark line and thin light line on top of each other, for a crude illusion of a cylindrical object. The bricks are just a grid, drawn with colors slightly darker color than that of the facade itself.

There we have it! The generative piece is now complete. You can try increasing the width and height of the canvas, to explore the variations. Or if you think of some other elements to add, feel free to try those out too!

Interactivity & Animation

Right now we get one static view and that's it. Let's add a click event listener to refresh/regenerate the piece, so we can have a better look at all the variations. It'll also be more convenient for our users, if they want to pick one they like.

We simply wrap our whole program in a function called generate, and call that whenever mouse button is pressed anywhere. We detect the event by looking at the return value of gx.poll(), which refreshes display and grabs user events, as mentioned before. Each poll pops one event, which we check if the type of which is MOUSE_PRESSED upon which we call generate again.

We use gx.text to draw a string in a fixed 8x16px monospace font, given string, x, and baselineY.

Again, we could have organized our code differently, perhaps by having some sort of parameter object or by modularizing. Here we just do barely enough to keep things simple.

Now this clicking thing is a bit boring. What if we have an infinite scroll of buildings? Like it keeps expanding forever and never repeats. It is not so hard to achieve, by having some offline buffers that we swap around.

We initialize offscreen rendering buffers (think of it as a canvas or drawing surface that we don't immediately put onto the screen) using gx.create_graphics(w,h). Once we call begin on the graphics, we can draw whatever we like, just like with the main canvas. When end is called on it, we return to drawing on the main canvas. We can blit the offscreen graphics back onto the screen by calling draw(x,y) on the graphics.

A simpler version of what we implemented above: we can just have two such buffers swap (left) and swbp (right), moving at the same time toward the left. When swap completely moves out of view, we fill it with new buildings, and put it to the right of swbp. Now swbp is the new conceptual swap and vice versa, and we keep on doing that.

A small problem with that approach is, if you have a slower computer, you might notice a tiny hiccup once in a while — this is when the new buffer is being generated. We improve it by having smaller slices: one buffer per column of buildings. We keep a list of these, and move the first of the list to the end of the list whenever it scrolls out of view. This implementation does exactly just that!

Now an interesting exercise for the reader would be to make it scroll vertically, or even diagonally!

Conclusion

In this tutorial, we learnt quite a few thing by doing a generative project together. To recap:

• size and background sets up our window and drawing context;
• rect, circle, line draws primitives;
• begin_shape, vertex, end_shape draws arbitrary polyline/polygons;
• fill, no_fill, stroke, no_stroke styles subsequent draw calls;
• push_matrix, pop_matrix saves and restores transformation states;
• translate and rotate_deg apply transformations;
• create_graphics, begin, end, draw deals with offline rendering buffers;
• text for simple text
• rand.random generates random numbers and vectors.

Now, you can read the official Dither examples which uses gx for 2D graphics extensively to learn more, check out the reference, or step up the game by working with 3D!