From badda070ef59a2a6b4ba4b1f9a6766d781e36384 Mon Sep 17 00:00:00 2001 From: enricobuehler Date: Sat, 1 Aug 2026 00:47:04 +0200 Subject: [PATCH] docs(android): the stats-array KDoc counts the doubles it actually returns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit nativeVideoStats grew to 33 with the decode split and the overflow counter, but its own KDoc still promised 30 and StatsOverlay still said 26 — a count that was already two extensions stale before this one. Both now list the full index set, with the JNI KDoc named as the authoritative one so the next extension has a single place to update. Co-Authored-By: Claude Fable 5 --- .../main/kotlin/io/unom/punktfunk/StatsOverlay.kt | 8 +++++--- .../kotlin/io/unom/punktfunk/kit/NativeBridge.kt | 12 +++++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/clients/android/app/src/main/kotlin/io/unom/punktfunk/StatsOverlay.kt b/clients/android/app/src/main/kotlin/io/unom/punktfunk/StatsOverlay.kt index 8160226d..d5195d9a 100644 --- a/clients/android/app/src/main/kotlin/io/unom/punktfunk/StatsOverlay.kt +++ b/clients/android/app/src/main/kotlin/io/unom/punktfunk/StatsOverlay.kt @@ -18,11 +18,13 @@ import kotlin.math.roundToInt * The live stats overlay — the unified HUD (`design/stats-unification.md`): headline is * `capture→displayed` tiled by `host+network` + `decode` + `display` when the platform delivered * OnFrameRendered render callbacks this window (`dispValid`), falling back to the v1 - * `capture→decoded` headline without the `display` term when it didn't. Reads the 26-double - * layout from [NativeBridge.nativeVideoStats]: + * `capture→decoded` headline without the `display` term when it didn't. Reads the 33-double + * layout from [NativeBridge.nativeVideoStats] (that KDoc is the authoritative index list): * `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skew, w, h, hz, lostTotal, bitDepth, colorPrimaries, * colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms, netP50Ms, lost, skipped, - * fec, frames, dispValid, displayP50Ms, e2eDispP50Ms, e2eDispP95Ms]`. + * fec, frames, dispValid, displayP50Ms, e2eDispP50Ms, e2eDispP95Ms, paceP50Ms, latchP50Ms, + * presentsWindow, presenterActive, feedP50Ms, codecP50Ms, skippedOverflowWindow]`. Every read + * is length-guarded, so an older native lib simply omits the lines it can't feed. * * [verbosity] selects how many lines render (each tier a superset of the last — see * [StatsVerbosity]): diff --git a/clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/NativeBridge.kt b/clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/NativeBridge.kt index ed03a18c..2875c5bb 100644 --- a/clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/NativeBridge.kt +++ b/clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/NativeBridge.kt @@ -248,11 +248,12 @@ object NativeBridge { /** * Drain ~1 s of live decode stats for the on-stream HUD, or `null` when no decode thread runs. - * Returns 30 doubles (unified stats spec, `design/stats-unification.md`): + * Returns 33 doubles (unified stats spec, `design/stats-unification.md`): * `[fps, mbps, e2eP50Ms, e2eP95Ms, latValid, skewCorrected, width, height, refreshHz, framesLost, * bitDepth, colorPrimaries, colorTransfer, chromaFormatIdc, hostNetP50Ms, decodeP50Ms, hostP50Ms, * netP50Ms, lostWindow, skippedWindow, fecWindow, framesWindow, dispValid, displayP50Ms, - * e2eDispP50Ms, e2eDispP95Ms, paceP50Ms, latchP50Ms, presentsWindow, presenterActive]` + * e2eDispP50Ms, e2eDispP95Ms, paceP50Ms, latchP50Ms, presentsWindow, presenterActive, + * feedP50Ms, codecP50Ms, skippedOverflowWindow]` * (the flags are 1.0/0.0; indexes 2/3 are the end-to-end capture→decoded headline; 10–13 * describe the negotiated video feed — bit depth 8/10, CICP primaries/transfer, and the HEVC * chroma_format_idc 1=4:2:0 / 3=4:4:4; 14/15 are the stage p50s tiling the headline — @@ -263,7 +264,12 @@ object NativeBridge { * `display` stage from the OnFrameRendered render timestamps — when `dispValid` is 1.0 the * headline becomes the directly-measured capture→displayed pair at 24/25, tiled by * `host+network` + `decode` + `display` (23), and when 0.0 the HUD falls back to the - * capture→decoded headline at 2/3 without the `display` term). + * capture→decoded headline at 2/3 without the `display` term; 26–29 split the `display` + * term the timeline presenter owns — `pace` = decoded→release, `latch` = release→displayed, + * the window's on-glass confirm count, and whether the presenter is active at all; 30/31 + * split `decode` (15) the same way — `feed` = received→queued (hand-off + input-slot wait), + * `codec` = queued→decoded, the decoder's own time; 32 is the parked-AU overflow subset of + * `skipped` (19), i.e. the decoder falling behind rather than benign newest-wins pacing). * Poll ~1 Hz; each call resets the measurement window. */ external fun nativeVideoStats(handle: Long): DoubleArray?