sani7/2023-Webservices_And_Applications
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update LCD API docs

Browse Source
This commit is contained in:
L-diy
2023-11-15 19:26:41 +01:00
parent a0525c1f6f
commit 7c6ff58afe
2 changed files with 110 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/lcd_api.md
View File

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

10
project/Core/Inc/lcd_api.h
View File

@@ -155,14 +155,14 @@ void lcd_clear(uint32_t color);
/**
* @brief Draw GIF image on screen from memory
* Draw GIF image from memory to the LCD screen at position X, Y
* @warning If the GIF has a loop count specified, it will stop after the specified amount of loops and the lcd_git_t handle will be invalid for further use
* @warning If the GIF has a loop count specified, it will stop after the specified amount of loops and the lcd_gif_t handle will be invalid for further use
* @note Before drawing over a GIF, make sure to call lcd_stop_gif(), otherwise the GIF will keep overwriting the screen
*
* @param src Pointer to the GIF image data
* @param size The size of the GIF image data
* @param x_pos The X position on the screen
* @param y_pos The Y position on the screen
* @return A handle to the GIF image, NULL if the GIF could not be opened
* @return A handle to the GIF image, NULL if the GIF could not be opened @ref lcd_gif_t
*/
lcd_gif_t* lcd_draw_gif(uint8_t* src, size_t size, uint32_t x_pos, uint32_t y_pos);
@@ -175,7 +175,7 @@ lcd_gif_t* lcd_draw_gif(uint8_t* src, size_t size, uint32_t x_pos, uint32_t y_po
* @param name The filename of the GIF image
* @param x_pos The X position on the screen
* @param y_pos The Y position on the screen
* @return A handle to the GIF image, NULL if the GIF could not be opened
* @return A handle to the GIF image, NULL if the GIF could not be opened @ref lcd_gif_t
*/
lcd_gif_t* lcd_draw_gif_from_fs(const char* name, uint32_t x_pos, uint32_t y_pos);
@@ -185,7 +185,7 @@ lcd_gif_t* lcd_draw_gif_from_fs(const char* name, uint32_t x_pos, uint32_t y_pos
* Call this function before trying to draw over a GIF
* @warning Make sure the GIF is still playing, otherwise it might stop another GIF
*
* @param gif The handle to the GIF image
* @param gif The handle to the GIF image @ref lcd_gif_t
*/
void lcd_stop_gif(lcd_gif_t* gif);
@@ -193,7 +193,7 @@ void lcd_stop_gif(lcd_gif_t* gif);
* @brief Check if a GIF is still playing
* @note It is possible that the GIF has stopped playing, but another GIF has taken its slot and is still playing
*
* @param gif The handle to the GIF image
* @param gif The handle to the GIF image @ref lcd_gif_t
* @return True if the GIF is still playing, false if not
*/
bool lcd_gif_is_playing(lcd_gif_t* gif);