2023-Webservices_And_Applications/docs/lcd_api.md

# LCD API

## Introduction

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 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, ... .

For example, using ImageMagick:
```bash
convert in.png -resize 10% BMP3:out.bmp
#OR (depending on the version of ImageMagick)
magick in.png -resize 50x50 out.png
```

The resize option can both be used to resize in percentages or in pixels.

The BMP3 option is used to convert the PNG to Bitmap version 3.0 (note that the BMP header will still be present in the output image).

#### 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).

Example:
```bash
./lv_img_conv.js test.png -f -c CF_TRUE_COLOR
```

The command above will generate a .c file in which arrays can be found for RGB332, RGB565, ARGB8888. It is also possible to generate a binary BMP image file in ARGB8332, ARGB8565, ARGB8565_RBSWAP, ARGB8888.
```bash
./lv_img_conv.js logo_lvgl.png -f -c CF_TRUE_COLOR -t bin --binary-format ARGB8888
```

### Using the LCD API
#### Initialization of LCD API
The `lcd_init(bool bl_on)` function initialises the LCD screen. The `bl_on` variable allows to enable or disable the LCD backlight.
```c
#include "lcd_api.h"

...

void main(void) {
    ...
    lcd_init(true);
    ...
}
```

#### 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
void lcd_display_text(const char* text, uint16_t x_pos, uint16_t y_pos, uint32_t color, uint32_t bg_color, sFONT *font);
```

```c
#include "lcd_api.h"

...

void main(void) {
    ...
    lcd_init(true);
    ...
    lcd_display_text("This is a text string.", 10, 10, LCD_GREEN, LCD_BLACK, LCD_FONT16);
}
```
Display text on the LCD screen in a certain color. When text width exceeds BSP_LCD_GetXSize(), a text wrap will be performed. If the text wrap is between two will be injected.

#### Drawing a 'raw' image onto the screen
```c
void lcd_draw_raw_img(const void* p_src, uint32_t x_pos, uint32_t y_pos, uint32_t x_size, uint32_t y_size, uint32_t color_mode);
```

```c
#include "lcd_api.h"
#include "test_image.h"

void main(void) {
  ...
  lcd_init(true);
  ...
  lcd_draw_raw_img(raw_img_array, 0, 0, 50, 50, LCD_ARGB8888);
}
```
Draw raw image from a C array to the LCD screen at position X, Y. In color mode ARGB8888, RGB888, RGB565 or ARGB1555 Supports ARGB8888, RGB565, RGB888 (see LCD_* defines in header file).

Note that 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 BMP image onto the screen
```c
void lcd_draw_bmp_img(uint8_t* bmp_buff, uint32_t x_pos, uint32_t y_pos);
```

```c
#include "lcd_api.h"
#include "test_image.h"

void main(void) {
  ...
  lcd_init(true);
  ...
  lcd_draw_bmp_img(bmp_array, 0, 0);
  lcd_draw_bmp_img(file->data, 50, 50);
}
```
Drawing a BMP image (either from filesystem or a C-array) to the LCD screen at position X, Y. The image size and color scheme do not have to be passed as arguments like in the `lcd_draw_raw_img(...)` function, these values are present in the BMP header.

Note that 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 BMP from the filesystem to the LCD
```c
void lcd_draw_img_from_fs(const char* name, uint32_t x_pos, uint32_t y_pos);
```

```c
#include "lcd_api.h"

void main(void) {
  ...
  lcd_init(true);
  ...
  lcd_draw_img_from_fs("st.bmp", 0, 0);
}
```

This function expects the name of the BMP image as argument, together with the X and Y coordinates.

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);
```

```c
#include "lcd_api.h"

void main(void) {
  ...
  lcd_init(true);
  ...
  lcd_clear(LCD_BLACK);
}
```

Clears the LCD screen to the specified color.