Update LCD API docs

docs/lcd_api.md

@@ -2,12 +2,45 @@
 
 ## Introduction
 
-The LCD API can be used to display BMP images or text onto the LCD screen.
-At the moment of writing, only BMP's in C array's are supported.
+The LCD API can be used to display text, BMP images and GIF animations onto the LCD screen.
 Supported color schemes for BMP's are ARGB8888, RGB565, RGB888.
-Displayed text that is exceeds the LCD width size, will be wrapped onto the next line and a '-' character will be injected if the wrap occurs within a word.
+Displayed text that exceeds the LCD width will be wrapped onto the next line,
+and a '-' character will be injected if the wrap occurs within a word.
+
+## Table of contents
+- [Introduction](#introduction)
+- [Table of contents](#table-of-contents)
+- [Usage of LCD API](#usage-of-lcd-api)
+  - [Generating BMP C header files](#generating-bmp-c-header-files)
+    - [Resizing images](#resizing-images)
+    - [Generating the C array](#generating-the-c-array)
+  - [Using the LCD API](#using-the-lcd-api)
+    - [Initialization of LCD API](#initialization-of-lcd-api)
+    - [The lcd task](#the-lcd-task)
+    - [Drawing text on the screen](#drawing-text-on-the-screen)
+    - [Drawing a 'raw' image onto the screen](#drawing-a-raw-image-onto-the-screen)
+    - [Drawing a BMP image onto the screen](#drawing-a-bmp-image-onto-the-screen)
+    - [Drawing a BMP from the filesystem to the LCD](#drawing-a-bmp-from-the-filesystem-to-the-lcd)
+    - [Drawing a GIF image/animation](#drawing-a-gif-imageanimation)
+    - [Stopping a GIF animation](#stopping-a-gif-animation)
+    - [Checking if a GIF is still running](#checking-if-a-gif-is-still-running)
+    - [Clearing the LCD screen](#clearing-the-lcd-screen)
 
 ## Usage of LCD API
+### Generating BMP images
+The LCD API supports BMP3 images in the following color-formats: ARGB8888, RGB888, RGB565.
+* RLE is not supported
+* Pixel data should be stored from the bottom up
+* Non-square pixels are not supported
+* Use of a color palette/table is not supported
+
+To convert an image to BMP3, one can use an image editor such as Photoshop, GIMP or ImageMagick.
+For example, using ImageMagick:
+```bash
+magick in.png -resize 50 BMP3:out.bmp # Resize to a width of 50 pixels
+```
+See the [Imagick documentation](https://imagemagick.org/script/convert.php) for more information.
+
 ### Generating BMP C header files
 #### Resizing images
 To resize an image to the desired size (width and height), one can use an image editor such as Photoshop, GIMP, ImageMagick, ... .
@@ -26,7 +59,7 @@ The BMP3 option is used to convert the PNG to Bitmap version 3.0 (note that the
 #### Generating the C array
 To easily generate a BMP C array (in the desired color scheme) from an image, [lv_img_conv](https://github.com/lvgl/lv_img_conv) can be used.
 
-See the installation instructions on Github or use the [online version](https://lvgl.io/tools/imageconverter).
+See the installation instructions on GitHub or use the [online version](https://lvgl.io/tools/imageconverter).
 
 Example:
 ```bash
@@ -53,6 +86,21 @@ void main(void) {
 }
 ```
 
+#### The lcd task
+The `lcd_task()` function should be called in the main loop of the application. This function is responsible for drawing the GIF animations.
+```c
+#include "lcd_api.h"
+
+void main(void) {
+    ...
+    lcd_init(true);
+    ...
+    for(;;) {
+        lcd_task();
+    }
+}
+```
+
 #### Drawing text on the screen
 
 ```c
@@ -134,6 +182,59 @@ This function expects the name of the BMP image as argument, together with the X
 
 Note that this function only works for BMP images and not raw images and when an image exceeds the X or Y size of the LCD display, the image will go out of the visible LCD area.
 
+#### Drawing a GIF image/animation
+```c
+lcd_gif_t* lcd_draw_gif(uint8_t* src, size_t size, uint32_t x_pos, uint32_t y_pos);
+lcd_gif_t* lcd_draw_gif_from_fs(const char* name, uint32_t x_pos, uint32_t y_pos);
+```
+```c
+#include "lcd_api.h"
+
+void main(void) {
+    ...
+    lcd_init(true);
+    ...
+    
+    // From a C-array
+    lcd_gif_t* gif = lcd_draw_gif(gif_array, gif_size, 0, 0);
+    
+    // From the filesystem
+    lcd_gif_t* gif = lcd_draw_gif_from_fs("st.gif", 0, 0);
+    
+    if (gif == NULL) {
+        LOG_WARNING("GIF could not be drawn");
+    }
+    ...
+    for(;;) {
+        lcd_task();
+    }
+}
+```
+This function expects a GIF image as argument, together with the X and Y coordinates.
+The size argument is the size of the GIF image in bytes.
+The function returns a handle for the GIF image, which can be used to stop the animation.
+
+If the GIF has a loop count specified,
+it will stop after the specified number of loops and the lcd_gif_t handle will be invalid for further use.
+Otherwise, the GIF will loop indefinitely.
+Before drawing over the GIF, the GIF should be stopped by calling `lcd_gif_stop(gif)`.
+
+#### Stopping a GIF animation
+```c
+void lcd_stop_gif(lcd_gif_t* gif);
+```
+This function stops the GIF animation and frees the memory allocated for the GIF.
+Call this function before drawing over the GIF.
+
+This function should not be called on a GIF that has already been stopped (GIFs with a loop count will stop automatically).
+It is possible that the handler has been assigned to a new GIF, so it would stop the new GIF instead.
+
+#### Checking if a GIF is still running
+```c
+bool lcd_gif_is_playing(lcd_gif_t* gif);
+```
+NOTE: It is possible that the GIF has stopped playing, but another GIF has taken its slot and is still playing.
+
 #### Clearing the LCD screen
 ```c
 void lcd_clear(uint32_t color);