8.7 KiB
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
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:
magick in.png -resize 50 BMP3:out.bmp # Resize to a width of 50 pixels
See the Imagick documentation 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:
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 can be used.
See the installation instructions on GitHub or use the online version.
Example:
./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.
./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.
#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.
#include "lcd_api.h"
void main(void) {
...
lcd_init(true);
...
for(;;) {
lcd_task();
}
}
Drawing text on the screen
void lcd_display_text(const char* text, uint32_t x_pos, uint32_t y_pos, uint32_t color, uint32_t bg_color, sFONT *font);
#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
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);
#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
void lcd_draw_bmp_img(uint8_t* bmp_buff, uint32_t x_pos, uint32_t y_pos);
#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
void lcd_draw_img_from_fs(const char* name, uint32_t x_pos, uint32_t y_pos);
#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
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);
#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
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.
Stopping all GIF animations
void lcd_stop_all_gifs(void);
This function stops all the GIF animations and frees the memory allocated for the GIF. Call this function before drawing over the GIF.
Checking if a GIF is still running
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 text on the LCD screen
void lcd_clear_text(void);
#include "lcd_api.h"
void main(void) {
...
lcd_init(true);
lcd_display_text("Hello world!", 0, 0, LCD_GREEN, LCD_FONT20);
...
lcd_clear_text();
}
Clears all text strings on the LCD screen.
Clearing the images on the LCD screen
void lcd_clear_images(void);
#include "lcd_api.h"
void main(void) {
...
lcd_init(true);
lcd_draw_img_from_fs("st.bmp", 300, 100);
...
lcd_clear_images();
}
Clears all text strings on the LCD screen.
Clearing (background/images) layer 0 to color
void lcd_set_bg_color_layer0(uint32_t color);
#include "lcd_api.h"
void main(void) {
...
lcd_init(true);
lcd_draw_img_from_fs("st.bmp", 300, 100);
...
lcd_set_bg_color_layer0(LCD_BLACK);
}