T

prosolis 29eb78a599 Measure the span: the mode survives, and it is an encoder format

FINDINGS 29 priced a literal-span mode at 4*(50 + 4L*9.08) cycles and labelled
the whole section DERIVED. Session 8 step 0 was to measure it before optimising
over the mode set it implies. Two variants in blit.s, one stream per span length
from prep_spans.py, timed by span.lua, driven by span.sh in ~25 s:

  v5, handed (x, npix) and left to work the copy out:  97.9/span + 10.459/px
  v6, handed an address and a jump displacement:       43.7/span +  9.152/px
  29 assumed                                           50.0/span +  9.080/px

So 29's arithmetic was right about a format nobody had written. The difference
is not tuning: v5 spends ~122 cycles a span computing a destination, dividing
npix into bursts and handling a 0..15 remainder, all of which the encoder knows
at build time. v6's record is {u32 absolute GVRAM address, u16 jump
displacement} into an unrolled chain of 24-pixel copy units -- no loop, no
remainder, no arithmetic -- and it fits 11 span lengths to 0.3%.

Three things that measurement showed and derivation could not:

  - The per-pixel cost is a function of REGISTER PRESSURE. FINDINGS 24's 9.08
    was a fixed blit with 12 registers free; v5 can spare 8 and pays 10.46; v6
    gets 12 back only because the encoder holds the state.
  - Short spans die in the remainder path -- a 12-pixel span costs MORE than a
    16-pixel one -- and the fix is padding, not avoidance.
  - Odd-x alignment is free (259.0 vs 261.8 cycles/span), as a 16-bit bus
    implies but nobody had checked.

Re-priced against the unchanged mode maps, sasi: median 74.4% -> 52.0% (29 said
43.0), misses 37 -> 10/120 (29 said 8), 448.0 KB/s. Break-even moved from runs
of 2 blocks to runs of 4. 29.4 survives: a scene cut needs x >= 0.196 of the
frame as spans and the bus allows x <= 0.373, so it fits at 12fps.

All 23 timing configs are also checked pixel-exact, so none of this was timed
against a decoder that quietly skipped work.

FINDINGS 30. Next: lever B, the cost-aware mode decision.

Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6

2026-08-23 15:45:51 -07:00

docs

Measure the span: the mode survives, and it is an encoder format

2026-08-23 15:45:51 -07:00

src/player

The 68000 decoder draws pixel-exact frames, and does not fit

2026-08-23 15:04:38 -07:00

tools

Measure the span: the mode survives, and it is an encoder format

2026-08-23 15:45:51 -07:00

.gitignore

Get a real Dragon's Lair frame onto the emulated X68000

2026-08-23 13:12:27 -07:00

README.md

Measure the span: the mode survives, and it is an encoder format

2026-08-23 15:45:51 -07:00

README.md

Dragon's Lair — Sharp X68000 port

Porting Dragon's Lair to a stock X68000 (68000 @ 10MHz, 2MB, SASI/SCSI).

This is fundamentally a video codec problem, not a game-logic problem: the game logic is a scene table with branching input windows; the difficulty is pushing ~22 minutes of Don Bluth animation through a 10MHz 68000.

Green-light check: ./tools/bench/check.sh (~3 min, needs the Blu-ray mounted) re-runs both display regression tests, the rate-control drift test, the display-path coherency counterexample and a 120-frame 68000 decode, then prints ALL GREEN.

Read first

docs/FINDINGS.md — measured hardware facts, content statistics, codec decision, and a section on measurement traps that produced three separate false results. Read §4 before trusting any pipeline number.
docs/STATUS.md — current state, working setup, blockers, next steps. Start here. It also lists what has been explicitly abandoned, so old ideas do not get re-proposed.
docs/BENCHMARK.md — how to measure the storage subsystem, and why a bandwidth figure out of MAME would be meaningless.
docs/HARDWARE.md — X68000 GVRAM/CRTC reference.

Layout

docs/            findings, status, hardware reference
tools/analysis/  measurement scripts, numbered in the order they were written
                 (01/02 marked BROKEN deliberately, kept as regression refs).
                 Run from the repo root — they import from tools/encoder/.
                 07 finds the hottest sustained window in a stream; 08 renders
                 source | decoded | block-mode map as .webm; 09 is the
                 rate-control drift gate (FINDINGS 26/27) and is part of
                 check.sh -- it exits non-zero if the encoder ever again
                 reports a reconstruction no decoder would produce.
                 10 is a COUNTEREXAMPLE, and exits non-zero by design: it
                 demonstrates that the two-display-path plan of FINDINGS
                 24.5/25.6 corrupts 70 of 120 frames (FINDINGS 28.1).
                 11 scores a container against the MEASURED per-mode block
                 costs without needing MAME; 12 prices the literal-span mode of
                 FINDINGS 30 against those same mode maps, and prints whether a
                 scene cut still fits at 12fps.
tools/bench/     MAME Lua injection harness + 68000 benchmark sources.
                 `check.sh` re-runs both display regression tests (~40 s).
                 `blit.s`/`blit.lua` time the full-frame GVRAM blit on the
                 68000 itself (FINDINGS 24) — not part of check.sh, because
                 wall timings would make the green-light check host-sensitive.
                 `span.sh` (prep_spans.py + span.lua + blit.s v5/v6) measures
                 the literal-span mode the same way (FINDINGS 30, ~25 s); it
                 also asserts all 23 timing configs drew a pixel-exact frame.
                 `crtc_mode.lua` is the single source of truth for CRTC R00-R08
                 and R20 — do not write CRTC values anywhere else.
                 `prep_dlx.py`/`decode.lua`/`verify_decode.py` load, time and
                 verify `src/player/decode.s`; the verify pass is in check.sh.
tools/vasm/      vasm m68k assembler (built from source)
tools/encoder/   hybrid VQ encoder + DLX1 container writer (working).
                 dlx.py is the reference DECODER -- ground truth for the 68000.
src/player/      decode.s: the 68000 DLX1 decoder. Pixel-exact, and 31% of
                 frames over the 12fps CPU budget. See FINDINGS 28.
assets/          extracted frames/audio (gitignored)

Encoder

python3 tools/encoder/extract.py 00020 /tmp/fr 12 crop
python3 tools/encoder/encode.py  /tmp/fr out.dlx --profile sasi --preview p.png

Two quality profiles ship from one codec and one decoder — sasi (110 KB/s) and scsi (280 KB/s) are two points on the same rate-distortion curve. Both are ceilings: lam is bisected per frame under a leaky bucket, so the profile's lam is a quality floor rather than a setting (--fixed-lam opts out). The codec is a Cinepak-style hybrid: each 4x4 block is coded as SKIP, one 4x4 codeword, four 2x2 codewords, or RAW literal pixels, chosen per block by rate-distortion.

The RAW escape means lam=0 is pixel-exact against the palettised frame, so the quality knob spans lossless to heavily-compressed without changing the bitstream.

Profiles are derived from a bandwidth figure, not chosen by eye:

python3 tools/encoder/profile_gen.py --bw-mbps 4 --name scsi

On reading docs/FINDINGS.md: it is append-only and several later sections overturn earlier ones. Superseded sections carry a blockquote at the top pointing to the correction — heed those, especially 18 (reversed by 21).

Source media (DRAGONS_LAIR.iso) and ROMs are gitignored — supply your own.

Not every large stream is game footage. 00216 is the feature with a burned-in commentary picture-in-picture and 00215 is the commentary itself — the two largest files on the disc. The clean 9.4-minute animation is 00223. See FINDINGS 25.1 before running any size-ranked survey.