The Pixel and the Number

// cmd/worldc/main.go — a throwaway main; the client's real one starts in stage 2
package main

import "fmt"

// show prints one packed color and the four bytes inside it.
func show(name string, c uint32) {
	a := (c >> 24) & 0xFF
	r := (c >> 16) & 0xFF
	g := (c >> 8) & 0xFF
	b := c & 0xFF
	fmt.Printf("%-14s 0x%08X = %10d   alpha %3d  red %3d  green %3d  blue %3d\n",
		name, c, c, a, r, g, b)
}

func main() {
	show("valley water", 0xFF4A90D2)
	show("no alpha byte", 0x004A90D2)
	show("pure red", 0xFFFF0000)

	// Take the water apart and put it back together.
	const water uint32 = 0xFF4A90D2
	a, r, g, b := (water>>24)&0xFF, (water>>16)&0xFF, (water>>8)&0xFF, water&0xFF
	packed := a<<24 | r<<16 | g<<8 | b
	fmt.Printf("repacked:      0x%08X   same number: %v\n", packed, packed == water)
}

$ go run ./cmd/worldc
valley water   0xFF4A90D2 = 4283076818   alpha 255  red  74  green 144  blue 210
no alpha byte  0x004A90D2 =    4886738   alpha   0  red  74  green 144  blue 210
pure red       0xFFFF0000 = 4294901760   alpha 255  red 255  green   0  blue   0
repacked:      0xFF4A90D2   same number: true

Two operators are doing all the work. c >> 16 shifts the whole number sixteen bits to the right, which slides the red byte down into the bottom eight bits and pushes green, blue and everything below them off the end. What is left above red is alpha, still sitting there, so & 0xFF follows: a bitwise AND against eight one-bits keeps the bottom eight bits and zeroes every bit above them. Shift to bring the byte you want to the bottom, mask to discard the rest. Packing runs the same two ideas backwards: shift each byte up to its own position and OR them together, since no two of them have a bit in common.

The second line is a trap you will meet in real work. 0x004A90D2 holds the same red, green and blue as the water, and it is a different color: alpha 0, a color that is not there. Six-digit hex is the habit the web trained into everyone, and dropping into it here silently writes a fully transparent pixel that no amount of squinting at the red, green and blue values will explain. Eight digits, always, and the first pair is not optional. The third line is the sanity check every palette deserves: 0xFFFF0000 reads as opaque, red at maximum, green and blue at zero, and it is the reddest red the display can produce.

// internal/render/color.go
// Package render owns pixels. Nothing in here knows what a world is,
// what a tick is, or that a package called sim exists.
package render

// Color is one pixel: alpha, red, green and blue, eight bits each,
// packed into one 32-bit number with alpha in the highest byte.
type Color uint32

// RGBA packs four components into one Color.
func RGBA(a, r, g, b uint8) Color {
	return Color(a)<<24 | Color(r)<<16 | Color(g)<<8 | Color(b)
}

// A, R, G and B are the four bytes back out again. Converting to
// uint8 keeps the low eight bits, which is the & 0xFF written shorter.
func (c Color) A() uint8 { return uint8(c >> 24) }
func (c Color) R() uint8 { return uint8(c >> 16) }
func (c Color) G() uint8 { return uint8(c >> 8) }
func (c Color) B() uint8 { return uint8(c) }

// The valley's first three colors, one per kind of ground, plus the
// fully transparent zero value a new buffer is full of.
const (
	Clear Color = 0x00000000
	Rock  Color = 0xFF5A5F63
	Soil  Color = 0xFF6B5A3E
	Water Color = 0xFF4A90D2
)

// internal/render/buffer.go
package render

// Buffer is a rectangle of pixels: W by H colors held in one flat
// slice, row after row, addressed with the same arithmetic the
// terrain grid uses on its cells.
type Buffer struct {
	W, H int
	Pix  []Color
}

// NewBuffer allocates a w-by-h buffer in a single allocation. Every
// pixel starts at the zero value, Clear.
func NewBuffer(w, h int) *Buffer {
	return &Buffer{W: w, H: h, Pix: make([]Color, w*h)}
}

// index turns a pixel coordinate into a position in the flat slice.
func (b *Buffer) index(x, y int) int { return y*b.W + x }

// In reports whether a pixel coordinate is on the buffer at all.
func (b *Buffer) In(x, y int) bool {
	return x >= 0 && x < b.W && y >= 0 && y < b.H
}

// Set writes one pixel. A coordinate off the buffer is dropped: a
// drawing operation that runs off an edge is ordinary, not an error.
func (b *Buffer) Set(x, y int, c Color) {
	if !b.In(x, y) {
		return
	}
	b.Pix[b.index(x, y)] = c
}

// At returns the color at a pixel coordinate, or Clear if the
// coordinate names no pixel.
func (b *Buffer) At(x, y int) Color {
	if !b.In(x, y) {
		return Clear
	}
	return b.Pix[b.index(x, y)]
}

// Fill paints every pixel one color, walking the flat slice straight
// through without computing a single coordinate.
func (b *Buffer) Fill(c Color) {
	for i := range b.Pix {
		b.Pix[i] = c
	}
}

// cmd/worldc/main.go — the client's real main, one buffer deep
package main

import (
	"fmt"

	"theworld/internal/render"
)

const version = "0.0.1"

func main() {
	fmt.Println("worldc", version)

	b := render.NewBuffer(24, 12)
	fmt.Printf("buffer %dx%d: %d pixels, %d bytes of pixel data\n",
		b.W, b.H, len(b.Pix), len(b.Pix)*4)
	fmt.Printf("a fresh pixel at (3,2): 0x%08X\n", uint32(b.At(3, 2)))

	b.Fill(render.Soil)
	b.Set(3, 2, render.Water)
	b.Set(30, 2, render.Rock) // off the right edge: dropped

	fmt.Printf("slot for (3,2) is 2*24 + 3 = %d\n", 2*b.W+3)
	fmt.Printf("Pix[%d] = 0x%08X, and At(3,2) = 0x%08X\n",
		2*b.W+3, uint32(b.Pix[2*b.W+3]), uint32(b.At(3, 2)))
	fmt.Print("row 2, slots 51 through 58:")
	for x := 3; x < 11; x++ {
		fmt.Printf(" %08X", uint32(b.Pix[2*b.W+x]))
	}
	fmt.Println()
	fmt.Printf("after the off-edge write: %d pixels, At(30,2) = 0x%08X\n",
		len(b.Pix), uint32(b.At(30, 2)))
}

$ go run ./cmd/worldc
worldc 0.0.1
buffer 24x12: 288 pixels, 1152 bytes of pixel data
a fresh pixel at (3,2): 0x00000000
slot for (3,2) is 2*24 + 3 = 51
Pix[51] = 0xFF4A90D2, and At(3,2) = 0xFF4A90D2
row 2, slots 51 through 58: FF4A90D2 FF6B5A3E FF6B5A3E FF6B5A3E FF6B5A3E FF6B5A3E FF6B5A3E FF6B5A3E
after the off-edge write: 288 pixels, At(30,2) = 0x00000000

Read the fourth and fifth lines together, because they are the whole claim of the chapter. The program computed the slot by hand, 2·24 + 3 = 51, reached into the flat slice at that number, and found the water it had asked Set to put at column 3, row 2. Then At was asked the same question in coordinates and answered with the same eight hex digits. Two ways of naming one location, agreeing. The row of slots after it shows the neighbours: one water pixel, then soil running east, laid out end to end in memory exactly as they are laid out on the row.

A fresh buffer prints 0x00000000, and that number is not black. Alpha 0 makes it a pixel with no color at all, the same zero-value trick the terrain grid used when a new world came out solid rock: make hands back zeroed memory, and the type decides what zero means. Here it means nothing has been drawn yet.

// internal/render/buffer.go — a debug view, four colors wide
import "strings"

// glyphs pairs each palette color with a one-byte stand-in.
var glyphs = []struct {
	c Color
	g byte
}{{Clear, ' '}, {Rock, '#'}, {Soil, '.'}, {Water, '~'}}

// Preview draws the buffer as one character per pixel, so a terminal
// can show what is in it before anything can display it properly. A
// color outside the palette prints as ?.
func (b *Buffer) Preview() string {
	var s strings.Builder
	for y := 0; y < b.H; y++ {
		for x := 0; x < b.W; x++ {
			c := b.Pix[b.index(x, y)]
			ch := byte('?')
			for _, k := range glyphs {
				if k.c == c {
					ch = k.g
				}
			}
			s.WriteByte(ch)
		}
		s.WriteByte('\n')
	}
	return s.String()
}

// cmd/worldc/main.go — the body of main paints something
	b := render.NewBuffer(24, 12)
	b.Fill(render.Soil)

	// The rim: the top and bottom rows, then the left and right columns.
	for x := 0; x < b.W; x++ {
		b.Set(x, 0, render.Rock)
		b.Set(x, b.H-1, render.Rock)
	}
	for y := 0; y < b.H; y++ {
		b.Set(0, y, render.Rock)
		b.Set(b.W-1, y, render.Rock)
	}
	// The pond: every pixel inside one rectangle.
	for y := 4; y <= 7; y++ {
		for x := 3; x <= 14; x++ {
			b.Set(x, y, render.Water)
		}
	}
	// The spring: exactly one pixel, at column 19, row 2.
	b.Set(19, 2, render.Water)

	fmt.Print(b.Preview())

	n := 0
	for _, c := range b.Pix {
		if c == render.Water {
			n++
		}
	}
	fmt.Println("water pixels in the slice:", n)

$ go run ./cmd/worldc
worldc 0.0.1
########################
#......................#
#..................~...#
#......................#
#..~~~~~~~~~~~~........#
#..~~~~~~~~~~~~........#
#..~~~~~~~~~~~~........#
#..~~~~~~~~~~~~........#
#......................#
#......................#
#......................#
########################
water pixels in the slice: 49

Four loops and a single write, and the rectangle came out where the arithmetic said it would: twelve columns of pond spanning rows 4 through 7, one lone spring pixel high on the right at column 19, row 2. Count the water: forty-eight pixels of pond plus one, and the count came from a single pass over the flat slice with no coordinates involved at all, the same loop Fill uses. That is the flat layout paying rent again. Ask a spatial question and you compute an index; ask "how many of these are there" and you walk the run.

Everything about this picture is hand-placed, exactly like the first pond you tiled by hand before a seed grew one. The terrain grid is right there in the same module and the buffer has never heard of it. Connecting them takes a tileset and a mapping from terrain to tile. What matters today is that a color put at a coordinate is at that coordinate.

// internal/render/color.go — the fix

// Lighten adds n to red, green and blue, each channel stopping at 255
// instead of running into its neighbour. Alpha is left alone.
func Lighten(c Color, n uint8) Color {
	return RGBA(c.A(), addTo255(c.R(), n), addTo255(c.G(), n), addTo255(c.B(), n))
}

// addTo255 adds two bytes in arithmetic wide enough to hold the answer,
// then clamps.
func addTo255(v, n uint8) uint8 {
	sum := int(v) + int(n)
	if sum > 255 {
		return 255
	}
	return uint8(sum)
}

// cmd/worldc/main.go — three depths of one water color
	show("water", render.Water)
	show("+24", render.Lighten(render.Water, 24))
	show("+48", render.Lighten(render.Water, 48))
	show("+72", render.Lighten(render.Water, 72))

$ go run ./cmd/worldc
water      0xFF4A90D2   alpha 255  red  74  green 144  blue 210
+24        0xFF62A8EA   alpha 255  red  98  green 168  blue 234
+48        0xFF7AC0FF   alpha 255  red 122  green 192  blue 255
+72        0xFF92D8FF   alpha 255  red 146  green 216  blue 255

Three steadily paler blues, and the interesting line is the middle one. Blue lands on 255 at +48, the same addition that wrapped to 2 before, because int(210) + int(48) is computed in a 64-bit register where 258 fits comfortably and only then gets a decision applied to it. Green comes out 192, not 193; the phantom carry is gone with the mechanism that produced it. At +72 blue is stuck at 255 while red and green keep climbing, so the color drifts toward white instead of overshooting into nonsense. That drift is a real property of clamping and something to watch: brighten hard enough and every color converges on white, so a palette built by lightening one base color runs out of distinct steps at the top.

// internal/render/ppm.go
package render

import (
	"bufio"
	"fmt"
	"io"
)

// WritePPM writes a buffer as a plain PPM image: three header lines,
// then one line per row holding three decimal numbers per pixel. PPM
// has no alpha channel, so the alpha byte is dropped on the way out.
func WritePPM(w io.Writer, b *Buffer) error {
	out := bufio.NewWriter(w)
	fmt.Fprintf(out, "P3\n%d %d\n255\n", b.W, b.H)
	for y := 0; y < b.H; y++ {
		for x := 0; x < b.W; x++ {
			c := b.Pix[b.index(x, y)]
			if x > 0 {
				out.WriteByte(' ')
			}
			fmt.Fprintf(out, "%d %d %d", c.R(), c.G(), c.B())
		}
		out.WriteByte('\n')
	}
	return out.Flush()
}

// cmd/worldc/main.go — stage 3's loops lifted into paint, plus depth and a file
package main

import (
	"flag"
	"fmt"
	"os"

	"theworld/internal/render"
)

const version = "0.0.1"

// paint fills a buffer with a rim, soil, and a pond that pales toward
// its northern edge.
func paint(b *render.Buffer) {
	b.Fill(render.Soil)
	for x := 0; x < b.W; x++ {
		b.Set(x, 0, render.Rock)
		b.Set(x, b.H-1, render.Rock)
	}
	for y := 0; y < b.H; y++ {
		b.Set(0, y, render.Rock)
		b.Set(b.W-1, y, render.Rock)
	}
	// Four rows of pond, the shallowest lightened most.
	shallow := []uint8{72, 48, 24, 0}
	for i, n := range shallow {
		c := render.Lighten(render.Water, n)
		for x := 3; x <= 14; x++ {
			b.Set(x, 4+i, c)
		}
	}
	b.Set(19, 2, render.Water)
}

func main() {
	path := flag.String("ppm", "valley.ppm", "where to write the picture")
	flag.Parse()

	fmt.Println("worldc", version)

	b := render.NewBuffer(24, 12)
	paint(b)
	fmt.Print(b.Preview())

	// A four-by-three buffer, small enough to read the file format off
	// the screen.
	demo := render.NewBuffer(4, 3)
	demo.Fill(render.Soil)
	demo.Set(1, 1, render.Water)
	demo.Set(2, 1, render.Rock)
	if err := render.WritePPM(os.Stdout, demo); err != nil {
		fmt.Fprintln(os.Stderr, "worldc:", err)
		os.Exit(1)
	}

	f, err := os.Create(*path)
	if err != nil {
		fmt.Fprintln(os.Stderr, "worldc:", err)
		os.Exit(1)
	}
	defer f.Close()
	if err := render.WritePPM(f, b); err != nil {
		fmt.Fprintln(os.Stderr, "worldc:", err)
		os.Exit(1)
	}
	info, err := f.Stat()
	if err != nil {
		fmt.Fprintln(os.Stderr, "worldc:", err)
		os.Exit(1)
	}
	fmt.Printf("wrote %s: %dx%d, %d bytes\n", *path, b.W, b.H, info.Size())
}

$ go run ./cmd/worldc -ppm /tmp/valley.ppm
worldc 0.0.1
########################
#......................#
#..................~...#
#......................#
#..????????????........#
#..????????????........#
#..????????????........#
#..~~~~~~~~~~~~........#
#......................#
#......................#
#......................#
########################
P3
4 3
255
107 90 62 107 90 62 107 90 62 107 90 62
107 90 62 74 144 210 90 95 99 107 90 62
107 90 62 107 90 62 107 90 62 107 90 62
wrote /tmp/valley.ppm: 24x12, 2898 bytes

The four-by-three image is the format with nothing hidden. P3 says plain-text color pixels, 4 3 is width then height, 255 is the largest value a channel will use, and then twelve pixels arrive in reading order: three rows of soil at 107, 90, 62, with the water and the rock side by side in the middle row. Those are the same decimal bytes stage 1 pulled out of 0xFF4A90D2, and any image viewer on your machine will open the 24-by-12 file and show you the pond, pale rows and all. Alpha does not survive the trip; PPM has nowhere to put it, so the number stays in the buffer and the file carries three channels instead of four.