prosolis
1be428c270
Two sessions, unrecorded until now, committed together because their edits share files and cannot be split cleanly after the fact. Session 28 (FINDINGS 60): the container is DLX5 -- every record sector-aligned, 120/120 starting on a boundary where 3/120 did, +0.48% on the wire and zero clocks -- and the ring's release rounds to RECALN so no pad is stranded. Two encoder levers measured and refused: `--spans all` buys +0.19 dB for +67% of the wire, and joint span/lam selection emits byte-identical containers because `lam` never leaves its floor on any of 120 frames. Session 29 (FINDINGS 61): the packed full-frame blit is 27.3% of a 12 fps frame, a channel fills GVRAM in buffer mode off the disc with the CPU halted, and it walks the 1,024 B line stride itself through array chaining. At the 9 clk/B dual-address floor the codec is 110.4% of a frame and a decoder-free packed literal player is 55.2%, at +4.89 dB -- 2.75 dB past a ceiling the codec's scene-wide palette cannot cross. Encoder work is parked; the codec is kept and not built on. check.sh is ALL GREEN before and after, plus one new stage that gates the ORDER of the measured paint costs rather than their values. Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6
505 lines
28 KiB
Python
505 lines
28 KiB
Python
#!/usr/bin/env python3
|
|
"""Rate control: hit a target bitrate exactly, so one encoder serves both targets.
|
|
|
|
USER DECISION (session 2): ship TWO quality modes, SASI and SCSI. The codec's
|
|
bitrate ceiling is a build parameter; the encoder is otherwise identical.
|
|
|
|
Mechanism: the hybrid encoder's lagrangian `lam` trades distortion for bytes
|
|
monotonically, so per frame we binary-search lam to land inside a byte budget.
|
|
A leaky bucket lets a quiet frame bank bytes that an action frame can spend --
|
|
without that, quiet frames waste budget and action frames stay ugly.
|
|
|
|
The ceiling is HARD: the 68000 streams at a fixed rate off the disk, and a frame
|
|
that overruns is a dropped frame, not a slow frame.
|
|
|
|
STATUS, session 6: WIRED IN and sound. `encode.py` rate-controls by default
|
|
for a profile; `--fixed-lam` restores the old behaviour. The lam-ladder of
|
|
session 5 was replaced by a per-frame bisection that drives the encoder one
|
|
frame at a time and feeds back the frame it actually emitted -- see
|
|
encode_rate_controlled(), and FINDINGS 26 for why the ladder could not be
|
|
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
|
|
# is unblocked, so they are deliberately conservative fractions of the quoted
|
|
# ceiling (audio, seeks and container overhead come out of the same pipe).
|
|
# Calibrated against the corrected rate-distortion curve (FINDINGS 14-15) AND
|
|
# against the bus and CPU budgets (FINDINGS 17). Session 2 initially set these
|
|
# far too low: 45 / 75 KB/s is 12% of the pessimistic SASI folklore figure and
|
|
# 7% of the SCSI one. Nothing justified that -- the numbers were read off the
|
|
# knee of the RD curve, not off the hardware.
|
|
#
|
|
# What actually bounds the high end:
|
|
# - Bus: unmeasured. ~300-500 KB/s SASI / ~1 MB/s SCSI, both FOLKLORE.
|
|
# This is the binding unknown and the reason the disk benchmark matters.
|
|
# - CPU: a full-frame blit is **53.6%** of the 12fps budget -- MEASURED on the
|
|
# emulated 68000, session 5, FINDINGS 24. This line previously said 38%,
|
|
# which was an estimate and was wrong by 41%. And 53.6% is a floor: MAME
|
|
# models no GVRAM wait states, so real hardware is worse.
|
|
# "Raising the bitrate is nearly free on CPU" survives but is now much
|
|
# tighter. It rests on RAW being the cheapest mode to blit, which is still
|
|
# true, but the display path alone now eats over half the frame before any
|
|
# decoding happens. The per-frame path choice of FINDINGS 25.6 (blit vs
|
|
# direct-to-GVRAM, whichever is cheaper for that frame) brings the median
|
|
# back to ~37% and caps the worst case at 53.6%.
|
|
# - Entropy coding is NOT the way to buy headroom here: deflate decode is
|
|
# ~216% of the frame budget on a 68000 and even LZ4 is ~54%. See FINDINGS 17.
|
|
# The rates below are therefore RAW payload, no entropy coding.
|
|
#
|
|
# `lam` here is a FLOOR, not a setting: encode.py rate-controls by default and
|
|
# bisects lam per frame in [lam, LAM_CLIFF] to keep under `kbps`. The floor is
|
|
# what a quiet frame is allowed to spend, so rate control can only ever spend
|
|
# less than session 5's fixed-lam encoder did. FINDINGS 27.
|
|
#
|
|
# THE `sasi` PROFILE IS GONE (session 9, USER DECISION). It was dropped on
|
|
# CAPACITY, not bandwidth: a SASI volume on this machine tops out at 40 MB, and
|
|
# the 22.8 minutes of unique scene footage on the source Blu-ray is 147 MB even
|
|
# at the 110 KB/s the profile targeted -- more than the whole 4-unit SASI
|
|
# address space, with nothing left for Human68k or the game. FINDINGS 32.
|
|
#
|
|
# That leaves ONE profile, which is also the end of the two-quality-mode
|
|
# decision of session 2. The 110 KB/s RATE POINT may still return under another
|
|
# name: a 1x SCSI CD-ROM sustains ~150 KB/s, below this profile, and CD-ROM is
|
|
# the only period medium with the capacity for the span-heavy stream. That is
|
|
# deferred to the blocked disk benchmark and the DMA-vs-PIO check (docs/
|
|
# BENCHMARK.md, FINDINGS 29.5), because every bandwidth figure here is folklore
|
|
# until one of them lands.
|
|
PROFILES = {
|
|
"scsi": dict(kbps=280, lam=10.0, k1=256, k4=256,
|
|
desc="Super/XVI, or CZ-6BS1 board in a 10MHz machine",
|
|
quality="39.4 dB on 00020 / 32.3 dB on 00146 / 29.9 dB on the "
|
|
"Singe window at 280.0 KB/s (session 5's fixed lam "
|
|
"gave 30.8 dB there, but at 381.6 KB/s)",
|
|
util="~275 KB/s = 28% of the 1 MB/s SCSI folklore figure"),
|
|
}
|
|
# lam=0 is PIXEL-EXACT against the palettised frame (0.00 dB loss) at ~450 KB/s
|
|
# of raw payload, and costs 53.6% of the CPU budget (not the 38% written here
|
|
# before session 5 -- FINDINGS 24). If the blocked disk
|
|
# benchmark confirms SCSI sustains >=800 KB/s, the `scsi` profile should become
|
|
# lam=0 and the port ships transparent video. That decision is waiting on a
|
|
# measurement, not on a design choice.
|
|
|
|
# Hard ceiling on the rate-control search. FINDINGS 15 puts the quality cliff
|
|
# between lam=800 and lam=2000. Above it a frame has not been rate-controlled,
|
|
# it has been destroyed, so the search stops here and lets the frame overrun
|
|
# instead (FINDINGS 26.2). The old ladder ran to lam=2e5, 250x past shippable.
|
|
LAM_CLIFF = 800.0
|
|
|
|
# Ceiling on the CYCLE search. mu prices a cycle in the same units lam prices a
|
|
# byte, so the scale that matters is set by their ratio: at a lam floor of 60
|
|
# (the retired `sasi` profile's, and the highest this codec has shipped),
|
|
# mu=0.2 makes a V1 block's 300 cycles cost what its 1 payload byte costs. MU_CLIFF=100 is three decades past that: a V1 block priced at 30,000
|
|
# distortion units.
|
|
#
|
|
# It does NOT freeze the picture, and that is the point. At MU_CLIFF a block
|
|
# only becomes SKIP if holding the previous reconstruction costs less than
|
|
# 28,665 units of distortion, so a frame with nothing on screen to hold -- the
|
|
# first frame of a stream, or a scene cut -- stays fully coded and comes out at
|
|
# the all-V1 floor of 110.6% (FINDINGS 28.5). Such a frame is emitted LATE on
|
|
# purpose, exactly as a frame that will not fit at LAM_CLIFF is emitted over
|
|
# budget. Freezing a cut to make the deadline would be the worse failure.
|
|
MU_CLIFF = 100.0
|
|
MU_FLOOR = 1e-4 # bisection is geometric, so lo must be > 0
|
|
|
|
# The hard per-frame decode budget. NOT a bucket: bytes can be banked in the
|
|
# player's ring buffer, but there is no double buffer to decode ahead into, so
|
|
# a frame that misses its deadline is simply late. FINDINGS 28.
|
|
FRAME_CYCLES = 10_000_000 / 12.0
|
|
|
|
# What one delivered byte costs the 68000, in clocks of that same budget. The
|
|
# SCSI DMA does not overlap with the CPU -- it steals the bus (FINDINGS 38.3) --
|
|
# and the MB89352 is an 8-bit port, so the DMAC pays PER BYTE and not per word
|
|
# (FINDINGS 43). 5.0 is the floor: single-address device-to-memory, bus held,
|
|
# zero drive wait (MC68450 Fig 4-25 sheet 2). Dual-address costs 9.
|
|
# 0.0 restores the pre-43 encoder, which priced a byte at nothing.
|
|
DISK_CLK_BYTE = 5.0
|
|
|
|
# Does the MODE DECISION see that debit, or only the fit test above it?
|
|
# FINDINGS 43.6 charged the disk inside the rate controller's ceiling but left
|
|
# vq_hybrid.decide() ranking modes with a free byte, so `mu` still bought
|
|
# cycles by moving V4 -> RAW: 47.8 cycles saved for 12 extra payload bytes,
|
|
# which at any c >= 4 clocks/byte is a net LOSS on the very budget mu is
|
|
# enforcing. True makes `decide` price a byte at `lam + mu*DISK_CLK_BYTE`.
|
|
#
|
|
# IT IS OFF, AND THAT IS A MEASUREMENT, NOT AN OVERSIGHT (FINDINGS 44). The
|
|
# inconsistency is real and the fix is a wash: on the 120-frame Singe window at
|
|
# c=5 it delivers 482.5 KB/s / 29.17 dB against 496.7 / 29.19, the same 1/120
|
|
# frames over budget, the same 112.9% worst frame, and 5,389 MORE clocks in the
|
|
# mean frame -- it buys 6,058 clocks of disk with 17,207 clocks of block
|
|
# decode. Scored at c=4 and c=9 as well, it is marginally the worse container
|
|
# at every price. `--joint-decide` turns it on.
|
|
JOINT_DECIDE = False
|
|
|
|
# The leaky bucket lets a quiet frame bank bytes for a busy one, because the
|
|
# player's ring buffer can hold them. True when a byte was only a byte. A byte
|
|
# is now also DISK_CLK_BYTE clocks of the frame's decode budget, and FINDINGS 28
|
|
# established there is no double buffer to decode ahead into -- so a frame that
|
|
# borrows bytes from the bucket borrows clocks it cannot repay (FINDINGS 43.5).
|
|
# True caps the borrow at what the clock budget can still absorb; the bucket
|
|
# then smooths only what is left after the disk is paid. It never caps BELOW
|
|
# the frame's own un-banked byte budget: that is rate control's job, not the
|
|
# clock budget's.
|
|
#
|
|
# IT IS OFF, AND THAT IS A MEASUREMENT (FINDINGS 44). At `--spans all`, the
|
|
# mode this project now recommends, the byte-side controller is INERT: a
|
|
# 32-frame bucket and an 8-frame bucket emit the same container byte for byte,
|
|
# and lam never leaves its floor on any of 120 frames. The cap is worth one
|
|
# frame of 120 at `--spans need` (2/120 -> 1/120, for +26 KB/s) and is a 2%
|
|
# regression at `all` (506.4 KB/s and 89.6% median frame against 496.7 and
|
|
# 87.9%), because capping the block payload only moves those bytes into the
|
|
# span section, which draws on its own flat pipe. Extending the cap to the
|
|
# span section too was measured and is much worse: 273.7 KB/s, 28.88 dB, and
|
|
# still 1/120 -- it starves the pass that was buying the deadline.
|
|
# `--joint-bucket` turns it on.
|
|
JOINT_BUCKET = False
|
|
|
|
# E3 / FINDINGS 39.3 item 5: SPAN SELECTION IS GREEDY AFTER `lam`, and this is
|
|
# the switch that makes the two joint. The lam bisection picks a mode map
|
|
# against a byte allowance, and the span pass then REMOVES the block payload of
|
|
# every block it covers -- so the frame lands under the allowance by exactly
|
|
# the bytes the spans freed, and the blocks that were NOT spanned were priced
|
|
# at a lam chosen as if those bytes were still needed. Joint mode hands the
|
|
# freed bytes back to the lam search and re-spans the result, to a fixed point
|
|
# or two rounds, whichever comes first.
|
|
#
|
|
# It is a REFINEMENT, not a different objective: lam can only fall (the
|
|
# allowance only grows), so the un-spanned blocks can only improve, and a round
|
|
# is kept only if the frame still fits both ceilings it was already fitting.
|
|
# Default OFF until measured, which is 44.3's lesson -- ask whether the lever
|
|
# is loaded before pulling it.
|
|
JOINT_SPANS = False
|
|
JOINT_SPAN_ROUNDS = 2
|
|
|
|
|
|
def _byte_clk():
|
|
"""The debit the mode decision is allowed to see (0 = the old decision)."""
|
|
return DISK_CLK_BYTE if JOINT_DECIDE else 0.0
|
|
|
|
AUDIO_KBPS = 7.8 # MSM6258 ADPCM 15.6kHz mono -- comes out of the same budget
|
|
|
|
|
|
def frame_budget(kbps, fps=12, audio=AUDIO_KBPS):
|
|
"""bytes per video frame after audio takes its cut"""
|
|
return (kbps - audio) * 1024.0 / fps
|
|
|
|
|
|
def _search_lam(ctx, allow, lam_lo, lam_hi, iters=12, mu=0.0):
|
|
"""Smallest lam (=> best quality) whose frame fits `allow` bytes.
|
|
|
|
Payload size is non-increasing in lam -- raising lam can only move a block
|
|
to a mode that costs no more -- so bisection is sound. Geometric bisection,
|
|
because lam spans three decades and the interesting range is multiplicative.
|
|
|
|
Returns (lam, mode, size, overrun). `overrun` is True when even lam_hi does
|
|
not fit: that frame is emitted over budget on purpose. Past the FINDINGS 15
|
|
cliff a frame is not rate-controlled, it is destroyed, so a visible overrun
|
|
is the better failure (FINDINGS 26.2)."""
|
|
bc = _byte_clk()
|
|
mode, sz = H.decide(ctx, lam_lo, mu, bc)
|
|
if sz <= allow:
|
|
return lam_lo, mode, sz, False
|
|
mode_hi, sz_hi = H.decide(ctx, lam_hi, mu, bc)
|
|
if sz_hi > allow:
|
|
return lam_hi, mode_hi, sz_hi, True
|
|
lo, hi = lam_lo, lam_hi # lo does not fit, hi does
|
|
best = (lam_hi, mode_hi, sz_hi)
|
|
for _ in range(iters):
|
|
mid = float(np.sqrt(lo * hi))
|
|
mode_m, sz_m = H.decide(ctx, mid, mu, bc)
|
|
if sz_m <= allow:
|
|
hi = mid; best = (mid, mode_m, sz_m)
|
|
else:
|
|
lo = mid
|
|
return best[0], best[1], best[2], False
|
|
|
|
|
|
def _search_mu(ctx, allow, lam_lo, lam_hi, cyc_budget, iters=10):
|
|
"""Smallest mu whose frame fits BOTH budgets: `allow` bytes and
|
|
`cyc_budget` 68000 cycles.
|
|
|
|
Two controllers, one nested inside the other, because the constraints are
|
|
not separable. Raising mu moves blocks to cheaper-to-DECODE modes, which
|
|
usually also shrinks the frame -- but not always: RAW is 400 cycles against
|
|
V4's 448 and 16 bytes against 4, so mu can buy cycles by SPENDING bytes
|
|
(FINDINGS 28.8). So every mu step re-runs the lam bisection and the byte
|
|
budget is enforced at the mu that is actually chosen.
|
|
|
|
Cost is scored with H.cycles(), the exact clustered rule, NOT with the
|
|
per-block ranking constant the decision uses -- see vq_hybrid's note on
|
|
SKIP. The controller therefore converges on what the 68000 will really do.
|
|
|
|
Monotonicity: at a fixed lam, raising mu can only move a block to a mode
|
|
that costs no more cycles, and it can only ADD to a SKIP cluster, so frame
|
|
cycles are non-increasing in mu. The nested lam re-search can perturb that
|
|
at the margin (a smaller frame permits a smaller lam, which buys quality
|
|
back and can cost a few cycles), so the bisection keeps the best FEASIBLE
|
|
point it has actually seen rather than trusting the invariant.
|
|
|
|
Returns (mu, lam, mode, size, cyc, over_bytes, over_cycles)."""
|
|
lam, mode, sz, ovr = _search_lam(ctx, allow, lam_lo, lam_hi, mu=0.0)
|
|
cyc = H.cycles(mode)
|
|
if cyc + DISK_CLK_BYTE * sz <= cyc_budget:
|
|
return 0.0, lam, mode, sz, cyc, ovr, False
|
|
|
|
lam_h, mode_h, sz_h, ovr_h = _search_lam(ctx, allow, lam_lo, lam_hi, mu=MU_CLIFF)
|
|
cyc_h = H.cycles(mode_h)
|
|
if cyc_h + DISK_CLK_BYTE * sz_h > cyc_budget: # cannot fit even frozen
|
|
return MU_CLIFF, lam_h, mode_h, sz_h, cyc_h, ovr_h, True
|
|
|
|
lo, hi = MU_FLOOR, MU_CLIFF # lo overruns, hi fits
|
|
best = (MU_CLIFF, lam_h, mode_h, sz_h, cyc_h, ovr_h)
|
|
for _ in range(iters):
|
|
mid = float(np.sqrt(lo * hi))
|
|
lam_m, mode_m, sz_m, ovr_m = _search_lam(ctx, allow, lam_lo, lam_hi, mu=mid)
|
|
cyc_m = H.cycles(mode_m)
|
|
if cyc_m + DISK_CLK_BYTE * sz_m <= cyc_budget:
|
|
hi = mid; best = (mid, lam_m, mode_m, sz_m, cyc_m, ovr_m)
|
|
else:
|
|
lo = mid
|
|
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, disk_clk_byte=DISK_CLK_BYTE, base_bytes=sz)
|
|
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 _refit_joint(m, ctx, allow, span_allow, lam_lo, lam_hi, cyc_budget,
|
|
span_mode, ib, mode_pre, mode, sz, cyc, sel, mu=0.0):
|
|
"""Give the lam search back the bytes the span pass freed, then re-span.
|
|
|
|
`mode_pre` is the mode map BEFORE spanning and `mode` the one after, so the
|
|
difference in frame_bytes is exactly what the spans made unnecessary. The
|
|
ceiling the result is judged against is the one _fit_spans was already
|
|
working to, so a kept round is never a frame that grew past a budget it was
|
|
inside.
|
|
"""
|
|
ceiling = span_allow if span_allow is not None else allow
|
|
for _ in range(JOINT_SPAN_ROUNDS):
|
|
if sel is None:
|
|
break
|
|
freed = (H.frame_bytes(mode_pre, ctx["nb"], ib)
|
|
- H.frame_bytes(mode, ctx["nb"], ib))
|
|
if freed <= 0:
|
|
break
|
|
lam2, mode2, sz2, _ = _search_lam(ctx, allow + freed, lam_lo, lam_hi, mu=mu)
|
|
if sz2 <= H.frame_bytes(mode_pre, ctx["nb"], ib):
|
|
break # lam did not move: already at the floor
|
|
n_pre, n_mode, n_sz, n_cyc, n_sel = (
|
|
mode2, *_fit_spans(m, ctx, mode2, sz2, span_allow if span_allow
|
|
is not None else allow, cyc_budget, span_mode, ib))
|
|
if n_sel is None or n_sz > ceiling:
|
|
break
|
|
if cyc_budget is not None and n_cyc + DISK_CLK_BYTE * n_sz > cyc_budget \
|
|
and cyc + DISK_CLK_BYTE * sz <= cyc_budget:
|
|
break # round 1 made the deadline and this does not
|
|
mode_pre, mode, sz, cyc, sel = n_pre, n_mode, n_sz, n_cyc, n_sel
|
|
return mode_pre, mode, sz, cyc, 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,
|
|
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.
|
|
|
|
That feedback is the whole point. The previous implementation encoded the
|
|
sequence once per lam and then picked frames off the resulting ladder; the
|
|
codec is temporally recursive, so frames picked from different rungs
|
|
reference reconstructions the decoder never saw -- 111 of 120 frames drifted,
|
|
worst frame 43.4% (FINDINGS 26.1). `tools/analysis/09_ratectl_drift.py` is
|
|
the regression test and must report zero drifting frames.
|
|
|
|
lam_lo is a QUALITY FLOOR, not a starting guess: rate control here only ever
|
|
spends less than the fixed-lam profile, never more, so it cannot regress
|
|
content that already fits. Pass lam_lo=1.0 to let quiet frames spend the
|
|
whole allowance instead.
|
|
|
|
`prefill` is how full the player's buffer is assumed to be when the scene
|
|
starts, as a fraction of the bucket. 0.0 (the default) is the conservative
|
|
assumption -- a cold buffer after a seek -- and is what FINDINGS 21 verified
|
|
needs no prefill to avoid underflow. It costs a startup transient: the first
|
|
`bucket_frames` frames cannot draw on a bank they have not accumulated yet,
|
|
so a clip shorter than a few bucket depths lands UNDER target. That is an
|
|
artefact of the clip length, not of the content; see FINDINGS 27.5.
|
|
|
|
DO NOT raise `prefill` to make a target look met. It works by permitting an
|
|
overshoot of cap/nframes: measured, prefill=1.0 takes the Singe window from
|
|
109.5 to 116.3 KB/s against a 110 ceiling, and on a 14-frame clip it
|
|
disables rate control entirely because the bucket is larger than the clip.
|
|
|
|
`cycle_budget` adds the SECOND controller (session 8): a hard per-frame
|
|
68000 decode ceiling, bisected on `mu` inside the lam search. None (the
|
|
default) leaves it off and reproduces session 6 exactly, which is what
|
|
keeps tools/analysis/09_ratectl_drift.py comparable. Pass
|
|
FRAME_CYCLES for the 12fps stock-68000 budget.
|
|
|
|
`steps` is accepted and ignored -- there is no ladder any more.
|
|
"""
|
|
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=[], 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
|
|
# 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).
|
|
hard = None
|
|
if (JOINT_BUCKET and cycle_budget is not None and DISK_CLK_BYTE > 0):
|
|
# What can this frame's clock budget still absorb, once its own
|
|
# block decode is paid? Priced at the mode map the UN-banked budget
|
|
# buys, so the cap is a property of the frame's content rather than
|
|
# of how full the bucket happens to be.
|
|
_, mode0, _, _ = _search_lam(ctx, budget, lam_lo, lam_hi)
|
|
hard = (cycle_budget - H.cycles(mode0)) / DISK_CLK_BYTE
|
|
allow = min(allow, max(budget, hard))
|
|
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 + DISK_CLK_BYTE * sz > cycle_budget)):
|
|
mode_pre = mode
|
|
mode, sz, cyc, sel = _fit_spans(m, ctx, mode, sz, span_allow,
|
|
cycle_budget, span_mode, ib)
|
|
if JOINT_SPANS:
|
|
mode_pre, mode, sz, cyc, sel = _refit_joint(
|
|
m, ctx, allow, span_budget and span_allow, lam_lo, lam_hi,
|
|
cycle_budget, span_mode, ib, mode_pre, mode, sz, cyc, sel)
|
|
if cycle_budget is not None and cyc + DISK_CLK_BYTE * sz > 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)
|
|
if span_mode:
|
|
mode_pre = mode
|
|
mode, sz, cyc, sel = _fit_spans(m, ctx, mode, sz, span_allow,
|
|
cycle_budget, span_mode, ib)
|
|
if JOINT_SPANS:
|
|
mode_pre, mode, sz, cyc, sel = _refit_joint(
|
|
m, ctx, allow, span_budget and span_allow, lam_lo,
|
|
lam_hi, cycle_budget, span_mode, ib, mode_pre, mode,
|
|
sz, cyc, sel, mu=mu)
|
|
late = cyc + DISK_CLK_BYTE * sz > 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"], 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"]),
|
|
late=np.array(out["late"]),
|
|
nb=m["nb"], budget=budget, cap=cap, cycle_budget=cycle_budget)
|
|
|
|
|
|
def summarise(m, enc, target_kbps, fps=12):
|
|
import vq as VQ
|
|
pal = m["pal"]
|
|
rec = [pal[i] for i in enc["recon"]]
|
|
src = [pal[i] for i in m["idx"]]
|
|
p = np.mean([VQ.psnr(o, v) for o, v in zip(m["rgb"], rec)])
|
|
pp = np.mean([VQ.psnr(o, v) for o, v in zip(m["rgb"], src)])
|
|
sz = enc["sizes"]
|
|
mo = np.concatenate(enc["modes"])
|
|
d = dict(target=target_kbps, psnr=p, pal=pp, loss=pp - p,
|
|
mean_B=sz.mean(), max_B=sz.max(), budget=enc.get("budget", 0.0),
|
|
kbps=sz.mean() * fps / 1024 + AUDIO_KBPS,
|
|
over=100.0 * np.mean(sz > enc.get("budget", np.inf)),
|
|
skip=100 * (mo == 0).mean(), v1=100 * (mo == 1).mean(),
|
|
v4=100 * (mo == 2).mean(), raw=100 * (mo == 3).mean())
|
|
if "cycles" in enc:
|
|
cy = np.asarray(enc["cycles"])
|
|
d.update(cyc_med=float(np.median(cy)), cyc_max=float(cy.max()),
|
|
cyc_p90=float(np.percentile(cy, 90)),
|
|
cpu_miss=int((cy > FRAME_CYCLES).sum()),
|
|
mu_med=float(np.median(enc["mu"])),
|
|
mu_max=float(np.asarray(enc["mu"]).max()),
|
|
late=int(np.asarray(enc.get("late", [])).sum()))
|
|
if "lam" in enc:
|
|
lam = enc["lam"]
|
|
d.update(lam_med=float(np.median(lam)), lam_max=float(lam.max()),
|
|
lam_p90=float(np.percentile(lam, 90)),
|
|
# a frame that could not fit even at the cliff: emitted over
|
|
# budget on purpose rather than destroyed
|
|
overrun=int(np.asarray(enc.get("overrun", [])).sum()))
|
|
return d
|