diff --git a/README.md b/README.md index 4d33504..af8fee8 100644 --- a/README.md +++ b/README.md @@ -2,685 +2,395 @@ Porting Dragon's Lair to a stock X68000 (68000 @ 10MHz, 2MB, 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. +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, and for most +of this project's life that was read as **a video codec problem**. It is not. +Measured on the machine, the codec costs more to *decode* than a literal frame +costs to *not decode*, so the live design has **no decoder in it at all**: the +disc holds packed 8-bit frames and a DMA channel walks them into GVRAM with the +CPU halted. It is a **delivery** problem — bus cycles and bytes off a disc. + +The codec still exists, still works and is **parked** (USER DECISION, session +29). Both branches are described below; the packed one is where the work goes. ## What it looks like -![Blu-ray source next to the 68000's output](docs/img/source-vs-decoded.png) +**The packed player, running off a real volume, with sound.** `src/player/packed.s` +on an emulated stock X68000: the 68000 brings up its own display, builds its own +193-entry DMA chain, keeps its own frame clock off the CRTC's V-DISP, and fetches +every record itself with `READ(10)` from a real MB89352. **There is no decoder in +the machine.** Source on the left; on the right, MAME's own snapshots of what the +68000 put on screen. **120 of 120 frames are pixel-exact against the container**, +every one compared, and the clip refuses to build otherwise. -Left, the Blu-ray frame cropped to 256x192. Right, the same frame **as the -emulated 68000 actually drew it**: 256 colours out of the X68000's 65536, one -16-colour-per-4x4-block codebook, decoded by `src/player/decode.s` from the -container. Not a re-render. These are the pixels MAME had on screen, pulled out -of its own snapshot, 2x nearest-neighbour, no filtering. + -**The player, running.** 119 frames out of a **256 KB ring buffer on an emulated -stock 2 MB X68000**, paced to a 12 fps frame clock, streamed from a host file at -488 KB/s by `src/player/stream.s` with no Lua in the decode path. Source on the -left, the machine's screen on the right. (This recording was paced by the host; -the 68000 now keeps that clock itself, off the CRTC's V-DISP, and the same 120 -frames decode pixel-exact under it — `src/player/clock.i`, FINDINGS 54.) +[`docs/img/packed-player.webm`](docs/img/packed-player.webm) (120 frames, 12 fps, +VP9, with the chip's own audio) - - -[`docs/img/player.webm`](docs/img/player.webm) (119 frames, 12 fps, VP9) - -116 of those 119 frames are **pixel-exact** against `tools/encoder/dlx.py`'s -reference reconstruction. The other three are **torn**: the top of the picture -is frame *n* and the bottom still holds frame *n-1*, because MAME captured the -screen while the block loop was partway down it. That is not a rig artefact. -`decode.s` writes straight to the displayed page, so a real player tears the -same way. `tools/media/make_readme_media.py` asserts the tear rather than -trimming it: every differing pixel has to come from the previous frame, or it -refuses to build. - -**What the decoder is doing.** The same window with the block-mode map beside -it. **Black is SKIP** (costs nothing, draws nothing, the previous frame stands), -**blue is V1** (one codebook index for a whole 4x4 block), **amber is V4** (four -indices), **red is RAW** (sixteen bytes verbatim). The mode mix is what every -cost table in `docs/FINDINGS.md` is really about: V4 costs 1.5x V1, and the mode -decision is charged both bytes *and* cycles, which is why a byte-rich profile -buys its way out to RAW rather than V4. - - - -[`docs/img/modes.webm`](docs/img/modes.webm) (the same 119 frames, with the mode map) - -**Name the layer.** Everything above is **emulated**: MAME 0.277 `x68000`, -`-bios ipl10`, stock 10 MHz / 2 MB, cross-checked frame for frame on a second -CPU core (px68k's C68K). Nothing in this project has run on real hardware yet. - -## Where it stands - -**The binding resource is the 68000's local BUS, not its clock.** The decoder -occupies 86.7% of it once instruction prefetch is counted, and 52 of the 53 -frames that miss the 12fps budget miss on the bus (FINDINGS 38). Read that -before optimising anything for cycles. - -**The decoder works and is measured.** `decode.s` draws blocks and v7 literal -spans pixel-exact under both CPU cores, and costs inside the player what the -standalone blit benchmark said it would, to 0.2% (FINDINGS 41). - -**The delivery path works too.** `stream.s` decodes the whole 120-frame window -out of a 256 KB ring on a stock 2 MB machine, final frame pixel-exact, with the -container in a host file rather than preloaded into RAM. The constraint is -**contiguity, not byte count**: the block loop reads with a monotonically -increasing `a0` and no bounds check, so the ring needs the whole next record -resident *and contiguous*, a condition no byte-counting buffer simulation can -see (FINDINGS 49). - -**Seek slack is accumulated, not owned.** A ring's lookahead is built out of -`pipe - wire` and a seek spends all of it. At 488 KB/s a 256 KB ring needs 4.83 -seconds of play to reach its 7-frame ceiling from empty, and 512 KB needs 8.42 -seconds to reach 14, so a bigger ring raises the ceiling *and* lengthens the -climb. A branch point therefore asks "has there been enough play since the last -one", not "is the buffer big enough" (FINDINGS 51). - -**There is no working delivery rate figure, deliberately.** `--bus`, `--kbps` -and `DLX_STREAM_KBPS` are required arguments with no defaults, so no table can -be scored against a rate its own output does not state. What replaces a constant -is a requirement: `tools/analysis/19_ring_stream.py` reports the **zero-prefill -pipe**, the rate a medium must clear for a container to need no prefill, which -is **513.2 KB/s** for the current candidate. That is a hardware acceptance test -to measure a BlueSCSI against (FINDINGS 50). - -**The largest open number is W, the clocks stolen per delivered byte.** The -MB89352 is an 8-bit SPC, so the DMAC pays per byte rather than per word, which -is a 2x correction the project has already paid for once (FINDINGS 43). What W -costs is set by how the player programs the DMAC: 5 clocks a byte single -address with the bus held, 9 dual address held, 12 single address arbitrating -per byte, 16..19 dual address arbitrating per byte. The design's fate changes -completely across that ladder, and it is ours to choose. - -**The one worked example on the machine is expensive.** The X68000 IPL ROM -programs all four HD63450 channels itself, and -`tools/analysis/21_iplrom_dmac.py` decodes that configuration out of the ROM -image and gates on the bytes still being there. Both the audio channel and the -on-board disk channel are dual address, 8-bit port, cycle steal *without* hold, -one external request per byte: **16..19 clocks a byte**, the top of the ladder. -For audio that is a settled figure and a small one, 1.25%..1.48% of a frame. For -the disk it is where nothing fits at any container size. The ROM drives SASI -rather than the MB89352, so it does not settle W, but a cheap configuration is -now the thing that has to be shown rather than assumed (FINDINGS 52). - -**The player builds its own codebooks and palette now.** The two load-time -transforms — codebooks to word-per-pixel form, palette to `GGGGGRRRRRBBBBBI` -with the shared LSB picked per entry — ran host-side until session 21 and now -run on the 68000, out of the raw container header, byte-exact against the host -implementation on both CPU cores and with the palette read back out of the -hardware registers. A scene change costs **18.96 ms**, a third of one 12fps -frame slot. The finding underneath it is a cost nothing had counted: a scene -header is **5,920 bytes** that must arrive before frame 0, and in the currency -of seek slack those bytes lengthen the refill climb by 138 ms at 488 KB/s and by -**1.099 s at 451.4 KB/s**, because the surplus they are divided by goes to zero -(FINDINGS 53). - -**The 68000 fills its own ring now, and the player's request loop costs more -than the medium does.** `src/player/ring.i` places records, prefills, keeps the -slack rule and seeks, out of a per-record index the container carries (DLX4). -The channel only moves bytes while it has a request and only the CPU can issue -one, so the disc **stands still between records** by an amount the player sets: -at 488 KB/s a one-deep request queue gives away **6.8% of the pipe and underruns -59 of 120 frames**, a two-deep one gives away 3.4% and underruns none — on a -container whose whole surplus over the wire is 8.7% (FINDINGS 55). - -**The player runs off a real disc now, and PIO costs 87 clocks a byte.** -`src/player/xfer.i` answers the ring's request mailbox with a real READ(10) to a -real MB89352 instead of a host moving bytes at a modelled rate: 120 records, -4,488,588 B, **pixel-exact out of a 256 KB ring**, with a real mid-stream seek in -a second pass, and the **same 18 wraps** three different transports have now -produced. What it costs is the finding. Subtracting the same 120 frames run -twice gives **87.28 clocks per delivered byte**, and the 68000's own cycle table -for that loop says **87.15** — 0.2% apart, so the cost is the instruction stream -rather than the emulator's device model, and it is the first number this rig has -produced that a real board would also pay. At this container's mean record that -is **391.8% of a 12 fps frame**; the machine's own V-DISP clock agrees from the -other end at **2.57 fps**. Against the W ladder — 22.4% of a frame at 5 clocks a -byte, 85.3% at 19 — **the CPU doing the work itself is 4.6x the worst DMA -configuration this project has found and 17.5x the best.** Getting the DMAC to -hold the bus is no longer worth 9 against 19; it is worth 87 against either, and -it is the only thing left before a player (FINDINGS 58). - -**The DMAC drives the data phase now, and it holds the bus.** `src/player/dma.i` -programs an HD63450 channel and hands it the SCSI data phase: **the same 2,048 -bytes come off the disc three ways — PIO, the channel with the bus held, the -channel stealing cycles — and all three are byte-exact.** The evidence that the -DMAC and not the CPU is driving it never looks at the data register, which -cannot answer the question: with the DMAC's OWN asserted, MAME cannot tell a -CPU-driven byte at `$EA0015` from a DMAC-driven one. What it looks at instead is -**the CPU's own progress**. MTC is sampled by the instruction *after* the one -that starts the channel; held, it reads **zero of 2,048** — the whole transfer -happened between two instructions, because the 68000 did not execute in between -— while the stealing configuration reads the full count and the CPU then goes -round its own loop 426 times. Put the stealing registers in the held slot and -the run still delivers every byte and the gate goes **red**, which is what says -the counter can come out different (FINDINGS 59.1). - -**And auto-request is charged by time, not by byte.** The card as MAME models it -has **no request line to the DMAC at all** — its flow control is DTACK — so -every configuration that can be run against it is auto-request, and an -auto-requested channel does not know whether the device is ready: it spends its -share of the bus either way. Every `W` in this project is clocks per *delivered* -byte, which presumes the device asks; here the cost scales with **how long the -record takes to arrive**, so halving the delivery rate *doubles* the CPU cost of -the same record. Priced from the MC68450's own limited-rate constants against an -explicit 460 KB/s: max rate costs the whole **95.3% of a frame** the record takes -to land, and of the four bus shares the GCR can be programmed for — 50, 25, -12.5, 6.25% — **only 50% carries the rate**, at 10.61 clocks a byte and 47.6% of -a frame. The GCR is a design lever nothing in this tree had named (FINDINGS -59.3). - -**And what it all costs: the frame affords 6.74 clocks a byte, and a -dual-address byte is 9.** Putting the transport on the channel cuts it from -**391.7% of a 12 fps frame to 40..95%** — four to ten times, the largest -movement in this project's cost model since the decoder was written — and **it -still does not fit.** After the measured decode (68.5%) and the audio DMA -(1.25%), 30.2% of the frame is left, which at this container's 37,403 B record -is 6.74 clocks a byte; a dual-address byte is a 4-clock read of the device plus -a 5-clock write to memory, so **9 is a floor no bus share and no delivery rate -goes under**. Single address is 5 and fits at 92.2% with room to spare — and it -needs the device to ACK the DMAC, which needs a request line MAME does not -connect and the slot pinout does have. So the project's live question is now a -fact about a board: **does a real CZ-6BS1 drive `#EXREQ`?** If it does, the -design fits. If it does not, the container has to come down from 438 KB/s of -payload to **328** — which is an encoder target, entirely inside this project, -and measured against the heaviest container the encoder emits rather than -against a shipping one (FINDINGS 59.7). - -**A record was not a sector, and the fix was a re-encode — it is done.** 117 of -120 records used to start part way into a 512 B block, and reading whole blocks -into the ring corrupts the neighbouring records rather than merely wasting bytes -— the block loop reads with no bounds check. PIO absorbed this for free by -simply not storing the bytes outside the window, a property that disappears the -moment a DMA channel takes over. Priced three ways: windowed PIO is +1.34% on -the wire and cannot be done by a channel at all; a bounce buffer is +1.34% and -**+5 clocks on every delivered byte**, 22.4% of a frame; sector-aligning records -in the container is **+0.43% and zero clocks** (FINDINGS 58.3). Session 27 made -it a precondition rather than a preference — the transport *refuses* a windowed -read when the data phase is the channel's (59.4) — and **session 28 met it: the -container is DLX5, every record is padded to 512 B and the frame stream starts -on a sector boundary. 120 of 120 records are aligned, the realised wire cost is -+0.48%, and the disc now moves exactly the records** — the bytes off the disc -and the bytes into the ring are the same number, which is what check.sh gates on -(FINDINGS 60.1). - -**And the player that has no decoder at all fits the budget the codec misses.** -256-colour GVRAM throws away the high byte of every word a CPU writes, so a -picture byte normally costs two disc bytes — but CRTC R20 bit 11 turns the -masking off, and with the two 256-colour pages scrolled apart one word carries -two pixels (FINDINGS 46/47). Session 29 measured what that is worth. The packed -full-frame blit is **227,553 clocks, 27.3% of a 12 fps frame** — 51% of the -unpacked one, and the *same* as the unpacked path's write-only floor, so packing -buys back the whole of the source read. A DMA channel fills GVRAM in buffer mode -straight off the disc with the CPU halted, and **walks the 1,024-byte line stride -itself** through array chaining, so a frame is one channel start and not 192. At -the 9 clk/B dual-address floor — the only configuration this machine can be shown -to run — **the shipping codec is 110.4% of a frame and a decoder-free packed -player is 55.2%.** Decoding 37,585 bytes costs more than not decoding 49,152. - -What it costs is the wire: **576 KB/s, fixed, with no lever** — a codec's bitrate -is adjustable and a literal frame's is geometry — against 327 KB/s for the codec -at the same floor. So the two open hardware facts changed character: **whether -the medium sustains 576 KB/s, and whether buffer mode blanks the layer while it -is being written, now decide which player exists** rather than how much headroom -one has. The codec cannot take the packing either way: writing 4×4 blocks a byte -at a time is **28% dearer** than the shipping shape, and pairing the blocks 128 -columns apart to get the burst back drops SKIP from 66.3% of blocks to 46.1% of -pairs — about **+60% on the bytes**, against a target that needs them 35% lower -(FINDINGS 61). - -**So encoder work is PARKED (USER DECISION, session 29).** Not because the codec -is wrong, but because its remaining path is a conjunction and the packed one is -not. The codec that exists is 440 KB/s and 110.4% of a frame; reaching E7's -327 KB/s needs a 35% byte reduction after two of its three levers were measured -and found inert (60.4, 60.5), and the reward on success is a design at ~100% of -the frame. The packed player is at 55.2% today. **The codec is kept on disk and -not built on**, because B2 is unanswered and 48.1's prior leans against packing — -if buffer mode blanks, it is the only thing left (48.3). - -**And a frame is now one channel start.** Session 30 asked the packed player's -one open structural question: a frame is a picture *and* a palette, and nothing -had ever pointed a DMA channel at the palette registers. It writes them — -512 B off the disc byte-exact into 256 registers at `$E82000`, read back out of -the registers by the 68000 — and **one array-chained start crosses from those -registers into GVRAM**, which is the shape of a whole frame: a palette entry and -192 row entries, walked by the channel with the CPU halted throughout. The array -is scene-constant, because the packed layout spends both 256-colour pages and -there is no page to flip. What is left on the CPU per frame in the video path is -the channel start and the disc read; there is no per-frame *paint*. **What it -does not settle is the board** — MAME models the palette as plain -`COMBINE_DATA` storage with no handler that could refuse a byte write, so the -run bounds the model and not the hardware, and "does a real palette register -take a byte write" joins the hardware list as B4. A negative answer costs 0.28% -of a frame and nothing else (FINDINGS 62). - -**The packed container exists, and the palette that makes it better than the -codec is not free after all.** `tools/encoder/dlxp.py` is DLXP1 and `pack.py` -writes it: a **49,664 byte record that is 97 sectors exactly**, no record index -and no length word — a packed record's length is geometry, so record *i* is at -`off + i*rec` and a seek is arithmetic — at **582.0 KB/s**, which is what -FINDINGS 61.9 predicted to the tenth, encoded in **3.3 seconds** because there is -no k-means in it. **px68k's own `gvram.c` renders the container's bytes -index-exact with the harness computing no interleave**, which is the only test -that can catch an encoder whose byte order is wrong: a container round-trips -against its own inverse either way. And the picture is re-derived against this -project's own quantiser rather than PIL's — **34.05 dB against 61.9's 34.08** — -with the X68000's `GGGGGRRRRRBBBBBI` word charged for the first time in this -tree, 0.53 dB, on every row, so it moves no comparison. - -**What the control found is the finding.** A packed container built on a *scene* -palette lands **exactly on the codec's ceiling, 30.79 dB**, so the whole +2.31 dB -the packed branch has over that ceiling is **the per-frame palette and nothing -else**. And a per-frame palette is not a small delta: **231 of 256 entries change -every frame**, and a picture under the neighbouring frame's palette is **12.8 dB -worse** than the correct pairing — a wipe on screen for roughly half of every -frame slot, forever, *if* buffer mode does not blank the layer. Correct render, -the same frame under the next frame's palette, and the 24-bit source; the frame -is the one whose mismatch is closest to the mean, so it is not an outlier picked -to make the point: - -![The palette mismatch: correct, mismatched, source](docs/img/palette-mismatch.png) - -It is chroma speckle and a shifted ground rather than a scramble — two -median-cut palettes of adjacent frames occupy a similar gamut — which is milder -than 12.8 dB sounds and worse than a still can show, because a still does not -show it arriving and leaving twelve times a second. So B2 stopped -being a question about headroom and became one about **which packed container -ships**. The fallback is already a flag: `--scene-palette --no-palette` is -30.79 dB, zero churn, **576.0 KB/s**, and still +2.07 dB on the shipping codec as -the display renders both (FINDINGS 63). - -**And the packed player runs, end to end, off the disc — the strongest -result in this tree, next to the worst news in it.** `src/player/packed.s` is -2,898 bytes: the 68000 brings up its own display, builds its own 193-entry DMA -chain, keeps its own frame clock off the CRTC's V-DISP, and fetches every record -itself with `READ(10)` off a real volume. The rig writes **no picture byte, no -palette entry and no CRTC register**. **120 of 120 frames are pixel-exact — every -one compared, in both palette orders** — and the gate had to grow to do it, -because a packed frame is a *literal*: the codec's last frame audits all 120 -through its own recursion, and frame 119 here says nothing about frame 60. +**The clip is a composite of two runs and that is the point.** The picture is the +gate run — paced at half rate so each snapshot lands inside the write window, +cycle stealing, no sound. The sound is the audio run — the same container at +12 fps with the MSM6258 on channel 3, captured by MAME off the speaker, cut at +the first sample the chip produced and gated sample-exact against lump 0 before +anything is written. **What it is not is a real-time capture of the shipping +configuration**, which at this container's own burst rate would show a blank +layer for 99.5% of every slot (FINDINGS 64.2, below). ![Blu-ray source next to the packed player's own screen](docs/img/packed-player.png) -Left, the source. Right, **MAME's own snapshot** of what the 68000 put on -screen with no decoder in the machine at all — the frame whose PSNR is closest -to the mean, so it is not the flattering one. The window's mean is **33.10 dB**, +The still is the frame whose PSNR is closest to the mean over the gated window, +so it is not the flattering one: **33.13 dB against the window's mean of 33.10**, which is the packed container's predicted GRB555 figure to the digit. -**And the write window turns out to be the frame.** Free-running — which is what -a 12 fps player becomes once the transfer is longer than the slot — the run -reported a number no budget here has a column for: **the GVRAM write window was -open on 99.5% of the host frames**. Every frame pixel-exact, and almost none of them visible. It is -arithmetic, not an emulator artefact — a packed write *requires* R20 bit 11, -buffer mode blanks the layer, and a DMAC-direct player holds the window open for -the whole data phase, because the packed layout spends both 256-colour pages and -there is no second page to hide behind: +**Name the layer.** Everything here is **emulated**: MAME 0.277 `x68000`, +`-bios ipl10`, stock 10 MHz / 2 MB, with every 68000 cycle figure cross-checked +on a second CPU core (px68k's C68K) and the display path cross-checked against +px68k's own `gvram.c`. **Nothing in this project has run on real hardware yet.** + +## How the packed player works + +**256-colour GVRAM throws away the high byte of every word a CPU writes**, so a +picture byte normally costs two disc bytes. **CRTC R20 bit 11 turns the masking +off**, and with the two 256-colour pages scrolled apart one word carries two +pixels (FINDINGS 46/47). That makes a frame 1.0 B/pixel — 49,152 bytes — and it +makes the frame a *literal*: no codebook, no recursion, no decode. + +A record is that picture plus its own 256-entry palette: **49,664 bytes, which is +97 sectors exactly**. A packed record's length is geometry, so **the container +carries no index and no length word** — record *i* is at `off + i*rec` and a seek +is arithmetic. A DMA channel fills GVRAM in buffer mode straight off the disc and +**walks the 1,024-byte line stride itself** through array chaining, so a frame is +**one channel start and not 192** — and the chain crosses from the palette +registers at `$E82000` into GVRAM in the same start (FINDINGS 62). The array is +scene-constant, because the packed layout spends both 256-colour pages and there +is no page to flip. + +**Audio rides a fixed cadence, not the record.** The MSM6258 wants 7,812.5 B/s +and 12 fps wants 651.0417 B a slot, a ratio with no arithmetic relationship, so +audio in the record would make records variable-length and bring the index back. +DLXP2 groups instead: **one 14-sector audio lump, then 11 records**, so +`record i = off_frm + i*rec + (i//11)*7168` — six instructions once a frame. The +lump is 7,168 bytes of space and eleven frames of audio is 7,161.4583…, so **the +payload alternates 7,161 and 7,162** and a player that fed the chip whole lumps +runs 0.09% fast: **1.25 s of lip-sync drift over the game's 22.8 minutes**, +predicted, and played at 1.26 (FINDINGS 67.2/68.3). The player carries one +accumulator instead, which is the frame clock's shape for the frame clock's +reason. + +**The wire is fixed and there is no lever on it: 582.0 KB/s of picture + +7.64 KB/s of audio cadence = 589.6 KB/s.** A codec's bitrate is adjustable; a +literal frame's is geometry, and no scene costs less than another. + +| | | +|---|---:| +| record | 49,664 B = 97 sectors | +| wire | **589.6 KB/s** | +| picture, as the display renders it | **33.10 dB** mean over the gate window | +| CPU per frame, video path | one channel start and one `READ(10)` — no paint | +| cost at the 9 clk/B dual-address floor | **54.9% of a 12 fps frame** (FINDINGS 64.2) | +| the codec, at the same floor | 110.4% (FINDINGS 61.4) | + +## Where it stands + +**What runs, end to end, on the emulated machine off a real volume:** + +- **120 of 120 frames pixel-exact**, in both palette orders, every frame compared + rather than the last — a packed frame is a literal, so frame 119 says nothing + about frame 60 (FINDINGS 64.1). +- **All 78,125 B of a container's audio, read back off the speaker**, sample-exact + against the four ADPCM axes carried in the container's own header, one + delivered byte at a time — because a player's counters all stay right through + a bug that overwrites the buffer the channel is reading (FINDINGS 68.1). +- **A mid-stream seek with sound on it**: `pg_aseek` rebuilds the lump index, the + stream position, the remainder accumulator and the byte offset into the group + and issues a second read — **132,162 B of spliced stream accounted for byte by + byte** across a branch deliberately not on a group boundary (FINDINGS 71.1). +- **The scene graph**: 40 scenes, 516 sequences, 906 input windows, imported from + the arcade's own graph into this project's schema (FINDINGS 56). + +**The binding resource is the 68000's local BUS, not its clock**, and every item +above is priced in one of four units: + +| resource | state | +|---|---| +| **68000 local bus** | the binding one. The codec's decoder occupies 86.7% of it, and 52 of the 53 frames that miss the 12 fps budget miss on the bus (FINDINGS 38). | +| **68000 clocks** | measured, on two independent cores. | +| **delivery rate** | **no working figure, deliberately** (FINDINGS 50, USER DECISION). `--bus`, `--kbps` and `DLX_STREAM_KBPS` are required arguments with no defaults, so no table can be scored against a rate its own output does not state. | +| **seek time** | **no figure at all, and never had one.** | +| **W, clocks stolen per delivered byte** | 5 single-address held, 9 dual held, 12 single arbitrated, 16..19 for the IPL ROM's own disk channel. **Still the largest open number.** The CPU doing the transfer itself is **87.28 clocks a byte, measured** — 4.6x the worst DMA configuration found here and 17.5x the best (FINDINGS 58). | + +### The open question that decides which player gets built + +**The write window is the frame.** A packed write *requires* R20 bit 11; buffer +mode blanks the layer while it is set; and a DMAC-direct player holds the window +open for the whole data phase, because there is no second page to hide behind. dark fraction of a slot = record bytes / (DATA-PHASE rate x slot) -**The rate in that expression is the BURST rate, not the sustained one**, and -that is a third hardware number the acceptance test did not have. At the -container's own **582.0 KB/s the dark fraction is 1.0**: every frame delivered, -on time, pixel-exact, and none of them displayed. It also **reverses the -ranking**: a packed player that DMAs into RAM with the window shut and paints -with the measured 27.3% blit is on screen **72.7% of every slot at any rate**, -and the two are equal only at **2,131 KB/s — 3.7x the wire**. Below that, which -is every rate anyone has proposed, the player with the CPU in the loop is the -one you can see (FINDINGS 64.2). +**The rate in that expression is the BURST rate, not the sustained one**, and at +the container's own 582.0 KB/s the dark fraction is **1.0**: every frame +delivered, on time, pixel-exact, and none of them displayed. Free-running, the +run reported exactly that — **the window was open on 99.5% of host frames**. -**And a held channel costs the frame clock half its ticks, without the clock -being able to tell.** `clock.i` counts V-DISP interrupts; a held channel halts -the 68000; the MFP's pending bit is one bit. Held at 12 fps, **487 of 1,038 -edges are lost** — and the player reports **zero late frames**, because the tick -it grades itself against is advanced by the interrupt the channel stopped it -from taking. It believed it was at 12 fps; the screen was at **6.37**. Only the -host's raster count contradicts it, and the gate asserts on the difference -(FINDINGS 64.3). +It **reverses the ranking** in clocks, so there are two packed players and the +difference between them is *when* the window is open: -**And the sound has an encoder, whose most useful output so far is a warning.** -The X68000's audio is an OKI MSM6258 — 4 bits a sample, 15,625 of them a second, -7,812.5 bytes a second exactly. `tools/encoder/adpcm.py` encodes the same ten -seconds the frames come from: **78,125 B at 21.97 dB**. There is no reference -encoder to check it against — ffmpeg has a decoder for this format and no encoder -— so what is gated is the decoder the encoder runs *inside its own nibble -search*, sample-exact against ffmpeg's over 4,268 nibbles. An encoder that agrees -with its own wrong decoder is what that catches. +| | clocks (W=9) | on screen | RAM | +|---|---:|---:|---:| +| **A — DMAC-direct** (built, FINDINGS 64) | **54.9%** of a slot | 0% at the container's wire, 72.7% only at 2,131 KB/s | none | +| **B — DMA to RAM + CPU paint** (K4, not built) | 82.2% | **72.7% at any rate** | 99,328 B | -**And the two published versions of this codec are not the same codec.** ffmpeg -computes a nibble's contribution as `((2*(n&7)+1) * step) >> 3`; the OKI -datasheet truncates per term. They differ by **at most 3 in 12-bit units**. -Encode for one and decode on the other and the signal-to-noise ratio goes from -**21.97 dB to −2.88 dB — the noise comes out louder than the signal**, because -ADPCM is recursive and a rounding difference does not stay where it happens. So -which one the chip runs is not a footnote; it is a precondition on shipping any -audio at all, and MAME's x68000 has the chip to ask (FINDINGS 65). +B's paint is **measured**: the packed `movem` blit is 227,553 clocks, 27.3% of a +slot, independent of the medium. They are equally visible only at **3.7x the +wire**. So B2 — *does buffer mode blank the display?* — is not a headroom +question any more; it decides which player exists, and **K4 is not being built +until it is answered** (FINDINGS 64.2, ROADMAP K4). -**So the chip was asked, and the encoder was wrong on four things rather than -one.** 68000 code programs the machine's own ADPCM DMA channel exactly as the -IPL ROM programs it — the register bytes are decoded out of the ROM image, not -recalled — and feeds the chip a designed 1,678-nibble stream at the chip's own -pace, 7,811.4 bytes a second against the format's 7,812.5. Sixteen candidate -decoder models are then fitted to what MAME captured, and **exactly one -reproduces it sample-exact over all 1,678 samples**, with a negative control on -every axis: flip one and the match dies. The chip runs the datasheet's -truncation, takes the **low** nibble of a byte first, clamps its accumulator at -**10 bits**, and starts it at **−2**. `adpcm.py` defaulted to the opposite of -all four. +### Other things the machine has said, that a player has to carry -And the expensive one is not the one the paragraph above worried about. Getting -the delta formula wrong costs −2.88 dB; getting the **nibble order** wrong costs -**−25.74 dB**. The earlier "high nibble first, measured" was a real measurement -of *ffmpeg*, i.e. of the Dialogic VOX **file** convention — a different question -from what a chip does with a byte written to its data register, with a different -answer. The 10-bit clamp costs nothing on this window and only because the -window peaks at **435 of 511**: it is a −13.4 dBFS passage with 1.4 dB of -headroom, where the encoder had been clamping 12.1 dB higher. So the audio -**level** became an open choice again, downward, with the loudest passage on the -disc unmeasured (FINDINGS 66) — session 37 measured it, and the answer was to -leave the level alone. +**A held channel costs the frame clock half its ticks, without the clock being +able to tell.** `clock.i` counts V-DISP interrupts; a held channel halts the +68000; the MFP's pending bit is one bit. Held at 12 fps, **487 of 1,038 edges are +lost** and the player reports **zero late frames**, because the tick it grades +itself against is advanced by the interrupt the channel stopped it from taking. +It believed it was at 12 fps; the screen was at **6.37** (FINDINGS 64.3). -**Name the layer**: that is MAME's device model, measured end to end through the -machine's real transport. It settles the rig — an emulated audio test encoded -against the wrong model is 25 dB of nothing — and it does not settle the -silicon. +**Held, the bus costs the audio 463 times the seam.** The MSM6258 has no +starvation state — it goes on decoding nibbles out of whatever byte its data +register still holds — so the interval between a channel counting out and the CPU +arming the next lump is a held nibble pair driving the predictor. Stealing, that +seam is **0.51 ms over ten seconds**, because the audio service runs from inside +`dma.i`'s transfer wait. Held, it is **236 ms, 2.31% of the audio**, with every +byte still correct (FINDINGS 68.2). -**And audio is what the packed container's best property finally costs -something for.** A packed record is 97 sectors and its address is arithmetic — -no index, and none can be needed. Audio is 651.0417 bytes a frame slot, a rate -with no arithmetic relationship to 12 fps, so it cannot ride the record without -making records variable length and bringing an index back. It rides a fixed -cadence instead — every 11 frames, 14 sectors — which wastes **0.09%**, where -the obvious one-lump-per-record cadence wastes **57.3%** of every audio sector. -The wire goes **582.0 → 589.6 KB/s**. The codec container, which already has the -index the packed one deleted, pays **zero**. +**The chip is not the datasheet and not ffmpeg, and it was asked.** Sixteen +candidate decoder models were fitted to what the emulated MSM6258 produced from a +designed nibble stream; **exactly one reproduces it sample-exact**, with a +negative control on every axis. The chip runs the datasheet's truncation, takes +the **low** nibble first, clamps its accumulator at **10 bits** and starts it at +**−2**. Getting the delta formula wrong costs −2.88 dB; **getting the nibble order +wrong costs −25.74 dB** (FINDINGS 66). The four axes ride in the container header +as fields rather than a version number. -**And the packed container has sound in it now — its padding turned out to be -drift.** DLXP2 is a 64-byte header and then *groups*: one audio lump of 14 -sectors, then 11 records, so `record i = off_frm + i*rec + (i//11)*7,168`. **Still -no index and still none needed** — the packed branch's whole claim survives the -one change that could have ended it — and on the 68000 the third term is **six -instructions once a frame** and zero parsing, because the cadence is two numbers -in the header rather than a table in the stream. `src/player/packed.s` fetches -records out of the interleaved container off a real MB89352 volume and **120 of -120 are still pixel-exact**, against a **silent control** built from the same -frames that says no picture byte moved. +**The audio level is measured off the whole disc and does not change.** All 201 +streams that have audio, 21.5 minutes: the **disc peaks at 946 of 2048, 5.35 dB +over the chip's clamp**, in 402 events totalling 44.0 ms. Forty windows encoded at +six gains price the choice, and the disc's own level has the **best mean SNR +(22.03 dB)** — the gain that guarantees zero clamping costs 0.85 dB across the +game to buy back 1.90 dB on the 2.11 seconds that clamp, because the OKI step +table's floor is a constant and does not scale (FINDINGS 69). -The finding is what 65.3 called padding. A lump is **7,168 bytes of space** and -eleven frames of audio is **7,161.4583… bytes**, so the *payload* alternates -7,161 and 7,162 and the rest is zero. A player that fed the chip the whole lump -— which is what "14 sectors every 11 frames" invites — runs **0.09% fast**, and -that is not waste, it is **drift: 1.25 seconds of lip-sync over the game's 22.8 -minutes**. What a player carries is one accumulator, `acc += 11*15625; -n = acc//24; acc %= 24`, which is the frame clock's shape for the frame clock's -reason. **Third time this tree has met a ratio with a remainder**, and the rule -it keeps writing is that rounding one *once* is an error and rounding it *every -period* is a rate. +**The predictor does not seek.** The MSM6258's accumulator is a pure integrator +with no leakage term, so a branch that hands the chip bytes chosen for a state it +is not in produces **a DC offset that does not decay**: playing through, −355 of +511 with AC 0.00, still −108 four seconds later; stopping and re-PLAYing, a single +permanent constant of −65. **A re-PLAY is 5.5x better and neither is zero.** The +only fix that reaches zero is the encoder's — reset the predictor where a branch +can land — and it costs **0.33 dB** (21.99 → 21.66) because the step table +re-converges in a few samples (FINDINGS 71). -The four ADPCM axes ride in the header as fields rather than a version number, -and the gate flips each one to show they earn it: **nibble order −31.99 dB, -delta formula −24.86, clamp 0.00, accumulator −0.49**. Nothing parses a packed -container, so the gate **partitions the whole file** — 131 spans, no overlap, no -gap — and asserts what a cadence-blind player would read: exactly records -11..119 wrong, **and frames 0..10 identical either way**, which is how an -off-by-one like that survives a rig that checks frame 0. The wire is **582.0 + -7.64 = 589.6 KB/s**, which is 65.3's prediction to the tenth (FINDINGS 67). +**Branch points do not wait for the buffer.** 5.4% of the game's 612 branch +transitions open an input window on the first frame of a clip the disc *seeked +to*, so two seeks can fall back to back with no play between them. On the packed +branch there is **no refill climb at all** — a record goes straight into GVRAM and +the video lookahead is zero records — so the only consumer with any lookahead is +the audio one: **1.833 s of sound held against 0.000 s of picture** (FINDINGS +56/70.2). And a DLXP2 group puts its lump *in front* of its records, so a seek +lands with its audio behind it: **mean 416.5 ms of silence entering a branch** +over the arcade's 409 within-container targets, which is what `pg_aseek`'s second +read removes for 11.7 ms (FINDINGS 70.3). -**And the container has been heard — held, the bus costs the audio 463 times -the seam.** All **78,125 B** of a DLXP2's audio reached the MSM6258 in order, -sample-exact against the four axes in the container's own header, out of a -player fetching records off the same disc at the same time: two DMA channels at -once, and the interaction is not in the bytes but in the timing. The chip has -**no starvation state** — it goes on decoding nibbles out of whatever byte its -data register still holds — so the interval between a channel counting out and -the CPU arming the next lump is a **held nibble pair driving the predictor**. -Stealing, that seam is **0.51 ms over ten seconds**, because `dma.i`'s hook -services the chip from inside the transfer wait (250,000 of 250,240 looks). -Held, the 68000 is halted and gets 369 looks: **every** lump boundary has a -seam, worst **72.8 ms**, **236 ms total = 2.31% of the audio** — a buzz once a -second, with every byte still correct. 67.2's drift was predicted at 1.25 s over -the game and played at **1.26** (FINDINGS 68). +### The parked branch: the codec -**And the audio level is measured now, off the whole disc — the headroom is not -worth buying.** The chip clamps its accumulator at **10 bits inside the -recursion**, and the ten seconds every audio figure here is quoted on peak at -435 of 511, which fits *by accident*: it is a −13.4 dBFS passage. Measured -against the game's own footage instead — all 201 streams that have audio, -21.5 minutes, through the same extract chain — the **disc peaks at 946 of 2048, -−6.71 dBFS, 5.35 dB over the clamp**, and the census behind that peak is **687 -samples of 20.2 million: 402 events, 44.0 ms, longest 0.90 ms**. Forty windows -drawn over the game and encoded at six gains then price the choice, and it is -not close: the disc's own level has the **best mean SNR (22.03 dB)** and the -gain that guarantees zero clamping costs **0.85 dB across the whole game** to -buy back **1.90 dB on the 2.11 seconds that clamp**, because the OKI step -table's floor is a constant and does not scale with the signal. **So the level -does not change** — `--audio-gain` exists so it is a parameter with a -measurement behind it rather than a shift nobody chose. +The codec is a Cinepak-style hybrid — each 4x4 block coded as SKIP, one 4x4 +codeword, four 2x2 codewords, or RAW literal pixels, chosen per block by +rate-distortion, with a v7 literal-span mode over the top. It works, it is +measured, and it is **pixel-exact on the 68000 under two independent CPU cores**; +`stream.s` decodes a 120-frame window out of a 256 KB ring on a stock 2 MB +machine with the container in a file rather than in RAM. -And 66.3's *mechanism* — that a clamp is a wrong state the next nibble is -applied to — does not survive a control. Error after a clamp run is elevated -about 5x; so is the same window at a gain that never clamps, read at the same -indices, because those samples are simply loud. Worst ratio **1.28**, and the -clamped encode's whole-window mean error is the **lower** of the two. The reason -is that `adpcm.encode` runs the chip's clamp inside its own sixteen-way search, -so it never loses the chip's state. The worry was right about the mechanism and -aimed one layer too late: an encoder clamping at 12 bits while the chip clamps -at 10 is exactly that divergence, and session 34 had already closed it -(FINDINGS 69). + -**The scene graph is in, and the worst gap between two decision points is -zero.** `tools/import/scenegraph.py` imports the arcade scene graph — 40 scenes, -516 sequences, 906 input windows — and 5.4% of the game's 612 branch transitions -open an input window on the first frame of a clip the disc *seeked to*, so two -seeks can fall back to back with no play between them. A rule of the form "has -there been enough play since the last branch" can therefore be answered no by -the **content**, not by the buffer. It does not break the design: a branch on an -empty ring costs the 2-record prefill, **149.7 ms at 488 KB/s**, not the climb. -What it removes is margin — at that rate in a 256 KB ring, **76% of this game's -branch points arrive before the ring has refilled**, and a 512 KB ring makes it -90%, because doubling the ceiling does not touch `pipe - wire` (FINDINGS 56). +[`docs/img/player.webm`](docs/img/player.webm) — the codec player, 119 frames, +12 fps. 116 are pixel-exact against the reference decoder; **three are torn**, +frame *n* on top of frame *n-1*, because MAME captured the screen while the block +loop was partway down it. `decode.s` writes straight to the displayed page, so a +real player tears the same way, and the media builder **asserts the tear** rather +than trimming it. [`docs/img/modes.webm`](docs/img/modes.webm) is the same window +with the block-mode map beside it — black SKIP, blue V1, amber V4, red RAW — +which is what every cost table in FINDINGS is really about. -**And with the second stream on the wire, that climb is a different number.** -Slack accrues out of `pipe − wire`, which is a small difference of two large -numbers, so a second consumer is **not** priced by its share of the wire. -7.63 KB/s of audio is **1.7% of the codec container's wire and up to 3.30x of -its climb**: at 451.4 KB/s — the rate at which the *silent* container is exactly -deliverable — the climb goes **6.70 s → 22.11 s** and the branch points arriving -under it go **79% → 99%** of the game. On the packed branch there is **no climb -at all**, because a record goes straight into GVRAM and the video lookahead is -zero records; the only consumer there with any lookahead is the audio one, -**1.833 s of sound held against 0.000 s of picture**. And at **589.6 KB/s**, the -acceptance figure this project quotes, the sounded packed container's surplus is -exactly **zero** — it plays and never banks a byte, which is why B1 has to name -a burst rate and not only a sustained one. +**Why it is parked.** At the 9 clk/B dual-address floor the codec is **110.4% of a +12 fps frame and the decoder-free packed player is 54.9%**: decoding 37,585 bytes +costs more than not decoding 49,152. Reaching a fitting rate needs a 35% byte +reduction after two of its three levers were measured and found inert, and the +reward on success is a design at ~100% of the frame. **It is kept on disk and not +built on** — if B2 comes back "buffer mode blanks", it is the only thing left +(FINDINGS 61.8, 48.3). -**A DLXP2 group is `lump k, then F records`, so a seek finds its audio behind -it.** Read forward from record *i* and the next lump carries frame *(k+1)F*, so -the frames in between have picture and no sound. On the **409 within-container -seek targets of the arcade's own graph** at the shipped cadence F=11 that is a -**mean 416.5 ms of silence entering a branch, worst 833.3 ms, and 36 of 409 -free**; the other 203 branch points — the scene changes — are free by -construction, because lump 0 sits between the header and record 0. **The -container's own start is the one branch point the cadence costs nothing at, and -it was the only one anybody had looked at.** The fix is one extra read of -7,168 B — **11.7 ms against 416, and no player here has an audio seek path** — -and the alternative is the cadence 32 called the worst one, F=1, which has no -group to enter off-boundary and gives back **12,288 B of RAM for +4.36 KB/s of -wire**. The deciding number is what one more SCSI command costs, and that is -hardware's (FINDINGS 70). +## What is open -**The player seeks with sound on it now — and the chip's predictor does not seek -with it.** `pg_aseek` rebuilds the four numbers a branch needs — the lump index, -the stream position, the remainder accumulator and the byte offset into the -group — and issues the second read: **132,162 B of spliced stream accounted for -byte by byte in MAME's own capture**, across a branch at frame 37 that is four -frames into lump 3 and so deliberately *not* on a group boundary. 70.3's silence -is gone, and what is left is smaller and is not a player problem. **The -MSM6258's accumulator is a pure integrator with no leakage term**, so a branch -that hands the chip bytes chosen for a state it is not in produces **a DC offset -that does not decay**: playing through, **−355 of 511 with AC 0.00** — the right -shape from the wrong ground — and still **−108 four seconds later**. Stop and -re-PLAY the chip and all 62,500 post-seek samples are *exactly* a decode from the -container's own start state, with the whole error a **single permanent constant, -−65**. A re-PLAY is **5.5x better and neither is zero**. +**Hardware — this list is the user's, and nothing here can be settled by an +emulator.** -**The only fix that reaches zero is the encoder's, and it costs 0.33 dB.** A -player cannot set the chip's accumulator, only reset it — so a branch is free -only if the stream was *encoded* with the predictor reset where the branch -lands. Resetting every frame makes all 119 of the container's branch points -exact for **21.99 → 21.66 dB**, because the OKI step table's floor is a constant -16 and the recursion re-converges in a few samples. Across the container's frame -boundaries the offset a re-PLAY costs averages **55.4 of 511 (10.8%)** and -reaches **313**, and the host's arithmetic for the machine's own branch point -agrees with the capture **to the digit**. The seek also turned up a race that -had passed this gate three times: `pg_ainit` waited on a *read-back* MTC before -telling the chip to PLAY, which can start the scene **one byte in, forever**, -with every counter in the player exact — found by locating the capture's opening -samples in the container image (FINDINGS 71). +- **B1. Measure the medium.** Three thresholds, not one: **sustained ≥ 589.6 KB/s** + or frames arrive late; **the data-phase BURST rate**, which decides how much of + the slot the picture is on screen; and **seek time**, which has no figure at + all. Plus what one extra SCSI command costs, which decides the audio cadence. + The 0.7–1.7 MB/s usually quoted for BlueSCSI on an X68000 is **folklore with no + published benchmark behind it**. +- **B2. Does buffer mode blank the display?** `probe_bit11_blank.lua` is written + and settles it in minutes on a real board. It decides A vs B above. +- **B3. Does a real CZ-6BS1 drive `#EXREQ`?** MAME's card has no request line to + the DMAC at all, so every configuration that can be run against it is + auto-requested and **charged by time rather than by byte**. A real request line + is what single-address 5 clk/B needs. +- **B4. Does a real palette register take a byte write?** A negative answer costs + 0.28% of a frame and nothing else. +- **The MSM6258V, on silicon**: the four axes; whether it resets accumulator, step + index and nibble select on PLAY only when it was not already playing; and + whether it goes on asserting `#DRQ` while STOPped. -**Nothing outside-derived is committed here.** The scene graph is not -redistributable from this tree; it is regenerated from a reader's own clones -into gitignored `tmp/`, and `tools/import/scenegraph.py` is the single file in -the repo coupled to those projects — everything downstream reads `DLXSCENE1`, -this project's own schema, with the sources' attribution carried in it. -DirkSimple is zlib (Ryan C. Gordon); the SNES chapter set is MIT (Chad -Doebelin) and, by its own README, *derived* from DirkSimple rather than an -independent transcription, which struck a cross-check this project had planned -on for eight sessions. +**Software, in order.** -**Current encode:** 496.7 KB/s at 29.19 dB, 1 frame of 120 over the 12fps -budget, and that one is frame 0, the intra frame, late on purpose. +1. **The predictor-reset container (DLXP3).** The cheapest thing that takes a + measured cost to zero rather than down. The player half already exists + (`PG_ARST`). +2. **The audio buffering depth.** `PG_ANBUF` is 3; two slots is one constant and + one run. The audio buffer is the packed branch's *only* buffer. +3. **The silent-clip and short-audio cases**: a scene whose audio is shorter than + its frames, and a scene with no audio track at all. +4. **The cadence pick.** With a working seek path the silence F=11 costs is zero, + so the trade is padding against RAM — plus one SCSI command per branch, which + is B1's. -**Green-light check:** `./tools/bench/check.sh` (~6 min, needs the Blu-ray -mounted) re-runs both display regression tests, the rate-control drift gate, the -display-path coherency counterexample, a 120-frame 68000 decode on two CPU -cores, the ring and paced-ring passes, the DMAC configuration gate and the -load-time transforms on both cores, then imports and gates the scene graph -when a DirkSimple checkout is present, then builds the packed container -- -with audio in it, and a silent control beside it -- and renders it through -px68k's own GVRAM model, then **runs the packed player for 120 frames off a real -volume and compares every one of them**, then encodes the same window's audio -and gates it against ffmpeg's decoder, then asks the emulated MSM6258 which of -sixteen decoders it is, then gates the DLXP2 container and every one of its -axes, then measures the audio level off every stream of the game's own footage -and gates the disc's peak against the chip's clamp, then runs the refill climb -against the arcade's own 612 branch points with the second stream on the wire, -then prints `ALL GREEN`. +**Parked, so it is not re-proposed:** the codec's remaining encoder work (E7, E4, +C1); `ring.i`, `xfer.i` and most of `stream.s`, which left the video path when a +DMAC-direct player deleted the ring, and P4a's wiring with them. **K4 is blocked +on B2**, not parked. ## Reproducing this -**No media ships in this repo and none of it is redistributable.** Bring your -own Dragon's Lair Blu-ray. Everything else needed to rebuild every number and -every picture above is either here or is packaged. - -You need: +**No media ships in this repo and none of it is redistributable.** Bring your own +Dragon's Lair Blu-ray. Everything else needed to rebuild every number and every +picture above is either here or is packaged. | | | |---|---| -| the disc | loop-mounted read-only: `udisksctl loop-setup -r -f DRAGONS_LAIR.iso`. The tree was built against a decrypted UDF 2.x image. 7-Zip cannot read UDF 2.x, so use the loop mount | +| the disc | loop-mounted read-only: `udisksctl loop-setup -r -f DRAGONS_LAIR.iso`. Built against a decrypted UDF 2.x image; 7-Zip cannot read UDF 2.x, so use the loop mount | | `python3` | plus **numpy** and **Pillow**, and nothing else. The k-means is hand-rolled rather than pulling in sklearn | | `ffmpeg` / `ffprobe` | frame extraction, and the clips above | | **MAME** | tested on 0.277, with the `x68000` ROM set. The rigs drive it headless via `-autoboot_script` | | vasm (m68k, Motorola syntax) | **vendored**: `tools/vasm/vasmm68k_mot` is a Linux x86-64 binary, with the source tarball beside it to rebuild elsewhere | -Then: - ```sh export DLX_BDROM=/path/to/your/mounted/bluray # if not /media/$USER/BDROM -./tools/bench/check.sh # ~3 min, prints ALL GREEN +./tools/bench/check.sh # the green light, prints ALL GREEN ``` -`DLX_BDROM` is honoured by every tool that reads the disc. Two stages are -optional and **skip rather than fail** when their input is absent, because both -live outside this repo: +`check.sh` re-runs everything above that a host can re-run: both display +regression tests, the rate-control drift gate, the display-path coherency +counterexample, a 120-frame 68000 decode on two CPU cores, the ring and paced-ring +passes, the DMAC configuration gate, the load-time transforms on both cores, the +scene-graph import when a DirkSimple checkout is present, the packed container +(with audio, and a silent control beside it) rendered through px68k's own GVRAM +model, **the packed player for 120 frames off a real volume with every frame +compared**, the audio encoder against ffmpeg's decoder, the sixteen-way decoder +identification against the emulated chip, the DLXP2 container and each of its four +axes with a negative control on each, the audio level off every stream of the +game's own footage, and the refill climb against the arcade's own 612 branch +points. `DLX_BDROM` is honoured by every tool that reads the disc. -- `PX68K=/path/to/px68k` for the second-CPU-core gate. This is the cheapest - strong test in the tree (seconds, no MAME, no ROMs) and it is what licenses - the bus and cycle figures. -- `IPLROM=/path/to/iplrom.dat` for the DMAC configuration gate. Defaults to - `~/mame/roms/iplrom.dat`. +Two stages **skip rather than fail** when their input is absent, because both live +outside this repo: `PX68K=/path/to/px68k` for the second-CPU-core gate — the +cheapest strong test in the tree, and what licenses the bus and cycle figures — +and `IPLROM=/path/to/iplrom.dat` for the DMAC configuration gate. -To rebuild the stills and clips in `docs/img/` you also need a paced recording -run; see the header of `tools/media/make_readme_media.py`. +The player runs and the media are rebuilt from them: + +```sh +bash tools/bench/packed_run.sh # the packed player, 7 runs +python3 tools/media/make_packed_media.py # docs/img/packed-player.{png,webm} +python3 tools/media/make_readme_media.py # the parked codec's stills and clips +``` + +Both media builders **gate before they write**: a still or a clip of the player is +a claim that the player drew it, so every frame is checked pixel-exact against the +container first and the audio cut is checked sample-exact against lump 0. A README +that illustrated a pixel-exact player with an approximate picture would be a small +lie about the one property this project keeps testing. **Scene selection is a hard-coded stream number, not a search.** The gates use -streams `00020` and `00223` of the disc's 224 `.m2ts` files. A different -pressing may number them differently, and if so the green light will extract the -wrong footage rather than fail, so check that `tmp/fr_singe/` looks like the -Singe encounter before trusting any figure. +streams `00020` and `00223` of the disc's 224 `.m2ts` files. A different pressing +may number them differently, and if so the green light will extract the wrong +footage rather than fail, so check that `tmp/fr_singe/` looks like the Singe +encounter before trusting any figure. **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`** (FINDINGS 25.1). -**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`** -(FINDINGS 25.1). +**Nothing outside-derived is committed here.** The scene graph is regenerated from +a reader's own clones into gitignored `tmp/`, and `tools/import/scenegraph.py` is +the single file in the repo coupled to those projects — everything downstream reads +`DLXSCENE1`, this project's own schema, with the sources' attribution carried in +it. DirkSimple is zlib (Ryan C. Gordon); the SNES chapter set is MIT (Chad +Doebelin) and, by its own README, *derived* from DirkSimple rather than an +independent transcription. -## Encoder +## Encoders -``` -python3 tools/encoder/extract.py 00020 /tmp/fr 12 crop -python3 tools/encoder/encode.py /tmp/fr out.dlx --profile scsi --preview p.png +**The live one is the packed container**, and it has no rate control in it because +there is no rate lever: + +```sh +# the gate window: stream 00223, 10.0 s from 539.4 s, the same seconds both times +python3 tools/encoder/extract.py 00223 tmp/fr_singe 12 crop 539.4 10.0 +python3 tools/encoder/extract_audio.py 00223 tmp/au_singe.raw 15625 539.4 10.0 +python3 tools/encoder/pack.py tmp/fr_singe out.dlxp --audio tmp/au_singe.raw ``` -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. +`dlxp.py` is the format and the one place the interleave, the 97-sector record, +the audio cadence and the lump payload are stated. It encodes in ~3 seconds +because there is no k-means in it. `--scene-palette --no-palette` is the fallback +container: **30.79 dB, zero palette churn, 576.0 KB/s**, still ahead of the codec +as the display renders both, and it is what ships if B2 says the layer blanks — +because a per-frame palette changes **231 of 256 entries every frame**, and a +picture under the neighbouring frame's palette is **12.8 dB worse** +([`docs/img/palette-mismatch.png`](docs/img/palette-mismatch.png)). -**Two byte budgets, not one.** `--kbps` is the quality rate point and -`--span-kbps` is the ceiling the span pass may draw on. They are different -things: the profile is chosen, the pipe is hardware, and bytes between them buy -a better picture if spent on `lam`, the 68000's deadline if spent on spans, and -nothing if left unspent. Spans run before `mu` because a span pays in bytes and -`mu` pays in picture (FINDINGS 41.2). +`adpcm.py` is the MSM6258 codec and it carries **two decoders on purpose**: the +module defaults are ffmpeg's, so `tools/bench/verify_adpcm.py` stays a check +against an independent implementation, and `adpcm.CHIP` is the set measured out of +the machine's own chip. Anything that encodes *for* the machine passes `CHIP` +explicitly. -**Two ceilings, on two different axes.** The second is the 68000's decode -budget: `mu` is bisected per frame against 833,333 cycles so the frame also -*decodes* in time, which takes the worst sustained window from 37 frames over -budget to 1, for 0.62 dB at `scsi` (FINDINGS 31). It is on by default and -`--no-cpu-fit` turns it off. Unlike bytes, cycles have no bucket: there is no -double buffer to decode ahead into, so it is a hard per-frame ceiling. - -**One profile, `scsi`, at 280 KB/s.** The 110 KB/s `sasi` profile was dropped on -capacity rather than bandwidth, since a SASI volume is limited to 40 MB and the -game's 22.8 minutes is 146 MiB even at that rate (FINDINGS 32). The rate point -may return under another name once the delivery medium is settled, because a 1x -CD-ROM sustains ~150 KB/s and CD-ROM is the only period medium with the -capacity. - -The profile bitrate is a **ceiling**: `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). At `--spans all` none of that binds, though. A -32-frame bucket emits the same container byte for byte as an 8-frame one and -`lam` never leaves its floor on any frame of the reference window, because the -rate is set by the span pass and by `mu` (FINDINGS 44.3). Two known unit -inconsistencies on that side are implemented and default off because they -measure as a wash: `--joint-decide` prices a byte at `lam + mu*c` rather than -`lam`, and `--joint-bucket` stops the bucket lending clocks it cannot repay. - -An encode is ~95% k-means. A 120-frame window is ~29 s, of which ~22 s is -training the two codebooks. - -Profiles are derived from a bandwidth figure rather than chosen by eye: +**The parked codec's encoder is kept and still runs:** +```sh +python3 tools/encoder/encode.py tmp/fr_singe out.dlx --profile scsi --preview p.png ``` -python3 tools/encoder/profile_gen.py --bw-mbps 4 --name scsi -``` + +`--kbps` is the quality rate point and `--span-kbps` the ceiling the span pass may +draw on; `mu` is bisected per frame against the 68000's own decode budget so a +frame also *decodes* in time. One profile, `scsi`; the 110 KB/s `sasi` profile was +dropped on capacity rather than bandwidth. The RAW escape means `lam=0` is +pixel-exact against the palettised frame. See FINDINGS 31/41/44 before changing +any of it. ## Documentation - **`docs/STATUS.md`** is the current state, working setup, blockers and next - steps. **Start here.** It also lists what has been explicitly abandoned, so - old ideas do not get re-proposed. -- **`docs/ROADMAP.md`** is the remaining work to a completion target, and which - milestone that target is. Read it with STATUS rather than instead of it: - STATUS holds the measurements, ROADMAP holds the shape and goes stale first. -- **`docs/FINDINGS.md`** is measured hardware facts, content statistics, the - codec decision, and a section on measurement traps that produced three - separate false results. Read §4 before trusting any pipeline number. It is - append-only and later sections overturn earlier ones; superseded sections - carry a blockquote pointing at the correction. + steps, newest session first. **Start here.** It also lists what has been + explicitly abandoned, so old ideas do not get re-proposed. +- **`docs/ROADMAP.md`** is the remaining work to a completion target. Read it with + STATUS rather than instead of it: STATUS holds the measurements, ROADMAP holds + the shape and goes stale first. +- **`docs/FINDINGS.md`** is measured hardware facts, content statistics, the codec + decision, and a section on measurement traps that produced three separate false + results. Read §4 before trusting any pipeline number. It is append-only and + later sections overturn earlier ones; superseded sections carry a blockquote + pointing at the correction. - **`docs/BENCHMARK.md`** is how to measure the storage subsystem, and why a bandwidth figure out of MAME would be meaningless. - **`docs/HARDWARE.md`** is the X68000 GVRAM/CRTC reference. @@ -688,184 +398,76 @@ python3 tools/encoder/profile_gen.py --bw-mbps 4 --name scsi ## Layout ``` -docs/ findings, status, roadmap, hardware reference -docs/img/ the stills and clips above, built from a real emulated run +src/player/ packed.s THE LIVE PLAYER: display bring-up, the 193-entry DMA + chain, its own V-DISP clock, READ(10) off a real + volume, and the MSM6258 on channel 3 -- a lump ring, + the remainder accumulator that stops the padding + becoming drift, a service routine that runs from + INSIDE dma.i's transfer wait (0.51 ms of seam + against 236), and pg_aseek. + dma.i the HD63450 channel: array chaining, held and + stealing, and DM_HOOK. + scsi.i the MB89352: selection, READ(10), the data phase. + adpcm.i the audio transport, every register byte of it + decoded out of the IPL ROM rather than recalled. + clock.i the frame clock, off the CRTC's V-DISP. + geom.i the constants, in one place. + decode.s the parked codec's 68000 decoder (1,296 bytes, + stream.s asserted), the same decoder behind a bounded ring, + ring.i the ring producer, the transport under it, and the + xfer.i load-time codebook/palette transforms. OUT OF THE + load.i VIDEO PATH since the packed player deleted the ring. + frame.i the block loop and span chain, included by both, so + there is exactly ONE copy of the bytes every cycle + constant is fitted to. The span pass is blit.s v7 + verbatim -- do not tidy it. +tools/encoder/ dlxp.py THE LIVE CONTAINER (DLXP2) and pack.py writes it. + pack.py Nothing is shared with the codec's writer on purpose. + adpcm.py the MSM6258 codec, carrying ffmpeg's decoder and the + chip's measured one side by side. + dlx.py the codec's container and its REFERENCE DECODER, + encode.py ground truth for the 68000; the encoder, rate + spans.py control, and the v7 span geometry. Parked, kept. + extract.py frames and audio off the disc. +tools/bench/ check.sh the green light. + packed_run.sh the packed player: gate, rate, audio, held, seek. + verify_packed.py / verify_packed_audio.py + the two gates that matter. The audio one reads the + SPEAKER, one delivered byte at a time, because every + counter in the player stayed right through a bug + that overwrote the buffer the channel was reading. + crtc_mode.lua the SINGLE SOURCE OF TRUTH for CRTC R00-R08 and + R20. Do not write CRTC values anywhere else. + probe_bit11_blank.lua B2, ready to run on a real board. + c68k/ a SECOND emulator for every 68000 cycle figure: + px68k's CPU core, no SDL, no ROMs. It also counts + BUS cycles, which MAME cannot report. + gvpack/ the same argument for the DISPLAY: px68k's own + x68k/gvram.c, so the address decode, the R20 bit-11 + write path and the scroll wrap are its code and not + a model of it. + blit.s the full-frame GVRAM blit, timed on the 68000 + itself. V8 is the packed one: 227,553 clocks. tools/analysis/ measurement scripts, numbered in the order they were written. - Run from the repo root; they import from tools/encoder/. - 01 and 02 are marked BROKEN deliberately and kept as - regression references. - 10 is a COUNTEREXAMPLE and exits non-zero by design: it - demonstrates that the two-display-path plan corrupts 70 of 120 - frames, which is why decode.s has one display path. - 15 measures how much of the 68000's local bus the decoder - occupies and exits non-zero if its derived model stops - matching the harness's measurement. - 16 is the DLX3 span container round-trip gate: it encodes, - writes the container, reads it back with the reference decoder - and fails if a pixel differs, or if it emitted too few spans to - have tested anything. - 19 models the ring's ADDRESSES rather than its occupancy, - because each record must be contiguous and not merely resident, - and reports the zero-prefill pipe. - 20 is an independent Python re-derivation of the seek-slack - model, sharing no code with the Lua producer it checks. - 21 decodes the IPL ROM's HD63450 configuration and gates on the - bytes being where it says they are. - 22 prices a scene change: header bytes, load-time clocks and - what both cost in accumulated seek slack, across explicit - rates. Its cycle counts are PARSED out of the rig's log, not - pasted in, so they cannot go stale silently. - 35 reads every stream of the game's own footage and reports - the disc's peak against the chip's 10-bit clamp, the RUN - LENGTHS of the samples above it (687 samples in 402 events is - a different sound from 687 in one), and what six gains cost on - windows drawn over the whole game. --gate asserts those - numbers; --recover is the control that kills 66.3's mechanism. - 36 puts 51.3's climb, 56.3's 612 real branch points and 32's - cadence in one place: what a SECOND CONSUMER does to the - climb, and what a seek into the middle of an audio group - costs. It reads only DLXSCENE1 and both containers' own - headers, and its one design assumption -- one container per - SCENE -- is printed in its own output. - 37 prices what a BRANCH costs the chip, which is a codec - property rather than a player one: the accumulator has no leak, - so a re-PLAY at a branch is an exact permanent DC offset and - playing through is a larger one that decays only by clamping. - It gives the census over every frame boundary, checks its own - arithmetic for the machine's branch point against what the - capture measured, and prices the encoder-side fix. - buscost.py is the shared bus-cycle table. The per-block - constants live in tools/encoder/vq_hybrid.py and are imported, - never copied. -tools/bench/ MAME Lua injection harness and 68000 benchmark sources. - check.sh is the green light. - blit.s/blit.lua time the full-frame GVRAM blit on the 68000 - itself. Not part of check.sh, because wall timings would make - the green light host-sensitive. - span.sh measures the literal-span mode the same way and - asserts that every one of its 36 timing configs drew a - pixel-exact frame, the count taken from generated metadata so - a new config cannot weaken the gate. - crtc_mode.lua is the single source of truth for CRTC R00-R08 - and R20. Do not write CRTC values anywhere else. - verify_packed_audio.py is P6c's gate and it reads the - SPEAKER: it accounts for every byte of a DLXP2's audio against - MAME's own -wavwrite capture, ONE DELIVERED BYTE AT A TIME, - because the chip plays a byte as two nibbles only when the DMA - write lands inside the right sound-stream slice. A player's own - counters cannot gate this -- all of them stayed right through a - bug that overwrote the buffer the channel was reading. - prep_dlx.py/decode.lua/verify_decode.py load, time and verify - decode.s. prep_stream.py/stream.lua do the same for stream.s, - but lay the container out as a DISK in a host file and feed it - through a bounded ring at a modelled pipe rate, so the rig is - not bounded by the emulated machine's RAM and a stock 2 MB - machine runs the whole window. dlxload.py holds the - codebook/palette load-time maths both preps share -- and - the reference src/player/load.i is gated against. - prep_load.py/load.lua/verify_load.py/load_run.sh run those - transforms ON the 68000 and compare all 10,752 output bytes - with dlxload.py's, palette words read back out of the palette - registers rather than a RAM shadow. -tools/bench/c68k/ headless px68k C68K harness, a SECOND emulator for every - 68000 cycle figure. Links only px68k's CPU core: no SDL, no - ROMs, no emulated machine. `make PX68K=~/src/px68k` then - run.sh; verify_c68k.py checks the decode is pixel-exact, which - is what licenses the cycle numbers. It also counts BUS cycles, - which MAME cannot report. The Makefile's -no-pie and the - harness's MAP_32BIT arena are load-bearing: C68K truncates - host pointers to 32 bits. -tools/bench/gvpack/ the same second-emulator argument for the DISPLAY: it links - px68k's real x68k/gvram.c, so the address decode, the R20 - bit-11 write path, the page-byte selection, the scroll wrap and - the index-0 transparency test are px68k's own code. - verify_gvpack.py checks the LAYOUT (the harness computes the - interleave); verify_dlxp.py checks the CONTAINER, writing a - DLXP1 record's bytes into GVRAM verbatim with no interleave - computed anywhere, which is the only way to catch an encoder - whose byte order is wrong. - 25 imports nothing itself: it reads the DLXSCENE1 scene - table and reports the worst gap between two decision points, - what the input layer has to survive, and what both cost in - 51.3's accumulated slack across explicit rates. -tools/import/ the ONLY code in this tree coupled to somebody else's source. - scenegraph.py reads a DirkSimple checkout (and optionally the - SNES chapter XMLs) and writes tmp/scenegraph.json in this - project's own DLXSCENE1 schema, with the sources' licences and - attribution inside it. Nothing is vendored and the output is - gitignored derived data. - 34 is DLXP2's gate: the file partitioned into spans, the - records checked against a SILENT control, the lumps checked - byte-exact against the encoder, and one negative control per - ADPCM axis. Nothing parses a packed container, so a lump one - sector out does not fail -- it paints. - 30 is the PACKED container's gate: the format's invariants - (round-trip, sectors, the transparency key, the palette word), - and the quality re-derivation 61.9 asked for, in both the RGB888 - domain every encoder PSNR here is quoted in and the GRB555 one a - player actually displays. -tools/media/ builds docs/img/ from a paced recording run -tools/vasm/ vasm m68k assembler, binary plus source tarball -tools/encoder/ hybrid VQ encoder and DLX3 container writer. - spans.py is the v7 span geometry, selection and serialiser, - and the single place the chain layout is stated on the encoder - side. It must match blit.s and decode.s: 11 coarse units of - 24 px, 11 fine of 2. - DLX2 4-byte-aligns every frame record, because an odd move.l - is an ADDRESS ERROR on a 68000, not a slow read. DLX5 aligns - them to 512 B sectors instead, so a DMA channel can read a - record as whole sectors straight into the ring with no window - and no bounce copy; dlx.record_lengths() is the one place that - rule is applied. - dlxp.py and pack.py are the OTHER container -- DLXP2, the - decoder-free packed one (FINDINGS 63, 67). Nothing is shared - with the codec's writer on purpose: a packed record is a - palette and a picture, both geometry, and dlxp.py is the one - place the interleave, the 97-sector record, the audio cadence - and the lump PAYLOAD are stated. There is no rate control in - pack.py because there is no rate lever. - adpcm.py is the MSM6258 codec and it carries TWO decoders on - purpose: the module defaults are ffmpeg's, so that - tools/bench/verify_adpcm.py stays a check against an - independent implementation, and adpcm.CHIP is the set measured - out of the machine's own chip (66). Anything that encodes FOR - the machine passes CHIP explicitly. - dlx.py is the reference DECODER, ground truth for the 68000. - 24 models the ring with the 68000 owning it: the request - queue, the poll-only-when-not-decoding rule and 54.4's frame - cadence, and reports the pipe the player's own loop gives away. -src/player/ packed.s is the DECODER-FREE player: it brings up its own - display, builds the DMA chain, keeps its own clock, fetches - every record off a real volume and -- since FINDINGS 68 -- feeds - the container's own audio lumps to the MSM6258 on channel 3 - while it does. Its audio half is three things: a lump ring - (pg_afill/pg_afetch), the remainder accumulator that stops the - padding becoming drift (pg_apay, 67.2), and a service routine - that runs from inside dma.i's transfer wait rather than once a - frame (pg_aserv through DM_HOOK). The last of those is the - whole difference between 0.51 ms of seam and 236 ms. - adpcm.i is the transport, every register byte of it decoded out - of the IPL ROM by tools/analysis/21_iplrom_dmac.py. - decode.s is the 68000 DLX3 decoder with a preloaded-stream - front-end. stream.s is the same decoder behind a bounded ring. - load.i is the LOAD-time half: codebook expansion and palette - packing, out of the raw container header, with loadgate.s as - its rig front-end. Its three scratch tables describe the - machine rather than the scene, so they are a separate entry - point a player calls once at boot. - ring.i is the RING PRODUCER: `aligned` placement, the - descriptor ring, the prefill policy, 51.2's slack rule as - arithmetic (ring_may_seek) and a seek. It reads the DLX4 record - index because a player cannot learn a record's length by - walking a stream it has not fetched. - Both include frame.i (the block loop and span chain) and - geom.i (the constants), so there is exactly ONE copy of the - bytes every cycle constant is fitted to. The span pass is - blit.s v7 verbatim, the same instruction sequence the - 66.0/9.143/9.978 clock fit was measured on, so do not tidy it. - check.sh asserts decode.s still assembles to the same 1,296 - bytes. -assets/ extracted frames and audio (gitignored) + Run from the repo root. 01 and 02 are marked BROKEN + deliberately and kept as regression references; 10 is a + COUNTEREXAMPLE and exits non-zero by design, demonstrating that + the two-display-path plan corrupts 70 of 120 frames. 15 is the + bus occupancy model, 19 the ring's ADDRESSES (not its + occupancy), 21 the IPL ROM's DMAC configuration, 25 the scene + graph, 30/34 the packed containers, 31 the display duty, 35 the + audio level off the whole disc, 36 the climb against real + branch points, 37 what a branch costs the chip. buscost.py is + the shared bus-cycle table; the per-block constants live in + vq_hybrid.py and are imported, never copied. +tools/import/ scenegraph.py -- the ONLY code in this tree coupled to somebody + else's source. Output is gitignored derived data. +tools/media/ make_packed_media.py builds the live player's still and clip; + make_readme_media.py builds the parked codec's. Both gate + before they write. +tools/vasm/ vasm m68k assembler, binary plus source tarball. +docs/img/ the stills and clips above, built from real emulated runs. +assets/, tmp/ extracted frames, audio and run output (gitignored). ``` Source media (`DRAGONS_LAIR.iso`) and ROMs are gitignored. Supply your own. diff --git a/docs/img/packed-player.webm b/docs/img/packed-player.webm new file mode 100644 index 0000000..20d2aba Binary files /dev/null and b/docs/img/packed-player.webm differ diff --git a/tools/media/make_packed_media.py b/tools/media/make_packed_media.py index c46faaa..1a60b1e 100644 --- a/tools/media/make_packed_media.py +++ b/tools/media/make_packed_media.py @@ -16,7 +16,7 @@ the source is CLOSEST TO THE MEAN over the whole gated window, so the still is representative rather than flattering. The chosen frame and its distance from the mean are printed, so a reader can see it was not the best one. """ -import argparse, csv, os, sys +import argparse, csv, os, shutil, struct, subprocess, sys, wave sys.path.insert(0, "tools/encoder") import numpy as np from PIL import Image, ImageDraw @@ -29,6 +29,14 @@ ap.add_argument("--map", default="tmp/packed_snaps_gate.csv") ap.add_argument("--src", default="tmp/fr_singe") ap.add_argument("--frame", type=int, default=None) ap.add_argument("--out", default="docs/img/packed-player.png") +ap.add_argument("--webm", default="docs/img/packed-player.webm") +ap.add_argument("--wav", default="tmp/packed_aud.wav", + help="MAME's own -wavwrite capture from run 5 of " + "packed_run.sh; --no-audio drops it") +ap.add_argument("--no-audio", action="store_true") +ap.add_argument("--no-webm", action="store_true") +ap.add_argument("--fps", type=float, default=None, + help="clip rate; defaults to the container's own") a = ap.parse_args() d = DLXP(a.container) @@ -109,3 +117,119 @@ print(f" chosen as the frame CLOSEST TO THE MEAN ({mean:.2f} dB over " f"best in the window is {max(scores.values()):.2f}, worst " f"{min(scores.values()):.2f}") print(f" and it is pixel-exact against {a.container}, checked before writing") + + +# --------------------------------------------------------------------------- +# THE CLIP. ROADMAP K3's result is a SEQUENCE -- 120 records off a real volume, +# every one of them a literal -- and a still cannot show the one property that +# distinguishes this branch from the codec's: there is no recursion here, so +# frame 119 says nothing about frame 60 and every frame has to be its own claim. +# This writes all of them, and gates all of them before writing any (64.1). +# +# WHAT IT IS, EXACTLY, because two runs of packed_run.sh are in it: +# picture run 1, the GATE run -- paced at half the container's rate so the +# snapshot lands inside the write window, cycle stealing, no sound. +# Every panel is MAME's own snapshot, 2x nearest, no filtering. +# sound run 5, the AUDIO run -- the same container at 12 fps with the +# MSM6258 on channel 3, captured by MAME's -wavwrite off the +# speaker. It is the chip's stream, not the encoder's. +# They are two runs because they have to be: the gate run is at 6 fps and audio +# cut at 12 fps played at 6 is not this scene. The clip is therefore a +# COMPOSITE, and saying so is the point -- what it is NOT is a real-time capture +# of the shipping configuration, which at the container's own burst rate would +# show a blank layer for 99.5% of every slot (FINDINGS 64.2). +if not a.no_webm: + if not shutil.which("ffmpeg"): + sys.exit("ffmpeg not found -- needed for the webm (--no-webm skips it)") + fps = a.fps or d.fps + + # EVERY frame gated, not the printed one. A packed frame is a literal: the + # codec's last-frame test audits 120 through its own recursion and nothing + # here does, so a clip of 120 frames is 120 separate claims. + bad = [f for f in frames if not np.array_equal(screen(f), d.render(f))] + if bad: + sys.exit(f"{len(bad)} of {len(frames)} frames are NOT pixel-exact " + f"against {a.container} (first {bad[0]}). The clip is not " + f"being written: it would be a recording of a failure.") + + aud = None + if not a.no_audio and d.has_audio and os.path.exists(a.wav): + # THE ALIGNMENT IS FOUND, NOT ASSUMED, and then CHECKED. The capture + # opens with the machine booting, so the stream starts at the first + # non-zero sample -- and "first non-zero" is exactly the kind of thing + # that is off by one byte forever with every counter in the player + # agreeing (FINDINGS 71.5). So lump 0 is decoded with the FOUR AXES OUT + # OF THE CONTAINER'S OWN HEADER and required to be sample-exact from + # there. Only lump 0: past it the seams need the walk in + # tools/bench/verify_packed_audio.py, which is what gates the whole + # stream in check.sh. This gates the cut. + sys.path.insert(0, "tools/encoder") + import adpcm + SCALE = 8 # okim6258's signal<<4 at gain 0.50 + w = wave.open(a.wav) + nfr, ch, rate, sw = (w.getnframes(), w.getnchannels(), + w.getframerate(), w.getsampwidth()) + if rate != d.aud_hz or sw != 2: + sys.exit(f"{a.wav}: {rate} Hz / {sw*8}-bit -- the capture has to be " + f"the chip's own {d.aud_hz} Hz or a resampler is in the " + f"measurement") + raw = w.readframes(nfr) + left = struct.unpack("<%dh" % (nfr * ch), raw)[0::ch] + rec = [round(v / SCALE) for v in left] + start = next((i for i, v in enumerate(rec) if v), None) + if start is None: + sys.exit(f"{a.wav} is silent -- run 5 of packed_run.sh writes it") + dec = d.decoder() + l0 = d.lump(0) + want = adpcm.decode(adpcm.unpack(l0, order=dec["order"]), + variant=dec["variant"], init=dec["init"], + bits=dec["bits"]) + got = rec[start:start + len(want)] + if got != list(want): + n = sum(x != y for x, y in zip(got, want)) + sys.exit(f"the cut at capture sample {start:,} does not decode as " + f"lump 0: {n:,} of {len(want):,} samples differ. The clip " + f"is not being written -- the sound would be the right " + f"scene from the wrong byte.") + n_out = int(round(len(frames) / fps * rate)) + aud = "tmp/_packed_media_audio.wav" + ow = wave.open(aud, "wb") + ow.setnchannels(ch); ow.setsampwidth(sw); ow.setframerate(rate) + ow.writeframes(raw[start * ch * sw:(start + n_out) * ch * sw]) + ow.close() + print(f" audio: {a.wav}, cut at sample {start:,} " + f"({start/rate:.2f} s of boot dropped), {n_out/rate:.2f} s -- " + f"lump 0 sample-exact against the container's own axes " + f"({dec['variant']}/{dec['order']}, {dec['bits']}-bit, " + f"init {dec['init']})") + elif not a.no_audio: + print(f" no audio: {a.wav} is missing or the container is silent") + + tmpd = "tmp/_packed_media_frames" + shutil.rmtree(tmpd, ignore_errors=True) + os.makedirs(tmpd) + for n, f in enumerate(frames): + l = captioned(source(f), "Blu-ray source, cropped 256x192") + r = captioned(screen(f), "emulated 68000, MAME's own snapshot, " + "no decoder in the machine") + im = Image.new("RGB", (l.width + r.width + 8, l.height), (16, 16, 18)) + im.paste(l, (0, 0)); im.paste(r, (l.width + 8, 0)) + im.save(f"{tmpd}/{n:04d}.png") + + # VP9 near-lossless: this is 256x192 palettised pixel art scaled by an + # integer, and a codec that smooths a colour boundary would be editorialising + # about the one thing the picture is evidence of. + cmd = ["ffmpeg", "-y", "-loglevel", "error", "-framerate", f"{fps:g}", + "-i", f"{tmpd}/%04d.png"] + if aud: + cmd += ["-i", aud, "-c:a", "libopus", "-b:a", "96k", "-shortest"] + cmd += ["-c:v", "libvpx-vp9", "-crf", "12", "-b:v", "0", + "-pix_fmt", "yuv444p", "-row-mt", "1", a.webm] + subprocess.run(cmd, check=True) + shutil.rmtree(tmpd) + if aud: + os.remove(aud) + print(f"{a.webm}: {len(frames)} frames @ {fps:g} fps, " + f"{os.path.getsize(a.webm)/1024:.0f} KB, every frame pixel-exact " + f"against {a.container}" + + (" -- with the chip's own audio" if aud else " -- silent"))