pixeldisplay

displaysys.pixeldisplay

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

MicroPython: PixelFramebuffer (pygraphics.FrameBuffer + grid map) and PixelDisplay live here. CircuitPython board configs use adafruit_pixel_framebuf.PixelFramebuffer with pydisplay PixelDisplay.

Classes

PixelFramebuffer

PixelFramebuffer(pixels, width, height, orientation=HORIZONTAL, alternating=True, reverse_x=False, reverse_y=False, top=0, bottom=0, rotation=0)

NeoPixel / DotStar grid framebuffer for MicroPython.

Same constructor signature as adafruit_pixel_framebuf.PixelFramebuffer. Flush changed pixels to the strip with display().

Build a grid framebuffer mapped onto an addressable LED strip.

Parameters:

Name	Type	Description	Default
pixels		NeoPixel / DotStar-like object with __setitem__ and show().	required
width		Logical grid width.	required
height		Logical grid height.	required
orientation		:data:HORIZONTAL or :data:VERTICAL strip layout.	HORIZONTAL
alternating		Zigzag rows/columns when True.	True
reverse_x		Mirror X before mapping.	False
reverse_y		Mirror Y before mapping.	False
top		Optional (x, y) origin of the active sub-grid.	0
bottom		Optional (x, y) exclusive end of the active sub-grid.	0
rotation		Stored rotation attribute (degrees).	0

Attributes

stride property

stride

Pixels per row in the logical framebuffer.

Methods:

blit

blit()

Not implemented — use :meth:display to flush the strip.

display

display()

Copy changed pixels to the LED strip and show.

PixelDisplay

PixelDisplay(pixel_buffer, *, quiet=False)

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.

Parameters:

Name	Type	Description	Default
pixel_buffer		PixelFramebuffer (or Adafruit equivalent on CircuitPython).	required

Attributes

width property

width

The width of the display in pixels.

height property

height

The height of the display in pixels.

rotation property writable

rotation

The rotation of the display.

touch_device property writable

touch_device

The touch device.

requires_byteswap property

requires_byteswap

Whether the display requires byte swapping.

vscroll property writable

vscroll

The vertical scroll position relative to the top fixed area.

Returns:

Type	Description
int	The vertical scroll position.

tfa property

tfa

The top fixed area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The top fixed area.

vsa property

vsa

The vertical scroll area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The vertical scroll area.

bfa property

bfa

The bottom fixed area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The bottom fixed area.

tfa_area property

tfa_area

Top fixed area for vertical scrolling.

Returns:

Type	Description
	tuple[int, int, int, int]: (x, y, width, height) of the top fixed band.

vsa_area property

vsa_area

The vertical scroll area as an Area object.

Returns:

Type	Description
tuple	The vertical scroll area.

bfa_area property

bfa_area

The bottom fixed area as an Area object.

Returns:

Type	Description
tuple	The bottom fixed area.

power property writable

power

The power state of the display.

brightness property writable

brightness

The brightness of the display.

Methods:

init

init()

No-op init hook (LED strip is already configured).

fill_rect

fill_rect(x, y, w, h, c)

Fill a rectangle with an RGB565 color (converted to RGB888).

Parameters:

Name	Type	Description	Default
x		Left edge.	required
y		Top edge.	required
w		Width.	required
h		Height.	required
c		RGB565 color.	required

Returns:

Type	Description
	Result of the inner framebuffer fill_rect.

blit_rect

blit_rect(buf, x, y, w, h)

Blit RGB565 bytes into the LED framebuffer.

Parameters:

Name	Type	Description	Default
buf		Source buffer of w * h * 2 bytes.	required
x		Destination left edge.	required
y		Destination top edge.	required
w		Width in pixels.	required
h		Height in pixels.	required

Returns:

Name	Type	Description
tuple		(x, y, w, h).

Raises:

Type	Description
ValueError	When buf length does not match dimensions.

pixel

pixel(x, y, c)

Set a single RGB565 pixel (converted to RGB888).

Parameters:

Name	Type	Description	Default
x		X coordinate.	required
y		Y coordinate.	required
c		RGB565 color.	required

Returns:

Type	Description
	Result of the inner framebuffer pixel.

show

show(_timer=None)

Flush dirty pixels to the LED strip via pixel_buffer.display().

framebuffers

framebuffers()

Return panel buffers for direct GUI paint, or None.

When sharing is supported, returns (buf1, buf2_or_None, nbytes, stride_bytes).

fill

fill(color)

Fill the display with a color.

Parameters:

Name	Type	Description	Default
color	int	The color to fill the display with.	required

scroll

scroll(dx, dy)

Scroll the display.

Parameters:

Name	Type	Description	Default
dx	int	The number of pixels to scroll horizontally.	required
dy	int	The number of pixels to scroll vertically.	required

disable_auto_byteswap

disable_auto_byteswap(value)

Disable byte swapping in the display driver.

If self.requires_byteswap and the guest application is capable of byte swapping color data check to see if byte swapping can be disabled. If so, disable it.

Usage

# If byte swapping is required and the display driver is capable of having byte swapping disabled,
# disable it and set a flag so we can swap the color bytes as they are created.
if display_drv.requires_byteswap:
    needs_swap = display_drv.disable_auto_byteswap(True)
else:
    needs_swap = False

Parameters:

Name	Type	Description	Default
value	bool	Whether to disable byte swapping.	required

Returns:

Type	Description
bool	Whether byte swapping was disabled successfully.

blit_transparent

blit_transparent(buf, x, y, w, h, key)

Blit a buffer with transparency.

Parameters:

Name	Type	Description	Default
buf	memoryview	The buffer to blit.	required
x	int	The x coordinate to blit to.	required
y	int	The y coordinate to blit to.	required
w	int	The width to blit.	required
h	int	The height to blit.	required
key	int	The color key to use for transparency.	required

Returns:

Type	Description
tuple	The x, y, w, h coordinates of the blitted area.

set_vscroll

set_vscroll(tfa=0, bfa=0)

Set the vertical scroll definition and move the vertical scroll to the top.

Parameters:

Name	Type	Description	Default
tfa	int	The top fixed area.	0
bfa	int	The bottom fixed area.	0

translate_point

translate_point(point)

Translate a point from real coordinates to scrolled coordinates.

Useful for touch events.

Parameters:

Name	Type	Description	Default
point	tuple	The x and y coordinates to translate.	required

Returns:

Type	Description
tuple	The translated x and y coordinates.

scroll_by

scroll_by(value)

Scroll vertically by value pixels relative to the current offset.

Parameters:

Name	Type	Description	Default
value		Signed pixel delta applied to :attr:vscroll.	required

scroll_to

scroll_to(value)

Set the absolute vertical scroll offset.

Parameters:

Name	Type	Description	Default
value		New :attr:vscroll position.	required

vscrdef

vscrdef(tfa, vsa, bfa)

Set the vertical scroll definition. Should be overridden by the subclass and called as super().vscrdef(tfa, vsa, bfa).

Parameters:

Name	Type	Description	Default
tfa	int	The top fixed area.	required
vsa	int	The vertical scroll area.	required
bfa	int	The bottom fixed area.	required

vscsad

vscsad(vssa=None)

Set or get the vertical scroll start address. Should be overridden by the subclass and called as super().vscsad(y).

Parameters:

Name	Type	Description	Default
vssa	int	The vertical scroll start address.	None

Returns:

Type	Description
int	The vertical scroll start address.

invert_colors

invert_colors(value)

Invert the colors of the display. Should be overridden by the subclass.

Parameters:

Name	Type	Description	Default
value	bool	True to invert the colors, False to restore the colors.	required

reset

reset()

Perform a reset of the display. Should be overridden by the subclass.

hard_reset

hard_reset()

Perform a hardware reset of the display. Should be overridden by the subclass.

soft_reset

soft_reset()

Perform a software reset of the display. Should be overridden by the subclass.

sleep_mode

sleep_mode(value)

Set the sleep mode of the display. Should be overridden by the subclass.

Parameters:

Name	Type	Description	Default
value	bool	True to enter sleep mode, False to exit sleep mode.	required

deinit

deinit()

Run subclass cleanup. Idempotent.

The broker owns the shared refresh timer, so there is no display-owned timer to stop here; board_config stops the timer on quit via runtime.stop_timer.

quit

quit(code=0, force=False)

Release display resources (REPL-safe unless force=True). Called on QUIT.

force_quit

force_quit(code=0)

Release resources then exit the process (alias for quit(code, force=True)).

Functions: