PicoGraphics: Update README.

libraries/pico_graphics/README.md

@@ -1,9 +1,12 @@
 # Pico Graphics <!-- omit in toc -->
 
-Pico Graphics is a tiny graphics library for 16-bit RGB565 displays.
+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](#overview)
+  - [Pen Types](#pen-types)
+  - [Creating A Pico Graphics Instance](#creating-a-pico-graphics-instance)
 - [Function Reference](#function-reference)
   - [Types](#types)
     - [rect](#rect)
@@ -14,16 +17,13 @@ It supports drawing text, primitive and individual pixels and includes basic typ
       - [rect.inflate & rect.deflate](#rectinflate--rectdeflate)
     - [point](#point)
       - [point.clamp](#pointclamp)
-      - [operators](#operators)
   - [Pens & Clipping](#pens--clipping)
     - [set_pen](#set_pen)
     - [create_pen](#create_pen)
     - [set_clip & remove_clip](#set_clip--remove_clip)
   - [Palette](#palette)
-    - [set_palette_mode](#set_palette_mode)
-    - [reserve_palette](#reserve_palette)
-    - [set_palette](#set_palette)
-    - [RGB565 and RGB332](#rgb565-and-rgb332)
+    - [update_pen](#update_pen)
+    - [reset_pen](#reset_pen)
   - [Pixels](#pixels)
     - [pixel](#pixel)
     - [pixel_span](#pixel_span)
@@ -33,6 +33,45 @@ It supports drawing text, primitive and individual pixels and includes basic typ
   - [Text](#text)
   - [Change Font](#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:
+
+```c++
+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:
+
+```c++
+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:
+
+```c++
+st7789.update(&graphics);
+```
+
+The driver will check your graphics type and act accordingly.
+
 ## Function Reference
 
 ### Types
@@ -152,13 +191,9 @@ A point can be clamped within the confines of a `rect`. This is useful for keepi
 
 ```c++
 point cursor(10, 1000);       // A point, far outside the bounds of our screen
-cursor.clamp(screen.bounds)); // Clamp to the screen
+cursor.clamp(screen.bounds);  // Clamp to the screen
 ```
 
-##### operators
-
-TODO
-
 ### Pens & Clipping
 
 #### set_pen
@@ -199,52 +234,22 @@ By default Pico Graphics uses an `RGB332` palette and clamps all pens to their `
 
 Alternatively `set_palette_mode()` lets you switch into an RGB565 `USER` palette which gives you up to 256 16-bit colours of your choice.
 
-#### set_palette_mode
+#### update_pen
 
 ```c++
-void PicoGraphics::set_palette_mode(PALETTE_USER);
+int PicoGraphics::update_pen(uint8_t index, uint8_t r, uint8_t g, uint8_t b);
 ```
 
-Clears the default `RGB332` palette and switches into `USER` mode.
+Modify a palette entry to the given RGB colour (or nearest supported equivilent.)
 
-Pens created with `create_pen()` will use 16-bit `RGB565` resolution and you have up to 256 palette entries to use.
+
+#### reset_pen
 
 ```c++
-void PicoGraphics::set_palette_mode(PALETTE_RGB332);
+void PicoGraphics::reset_pen(uint8_t index);
 ```
 
-Clears any `USER` assigned palettes and returns to `RGB332` mode.
-
-#### reserve_palette
-
-```c++
-int PicoGraphics::reserve_palette();
-```
-
-Marks the first empty palette entry as reserved and return its index.
-
-
-#### set_palette
-
-```c++
-void PicoGraphics::set_palette(uint8_t index, RGB565 color);
-```
-
-#### RGB565 and RGB332
-
-```c++
-int RGB565(uint8_t r, uint8_t g, uint8_t b);
-```
-
-Creates and returns an RGB565 colour, using the five/six/five most significant bits of each channel in turn.
-
-```c++
-int RGB332(uint8_t, uint8_t g, uint8_t b);
-```
-
-Creates and returns an RGB565 colour, using the three/three/two most significant bits of each channel in turn.
-
-IE: This clips the colour to RGB332.
+Return a palette entry to its default value. Usually black and marked unused.
 
 ### Pixels