pimoroni-pico/libraries/pico_graphics

Pico Graphics

Pico Graphics is a tiny graphics library supporting a number of underlying buffer formats including 8-bit paletted (256 colour), 8-bit RGB332 (256 colour), 16-bit RGB565 (65K colour) and 4-bit packed (8 colour).

It supports drawing text, primitive and individual pixels and includes basic types such as rect and point brimming with methods to help you develop games and applications.

• Overview
  • Pen Types
  • Creating A Pico Graphics Instance
• Function Reference
  • Types
    • rect
      • rect.empty
      • rect.contains
      • rect.intersects
      • rect.intersection
      • rect.inflate & rect.deflate
    • point
      • point.clamp
  • Pens & Clipping
    • set_pen
    • create_pen
    • set_clip & remove_clip
  • Palette
    • update_pen
    • reset_pen
  • Pixels
    • pixel
    • pixel_span
  • Primitives
    • rectangle
    • circle
  • Text
  • Change Font

Overview

Pico Graphics comes in multiple flavours depending on which underlying buffer type you wish to work with.

Your buffer doesn't have to be native to your display. For example a 16-bit ST7789 display can work with P4, P8, RGB332 and RGB565 buffers, with palette lookups handled for you on the fly.

Pen Types

• P4 - 4-bit packed, with an 8 colour palette. This is commonly used for 7/8-colour e-ink displays or driving large displays with few colours.
• P8 - 8-bit, with a 256 colour palette. Great balance of memory usage versus available colours. You can replace palette entries on the fly.
• RGB332 - 8-bit, with a fixed 256 colour RGB332 palette. Great for quickly porting an RGB565 app to use less RAM. Limits your colour choices, but is easier to grok.
• RGB565 - 16-bit, 65K "True Colour." Great for rainbows, gradients and images but comes at the cost of RAM!

Creating A Pico Graphics Instance

To create a Pico Graphics instance to draw into, you should construct an instance of the Pen type class you want to use:

PicoGraphics_PenP4 graphics(WITH, HEIGHT, nullptr);
PicoGraphics_PenP8 graphics(WITH, HEIGHT, nullptr);
PicoGraphics_PenRGB332 graphics(WITH, HEIGHT, nullptr);
PicoGraphics_PenRGB565 graphics(WITH, HEIGHT, nullptr);

To draw something to a display you should create a display driver instance, eg:

ST7789 st7789(PicoExplorer::WIDTH, PicoExplorer::HEIGHT, ROTATE_0, false, get_spi_pins(BG_SPI_FRONT));

And then send it the Pico Graphics instance to draw:

st7789.update(&graphics);

The driver will check your graphics type and act accordingly.

Function Reference

Types

rect

The rect type describes a rectangle in terms of its x, y position, width and height.

rect.empty

bool rect::empty();

rect.contains

bool rect::contains(const rect &p);

contains allows you to check if a rect contains a specific point. This can be useful for checking collissions (have I clicked on something?):

point cursor(50, 50);
rect widget(0, 0, 100, 100);
bool hover = widet.contains(cursor);

rect.intersects

bool rect::intersects(const rect &r);

intersects allows you to check if a rect intersects or overlaps another rect, for example these rectangles do not intersect:

rect a(10, 10, 10, 10);
rect b(30, 10, 10, 10);
a.intersects(b) == false

And these do:

rect a(10, 10, 10, 10);
rect b(15, 10, 10, 10);
a.intersects(b) == true

rect.intersection

rect rect::intersection(const rect &r);

intersection takes an input rect and returns a new rect that describes the region in which the two rects overlap. For example:

rect a(0, 0, 10, 20);
rect b(0, 0, 20, 10);
rect c = a.intersection(b);

In this case c would equal rect c(0, 0, 10, 10); since this is the region that a and b overlap.

rect.inflate & rect.deflate

void rect::inflate(int32_t v);
void rect::declate(int32_t v);

inflate will inflate a rect, like a balooon, by adding the number of pixels you specify to all sides. For example:

rect box(10, 10, 10, 10);
box.inflate(10);

Would inflate our box to start at 0,0 and be 30x30 pixels in size.

deflate does the opposite:

rect box(10, 10, 10, 10);
box.deflate(1);

Would deflate our box to start at 11,11 and be 8x8 pixels in size.

Since rectangle always draws a filled rectangle, this can be useful to add an outline of your desired thickness:

WHITE = screen.create_pen(255, 255, 255);
rect box(10, 10, 100, 100);
box.inflate(1); // Inflate our box by 1px on all sides
screen.set_pen(WHITE); // White outline
screen.rectangle(box);
box.deflate(1); // Return to our original box size
screen.set_pen(0, 0, 0); /// Black fill
screen.rectangle(box);

point

The point type descrives a single point - synonymous with a pixel - in terms of its x and y position.

point.clamp

point point::clamp(const rect &r);

A point can be clamped within the confines of a rect. This is useful for keeping - for example - a cursor within the bounds of the screen:

point cursor(10, 1000);       // A point, far outside the bounds of our screen
cursor.clamp(screen.bounds);  // Clamp to the screen

Pens & Clipping

set_pen

In order to draw anything with Pico Graphics you must first set the pen to your desired palette colour:

void PicoGraphics::set_pen(uint8_t p);

This value represents an index into the internal colour palette, which has 256 entries and defaults to RGB332 giving an approximation of all RGB888 colours.

create_pen

int PicoGraphics::create_pen(uint8_t r, uint8_t g, uint8_t b);

By default create pen takes R, G and B values, clamps them to 3, 3 and 2 bits respectively and returns an index in the RGB332 palette.

You must create pens before using them with set_pen() which accepts only a palette index.

set_clip & remove_clip

void PicoGraphics::set_clip(const rect &r);
void PicoGraphics::remove_clip();

set_clip applies a clipping rectangle to the drawing surface. Any pixels outside of this rectangle will not be drawn. By default drawing operations are clipped to bounds since it's impossible to draw outside of the buffer.

remove_clip sets the surface clipping rectangle back to the surface bounds.

Palette

By default Pico Graphics uses an RGB332 palette and clamps all pens to their RGB332 values so it can give you an approximate colour for every RGB888 value you request. If you don't want to think about colours and palettes you can leave it as is.

Alternatively set_palette_mode() lets you switch into an RGB565 USER palette which gives you up to 256 16-bit colours of your choice.

update_pen

int PicoGraphics::update_pen(uint8_t index, uint8_t r, uint8_t g, uint8_t b);

Modify a palette entry to the given RGB colour (or nearest supported equivilent.)

reset_pen

void PicoGraphics::reset_pen(uint8_t index);

Return a palette entry to its default value. Usually black and marked unused.

Pixels

pixel

void PicoGraphics::pixel(const point &p);

pixel sets the pixel at point p to the current pen.

pixel_span

void PicoGraphics::pixel_span(const point &p, int32_t l)

pixel_span draws a horizontal line of pixels of length int32_t l starting at point p.

Primitives

rectangle

void PicoGraphics::rectangle(const rect &r) ;

rectangle draws a filled rectangle described by rect.

circle

PicoGraphics::circle(const point &p, int32_t radius) 

circle draws a filled circle centered on point p with radius int32_t radius.

Text

void PicoGraphics::text(const std::string &t, const point &p, int32_t wrap, uint8_t scale);

text allows you to draw a string at point p, with a maximum line-width of int32_t wrap.

The 6x6 and 6x8 pixel font characters are encoded in font6_data.hpp and font8_data.hpp along with their character widths so that text can be drawn variable-width.

You can scale text with uint8_t scale for 12x12, 18x18, etc character sizes.

Change Font

void PicoGraphics::set_font(const Font *font);

set_font allows you to change the font that PicoGraphics uses to draw text.

If you:

#include "font8_data.hpp"

Then you can: set_font(&font8); to use a font with upper/lowercase characters.