Drawing

The screen

The screen is 160 × 120 pixels and starts black. Nothing appears on it unless your code draws it, as on the old machines, where the program had to put every pixel there itself.

Positions are counted in blocks of 5 × 5 pixels: x from 0 to v (31), y from 0 to n (23). The middle of the screen is about g (16), c (12).

A colour is a number from 0 to f in the current palette. V sets the palette: 0 NES, 1 Commodore 64, 2 Game Boy, 3 CGA. Its second input is the background colour. Change the palette and everything already drawn changes colour with it. The palettes, colour by colour.

Drawing operators

Most drawing operators draw every tick, at the place their inputs say:

Operator	Draws	Inputs
X	a pixel (a 5 × 5 block)	x, y, colour
H	a horizontal bar	x, y, width, colour
L	a line	x1, y1, x2, y2, colour
Q	a ring	x, y, radius, colour
O	a sprite, chosen by a seed	x, y, seed, colour
$	your own sprite, drawn in the cells below it	x, y, width, height
"	text	x, y, colour, then letters
U	random sparkles	amount, colour
~	a whole-screen pattern	pattern, speed, scale, colour, span

What is drawn stays: the picture keeps it. So a pixel whose x moves leaves a line. Feed a wave into its x:

V0
.4Wu
.X.c4
T2

4Wu writes a value that swings smoothly from 0 to u (30) and back, once a bar, straight into X’s x input. X draws a yellow block on row c. T2 dissolves the picture a little every tick, so the line becomes a fading trail. Without T, it would fill the row.

Clearing and fading

• T dissolves: random pixels go out each tick, from 0 (keep everything) to 9 (almost at once). With a second input of 1, it fades instead: every pixel steps down through the palette together, for smooth glows.
• K wipes the picture when a bang touches it. Next to a beat, it clears in time.
• F flashes the whole screen in one colour on a bang.

Moving the picture

These change what is already drawn, every tick:

• M scrolls: direction (0 left, 1 right, 2 up, 3 down), amount in pixels, and a rotation in steps of 10°. M05 scrolls left five pixels a tick: time passing.
• Z mirrors: 0 left half onto the right, 1 top onto bottom, 2 both, a kaleidoscope. Draw in one corner, get four.
• + zooms from the centre: something small in the middle becomes a tunnel.
• = ripples rows sideways along a wave.
• % shifts every colour along the palette: palette cycling.
• / glitches: random bands jump sideways.

Several of them react to bangs too: each bang turns M and Z by a step, kicks the zoom, jumps the ripple, or bursts the glitch. See the drawing reference.

Layers

The picture has three layers, seen from the front: 2 front, 1 middle (the usual one), 0 back. Empty pixels show the layer behind.

[ sets the layer for the drawing operators that follow it in reading order: [0 sends them to the back, [2 to the front. The effects (T, M, K, Z…) only touch their own layer, so a sky can stay still behind a ship that leaves a trail.

~ fills a whole layer with a moving pattern (plasma, stripes, rings, checkerboard, noise, gradient, tunnel). It goes to the back layer by itself, so it never hides what you draw.

[0
~0244
[1
.1D4
..?Xgc1
T3

A plasma at the back, and on the middle layer a white block that appears on every beat (? lets X draw only when a bang touches the gate) and dissolves.

] sets the size of what follows: ]3 draws sprites and text three times as big, up to 8.

Your own sprites and words

$ draws a sprite you write yourself: its inputs are x, y, width and height, and the pixels are the cells below it, one colour digit each (empty is see-through). So the picture in the code is the picture on the screen. Up to 16 × 16.

" writes text: x, y, colour, then the letters, up to 16. _ is a space. Any letter can come from a sequence, which makes a scroller.

Pictures that follow the music

• I writes the current volume of a chip channel (0–f). Put it on a radius, a width or a colour:

  1D4
  ..B3C2o
  ...I2
  Qgc.4
  T6

  I2 listens to the triangle, which plays the kick. Its value lands in the ring’s radius, so the ring jumps on every kick and shrinks as the note dies.

• ; is a swell: a bang sets it to its peak, then it falls back by one every few ticks. Wired into a size, it makes things pulse on the beat.

• A bang can drive the picture directly: F flashes, K wipes, and a gate ? in front of any drawing operator makes it draw only on the bang.

The picture plays the music

It works the other way round too. , is an eye: it looks at one block of the picture and writes the colour it sees below, or a bang if anything is drawn there (third input 1). Draw bars, sweep an eye over them, and each bar is a note. The example Player piano and the tutorial chapter The picture plays show how.

Ideas to start from

The Visuals examples cover rain, equalizers, raster bars, tunnels, plasma, scrollers and kaleidoscopes; Code as art and Little worlds put sound and picture together.