The Pixels a Sprite Skips

// cmd/mkatlas/main.go
package main

import (
	"fmt"
	"os"

	"theworld/internal/render"
)

// Cell is the size of every frame on the sheet.
const Cell = 16

// The stand-in palette. ' ' is the pixel that is not there.
var key = map[byte]render.Color{
	' ': 0x00000000, // nothing at all: alpha 0
	'o': 0xFF2B3524, // outline
	'b': 0xFF6E8F4A, // body
	'l': 0xFF9DBF6B, // belly
	'e': 0xFFF2EEDC, // eye
}

// shade is the shadow's color: a cool near-black, one quarter there.
const shade render.Color = 0x40101418

// stand is one walker, drawn as characters so the transparent pixels
// are the ones you can see through in the source too.
var stand = []string{
	"                ",
	"                ",
	"          oooo  ",
	"        oobbbbo ",
	"   oooooobbebbo ",
	"  obbbbbbbbbbbo ",
	" obllbbbbbbbbbo ",
	" obllllbbbbbbo  ",
	" obbllbbbbbbo   ",
	"  obbbbbbbbbo   ",
	"   bb    bb     ",
	"   bb    bb     ",
	"   oo    oo     ",
	"                ",
	"                ",
	"                ",
}

// step is the same walker mid-stride: two frames of an animation share
// everything except the rows that move.
var step = withLegs(stand, []string{
	"  bb       bb   ",
	"  bb       bb   ",
	"  oo       oo   ",
})

// withLegs copies a mask and replaces rows 10 through 12.
func withLegs(mask []string, legs []string) []string {
	out := append([]string(nil), mask...)
	copy(out[10:13], legs)
	return out
}

// cmd/mkatlas/main.go — the mask becomes pixels

// paint writes one character mask into the sheet at a cell origin.
func paint(sheet *render.Buffer, col int, mask []string) {
	if len(mask) != Cell {
		fmt.Fprintf(os.Stderr, "mkatlas: cell %d has %d rows, want %d\n", col, len(mask), Cell)
		os.Exit(1)
	}
	for y, row := range mask {
		if len(row) != Cell {
			fmt.Fprintf(os.Stderr, "mkatlas: cell %d row %d is %d characters, want %d\n", col, y, len(row), Cell)
			os.Exit(1)
		}
		for x := 0; x < Cell; x++ {
			c, ok := key[row[x]]
			if !ok {
				fmt.Fprintf(os.Stderr, "mkatlas: cell %d row %d: no color for %q\n", col, y, row[x])
				os.Exit(1)
			}
			sheet.Set(col*Cell+x, y, c)
		}
	}
}

// shadow draws a squat oval across the bottom of a cell, every pixel of
// it one quarter opaque.
func shadow(sheet *render.Buffer, col int) {
	for _, r := range []render.Rect{{X0: 4, Y0: 12, X1: 12, Y1: 13},
		{X0: 2, Y0: 13, X1: 14, Y1: 14},
		{X0: 4, Y0: 14, X1: 12, Y1: 15}} {
		for x := r.X0; x < r.X1; x++ {
			sheet.Set(col*Cell+x, r.Y0, shade)
		}
	}
}

// testCard fills a cell with sixteen columns of one color at sixteen
// alphas, 0 on the left and 255 on the right: an asset that exists to
// be measured.
func testCard(sheet *render.Buffer, col int) {
	for x := 0; x < Cell; x++ {
		a := uint8(x * 17)
		for y := 0; y < Cell; y++ {
			sheet.Set(col*Cell+x, y, render.RGBA(a, 0xE8, 0xD8, 0xA0))
		}
	}
}

func main() {
	sheet := render.NewBuffer(4*Cell, Cell)
	paint(sheet, 0, stand)
	paint(sheet, 1, step)
	shadow(sheet, 2)
	testCard(sheet, 3)

	const path = "assets/atlas.png"
	if err := sheet.SaveSheet(path); err != nil {
		fmt.Fprintln(os.Stderr, "mkatlas:", err)
		os.Exit(1)
	}
	fi, err := os.Stat(path)
	if err != nil {
		fmt.Fprintln(os.Stderr, "mkatlas:", err)
		os.Exit(1)
	}
	fmt.Printf("wrote %s: %dx%d, %d cells of %d, %d bytes\n",
		path, sheet.W, sheet.H, sheet.W/Cell, Cell, fi.Size())
	fmt.Printf("pixels sha256 %s\n", sheet.Hash())
	fmt.Print(render.AlphaMap(sheet, sheet.Bounds()))
}

$ go run ./cmd/mkatlas
wrote assets/atlas.png: 64x16, 4 cells of 16, 328 bytes
pixels sha256 32b9647db215d2efe2da7a7ee45ac09cda38bac87273bc043f9db185dc88f96b
.................................................01123344566778#
.................................................01123344566778#
..........####............####...................01123344566778#
........#######.........#######..................01123344566778#
...############....############..................01123344566778#
..#############...#############..................01123344566778#
.##############..##############..................01123344566778#
.#############...#############...................01123344566778#
.############....############....................01123344566778#
..###########.....###########....................01123344566778#
...##....##.......##.......##....................01123344566778#
...##....##.......##.......##....................01123344566778#
...##....##.......##.......##.......22222222.....01123344566778#
..................................222222222222...01123344566778#
....................................22222222.....01123344566778#
.................................................01123344566778#

That block of characters is AlphaMap, which prints one character per pixel from the alpha channel alone: . for a pixel that is not there, # for a solid one, and a digit for everything in between. It is the same debugging trick Preview plays with color, aimed at the byte this chapter is about, and it shows the sheet's whole design in sixteen lines. Two solid silhouettes with different legs. A shadow of 28 pixels, every one of them a 2, which is alpha 64 of a possible 255. A test card whose sixteen columns climb from nothing on the left to solid on the right, seventeen units of alpha at a time.

The test card is there to be measured. Art is judged by eye, which leaves a blend bug room to hide inside a picture nobody has seen before; sixteen known alphas of one color over a known background produce sixteen numbers you can predict on paper.

// internal/render/sprite.go

// SaveSheet writes a buffer as an 8-bit RGBA PNG whose channels are
// straight, not scaled by alpha: the form a sprite sheet is authored
// and read in.
func (b *Buffer) SaveSheet(path string) error {
	m := image.NewNRGBA(image.Rect(0, 0, b.W, b.H))
	for y := range b.H {
		for x := range b.W {
			c := b.At(x, y)
			i := m.PixOffset(x, y)
			m.Pix[i], m.Pix[i+1], m.Pix[i+2], m.Pix[i+3] = c.R(), c.G(), c.B(), c.A()
		}
	}
	f, err := os.Create(path)
	if err != nil {
		return err
	}
	if err := png.Encode(f, m); err != nil {
		f.Close()
		return fmt.Errorf("encode %s: %w", path, err)
	}
	return f.Close()
}

$ xxd -l 32 assets/atlas.png
00000000: 8950 4e47 0d0a 1a0a 0000 000d 4948 4452  .PNG........IHDR
00000010: 0000 0040 0000 0010 0806 0000 00a6 e779  ...@...........y

SavePNG hands pixels to the encoder as color.RGBA, a type whose three color channels are defined to be scaled by alpha already. Every pixel of a frame is opaque, and for an opaque pixel the scaled and unscaled forms are the same three numbers, so the distinction has cost nothing so far. Half the cells on this sheet are not opaque. image.NRGBA is the standard library's name for the other convention, four bytes per pixel with the colors untouched, which is what the mask wrote and what the file has to carry.

The header says the file agrees. Width 00000040 is 64, height 00000010 is 16, then bit depth 8 and color type 6. The scene's PNG came out color type 2, three channels and no alpha, because the encoder inspected the pixels and found nothing to keep. This one is type 6, and that single byte is the file admitting it has holes in it.

// internal/render/sprite.go

// Sheet is one decoded image plus the size of the square cells its
// frames are cut on. Frames are rectangles into it, not files.
type Sheet struct {
	Pix  *Buffer
	Cell int
}

// Frame is the source rectangle of one cell, counted left to right and
// top to bottom, in the same half-open convention every other rectangle
// in this package uses.
func (s *Sheet) Frame(col, row int) Rect {
	return Rect{
		X0: col * s.Cell,
		Y0: row * s.Cell,
		X1: (col + 1) * s.Cell,
		Y1: (row + 1) * s.Cell,
	}
}

// Blit copies the source rectangle src of a sheet onto the buffer with
// its top-left corner at (dx,dy).
func (b *Buffer) Blit(s *Sheet, src Rect, dx, dy int) {
	// A frame that hangs off the sheet is cut to the sheet, and the
	// destination corner moves with it.
	cut := src.Intersect(s.Pix.Bounds())
	dx, dy = dx+(cut.X0-src.X0), dy+(cut.Y0-src.Y0)
	src = cut

	dst := Rect{dx, dy, dx + (src.X1 - src.X0), dy + (src.Y1 - src.Y0)}.Intersect(b.clip)
	if dst.Empty() {
		return
	}
	// Whatever the clip took off the destination comes off the source
	// too: this pair of offsets carries a destination pixel back to the
	// sheet pixel it came from.
	ox, oy := src.X0-dx, src.Y0-dy

	for y := dst.Y0; y < dst.Y1; y++ {
		for x := dst.X0; x < dst.X1; x++ {
			c := s.Pix.Pix[s.Pix.index(x+ox, y+oy)]
			if c.A() == 0 {
				continue // this pixel is not there
			}
			b.Pix[b.index(x, y)] = c
		}
	}
}

// cmd/worldc/main.go — load the sheet, count what is in one cell, draw
	pix, err := render.LoadPNG("assets/atlas.png")
	if err != nil {
		fmt.Fprintln(os.Stderr, "worldc:", err)
		os.Exit(1)
	}
	sheet := &render.Sheet{Pix: pix, Cell: 16}
	fmt.Printf("worldc %s sheet %dx%d, %d cells of %d, sha256 %s\n",
		version, sheet.Pix.W, sheet.Pix.H, sheet.Pix.W/sheet.Cell, sheet.Cell, sheet.Pix.Hash())

	// How much of one cell is actually there.
	stand := sheet.Frame(render.CellStand, 0)
	there := 0
	for y := stand.Y0; y < stand.Y1; y++ {
		for x := stand.X0; x < stand.X1; x++ {
			if sheet.Pix.At(x, y).A() != 0 {
				there++
			}
		}
	}
	fmt.Printf("cell %d: %d pixels, %d of them carry color\n", render.CellStand, 16*16, there)

	before := render.NewBuffer(render.SceneW, render.SceneH)
	render.Scene(before)

	b := render.NewBuffer(render.SceneW, render.SceneH)
	render.Scene(b)
	b.Blit(sheet, stand, 40, 58)
	b.Blit(sheet, sheet.Frame(render.CellStep, 0), 92, 66)
	b.Blit(sheet, stand, -6, 74) // half of it is off the west edge

	fmt.Printf("blitting three cells changed %d pixels of the frame\n", render.Diff(before, b).Count)
	fmt.Printf("frame %dx%d sha256 %s\n", b.W, b.H, b.Hash())

$ go run ./cmd/worldc -shot walkers.png
worldc 0.0.1 sheet 64x16, 4 cells of 16, sha256 befd50436a855f41cb45c7ff45d804b5f5e73956e650b1db3aa167e9a9f45e54
cell 0: 256 pixels, 98 of them carry color
blitting three cells changed 262 pixels of the frame
frame 160x96 sha256 560c9e0bad113c4410441a0fd25f2319c50414fcf0b0295d11eddf1ba6936857
wrote walkers.png

Open walkers.png. Two creatures stand on the ground, one of them at the north edge of the pond with water plainly visible between its front and back legs, and a third is walking in from the west with only its head and front legs on the frame. None of them sits in a box. The 158 transparent pixels of each cell did nothing, and doing nothing is the entire feature.

The count on the third line is the claim, and it is checkable. Two full cells at 98 colored pixels each is 196. The third blit starts at column −6, so its first six columns fall off the west edge and ten survive, and those ten columns hold 66 colored pixels. 98 + 98 + 66 = 262, exactly what Diff reports against the same scene drawn without sprites. No blitted pixel landed on ground that already happened to be its color.

Follow the clipped one through the code, because it is where blitting differs from filling. The destination rectangle is {-6 74 10 90}, and intersecting it with the clip gives {0 74 10 90}, six columns narrower on the left. The source has to lose the same six columns from the same side, and ox = src.X0 - dx is what does it: with src.X0 at 0 and dx at −6, ox is 6, so destination column 0 reads sheet column 6 and the walker's rear half is never read at all. That is chapter 13's rule applied to two rectangles at once. Clip the largest unit you can name in advance, then carry the same adjustment across to wherever the pixels are coming from.

// internal/render/sprite.go

// Over mixes one source pixel into one destination pixel, source-over:
// each channel is (src*a + dst*(255-a)) / 255. The destination is a
// framebuffer pixel, always opaque, so the answer is opaque too.
func Over(src, dst Color) Color {
	a := int(src.A())
	inv := 255 - a
	r := (int(src.R())*a + int(dst.R())*inv) / 255
	g := (int(src.G())*a + int(dst.G())*inv) / 255
	b := (int(src.B())*a + int(dst.B())*inv) / 255
	return RGBA(255, uint8(r), uint8(g), uint8(b))
}

// internal/render/sprite.go — Blit's inner loop, with the case it was missing
			c := s.Pix.Pix[s.Pix.index(x+ox, y+oy)]
			switch c.A() {
			case 0: // not there: leave the framebuffer alone
			case 255: // solid: overwrite
				b.Pix[b.index(x, y)] = c
			default: // partly there: mix
				i := b.index(x, y)
				b.Pix[i] = Over(c, b.Pix[i])
			}

// cmd/worldc/main.go — print the hand calculation, then draw everything
	shadowPx := sheet.Pix.At(render.CellShade*16+8, 13)
	cardPx := sheet.Pix.At(render.CellCard*16+8, 4)
	soil, sky := b.At(98, 79), b.At(128, 12)
	fmt.Printf("shadow %08X over soil %08X -> %08X\n",
		uint32(shadowPx), uint32(soil), uint32(render.Over(shadowPx, soil)))
	fmt.Printf("card   %08X over sky  %08X -> %08X\n",
		uint32(cardPx), uint32(sky), uint32(render.Over(cardPx, sky)))

	render.SpriteScene(b, sheet)
	fmt.Printf("frame %dx%d sha256 %s\n", b.W, b.H, b.Hash())
	fmt.Printf("the frame holds %08X at (98,79) and %08X at (128,12)\n",
		uint32(b.At(98, 79)), uint32(b.At(128, 12)))

// internal/render/scene.go — the standing composition, with sprites on it

// SpriteScene is Scene with the sheet drawn over it: two creatures with
// shadows, a third walking off the west edge, and the test card in the
// sky, in that order.
func SpriteScene(b *Buffer, s *Sheet) {
	Scene(b)

	stand, step := s.Frame(CellStand, 0), s.Frame(CellStep, 0)
	shade, card := s.Frame(CellShade, 0), s.Frame(CellCard, 0)

	b.Blit(s, shade, 40, 58)
	b.Blit(s, stand, 40, 58)

	b.Blit(s, shade, 92, 66)
	b.Blit(s, step, 92, 66)

	b.Blit(s, stand, -6, 74) // half of it is off the west edge
	b.Blit(s, card, 120, 8)
}

$ go run ./cmd/worldc -shot dark.png
worldc 0.0.1 sheet 64x16, 4 cells of 16, sha256 befd50436a855f41cb45c7ff45d804b5f5e73956e650b1db3aa167e9a9f45e54
shadow 40040506 over soil FF6B5A3E -> FF51442F
card   887C7355 over sky  FF6E8CA0 -> FF757E78
frame 160x96 sha256 119f1222fdc2003de1c564185cfecc9a2cfa95a992ad5bc2a4801e92f9d941e7
the frame holds FF51442F at (98,79) and FF757E78 at (128,12)
wrote dark.png

The hand calculation said 0xFF544834 and the program says 0xFF51442F. Open the file and the test card, which should climb evenly from sky blue to pale, sags through a muddy grey in its middle columns before snapping to the right color in its last one. Something is wrong, and the interlude was checked twice.

// internal/render/sprite.go

// LoadSheet reads a sprite sheet, taking its four bytes per pixel
// exactly as they were authored.
func LoadSheet(path string, cell int) (*Sheet, error) {
	f, err := os.Open(path)
	if err != nil {
		return nil, err
	}
	defer f.Close()

	img, err := png.Decode(f)
	if err != nil {
		return nil, fmt.Errorf("decode %s: %w", path, err)
	}
	n, ok := img.(*image.NRGBA)
	if !ok {
		return nil, fmt.Errorf("%s decoded as %T, want *image.NRGBA: save the sheet as 8-bit RGBA", path, img)
	}
	b := NewBuffer(n.Rect.Dx(), n.Rect.Dy())
	for y := range b.H {
		for x := range b.W {
			i := n.PixOffset(n.Rect.Min.X+x, n.Rect.Min.Y+y)
			b.Pix[b.index(x, y)] = RGBA(n.Pix[i+3], n.Pix[i], n.Pix[i+1], n.Pix[i+2])
		}
	}
	if b.W%cell != 0 || b.H%cell != 0 {
		return nil, fmt.Errorf("%s is %dx%d, which does not divide into %d-pixel cells", path, b.W, b.H, cell)
	}
	return &Sheet{Pix: b, Cell: cell}, nil
}

// cmd/worldc/main.go — one line different
	sheet, err := render.LoadSheet("assets/atlas.png", 16)
	if err != nil {
		fmt.Fprintln(os.Stderr, "worldc:", err)
		os.Exit(1)
	}

$ go run ./cmd/worldc -shot frame.png
worldc 0.0.1 sheet 64x16, 4 cells of 16, sha256 32b9647db215d2efe2da7a7ee45ac09cda38bac87273bc043f9db185dc88f96b
shadow 40101418 over soil FF6B5A3E -> FF544834
card   88E8D8A0 over sky  FF6E8CA0 -> FFAFB4A0
frame 160x96 sha256 eb3c5619ec6474601ee8d8d80c22af448a17b6f6f87e712846d1afaefc236a83
the frame holds FF544834 at (98,79) and FFAFB4A0 at (128,12)
wrote frame.png

0xFF544834, the three numbers the table produced, and the last line confirms that the pixel sitting in the framebuffer at (98,79) is the one Over promised. The sheet's own hash changed too, from befd5043… to 32b9647d…, and the second of those is the number mkatlas printed when it wrote the file. Two programs now agree about what is in that PNG.

The card line is the more interesting proof. Blue was 160 in the sheet and 160 in the sky, and it comes back 160: mixing a color with itself returned that color, which is the property the shift would have broken. Red climbed from 110 to 175 and green from 140 to 180, both a little over half way to the card's own color, because alpha 136 out of 255 is a little over half. Open frame.png and the card is a clean ramp from sky to pale, with the ridge line behind it faintly visible through its middle columns.

dark.png is still on disk, so measure how far the bug reached, using the comparison the client grew in chapter 14:

$ go run ./cmd/worldc -diff frame.png dark.png
frame.png sha256 eb3c5619ec6474601ee8d8d80c22af448a17b6f6f87e712846d1afaefc236a83
dark.png sha256 119f1222fdc2003de1c564185cfecc9a2cfa95a992ad5bc2a4801e92f9d941e7
276 of 15360 pixels differ, first at (121,8): ff7691a0 became ff678396

276 pixels of 15,360, and their addresses finish the story. 224 of them are in the test card: fourteen of its sixteen columns, all but the two ends. 25 and 27 more are the two shadows, a little short of 28 each because the creatures' feet were drawn over them afterwards. Outside those three rectangles nothing differs at all. Both creatures are identical in both files, the card's alpha-0 column is identical, and so is its alpha-255 column. The bug could only ever touch a pixel that went through the default branch, which is exactly the set of pixels whose color the loader had scaled.

// internal/render/sprite_test.go

// sheetPath is the stand-in atlas, written by cmd/mkatlas.
var sheetPath = filepath.Join("..", "..", "assets", "atlas.png")

// frameHash is the SHA-256 of the pixels SpriteScene draws over Scene.
const frameHash = "eb3c5619ec6474601ee8d8d80c22af448a17b6f6f87e712846d1afaefc236a83"

// TestOverKeepsItsEnds pins the three properties the mix must have for a
// sprite to look like the art it was drawn from.
func TestOverKeepsItsEnds(t *testing.T) {
	dst := Soil
	src := RGBA(255, 0xE8, 0xD8, 0xA0)

	if got := Over(RGBA(0, 0xE8, 0xD8, 0xA0), dst); got != dst {
		t.Errorf("alpha 0 moved the destination: %08X, want %08X", uint32(got), uint32(dst))
	}
	if got := Over(src, dst); got != src {
		t.Errorf("alpha 255 did not deliver the source: %08X, want %08X", uint32(got), uint32(src))
	}
	// Mixing a color with itself has to return that color at every alpha,
	// or flat areas crawl darker every time something is drawn over them.
	flat := RGBA(255, 90, 90, 90)
	for a := 0; a <= 255; a++ {
		if got := Over(RGBA(uint8(a), 90, 90, 90), flat); got != flat {
			t.Fatalf("alpha %d mixed %08X with itself and got %08X", a, uint32(flat), uint32(got))
		}
	}
}

// TestSheetIsStraight checks the sheet arrives with the bytes mkatlas
// wrote, not with its colors already scaled by alpha.
func TestSheetIsStraight(t *testing.T) {
	s, err := LoadSheet(sheetPath, 16)
	if err != nil {
		t.Fatal(err)
	}
	if got, want := s.Pix.At(CellShade*16+8, 13), Color(0x40101418); got != want {
		t.Errorf("shadow pixel is %08X, want %08X: the loader scaled it", uint32(got), uint32(want))
	}
	if got, want := s.Pix.At(CellCard*16+8, 4), Color(0x88E8D8A0); got != want {
		t.Errorf("card pixel is %08X, want %08X: the loader scaled it", uint32(got), uint32(want))
	}
}

func TestSpriteSceneMatchesItsHash(t *testing.T) {
	s, err := LoadSheet(sheetPath, 16)
	if err != nil {
		t.Fatal(err)
	}
	b := NewBuffer(SceneW, SceneH)
	SpriteScene(b, s)
	got := b.Hash()
	if got == frameHash {
		return
	}
	gotPath := filepath.Join("testdata", "sprites.got.png")
	if err := b.SavePNG(gotPath); err != nil {
		t.Fatal(err)
	}
	t.Fatalf("pixels hash %s\n          want %s\n    wrote %s", got, frameHash, gotPath)
}

$ go test -count=1 -v ./internal/render/
=== RUN   TestOverKeepsItsEnds
--- PASS: TestOverKeepsItsEnds (0.00s)
=== RUN   TestSheetIsStraight
--- PASS: TestSheetIsStraight (0.00s)
=== RUN   TestSpriteSceneMatchesItsHash
--- PASS: TestSpriteSceneMatchesItsHash (0.00s)
PASS
ok  	theworld/internal/render	0.003s

Now change the three divisions in Over to >> 8 and run the first test alone, to see whether an argument made on paper is one a machine can hold you to:

$ go test -count=1 -run TestOverKeepsItsEnds ./internal/render/
--- FAIL: TestOverKeepsItsEnds (0.00s)
    sprite_test.go:21: alpha 0 moved the destination: FF6A593D, want FF6B5A3E
    sprite_test.go:24: alpha 255 did not deliver the source: FFE7D79F, want FFE8D8A0
    sprite_test.go:31: alpha 0 mixed FF5A5A5A with itself and got FF595959
FAIL
FAIL	theworld/internal/render	0.002s
FAIL

Every channel of every line is exactly one short. That is a change no screenshot would ever have surfaced, and it would have quietly put a one-unit seam between every sprite and the flat color beside it.