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/dlx.py
+83 -4
View File
@@ -1,5 +1,5 @@
#!/usr/bin/env python3
"""Reference DLX1 reader/decoder -- the ground truth the 68000 player is checked against.
"""Reference DLX reader/decoder -- the ground truth the 68000 player is checked against.
This is deliberately a *decoder*, not a re-run of the encoder: it parses the
container byte-for-byte the way `src/player/` must, so that any disagreement
@@ -12,9 +12,19 @@ Everything is big-endian (see the `encode.py` docstring). Block raster order,
V4 sub-block order is (sub_y, sub_x) row-major -- TL, TR, BL, BR -- matching
`vq_hybrid.paint`'s reshape(-1,2,2,2,2).transpose(0,1,3,2,4).
DLX3 adds the v7 LITERAL SPAN section between the mode header and the block
payload (FINDINGS 40, tools/encoder/spans.py). A spanned block reads SKIP in
the mode header and is painted by a span instead, so a reader that ignores the
section does not merely lose the spans -- it displays stale pixels wherever one
was. The section is at a KNOWN offset (header end) rather than behind the
block payload precisely so that the 68000 can paint it before it has parsed
anything of variable length.
"""
import struct
import os, sys, struct
import numpy as np
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import spans as SP
MODE_SKIP, MODE_V1, MODE_V4, MODE_RAW = 0, 1, 2, 3
@@ -28,10 +38,11 @@ class DLX:
# (FINDINGS 28.3), so the padding is part of the format, not a loader
# convenience -- but DLX1 containers stay readable, because every
# measurement in FINDINGS 28-31 was taken on one.
if b[:4] not in (b"DLX1", b"DLX2"):
if b[:4] not in (b"DLX1", b"DLX2", b"DLX3"):
raise ValueError(f"{path}: not a DLX container")
self.version = int(b[3:4])
self.aligned = self.version >= 2
self.has_spans = self.version >= 3
(self.W, self.H, self.fps, self.nframes,
self.k1, self.k4) = struct.unpack(">HHHHHH", b[4:16])
off_pal, off_cb1, off_cb4, off_frm = struct.unpack(">IIII", b[16:32])
@@ -72,6 +83,60 @@ class DLX:
m = np.stack([(h >> 6) & 3, (h >> 4) & 3, (h >> 2) & 3, h & 3], axis=1)
return m.reshape(-1)[:self.nb].copy()
def spans(self, f):
"""The frame's literal spans: (list of (y, x, pixels), payload offset).
Layout, big-endian, at the end of the mode header (DLX3 only):
u16 nspans
nspans * { u32 GVRAM address, u16 coarse disp, c*48 B pixels,
u16 fine disp, f*4 B pixels }
The displacements are JUMP offsets into the decoder's two unrolled copy
chains, so the pixel counts are read back out of them -- which is the
strongest available check that the encoder and `blit.s` agree about the
chain geometry, because a wrong displacement lands mid-chain and paints
the wrong number of pixels rather than failing loudly.
"""
o, n = self.frames[f]
p = o + self.mode_bytes
if not self.has_spans:
return [], p
b = self.raw
(ns,) = struct.unpack(">H", b[p:p + 2])
p += 2
out = []
for _ in range(ns):
addr, cd = struct.unpack(">IH", b[p:p + 6])
p += 6
c = SP.COARSE_N - cd // SP.COARSE_CODE
if cd % SP.COARSE_CODE or not 0 <= c <= SP.COARSE_N:
raise ValueError(f"frame {f}: coarse displacement {cd} is not "
f"an entry point in an {SP.COARSE_N}-unit chain")
px = list(np.frombuffer(b, ">u2", c * SP.COARSE_PX, p) & 0xFF)
p += c * SP.COARSE_PX * 2
(fd,) = struct.unpack(">H", b[p:p + 2])
p += 2
fu = SP.FINE_N - fd // SP.FINE_CODE
if fd % SP.FINE_CODE or not 0 <= fu <= SP.FINE_N:
raise ValueError(f"frame {f}: fine displacement {fd} is not "
f"an entry point in a {SP.FINE_N}-unit chain")
px += list(np.frombuffer(b, ">u2", fu * SP.FINE_PX, p) & 0xFF)
p += fu * SP.FINE_PX * 2
a = addr - SP.GVRAM
y, x = divmod(a, SP.STRIDE)
y -= SP.YOFF
if x % 2 or not (0 <= y < self.H) or not (0 <= x // 2 < self.W):
raise ValueError(f"frame {f}: span destination {addr:#x} is "
f"not a pixel of the {self.W}x{self.H} picture")
# blit.s tolerates a span running past the visible 256 pixels (the
# line stride is 1024 bytes and only the first 512 are displayed),
# but nothing an encoder emits should need to: a span is a run of
# whole blocks. numpy would truncate it here in silence.
if x // 2 + len(px) > self.W:
raise ValueError(f"frame {f}: span at ({x//2},{y}) of "
f"{len(px)} px overruns the picture width")
out.append((y, x // 2, np.array(px, np.uint8)))
return out, p
def blocks(self, f):
"""Decoded 4x4 palette-index blocks for the non-SKIP blocks of frame f.
@@ -82,7 +147,8 @@ class DLX:
"""
mode = self.modes(f)
o, n = self.frames[f]
p, end = o + self.mode_bytes, o + n
_, p = self.spans(f)
end = o + n
ib, out = self.idx_bytes, {}
b = self.raw
for i, mo in enumerate(mode):
@@ -115,6 +181,19 @@ class DLX:
for i, blk in blks.items():
by, bx = divmod(i, self.nbx)
canvas[by * 4:by * 4 + 4, bx * 4:bx * 4 + 4] = blk
sp, _ = self.spans(f)
for y, x, pix in sp:
# A span paints blocks the mode header calls SKIP. If it ever
# overlaps a coded block the two disagree about the same pixels and
# the 68000's answer depends on which it does last -- so this is a
# format invariant, not a courtesy check.
b0, b1 = x // 4, -(-(x + len(pix)) // 4)
bad = [b for b in range(b0, b1)
if mode[(y // 4) * self.nbx + b] != MODE_SKIP]
if bad:
raise ValueError(f"frame {f}: span at ({x},{y}) covers "
f"non-SKIP block(s) {bad} of block row {y//4}")
canvas[y, x:x + len(pix)] = pix
return mode
def decode_all(self):
tools/encoder/encode.py
+158 -79
View File
@@ -30,8 +30,17 @@ multi-byte field is big-endian and the decoder can read it with a plain move.w):
`move.l` -- FINDINGS 28.3):
u32 payload length, then
ceil(nblocks*2/8) bytes of 2-bit mode headers, MSB-first, block raster order
DLX3 only: the v7 LITERAL SPAN section (tools/encoder/spans.py) --
u16 nspans, then per span { u32 GVRAM address, u16 coarse displacement,
c*48 B pixels, u16 fine displacement, f*4 B pixels }
then payloads in block order: V1 -> 1 byte, V4 -> 4 bytes, RAW -> 16 bytes
The span section is between the header and the block payload, not after it,
because the 68000 has to reach it without first parsing something of variable
length: the mode header is a fixed 768 bytes, so the section starts at a known
offset and the block payload starts wherever the span walk finishes. Every
span record is a multiple of 4 bytes long, so nothing inside needs padding.
Codebooks are emitted as palette INDICES, not pixels. The player expands them
once at load time into word-per-pixel form so the blitter can movem them
straight into GVRAM -- k1=1024 costs 1024*16*2 = 32 KB of the 2 MB.
@@ -39,7 +48,7 @@ straight into GVRAM -- k1=1024 costs 1024*16*2 = 32 KB of the 2 MB.
import argparse, struct, sys, os
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import numpy as np
import vq as VQ, vq_hybrid as H, ratectl as RC
import vq as VQ, vq_hybrid as H, ratectl as RC, spans as SP
# Measured on the emulated 68000, FINDINGS 24. Instruction cycles against
# zero-wait-state memory, so these are floors, not hardware predictions.
@@ -81,81 +90,35 @@ def _idx(v):
_IDX_BYTES = 1
def main():
global _IDX_BYTES
ap = argparse.ArgumentParser()
ap.add_argument("frames_dir"); ap.add_argument("out")
ap.add_argument("--profile", choices=list(RC.PROFILES), default="scsi")
ap.add_argument("--lam", type=float, default=None)
ap.add_argument("--fps", type=int, default=12)
ap.add_argument("--iters", type=int, default=16)
ap.add_argument("--fixed-lam", action="store_true",
help="disable rate control (session 5 behaviour)")
ap.add_argument("--rc-floor", choices=("profile", "open"), default="profile",
help="quality floor for rate control")
ap.add_argument("--bucket-frames", type=int, default=8,
help="leaky-bucket depth, in frame budgets")
ap.add_argument("--no-cpu-fit", action="store_true",
help="drop the per-frame 68000 decode ceiling (session 7 "
"behaviour: 31%% of frames on hard content do not fit)")
ap.add_argument("--prefill", type=float, default=0.0,
help="how full the player's buffer is assumed to be at "
"scene start, as a fraction of the bucket (0 = cold "
"buffer after a seek, the conservative assumption)")
ap.add_argument("--preview")
a = ap.parse_args()
def build_records(m, enc, span_mode):
"""The per-frame records of the container, in order.
prof = RC.PROFILES[a.profile]
lam = a.lam if a.lam is not None else prof["lam"]
k1, k4 = prof["k1"], prof["k4"]
_IDX_BYTES = 1 if max(k1, k4) <= 256 else 2
The encoder hands back the symbols it actually chose. Re-deriving them here
(as session 5 did) is a second chance to disagree with the encoder, and with
per-frame rate control the mode map is no longer reproducible from a single
lam anyway.
# An explicit --lam is a request for that lam, so it implies --fixed-lam.
rc = not (a.fixed_lam or a.lam is not None)
lam_lo = lam if a.rc_floor == "profile" else 1.0
# The CPU ceiling is hardware, not taste: without it 31%% of frames on the
# worst sustained window do not decode in time on a stock 68000, and with
# it that is one frame -- the intra frame -- for 0.26 dB. FINDINGS 31.
cyc_budget = None if a.no_cpu_fit else RC.FRAME_CYCLES
print(f"profile {a.profile}: {prof['desc']}")
if rc:
print(f" target {prof['kbps']} KB/s CEILING, rate-controlled: "
f"lam bisected per frame in [{lam_lo:g}, {RC.LAM_CLIFF:g}], "
f"{a.bucket_frames}-frame bucket")
print(f" CPU ceiling: " + (f"mu bisected per frame against "
f"{RC.FRAME_CYCLES:,.0f} cycles (12fps, stock 68000)"
if cyc_budget else "OFF (--no-cpu-fit)"))
else:
print(f" target {prof['kbps']} KB/s, FIXED lam={lam} (no rate control)")
print(f" k1={k1} k4={k4}, {_IDX_BYTES}-byte indices")
m = H.build(a.frames_dir, k1=k1, k4=k4, iters=a.iters)
if rc:
enc = RC.encode_rate_controlled(m, prof["kbps"], fps=a.fps,
bucket_frames=a.bucket_frames,
lam_lo=lam_lo, prefill=a.prefill,
cycle_budget=cyc_budget)
else:
enc = H.encode(m, lam=lam)
r = H.evaluate(m, enc, fps=a.fps)
H_, W_ = m["H"], m["W"]; nbx = W_ // 4
pal, idx = m["pal"], m["idx"]
# The encoder hands back the symbols it actually chose. Re-deriving them
# here (as session 5 did) is a second chance to disagree with the encoder,
# and with per-frame rate control the mode map is no longer reproducible
# from a single lam anyway.
frames = []
for f, im in enumerate(idx):
Factored out of main() so tools/analysis/16_span_roundtrip.py can build the
same bytes the shipping encoder does -- a round-trip gate that rebuilt the
records itself would be testing its own copy of the format.
"""
nbx = m["W"] // 4
out = []
for f, im in enumerate(m["idx"]):
mode = enc["modes"][f]
frames.append(pack_modes(mode)
+ frame_payload(mode, enc["l1"][f], enc["l4g"][f], im, nbx))
sp = enc.get("spans", [[]] * len(m["idx"]))[f]
rec = (pack_modes(mode)
+ (SP.serialise(sp) if span_mode else b"")
+ frame_payload(mode, enc["l1"][f], enc["l4g"][f], im, nbx))
# the rate controller budgets exactly these bytes -- if that ever drifts
# from the container, every bitrate figure below is fiction
assert len(frames[-1]) == enc["sizes"][f], (f, len(frames[-1]), enc["sizes"][f])
# from the container, every bitrate figure reported is fiction
assert len(rec) == enc["sizes"][f], (f, len(rec), enc["sizes"][f])
out.append(rec)
return out
def write_container(path, m, frames, fps, k1, k4, span_mode):
"""Write the whole container. Returns (total bytes, video bytes, pad)."""
palette = m["pal"][:256]
if len(palette) < 256:
palette = np.vstack([palette, np.zeros((256 - len(palette), 3), np.uint8)])
@@ -175,22 +138,119 @@ def main():
# realigning at load time; the container now carries it.
tbl_pad = -off_frm % 4
off_frm += tbl_pad
hdr = (b"DLX2" + struct.pack(">HHHHHH", W_, H_, a.fps, len(idx), k1, k4)
hdr = ((b"DLX3" if span_mode else b"DLX2")
+ struct.pack(">HHHHHH", m["W"], m["H"], fps, len(frames), k1, k4)
+ struct.pack(">IIII", off_pal, off_cb1, off_cb4, off_frm))
assert len(hdr) == 32, len(hdr)
frm_pad = 0
with open(a.out, "wb") as fh:
with open(path, "wb") as fh:
fh.write(hdr); fh.write(pal_b); fh.write(cb1_b); fh.write(cb4_b)
fh.write(b"\0" * tbl_pad)
for i, p in enumerate(frames):
fh.write(struct.pack(">I", len(p))); fh.write(p)
for i, rec in enumerate(frames):
fh.write(struct.pack(">I", len(rec))); fh.write(rec)
if i + 1 < len(frames): # nothing follows the last record
n = -(4 + len(p)) % 4
n = -(4 + len(rec)) % 4
fh.write(b"\0" * n); frm_pad += n
total = os.path.getsize(path)
return total, sum(len(r) + 4 for r in frames) + frm_pad, frm_pad
total = os.path.getsize(a.out)
vid = sum(len(p) + 4 for p in frames) + frm_pad
def main():
global _IDX_BYTES
ap = argparse.ArgumentParser()
ap.add_argument("frames_dir"); ap.add_argument("out")
ap.add_argument("--profile", choices=list(RC.PROFILES), default="scsi")
ap.add_argument("--lam", type=float, default=None)
ap.add_argument("--fps", type=int, default=12)
ap.add_argument("--iters", type=int, default=16)
ap.add_argument("--fixed-lam", action="store_true",
help="disable rate control (session 5 behaviour)")
ap.add_argument("--rc-floor", choices=("profile", "open"), default="profile",
help="quality floor for rate control")
ap.add_argument("--bucket-frames", type=int, default=8,
help="leaky-bucket depth, in frame budgets")
ap.add_argument("--kbps", type=float, default=None,
help="override the profile's bitrate CEILING. The profile "
"is a rate point on a delivery medium; this is for "
"asking what the codec does at another one -- e.g. "
"the 488 KB/s bus figure the span analyses of "
"FINDINGS 30/40 are scored against.")
ap.add_argument("--span-kbps", type=float, default=None,
help="byte ceiling the SPAN pass may draw on, if it differs "
"from the profile's. The profile is a quality rate "
"point; the pipe is hardware. Bytes between the two "
"buy a better picture if spent on lam and the 68000's "
"deadline if spent on spans -- and nothing at all if "
"left unspent (FINDINGS 41.2). 488 is the bus figure "
"tools/analysis/14_dmac_chain.py scores against.")
ap.add_argument("--spans", choices=("off", "need", "all"), default="need",
help="v7 literal spans (FINDINGS 40). `need` (default) "
"spends container bytes on spans only where a frame "
"misses the 68000's decode deadline; `all` spends "
"every profitable byte, which is the model "
"14_dmac_chain.py scores; `off` emits DLX2.")
ap.add_argument("--no-cpu-fit", action="store_true",
help="drop the per-frame 68000 decode ceiling (session 7 "
"behaviour: 31%% of frames on hard content do not fit)")
ap.add_argument("--prefill", type=float, default=0.0,
help="how full the player's buffer is assumed to be at "
"scene start, as a fraction of the bucket (0 = cold "
"buffer after a seek, the conservative assumption)")
ap.add_argument("--preview")
a = ap.parse_args()
prof = dict(RC.PROFILES[a.profile])
if a.kbps is not None:
prof["kbps"] = a.kbps
prof["desc"] = f"{prof['desc']} -- bitrate overridden to {a.kbps:g} KB/s"
lam = a.lam if a.lam is not None else prof["lam"]
k1, k4 = prof["k1"], prof["k4"]
_IDX_BYTES = 1 if max(k1, k4) <= 256 else 2
# An explicit --lam is a request for that lam, so it implies --fixed-lam.
rc = not (a.fixed_lam or a.lam is not None)
lam_lo = lam if a.rc_floor == "profile" else 1.0
# The CPU ceiling is hardware, not taste: without it 31%% of frames on the
# worst sustained window do not decode in time on a stock 68000, and with
# it that is one frame -- the intra frame -- for 0.26 dB. FINDINGS 31.
cyc_budget = None if a.no_cpu_fit else RC.FRAME_CYCLES
span_mode = None if (a.spans == "off" or not rc) else a.spans
print(f"profile {a.profile}: {prof['desc']}")
if rc:
print(f" target {prof['kbps']} KB/s CEILING, rate-controlled: "
f"lam bisected per frame in [{lam_lo:g}, {RC.LAM_CLIFF:g}], "
f"{a.bucket_frames}-frame bucket")
print(f" CPU ceiling: " + (f"mu bisected per frame against "
f"{RC.FRAME_CYCLES:,.0f} cycles (12fps, stock 68000)"
if cyc_budget else "OFF (--no-cpu-fit)"))
else:
print(f" target {prof['kbps']} KB/s, FIXED lam={lam} (no rate control)")
print(f" k1={k1} k4={k4}, {_IDX_BYTES}-byte indices")
m = H.build(a.frames_dir, k1=k1, k4=k4, iters=a.iters)
if rc:
enc = RC.encode_rate_controlled(m, prof["kbps"], fps=a.fps,
bucket_frames=a.bucket_frames,
lam_lo=lam_lo, prefill=a.prefill,
cycle_budget=cyc_budget,
span_mode=span_mode,
span_kbps=a.span_kbps)
else:
# Spans are a rate-control-era mode: `need` has no meaning without a
# per-frame byte allowance to spend, so --fixed-lam emits DLX2.
enc = H.encode(m, lam=lam)
r = H.evaluate(m, enc, fps=a.fps)
H_, W_ = m["H"], m["W"]; nbx = W_ // 4
pal, idx = m["pal"], m["idx"]
frames = build_records(m, enc, span_mode)
nspans = sum(len(x) for x in enc.get("spans", []))
total, vid, frm_pad = write_container(a.out, m, frames, a.fps, k1, k4,
span_mode)
print(f" wrote {a.out}: {total} B "
f"(header+tables {total-vid} B, video {vid} B)")
print(f" DLX2 4-byte record alignment: {frm_pad} B over {len(frames)} frames "
@@ -201,6 +261,20 @@ def main():
f"loss {r['loss']:.2f} dB")
print(f" modes: SKIP {r['skip']:.1f}% V1 {r['v1']:.1f}% "
f"V4 {r['v4']:.1f}% RAW {r['raw']:.1f}%")
if span_mode:
spf = np.array([len(x) for x in enc["spans"]])
spb = np.array([SP.section_bytes(x) for x in enc["spans"]])
# a run of L blocks is four spans of 4L pixels, so a block is 16 span
# pixels -- not 4, which would count each block four times over
blk = np.array([sum(len(p) for _, _, p in x) // 16 for x in enc["spans"]])
print(f" v7 spans ({span_mode}): {nspans:,} over {len(idx)} frames, "
f"median {np.median(spf):.0f}/frame, max {spf.max()}/frame; "
f"{100*np.mean(spb)/np.mean([len(p) for p in frames]):.1f}% of the "
f"container")
print(f" frames with any span: {int((spf>0).sum())}/{len(idx)}; "
f"blocks painted by one: median {np.median(blk):.0f}, "
f"max {blk.max()} of {m['nb']} "
f"({100*blk.max()/m['nb']:.1f}%)")
if rc:
rr = RC.summarise(m, enc, prof["kbps"], fps=a.fps)
lm = enc["lam"]
@@ -225,7 +299,12 @@ def main():
# begin with, because the compose path pays the blit ON TOP of decoding.
# FINDINGS 28.1/28.4. The player has one path and no reference frame.
ns = np.array([100 * (mm != 0).mean() for mm in enc["modes"]])
cyc = np.array([H.cycles(mm) for mm in enc["modes"]])
# enc["cycles"] already carries the span PAINTING clocks; H.cycles() sees
# only the mode map, in which a spanned block reads SKIP, so re-deriving
# here would report a frame as fitting on the strength of work the encoder
# moved into the span section rather than removed.
cyc = (np.asarray(enc["cycles"]) if "cycles" in enc
else np.array([H.cycles(mm) for mm in enc["modes"]]))
pct = 100 * cyc / RC.FRAME_CYCLES
miss = int((pct > 100).sum())
print(f" non-SKIP blocks/frame: median {np.median(ns):.1f}% "
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"]),
tools/encoder/spans.py
+216
View File
@@ -0,0 +1,216 @@
#!/usr/bin/env python3
"""v7 literal spans: geometry, selection, and the bytes that go in the container.
A span is a ROW-LINEAR run of word-expanded literal pixels that the 68000
copies straight from the stream buffer into GVRAM through an unrolled chain of
`movem.l` units, with no address arithmetic, no loop and no remainder logic.
It is the mode FINDINGS 29 derived, FINDINGS 30 measured as v6, and FINDINGS 40
re-measured as v7 -- v6's 24-pixel coarse chain with a 2-pixel fine chain
appended, at
66.0 clocks/span + 9.143/coarse pixel + 9.978/fine pixel (MEASURED)
The span constants live in tools/analysis/buscost.py and the per-block ones in
tools/encoder/vq_hybrid.py; both are imported rather than copied, which is what
kept session 12's correction to C_SKIP_MIXED from having to be made twice.
WHAT A SPAN COVERS. A run of L horizontally adjacent 4x4 blocks inside one
block row, coded as FOUR spans of 4L pixels -- one per picture row. The run's
blocks are marked SKIP in the mode header and the span paints them instead, so
a span costs the mode-map dispatch but not the block body. That is exactly the
accounting tools/analysis/14_dmac_chain.py scores.
WHY THE PADDING IS ZERO. v7's fine unit is one `move.l (a0)+,(a2)+` = 2
pixels, and a span is a run of 4x4 blocks, so its length is always a multiple
of 4 and splits into 24*c + 2*f with nothing left over (FINDINGS 40.3). v6's
24-pixel quantum wasted ~11 pixels a span and was 86% of the DMAC's advantage
over it.
SPANS ARE LITERAL, SO THEY ARE PIXEL-EXACT. A span carries palette indices
straight out of the palettised source, exactly as a RAW block does. Spanning a
run therefore does not just buy cycles, it removes that run's quantisation
error -- which is why the selection below can only improve PSNR, and why the
reconstruction the encoder feeds back to the next frame has to include spans
(a temporally recursive codec drifts otherwise -- FINDINGS 26.1).
"""
import os, sys
import numpy as np
sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)),
"..", "analysis"))
import buscost as B
# Display geometry, and it must match tools/bench/crtc_mode.lua: 256-colour
# page, one pixel per WORD of CPU address space, 1024-byte line stride, picture
# in rows 32..223 of a 256-row page. GVRAM is at a fixed $C00000 on every
# X68000, which is what makes an absolute destination address a legitimate
# thing for an encoder to bake into a stream (FINDINGS 30.2).
GVRAM, YOFF, STRIDE = 0xC00000, 32, 1024
# The two chains, and these must match tools/bench/blit.s v7 exactly.
COARSE_PX, COARSE_CODE, COARSE_N = 24, 12, 11
FINE_PX, FINE_CODE, FINE_N = 2, 2, 11
SPAN_HDR = B.V7_SPAN_HDR # {u32 address, u16 coarse disp} + u16 fine
BYTES_PX = 2 # word-expanded, high byte discarded by gvram_w
def split(npix):
"""(coarse units, fine units) for a span of npix pixels. Exact: npix is a
multiple of 4 for any real span, and 4 is a multiple of the 2-pixel fine
quantum, so nothing is padded."""
if npix % FINE_PX:
raise ValueError(f"span of {npix} px is not a multiple of {FINE_PX}")
c, r = divmod(npix, COARSE_PX)
f = r // FINE_PX
if c > COARSE_N or f > FINE_N:
raise ValueError(f"span of {npix} px exceeds the chain "
f"({c} coarse > {COARSE_N} or {f} fine > {FINE_N})")
return c, f
def clocks(npix):
"""68000 clocks to paint one span of npix pixels (MEASURED, FINDINGS 40)."""
c, f = split(npix)
return (B.V7_SPAN_CYC + c * COARSE_PX * B.V7_CPX_CYC
+ f * FINE_PX * B.V7_FPX_CYC)
def run_clocks(L):
"""Clocks for a run of L blocks: four spans of 4L pixels."""
return 4.0 * clocks(4 * L)
def run_bytes(L):
"""Container bytes for a run of L blocks."""
return 4 * (SPAN_HDR + 4 * L * BYTES_PX)
def dest(y, x):
"""Absolute GVRAM address of picture pixel (x, y)."""
return GVRAM + (YOFF + y) * STRIDE + x * 2
def dirty_runs(mode2d, nbx):
"""Maximal runs of horizontally adjacent non-SKIP blocks, per block row."""
for by in range(mode2d.shape[0]):
d = mode2d[by] != 0
i = 0
while i < nbx:
if not d[i]:
i += 1
continue
j = i
while j < nbx and d[j]:
j += 1
yield by, i, j
i = j
# Per-block decode cost, the same measured table vq_hybrid.cycles() uses --
# imported rather than copied, because session 12 corrected one of them and a
# second copy is how a corrected constant stops being corrected everywhere.
import vq_hybrid as _H
C_SKIP_MIXED = _H.C_SKIP_MIXED # a spanned block still pays its dispatch
BLK_CLK = {1: _H.C_V1, 2: _H.C_V4, 3: _H.C_RAW}
BLK_BYT = {1: 1, 2: 4, 3: 16}
def select(mode, src_idx, nbx, nby, byte_room, need_clocks=None,
idx_bytes=1):
"""Choose which runs to paint as spans.
`mode` 1-D mode map, modified nowhere (a new one is returned)
`src_idx` (H, W) palettised source -- what the spans will carry
`byte_room` container bytes the frame may still spend
`need_clocks` stop as soon as the frame's decode cost is at or below this;
None spends every profitable byte instead (the model
tools/analysis/14_dmac_chain.py scores).
Ranked by clocks saved per byte spent, which is the same greedy 12 and 14
use. Selection is deliberately conservative in two ways and the reported
figures are exact rather than greedy: a run is only offered if the span
beats the blocks it replaces on cycles ALONE, and the saving credited here
ignores the extra all-SKIP header bytes spanning tends to create. The
caller recomputes the frame's real cost from the returned mode map.
Returns dict(mode, spanned, spans, bytes, clocks).
"""
m2 = np.asarray(mode).reshape(nby, nbx)
spanned = np.zeros((nby, nbx), bool)
cand = []
for by, i, j in dirty_runs(m2, nbx):
L = j - i
cur_c = sum(BLK_CLK[int(b)] for b in m2[by][i:j])
cur_b = sum(BLK_BYT[int(b)] * (idx_bytes if int(b) != 3 else 1)
for b in m2[by][i:j])
sc = run_clocks(L) + L * C_SKIP_MIXED # the dispatch still happens
if sc >= cur_c:
continue
db = run_bytes(L) - cur_b
cand.append(((cur_c - sc) / max(db, 1), cur_c - sc, db, by, i, j))
cand.sort(key=lambda s: -s[0])
# `need_clocks` is measured against the frame as it stands, so the loop
# tracks the real running total rather than a delta: a spanned run's blocks
# become SKIP, and four SKIPs sharing a header byte cost 53 cycles instead
# of 4x55, which the greedy's per-run delta does not see.
import vq_hybrid as H
cur = m2.copy()
total_b, total_c = 0.0, 0.0
chosen = []
for _, dc, db, by, i, j in cand:
if need_clocks is not None and H.cycles(cur) + total_c <= need_clocks:
break
if total_b + db > byte_room:
continue
total_b += db
total_c += run_clocks(j - i)
cur[by][i:j] = 0
spanned[by][i:j] = True
chosen.append((by, i, j))
spans = []
for by, i, j in sorted(chosen):
x, npix = i * 4, (j - i) * 4
for k in range(4):
y = by * 4 + k
spans.append((y, x, src_idx[y, x:x + npix].astype(np.uint8)))
spans.sort()
return dict(mode=cur.reshape(-1), spanned=spanned, spans=spans,
bytes=int(total_b), clocks=float(total_c))
def serialise(spans):
"""The span section of a frame record, exactly as blit.s v7 reads it.
u16 nspans
nspans * { u32 GVRAM address, u16 coarse disp, c*48 B pixels,
u16 fine disp, f*4 B pixels }
The fine displacement sits MID-STREAM rather than in the record because
that is what lets the decoder keep all 12 payload registers: the coarse
chain falls out into `move.w (a0)+,d0 / jmp` with d0 dead payload and a0
already pointing at it (FINDINGS 40.4).
Every field is big-endian and every span record is a multiple of 4 bytes
long (4 + 2 + 48c + 2 + 4f), so the section needs no internal padding.
"""
out = bytearray()
out += len(spans).to_bytes(2, "big")
for y, x, pix in spans:
c, f = split(len(pix))
w = np.zeros((len(pix), 2), np.uint8)
w[:, 1] = pix # high byte discarded by gvram_w
w = w.tobytes()
out += dest(y, x).to_bytes(4, "big")
out += ((COARSE_N - c) * COARSE_CODE).to_bytes(2, "big")
out += w[:c * COARSE_PX * 2]
out += ((FINE_N - f) * FINE_CODE).to_bytes(2, "big")
out += w[c * COARSE_PX * 2:]
return bytes(out)
def section_bytes(spans):
return 2 + sum(SPAN_HDR + len(p) * BYTES_PX for _, _, p in spans)
tools/encoder/vq_hybrid.py
+24 -1
View File
@@ -61,7 +61,30 @@ RAW_BYTES = 16.0 # literal palette bytes, never indices
# mode decision uses the ranking constant.
C_V1, C_V4, C_RAW = 299.9, 448.2, 400.4
C_SKIP_CLUSTERED = 53.0 / 4 # all-SKIP header byte: one tst.b for four
C_SKIP_MIXED = 45.0 # a SKIP block inside a mixed byte
# C_SKIP_MIXED WAS THE ONE CONSTANT HERE THAT HAD NEVER BEEN MEASURED. It was
# 45.0, hand-derived, from session 7 until session 12 measured it -- and it was
# 18% low. Every other figure in this table comes from a synthetic frame of a
# single mode, and there was no such frame for a SKIP in a MIXED byte, because
# a frame of nothing but mixed SKIPs cannot exist: the byte has to hold a coded
# block for the SKIP to be mixed at all.
#
# tools/bench/prep_dlx.py now emits four that bracket it -- (3 SKIP + 1 V1),
# (1 SKIP + 3 V1), (3 SKIP + 1 RAW), (1 SKIP + 3 RAW), each with the header byte
# ROTATED through all four positions so no mode is pinned to the free `lsr`
# slot -- and each pair solves for the SKIP cost and its partner's together:
#
# MAME C68K (the partner solves back to its own anchored
# V1 pair 55.03 56.50 value to 0.2%, which is what says the pair
# RAW pair 55.83 56.50 is measuring the SKIP and not absorbing it)
#
# 55.0 is taken because every other constant here is MAME's; C68K reads V4 and
# RAW 3.2-3.5% higher on pure frames too, which is FINDINGS 37's known table
# spread and not a property of mixed bytes.
#
# It matters more than 10 clocks a block sounds, because a v7 SPAN marks its
# run SKIP: a spanned container is made largely of mixed SKIPs, so this is the
# dominant population in exactly the frames spans are judged on. FINDINGS 41.5.
C_SKIP_MIXED = 55.0 # a SKIP block inside a mixed byte, MEASURED
C_SKIP_RANK = C_SKIP_CLUSTERED # ranking only -- see above
MODE_CYCLES = np.array([C_SKIP_RANK, C_V1, C_V4, C_RAW], dtype=np.float64)