docs(disp): recommend to use lv_display_set_buffers instead (#5304)

Signed-off-by: Xu Xingliang <xuxingliang@xiaomi.com>

docs/CHANGELOG.rst

@@ -22,8 +22,7 @@ If you are updating a v8 project to v9, special care must be taken as some parts
 
 So pay extra attention to these:
 
-- :cpp:func:`lv_display_set_draw_buffers(display, buf1, buf2)` is more or less the equivalent of ``lv_disp_draw_buf_init(&draw_buf_dsc, buf1, buf2, buf_size_px)`` from v8, however in **v9 the buffer type is lv_draw_buf_t**.
-- Make sure to call :cpp:func:`lv_display_set_render_mode(display, mode)` to set correct render mode.
+- :cpp:func:`lv_display_set_buffers(display, buf1, buf2, buf_size_byte, mode)` is more or less the equivalent of ``lv_disp_draw_buf_init(&draw_buf_dsc, buf1, buf2, buf_size_px)`` from v8, however in **v9 the buffer size is set in bytes**.
 - In v9 ``lv_color_t`` is always RGB888 regardless of ``LV_COLOR_DEPTH``.
 - ``lv_conf.h`` has been changed a lot, so don't forget to update it from ``lv_conf_template.h``
 - Be sure ``<stdint.h>`` is **not** included in ``lv_conf.h``. In v9 we have some assembly parts for even better performance and a random include there would mess up the assembly part.
@@ -79,10 +78,9 @@ Display API
 
    lv_display_t * disp = lv_display_create(hor_res, ver_res)
    lv_display_set_flush_cb(disp, flush_cb);
-   lv_display_set_draw_buffers(disp, buf1, buf2);
-   lv_display_set_render_mode(disp, mode);
+   lv_display_set_buffers(disp, buf1, buf2, buf_size_in_bytes, mode);
 
--  Note that now **draw buffer can be malloced by `lv_draw_buf_create` or initialized by `lv_draw_buf_init`**
+-  Note that now **buf size is in bytes and not pixels**
 -  ``mode`` can be:
 
    -  ``LV_DISPLAY_RENDER_MODE_PARTIAL`` This way the buffers can be

docs/integration/chip/stm32.rst

@@ -43,7 +43,7 @@ the *main.c* file. \* Create some frame buffer(s) as global variables:
   peripherals, and LCD panel, call :cpp:func:`lv_init` to initialise LVGL.
   You can then create the display driver using
   :cpp:func:`lv_disp_create`, and register the frame buffers using
-  :cpp:func:`lv_disp_set_draw_buffers`.
+  :cpp:func:`lv_display_set_buffers`.
 
 .. code:: c
 
@@ -51,8 +51,8 @@ the *main.c* file. \* Create some frame buffer(s) as global variables:
    lv_init();
 
    lv_disp_t * disp = lv_disp_create(WIDTH, HEIGHT); /*Basic initialization with horizontal and vertical resolution in pixels*/
-   lv_disp_set_flush_cb(disp, my_flush_cb); /*Set a flush callback to draw to the display*/
-   lv_disp_set_draw_buffers(disp, buf_1, buf_2, sizeof(buf_1), LV_DISP_RENDER_MODE_PARTIAL); /*Set an initialized buffer*/
+   lv_display_set_flush_cb(disp, 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_DISP_RENDER_MODE_PARTIAL); /*Set an initialized buffer*/
 
 - Create some dummy objects to test the output:
 

docs/integration/driver/display/gen_mipi.rst

@@ -78,7 +78,7 @@ when the color transfer completes. In case of a DMA transfer this is usually don
 	by polling the hardware, polling a global variable (which is reset at the end of the transfer), or by using a semaphore or other locking mechanism.
 
 Please also note that the driver does not handle the draw buffer allocation, because this may be platform-dependent, too. Thus you need to allocate the buffers and assign them
-to the display object as usual by calling :cpp:func:`lv_display_set_draw_buffers()`.
+to the display object as usual by calling :cpp:func:`lv_display_set_buffers()`.
 
 The driver can be used to create multiple displays. In such a configuration the callbacks must be able to distinguish between the displays. Usually one would
 implement a separate set of callbacks for each display. Also note that the user must take care of arbitrating the bus when multiple devices are connected to it.
@@ -97,11 +97,11 @@ Example
 	#define LCD_H_RES		240
 	#define LCD_V_RES		320
 	#define LCD_BUF_LINES	60
-	
+
 	lv_display_t *my_disp;
 
 	...
-	
+
 
 	/* Initialize LCD I/O bus, reset LCD */
 	static int32_t my_lcd_io_init(void)
@@ -135,7 +135,7 @@ Example
 
 		/* Create the LVGL display object and the LCD display driver */
 		my_disp = lv_lcd_generic_mipi_create(LCD_H_RES, LCD_V_RES, LV_LCD_FLAG_NONE, my_lcd_send_cmd, my_lcd_send_color);
-		
+
 		/* Set display orientation to landscape */
 		lv_display_set_rotation(my_disp, LV_DISPLAY_ROTATION_90);
 
@@ -201,11 +201,11 @@ the generic MIPI driver supports sending a custom command list to the controller
 		...
 		LV_LCD_CMD_DELAY_MS, LV_LCD_CMD_EOF		/* terminate list: this is required! */
 	};
-	
+
 	...
 
 	lv_lcd_generic_mipi_send_cmd_list(my_disp, init_cmd_list);
-	
+
 You can add a delay between the commands by using the pseudo-command ``LV_LCD_CMD_DELAY_MS``, which must be followed by the delay given in 10ms units.
 To terminate the command list you must use a delay with a value of ``LV_LCD_CMD_EOF``, as shown above.
 

docs/porting/display.rst

@@ -54,7 +54,7 @@ Draw buffers
 ------------
 
 The draw buffers can be set with
-:cpp:expr:`lv_display_set_draw_buffers(display, buf1, buf2, buf_size_px, render_mode)`
+:cpp:expr:`lv_display_set_buffers(display, buf1, buf2, buf_size_px, render_mode)`
 
 -  ``buf1`` a buffer where LVGL can render
 -  ``buf2`` a second optional buffer (see more details below)
@@ -86,7 +86,7 @@ Example:
 .. code:: c
 
    static uint16_t buf[LCD_HOR_RES * LCD_VER_RES / 10];
-   lv_disp_set_draw_buffers(disp, buf, NULL, sizeof(buf), LV_DISP_RENDER_MODE_PARTIAL);
+   lv_display_set_buffers(disp, buf, NULL, sizeof(buf), LV_DISP_RENDER_MODE_PARTIAL);
 
 One buffer
 ^^^^^^^^^^

src/dev/display/tft_espi/lv_tft_espi.cpp

@@ -54,9 +54,9 @@ lv_disp_t * lv_tft_espi_create(uint32_t hor_res, uint32_t ver_res, void * buf, u
     dsc->tft = new TFT_eSPI(hor_res, ver_res);
     dsc->tft->begin();          /* TFT init */
     dsc->tft->setRotation(3);   /* Landscape orientation, flipped */
-    lv_disp_set_driver_data(disp, (void *)dsc);
-    lv_disp_set_flush_cb(disp, flush_cb);
-    lv_disp_set_draw_buffers(disp, (void *)buf, NULL, buf_size_bytes, LV_DISP_RENDER_MODE_PARTIAL);
+    lv_display_set_driver_data(disp, (void *)dsc);
+    lv_display_set_flush_cb(disp, flush_cb);
+    lv_display_set_buffers(disp, (void *)buf, NULL, buf_size_bytes, LV_DISP_RENDER_MODE_PARTIAL);
     return disp;
 }
 

src/display/lv_display.h

@@ -239,6 +239,8 @@ void lv_display_set_buffers(lv_display_t * disp, void * buf1, void * buf2, uint3
 
 /**
  * Set the buffers for a display, accept a draw buffer pointer.
+ * Normally use `lv_display_set_buffers` is enough for most cases.
+ * Use this function when an existing lv_draw_buf_t is available.
  * @param disp              pointer to a display
  * @param buf1              first buffer
  * @param buf2              second buffer (can be `NULL`)