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

Put the ring on the 68000, and find the disc stops whenever the player is not asking

Browse Source 
ROADMAP P5. The loader moved in session 21 and the frame clock in 22; the ring
producer was the last policy living outside the machine. src/player/ring.i does
`aligned` placement, the descriptor ring, a prefill, 51.2's slack rule and a
seek, and the host keeps only the transport.

It needed a container change. `aligned` asks whether the next record fits
before the end of the ring -- a length asked BEFORE the record is fetched -- and
every reader in this tree answered that by walking the frame stream, which is
exactly what a player streaming off a disc cannot do. DLX4 carries nframes u16
record lengths in the scene header. Frame payloads are byte-identical to the
DLX3 encode, so no fitted constant moves; the scene header goes 5,920 to 6,164 B.

The producer reproduces the host's tiling exactly: 18 wraps, 14.7 KB mean hole,
pixel-exact, a third independent implementation of the same policy.

What it exposed is bigger than the item. A 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, not the medium -- and no host-filled run
could see it. At 488 KB/s in a 256 KB ring a one-deep request queue gives away
6.8% of the pipe and underruns 59 of 120 frames; two-deep gives away 3.4% and
underruns none. The container's whole surplus over the wire is 8.7%, so the
player's own loop was spending most of the slack a branch point saves up.
Prefill is the weaker lever: six records of it still leaves 24 underruns.

Three silent bugs are recorded in FINDINGS 55.7 -- all produced wrong pixels or
a desync rather than a fault -- plus a rig one: MAME renders a screen line by
line, so snapshotting the frame the decoder finished in captures a tear that
reads exactly like a decoder bug.

check.sh gains the machine-owned ring and a seek with the decode after it.
decode.bin is unchanged at 1,296 B and a host-filled run executes none of the
new code, so every FINDINGS 49/51 figure stands. ALL GREEN before and after.

Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6
This commit is contained in:
prosolis
2026-08-24 21:45:05 -07:00
parent c419251266
commit 2676f3b835
16 changed files with 1880 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/encoder/dlx.py
+30 -1
View File
@@ -38,14 +38,16 @@ 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", b"DLX3"):
if b[:4] not in (b"DLX1", b"DLX2", b"DLX3", b"DLX4"):
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.has_index = self.version >= 4
(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])
off_idx = struct.unpack(">I", b[32:36])[0] if self.has_index else None
self.pal = np.frombuffer(b, np.uint8, 256 * 3, off_pal).reshape(256, 3)
self.cb1 = np.frombuffer(b, np.uint8, self.k1 * 16,
@@ -77,6 +79,33 @@ class DLX:
raise ValueError(f"{path}: {slack} trailing bytes after "
f"{self.nframes} frames")
# DLX4's record index, and it is CHECKED rather than trusted. The
# walk above is what every reader in this tree did before there was an
# index -- read a record's length word to find the next one -- and it is
# exactly what a player streaming off a disc cannot do, because the
# length word of record i+1 is one of the bytes it has not fetched. So
# the two are computed independently here and required to agree: the
# index is the producer's only source of record geometry, and an index
# that disagrees with the stream places records at wrong addresses,
# which the block loop reads without a bounds check (49.2).
self.index = None
if self.has_index:
self.index = list(struct.unpack(
f">{self.nframes}H", b[off_idx:off_idx + 2 * self.nframes]))
walked = [(-(4 + n) % 4 + 4 + n) // 4 for _, n in self.frames]
if self.index != walked:
bad = next(i for i in range(self.nframes)
if self.index[i] != walked[i])
raise ValueError(
f"{path}: record index disagrees with the frame stream at "
f"frame {bad}: index says {self.index[bad]} longwords, the "
f"stream is {walked[bad]}")
if off_frm + 4 * sum(self.index) != len(b):
raise ValueError(
f"{path}: the index accounts for "
f"{off_frm + 4 * sum(self.index)} bytes and the file is "
f"{len(b)} -- a producer trusting it would run off the end")
def modes(self, f):
o, _ = self.frames[f]
h = np.frombuffer(self.raw, np.uint8, self.mode_bytes, o)
tools/encoder/encode.py
+47 -7
View File
@@ -15,7 +15,7 @@ lets quiet frames spend the whole allowance and lands the mean ON target.
Container (little-endian is WRONG here -- the 68000 is big-endian, so every
multi-byte field is big-endian and the decoder can read it with a plain move.w):
header, 32 bytes
header, 32 bytes ('DLX4': 36 -- one more offset, see below)
0 'DLX2' magic ('DLX1' = the same, unaligned; still read)
4 u16 width, u16 height
8 u16 fps, u16 nframes
@@ -25,6 +25,23 @@ multi-byte field is big-endian and the decoder can read it with a plain move.w):
20 u32 cb1 offset (k1 * 16 bytes of palette indices)
24 u32 cb4 offset (k4 * 4 bytes)
28 u32 frames offset
32 u32 record index offset DLX4 ONLY. nframes * u16, each the length of
that frame's PADDED record in LONGWORDS --
i.e. (4 + payload + pad) / 4, the whole thing
the ring producer must place contiguously.
THE INDEX IS NOT A CONVENIENCE, AND IT IS NOT DERIVABLE ON THE MACHINE. The
`aligned` wrap policy (FINDINGS 49.3) requires the producer to know how long
the next record is BEFORE it fetches it, because that is what decides whether
it fits before the end of the ring or leaves a hole and restarts at the base.
Every reader in this tree up to DLX3 learned record boundaries by WALKING the
frame stream -- reading each record's length word to find the next -- which a
host with the whole file mapped can do and a player streaming off a disc
cannot: the length word of record i+1 is exactly one of the bytes it has not
fetched yet. A branching game needs the same structure a second time, to seek
to a branch point without reading what lies between.
Lengths are stored rather than offsets: 2 bytes a frame instead of 4, and the
offsets are a running sum the player builds once at scene load (u16 caps a
record at 262,140 B, asserted at write time).
then, per frame, each record starting on a 4-BYTE BOUNDARY (0-3 zero pad
bytes before it; a 68000 takes an address error, not a slow read, on an odd
`move.l` -- FINDINGS 28.3):
@@ -126,10 +143,26 @@ def write_container(path, m, frames, fps, k1, k4, span_mode):
cb1_b = m["cb1"].astype(np.uint8).tobytes()
cb4_b = m["cb4"].astype(np.uint8).tobytes()
off_pal = 32
off_pal = 36 if span_mode else 32
off_cb1 = off_pal + len(pal_b)
off_cb4 = off_cb1 + len(cb1_b)
off_frm = off_cb4 + len(cb4_b)
# DLX4: the record index sits with the palette and the codebooks, ahead of
# the frame stream, because it is part of what has to ARRIVE before frame 0
# can be decoded -- FINDINGS 53.5's scene header, and this adds to it.
idx_b = b""
if span_mode:
qlens = []
for i, rec in enumerate(frames):
n = 4 + len(rec)
n += -n % 4
q = n // 4
assert q <= 0xFFFF, (f"frame {i} is {n} B: a u16 longword count "
f"caps a record at 262,140 B")
qlens.append(q)
idx_b = struct.pack(f">{len(qlens)}H", *qlens)
off_idx = off_cb4 + len(cb4_b)
off_frm = off_idx + len(idx_b)
# DLX2: every frame record starts on a 4-byte boundary, including the
# first. Payload lengths are arbitrary, so end-to-end records land on odd
# addresses -- and `move.l (a0)+` at an odd address is an ADDRESS ERROR on
@@ -138,18 +171,25 @@ def write_container(path, m, frames, fps, k1, k4, span_mode):
# realigning at load time; the container now carries it.
tbl_pad = -off_frm % 4
off_frm += tbl_pad
hdr = ((b"DLX3" if span_mode else b"DLX2")
hdr = ((b"DLX4" 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)
if span_mode:
hdr += struct.pack(">I", off_idx)
assert len(hdr) == (36 if span_mode else 32), len(hdr)
frm_pad = 0
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)
fh.write(idx_b); fh.write(b"\0" * tbl_pad)
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
# DLX2/3 skipped the pad after the LAST record because nothing
# followed it. DLX4's index describes PADDED records, and a producer
# that trusts the index fetches that many bytes -- so the last
# record is padded too, and the file ends where the index says it
# does rather than up to 3 bytes short of it.
if span_mode or i + 1 < len(frames):
n = -(4 + len(rec)) % 4
fh.write(b"\0" * n); frm_pad += n
total = os.path.getsize(path)