# LCD API

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

## Usage of LCD API
### 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);
    ...
}
```

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

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

#### Drawing a BMP from the filesystem to the LCD
```c
void lcd_draw_img_from_fs_with_name(const char* name, 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_img_from_fs_with_name("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.

#### Clearing the LCD screen
```c
void lcd_clear(uint32_t color);
```

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

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

Clears the LCD screen to the specified color.