Merge pull request #441 from pimoroni/patch-picographics-docs

PicoGraphics: Update C++ docs.

libraries/pico_graphics/README.md

@@ -40,8 +40,12 @@ Pico Graphics comes in multiple flavours depending on which underlying buffer ty
 
 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.
 
+A monochrome OLED display can currently only work with `1Bit` type buffers, and Inky Frame only with `3Bit`.
+
 ### Pen Types
 
+* `1Bit` and `1BitY` - 1-bit packed, with automatic dithering from 16 shades of grey. 0 == Black, 15 == White. (For Inky Pack, or monochrome OLEDs)
+* `3Bit` - 3-bit bitplaned, using three 1-bit buffers and supporting up to 8 colours. (For Inky Frame)
 * `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.
@@ -52,10 +56,13 @@ Your buffer doesn't have to be native to your display. For example a 16-bit ST77
 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);
+PicoGraphics_Pen3Bit graphics(WIDTH, HEIGHT, nullptr);   // For Inky Frame
+PicoGraphics_Pen1Bit graphics(WIDTH, HEIGHT, nullptr);   // For MonoChrome OLEDs
+PicoGraphics_Pen1BitY graphics(WIDTH, HEIGHT, nullptr);  // For Inky Pack / Badger 2040
+PicoGraphics_PenP4 graphics(WIDTH, HEIGHT, nullptr);     // For colour LCDs such as Pico Display
+PicoGraphics_PenP8 graphics(WIDTH, HEIGHT, nullptr);     // ditto- uses 2x the RAM of P4
+PicoGraphics_PenRGB332 graphics(WIDTH, HEIGHT, nullptr); // ditto
+PicoGraphics_PenRGB565 graphics(WIDTH, HEIGHT, nullptr); // For 16-bit colour LCDs. Uses 2x the RAM of P8 or RGB332 but permits 65K colour.
 ```
 
 To draw something to a display you should create a display driver instance, eg:
@@ -230,9 +237,15 @@ void PicoGraphics::remove_clip();
 
 ### 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.
+If you construct an instance of PicoGraphics with `PicoGraphics_PenRGB332` all colour values (created pens) will be clamped to their `RGB332` equivalent values.
 
-Alternatively `set_palette_mode()` lets you switch into an RGB565 `USER` palette which gives you up to 256 16-bit colours of your choice.
+This will give you an approximate colour for every RGB888 value you request, but only a fixed palette of 256 total colours is actually supported and displayed on screen.
+
+If you don't want to think about or manage a palette of custom colours, `RGB332` is the way to go.
+
+If you wish to choose your own custom palette you should use either `PicoGraphics_PenP8` or `PicoGraphics_PenP4` which support up to 256 and 16 colours respectively.
+
+Internally all colours are stored as RGB888 and converted when they are displayed on your screen.
 
 #### update_pen
 
@@ -242,7 +255,6 @@ 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
 
 ```c++

micropython/modules/picographics/README.md

@@ -9,9 +9,14 @@ Pico Graphics replaces the individual drivers for displays- if you're been using
   - [Supported Graphics Modes (Pen Type)](#supported-graphics-modes-pen-type)
   - [Supported Rotations](#supported-rotations)
   - [Custom Pins](#custom-pins)
+    - [SPI / Parallel](#spi--parallel)
+    - [I2C](#i2c)
 - [Function Reference](#function-reference)
   - [General](#general)
     - [Creating & Setting Pens](#creating--setting-pens)
+      - [RGB565, RGB332, P8 and P4 modes](#rgb565-rgb332-p8-and-p4-modes)
+      - [Monochrome Modes](#monochrome-modes)
+      - [Inky Frame](#inky-frame)
     - [Controlling The Backlight](#controlling-the-backlight)
     - [Clipping](#clipping)
     - [Clear](#clear)
@@ -55,18 +60,29 @@ Bear in mind that MicroPython has only 192K of RAM available- a 320x240 pixel di
 * 240x240 Round SPI LCD Breakout - `DISPLAY_ROUND_LCD_240X240`
 * 240x240 Square SPI LCD Breakout - `DISPLAY_LCD_240X240`
 * 160x80 SPI LCD Breakout - `DISPLAY_LCD_160X80`
+* 128x128 I2C OLED - `DISPLAY_I2C_OLED_128X128`
+* Pico Inky Pack - 296x128 mono e-ink - `DISPLAY_INKY_PACK`
+* Inky Frame - 600x447 7-colour e-ink - `DISPLAY_INKY_FRAME`
 
 ### Supported Graphics Modes (Pen Type)
 
+* 1-bit - `PEN_1BIT` - mono, used for Pico Inky Pack and i2c OLED
+* 3-bit - `PEN_3BIT` - 8-colour, used for Inky Frame
 * 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.
+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 for colour LCDs.
 
 Eg:
 
+```python
+display = PicoGraphics(display=PICO_DISPLAY)
+```
+
+Is equivalent to:
+
 ```python
 display = PicoGraphics(display=PICO_DISPLAY, pen_type=PEN_RGB332)
 ```
@@ -83,6 +99,8 @@ display = PicoGraphics(display=PICO_DISPLAY, rotate=90)
 
 ### Custom Pins
 
+#### SPI / Parallel
+
 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.
@@ -98,12 +116,27 @@ spibus = SPIBus(cs=17, dc=16, sck=18, mosi=19)
 display = PicoGraphics(display=DISPLAY_PICO_EXPLORER, bus=spibus, pen_type=PEN_RGB332)
 ```
 
+#### I2C
+
+The `pimoroni_i2c` library includes `PimoroniI2C` which can be used to change the pins used by the mono OLED:
+
+```python
+from pimoroni_i2c import PimoroniI2C
+from picographics import PicoGraphics, DISPLAY_I2C_OLED_128X128
+
+i2cbus = PimoroniI2C(4, 5)
+
+display = PicoGraphics(display=DISPLAY_I2C_OLED_128X128, bus=i2cbus)
+```
+
 ## Function Reference
 
 ### General
 
 #### Creating & Setting Pens
 
+##### RGB565, RGB332, P8 and P4 modes
+
 Create a pen colour for drawing into a screen:
 
 ```python
@@ -122,6 +155,46 @@ display.set_pen(my_pen)
 
 This will be either an RGB332 or RGB565 colour, or a palette index.
 
+##### Monochrome Modes
+
+For 1BIT mode - such as for Inky Pack and the Mono OLED - pens are handled a little differently.
+
+There's no need to create one, since mapping an RGB colour to black/white is meaningless.
+
+Instead you can pick from 16 shades of grey which are automatically dithered into the PicoGraphics buffer, where:
+
+* `0` is Black,
+* `1 - 14` are shades of grey,
+* `15` is white.
+
+And just call `set_pen` with your desired shade:
+
+```python
+display.set_pen(0)   # Black
+display.set_pen(15)  # White
+```
+
+Because shades 1 through 14 are created with ordered dither you should avoid using them for text, small details or lines.
+
+Dithering works by mixing black and white pixels in various patterns and quantities to fake grey shades.
+
+If you were to try and draw a single "grey" pixel it will end up either black or white depending on where it's drawn and which shade of grey you pick.
+
+##### Inky Frame
+
+Inky Frame is a special case- the display itself supports only 7 (8 if you include its cleaning "clear" colour, which we call Tapue) colours.
+
+These are:
+
+* `BLACK` = 0
+* `WHITE` = 1
+* `GREEN` = 2
+* `BLUE` = 3
+* `RED` = 4
+* `YELLOW` = 5
+* `ORANGE` = 6
+* `TAUPE` = 7
+
 #### Controlling The Backlight
 
 You can set the display backlight brightness between `0.0` and `1.0`: