From 09520872859fdc28232ad1e715870befabc4f2f5 Mon Sep 17 00:00:00 2001 From: Christian Eggers <45507747+ceggers-arri@users.noreply.github.com> Date: Mon, 15 Jul 2024 18:41:09 +0200 Subject: [PATCH] docs: update the drivers description (#6423) --- docs/get-started/quick-overview.rst | 8 +++++--- docs/integration/chip/stm32.rst | 15 ++++++++++---- docs/integration/driver/display/gen_mipi.rst | 4 ++-- examples/porting/lv_port_disp_template.c | 12 ++++++----- examples/porting/lv_port_lcd_stm32_template.c | 4 ++-- src/display/lv_display.h | 2 ++ src/drivers/nuttx/lv_nuttx_lcd.c | 4 ++-- src/drivers/x11/lv_x11_display.c | 2 +- src/misc/lv_color.h | 20 +++++++++++++++++-- 9 files changed, 50 insertions(+), 21 deletions(-) diff --git a/docs/get-started/quick-overview.rst b/docs/get-started/quick-overview.rst index 01dbf6c7c..57c88d4cc 100644 --- a/docs/get-started/quick-overview.rst +++ b/docs/get-started/quick-overview.rst @@ -33,11 +33,11 @@ If you would rather try LVGL on your own project follow these steps: ``lvgl`` folder, change the first ``#if 0`` to ``1`` to enable the file's content and set the :c:macro:`LV_COLOR_DEPTH` defines. - Include ``lvgl/lvgl.h`` in files where you need to use LVGL related functions. +- Call :cpp:func:`lv_init` - Call :cpp:expr:`lv_tick_inc(x)` every ``x`` milliseconds in a Timer or Task (``x`` should be between 1 and 10). It is required for the internal timing of LVGL. Alternatively, register a ``tick_get_cb`` with :cpp:func:`lv_tick_set_cb` so that LVGL can retrieve the current time directly. -- Call :cpp:func:`lv_init` - Create a display. .. code:: c @@ -51,8 +51,10 @@ If you would rather try LVGL on your own project follow these steps: .. code:: c - static lv_color_t buf1[MY_DISP_HOR_RES * MY_DISP_VER_RES / 10]; /*Declare a buffer for 1/10 screen size*/ - lv_display_set_buffers(display, buf1, NULL, sizeof(buf1)); /*Initialize the display buffer.*/ + /*Declare a buffer for 1/10 screen size*/ + #define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /*will be 2 for RGB565 */ + static uint8_t buf1[MY_DISP_HOR_RES * MY_DISP_VER_RES / 10 * BYTE_PER_PIXEL]; + lv_display_set_buffers(display, buf1, NULL, sizeof(buf1), LV_DISPLAY_RENDER_MODE_PARTIAL); /*Initialize the display buffer.*/ - Implement and register a function which can copy the rendered image to an area of your display: diff --git a/docs/integration/chip/stm32.rst b/docs/integration/chip/stm32.rst index c3d5adc39..ed630e2a3 100644 --- a/docs/integration/chip/stm32.rst +++ b/docs/integration/chip/stm32.rst @@ -36,8 +36,11 @@ the *main.c* file. \* Create some frame buffer(s) as global variables: //Frame buffers /*Static or global buffer(s). The second buffer is optional*/ - static lv_color_t buf_1[BUFF_SIZE]; //TODO: Chose a buffer size. DISPLAY_WIDTH * 10 is one suggestion. - static lv_color_t buf_2[BUFF_SIZE]; + //TODO: Adjust color format and choose buffer size. DISPLAY_WIDTH * 10 is one suggestion. + #define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /*will be 2 for RGB565 */ + #define BUFF_SIZE (DISPLAY_WIDTH * 10 * BYTE_PER_PIXEL) + static uint8_t buf_1[BUFF_SIZE]; + static uint8_t buf_2[BUFF_SIZE]; - In your ``main()`` function, after initialising your CPU, peripherals, and LCD panel, call :cpp:func:`lv_init` to initialise LVGL. @@ -149,8 +152,11 @@ variables: //Frame buffers /*Static or global buffer(s). The second buffer is optional*/ - static lv_color_t buf_1[BUFF_SIZE]; //TODO: Declare your own BUFF_SIZE appropriate to your system. - static lv_color_t buf_2[BUFF_SIZE]; + #define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /*will be 2 for RGB565 */ + //TODO: Declare your own BUFF_SIZE appropriate to your system. + #define BUFF_SIZE (DISPLAY_WIDTH * 10 * BYTE_PER_PIXEL) + static uint8_t buf_1[BUFF_SIZE]; + static uint8_t buf_2[BUFF_SIZE]; - In your ``main`` function, after your peripherals (SPI, GPIOs, LCD etc) have been initialised, initialise LVGL using :cpp:func:`lv_init`, @@ -163,6 +169,7 @@ variables: lv_init(); lv_display_t *display = lv_display_create(WIDTH, HEIGHT); /*Create the display*/ lv_display_set_flush_cb(display, my_flush_cb); /*Set a flush callback to draw to the display*/ + lv_display_set_buffers(disp, buf_1, buf_2, sizeof(buf_1), LV_DISPLAY_RENDER_MODE_PARTIAL); /*Set an initialized buffer*/ // Register the touch controller with LVGL - Not included here for brevity. diff --git a/docs/integration/driver/display/gen_mipi.rst b/docs/integration/driver/display/gen_mipi.rst index f350292e8..36fb91175 100644 --- a/docs/integration/driver/display/gen_mipi.rst +++ b/docs/integration/driver/display/gen_mipi.rst @@ -138,8 +138,8 @@ Example lv_display_set_rotation(my_disp, LV_DISPLAY_ROTATION_90); /* Configure draw buffers, etc. */ - lv_color_t * buf1 = NULL; - lv_color_t * buf2 = NULL; + uint8_t * buf1 = NULL; + uint8_t * buf2 = NULL; uint32_t buf_size = LCD_H_RES * LCD_BUF_LINES * lv_color_format_get_size(lv_display_get_color_format(my_disp)); diff --git a/examples/porting/lv_port_disp_template.c b/examples/porting/lv_port_disp_template.c index 8657acb95..a1e64abf3 100644 --- a/examples/porting/lv_port_disp_template.c +++ b/examples/porting/lv_port_disp_template.c @@ -25,6 +25,8 @@ #define MY_DISP_VER_RES 240 #endif +#define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /*will be 2 for RGB565 */ + /********************** * TYPEDEFS **********************/ @@ -63,21 +65,21 @@ void lv_port_disp_init(void) /* Example 1 * One buffer for partial rendering*/ - static lv_color_t buf_1_1[MY_DISP_HOR_RES * 10]; /*A buffer for 10 rows*/ + static uint8_t buf_1_1[MY_DISP_HOR_RES * 10 * BYTE_PER_PIXEL]; /*A buffer for 10 rows*/ lv_display_set_buffers(disp, buf_1_1, NULL, sizeof(buf_1_1), LV_DISPLAY_RENDER_MODE_PARTIAL); /* Example 2 * Two buffers for partial rendering * In flush_cb DMA or similar hardware should be used to update the display in the background.*/ - static lv_color_t buf_2_1[MY_DISP_HOR_RES * 10]; - static lv_color_t buf_2_2[MY_DISP_HOR_RES * 10]; + static uint8_t buf_2_1[MY_DISP_HOR_RES * 10 * BYTE_PER_PIXEL]; + static uint8_t buf_2_2[MY_DISP_HOR_RES * 10 * BYTE_PER_PIXEL]; lv_display_set_buffers(disp, buf_2_1, buf_2_2, sizeof(buf_2_1), LV_DISPLAY_RENDER_MODE_PARTIAL); /* Example 3 * Two buffers screen sized buffer for double buffering. * Both LV_DISPLAY_RENDER_MODE_DIRECT and LV_DISPLAY_RENDER_MODE_FULL works, see their comments*/ - static lv_color_t buf_3_1[MY_DISP_HOR_RES * MY_DISP_VER_RES]; - static lv_color_t buf_3_2[MY_DISP_HOR_RES * MY_DISP_VER_RES]; + static uint8_t buf_3_1[MY_DISP_HOR_RES * MY_DISP_VER_RES * BYTE_PER_PIXEL]; + static uint8_t buf_3_2[MY_DISP_HOR_RES * MY_DISP_VER_RES * BYTE_PER_PIXEL]; lv_display_set_buffers(disp, buf_3_1, buf_3_2, sizeof(buf_3_1), LV_DISPLAY_RENDER_MODE_DIRECT); } diff --git a/examples/porting/lv_port_lcd_stm32_template.c b/examples/porting/lv_port_lcd_stm32_template.c index 8db7eb050..1148d2cd2 100644 --- a/examples/porting/lv_port_lcd_stm32_template.c +++ b/examples/porting/lv_port_lcd_stm32_template.c @@ -71,8 +71,8 @@ void lv_port_display_init(void) lv_display_set_rotation(lcd_disp, LV_DISPLAY_ROTATION_270); /* set landscape orientation */ /* Example: two dynamically allocated buffers for partial rendering */ - lv_color_t * buf1 = NULL; - lv_color_t * buf2 = NULL; + uint8_t * buf1 = NULL; + uint8_t * buf2 = NULL; uint32_t buf_size = MY_DISP_HOR_RES * MY_DISP_VER_RES / 10 * lv_color_format_get_size(lv_display_get_color_format( lcd_disp)); diff --git a/src/display/lv_display.h b/src/display/lv_display.h index 498e5ea8f..84a4828df 100644 --- a/src/display/lv_display.h +++ b/src/display/lv_display.h @@ -228,6 +228,8 @@ int32_t lv_display_get_dpi(const lv_display_t * disp); /** * Set the buffers for a display, similarly to `lv_display_set_draw_buffers`, but accept the raw buffer pointers. + * For DIRECT/FULL rending modes, the buffer size must be at least + * `hor_res * ver_res * lv_color_format_get_size(lv_display_get_color_format(disp))` * @param disp pointer to a display * @param buf1 first buffer * @param buf2 second buffer (can be `NULL`) diff --git a/src/drivers/nuttx/lv_nuttx_lcd.c b/src/drivers/nuttx/lv_nuttx_lcd.c index c785d222f..228c44593 100644 --- a/src/drivers/nuttx/lv_nuttx_lcd.c +++ b/src/drivers/nuttx/lv_nuttx_lcd.c @@ -150,8 +150,8 @@ static void flush_cb(lv_display_t * disp, const lv_area_t * area_p, static lv_display_t * lcd_init(int fd, int hor_res, int ver_res) { - lv_color_t * draw_buf = NULL; - lv_color_t * draw_buf_2 = NULL; + uint8_t * draw_buf = NULL; + uint8_t * draw_buf_2 = NULL; lv_nuttx_lcd_t * lcd = lv_malloc_zeroed(sizeof(lv_nuttx_lcd_t)); LV_ASSERT_MALLOC(lcd); if(lcd == NULL) { diff --git a/src/drivers/x11/lv_x11_display.c b/src/drivers/x11/lv_x11_display.c index 91e5f2995..1a2b83cad 100644 --- a/src/drivers/x11/lv_x11_display.c +++ b/src/drivers/x11/lv_x11_display.c @@ -49,7 +49,7 @@ typedef struct { void * xdata; /**< allocated data for XImage */ /* LVGL related information */ lv_timer_t * timer; /**< timer object for @ref x11_event_handler */ - lv_color_t * buffer[2]; /**< (double) lv display buffers, depending on @ref LV_X11_RENDER_MODE */ + uint8_t * buffer[2]; /**< (double) lv display buffers, depending on @ref LV_X11_RENDER_MODE */ lv_area_t flush_area; /**< integrated area for a display update */ /* systemtick by thread related information */ pthread_t thr_tick; /**< pthread for SysTick simulation */ diff --git a/src/misc/lv_color.h b/src/misc/lv_color.h index ebf07b36a..993045f01 100644 --- a/src/misc/lv_color.h +++ b/src/misc/lv_color.h @@ -62,6 +62,12 @@ typedef uint8_t lv_opa_t; #define LV_OPA_MIN 2 /*Opacities below this will be transparent*/ #define LV_OPA_MAX 253 /*Opacities above this will fully cover*/ +/** + * Get the pixel size of a color format in bits, bpp + * @param cf a color format (`LV_COLOR_FORMAT_...`) + * @return the pixel size in bits + * @sa lv_color_format_get_bpp + */ #define LV_COLOR_FORMAT_GET_BPP(cf) ( \ (cf) == LV_COLOR_FORMAT_I1 ? 1 : \ (cf) == LV_COLOR_FORMAT_A1 ? 1 : \ @@ -82,6 +88,14 @@ typedef uint8_t lv_opa_t; 0 \ ) +/** + * Get the pixel size of a color format in bytes + * @param cf a color format (`LV_COLOR_FORMAT_...`) + * @return the pixel size in bytes + * @sa lv_color_format_get_size + */ +#define LV_COLOR_FORMAT_GET_SIZE(cf) ((LV_COLOR_FORMAT_GET_BPP(cf) + 7) >> 3) + /********************** * TYPEDEFS **********************/ @@ -207,15 +221,17 @@ typedef uint8_t lv_color_format_t; /** * Get the pixel size of a color format in bits, bpp - * @param src_cf a color format (`LV_COLOR_FORMAT_...`) + * @param cf a color format (`LV_COLOR_FORMAT_...`) * @return the pixel size in bits + * @sa LV_COLOR_FORMAT_GET_BPP */ uint8_t lv_color_format_get_bpp(lv_color_format_t cf); /** * Get the pixel size of a color format in bytes - * @param src_cf a color format (`LV_COLOR_FORMAT_...`) + * @param cf a color format (`LV_COLOR_FORMAT_...`) * @return the pixel size in bytes + * @sa LV_COLOR_FORMAT_GET_SIZE */ static inline uint8_t lv_color_format_get_size(lv_color_format_t cf) {