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.

• TileGrid - This uses a Bitmap and a pixel shader (Palette) to draw actual pixels. It must be added to a Group.
• Group - This is a collection of one or more TileGrids. It can also contain other Groups.

Display Hardware Things

This sets up the actual display hardware and how it is connected to the microcontroller.

• BusDisplay- 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.
• I2CDisplayBus - An I2C based display bus.
• EPaperDisplay - An EPaper or E-Ink style display.

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
• y is 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.