#!/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)