drwily/Dragon-s-Lair-X68k
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Build v7 into the player, and find the cost model 18% wrong on the block it made commonest

Browse Source 
src/player/decode.s now paints v7 literal spans, pixel-exact under MAME and
px68k's C68K core over a container where every frame carries 128-216 spans
covering up to 38% of the picture. The span pass is blit.s v7 verbatim: the
66.0/9.143/9.978 fit was measured on that instruction sequence.

The container is DLX3 -- a span section between the mode header and the block
payload, since that is the only place the 68000 can reach without first parsing
something of variable length. 16_span_roundtrip.py gates it in check.sh, and
asserts it emitted enough spans to have tested anything.

Two synthetic all-SPAN anchors price v7 inside decode.s at 151.2 and 225.6
clocks per 4x4 block, against FINDINGS 40's table of 151 and 226 -- 0.2% on
both emulators. The measured mode costs what it was said to cost.

Two things that were not on the list:

TWO BYTE BUDGETS. FINDINGS 40's 18/120 was scored against the 488 KB/s PIPE,
not the 280 KB/s profile, and at the profile rate the lam search has already
spent the allowance -- spans fired on 5 frames of 120 and looked like a
regression. The profile is a chosen quality rate point; the pipe is hardware.
--kbps and --span-kbps are now separate and spans run before mu, because a span
pays in bytes and mu pays in picture. Delivered: 86/120 over budget without
spans, 77/120 at the profile budget, 34/120 on the pipe for +0.36 dB.

C_SKIP_MIXED WAS NEVER MEASURED, and it was 18% low -- 45.0, now 55.0. It is
the one constant in the table that came from a derivation, because the
synthetic frame that would measure it cannot exist: a byte needs a coded block
for its SKIP to be mixed. Four bracketing anchors measure it on both emulators
with the header byte rotated through all four positions, and the partner mode
solves back to its own anchored value to 0.2%. With it corrected the model
predicts a real spanned decode to -0.06% mean / 0.09% worst, against -2.99% /
4.30%. It matters because a span marks its run SKIP, so mixed SKIPs dominate
exactly the frames spans are judged on.

Also: the rig had been writing its synthetic timing frames 26 KB past the top
of a 2 MB machine, and got away with it because the modes it overran are
data-independent. A span's jump displacements come out of the stream, so it is
not. And frames-over-budget is no longer a safe headline -- the controller aims
at the deadline, so 55 of 120 frames sit within 5% of it and a 1% cost shift
moves 22 frames.

FINDINGS 41. check.sh ALL GREEN, now gating on a span-heavy DLX3 container.

Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6
This commit is contained in:
prosolis
2026-08-23 20:02:03 -07:00
parent c520a89e14
commit b49bbdc939
16 changed files with 1342 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/encoder/ratectl.py
+91 -9
View File
@@ -21,6 +21,7 @@ fixed by tuning. Regression test: tools/analysis/09_ratectl_drift.py.
"""
import numpy as np
import vq_hybrid as H
import spans as SP
# Profiles. Bandwidths are the sustained-read figures the player can rely on;
# see docs/FINDINGS.md 5 -- these are FOLKLORE-grade until the disk benchmark
@@ -192,9 +193,51 @@ def _search_mu(ctx, allow, lam_lo, lam_hi, cyc_budget, iters=10):
return (*best, False)
def _fit_spans(m, ctx, mode, sz, room, cyc_budget, span_mode, ib):
"""Buy 68000 cycles with container bytes, by painting runs as v7 spans.
Returns (mode, size, cycles, sel) where `sel` is spans.select()'s result.
ORDER MATTERS, and it is the reason this runs before the mu search rather
than inside it. Both controllers make a frame decode in time, but they pay
for it differently: mu buys cycles with QUALITY (it pushes blocks down to
cheaper modes and ultimately to SKIP), and a span buys them with BYTES --
and it carries literal source pixels, so it *removes* that run's
quantisation error. Spending bytes we already have is strictly better than
spending picture, so spans go first and mu is what is left when the byte
allowance runs out.
`span_mode` is "need" (stop as soon as the frame fits its cycle budget --
the default, and the cheapest way to make the deadline) or "all" (spend
every profitable byte, which is the model tools/analysis/14_dmac_chain.py
scores and costs several times the bitrate for a little more headroom).
`room` is a byte ceiling for the WHOLE frame, and it is not necessarily the
same one the lam search ran under. Those are two different budgets and
conflating them is what made the first measured span encode look like a
regression (FINDINGS 41.2): the profile's bitrate is a chosen quality rate
point, while the pipe is a hardware ceiling, and bytes left between them
buy nothing if they are not spent. Spending them on lam gets a better
picture; spending them on spans gets the deadline. `--span-kbps` picks.
"""
src = m["idx"][ctx["f"]]
room = room - sz - 2 # the u16 span count is always emitted
if room <= 0:
return mode, sz, H.cycles(mode), None
sel = SP.select(mode, src, m["nbx"], m["nby"], room,
need_clocks=(None if span_mode == "all" else cyc_budget),
idx_bytes=ib)
if not sel["spans"]:
return mode, sz, H.cycles(mode), None
nmode = sel["mode"]
nsz = (H.frame_bytes(nmode, ctx["nb"], ib) + SP.section_bytes(sel["spans"]))
return nmode, nsz, H.cycles(nmode) + sel["clocks"], sel
def encode_rate_controlled(m, target_kbps, fps=12, bucket_frames=8,
lam_lo=1.0, lam_hi=LAM_CLIFF, prefill=0.0,
steps=None, verbose=False, cycle_budget=None):
steps=None, verbose=False, cycle_budget=None,
span_mode=None, span_kbps=None):
"""Per-frame lam search under a leaky bucket, driving the encoder ONE FRAME
AT A TIME and feeding back the frame actually emitted.
@@ -234,32 +277,71 @@ def encode_rate_controlled(m, target_kbps, fps=12, bucket_frames=8,
if steps is not None and verbose:
print(" note: `steps` is ignored; lam is now bisected per frame")
budget = frame_budget(target_kbps, fps)
span_budget = None if span_kbps is None else frame_budget(span_kbps, fps)
cap = bucket_frames * budget
bucket = prefill * cap # banked bytes; bounded by the player's buffer both ways
out = dict(recon=[], modes=[], sizes=[], lam=[], l1=[], l4g=[], overrun=[],
mu=[], cycles=[], late=[])
mu=[], cycles=[], late=[], spans=[])
ib = H.default_idx_bytes(m)
prev = None
for f in range(len(m["idx"])):
ctx = H.frame_ctx(m, f, prev)
allow = budget + bucket
if cycle_budget is None:
lam, mode, sz, ovr = _search_lam(ctx, allow, lam_lo, lam_hi)
mu, cyc, late = 0.0, H.cycles(mode), False
else:
# The span pass may draw on a DIFFERENT ceiling: flat per frame, not
# banked, because it is the delivery pipe rather than a quality target
# and a pipe cannot be saved up. None means "the same allowance the lam
# search had", which is what leaves spans nothing to buy with at a rate
# point the block coder has already spent (FINDINGS 41.2).
span_allow = allow if span_budget is None else span_budget
sel = None
lam, mode, sz, ovr = _search_lam(ctx, allow, lam_lo, lam_hi)
mu, cyc, late = 0.0, H.cycles(mode), False
if span_mode and (span_mode == "all"
or (cycle_budget is not None and cyc > cycle_budget)):
mode_pre = mode
mode, sz, cyc, sel = _fit_spans(m, ctx, mode, sz, span_allow,
cycle_budget, span_mode, ib)
if cycle_budget is not None and cyc > cycle_budget:
# The byte allowance could not buy the frame's deadline, so fall
# back to the controller that pays in picture -- and then offer
# spans the bytes the smaller mode map just freed.
mu, lam, mode, sz, cyc, ovr, late = _search_mu(
ctx, allow, lam_lo, lam_hi, cycle_budget)
rec = H.paint(m, ctx, mode)
bucket = float(np.clip(bucket + budget - sz, -cap, cap))
if span_mode:
mode_pre = mode
mode, sz, cyc, sel = _fit_spans(m, ctx, mode, sz, span_allow,
cycle_budget, span_mode, ib)
late = cyc > cycle_budget
# Paint from the mode map as it was BEFORE spanning. A spanned run's
# blocks read SKIP in the emitted header, but SKIP means "hold the
# previous reconstruction" and on the first frame there is none -- and
# more generally the held pixels would be wrong. The span overwrites
# exactly the run it covers (4 rows x 4L pixels = the blocks), so
# painting the pre-span modes and then laying the spans over them is
# what the 68000 produces, and it is defined on frame 0.
if span_mode and sel is None:
sz += 2 # the u16 span count is in every DLX3 frame record
# What the quality bucket banks is the BLOCK payload. Charging it the
# span bytes too would drive it to its floor on the first spanned frame
# and starve every later frame of quality for a budget the spans were
# never drawing on.
sz_quality = sz if (sel is None or span_budget is None) else sz - sel["bytes"]
rec = H.paint(m, ctx, mode if sel is None else mode_pre)
if sel is not None:
for y, x, pix in sel["spans"]:
rec[y, x:x + len(pix)] = pix
bucket = float(np.clip(bucket + budget - sz_quality, -cap, cap))
out["recon"].append(rec); out["modes"].append(mode)
out["sizes"].append(sz); out["lam"].append(lam); out["overrun"].append(ovr)
out["mu"].append(mu); out["cycles"].append(cyc); out["late"].append(late)
out["l1"].append(ctx["sym"]["l1"]); out["l4g"].append(ctx["sym"]["l4g"])
out["spans"].append([] if sel is None else sel["spans"])
prev = rec
if verbose:
print(f" f{f:04d} lam={lam:8.2f} mu={mu:8.4f} {sz:7.0f} B "
f"(allow {allow:7.0f}) {100*cyc/FRAME_CYCLES:5.1f}% cpu"
f"{' OVER' if ovr else ''}{' LATE' if late else ''}")
return dict(recon=out["recon"], modes=out["modes"],
return dict(recon=out["recon"], modes=out["modes"], spans=out["spans"],
sizes=np.array(out["sizes"]), lam=np.array(out["lam"]),
l1=out["l1"], l4g=out["l4g"], overrun=np.array(out["overrun"]),
mu=np.array(out["mu"]), cycles=np.array(out["cycles"]),