Make sure you have the latest CircuitPython firmware loaded for your board to use displayio. You can download it from the link below.

This example is simple, but shows a basic usage of what makes TileGrid so cool. While you can create a TileGrid with multiple tiles, you can also create a TileGrid with just a single tile. This special case is often referred to as a "sprite". You still need a source Bitmap for the TileGrid. So we use one that contains several sprites all arranged nicely. This is called a "sprite sheet".

Here's a nice little sprite sheet bitmap we will use for this example:

It's super tiny! If you zoom in, it looks like this:

Let's add a grid overlay to better show each individual pixel:

You can see how there are 6 total sprites. Each sprite is 16 pixels wide by 16 pixels high. We want to slice it up like this:

Remember, this is not the TileGrid. This is just how the source bitmap is sliced up to provide source tiles for the TileGrid.

We will create a TileGrid with only one tile (sprite). We can then change the index of this TileGrid to be whichever of these 6 characters from the source bitmap (sprite sheet) we want to show. And we can change it again to show a different one, etc.

We have everything we need:

  • A source Bitmap - the sprite sheet
  • We know each sprite is 16 pixels by 16 pixels
    • tile_width = 16
    • tile_height = 16
  • We know we want a TileGrid that is only 1 wide by 1 high
    • width = 1
    • height = 1

Here is what creating the TileGrid would look like to set this up:

Download: file
sprite = displayio.TileGrid(sprite_sheet, pixel_shader=palette,
                            width = 1,
                            height = 1,
                            tile_width = 16,
                            tile_height = 16)

By default, the source index will be 0 to start with. So the sprite is set to show Blinka (the purple snake). You can change it to any of the other 6 sprites using the syntax:

Download: file
sprite[0] = 1

Now the sprite is set to show Adabot - index 1. Note that the sprite index is [0], which is the only index that applies in this case, since there's only 1 tile in the TileGrid.

Want Sparky? Do this:

Download: file
sprite[0] = 4

And so on.

Sprite Sheet Example

Here's the full code. It loads the source Bitmap, sets up the TileGrid, adds it to a Group, which is then added to the Display so it's finally shown. It then cycles through each of the sprites.

Download: file
import time
import board
import displayio
import adafruit_imageload

display = board.DISPLAY

# Load the sprite sheet (bitmap)
sprite_sheet, palette = adafruit_imageload.load("/cp_sprite_sheet.bmp",
                                                bitmap=displayio.Bitmap,
                                                palette=displayio.Palette)

# Create a sprite (tilegrid)
sprite = displayio.TileGrid(sprite_sheet, pixel_shader=palette,
                            width = 1,
                            height = 1,
                            tile_width = 16,
                            tile_height = 16)

# Create a Group to hold the sprite
group = displayio.Group(scale=1)

# Add the sprite to the Group
group.append(sprite)

# Add the Group to the Display
display.show(group)

# Set sprite location
group.x = 120
group.y = 80

# Loop through each sprite in the sprite sheet
source_index = 0
while True:
    sprite[0] = source_index % 6
    source_index += 1
    time.sleep(2)

Change The Scale!

The sprites are pretty small. The default scale is 1, so each pixel of the sprite is a pixel on the display. You can change this using the scale parameter which is passed in when creating the Group.

Try changing that to something like 2 or 4 and running the code again. It's this line of code:

Download: file
group = displayio.Group(scale=1)

Now the sprites should show up much larger!

Change The Location!

Want the sprites to show up in a different location? You can do so by changing these lines and setting new values for x and y.

Download: file
group.x = 120
group.y = 80
This guide was first published on Apr 30, 2019. It was last updated on Apr 30, 2019.
This page (Sprite Sheet) was last updated on Oct 24, 2020.