Library Overview

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 (Pallete) 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. The contents of a Group are ultimately what get shown on a 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
  • 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).
This guide was first published on Apr 30, 2019. It was last updated on Apr 30, 2019.
This page (Library Overview) was last updated on Aug 04, 2020.