#!/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, disk_clk_byte=0.0, base_bytes=0): """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 cost is at or below this; None spends every profitable byte instead (the model tools/analysis/14_dmac_chain.py scores). `disk_clk_byte` what a delivered byte costs the 68000 in clocks, because the SCSI DMA steals the bus from it (FINDINGS 43). 0.0 is the pre-43 behaviour: bytes are free and a span is judged on decode clocks alone. At the real value a span's two wire bytes per pixel are the dominant term and the ranking inverts on short runs. `base_bytes` the frame's byte count before any span is added, so the running total this loop compares against `need_clocks` can include the disk debit the frame is already carrying. Ranked by clocks saved per byte spent, which is the same greedy 12 and 14 use. A run is only offered if the span beats the blocks it replaces on TOTAL clocks -- decode plus the disk debit of the bytes it adds -- which at `disk_clk_byte`=0 reduces to the cycles-alone test this used before FINDINGS 43. Selection is otherwise deliberately conservative and the reported figures are exact rather than greedy: 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 db = run_bytes(L) - cur_b # TOTAL saving: decode clocks won, less the clocks the extra bytes cost # on the way in. With disk_clk_byte=0 this is (cur_c - sc) exactly. net = (cur_c - sc) - disk_clk_byte * db if net <= 0: continue cand.append((net / 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 + disk_clk_byte * (base_bytes + total_b) <= 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)