The official documentation for the displayio library can be found here:
You'll want to go there for detailed information about using the displayio library. This guide is meant to be a compliment to that information.
We start with an overview of what all the parts do.
Image Related Things
Graphics means images, right? Pretty much. These are the items that relate to essentially that.
- Bitmap - This is pretty much what you expect, a 2D array of pixels. Each pixel contains an index into a "pixel shader", typically a Palette, which is where the actual color information comes from.
-
OnDiskBitmap - This creates a Bitmap image (picture) from a file stored on a disk, like
omg_cute_kitteh.bmp. It must also be used in conjunction with a pixel shader, typically ColorConverter, to provide the color information. - Palette - This is a simple list of colors. A Bitmap's pixel value is an index into this list.
- ColorConverter - Use to convert between color formats.
Collection Related Things
Bitmaps are not displayed directly. Instead, they are added to a set of nested collection like classes which ultimately get shown on the display.
Display Hardware Things
This sets up the actual display hardware and how it is connected to the microcontroller.
- Display - This is the actual display. It must be connected to the host controller via a "display bus".
- FourWire - A SPI based display bus.
- ParallelBus - An 8-bit parallel display bus.
Coordinate System
Two dimensional (2D) information is used throughout the displayio library. The 2D objects have an associated width and height, usually in units of pixels. Locating things, like pixels, within these 2D areas is done using x and y coordinates. Here's an example with width=4 and height=3:
Note the following:
- the origin is in the upper left hand corner
-
yis positive in the down direction - the first pixel is at
(0, 0)and the last pixel is at(3, 2), which corresponds to(width - 1, height - 1).
Hierarchy and Nesting
The image at the top of this page is an example of the most simple arrangement of displayio objects. It's a good visual reference for the general hierarchy. However, much more complex arrangements are possible. Keep in mind these general rules:
- A Display can only show a Group.
- A Display can only show one Group at any time. This is called the root group.
- A Group can contain one or more TileGrids as well as one or more Groups.
So, for example, you could have something like the arrangement shown below. The Bitmap and Palette associated with each TileGrid have been left out for simplicity.
