scrollkit 0.8.3__py3-none-any.whl

scrollkit/effects/drip_splash.py

@@ -0,0 +1,253 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Drip-splash animation — LEDs drip in from an edge (default the top) into place.
+
+The inverse of :func:`scrollkit.effects.show_reveal_splash`.  The screen starts
+blank; every lit pixel of the target image appears at the top of its column
+(y=0) and falls straight down, one row at a time, until it reaches its
+destination row — where it stops.  Pixels accumulate column-by-column until the
+full text/image is assembled.
+
+Within a column the *bottom-most* target launches first, so a higher-stopping
+drop can never overtake an already-settled one.  This preserves gaps (the holes
+in a ``:`` or the space between glyphs) with no per-drop collision checks.
+
+Each frame is one cheap whole-bitmap ``fill(0)`` (a single C call, ~9 µs on the
+MatrixPortal S3) followed by a per-pixel write for every visible drop — far
+cheaper than per-region bulk ops for sparse moving pixels.  A drop's position is
+a pure function of the frame number, so there is no per-frame allocation and no
+clear/redraw bookkeeping.
+
+The overlay's background (index 0) is **transparent**, so a drip composites over
+whatever else is on screen (e.g. a scrolling label) rather than blacking it out.
+Uses ``display.gfx`` (the same graphics context :class:`OverlayMask` uses) rather
+than a bare ``import displayio``, so the simulator's displayio is used on desktop
+and the hardware one on CircuitPython.
+
+Two ways to use it:
+
+* :func:`show_drip_splash` — a blocking convenience for setup-time splashes; it
+  runs the whole animation, holds, and removes the overlay.
+* :class:`DripReveal` — a *frame-driven* core for use inside a running display
+  loop (call :meth:`DripReveal.step` once per frame).  After it completes you can
+  leave the overlay in place so the assembled image stays on screen as the live
+  content, then update the value by starting a fresh ``DripReveal``.
+
+Typical usage::
+
+    from scrollkit.effects.drip_splash import show_drip_splash
+    from scrollkit.effects.reveal_splash import pixels_from_text
+
+    px = pixels_from_text("PIXEL", x=17, y=8)
+    px += pixels_from_text("RAIN", x=20, y=20)
+    await show_drip_splash(display, px, color=0x00CCFF)
+"""
+
+import asyncio
+
+
+__all__ = ['DripReveal', 'show_drip_splash']
+
+class DripReveal:
+    """Frame-driven drip-in of a fixed set of target pixels from an edge.
+
+    Build it with the target ``pixels`` (e.g. from :func:`pixels_from_font_text`)
+    and a ``direction`` ("top" default — drops fall down; or "bottom"/"left"/"right"
+    to enter from that edge), call :meth:`start` once with the display, then
+    :meth:`step` once per frame.
+    :meth:`step` renders the current frame into a transparent overlay and returns
+    ``True`` when the image is fully assembled.  The overlay persists until
+    :meth:`detach` is called, so a completed reveal can stay on screen as the live
+    image (the assembled pixels are exactly the target pixels — there is nothing
+    to swap in).
+    """
+
+    _DIRECTIONS = ("top", "bottom", "left", "right")
+
+    def __init__(self, pixels, color=0xFFFF00, fall_speed=1, stagger=2, direction="top"):
+        self.pixels = pixels
+        self.color = color
+        self.fall_speed = fall_speed if fall_speed > 1 else 1
+        self.stagger = stagger if stagger > 0 else 0
+        # Edge the drops enter from: "top" (default, fall down), "bottom" (rise up),
+        # "left" (slide right), or "right" (slide left). Top keeps the original look.
+        self.direction = direction if direction in self._DIRECTIONS else "top"
+        self._display = None
+        self._bitmap = None
+        self._tile = None
+        self._drops = []
+        self._last_frame = 0
+        self._frame = 0
+        self._started = False
+        self._w = 0
+        self._h = 0
+
+    def start(self, display):
+        """Create the transparent overlay layer and compute the drop schedule."""
+        gfx = display.gfx
+        w, h = display.width, display.height
+        self._w, self._h = w, h
+        self._bitmap = gfx.Bitmap(w, h, 2)
+        palette = gfx.Palette(2)
+        palette.make_transparent(0)          # composite over content below
+        palette[1] = self.color
+        self._tile = gfx.TileGrid(self._bitmap, pixel_shader=palette)
+        display.add_layer(self._tile)
+        self._display = display
+
+        # Group pixels by the FIXED axis (the column for top/bottom, the row for
+        # left/right); each drop travels along the other axis from the entry edge to
+        # its target. The pixel that travels FARTHEST in a group launches first so a
+        # drop never has to pass a settled one (gaps preserved, no collision checks).
+        vertical = self.direction in ("top", "bottom")
+        from_low = self.direction in ("top", "left")   # enters from coordinate 0
+        span = h if vertical else w
+        groups = {}
+        for (x, y) in self.pixels:
+            if 0 <= x < w and 0 <= y < h:
+                fixed = x if vertical else y
+                target = y if vertical else x
+                groups.setdefault(fixed, []).append(target)
+        drops = []
+        last_frame = 0
+        for fixed, targets in groups.items():
+            targets.sort(reverse=from_low)             # farthest-travelling first
+            for k, t in enumerate(targets):
+                launch = k * self.stagger
+                drops.append((fixed, t, launch))
+                dist = t if from_low else (span - 1 - t)
+                settle = launch + (dist + self.fall_speed - 1) // self.fall_speed
+                if settle > last_frame:
+                    last_frame = settle
+        self._drops = drops
+        self._last_frame = last_frame
+        self._frame = 0
+        self._started = True
+
+    @property
+    def has_pixels(self):
+        """True if there is anything to drip (start() must run first)."""
+        return bool(self._drops)
+
+    @property
+    def is_complete(self):
+        """True once every drop has reached its target."""
+        return self._started and self._frame > self._last_frame
+
+    def step(self):
+        """Render the current frame into the overlay and advance one frame.
+
+        Does NOT call ``display.show()`` — the caller (or the display loop) owns
+        that.  Returns ``True`` when the reveal is complete.
+        """
+        if not self._started or self.is_complete:
+            return True
+        b = self._bitmap
+        f = self._frame
+        fs = self.fall_speed
+        try:
+            b.fill(0)
+        except (AttributeError, TypeError):
+            for xx in range(self._w):
+                for yy in range(self._h):
+                    b[xx, yy] = 0
+        vertical = self.direction in ("top", "bottom")
+        from_low = self.direction in ("top", "left")
+        span = self._h if vertical else self._w
+        for (fixed, t, launch) in self._drops:
+            if f < launch:
+                continue                     # not released yet
+            moved = (f - launch) * fs
+            if from_low:
+                cur = moved if moved < t else t          # 0 -> t, then settled
+            else:
+                cur = (span - 1) - moved
+                if cur < t:
+                    cur = t                              # max -> t, then settled
+            if vertical:
+                b[fixed, cur] = 1
+            else:
+                b[cur, fixed] = 1
+        self._frame += 1
+        return self.is_complete
+
+    def detach(self):
+        """Remove the overlay layer from the display (no-op if already gone)."""
+        if self._display is not None and self._tile is not None:
+            self._display.remove_layer(self._tile)
+            self._tile = None
+
+
+async def show_drip_splash(
+    display,
+    pixels,
+    color=0xFFFF00,
+    fall_speed=1,
+    stagger=2,
+    hold_seconds=2.0,
+    direction="top",
+):
+    """Play a drip-in animation on ``display`` (blocking convenience wrapper).
+
+    Every pixel in ``pixels`` enters from one edge (the top by default — drops fall
+    down their column) and settles at its target position; the assembled image then
+    holds for ``hold_seconds`` before the overlay is removed.  Built on
+    :class:`DripReveal`.
+
+    Args:
+        display:      A ScrollKit display (``UnifiedDisplay``/``SimulatorDisplay``).
+        pixels:       Iterable of ``(x, y)`` tuples — the target image.  Build one
+                      with :func:`pixels_from_text` / :func:`pixels_from_font_text`
+                      or supply pixel art.
+        color:        24-bit RGB color of the drops (default: yellow 0xFFFF00).
+        fall_speed:   Rows a drop descends per frame (>=1).  Higher = faster fall.
+        stagger:      Frames between successive drops launching in the same
+                      column (>=0).  Higher = a sparser, more deliberate drip;
+                      0 launches a whole column at once.
+        hold_seconds: Seconds to hold the finished image before finishing.
+        direction:    Edge the drops enter from — ``"top"`` (default, fall down),
+                      ``"bottom"`` (rise up), ``"left"`` (slide right), or ``"right"``
+                      (slide left).
+
+    Returns:
+        ``True`` when the animation finished normally; ``False`` if it was cut
+        short because the display reported a close (the simulator window was
+        closed).  On hardware ``show()`` never reports a close, so this is
+        always ``True`` there.  Callers that loop the effect can stop on
+        ``False``.
+    """
+    reveal = DripReveal(pixels, color=color, fall_speed=fall_speed, stagger=stagger,
+                        direction=direction)
+    reveal.start(display)
+    if not reveal.has_pixels:
+        reveal.detach()
+        return True
+
+    while not reveal.is_complete:
+        reveal.step()
+        if await display.show() is False:    # simulator window closed
+            reveal.detach()
+            return False
+        await asyncio.sleep(0.02)
+
+    await asyncio.sleep(hold_seconds)
+    reveal.detach()
+    return True
+
+
+# --- advertised feasibility metadata (US7 / FR-026) -------------------------
+# Per frame: one whole-bitmap C fill (~9 us) + one per-pixel write per launched
+# drop (~7 us each). Total writes are bounded by the lit-pixel count of the
+# image (a few hundred for typical text), so even a dense 512-px image is
+# ~9 us + 512*7 us ~= 3.6 ms — well inside the 50 ms (20 fps) budget. No
+# per-frame allocation (the drop list is built once; positions are recomputed).
+# NOTE: FEASIBILITY is attached to the CLASS only. CircuitPython/MicroPython does
+# not allow setting attributes on function objects, so the convenience wrapper
+# does NOT carry it (callers read DripReveal.FEASIBILITY). Setting it on a
+# function crashes `import scrollkit.effects` on-device.
+_FEASIBILITY = {
+    "hardware_safe": True,
+    "allocates_per_frame": False,
+    "max_pixel_writes_per_frame": 512,
+    "modeled_frame_ms": 4.0,
+}
+DripReveal.FEASIBILITY = _FEASIBILITY

scrollkit/effects/easing.py

@@ -0,0 +1,131 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Integer easing/tween lookup tables (CircuitPython-safe).
+
+Each named curve is a length-256 ``bytes`` table mapping a 0..255 progress to a
+0..255 eased value, built **once** at import. ``ease()`` is a pure table lookup
+— no float math and no allocation on the hot path. Six curves of 256 bytes each
+is ~1.5 KB of static RAM.
+
+Table values are clamped to 0..255; a curve that conceptually overshoots past the
+endpoints (``OVERSHOOT``/``ELASTIC``) is clamped in storage, and an effect that
+wants the overshoot expresses it by scaling the eased value itself.
+
+The float math below runs at import only (once); the device imports this once and
+then only ever indexes the tables.
+"""
+
+import math
+
+# Curve ids (plain strings — no enum, CircuitPython-friendly).
+LINEAR = "linear"
+EASE_OUT_QUAD = "ease_out_quad"
+EASE_IN_OUT = "ease_in_out"
+OVERSHOOT = "overshoot"
+BOUNCE = "bounce"
+ELASTIC = "elastic"
+
+CURVES = (LINEAR, EASE_OUT_QUAD, EASE_IN_OUT, OVERSHOOT, BOUNCE, ELASTIC)
+
+
+__all__ = ['ease', 'interp', 'CURVES', 'LINEAR', 'EASE_OUT_QUAD', 'EASE_IN_OUT', 'OVERSHOOT', 'BOUNCE', 'ELASTIC']
+
+def _clamp_byte(v):
+    if v < 0:
+        return 0
+    if v > 255:
+        return 255
+    return int(round(v))
+
+
+def _f_linear(t):
+    return t
+
+
+def _f_ease_out_quad(t):
+    return 1.0 - (1.0 - t) * (1.0 - t)
+
+
+def _f_ease_in_out(t):
+    if t < 0.5:
+        return 2.0 * t * t
+    return 1.0 - 2.0 * (1.0 - t) * (1.0 - t)
+
+
+def _f_overshoot(t):
+    # Back ease-out: overshoots above 1.0 then settles (clamped in storage).
+    c1 = 1.70158
+    c3 = c1 + 1.0
+    u = t - 1.0
+    return 1.0 + c3 * u * u * u + c1 * u * u
+
+
+def _f_bounce(t):
+    # Standard ease-out bounce.
+    n1 = 7.5625
+    d1 = 2.75
+    if t < 1.0 / d1:
+        return n1 * t * t
+    if t < 2.0 / d1:
+        t -= 1.5 / d1
+        return n1 * t * t + 0.75
+    if t < 2.5 / d1:
+        t -= 2.25 / d1
+        return n1 * t * t + 0.9375
+    t -= 2.625 / d1
+    return n1 * t * t + 0.984375
+
+
+def _f_elastic(t):
+    # Ease-out elastic (lite). Endpoints pinned below.
+    if t <= 0.0:
+        return 0.0
+    if t >= 1.0:
+        return 1.0
+    c4 = (2.0 * math.pi) / 3.0
+    return math.pow(2.0, -10.0 * t) * math.sin((t * 10.0 - 0.75) * c4) + 1.0
+
+
+_FUNCS = {
+    LINEAR: _f_linear,
+    EASE_OUT_QUAD: _f_ease_out_quad,
+    EASE_IN_OUT: _f_ease_in_out,
+    OVERSHOOT: _f_overshoot,
+    BOUNCE: _f_bounce,
+    ELASTIC: _f_elastic,
+}
+
+
+def _build(fn):
+    out = bytearray(256)
+    for p in range(256):
+        t = p / 255.0
+        out[p] = _clamp_byte(fn(t) * 255.0)
+    out[0] = 0          # pin endpoints
+    out[255] = 255
+    return bytes(out)
+
+
+_TABLES = {name: _build(fn) for name, fn in _FUNCS.items()}
+
+
+def ease(curve, progress_0_255):
+    """Return the eased 0..255 value for ``progress`` (0..255) on ``curve``.
+
+    Pure ``bytes`` lookup: no floats, no allocation. Unknown curves fall back to
+    linear. ``progress`` is clamped to 0..255.
+    """
+    table = _TABLES.get(curve)
+    if table is None:
+        table = _TABLES[LINEAR]
+    p = progress_0_255
+    if p < 0:
+        p = 0
+    elif p > 255:
+        p = 255
+    return table[p]
+
+
+def interp(curve, a, b, progress_0_255):
+    """Integer interpolation from ``a`` to ``b`` along ``curve`` (no floats)."""
+    e = ease(curve, progress_0_255)
+    return a + ((b - a) * e) // 255

scrollkit/effects/overlay.py

@@ -0,0 +1,92 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Preallocated overlay-mask layer (Phase 3 primitive; substrate for transitions).
+
+One reusable indexed Bitmap (transparent index 0) + Palette + TileGrid, added as a
+display layer composited ABOVE content. A whole class of transitions becomes
+"write a small pattern into the mask": cover regions with an opaque index, reveal
+by setting them back to transparent. Allocated ONCE; every mutation touches only
+dirty spans via the C bulk ops in ``display.gfx.bitmaptools`` — never a full-2048
+Python loop, never a per-frame allocation. Runs unchanged on device and simulator.
+"""
+
+
+__all__ = ['OverlayMask']
+
+class OverlayMask:
+    """A reusable full-screen mask layer for cover -> swap -> reveal transitions.
+
+    Index 0 is transparent (underlying content shows through); indices 1..N are
+    opaque cover colors (index 1 defaults to black). Build once, reuse across
+    transitions (``clear()`` resets it); ``detach()`` removes the layer.
+    """
+
+    def __init__(self, display, value_count=4):
+        self._display = display
+        gfx = display.gfx
+        self._gfx = gfx
+        self._w = display.width
+        self._h = display.height
+        self.bitmap = gfx.Bitmap(self._w, self._h, value_count)
+        self.palette = gfx.Palette(value_count)
+        self.palette.make_transparent(0)       # index 0 = transparent
+        if value_count > 1:
+            self.palette[1] = 0x000000          # default opaque cover = black
+        self.tilegrid = gfx.TileGrid(self.bitmap, pixel_shader=self.palette)
+        display.add_layer(self.tilegrid)
+
+    # --- palette --------------------------------------------------------------
+    def set_cover_color(self, index, color):
+        """Set the color of an opaque cover index (1..N)."""
+        self.palette[index] = color
+
+    # --- bounded mutators (dirty-span only) -----------------------------------
+    def _clip(self, x, y, w, h):
+        x0 = x if x > 0 else 0
+        y0 = y if y > 0 else 0
+        x1 = x + w
+        y1 = y + h
+        if x1 > self._w:
+            x1 = self._w
+        if y1 > self._h:
+            y1 = self._h
+        if x1 < x0:
+            x1 = x0
+        if y1 < y0:
+            y1 = y0
+        return x0, y0, x1, y1
+
+    def _account(self, kind, px):
+        pm = getattr(self._display, "_perf", None)
+        if pm is not None:
+            pm.account_bulk_op(kind, px)
+
+    async def fill_rect(self, x, y, w, h, index=1):
+        """Cover a clipped rectangle with an opaque ``index`` via a C bulk op."""
+        x0, y0, x1, y1 = self._clip(x, y, w, h)
+        if x1 > x0 and y1 > y0:
+            self._gfx.bitmaptools.fill_region(self.bitmap, x0, y0, x1, y1, index)
+            self._account("fill_region", (x1 - x0) * (y1 - y0))
+
+    async def fill_span(self, y, x0, x1, index=1):
+        """Cover the single-row span ``[x0, x1)``."""
+        await self.fill_rect(x0, y, x1 - x0, 1, index)
+
+    async def clear_rect(self, x, y, w, h):
+        """Reveal a clipped rectangle (set back to transparent index 0)."""
+        await self.fill_rect(x, y, w, h, 0)
+
+    async def clear(self):
+        """Reset the whole mask to transparent (one bulk fill). Reusable."""
+        self.bitmap.fill(0)
+        self._account("fill_region", self._w * self._h)
+
+    async def blit_pattern(self, x, y, pattern_bitmap, *, skip_index=0):
+        """Stamp a small pattern bitmap into the mask (transparent ``skip_index``)."""
+        self._gfx.bitmaptools.blit(self.bitmap, pattern_bitmap, x, y,
+                                   skip_index=skip_index)
+        self._account("blit", pattern_bitmap.width * pattern_bitmap.height)
+
+    # --- lifecycle ------------------------------------------------------------
+    def detach(self):
+        """Remove the mask's layer from the display."""
+        self._display.remove_layer(self.tilegrid)