WP1 of design/presenter-cadence-rework-implementation-plan.md. Shared core
type plus the Android binding; desktop and Apple follow.
Every stat we publish is a latency — a difference between two points on one
frame. No latency can see judder, because judder is a property of the
SEQUENCE. A stream that shows each frame one refresh early and the next one
late has excellent percentiles and looks broken; a stream whose every
interval is exactly two refreshes has worse latency than one alternating 1
and 3, and looks perfect. That blind spot is why a smoothness complaint
could not be confirmed or refuted from our own telemetry.
PresentIntervals quantises the spacing between consecutive on-glass instants
onto the learned panel grid and reports the modal spacing plus the fraction
of intervals that miss it — the judder number, in permille to match the
phase coherence already next to it. Scale-free: the mode absorbs the cadence
ratio, so 60-on-120 and 120-on-120 are both "one tall bucket" and directly
comparable. That is what makes it usable as one ruler across clients,
refresh rates and stream rates, and for a feature-on/off A/B.
Deliberate choices, each with a test:
- fed the MEASURED on-glass instant, never the requested present time,
which would measure our own intent and always look perfect
- fed SurfaceFlinger's raw CLOCK_MONOTONIC render stamp, not the
realtime-rebased one the latency stats use: cadence is about spacing,
and a realtime clock step would forge a hitch that never happened
- stalls (>8 refreshes) and out-of-order callbacks counted apart from the
ratio, so a window that looks smooth because the stream was PAUSED
cannot be mistaken for a good one
- sub-refresh jitter is not judder: the display quantises it away, so the
metric must too
- the predecessor survives a window drain, else one interval per window
would go unscored forever
Always-on via the 1 Hz pf.present line, so the HUD-off wireless A/B the
baseline measurement needs is readable from logcat. HUD surfacing waits on
the stats-unification spec amendment (plan S3) and on the in-flight HUD work.
Gates: punktfunk-core 189 tests green (10 new); cargo ndk check + clippy
arm64 clean — the 5 remaining warnings are pre-existing and in other files.
enricobuehler
fc5b6296e3