Source code for displaydev.pixeldisplay

# SPDX-FileCopyrightText: 2024 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""
displaydev.pixeldisplay — addressable LED grids (NeoPixel, DotStar, etc.).

MicroPython: ``PixelFramebuffer`` (RGB888 grid + strip map) and ``PixelDisplay``
live here.  CircuitPython board configs use
``adafruit_pixel_framebuf.PixelFramebuffer`` with OmniPython ``PixelDisplay``.
"""

try:
    from micropython import const
except ImportError:

    def const(x):
        return x


from displaydev import DisplayDriver, color_rgb


def _color888_from_565(c):
    r, g, b = color_rgb(c)
    return (r << 16) | (g << 8) | b


def _rgb888_bytes(c):
    return bytes(((c >> 16) & 0xFF, (c >> 8) & 0xFF, c & 0xFF))


HORIZONTAL = const(1)
VERTICAL = const(2)


def _horizontal_strip_gridmap(width, alternating=True):
    def mapper(x, y):
        if alternating and y % 2:
            return y * width + (width - 1 - x)
        return y * width + x

    return mapper


def _vertical_strip_gridmap(height, alternating=True):
    def mapper(x, y):
        if alternating and x % 2:
            return x * height + (height - 1 - y)
        return x * height + y

    return mapper


def _reverse_x_mapper(width, mapper):
    max_x = width - 1

    def x_mapper(x, y):
        return mapper(max_x - x, y)

    return x_mapper


def _reverse_y_mapper(height, mapper):
    max_y = height - 1

    def y_mapper(x, y):
        return mapper(x, max_y - y)

    return y_mapper


def _build_grid_mapper(
    width,
    height,
    *,
    orientation=HORIZONTAL,
    alternating=True,
    reverse_x=False,
    reverse_y=False,
    top=0,
    bottom=0,
):
    if orientation == HORIZONTAL:
        mapper = _horizontal_strip_gridmap(width, alternating)
    else:
        mapper = _vertical_strip_gridmap(height, alternating)

    if reverse_x:
        mapper = _reverse_x_mapper(width, mapper)
    if reverse_y:
        mapper = _reverse_y_mapper(height, mapper)

    x_start = 0
    x_end = width
    y_start = 0
    y_end = height
    if top:
        x_start, y_start = top
    if bottom:
        x_end, y_end = bottom

    grid_width = x_end - x_start
    grid_height = y_end - y_start
    indices = []
    for _y in range(grid_height):
        for _x in range(grid_width):
            indices.append(mapper(_x + x_start, _y + y_start))
    return grid_width, grid_height, indices


[docs] class PixelFramebuffer: """ NeoPixel / DotStar grid framebuffer for MicroPython. Same constructor signature as ``adafruit_pixel_framebuf.PixelFramebuffer``. Flush changed pixels to the strip with ``display()``. """ def __init__( self, pixels, width, height, orientation=HORIZONTAL, alternating=True, reverse_x=False, reverse_y=False, top=0, bottom=0, rotation=0, ): """Build a grid framebuffer mapped onto an addressable LED strip. Args: pixels: NeoPixel / DotStar-like object with ``__setitem__`` and ``show()``. width: Logical grid width. height: Logical grid height. orientation: `HORIZONTAL` or `VERTICAL` strip layout. alternating: Zigzag rows/columns when True. reverse_x: Mirror X before mapping. reverse_y: Mirror Y before mapping. top: Optional ``(x, y)`` origin of the active sub-grid. bottom: Optional ``(x, y)`` exclusive end of the active sub-grid. rotation: Stored rotation attribute (degrees). """ self._pixels = pixels grid_width, grid_height, self._indices = _build_grid_mapper( width, height, orientation=orientation, alternating=alternating, reverse_x=reverse_x, reverse_y=reverse_y, top=top, bottom=bottom, ) self._width = grid_width self._height = grid_height nbytes = grid_width * grid_height * 3 self._buffer = bytearray(nbytes) self._double_buffer = bytearray(nbytes) self.rotation = rotation @property def width(self): """Logical grid width in pixels.""" return self._width @property def height(self): """Logical grid height in pixels.""" return self._height @property def stride(self): """Pixels per row in the logical framebuffer.""" return self._width
[docs] def fill_rect(self, x, y, w, h, c): """Fill a rectangle with an RGB888 packed color ``0xRRGGBB``.""" rgb = _rgb888_bytes(c) stride = self._width if x == 0 and w == stride: rowbytes = rgb * w for _y in range(y, y + h): begin = _y * stride * 3 self._buffer[begin : begin + len(rowbytes)] = rowbytes return (x, y, w, h) for _y in range(y, y + h): row = _y * stride for _x in range(x, x + w): index = (row + _x) * 3 self._buffer[index : index + 3] = rgb return (x, y, w, h)
[docs] def pixel(self, x, y, c=None): """Get or set one RGB888 packed pixel ``0xRRGGBB``.""" index = (y * self._width + x) * 3 if c is None: r, g, b = self._buffer[index : index + 3] return (r << 16) | (g << 8) | b self._buffer[index : index + 3] = _rgb888_bytes(c)
[docs] def blit(self): """Not implemented — use `display` to flush the strip.""" raise NotImplementedError
[docs] def display(self) -> None: """Copy changed pixels to the LED strip and show.""" stride = self.stride for _y in range(self._height): for _x in range(self._width): index = (_y * stride + _x) * 3 if self._buffer[index : index + 3] != self._double_buffer[index : index + 3]: grid_index = _y * self._width + _x strip_index = self._indices[grid_index] self._pixels[strip_index] = tuple(self._buffer[index : index + 3]) self._double_buffer[index : index + 3] = self._buffer[index : index + 3] self._pixels.show()
[docs] class PixelDisplay(DisplayDriver): """ DisplayDriver for addressable-LED matrix layouts. Exposes the usual RGB565 ``DisplayDriver`` API (``color_depth=16``). The inner ``PixelFramebuffer`` stores RGB888 for the LED strip; conversion uses ``color_rgb``. Args: pixel_buffer: ``PixelFramebuffer`` (or Adafruit equivalent on CircuitPython). ``can_rotate`` is False: the matrix's wiring sets its orientation, taken from ``pixel_buffer`` when the driver starts. """ can_rotate = False def __init__(self, pixel_buffer, *, quiet=False): self._raw_buffer = pixel_buffer self._width = pixel_buffer.width self._height = pixel_buffer.height self._rotation = getattr(pixel_buffer, "rotation", 0) self.color_depth = 16 self._requires_byteswap = False super().__init__(quiet=quiet)
[docs] def init(self) -> None: """No-op init hook (LED strip is already configured)."""
[docs] def fill_rect(self, x, y, w, h, c): """Fill a rectangle with an RGB565 color (converted to RGB888). Args: x: Left edge. y: Top edge. w: Width. h: Height. c: RGB565 color. Returns: Result of the inner framebuffer ``fill_rect``. """ return self._raw_buffer.fill_rect(x, y, w, h, _color888_from_565(c))
[docs] def blit_rect(self, buf, x, y, w, h): """Blit RGB565 bytes into the LED framebuffer. Args: buf: Source buffer of ``w * h * 2`` bytes. x: Destination left edge. y: Destination top edge. w: Width in pixels. h: Height in pixels. Returns: tuple: ``(x, y, w, h)``. Raises: ValueError: When ``buf`` length does not match dimensions. """ bpp = self.color_depth // 8 expected = w * h * bpp if len(buf) != expected: raise ValueError( f"The source buffer is not the correct size (got {len(buf)} bytes, expected {expected})" ) inner = self._raw_buffer for row in range(h): row_base = row * w * bpp for col in range(w): off = row_base + col * bpp inner.pixel(x + col, y + row, _color888_from_565(buf[off : off + bpp])) return (x, y, w, h)
[docs] def pixel(self, x, y, c): """Set a single RGB565 pixel (converted to RGB888). Args: x: X coordinate. y: Y coordinate. c: RGB565 color. Returns: Result of the inner framebuffer ``pixel``. """ return self._raw_buffer.pixel(x, y, _color888_from_565(c))
[docs] def show(self, _timer=None) -> None: """Flush dirty pixels to the LED strip via ``pixel_buffer.display()``.""" self._raw_buffer.display()