ChuckandClaude Opus 5.5
4f30bc62ca
The render thread spends most of each refresh in SwapOnVSync with the GIL released, then needs it back the moment the swap returns. With plugin rendering on the prefetch thread, it often has to wait for it -- behind bytecode for up to the switch interval, behind a GIL-holding C call for as long as that takes -- and hdpi's late frames of 2-5 refreshes went up. src/common/render_gate.py opens a window around each swap, up to just before the refresh the swap will return on, and a profile hook on the prefetch thread parks it outside that window. It is never parked holding a lock the render thread also takes (the Vegas buffer, cache and state locks, logging, threading, importlib, the cache), never when no frame has been swapped for 50ms, and never for more than 50ms at a time. Off by default and ignored on a binding that keeps the GIL in SwapOnVSync, where the window would never let the prefetch run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Common Utilities
This directory contains reusable utilities and helpers for LEDMatrix plugins and core modules.
Adaptive Layout & Images (src/adaptive_layout.py, src/adaptive_images.py)
The recommended way to lay out plugins that render legibly on any panel
size (64x32 through 256x128+) without hand-tuned coordinates. Re-exported
from src.common for convenience; canonical import paths are
src.adaptive_layout / src.adaptive_images.
# Every BasePlugin already has self.layout and the draw helpers:
regs = scoreboard_regions(self.layout.bounds, ctx=self.layout)
self.draw_image(away_logo, regs.away_slot, mode="fill_height",
crop_to_ink=True, cache_key=f"logo:{abbr}")
self.draw_fit(score_text, regs.score_area) # largest crisp font that fits
self.draw_fit(status, regs.status_band)
Key pieces: Region (rect algebra: bands/columns/splits/offset),
font ladders (LADDER_GRID, LADDER_ARCADE — discrete crisp sizes, never
fractional scaling), LayoutContext (fit_text, fit_image, by_tier,
px), and composite carvers scoreboard_regions() / media_row().
Full guide: docs/ADAPTIVE_LAYOUT.md.
API Helpers (api_helper.py)
Utilities for making HTTP requests and handling API responses.
Logo Helpers (logo_helper.py)
Utilities for loading and managing team logos.
Text Helpers (text_helper.py)
Utilities for text processing and formatting.
Scroll Helpers (scroll_helper.py)
Utilities for scrolling text on the display.
Permission Utilities (permission_utils.py)
Helpers for ensuring directory permissions and ownership are correct
when running as a service (used by CacheManager to set up its
persistent cache directory).
Best Practices
- Use centralized logging: Import from
src.logging_configinstead of creating loggers directly - Reuse utilities: Check existing utilities before creating new ones
- Document additions: Add documentation when adding new utilities