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.
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.
Bitmaps are not displayed directly. Instead, they are added to a set of nested collection like classes which ultimately get shown on the display.
This sets up the actual display hardware and how it is connected to the microcontroller.
Two dimensional (2D) information is used throughout the displayio library. The 2D objects have an associated
height, usually in units of pixels. Locating things, like pixels, within these 2D areas is done using
y coordinates. Here's an example with
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).
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.