mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-04 14:25:08 +00:00
perf(scroll): pace frames to the panel — 44→100 fps, stalls 14% → 0.02% (#523)
* perf(scroll): pace frames to the panel, not to a fixed sleep Scrolling ran at 44-46 fps on a 2x128x64 chain and 14-17% of frames took 41-53ms, which reads as judder. Four independent causes, each measured on the hardware; details and the diagnostic recipe are in docs/SCROLL_PERFORMANCE.md. The high-FPS loop slept a flat 8ms after every render. display() has already blocked on the panel's vsync by then, so that sleep was added to a wait that had happened: ~4ms of render plus 8ms put each iteration at ~12ms against a 10ms refresh grid, so every swap missed a refresh and the loop settled at 50fps while asking for 125 -- with no headroom, so a further 14% of frames slipped again. It now sleeps only the remainder, with a 1ms floor so plugin threads still get the GIL. ScrollHelper stepped position on a wall clock at 1/scroll_delay steps per second. Plugins set scroll_delay to the frame period, so that comparison sat exactly on its own threshold: a frame arriving a hair early moved zero pixels and rendered an identical frame, dirty-tracking skipped the swap, it returned in ~2ms, and the beat repeated. No scroll_delay value tunes that out -- a shorter delay trades stalled frames for periodic double-steps. Both modes now accumulate elapsed time at the same configured speed, so position stays proportional to real time. Sub-pixel blending goes back to off by default. It renders a half-step by mixing two adjacent columns, which on a coarse panel showing pixel-font text alternates crisp and smeared frames and reads as shimmer -- visibly worse than integer stepping on the hardware. Vegas mode still opts in. disk_cache uses orjson when importable, falling back to the stdlib. Encoding a ~1MB record drops from 14.8ms to 5.4ms end-to-end, and that work holds the GIL while a marquee is on screen. display_manager also checksummed the whole framebuffer twice per frame (dirty tracking, then the preview snapshot); the snapshot now takes the checksum the caller already computed. New src/common/scroll_config.py resolves scroll settings in one place. Five ticker plugins each hand-rolled this and disagreed: odds-ticker ranked the deprecated scroll_pixels_per_second above the documented scroll_speed/delay pair, and because that key carries a schema default the documented settings were dead for every user (ChuckBuilds/ledmatrix-plugins#408), while ledmatrix-leaderboard read the same key only as a fallback. The resolver also warns when a speed will not advance a whole number of pixels per refresh, which is the property that actually determines whether a scroll looks smooth. scripts/build_rgbmatrix_nogil.sh rebuilds the rgbmatrix binding so it releases the GIL. Upstream declares SwapOnVSync without nogil, unlike SetPixel/Clear/Fill beside it, so the render thread held the GIL for the whole vsync wait and starved background threads into long uninterruptible bursts. The script patches, builds and self-verifies into a scratch tree; --install backs up the original and rolls back if the service does not come back healthy. Measured after: 100 fps locked, no stalls observed, render thread down from 51% to 19% of one core. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(display): keep the panel swap locked to vsync while scrolling Dirty tracking skipped SwapOnVSync for byte-identical frames. That is the right call for static content, but SwapOnVSync is also what paces the render loop, so skipping it skips the wait for the panel: a duplicate frame returns in ~8ms instead of ~10ms on a 100Hz panel, advances the strip only 0.8px instead of 1.0px, and so makes the next frame more likely to repeat as well. The effect sustains itself once it starts. Measured over 20 minutes on a 2x128x64 chain, both scrollers configured identically at 100 px/s: leaderboard 10ms x35, 11ms x3 (clean) odds-ticker 10ms x26, 8ms x7, 15ms x5 (~20% duplicates mid-scroll) The duplicates were not end-of-cycle idling -- 38% of fast frames fell within 90s of a scroll completion against 35% of normal frames, a null result. The trigger is per-frame work: odds does more of it, and more variably, so it is first to land a frame that advances less than a whole pixel. Pushing an identical frame costs one canvas copy. Falling out of vsync lock costs smooth motion. Static content is untouched, because is_currently_scrolling() expires on its own inactivity threshold -- covered by test_stale_scrolling_state_stops_forcing_pushes so a plugin that stops scrolling without saying so cannot pin the panel into always-push. Also de-flakes test_snapshot_still_written_on_skip, which asserted a strict mtime increase between two writes that can land in the same filesystem tick; it failed about two runs in three on Windows regardless of the code under test. The file is now backdated before the check. 156 tests pass on the Pi. Not yet confirmed by eye on the panel. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(scroll): report the frame-time tail, and stop the row-major blit Two problems, both found by looking at the panel rather than the metric. The frame-stats line reported ONE instantaneous frame every 5 seconds -- about 1 frame in 500 -- printed beside a 100-frame average. Both hide exactly the fault they are used to chase: a 2ms duplicate and a 21ms double-wait average to precisely 10ms, so a ticker stalling on half its frames still reports a healthy "Avg FPS: 100.0". That reading cost several rounds of chasing the wrong layer. The line now aggregates every frame since the last log and reports median, p95, max, min, and explicit stall and skip rates (past 1.5x the median missed a refresh; under half never reached the panel, because dirty tracking skipped the swap so the frame never waited on vsync). On the hardware this now reads: leaderboard 100.0 fps over 501 frames | median 10.00ms p95 10.05ms max 10.34ms | stalls 0 (0.0%) skips 0 (0.0%) The binding rebuild's blit patch becomes opt-in (RGB_PATCH_BLIT=1, default off). Reordering that loop to row-major changes what a torn frame looks like: column-major tearing shows as a vertical seam, row-major as a horizontal split between the panel's upper and lower halves. On a 1/32 scan panel that reads as a one-pixel fold across the middle of every panel, which is what was reported on hardware and what went away when the blit was reverted. All of the measured gain comes from the SwapOnVSync change, so the risky half is simply not worth taking; the header says so. Also fixes --install resolving its paths against $HOME, which is /root under sudo, so it looked in /root/rgbmatrix-nogil-build and died with "no built module found" on a machine where the build had just succeeded. It now resolves SUDO_USER's home. Both build paths are verified on the Pi: default yields one GIL-release site, RGB_PATCH_BLIT=1 yields two. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(scroll): let users pick a crisp speed for their own panel Whole-pixel motion was previously only available at multiples of the refresh rate -- 100, 200, 300 px/s on a 100Hz panel. 100 px/s crosses a 256px panel in 2.6s, which is brisk for reading, and everything slower had to blend (blur) or repeat frames unevenly (judder). There was no way to ask for 50 px/s and get clean motion. SwapOnVSync takes a framerate_fraction the display manager never passed. It holds each frame for N panel refreshes; the panel keeps refreshing at its full rate throughout, so holding costs nothing in flicker and only changes how often a NEW image is presented. That turns 50 px/s into one whole pixel every second refresh instead of half a pixel every refresh. The crisp speeds are therefore refresh_hz / hold * pixels_per_frame, and that ladder depends on the panel: a Pi Zero on a long chain has a different set of good speeds from a Pi 4 on a short one. crisp_ladder() enumerates them and solve_crisp() picks the best match for a requested speed. solve_crisp weights motion quality rather than picking the numerically nearest entry, which matters more than it sounds. Asked for 30 px/s, nearest-by-value answers 28.6 -- 2px jumps at 14fps -- over 33.3, which is single-pixel motion at 33fps and obviously better on the panel. The target is also clamped into the ladder's range first, because relative error saturates near 1.0 for a target far outside it and the quality penalty would otherwise answer "10000 px/s" with the slowest entry. configure() snaps to the ladder and applies the hold when given a display manager. Without one the hold silently cannot happen and motion falls back to fractional pixels, so it warns rather than failing quietly. set_frame_hold() resets to 1 when scrolling stops, so one plugin's pacing cannot leak into whatever is on screen next. scripts/scroll_speeds.py is the user-facing part: it prints the ladder for the configured rate, measures what the panel ACTUALLY manages (--measure, for hardware that cannot reach its configured limit), highlights the nearest option to a wanted speed, and demos one live. It never starts or stops the display service itself -- doing that inside a script stranded the panel twice today. Speeds below ~20 px/s remain stepped regardless. That is the pixel pitch, not a software limit. Also fixes the dirty-tracking test spy, which stubbed SwapOnVSync with a single-argument function and would have masked the new call as a failed push, and rewrites a configure() test that had started passing for the wrong reason: it asserted a judder warning, which snapping now prevents, and was matching the unrelated "hold could not be applied" warning instead. 183 tests pass on the Pi. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(scroll): tie the frame hold to the scroll, not the plugin The hold applied in configure() never reached the panel. Plugins share one display manager, and set_scrolling_state(False) -- fired whenever ANY other plugin finishes its scroll -- reset the hold to 1. A hold set once at plugin construction was therefore always gone by the time that plugin rendered. The symptom was a log line that lied. ledmatrix-stocks reported Scroll configured: 50.0 px/s (1px every 2 refreshes = 50.0 fps, smooth) while the panel measured 100.0 fps, median 10.00ms. Config, resolution and snapping were all correct; only the pacing silently was not applied. set_scrolling_state(is_scrolling, frame_hold=1) now carries it, so the hold lives exactly as long as the scroll that asked for it. configure() reports the value as ScrollSettings.frame_hold instead of applying it -- applying it behind the caller's back could never have been right on a shared display manager. Existing callers are unaffected; the default keeps one frame per refresh. Verified on hardware: stocks at 50 px/s now measures 50.0 fps over 251 frames | median 20.00ms p95 20.09ms | stalls 0 skips 0 20.00ms being exactly two refreshes, with the panel still refreshing at 100Hz underneath so flicker is unchanged. test_another_plugin_stopping_does_not_strand_a_hold pins the interaction that broke this. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(scroll,cache): resolve CodeRabbit review on #523 Eight findings, all reproduced before fixing. scroll_config.configure() read the refresh rate *after* resolve() had already used it. resolve() fills in target_fps, pixels_per_frame and the judder warning from that rate, so on a 60Hz panel every one of them described 100Hz -- and with snap_to_crisp=False nothing downstream corrected it, so set_target_fps() paced the helper to 100 FPS. The rate is now settled first, and falls back to the global config rather than straight to the default. refresh_hz_from_config() used `(cfg.get("display") or {}).get(...)`, which raises AttributeError when either level is truthy but not a mapping -- out of a function whose whole contract is a rate or a default. The frame-stats line reported the upper-middle sample as the median and the 96th sorted sample as p95 of 100. Both are also thresholds (stalls at 1.5x the median, skips at 0.5x), so the counts were biased too. The arithmetic is now in frame_stats()/format_frame_stats(), testable without a clock. configure()'s docstring and docs/SCROLL_PERFORMANCE.md still said it applies the frame hold and warns when it cannot. It deliberately does neither since "tie the frame hold to the scroll, not the plugin"; a caller following the old text would omit set_scrolling_state() and slow snapped speeds would still present every refresh. disk_cache had no policy for non-finite floats: orjson writes null, the stdlib writes NaN/Infinity, and orjson then rejects those legacy files so DiskCache.get deleted them as corrupt. One behaviour on both paths now -- write null, keep legacy records readable. allow_nan=False detects the values; the replacement walk runs only when there is one, so the ordinary write path is byte-identical and pays nothing. build_rgbmatrix_nogil.sh picked the build artifact with a glob piped to `head -1`, which sorts cpython-311 ahead of cpython-313, so a stale .so staged in from the source tree was installed as core.so while the GIL check -- which reads the generated core.cpp, not the .so -- still passed. It now requires the current interpreter's exact ABI name and fails closed. Its systemctl calls were also unchecked under `set -uo pipefail`: a failed stop left the old service running, the following start succeeded as a no-op, and the health check reported SUCCESS for a binding that was never loaded. orjson floor raised to 3.11.6 for CVE-2025-67221 (unbounded recursion in dumps); it covers the project's Python 3.10-3.13 range. Adds test/test_cache_nonfinite_floats.py (14) plus regression tests in test_scroll_config.py and test_scroll_helper.py. 9 of the cache tests and 9 of the scroll_config tests fail against the pre-fix code. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014RRtqXDCnvnY6EQwhT5CV9 * test(harness): keep the visual double's signature tied to production Moves set_scrolling_state's frame_hold into the test double here, where DisplayManager gains it, rather than in #534 where it arrived a PR early. CodeRabbit flagged the #534 version correctly: a double that accepts an argument production does not lets the call pass every harness run and raise TypeError on the panel, which is the one failure a safety harness exists to prevent. The drift has now gone both ways across two branches -- double behind production on this branch, double ahead of it on #534 -- so it is pinned instead of remembered. test_display_double_parity.py compares the two signatures and fails with the direction of the drift named. It reads the files with ast rather than importing them, because display_manager imports rgbmatrix at module scope and this check should hold on a laptop and in CI as well as on a Pi. Plugins begin passing frame_hold in ledmatrix-plugins#462, which is why production and the double both need it before that lands. Full suite: 3889 passed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014RRtqXDCnvnY6EQwhT5CV9 --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Chuck
Vendored
+98
-8
@@ -5,6 +5,7 @@ Handles persistent disk-based caching with atomic writes and error recovery.
|
||||
"""
|
||||
|
||||
import json
|
||||
import math
|
||||
import os
|
||||
import time
|
||||
import tempfile
|
||||
@@ -14,6 +15,11 @@ import zlib
|
||||
from typing import Dict, Any, Optional, Protocol
|
||||
from datetime import datetime
|
||||
|
||||
try: # optional: large speedup on the cache write path, see _dumps below
|
||||
import orjson
|
||||
except ImportError: # pragma: no cover - exercised on hosts without the wheel
|
||||
orjson = None
|
||||
|
||||
# How old an abandoned write's temp file must be before the sweep removes it.
|
||||
# A real write holds its temp file for milliseconds, so an hour is far beyond
|
||||
# any in-flight write while still clearing the same day's debris. Deliberately
|
||||
@@ -40,13 +46,97 @@ class CacheStrategyProtocol(Protocol):
|
||||
|
||||
|
||||
class DateTimeEncoder(json.JSONEncoder):
|
||||
"""JSON encoder that handles datetime objects."""
|
||||
"""JSON encoder that handles datetime objects.
|
||||
|
||||
Retained for the stdlib fallback path and for any caller importing it.
|
||||
"""
|
||||
def default(self, obj: Any) -> Any:
|
||||
if isinstance(obj, datetime):
|
||||
return obj.isoformat()
|
||||
return super().default(obj)
|
||||
|
||||
|
||||
def _datetime_default(obj: Any) -> Any:
|
||||
"""Serialise datetimes exactly as DateTimeEncoder did."""
|
||||
if isinstance(obj, datetime):
|
||||
return obj.isoformat()
|
||||
raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
|
||||
|
||||
|
||||
def _replace_nonfinite(obj: Any) -> Any:
|
||||
"""Non-finite floats -> None, matching what ``orjson.dumps`` writes.
|
||||
|
||||
Only reached once a strict pass has proved there is something to replace,
|
||||
so the ordinary write path never pays for this walk.
|
||||
"""
|
||||
if isinstance(obj, float):
|
||||
return obj if math.isfinite(obj) else None
|
||||
if isinstance(obj, dict):
|
||||
return {k: _replace_nonfinite(v) for k, v in obj.items()}
|
||||
if isinstance(obj, (list, tuple)):
|
||||
return [_replace_nonfinite(v) for v in obj]
|
||||
return obj
|
||||
|
||||
|
||||
# NON-FINITE FLOATS
|
||||
# -----------------
|
||||
# JSON has no NaN or Infinity. The stdlib emits them anyway as an extension;
|
||||
# orjson refuses to and writes null. That divergence is not acceptable in a
|
||||
# cache whose files outlive the decision of which encoder is installed, so the
|
||||
# policy here is one behaviour on both paths:
|
||||
#
|
||||
# writing non-finite floats become null, whichever encoder is in use
|
||||
# reading files already on disk that carry the stdlib's NaN/Infinity
|
||||
# tokens stay readable, whichever encoder is in use
|
||||
#
|
||||
# Without the write half, installing orjson silently changed cached values.
|
||||
# Without the read half, installing orjson turned every legacy record holding a
|
||||
# NaN into a "corrupted cache file" that DiskCache.get logged as an error and
|
||||
# deleted. Both halves are covered by test/test_cache_nonfinite_floats.py.
|
||||
|
||||
|
||||
if orjson is not None:
|
||||
# Encoding the cache record dominated the background fetch worker: on a
|
||||
# Pi 4, stdlib json.dumps runs ~12ms per MB and holds the GIL for all of
|
||||
# it, which stalls the render thread mid-scroll. orjson measures ~7x
|
||||
# faster on the same payloads (11.9ms -> 1.6ms for 985KB). Decoding gains
|
||||
# far less (~1.3x on large payloads) because the cost there is building
|
||||
# the Python objects, not scanning the text, but it is still free to take.
|
||||
#
|
||||
# OPT_NON_STR_KEYS: stdlib json coerces int/float dict keys to strings;
|
||||
# orjson raises without this, and cache records do carry numeric keys.
|
||||
# OPT_PASSTHROUGH_DATETIME: orjson would otherwise emit its own RFC 3339
|
||||
# form for datetimes instead of calling default(). Routing them through
|
||||
# _datetime_default keeps byte-for-byte parity with the records already
|
||||
# on disk.
|
||||
_DUMPS_OPTS = orjson.OPT_NON_STR_KEYS | orjson.OPT_PASSTHROUGH_DATETIME
|
||||
|
||||
def _dumps(data: Any) -> bytes:
|
||||
return orjson.dumps(data, default=_datetime_default, option=_DUMPS_OPTS)
|
||||
|
||||
def _loads(raw: bytes) -> Any:
|
||||
try:
|
||||
return orjson.loads(raw)
|
||||
except orjson.JSONDecodeError:
|
||||
# Legacy record written by the stdlib path, carrying NaN or
|
||||
# Infinity. Genuinely malformed files raise again from here, as
|
||||
# json.JSONDecodeError, which is what DiskCache.get expects.
|
||||
return json.loads(raw)
|
||||
else:
|
||||
def _dumps(data: Any) -> bytes:
|
||||
try:
|
||||
return json.dumps(data, cls=DateTimeEncoder,
|
||||
allow_nan=False).encode("utf-8")
|
||||
except ValueError:
|
||||
# allow_nan=False is what detects the non-finite values; the walk
|
||||
# runs only now that we know there is one to replace.
|
||||
return json.dumps(_replace_nonfinite(data), cls=DateTimeEncoder,
|
||||
allow_nan=False).encode("utf-8")
|
||||
|
||||
def _loads(raw: bytes) -> Any:
|
||||
return json.loads(raw)
|
||||
|
||||
|
||||
class DiskCache:
|
||||
"""Manages persistent disk-based cache."""
|
||||
|
||||
@@ -99,8 +189,8 @@ class DiskCache:
|
||||
|
||||
try:
|
||||
with self._lock:
|
||||
with open(cache_path, 'r', encoding='utf-8') as f:
|
||||
record = json.load(f)
|
||||
with open(cache_path, 'rb') as f:
|
||||
record = _loads(f.read())
|
||||
|
||||
# Determine record timestamp (prefer embedded, else file mtime)
|
||||
record_ts = None
|
||||
@@ -189,12 +279,12 @@ class DiskCache:
|
||||
# write path below, and cache files are machine-read only — indenting
|
||||
# them just multiplied the bytes written to the SD card.
|
||||
try:
|
||||
payload = json.dumps(data, cls=DateTimeEncoder)
|
||||
payload = _dumps(data)
|
||||
except (TypeError, ValueError) as e:
|
||||
self.logger.warning("Cache data for key '%s' not serializable: %s", key, e)
|
||||
return
|
||||
|
||||
digest = zlib.adler32(payload.encode('utf-8'))
|
||||
digest = zlib.adler32(payload)
|
||||
|
||||
try:
|
||||
# Atomic write to avoid partial/corrupt files
|
||||
@@ -242,7 +332,7 @@ class DiskCache:
|
||||
# wear source (dozens of fsyncs/min on API-heavy
|
||||
# installs) for data that can be re-downloaded.
|
||||
try:
|
||||
with os.fdopen(fd, 'w', encoding='utf-8') as tmp_file:
|
||||
with os.fdopen(fd, 'wb') as tmp_file:
|
||||
tmp_file.write(payload)
|
||||
os.replace(tmp_path, cache_path)
|
||||
self._write_digests[key] = digest
|
||||
@@ -260,7 +350,7 @@ class DiskCache:
|
||||
else:
|
||||
# Fallback: direct write (not atomic, but better than failing)
|
||||
try:
|
||||
with open(cache_path, 'w', encoding='utf-8') as cache_file:
|
||||
with open(cache_path, 'wb') as cache_file:
|
||||
cache_file.write(payload)
|
||||
self._write_digests[key] = digest
|
||||
# Set proper permissions: 660 (rw-rw----) for group-readable cache files
|
||||
@@ -290,7 +380,7 @@ class DiskCache:
|
||||
# is a different path, so future sets must keep
|
||||
# retrying the primary location.
|
||||
fallback_path = os.path.join(fallback_dir, os.path.basename(cache_path))
|
||||
with open(fallback_path, 'w', encoding='utf-8') as tmp_file:
|
||||
with open(fallback_path, 'wb') as tmp_file:
|
||||
tmp_file.write(payload)
|
||||
# Set proper permissions: 660 (rw-rw----) for group-readable cache files
|
||||
try:
|
||||
|
||||
@@ -23,6 +23,13 @@ from src.common.error_handler import (
|
||||
)
|
||||
from src.common.api_helper import APIHelper
|
||||
from src.common.scroll_helper import ScrollHelper
|
||||
from src.common import scroll_config
|
||||
from src.common.scroll_config import (
|
||||
ScrollSettings,
|
||||
configure as configure_scroll,
|
||||
resolve as resolve_scroll_settings,
|
||||
refresh_hz_from_config,
|
||||
)
|
||||
from src.common.logo_helper import LogoHelper
|
||||
from src.common.text_helper import TextHelper
|
||||
|
||||
@@ -60,6 +67,11 @@ __all__ = [
|
||||
'log_and_raise',
|
||||
'APIHelper',
|
||||
'ScrollHelper',
|
||||
'scroll_config',
|
||||
'ScrollSettings',
|
||||
'configure_scroll',
|
||||
'resolve_scroll_settings',
|
||||
'refresh_hz_from_config',
|
||||
'LogoHelper',
|
||||
'TextHelper',
|
||||
# adaptive layout & images
|
||||
|
||||
@@ -0,0 +1,440 @@
|
||||
"""One place that turns plugin config into a configured ScrollHelper.
|
||||
|
||||
Five ticker plugins each hand-rolled this resolution (odds-ticker, news and
|
||||
ledmatrix-leaderboard reference the deprecated ``scroll_pixels_per_second``
|
||||
key 16-18 times apiece), and they disagreed in ways that were invisible until
|
||||
someone watched the panel:
|
||||
|
||||
* odds-ticker read ``scroll_pixels_per_second`` on the *recommended* config
|
||||
path and let it override ``scroll_speed``/``scroll_delay``. Because that key
|
||||
carries a schema default, the documented settings were dead for every user
|
||||
-- see ChuckBuilds/ledmatrix-plugins#408.
|
||||
* ledmatrix-leaderboard read the same key only as a fallback, so identical
|
||||
config produced different speeds in the two plugins.
|
||||
* stock-news derived px/frame from it via its own arithmetic.
|
||||
|
||||
What matters on the hardware
|
||||
----------------------------
|
||||
Motion is smooth when the strip advances a **whole number of pixels per panel
|
||||
refresh**. On a 100Hz panel that means 100 px/s, 200 px/s, and so on. Anything
|
||||
else has to either blend adjacent columns (which on pixel-font text reads as
|
||||
shimmer) or repeat frames (which reads as judder). :func:`resolve` warns when
|
||||
the requested speed will not divide evenly, because that is a real display
|
||||
artefact and not a rounding detail.
|
||||
|
||||
Speed is always expressed to the helper as pixels per second and applied in
|
||||
time-based mode. Frame-based stepping gates motion on a wall clock at
|
||||
``1/scroll_delay`` steps per second; plugins set ``scroll_delay`` to the frame
|
||||
period, which puts that comparison exactly on its own threshold and makes the
|
||||
step count flip on sub-millisecond jitter. Accumulating elapsed time keeps
|
||||
position proportional to real time instead.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from dataclasses import dataclass, replace
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
#: Speed used when a plugin supplies nothing usable. One pixel per refresh on a
|
||||
#: 100Hz panel, which is the slowest crisp scroll that hardware can show.
|
||||
DEFAULT_PIXELS_PER_SECOND = 100.0
|
||||
|
||||
#: Bounds accepted from config. Below the floor a marquee appears frozen;
|
||||
#: above the ceiling it outruns any panel's refresh and tears.
|
||||
MIN_PIXELS_PER_SECOND = 1.0
|
||||
MAX_PIXELS_PER_SECOND = 500.0
|
||||
|
||||
#: Assumed refresh when the caller does not say. Matches the usual
|
||||
#: ``display.hardware.limit_refresh_rate_hz``.
|
||||
DEFAULT_REFRESH_HZ = 100.0
|
||||
|
||||
#: How far px/s may sit from a whole number of pixels per refresh before it is
|
||||
#: worth warning about. 0.05px per frame is invisible; a third of a pixel is not.
|
||||
_WHOLE_PIXEL_TOLERANCE = 0.05
|
||||
|
||||
|
||||
#: Longest a frame may be held before motion reads as a slideshow rather than
|
||||
#: a scroll. 6 refreshes at 100Hz is ~17px/s, already visibly stepped.
|
||||
MAX_FRAME_HOLD = 8
|
||||
|
||||
#: Largest whole-pixel jump per presented frame before motion looks like it is
|
||||
#: teleporting rather than sliding.
|
||||
MAX_PIXELS_PER_FRAME = 6
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class CrispSpeed:
|
||||
"""A speed the panel can show with whole-pixel motion.
|
||||
|
||||
``pixels_per_second`` is always ``refresh_hz / frame_hold * pixels_per_frame``
|
||||
exactly -- no rounding, no fractional pixel positions, so nothing has to be
|
||||
blended or repeated unevenly.
|
||||
|
||||
:param frame_hold: refreshes each frame is held for. This is rgbmatrix's
|
||||
``SwapOnVSync(canvas, framerate_fraction)``. The panel keeps refreshing
|
||||
at full rate either way, so holding a frame costs nothing in flicker.
|
||||
:param pixels_per_frame: whole pixels advanced per presented frame.
|
||||
"""
|
||||
|
||||
pixels_per_second: float
|
||||
frame_hold: int
|
||||
pixels_per_frame: int
|
||||
refresh_hz: float
|
||||
|
||||
@property
|
||||
def frames_per_second(self) -> float:
|
||||
return self.refresh_hz / self.frame_hold
|
||||
|
||||
@property
|
||||
def steppiness(self) -> str:
|
||||
"""Rough readability hint for this combination."""
|
||||
if self.pixels_per_frame > 2:
|
||||
return "jumpy"
|
||||
if self.frames_per_second < 20:
|
||||
return "stepped"
|
||||
if self.frames_per_second < 30:
|
||||
return "slightly stepped"
|
||||
return "smooth"
|
||||
|
||||
def describe(self) -> str:
|
||||
return (
|
||||
f"{self.pixels_per_second:6.1f} px/s "
|
||||
f"({self.pixels_per_frame}px every {self.frame_hold} refresh"
|
||||
f"{'es' if self.frame_hold != 1 else ' '} = "
|
||||
f"{self.frames_per_second:5.1f} fps, {self.steppiness})"
|
||||
)
|
||||
|
||||
|
||||
def crisp_ladder(
|
||||
refresh_hz: float = DEFAULT_REFRESH_HZ,
|
||||
max_frame_hold: int = MAX_FRAME_HOLD,
|
||||
max_pixels_per_frame: int = MAX_PIXELS_PER_FRAME,
|
||||
):
|
||||
"""Every whole-pixel speed this panel can show, slowest first.
|
||||
|
||||
Duplicates are collapsed keeping the gentlest option: 100 px/s is reachable
|
||||
as 1px every refresh or 2px every 2nd refresh, and the former moves in
|
||||
smaller increments, so that is the one worth offering.
|
||||
"""
|
||||
best = {}
|
||||
for hold in range(1, max_frame_hold + 1):
|
||||
for ppf in range(1, max_pixels_per_frame + 1):
|
||||
pps = refresh_hz / hold * ppf
|
||||
key = round(pps, 3)
|
||||
candidate = CrispSpeed(pps, hold, ppf, refresh_hz)
|
||||
incumbent = best.get(key)
|
||||
if incumbent is None or ppf < incumbent.pixels_per_frame:
|
||||
best[key] = candidate
|
||||
return [best[k] for k in sorted(best)]
|
||||
|
||||
|
||||
#: How much a bigger pixel step costs, as a fraction of the target speed.
|
||||
#: Tuned so 66.7px/s (2px at 33fps) beats 50px/s (1px at 50fps) when 60 was
|
||||
#: asked for, but 33.3px/s (1px, smooth) still beats 28.6px/s (2px at 14fps)
|
||||
#: when 30 was asked for -- being 11% slow is worth far less than looking bad.
|
||||
_STEP_PENALTY = 0.05
|
||||
_SLOW_FPS_PENALTY = 0.25 # below 20fps
|
||||
_LOWISH_FPS_PENALTY = 0.10 # below 25fps
|
||||
|
||||
|
||||
def _quality_cost(candidate: "CrispSpeed", target: float) -> float:
|
||||
"""Lower is better. Numeric closeness alone picks bad-looking speeds.
|
||||
|
||||
Nearest-by-value would answer "30 px/s" with 28.6 px/s -- which is 2px
|
||||
jumps at 14fps -- over 33.3 px/s, which is single-pixel motion at 33fps and
|
||||
obviously better on the panel. Proximity has to be traded against how the
|
||||
motion actually reads.
|
||||
"""
|
||||
error = abs(candidate.pixels_per_second - target) / max(target, 1e-6)
|
||||
cost = error + _STEP_PENALTY * (candidate.pixels_per_frame - 1)
|
||||
fps = candidate.frames_per_second
|
||||
if fps < 20:
|
||||
cost += _SLOW_FPS_PENALTY
|
||||
elif fps < 25:
|
||||
cost += _LOWISH_FPS_PENALTY
|
||||
return cost
|
||||
|
||||
|
||||
def solve_crisp(
|
||||
target_pixels_per_second: float,
|
||||
refresh_hz: float = DEFAULT_REFRESH_HZ,
|
||||
max_frame_hold: int = MAX_FRAME_HOLD,
|
||||
max_pixels_per_frame: int = MAX_PIXELS_PER_FRAME,
|
||||
) -> CrispSpeed:
|
||||
"""The whole-pixel speed that will look best for what was asked for.
|
||||
|
||||
Not simply the nearest -- see :func:`_quality_cost`. Ties break toward the
|
||||
smaller pixel step and the shorter hold.
|
||||
"""
|
||||
ladder = crisp_ladder(refresh_hz, max_frame_hold, max_pixels_per_frame)
|
||||
# Clamp into the ladder's range first. Relative error saturates near 1.0
|
||||
# for a target far outside it, so the quality penalty would dominate and
|
||||
# answer "10000 px/s" with the *slowest* entry -- smooth, and useless.
|
||||
target = min(max(target_pixels_per_second, ladder[0].pixels_per_second),
|
||||
ladder[-1].pixels_per_second)
|
||||
return min(
|
||||
ladder,
|
||||
key=lambda c: (round(_quality_cost(c, target), 6),
|
||||
c.pixels_per_frame, c.frame_hold),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ScrollSettings:
|
||||
"""The resolved outcome, and which config key produced it."""
|
||||
|
||||
pixels_per_second: float
|
||||
source: str
|
||||
target_fps: Optional[float] = None
|
||||
pixels_per_frame: Optional[float] = None
|
||||
warning: Optional[str] = None
|
||||
#: The whole-pixel speed actually applied, when snapping was enabled.
|
||||
crisp: Optional[CrispSpeed] = None
|
||||
#: What the config asked for, before snapping.
|
||||
requested_pixels_per_second: Optional[float] = None
|
||||
|
||||
@property
|
||||
def frame_hold(self) -> int:
|
||||
"""Refreshes to hold each frame for; pass to set_scrolling_state()."""
|
||||
return self.crisp.frame_hold if self.crisp else 1
|
||||
|
||||
def describe(self) -> str:
|
||||
text = f"{self.pixels_per_second:.1f} px/s (from {self.source})"
|
||||
if self.pixels_per_frame is not None:
|
||||
text += f" = {self.pixels_per_frame:.2f} px/frame"
|
||||
if self.target_fps:
|
||||
text += f" at {self.target_fps:.0f} fps"
|
||||
return text
|
||||
|
||||
|
||||
def _coerce(value: Any) -> Optional[float]:
|
||||
"""A positive float, or None. Config reaches us with nulls and strings."""
|
||||
if value is None or isinstance(value, bool):
|
||||
return None
|
||||
try:
|
||||
number = float(value)
|
||||
except (TypeError, ValueError):
|
||||
return None
|
||||
return number if number > 0 else None
|
||||
|
||||
|
||||
def _from_speed_and_delay(block: Any) -> Optional[float]:
|
||||
"""px/s from a ``scroll_speed`` (px/frame) + ``scroll_delay`` (s) pair."""
|
||||
if not isinstance(block, dict):
|
||||
return None
|
||||
speed = _coerce(block.get("scroll_speed"))
|
||||
delay = _coerce(block.get("scroll_delay"))
|
||||
if speed is None or delay is None:
|
||||
return None
|
||||
return speed / delay
|
||||
|
||||
|
||||
def resolve(
|
||||
plugin_config: Optional[Dict[str, Any]] = None,
|
||||
global_config: Optional[Dict[str, Any]] = None,
|
||||
default_pixels_per_second: float = DEFAULT_PIXELS_PER_SECOND,
|
||||
refresh_hz: Optional[float] = None,
|
||||
) -> ScrollSettings:
|
||||
"""Resolve one scroll speed from the several shapes plugins accept.
|
||||
|
||||
Precedence, highest first. The deprecated flat key sits *below* the
|
||||
explicit pairs deliberately: it carries schema defaults in some plugins, so
|
||||
ranking it above them silently disables the documented settings.
|
||||
|
||||
1. ``display_options.scroll_speed`` + ``scroll_delay`` (current)
|
||||
2. ``display.scroll_speed`` + ``scroll_delay`` (deprecated shape)
|
||||
3. ``scroll_speed`` + ``scroll_delay`` at the root (legacy flat)
|
||||
4. ``scroll_pixels_per_second``, nested or flat (deprecated)
|
||||
5. the global ``display`` block
|
||||
6. ``default_pixels_per_second``
|
||||
|
||||
:param refresh_hz: panel refresh, used only to check whether the resolved
|
||||
speed lands on whole pixels per frame and to fill in ``target_fps``.
|
||||
"""
|
||||
plugin_config = plugin_config or {}
|
||||
global_config = global_config or {}
|
||||
refresh = _coerce(refresh_hz) or DEFAULT_REFRESH_HZ
|
||||
|
||||
display_options = plugin_config.get("display_options")
|
||||
display_block = plugin_config.get("display")
|
||||
|
||||
candidates = [
|
||||
(_from_speed_and_delay(display_options), "display_options.scroll_speed/delay"),
|
||||
(_from_speed_and_delay(display_block), "display.scroll_speed/delay"),
|
||||
(_from_speed_and_delay(plugin_config), "scroll_speed/delay (root)"),
|
||||
]
|
||||
for block, label in (
|
||||
(display_options, "display_options.scroll_pixels_per_second"),
|
||||
(display_block, "display.scroll_pixels_per_second"),
|
||||
(plugin_config, "scroll_pixels_per_second"),
|
||||
):
|
||||
if isinstance(block, dict):
|
||||
candidates.append((_coerce(block.get("scroll_pixels_per_second")), label))
|
||||
|
||||
global_display = global_config.get("display")
|
||||
candidates.append((_from_speed_and_delay(global_display), "global display.scroll_speed/delay"))
|
||||
|
||||
pixels_per_second = None
|
||||
source = "default"
|
||||
for value, label in candidates:
|
||||
if value is not None:
|
||||
pixels_per_second, source = value, label
|
||||
break
|
||||
if pixels_per_second is None:
|
||||
pixels_per_second = default_pixels_per_second
|
||||
|
||||
clamped = max(MIN_PIXELS_PER_SECOND, min(MAX_PIXELS_PER_SECOND, pixels_per_second))
|
||||
warning = None
|
||||
if clamped != pixels_per_second:
|
||||
warning = (
|
||||
f"scroll speed {pixels_per_second:.1f} px/s out of range, "
|
||||
f"clamped to {clamped:.1f}"
|
||||
)
|
||||
pixels_per_second = clamped
|
||||
|
||||
pixels_per_frame = pixels_per_second / refresh if refresh > 0 else None
|
||||
if warning is None and pixels_per_frame is not None:
|
||||
offset = abs(pixels_per_frame - round(pixels_per_frame))
|
||||
if pixels_per_frame < 1.0 - _WHOLE_PIXEL_TOLERANCE or offset > _WHOLE_PIXEL_TOLERANCE:
|
||||
suggestion = max(1.0, round(pixels_per_frame)) * refresh
|
||||
warning = (
|
||||
f"{pixels_per_second:.1f} px/s is {pixels_per_frame:.2f} px per "
|
||||
f"refresh at {refresh:.0f}Hz, so some frames repeat and the "
|
||||
f"scroll will judder; {suggestion:.0f} px/s divides evenly"
|
||||
)
|
||||
|
||||
return ScrollSettings(
|
||||
pixels_per_second=pixels_per_second,
|
||||
source=source,
|
||||
target_fps=refresh,
|
||||
pixels_per_frame=pixels_per_frame,
|
||||
warning=warning,
|
||||
)
|
||||
|
||||
|
||||
def configure(
|
||||
scroll_helper: Any,
|
||||
plugin_config: Optional[Dict[str, Any]] = None,
|
||||
global_config: Optional[Dict[str, Any]] = None,
|
||||
default_pixels_per_second: float = DEFAULT_PIXELS_PER_SECOND,
|
||||
refresh_hz: Optional[float] = None,
|
||||
plugin_logger: Optional[logging.Logger] = None,
|
||||
display_manager: Any = None,
|
||||
snap_to_crisp: bool = True,
|
||||
) -> ScrollSettings:
|
||||
"""Resolve the config and apply it to ``scroll_helper``.
|
||||
|
||||
Applied in time-based mode: see the module docstring for why frame-based
|
||||
stepping is not used. ``hasattr`` guards keep this usable against older
|
||||
ScrollHelper builds that a plugin may be running on.
|
||||
|
||||
:param display_manager: consulted for the panel's refresh rate only (it can
|
||||
see display.hardware; a plugin cannot). The frame hold is NOT applied
|
||||
here -- see the note in the body. The caller must pass
|
||||
``settings.frame_hold`` to ``display_manager.set_scrolling_state(True,
|
||||
...)`` when it starts scrolling, or a sub-refresh speed still presents
|
||||
a new frame every refresh and the motion falls back to fractional
|
||||
pixels.
|
||||
:param snap_to_crisp: move the requested speed to the nearest speed the
|
||||
panel can show in whole pixels. On by default because a speed that does
|
||||
not divide evenly has no good rendering, only a choice of artefacts.
|
||||
|
||||
:returns: the settings applied, so the caller can log or assert on them.
|
||||
"""
|
||||
log = plugin_logger or logger
|
||||
|
||||
# Refresh rate, most authoritative first: what the caller passed, then the
|
||||
# display manager (which can see display.hardware; a plugin cannot), then
|
||||
# the global config, then the default.
|
||||
#
|
||||
# This has to be settled BEFORE resolve(), not after. resolve() uses the
|
||||
# refresh to fill in target_fps, pixels_per_frame and the judder warning,
|
||||
# so deriving it afterwards described a 100Hz panel to everyone running at
|
||||
# 60 -- and with snap_to_crisp=False nothing downstream corrected it, so
|
||||
# set_target_fps() paced the helper to 100 FPS on a 60Hz panel.
|
||||
hz = _coerce(refresh_hz)
|
||||
if hz is None and display_manager is not None:
|
||||
hz = _coerce(getattr(display_manager, "refresh_hz", None))
|
||||
if hz is None:
|
||||
hz = refresh_hz_from_config(global_config)
|
||||
|
||||
settings = resolve(
|
||||
plugin_config,
|
||||
global_config,
|
||||
default_pixels_per_second=default_pixels_per_second,
|
||||
refresh_hz=hz,
|
||||
)
|
||||
applied = settings.pixels_per_second
|
||||
choice = None
|
||||
|
||||
if snap_to_crisp:
|
||||
choice = solve_crisp(settings.pixels_per_second, hz)
|
||||
applied = choice.pixels_per_second
|
||||
settings = replace(
|
||||
settings,
|
||||
pixels_per_second=applied,
|
||||
requested_pixels_per_second=settings.pixels_per_second,
|
||||
crisp=choice,
|
||||
pixels_per_frame=float(choice.pixels_per_frame),
|
||||
# Snapping resolves the whole-pixel problem the warning describes.
|
||||
warning=None if settings.warning and "judder" in settings.warning
|
||||
else settings.warning,
|
||||
)
|
||||
|
||||
if hasattr(scroll_helper, "set_frame_based_scrolling"):
|
||||
scroll_helper.set_frame_based_scrolling(False)
|
||||
scroll_helper.set_scroll_speed(applied)
|
||||
if choice and hasattr(scroll_helper, "set_target_fps"):
|
||||
scroll_helper.set_target_fps(choice.frames_per_second)
|
||||
elif settings.target_fps and hasattr(scroll_helper, "set_target_fps"):
|
||||
scroll_helper.set_target_fps(settings.target_fps)
|
||||
|
||||
# Deliberately NOT applied here. The hold belongs to a scroll, not to a
|
||||
# plugin's lifetime: plugins share one display manager, and one left set at
|
||||
# construction is reset the moment any other plugin finishes scrolling.
|
||||
# Callers pass settings.frame_hold to set_scrolling_state(True, ...) when
|
||||
# they start scrolling. configure() only reports what is needed.
|
||||
|
||||
if choice:
|
||||
requested = settings.requested_pixels_per_second
|
||||
if abs(requested - applied) > 0.05:
|
||||
log.info(
|
||||
"Scroll configured: %s (asked for %.1f px/s from %s; "
|
||||
"nearest whole-pixel speed on a %.0fHz panel)",
|
||||
choice.describe(), requested, settings.source, hz,
|
||||
)
|
||||
else:
|
||||
log.info("Scroll configured: %s (from %s)",
|
||||
choice.describe(), settings.source)
|
||||
if choice.frame_hold > 1:
|
||||
log.debug(
|
||||
"Scroll needs a frame hold of %d - pass settings.frame_hold to "
|
||||
"display_manager.set_scrolling_state(True, ...) each scroll",
|
||||
choice.frame_hold,
|
||||
)
|
||||
else:
|
||||
log.info("Scroll configured: %s", settings.describe())
|
||||
|
||||
if settings.warning:
|
||||
log.warning("Scroll speed: %s", settings.warning)
|
||||
return settings
|
||||
|
||||
|
||||
def refresh_hz_from_config(global_config: Optional[Dict[str, Any]]) -> float:
|
||||
"""The panel's refresh cap from the global config, or the default."""
|
||||
if not isinstance(global_config, dict):
|
||||
return DEFAULT_REFRESH_HZ
|
||||
# Each level is checked for being a mapping rather than merely truthy: a
|
||||
# malformed config where display or display.hardware is a string or a list
|
||||
# raised AttributeError out of what is meant to be a total function with a
|
||||
# default, taking down every caller that asked for the refresh rate.
|
||||
display = global_config.get("display")
|
||||
if not isinstance(display, dict):
|
||||
return DEFAULT_REFRESH_HZ
|
||||
hardware = display.get("hardware")
|
||||
if not isinstance(hardware, dict):
|
||||
return DEFAULT_REFRESH_HZ
|
||||
return _coerce(hardware.get("limit_refresh_rate_hz")) or DEFAULT_REFRESH_HZ
|
||||
+98
-21
@@ -16,6 +16,7 @@ Features:
|
||||
"""
|
||||
|
||||
import logging
|
||||
import math
|
||||
import time
|
||||
from typing import Optional, Dict, Any
|
||||
from PIL import Image
|
||||
@@ -29,6 +30,49 @@ except ImportError:
|
||||
HAS_SCIPY = False
|
||||
|
||||
|
||||
def frame_stats(frame_times: list) -> Dict[str, Any]:
|
||||
"""Summary statistics over one window of frame durations (seconds).
|
||||
|
||||
Split out of log_frame_rate() so the arithmetic can be tested without a
|
||||
clock. Median and p95 are the real ones: the median takes both middle
|
||||
samples on an even window, and p95 is nearest-rank, so a 100-frame window
|
||||
reports the 95th sorted sample rather than the 96th. That matters twice
|
||||
over, because the median is also the threshold the stall and skip counts
|
||||
are measured against.
|
||||
"""
|
||||
window = sorted(frame_times)
|
||||
n = len(window)
|
||||
median = (window[n // 2] if n % 2
|
||||
else (window[n // 2 - 1] + window[n // 2]) / 2.0)
|
||||
mean = sum(window) / n
|
||||
# Anything past 1.5x the median missed a panel refresh; anything under
|
||||
# half of it never reached the panel at all (dirty tracking skipped the
|
||||
# swap, so the frame did not wait for vsync).
|
||||
return {
|
||||
"frames": n,
|
||||
"fps": (1.0 / mean) if mean > 0 else 0.0,
|
||||
"median": median,
|
||||
"p95": window[max(0, math.ceil(0.95 * n) - 1)],
|
||||
"max": window[-1],
|
||||
"min": window[0],
|
||||
"stalls": sum(1 for f in window if f > median * 1.5),
|
||||
"skips": sum(1 for f in window if f < median * 0.5),
|
||||
}
|
||||
|
||||
|
||||
def format_frame_stats(frame_times: list) -> str:
|
||||
"""The one-line rendering of frame_stats(), in milliseconds."""
|
||||
s = frame_stats(frame_times)
|
||||
n = s["frames"]
|
||||
return (
|
||||
f"{s['fps']:.1f} fps over {n} frames | "
|
||||
f"median {s['median'] * 1000:.2f}ms p95 {s['p95'] * 1000:.2f}ms "
|
||||
f"max {s['max'] * 1000:.2f}ms min {s['min'] * 1000:.2f}ms | "
|
||||
f"stalls {s['stalls']} ({100.0 * s['stalls'] / n:.1f}%) "
|
||||
f"skips {s['skips']} ({100.0 * s['skips'] / n:.1f}%)"
|
||||
)
|
||||
|
||||
|
||||
class ScrollHelper:
|
||||
"""
|
||||
Helper class for scrolling text and image content on LED displays.
|
||||
@@ -75,8 +119,19 @@ class ScrollHelper:
|
||||
# Pre-allocated buffer for output frame (reused to avoid allocations)
|
||||
self._frame_buffer: Optional[np.ndarray] = None
|
||||
|
||||
# Sub-pixel scrolling settings (disabled - using high FPS integer scrolling instead)
|
||||
self.sub_pixel_scrolling = False # Disabled - use high frame rate for smoothness
|
||||
# Sub-pixel scrolling: OFF by default, and that is deliberate.
|
||||
# Blending renders a half-step by mixing two adjacent columns 50/50.
|
||||
# On a high-resolution screen that reads as smooth motion; on a coarse
|
||||
# LED matrix showing pixel-font text it does not. A one-pixel stroke
|
||||
# becomes two half-brightness pixels, so frames alternate between crisp
|
||||
# and smeared and the text appears to shimmer and jump a pixel ahead --
|
||||
# tested on a 2x128x64 panel and clearly worse than integer stepping.
|
||||
#
|
||||
# The rule this display obeys: motion is smooth when it advances a
|
||||
# whole number of pixels per refresh. Anything slower must either
|
||||
# blend (blur) or repeat frames (judder); blending is the worse of the
|
||||
# two here. Vegas mode still opts in via set_sub_pixel_scrolling().
|
||||
self.sub_pixel_scrolling = False
|
||||
self._last_integer_position = 0 # Cache for integer position to avoid repeated calculations
|
||||
|
||||
# Frame-based scrolling settings
|
||||
@@ -105,6 +160,9 @@ class ScrollHelper:
|
||||
self.last_frame_time = time.time()
|
||||
self.last_fps_log_time = time.time()
|
||||
self.frame_times = []
|
||||
# Every frame time since the last stats line, so the 5s summary can
|
||||
# report the tail rather than one arbitrary sample. Cleared on log.
|
||||
self._window: list = []
|
||||
|
||||
# Scrolling state management
|
||||
self.is_scrolling = False
|
||||
@@ -244,19 +302,31 @@ class ScrollHelper:
|
||||
if self.last_step_time == 0.0:
|
||||
self.last_step_time = current_time
|
||||
|
||||
# Check if scroll_delay has passed
|
||||
time_since_last_step = current_time - self.last_step_time
|
||||
if time_since_last_step >= self.scroll_delay:
|
||||
# Move pixels (can move multiple steps if lag occurred, but cap to prevent huge jumps)
|
||||
steps = int(time_since_last_step / self.scroll_delay)
|
||||
# Cap at reasonable number to prevent huge jumps from lag
|
||||
max_steps = max(1, int(0.04 / self.scroll_delay)) # Limit to 0.04s (2 steps at 50 FPS) for smoother scrolling
|
||||
steps = min(steps, max_steps)
|
||||
pixels_to_move = self.scroll_speed * steps
|
||||
# Update last_step_time, preserving fractional delay for smooth timing
|
||||
self.last_step_time = current_time - (time_since_last_step % self.scroll_delay)
|
||||
# Frame-based mode advances by elapsed time, exactly like the
|
||||
# time-based branch below, at the same configured speed
|
||||
# (scroll_speed px per scroll_delay seconds).
|
||||
#
|
||||
# It used to step discretely: 0, 1 or 2 whole pixels depending on
|
||||
# whether a wall clock had passed scroll_delay. Plugins set
|
||||
# scroll_delay to the target frame period, so that comparison sits
|
||||
# exactly on its own threshold and the decision flips on sub-
|
||||
# millisecond jitter -- a frame a hair early moved nothing and
|
||||
# rendered an identical frame, a frame a hair late moved two
|
||||
# pixels. Rounding the step count fixed the stalls but still
|
||||
# discarded the remainder, so the error never corrected.
|
||||
#
|
||||
# Accumulating elapsed time keeps position exactly proportional to
|
||||
# real time: jitter shifts a pixel boundary by a fraction of a
|
||||
# frame instead of flipping a whole step, and nothing is lost or
|
||||
# gained. This is what the one visibly smooth scroller on the
|
||||
# hardware (the stock ticker) was already doing by virtue of never
|
||||
# enabling frame-based mode.
|
||||
if self.scroll_delay > 0:
|
||||
pixels_per_second = self.scroll_speed / self.scroll_delay
|
||||
else:
|
||||
pixels_to_move = 0.0
|
||||
pixels_per_second = self.scroll_speed * 100.0
|
||||
pixels_to_move = pixels_per_second * delta_time
|
||||
self.last_step_time = current_time
|
||||
else:
|
||||
# Time-based: move based on time delta (correct speed over time)
|
||||
# scroll_speed is pixels per second
|
||||
@@ -1017,18 +1087,25 @@ class ScrollHelper:
|
||||
# Keep only last 100 frames for average
|
||||
if len(self.frame_times) > 100:
|
||||
self.frame_times.pop(0)
|
||||
|
||||
# Every frame since the last log, not just the last 100 and not just
|
||||
# the one that happens to land on the 5s boundary. The old line
|
||||
# reported a single instantaneous sample -- roughly 1 frame in 500 --
|
||||
# which cannot see a stall that hits 1% of frames, and reported it
|
||||
# next to an average that hides the same stall by construction (a 2ms
|
||||
# duplicate and a 21ms double-wait mean exactly 10ms). Chasing scroll
|
||||
# judder needs the tail, so keep the window and report percentiles.
|
||||
self._window.append(frame_time)
|
||||
|
||||
# Log FPS every 5 seconds to avoid spam
|
||||
if current_time - self.last_fps_log_time >= 5.0:
|
||||
avg_frame_time = sum(self.frame_times) / len(self.frame_times)
|
||||
avg_fps = 1.0 / avg_frame_time if avg_frame_time > 0 else 0
|
||||
instant_fps = 1.0 / frame_time if frame_time > 0 else 0
|
||||
|
||||
self.logger.info(f"Scroll frame stats - Avg FPS: {avg_fps:.1f}, "
|
||||
f"Current FPS: {instant_fps:.1f}, "
|
||||
f"Frame time: {frame_time*1000:.2f}ms")
|
||||
self.logger.info(
|
||||
"Scroll frame stats - %s",
|
||||
format_frame_stats(self._window or [frame_time]),
|
||||
)
|
||||
self.last_fps_log_time = current_time
|
||||
self.frame_count = 0
|
||||
self._window = []
|
||||
|
||||
self.last_frame_time = current_time
|
||||
self.frame_count += 1
|
||||
|
||||
@@ -2461,6 +2461,7 @@ class DisplayController:
|
||||
)
|
||||
|
||||
while True:
|
||||
_frame_start = time.perf_counter()
|
||||
try:
|
||||
with self._display_lock_or_skip(plugin_id) as can_display:
|
||||
if can_display:
|
||||
@@ -2481,11 +2482,26 @@ class DisplayController:
|
||||
# Multi-display sync: send follower frame after each render
|
||||
self._send_follower_frame(manager_to_display)
|
||||
|
||||
time.sleep(display_interval)
|
||||
self._tick_plugin_updates()
|
||||
self._poll_on_demand_requests()
|
||||
self._check_on_demand_expiration()
|
||||
|
||||
# Pace to the frame deadline rather than sleeping a flat
|
||||
# interval on top of the work. display() has already
|
||||
# blocked on the panel's vsync by this point, so an
|
||||
# unconditional sleep is added to a wait that already
|
||||
# happened. Measured on a 2x128x64 chain at
|
||||
# limit_refresh_rate_hz=100: ~4ms of render plus a flat
|
||||
# 8ms put each iteration at ~12ms against a 10ms refresh
|
||||
# grid, so every swap missed a refresh and the loop
|
||||
# settled at 50fps where display_interval asks for 125 --
|
||||
# and with zero headroom, ~14% of frames slipped a
|
||||
# further refresh, which is what reads as scroll stutter.
|
||||
_remaining = display_interval - (time.perf_counter() - _frame_start)
|
||||
# Yield even when the frame overran its budget, so plugin
|
||||
# update threads and the web UI are not starved of the GIL.
|
||||
time.sleep(_remaining if _remaining > 0 else 0.001)
|
||||
|
||||
if self.current_display_mode != active_mode:
|
||||
logger.debug("Mode changed during high-FPS loop, breaking early")
|
||||
break
|
||||
|
||||
+101
-11
@@ -240,6 +240,14 @@ class DisplayManager:
|
||||
self._update_lock = threading.RLock()
|
||||
|
||||
# Scrolling state tracking for graceful updates
|
||||
# How many panel refreshes each pushed frame is held for. 1 means a new
|
||||
# frame every refresh. Higher values are how a scroll runs slower than
|
||||
# one pixel per refresh WITHOUT fractional pixel positions: the panel
|
||||
# keeps refreshing at full rate (so flicker is unchanged) but motion
|
||||
# advances a whole pixel every Nth refresh instead of every one.
|
||||
# See src/common/scroll_config.py and scripts/scroll_speeds.py.
|
||||
self._frame_hold = 1
|
||||
|
||||
self._scrolling_state = {
|
||||
'is_scrolling': False,
|
||||
'last_scroll_activity': 0,
|
||||
@@ -771,16 +779,33 @@ class DisplayManager:
|
||||
return # Skip hardware write — content is being captured off-screen
|
||||
|
||||
digest = None
|
||||
frame_checksum = None
|
||||
if self._dirty_tracking_enabled:
|
||||
try:
|
||||
brightness = getattr(self.matrix, 'brightness', None)
|
||||
except AttributeError:
|
||||
brightness = None
|
||||
digest = (zlib.adler32(self.image.tobytes()), brightness)
|
||||
if digest == self._last_pushed_digest:
|
||||
frame_checksum = zlib.adler32(self.image.tobytes())
|
||||
digest = (frame_checksum, brightness)
|
||||
if digest == self._last_pushed_digest and not self.is_currently_scrolling():
|
||||
# Nothing changed since the last push — the panel is
|
||||
# already showing exactly this frame.
|
||||
self._write_snapshot_if_due()
|
||||
#
|
||||
# Never taken mid-scroll, and that exception is the
|
||||
# point. SwapOnVSync is what paces the render loop, so
|
||||
# skipping it also skips the wait: a duplicate frame
|
||||
# returns in ~8ms instead of ~10ms on a 100Hz panel,
|
||||
# advances only 0.8px instead of 1.0px, and so makes
|
||||
# the *next* frame more likely to repeat as well. That
|
||||
# is self-sustaining -- measured at ~20% duplicate
|
||||
# frames mid-scroll on the odds ticker, against
|
||||
# essentially zero on a lighter plugin with identical
|
||||
# scroll settings. Swapping an identical frame costs
|
||||
# one canvas copy and keeps the loop locked to the
|
||||
# panel; falling out of that lock costs smooth motion.
|
||||
# Static content is unaffected: is_currently_scrolling()
|
||||
# expires on its own inactivity threshold.
|
||||
self._write_snapshot_if_due(frame_checksum)
|
||||
return
|
||||
|
||||
# Copy the current image to the offscreen canvas. In double-sided
|
||||
@@ -790,8 +815,10 @@ class DisplayManager:
|
||||
else:
|
||||
self.offscreen_canvas.SetImage(self.image)
|
||||
|
||||
# Swap buffers immediately
|
||||
self.matrix.SwapOnVSync(self.offscreen_canvas)
|
||||
# Swap buffers immediately. framerate_fraction holds the frame
|
||||
# for N refreshes; SwapOnVSync blocks for all of them, which is
|
||||
# what paces the render loop to the chosen frame rate.
|
||||
self.matrix.SwapOnVSync(self.offscreen_canvas, self._frame_hold)
|
||||
|
||||
# Swap our canvas references
|
||||
self.offscreen_canvas, self.current_canvas = self.current_canvas, self.offscreen_canvas
|
||||
@@ -799,7 +826,7 @@ class DisplayManager:
|
||||
self._last_pushed_digest = digest
|
||||
|
||||
# Write a snapshot for the web preview (throttled)
|
||||
self._write_snapshot_if_due()
|
||||
self._write_snapshot_if_due(frame_checksum)
|
||||
except Exception as e:
|
||||
logger.error(f"Error updating display: {e}")
|
||||
|
||||
@@ -1280,12 +1307,65 @@ class DisplayManager:
|
||||
|
||||
return dt.strftime(f"%b %-d{suffix}")
|
||||
|
||||
def set_scrolling_state(self, is_scrolling: bool):
|
||||
"""Set the current scrolling state. Call this when a display starts/stops scrolling."""
|
||||
@property
|
||||
def refresh_hz(self) -> float:
|
||||
"""The panel's refresh rate in Hz, from the hardware config.
|
||||
|
||||
The authoritative place to ask, because a plugin only receives its own
|
||||
config section and cannot see display.hardware. Scroll pacing needs
|
||||
this: the speeds a panel can show in whole pixels are refresh_hz
|
||||
divided by the frame hold, so getting it wrong silently produces
|
||||
fractional-pixel motion. See src/common/scroll_config.py.
|
||||
|
||||
Note this is the configured *cap*, not necessarily what the panel
|
||||
achieves -- scripts/scroll_speeds.py --measure reports the real rate.
|
||||
"""
|
||||
hardware = (self.config.get('display') or {}).get('hardware') or {}
|
||||
try:
|
||||
value = float(hardware.get('limit_refresh_rate_hz') or 0)
|
||||
except (TypeError, ValueError):
|
||||
value = 0.0
|
||||
return value if value > 0 else 100.0
|
||||
|
||||
def set_frame_hold(self, refreshes: int) -> None:
|
||||
"""Hold each pushed frame for this many panel refreshes (>=1).
|
||||
|
||||
Set by the scroll configuration so a plugin can run at, say, 50px/s on
|
||||
a 100Hz panel as one whole pixel every second refresh, rather than half
|
||||
a pixel every refresh (which has to be blended or repeated unevenly).
|
||||
|
||||
Reset to 1 whenever scrolling stops, so one plugin's pacing cannot
|
||||
leak into the next thing on screen.
|
||||
"""
|
||||
try:
|
||||
value = int(refreshes)
|
||||
except (TypeError, ValueError):
|
||||
logger.warning("Ignoring unusable frame hold: %r", refreshes)
|
||||
return
|
||||
self._frame_hold = max(1, min(255, value))
|
||||
|
||||
def set_scrolling_state(self, is_scrolling: bool, frame_hold: int = 1):
|
||||
"""Set the current scrolling state, and this scroll's frame pacing.
|
||||
|
||||
Call this when a display starts or stops scrolling. ``frame_hold`` is
|
||||
how many panel refreshes each frame is held for -- 2 gives one whole
|
||||
pixel every second refresh, which is how a scroll runs at half the
|
||||
refresh rate without fractional pixel positions.
|
||||
|
||||
The hold is set here rather than once at plugin construction because
|
||||
it must not outlive the scroll that asked for it: plugins share one
|
||||
display manager, so a hold left set by whoever scrolled last would
|
||||
silently re-pace the next plugin. Passing it alongside the state makes
|
||||
the lifetime exactly the scroll, and the default of 1 means any caller
|
||||
that does not care gets a new frame every refresh.
|
||||
"""
|
||||
current_time = time.time()
|
||||
self._scrolling_state['is_scrolling'] = is_scrolling
|
||||
if is_scrolling:
|
||||
self._scrolling_state['last_scroll_activity'] = current_time
|
||||
self.set_frame_hold(frame_hold)
|
||||
else:
|
||||
self._frame_hold = 1
|
||||
logger.debug(f"Scrolling state set to: {is_scrolling}")
|
||||
|
||||
def is_currently_scrolling(self) -> bool:
|
||||
@@ -1416,11 +1496,20 @@ class DisplayManager:
|
||||
self._viewer_fresh = False
|
||||
return self._viewer_fresh
|
||||
|
||||
def _write_snapshot_if_due(self) -> None:
|
||||
def _write_snapshot_if_due(self, frame_checksum: Optional[int] = None) -> None:
|
||||
"""Mirror the current frame to the preview snapshot when the policy
|
||||
says it's worth it — see src/common/snapshot_policy.py. Unchanged
|
||||
frames are never re-encoded; without viewers the cadence drops to
|
||||
the idle keepalive."""
|
||||
the idle keepalive.
|
||||
|
||||
Args:
|
||||
frame_checksum: adler32 of the current frame, when the caller has
|
||||
already computed one. Dirty tracking checksums every frame a
|
||||
few lines above the call site, and re-deriving it here meant a
|
||||
second tobytes() plus a second pass over the whole framebuffer
|
||||
on every single frame — ~0.17ms per frame of the two combined
|
||||
at 256x64, paid 100 times a second to reach the same number.
|
||||
"""
|
||||
try:
|
||||
now = time.time()
|
||||
viewer_fresh = self._viewer_is_fresh(now)
|
||||
@@ -1430,7 +1519,8 @@ class DisplayManager:
|
||||
self._last_snapshot_ts = 0.0
|
||||
self._viewer_was_fresh = viewer_fresh
|
||||
|
||||
digest = zlib.adler32(self.image.tobytes())
|
||||
digest = (frame_checksum if frame_checksum is not None
|
||||
else zlib.adler32(self.image.tobytes()))
|
||||
action = snapshot_policy.decide(
|
||||
now, self._last_snapshot_ts, self._last_snapshot_touch_ts,
|
||||
viewer_fresh, digest != self._last_snapshot_digest)
|
||||
|
||||
@@ -506,9 +506,18 @@ class VisualTestDisplayManager:
|
||||
# Scrolling state (no-op interface compat)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def set_scrolling_state(self, is_scrolling: bool):
|
||||
"""Set the current scrolling state (no-op for testing)."""
|
||||
def set_scrolling_state(self, is_scrolling: bool, frame_hold: int = 1):
|
||||
"""Set the current scrolling state (no-op for testing).
|
||||
|
||||
``frame_hold`` mirrors the DisplayManager signature this change adds.
|
||||
The two are kept in step deliberately: a double that accepts arguments
|
||||
production does not lets a call pass every harness run and then raise
|
||||
TypeError on the panel, and a double that lacks one production has
|
||||
fails every render of a plugin that legitimately paces its scroll.
|
||||
Plugins begin passing it in ledmatrix-plugins#462.
|
||||
"""
|
||||
self._scrolling_state['is_scrolling'] = is_scrolling
|
||||
self._scrolling_state['frame_hold'] = frame_hold
|
||||
if is_scrolling:
|
||||
self._scrolling_state['last_scroll_activity'] = time.time()
|
||||
|
||||
|
||||
Reference in New Issue
Block a user