"GPU" Features

[Gadgetoid]

The "GPU" - RP2040 - offers "hardware" accelerated sprites and scanline scrolling that can be useful when trying to push a lot of pixels quickly.

Sprites

First, some terms-

• Image Index - an index to identify where sprite image data should be stored
• Sprite Slot - a single, hardware sprite. There are up to 32 (or 16 on widescreen versions).

An index must be specified when loading an image, and can later be used to refer to that specific image and assign it to a sprite. It's a good idea to use a variable to keep track of these:

IMAGE_ELEPHANT = 1
for _ in range(2):
    display.load_sprite("elephant.png", IMAGE_ELEPHANT)
    display.update()

Note: the quirk of loading the sprite twice in a loop is because we must swap the hardware PSRAM buffers and load the image data into each. This might be swept into PicoGraphics in future.

A sprite slot can display a specific sprite - referenced by its index - at a given X and Y position. Once displayed the sprite will continue to display at its given X and Y coordinates without any intervention from your code.

The display_sprite function serves both to display a sprite and to update its location or image:

SPRITE_SLOT = 1
display.display_sprite(SPRITE_SLOT, IMAGE_ELEPHANT, X, Y)

The current maximim size for a sprite is 2k, which corresponds to a 32x32 pixel image, however there are no restrictions on width/height so non-square images exceeding one of these dimensions and making up for it in the other is fine- so long as they don't exceed 2k (2 bytes per pixel).

Scanlines

You can configure the "GPU" to scroll up to three groups of scanlines at indexes 1, 2 and 3. The following code cuts a 240 pixel tall frame into three horizontal slices:

display.set_scroll_index_for_lines(1, 0, 80)
display.set_scroll_index_for_lines(2, 80, 160)
display.set_scroll_index_for_lines(3, 160, 240)

Once the scroll groups have been configured, you can ask the "GPU" to offset them like so:

display.set_display_offset(X, Y, 1)

The last argument is the scroll group (it can be either 1, 2 or 3).

Frame vs Display

DISPLAY_WIDTH = 320 
DISPLAY_HEIGHT = 240

FRAME_WIDTH = 960
FRAME_HEIGHT = 240

display = PicoGraphics(DISPLAY_PICOVISION,
                       width=DISPLAY_WIDTH,
                       height=DISPLAY_HEIGHT,
                       frame_width=FRAME_WIDTH,
                       frame_height=FRAME_HEIGHT,
                       pen_type=PEN) 

The PicoGraphics constructor can optionally take a frame Width and Height which specifies a larger drawing area that you can pan around with scroll offsets. This is useful to mask slow drawing of new elements, or to contain additional horizontal data that the scanline scrolling could bring into view.

[Gadgetoid]

Sprites can also be loaded in "PicoVision Sprite" or ".pvs" format, there's a tool for conversion here - https://github.com/MichaelBell/picovision/blob/feature/sprite-loading/scripts/sprite_convert.py and the format is currently:

Sprite entry:
  1 byte: Width
  1 byte: Height
  For each line:
    1 byte x offset of first pixel on the line
    1 byte line width
  2 bytes padding if height is even
  Height times:
    Line width times:
      Sprite pixel data

[Gadgetoid]

I've come up with a somewhat janky code snippet to deal with sprite limitations-

class SpriteList:
    def __init__(self):
        self.items = []

    def add(self, image, x, y, force=False):
        if len(self.items) == 32:
            if force:
                self.items.pop(0)
            else:
                return
        self.items.append((image, x, y))

    def clear(self):
        self.items = []

    def display(self):
        for i in range(32):
            try:
                image, x, y = self.items[i]
                display.display_sprite(i, image, x, y)
            except:
                display.clear_sprite(i)


spritelist = SpriteList()

It's a little rough and ready, but is based around the idea that we don't really care about sprite slots and that should just be handled as an implementation detail.

Currently on every frame of my sprite-powered Floppy Birb I'm calling:

spritelist.clear()

To clear the sprite list, then adding pipe sprites:

spritelist.add(SPRITE_PIPE, pipe_x, GAME_TOP + top_pipe_height - n - CAP_HEIGHT)
spritelist.add(SPRITE_PIPE_CAP, pipe_x - 3, top_pipe_end - CAP_HEIGHT)
spritelist.add(SPRITE_PIPE, pipe_x, bottom_pipe_start + CAP_HEIGHT)

And player/goal sprites:

spritelist.add(SPRITE_GOAL, int(goal_x), goal_y, force=True)
spritelist.add(BIRBS[int(current_x / 10) % 3], int(WIDTH / 6), int(birb_y), force=True)

With force=True specified if the sprite list is full, the first sprite you added will be popped off the list and replaced with the specified new one. This means player sprites and the goal will always show, but pipes might disappear if the limit is hit.

This works surprisingly well and some form of it could maybe be a standard lib for PicoVision MicroPython.

[technolhodgy]

One thing the Amiga was able to do in hardware ( Denise IC ) was change a palette colour every scan line.
Could the be implemented on picoVision?
If the GPU was able to handle it, this would give the illusion of a bigger palette.
Captain Planet on the Amiga used this on the sky background colour.

[MichaelBell]

Sadly the HDMI encoding is tricky enough that this probably isn’t possible, at least for the full res modes.
When horizontal pixel doubling everything is much easier - but there it would probably make more sense just to support a 128 (plus depth bit) or 256 colour palette.
We do now support defining multiple palettes and you can switch between them without having to flip the buffers, but the change only applies at the next vsync.

[MichaelBell]

Note that some of the info here is getting out of date, take a look at https://github.com/pimoroni/picovision/blob/patch-picographics-docs/docs/hardware.md for more info.