From 7c6ff58afe7c7d1804a95805f22bbb8f51ef8834 Mon Sep 17 00:00:00 2001 From: L-diy Date: Wed, 15 Nov 2023 19:26:41 +0100 Subject: [PATCH] Update LCD API docs --- docs/lcd_api.md | 109 +++++++++++++++++++++++++++++++++++-- project/Core/Inc/lcd_api.h | 10 ++-- 2 files changed, 110 insertions(+), 9 deletions(-) diff --git a/docs/lcd_api.md b/docs/lcd_api.md index 4e61aca..3ca9766 100644 --- a/docs/lcd_api.md +++ b/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); diff --git a/project/Core/Inc/lcd_api.h b/project/Core/Inc/lcd_api.h index 79e6306..292515b 100644 --- a/project/Core/Inc/lcd_api.h +++ b/project/Core/Inc/lcd_api.h @@ -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);