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 = 16tile_height = 16
- We know we want a TileGrid that is only 1 wide by 1 high
width = 1height = 1
Here is what creating the TileGrid would look like to set this up:
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:
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:
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.
# SPDX-FileCopyrightText: 2019 Carter Nelson for Adafruit Industries
#
# SPDX-License-Identifier: MIT
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.root_group = 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:
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.
group.x = 120 group.y = 80
Page last edited January 22, 2025
Text editor powered by tinymce.
