docs: update the drivers description (#6423)

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*/
+   /*Declare a buffer for 1/10 screen size*/
-   lv_display_set_buffers(display, buf1, NULL, sizeof(buf1));  /*Initialize the display buffer.*/
+   #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:

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.
+   //TODO: Adjust color format and choose buffer size. DISPLAY_WIDTH * 10 is one suggestion.
-   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 */
+   #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.
+   #define BYTE_PER_PIXEL (LV_COLOR_FORMAT_GET_SIZE(LV_COLOR_FORMAT_RGB565)) /*will be 2 for RGB565 */
-   static lv_color_t buf_2[BUFF_SIZE];
+   //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.
 

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;
+		uint8_t * buf1 = NULL;
-		lv_color_t * buf2 = 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));
 

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 uint8_t buf_2_1[MY_DISP_HOR_RES * 10 * BYTE_PER_PIXEL];
-    static lv_color_t buf_2_2[MY_DISP_HOR_RES * 10];
+    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 uint8_t buf_3_1[MY_DISP_HOR_RES * MY_DISP_VER_RES * BYTE_PER_PIXEL];
-    static lv_color_t buf_3_2[MY_DISP_HOR_RES * MY_DISP_VER_RES];
+    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);
 
 }

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;
+    uint8_t * buf1 = NULL;
-    lv_color_t * buf2 = 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));

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`)

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;
+    uint8_t * draw_buf = NULL;
-    lv_color_t * draw_buf_2 = 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) {

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 */

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)
 {