scrollkit 0.8.3__py3-none-any.whl

scrollkit/simulator/core/performance_manager.py

@@ -0,0 +1,253 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Models how slow the real CircuitPython hardware runs.
+
+It works by ACCUMULATING modeled time per frame — it does NOT actually sleep
+(unless ``throttle=True``), so the simulator and the headless test suite stay
+fast. The accumulated time becomes an estimated *hardware* frame time / FPS in a
+FeasibilityReport.
+
+Wired into the previously-dead hooks in ``core/led_matrix.py`` plus one hook in
+``adafruit_display_text/label.py`` (looked up lazily via the module-level active
+manager, so there's zero cost and no constructor threading when it's off).
+
+Desktop/simulator only — never imported on hardware.
+"""
+
+from collections import deque
+
+from .hardware_profile import HardwareProfile  # noqa: F401  (re-exported for callers)
+
+
+# --- module-level active manager (for the lazy Label hook) ---------------------
+_active = None
+
+
+def set_active(manager):
+    """Register the manager the Label bitmap-rebuild hook should report to."""
+    global _active
+    _active = manager
+
+
+def get_active():
+    """Return the active PerformanceManager, or None when disabled (the default)."""
+    return _active
+
+
+class FrameCost:
+    """Modeled microseconds for one frame, split by category."""
+
+    __slots__ = ("pixel_writes_us", "refresh_us", "bitmap_rebuild_us", "gc_us",
+                 "bulk_ops_us")
+
+    def __init__(self):
+        self.pixel_writes_us = 0.0
+        self.refresh_us = 0.0
+        self.bitmap_rebuild_us = 0.0
+        self.gc_us = 0.0
+        self.bulk_ops_us = 0.0     # C bulk ops (fill_region/blit) from the painters
+
+    @property
+    def total_us(self):
+        return (self.pixel_writes_us + self.refresh_us
+                + self.bitmap_rebuild_us + self.gc_us + self.bulk_ops_us)
+
+    def as_dict(self):
+        return {
+            "pixel_writes_us": self.pixel_writes_us,
+            "refresh_us": self.refresh_us,
+            "bitmap_rebuild_us": self.bitmap_rebuild_us,
+            "gc_us": self.gc_us,
+            "bulk_ops_us": self.bulk_ops_us,
+            "total_us": self.total_us,
+        }
+
+
+class PerformanceManager:
+    """Cost accumulator behind the simulator's performance hooks."""
+
+    def __init__(self, profile, enabled=True, throttle=False, history=120,
+                 ambient_warnings=None, warn_interval=30, stutter_fps=10.0,
+                 strict=False, target_fps=20.0, warmup_frames=2,
+                 gate_window=8, transient_factor=2.0):
+        self.profile = profile
+        self.enabled = enabled            # read by led_matrix hooks
+        self.throttle = throttle          # if True, also real-sleep to crawl the window
+        # Periodic console "this would stutter on hardware" nags. Default: follow
+        # throttle (visceral mode), but can be toggled independently (so tests can
+        # exercise the warning logic without actually sleeping).
+        self.ambient_warnings = throttle if ambient_warnings is None else ambient_warnings
+        self.warn_interval = warn_interval   # min frames between ambient nags
+        self.stutter_fps = stutter_fps       # warn when modeled FPS drops below this
+        self.last_warning = None             # most recent ambient nag (for UIs/tests)
+        # --- strict feasibility gate (opt-in; default off keeps the warning path)
+        self.strict = strict
+        self.target_fps = target_fps
+        self.warmup_frames = warmup_frames   # leading frames exempt (one-time setup)
+        self.gate_window = max(1, gate_window)
+        self.transient_factor = transient_factor
+        self.frame_budget_us = 1_000_000.0 / target_fps          # 50_000 at 20 fps
+        self.transient_budget_us = self.frame_budget_us * transient_factor
+        self._frame = FrameCost()
+        self._frames = deque(maxlen=history)
+        self._frame_index = 0
+        self._last_warn_frame = 0
+        self._max_bitmap_px = 0           # largest live text bitmap seen (RAM proxy)
+
+    # --- hooks called by core/led_matrix.py (existing signatures) -------------
+    def simulate_instruction_delay(self, n):
+        """Per matrix.set_pixel(): n is a fixed weight, not a pixel count."""
+        self._frame.pixel_writes_us += n * self.profile.pixel_write_us
+
+    def simulate_io_operation(self, kind):
+        """A display.refresh() — also the frame boundary (one refresh == one frame)."""
+        if kind == "display_refresh":
+            self._frame.refresh_us += self.profile.full_refresh_us
+            self._end_frame()
+
+    def simulate_gc_pause(self):
+        if self._frame_index % self.profile.gc_every_n_frames == 0:
+            self._frame.gc_us += self.profile.gc_pause_us
+
+    # --- hook called by adafruit_display_text/label.py _update_text -----------
+    def account_bitmap_rebuild(self, width_px, height_px):
+        """A Label rebuilt its glyph bitmap (the dominant cost for scrolling text)."""
+        px = max(0, width_px) * max(0, height_px)
+        self._frame.bitmap_rebuild_us += px * self.profile.bitmap_rebuild_us_per_px
+        if px > self._max_bitmap_px:
+            self._max_bitmap_px = px
+
+    # --- hook called by the display span/rect painters + overlay --------------
+    def account_bulk_op(self, kind, px):
+        """A C bulk op (``fill_region`` / ``blit``) touched ``px`` clipped pixels.
+
+        Cost = ``bulk_base_us`` (fixed per-call C dispatch) + ``px * slope`` for
+        the op. The base over-counts slightly on purpose so the strict gate fails
+        safe. ``px`` is the clipped/scanned pixel count (a fully-clipped no-op
+        still pays the base).
+        """
+        px = max(0, px)
+        if kind == "blit":
+            slope = self.profile.blit_us_per_px
+        else:  # "fill_region" (and any other bounded fill)
+            slope = self.profile.fill_region_us_per_px
+        self._frame.bulk_ops_us += self.profile.bulk_base_us + px * slope
+
+    # --- frame bookkeeping ----------------------------------------------------
+    def _end_frame(self):
+        total_us = self._frame.total_us
+        self._frames.append(self._frame)
+        self._frame_index += 1
+        # Reset the live frame BEFORE the strict gate can raise, so a caller that
+        # catches FeasibilityError and keeps rendering doesn't accumulate the next
+        # frame's cost onto the (already-appended) aborted frame and corrupt the
+        # rolling history. The appended frame stays valid in self._frames.
+        self._frame = FrameCost()
+        # Strict feasibility gate (opt-in). Past the warmup grace, a sustained
+        # over-budget run (steady-state median) or a single catastrophic frame
+        # (transient ceiling) or a RAM breach raises FeasibilityError, stopping
+        # the run at the offending frame. Default (strict=False) skips all of this
+        # so the warning path below is unchanged.
+        if self.strict and self._frame_index > self.warmup_frames:
+            self._enforce_strict(total_us)
+        # Visceral mode: actually sleep the modeled frame time so the live window
+        # crawls at hardware speed.
+        if self.throttle and total_us > 0:
+            import time
+            try:
+                time.sleep(total_us / 1_000_000.0)
+            except (ValueError, OSError):
+                pass
+        if self.ambient_warnings:
+            self._maybe_emit_ambient_warning(total_us)
+
+    def _enforce_strict(self, total_us):
+        """Raise FeasibilityError if this frame busts the device budget."""
+        from ...exceptions import FeasibilityError
+        # 1) Transient ceiling: a single catastrophic frame (e.g. 2 full rebuilds).
+        if total_us > self.transient_budget_us:
+            raise FeasibilityError(self._budget_message(
+                "single frame", total_us, self.transient_budget_us))
+        # 2) Steady-state: the median over the rolling window must hold the budget.
+        #    Only meaningful once the window is full, so an isolated rebuild spike
+        #    is absorbed rather than triggering a false trip.
+        totals = [f.total_us for f in self._frames]
+        if len(totals) >= self.gate_window:
+            window = totals[-self.gate_window:]
+            med = self._median(window)
+            if med > self.frame_budget_us:
+                raise FeasibilityError(self._budget_message(
+                    "median over %d frames" % self.gate_window, med,
+                    self.frame_budget_us))
+        # 3) RAM: must fit the usable device RAM.
+        peak = self.estimated_peak_ram_bytes()
+        if peak > self.profile.usable_ram_bytes:
+            raise FeasibilityError(
+                "[hw-strict] frame %d: modeled peak RAM ~%d KB exceeds the device's "
+                "usable ~%d KB. Reduce content/effects."
+                % (self._frame_index, peak // 1024,
+                   self.profile.usable_ram_bytes // 1024))
+
+    def _budget_message(self, scope, us, budget_us):
+        fps = 1_000_000.0 / us if us > 0 else 0.0
+        budget_fps = 1_000_000.0 / budget_us if budget_us > 0 else 0.0
+        return ("[hw-strict] frame %d: %s ~%d ms/frame (~%d fps) exceeds the "
+                "%d ms budget (%d fps); dominant: %s. Reuse Labels, avoid per-frame "
+                "glyph rebuild, and express bounded work through the C bulk painters."
+                % (self._frame_index, scope, round(us / 1000.0), round(fps),
+                   round(budget_us / 1000.0), round(budget_fps),
+                   self._dominant_component()))
+
+    def _dominant_component(self):
+        last = self._frames[-1] if self._frames else self._frame
+        cats = last.as_dict()
+        cats.pop("total_us", None)
+        if not cats:
+            return "unknown"
+        return max(cats, key=lambda k: cats[k]).replace("_us", "")
+
+    @staticmethod
+    def _median(values):
+        s = sorted(values)
+        n = len(s)
+        if n == 0:
+            return 0.0
+        mid = n // 2
+        return s[mid] if n % 2 else (s[mid - 1] + s[mid]) / 2.0
+
+    def _maybe_emit_ambient_warning(self, frame_total_us):
+        """Periodically nag when the modeled frame time implies a stuttery FPS.
+
+        Rate-limited to one nag per ``warn_interval`` frames so it informs rather
+        than floods. Routed through ``_emit`` so callers/tests can redirect it.
+        """
+        if frame_total_us <= 0:
+            return
+        if self._frame_index - self._last_warn_frame < self.warn_interval:
+            return
+        fps = 1_000_000.0 / frame_total_us
+        if fps >= self.stutter_fps:
+            return
+        self._last_warn_frame = self._frame_index
+        msg = ("[hw-sim] frame %d: ~%d ms/frame (~%d FPS) on the real device — "
+               "this would stutter. (estimate)"
+               % (self._frame_index, round(frame_total_us / 1000.0), round(fps)))
+        self.last_warning = msg
+        self._emit(msg)
+
+    def _emit(self, msg):
+        """Where ambient nags go. Overridable; defaults to stdout."""
+        print(msg)
+
+    # --- reporting ------------------------------------------------------------
+    @property
+    def frames(self):
+        return list(self._frames)
+
+    def estimated_peak_ram_bytes(self):
+        """Rough modeled peak RAM: app floor + largest live text bitmap."""
+        return int(self.profile.base_app_ram_bytes
+                   + self._max_bitmap_px * self.profile.bytes_per_label_px)
+
+    def report(self):
+        from .feasibility import FeasibilityReport
+        return FeasibilityReport.from_manager(self)

scrollkit/simulator/core/pixel_buffer.py

@@ -0,0 +1,188 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Pixel buffer management for LED matrix simulation."""
+
+import numpy as np
+
+
+class PixelBuffer:
+    """Manages the pixel data for an LED matrix.
+    
+    This class provides efficient storage and manipulation of pixel data
+    using numpy arrays for performance.
+    """
+    
+    def __init__(self, width, height):
+        """Initialize pixel buffer.
+        
+        Args:
+            width: Width of the matrix in pixels
+            height: Height of the matrix in pixels
+        """
+        self.width = width
+        self.height = height
+        # Store pixels as RGB888 internally for better color accuracy
+        self._buffer = np.zeros((height, width, 3), dtype=np.uint8)
+        self._dirty = True
+        self._dirty_region = None
+        
+    def set_pixel(self, x, y, color):
+        """Set a single pixel color.
+        
+        Args:
+            x: X coordinate (0 to width-1)
+            y: Y coordinate (0 to height-1)
+            color: Color as (r, g, b) tuple or single RGB value
+        """
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            return
+            
+        if isinstance(color, (list, tuple)):
+            self._buffer[y, x] = color[:3]
+        else:
+            # Assume it's a packed RGB value
+            r = (color >> 16) & 0xFF
+            g = (color >> 8) & 0xFF
+            b = color & 0xFF
+            self._buffer[y, x] = [r, g, b]
+            
+        self._mark_dirty(x, y, x, y)
+        
+    def get_pixel(self, x, y):
+        """Get a single pixel color.
+        
+        Args:
+            x: X coordinate (0 to width-1)
+            y: Y coordinate (0 to height-1)
+            
+        Returns:
+            Color as (r, g, b) tuple
+        """
+        if not (0 <= x < self.width and 0 <= y < self.height):
+            return (0, 0, 0)
+        return tuple(self._buffer[y, x])
+        
+    def fill(self, color):
+        """Fill entire buffer with a single color.
+        
+        Args:
+            color: Color as (r, g, b) tuple or single RGB value
+        """
+        if isinstance(color, (list, tuple)):
+            self._buffer[:] = color[:3]
+        else:
+            r = (color >> 16) & 0xFF
+            g = (color >> 8) & 0xFF
+            b = color & 0xFF
+            self._buffer[:] = [r, g, b]
+            
+        self._dirty = True
+        self._dirty_region = None
+        
+    def clear(self):
+        """Clear all pixels to black."""
+        self._buffer.fill(0)
+        self._dirty = True
+        self._dirty_region = None
+        
+    def blit(self, source, x=0, y=0, key_color=None):
+        """Copy pixels from another buffer.
+        
+        Args:
+            source: Source PixelBuffer
+            x: Destination X coordinate
+            y: Destination Y coordinate
+            key_color: Optional color to treat as transparent
+        """
+        # Calculate source and destination regions
+        src_x = max(0, -x)
+        src_y = max(0, -y)
+        dst_x = max(0, x)
+        dst_y = max(0, y)
+        
+        copy_width = min(source.width - src_x, self.width - dst_x)
+        copy_height = min(source.height - src_y, self.height - dst_y)
+        
+        if copy_width <= 0 or copy_height <= 0:
+            return
+            
+        # Copy the pixel data
+        src_data = source._buffer[src_y:src_y + copy_height, src_x:src_x + copy_width]
+        
+        if key_color is not None:
+            # Create mask for non-transparent pixels
+            if isinstance(key_color, (list, tuple)):
+                mask = np.any(src_data != key_color[:3], axis=2)
+            else:
+                r = (key_color >> 16) & 0xFF
+                g = (key_color >> 8) & 0xFF
+                b = key_color & 0xFF
+                mask = np.any(src_data != [r, g, b], axis=2)
+                
+            # Only copy non-transparent pixels
+            dst_slice = self._buffer[dst_y:dst_y + copy_height, dst_x:dst_x + copy_width]
+            dst_slice[mask] = src_data[mask]
+        else:
+            # Copy all pixels
+            self._buffer[dst_y:dst_y + copy_height, dst_x:dst_x + copy_width] = src_data
+            
+        self._mark_dirty(dst_x, dst_y, dst_x + copy_width - 1, dst_y + copy_height - 1)
+        
+    def get_buffer(self):
+        """Get the raw numpy buffer.
+        
+        Returns:
+            Numpy array of shape (height, width, 3)
+        """
+        return self._buffer
+        
+    def is_dirty(self):
+        """Check if buffer has been modified.
+        
+        Returns:
+            True if buffer has been modified since last clear_dirty()
+        """
+        return self._dirty
+        
+    def get_dirty_region(self):
+        """Get the region that has been modified.
+        
+        Returns:
+            Tuple of (x1, y1, x2, y2) or None if entire buffer is dirty
+        """
+        return self._dirty_region
+        
+    def clear_dirty(self):
+        """Clear the dirty flag."""
+        self._dirty = False
+        self._dirty_region = None
+        
+    def _mark_dirty(self, x1, y1, x2, y2):
+        """Mark a region as dirty.
+        
+        Args:
+            x1, y1: Top-left corner
+            x2, y2: Bottom-right corner
+        """
+        self._dirty = True
+        
+        if self._dirty_region is None:
+            self._dirty_region = (x1, y1, x2, y2)
+        else:
+            # Expand existing dirty region
+            old_x1, old_y1, old_x2, old_y2 = self._dirty_region
+            self._dirty_region = (
+                min(x1, old_x1),
+                min(y1, old_y1),
+                max(x2, old_x2),
+                max(y2, old_y2)
+            )
+            
+    def apply_brightness(self, brightness):
+        """Apply brightness adjustment to all pixels.
+        
+        Args:
+            brightness: Float from 0.0 to 1.0
+        """
+        self._buffer = (self._buffer * brightness).astype(np.uint8)
+        self._dirty = True
+        self._dirty_region = None

scrollkit/simulator/devices/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""SLDK simulator device implementations."""
+
+from .matrixportal_s3 import MatrixPortalS3
+from .base_device import BaseDevice
+
+__all__ = ['MatrixPortalS3', 'BaseDevice']

scrollkit/simulator/devices/base_device.py

@@ -0,0 +1,79 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Base class for LED matrix devices."""
+
+from abc import ABC, abstractmethod
+from ..core import LEDMatrix
+from ..displayio import Display, FourWire
+
+
+class BaseDevice(ABC):
+    """Abstract base class for LED matrix devices.
+    
+    Provides common functionality for all simulated devices.
+    """
+    
+    def __init__(self, width, height, pitch=4.0):
+        """Initialize base device.
+        
+        Args:
+            width: Display width in pixels
+            height: Display height in pixels
+            pitch: LED pitch in mm
+        """
+        self.width = width
+        self.height = height
+        self.pitch = pitch
+        
+        # Display components
+        self.display = None
+        self.matrix = None
+        self.display_bus = None
+
+        # Performance simulation (optional)
+        self.performance_manager = None
+        
+    @abstractmethod
+    def initialize(self):
+        """Initialize the device.
+        
+        Must be implemented by subclasses.
+        """
+        raise NotImplementedError
+        
+    def set_brightness(self, brightness):
+        """Set display brightness.
+        
+        Args:
+            brightness: Brightness value from 0.0 to 1.0
+        """
+        if self.display:
+            self.display.brightness = brightness
+            
+    def clear(self):
+        """Clear the display."""
+        if self.matrix:
+            self.matrix.clear()
+            
+    def show(self, group_or_tilegrid):
+        """Show a Group or TileGrid on the display.
+        
+        Args:
+            group_or_tilegrid: Display object to show
+        """
+        if self.display:
+            self.display.root_group = group_or_tilegrid
+            
+    def refresh(self):
+        """Refresh the display."""
+        if self.display:
+            self.display.refresh()
+            
+    def get_surface(self):
+        """Get the pygame surface for this device.
+        
+        Returns:
+            Pygame surface or None
+        """
+        if self.matrix:
+            return self.matrix.get_surface()
+        return None

scrollkit/simulator/devices/matrixportal_s3.py

@@ -0,0 +1,87 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""MatrixPortal S3 device simulation."""
+
+from .base_device import BaseDevice
+from ..core import LEDMatrix
+from ..displayio import Display, FourWire
+
+
+class MatrixPortalS3(BaseDevice):
+    """Simulated Adafruit MatrixPortal S3 device.
+    
+    Standard configuration with 64x32 RGB LED matrix.
+    """
+    
+    def __init__(self, pitch=3.0, width=64, height=32):
+        """Initialize MatrixPortal S3.
+        
+        Args:
+            pitch: LED pitch in mm (default 3.0 for 192x96mm physical size)
+            width: Display width in pixels (default 64)
+            height: Display height in pixels (default 32)
+        """
+        super().__init__(width, height, pitch)
+        
+        # Board-specific attributes
+        self.NEOPIXEL = None  # Status NeoPixel (not simulated)
+        self.ACCELEROMETER = None  # LIS3DH accelerometer (not simulated)
+        
+    def initialize(self):
+        """Initialize MatrixPortal S3 specific features."""
+        # Create LED matrix
+        self.matrix = LEDMatrix(
+            self.width, 
+            self.height, 
+            pitch=self.pitch,
+            performance_manager=self.performance_manager
+        )
+        
+        # Create display bus (stub for compatibility)
+        self.display_bus = FourWire(
+            spi_bus=None,
+            command=None,
+            chip_select=None,
+            reset=None
+        )
+        
+        # Create display
+        self.display = Display(
+            self.display_bus,
+            width=self.width,
+            height=self.height,
+            rotation=0,
+            color_depth=16,
+            auto_refresh=True
+        )
+        
+        # Link display to matrix
+        self.display._matrix = self.matrix
+        
+        # Create board module stub
+        self._create_board_module()
+        
+    def _create_board_module(self):
+        """Create board module attributes for compatibility."""
+        # This would normally be done by importing board
+        # but we create a simple stub here
+        class BoardStub:
+            def __init__(self, display):
+                self.DISPLAY = display
+                
+        self.board = BoardStub(self.display)
+        
+    def set_text_color(self, color):
+        """Set default text color (convenience method).
+        
+        Args:
+            color: RGB color value
+        """
+        # This is a convenience method not in the real hardware
+        # but useful for the simulator
+        pass
+        
+    @property
+    def default_font(self):
+        """Get the default font for this device."""
+        from ..terminalio import FONT
+        return FONT

scrollkit/simulator/displayio/__init__.py

@@ -0,0 +1,12 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""CircuitPython displayio compatibility layer."""
+
+from .bitmap import Bitmap
+from .group import Group
+from .palette import Palette
+from .tilegrid import TileGrid
+from .ondiskbitmap import OnDiskBitmap
+from .display import Display
+from .fourwire import FourWire
+
+__all__ = ['Bitmap', 'Group', 'Palette', 'TileGrid', 'OnDiskBitmap', 'Display', 'FourWire']