pimoroni-pico/micropython/modules/picographics/README.md

Pico Graphics

Pico Graphics is our unified graphics and display library for driving displays from your Pico in MicroPython.

Pico Graphics replaces the individual drivers for displays- if you're been using breakout_colorlcd, ST7789 then you'll need to update your code!

• Setting up Pico Graphics
  • Supported Displays
  • Supported Graphics Modes (Pen Type)
  • Supported Rotations
  • Custom Pins
• Function Reference
  • Text
  • Sprites
    • Loading Sprites
    • Drawing Sprites
  • JPEG Files

Setting up Pico Graphics

You must construct an instance of PicoGraphics with your desired display:

from picographics import PicoGraphics, DISPLAY_LCD_160X80

display = PicoGraphics(display=DISPLAY_LCD_160X80)

Bear in mind that MicroPython has only 192K of RAM available- a 320x240 pixel display in RGB565 mode uses 150K!

Supported Displays

• Pico Display - 240x135 SPI LCD - DISPLAY_PICO_DISPLAY
• Pico Display 2 - 320x240 SPI LCD - DISPLAY_PICO_DISPLAY_2
• Tufty 2040 - 320x240 Parallel LCD - DISPLAY_TUFTY_2040
• Pico Explorer - 240x240 SPI LCD - DISPLAY_PICO_EXPLORER
• Enviro Plus - 240x240 SPI LCD - DISPLAY_ENVIRO_PLUS
• 240x240 Round SPI LCD Breakout - DISPLAY_ROUND_LCD_240X240
• 240x240 Square SPI LCD Breakout - DISPLAY_LCD_240X240
• 160x80 SPI LCD Breakout - DISPLAY_LCD_160X80

Supported Graphics Modes (Pen Type)

• 4-bit - PEN_P4 - 16-colour palette of your choice
• 8-bit - PEN_P8 - 256-colour palette of your choice
• 8-bit RGB332 - PEN_RGB332 - 256 fixed colours (3 bits red, 3 bits green, 2 bits blue)
• 16-bit RGB565 - PEN_RGB565 - 64K colours at the cost of RAM. (5 bits red, 6 bits green, 5 bits blue)

These offer a tradeoff between RAM usage and available colours. In most cases you would probably use RGB332 since it offers the easiest tradeoff. It's also the default.

Eg:

display = PicoGraphics(display=PICO_DISPLAY, pen_type=PEN_RGB332)

Supported Rotations

All SPI LCDs support 0, 90, 180 and 270 degree rotations.

Eg:

display = PicoGraphics(display=PICO_DISPLAY, roation=90)

Custom Pins

The pimoroni_bus library includes SPIBus for SPI LCDs and ParallelBus for Parallel LCDs (like Tufty 2040).

In most cases you'll never need to use these, but they come in useful if you're wiring breakouts to your Pico or using multiple LCDs.

A custom SPI bus:

from pimoroni_bus import SPIBus
from picographics import PicoGraphics, DISPLAY_PICO_EXPLORER, PEN_RGB332

spibus = SPIBus(cs=17, dc=16, sck=18, mosi=19)

display = PicoGraphics(display=DISPLAY_PICO_EXPLORER, bus=spibus, pen_type=PEN_RGB332)

Function Reference

Text

Sprites

Pico Display has very limited support for sprites in RGB332 mode.

Sprites must be 8x8 pixels arranged in a 128x128 pixel spritesheet. 1-bit transparency is handled by electing a single colour to skip over.

We've prepared some RGB332-compatible sprite assets for you, but you can use spritesheet-to-rgb332.py <filename> to convert your own.

Loading Sprites

Use Thonny to upload your spritesheet.rgb332 file onto your Pico. Then load it into Pico Graphics:

display.load_spritesheet("s4m_ur4i-dingbads.rgb332")

Drawing Sprites

And finally display a sprite:

display.sprite(0, 0, 0, 0)

These arguments for sprite are as follows:

1. Sprite X position (from 0-15) - this selects the horizontal location of an 8x8 sprite from your 128x128 pixel spritesheet.
2. Sprite Y position (from 0-15)
3. Destination X - where to draw on your screen horizontally
4. Destination Y = where to draw on your screen vertically
5. Scale (optional) - an integer scale value, 1 = 8x8, 2 = 16x16 etc.
6. Transparent (optional) - specify a colour to treat as transparent

JPEG Files

We've included BitBank's JPEGDEC - https://github.com/bitbank2/JPEGDEC - so you can display JPEG files on your LCDs.

Eg:

import picographics
import jpegdec

display = picographics.PicoGraphics(display=picographics.DISPLAY_PICO_EXPLORER)

# Create a new JPEG decoder for our PicoGraphics
j = jpegdec.JPEG(display)

# Open the JPEG file
j.open_file("filename.jpeg")

# Decode the JPEG
j.decode(0, 0, jpegdec.JPEG_SCALE_FULL)

# Display the result
display.update()

JPEG files must be small enough to load into RAM for decoding, and must not be progressive.

JPEG files will be automatically dithered in RGB332 mode.

In P4 and P8 modes JPEGs are dithered to your custom colour paleete. Their appearance of an image will vary based on the colours you choose.

The arguments for decode are as follows:

1. Decode X - where to place the decoded JPEG on screen
2. Decode Y
3. Flags - one of JPEG_SCALE_FULL, JPEG_SCALE_HALF, JPEG_SCALE_QUARTER or JPEG_SCALE_EIGHTH