Merge pull request #32 from UnfinishedStuff/main

Updated MicroPython Pico Display documentation

micropython/modules/pico_display/README.md

@@ -11,6 +11,17 @@ We've included helper functions to handle every aspect of drawing to the screen
   - [set_led](#set_led)
   - [is_pressed](#is_pressed)
   - [update](#update)
+  - [set_pen](#set_pen)
+  - [create_pen](#create_pen)
+  - [clear](#clear)
+  - [pixel](#pixel)
+  - [pixel_span](#pixel_span)
+  - [rectangle](#rectangle)
+  - [circle](#circle)
+  - [character](#character)
+  - [text](#text)
+  - [set_clip](#set_clip)
+  - [remove_clip](#remove_clip)
 
 ## Example Program
 
@@ -86,4 +97,100 @@ To display your changes on Pico Display's screen you need to call `update`:
 
 ```python
 picodisplay.update()
-```
+```
+
+### set_pen
+
+Sets the colour to be used by subsequent calls to drawing functions.  The values for `r`, `g` and `b` should be from 0-255 inclusive.
+
+```python
+picodisplay.set_pen(r, g, b)
+```
+
+### create_pen
+
+Creates a pen which can be stored as a variable for faster re-use of the same colour through calls to `set_pen`.  The values for `r`, `g` and `b` should be from 0-255 inclusive.
+
+```python
+pen_colour = picodisplay.create_pen(r, g, b)
+picodisplay.set_pen(penColour)
+```
+
+### clear
+
+Fills the display buffer with the currently set pen colour.
+
+```python
+picodisplay.clear()
+```
+
+### pixel
+
+Sets a single pixel in the display buffer to the current pen colour.  The `x` and `y` parameters determine the X and Y coordinates of the drawn pixel in the buffer.
+
+```python
+picodisplay.pixel(x, y)
+```
+
+### pixel_span
+
+Draws a horixontal line of pixels to the buffer.  The `x` and `y` parameters specify the coordinates of the first pixel of the line.  The `l` parameter describes the length of the line in pixels.  This function will only extend the line towards the end of the screen, i.e. the `x` coordinate should specify the left hand extreme of the line.
+
+```python
+picodisplay.span(x, y, l)
+```
+
+### rectangle
+
+Draws a rectangle filled with the current pen colour to the buffer.  The `x` and `y` parameters specify the upper left corner of the rectangle, `w` specifies the width in pixels, and `h` the height.
+
+```python
+picodisplay.rectangle(x, y, w, h)
+```
+
+![Rectangle function explanation image](/micropython/modules/pico_display/images/rectangle.png)
+
+### circle
+
+Draws a circle filled with the current pen colour to the buffer.  The `x` and `y` parameters specify the centre of the circle, `r` specifies the radius in pixels.
+
+```python
+picodisplay.rectangle(x, y, w, h)
+```
+
+![Circle function explanation image](/micropython/modules/pico_display/images/circle.png)
+
+### character
+
+Draws a single character to the display buffer in the current pen colour.  The `c` parameter should be the ASCII numerical representation of the character to be printed, `x` and `y` describe the top-left corner of the character's drawing field.  The `character` function can also be given an optional 4th parameter, `scale`, describing the scale of the character to be drawn.  Default value is 2.
+
+```python
+char_a = ord('a')
+picodisplay.character(char_a, x, y)
+picodisplay.character(char_a, x, y, scale)
+```
+
+### text
+
+Draws a string of text to the display buffer in the current pen colour.  The `string` parameter is the string of text to be drawn, and `x` and `y` specify the upper left corner of the drawing field.  The `wrap` parameter describes the width, in pixels, after which the next word in the string will be drawn on a new line underneath the current text.  This will wrap the string over multiple lines if required.  This function also has an optional parameter, `scale`, which describes the size of the characters to be drawn.  The default `scale` is 2.
+
+```python
+picodisplay.text(string, x, y, wrap)
+picodisplay.text(string, x, y, wrap, scale)
+```
+
+![Text scale explanation image](/micropython/modules/pico_display/images/text_scale.png)
+
+### set_clip
+
+This function defines a rectangular area outside which no drawing actions will take effect.  If a drawing action crosses the boundary of the clip then only the pixels inside the clip will be drawn.  Note that `clip` does not remove pixels which have already been drawn, it only prevents new pixels being drawn outside the described area.  A more visual description of the function of clips can be found below.  Only one clip can be active at a time, and defining a new clip replaces any previous clips.  The `x` and `y` parameters describe the upper-left corner of the clip area, `w` and `h` describe the width and height in pixels.
+
+```python
+picodisplay.set_clip(x, y, w, h)
+```
+
+![Clip function explanation image](/micropython/modules/pico_display/images/clip.png)
+
+### remove_clip
+
+This function removes any currently implemented clip.