displayio – High level, display object compositing system — Adafruit CircuitPython 1 documentation (original) (raw)

The displayio module contains classes to define what objects to display. It is optimized for low memory use and, therefore, computes final pixel values for dirty regions as needed.

Separate modules manage transmitting the display contents to a display.

For more a more thorough explanation and guide for using displayio, please refer to this Learn guide.

Available on these boards

displayio.AnyDisplayBus

Type-checking shorthand for any kind of display bus. Not actually defined in CircuitPython.

displayio.AnyFramebuffer

Type-checking shorthand for any kind of framebuffer. Not actually defined in CircuitPython.

displayio.AnyDisplay

Type-checking shorthand for any kind of display. Not actually defined in CircuitPython.

displayio.CIRCUITPYTHON_TERMINAL_: Group_

The displayio.Group that is the displayed serial terminal (REPL).

displayio.release_displays() → None

Releases any actively used displays so their buses and pins can be used again. This will also release the builtin display on boards that have one. You will need to reinitialize it yourself afterwards. This may take seconds to complete if an active EPaperDisplay is refreshing.

Use this once in your code.py if you initialize a display. Place it right before the initialization so the display is active as long as possible.

class displayio.Colorspace

The colorspace for a ColorConverter to operate in

RGB888_: Colorspace_

The standard 24-bit colorspace. Bits 0-7 are blue, 8-15 are green, and 16-24 are red. (0xRRGGBB)

RGB565_: Colorspace_

The standard 16-bit colorspace. Bits 0-4 are blue, bits 5-10 are green, and 11-15 are red (0bRRRRRGGGGGGBBBBB)

RGB565_SWAPPED_: Colorspace_

The swapped 16-bit colorspace. First, the high and low 8 bits of the number are swapped, then they are interpreted as for RGB565

RGB555_: Colorspace_

The standard 15-bit colorspace. Bits 0-4 are blue, bits 5-9 are green, and 11-14 are red. The top bit is ignored. (0bxRRRRRGGGGGBBBBB)

RGB555_SWAPPED_: Colorspace_

The swapped 15-bit colorspace. First, the high and low 8 bits of the number are swapped, then they are interpreted as for RGB555

class displayio.Bitmap(width: int, height: int, value_count: int)

Stores values of a certain size in a 2D array

Bitmaps can be treated as read-only buffers. If the number of bits in a pixel is 8, 16, or 32; and the number of bytes per row is a multiple of 4, then the resulting memoryview will correspond directly with the bitmap’s contents. Otherwise, the bitmap data is packed into the memoryview with unspecified padding.

A Bitmap can be treated as a buffer, allowing its content to be viewed and modified using e.g., with ulab.numpy.frombuffer, but the displayio.Bitmap.dirty method must be used to inform displayio when a bitmap was modified through the buffer interface.

bitmaptools.arrayblit can also be useful to move data efficiently into a Bitmap.

Create a Bitmap object with the given fixed size. Each pixel stores a value that is used to index into a corresponding palette. This enables differently colored sprites to share the underlying Bitmap. value_count is used to minimize the memory used to store the Bitmap.

Parameters:

width_: int_

Width of the bitmap. (read only)

height_: int_

Height of the bitmap. (read only)

bits_per_value_: int_

Bits per Pixel of the bitmap. (read only)

__getitem__(index: Tuple[int, int] | int) → int

Returns the value at the given index. The index can either be an x,y tuple or an int equal to y * width + x.

This allows you to:

__setitem__(index: Tuple[int, int] | int, value: int) → None

Sets the value at the given index. The index can either be an x,y tuple or an int equal to y * width + x.

This allows you to:

fill(value: int) → None

Fills the bitmap with the supplied palette index value.

dirty(x1: int = 0, y1: int = 0, x2: int = -1, y2: int = -1) → None

Inform displayio of bitmap updates done via the buffer protocol.

Parameters:

If x1 or y1 are not specified, they are taken as 0. If x2 or y2 are not specified, or are given as -1, they are taken as the width and height of the image. Thus, calling dirty() with the default arguments treats the whole bitmap as modified.

When a bitmap is modified through the buffer protocol, the display will not be properly updated unless the bitmap is notified of the “dirty rectangle” that encloses all modified pixels.

deinit() → None

Release resources allocated by Bitmap.

class displayio.ColorConverter(*, input_colorspace: Colorspace = Colorspace.RGB888, dither: bool = False)

Converts one color format to another.

Create a ColorConverter object to convert color formats.

Parameters:

convert(color: int) → int

Converts the given color to RGB565 according to the Colorspace

dither_: bool_

When True the ColorConverter dithers the output by adding random noise when truncating to display bitdepth

make_transparent(color: int) → None

Set the transparent color or index for the ColorConverter. This will raise an Exception if there is already a selected transparent index.

Parameters:

color (int) – The color to be transparent

make_opaque(color: int) → None

Make the ColorConverter be opaque and have no transparent pixels.

Parameters:

color (int) – [IGNORED] Use any value

class displayio.Group(*, scale: int = 1, x: int = 0, y: int = 0)

Manage a group of sprites and groups and how they are inter-related.

Create a Group of a given size and scale. Scale is in one dimension. For example, scale=2 leads to a layer’s pixel being 2x2 pixels when in the group.

Parameters:

hidden_: bool_

True when the Group and all of its layers are not visible. When False, the Group’s layers are visible if they haven’t been hidden.

scale_: int_

Scales each pixel within the Group in both directions. For example, when scale=2 each pixel will be represented by 2x2 pixels.

x_: int_

X position of the Group in the parent.

y_: int_

Y position of the Group in the parent.

append(layer: vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid) → None

Append a layer to the group. It will be drawn above other layers.

insert(index: int, layer: vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid) → None

Insert a layer into the group.

index(layer: vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid) → int

Returns the index of the first copy of layer. Raises ValueError if not found.

pop(i: int = -1) → vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid

Remove the ith item and return it.

remove(layer: vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid) → None

Remove the first copy of layer. Raises ValueError if it is not present.

__bool__() → bool

__contains__(item: vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid) → bool

__iter__() → Iterator[vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid]

__len__() → int

Returns the number of layers in a Group

__getitem__(index: int) → vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid

Returns the value at the given index.

This allows you to:

__setitem__(index: int, value: vectorio.Circle | vectorio.Rectangle | vectorio.Polygon | Group | TileGrid) → None

Sets the value at the given index.

This allows you to:

__delitem__(index: int) → None

Deletes the value at the given index.

This allows you to:

sort(key: function, reverse: bool) → None

Sort the members of the group.

class displayio.OnDiskBitmap(file: str | BinaryIO)

Loads values straight from disk. This minimizes memory use but can lead to much slower pixel load times. These load times may result in frame tearing where only part of the image is visible.

It’s easiest to use on a board with a built in display such as the Hallowing M0 Express.

import board import displayio import time import pulseio

board.DISPLAY.brightness = 0 splash = displayio.Group() board.DISPLAY.root_group = splash

odb = displayio.OnDiskBitmap('/sample.bmp') face = displayio.TileGrid(odb, pixel_shader=odb.pixel_shader) splash.append(face)

Wait for the image to load.

board.DISPLAY.refresh(target_frames_per_second=60)

Fade up the backlight

for i in range(100): board.DISPLAY.brightness = 0.01 * i time.sleep(0.05)

Wait forever

while True: pass

Create an OnDiskBitmap object with the given file.

Parameters:

file (file) – The name of the bitmap file. For backwards compatibility, a file opened in binary mode may also be passed.

Older versions of CircuitPython required a file opened in binary mode. CircuitPython 7.0 modified OnDiskBitmap so that it takes a filename instead, and opens the file internally. A future version of CircuitPython will remove the ability to pass in an opened file.

width_: int_

Width of the bitmap. (read only)

height_: int_

Height of the bitmap. (read only)

pixel_shader_: ColorConverter | Palette_

The image’s pixel_shader. The type depends on the underlying bitmap’s structure. The pixel shader can be modified (e.g., to set the transparent pixel or, for palette shaded images, to update the palette.)

class displayio.Palette(color_count: int, *, dither: bool = False)

Map a pixel palette_index to a full color. Colors are transformed to the display’s format internally to save memory.

Create a Palette object to store a set number of colors.

Parameters:

dither_: bool_

When True the Palette dithers the output color by adding random noise when truncating to display bitdepth

__bool__() → bool

__len__() → int

Returns the number of colors in a Palette

__getitem__(index: int) → int | None

Return the pixel color at the given index as an integer.

__setitem__(index: int, value: int | circuitpython_typing.ReadableBuffer | Tuple[int, int, int]) → None

Sets the pixel color at the given index. The index should be an integer in the range 0 to color_count-1.

The value argument represents a color, and can be from 0x000000 to 0xFFFFFF (to represent an RGB value). Value can be an int, bytes (3 bytes (RGB) or 4 bytes (RGB + pad byte)), bytearray, or a tuple or list of 3 integers.

This allows you to:

palette[0] = 0xFFFFFF # set using an integer palette[1] = b'\xff\xff\x00' # set using 3 bytes palette[2] = b'\xff\xff\x00\x00' # set using 4 bytes palette[3] = bytearray(b'\x00\x00\xFF') # set using a bytearay of 3 or 4 bytes palette[4] = (10, 20, 30) # set using a tuple of 3 integers

make_transparent(palette_index: int) → None

Makes the palette index transparent. The color is ignored.

make_opaque(palette_index: int) → None

Mark the given palette index as opaque.

is_transparent(palette_index: int) → bool

Returns True if the palette index is transparent. Returns False if opaque.

class displayio.TileGrid(bitmap: Bitmap | OnDiskBitmap, *, pixel_shader: ColorConverter | Palette, width: int = 1, height: int = 1, tile_width: int | None = None, tile_height: int | None = None, default_tile: int = 0, x: int = 0, y: int = 0)

A grid of tiles sourced out of one bitmap

Position a grid of tiles sourced from a bitmap and pixel_shader combination. Multiple grids can share bitmaps and pixel shaders.

A single tile grid is also known as a Sprite.

Create a TileGrid object. The bitmap is source for 2d pixels. The pixel_shader is used to convert the value and its location to a display native pixel color. This may be a simple color palette lookup, a gradient, a pattern or a color transformer.

When the total number of tiles is 256 or less, tile values are stored as single bytes (uint8_t). When the total number of tiles is more than 256, tile values are stored as double bytes (uint16_t).

tile_width and tile_height match the height of the bitmap by default.

Parameters:

hidden_: bool_

True when the TileGrid is hidden. This may be False even when a part of a hidden Group.

x_: int_

X position of the left edge in the parent.

y_: int_

Y position of the top edge in the parent.

width_: int_

Width of the tilegrid in tiles.

height_: int_

Height of the tilegrid in tiles.

tile_width_: int_

Width of a single tile in pixels.

tile_height_: int_

Height of a single tile in pixels.

flip_x_: bool_

If true, the left edge rendered will be the right edge of the right-most tile.

flip_y_: bool_

If true, the top edge rendered will be the bottom edge of the bottom-most tile.

transpose_xy_: bool_

If true, the TileGrid’s axis will be swapped. When combined with mirroring, any 90 degree rotation can be achieved along with the corresponding mirrored version.

contains(touch_tuple: tuple) → bool

Returns True if the first two values in touch_tuple represent an x,y coordinate inside the tilegrid rectangle bounds.

pixel_shader_: ColorConverter | Palette_

The pixel shader of the tilegrid.

bitmap_: Bitmap | OnDiskBitmap_

The bitmap of the tilegrid.

__getitem__(index: Tuple[int, int] | int) → int

Returns the tile index at the given index. The index can either be an x,y tuple or an int equal to y * width + x.

This allows you to:

__setitem__(index: Tuple[int, int] | int, value: int) → None

Sets the tile index at the given index. The index can either be an x,y tuple or an int equal to y * width + x.

This allows you to:

or: