feat(docs): reorganize docs (#7136)

docs/details/integration/renderers/arm2d.rst

@@ -0,0 +1,70 @@
+.. _arm2d:
+
+==========
+Arm-2D GPU
+==========
+
+Arm-2D is not a GPU but **an abstraction layer for 2D GPUs dedicated to
+Microcontrollers**. It supports all Cortex-M processors ranging from
+Cortex-M0 to the latest Cortex-M85.
+
+Arm-2D accelerates LVGL9 with two modes: **Synchronous Mode** and
+**Asynchronous Mode**.
+
+- When **Helium** and **ACI (Arm Custom Instruction)** are available, it is recommend
+  to use **Synchronous Mode** to accelerate LVGL.
+- When Arm-2D backed 2D-GPUs are available, for example, **DMAC-350 based 2D
+  GPUs**, it is recommend to use **Asynchronous Mode** to accelerate LVGL.
+
+Arm-2D is an open-source project on GitHub. For more, please refer to:
+https://github.com/ARM-software/Arm-2D.
+
+
+How to Use
+**********
+
+In general:
+
+- you can set the macro :c:macro:`LV_USE_DRAW_ARM2D_SYNC` to ``1`` and
+  :c:macro:`LV_DRAW_SW_ASM` to ``LV_DRAW_SW_ASM_HELIUM`` in ``lv_conf.h`` to
+  enable Arm-2D synchronous acceleration for LVGL.
+- You can set
+  the macro :c:macro:`LV_USE_DRAW_ARM2D_ASYNC` to ``1`` in ``lv_conf.h`` to enable
+  Arm-2D Asynchronous acceleration for LVGL.
+
+If you are using
+`CMSIS-Pack <https://github.com/lvgl/lvgl/tree/master/env_support/cmsis-pack>`__
+to deploy the LVGL. You don't have to define the macro
+:c:macro:`LV_USE_DRAW_ARM2D_SYNC` manually, instead the lv_conf_cmsis.h will
+check the environment and set the :c:macro:`LV_USE_DRAW_ARM2D_SYNC` accordingly.
+
+Design Considerations
+*********************
+
+As mentioned before, Arm-2D is an abstraction layer for 2D GPU; hence if
+there is no accelerator or dedicated instruction set (such as Helium or
+ACI) available for Arm-2D, it provides negligible performance boost for
+LVGL (sometimes worse) for regular Cortex-M processors.
+
+**We highly recommend you enable Arm-2D acceleration for LVGL** when:
+
+-  The target processors are **Cortex-M55**, **Cortex-M52** and **Cortex-M85**
+-  The target processors support
+   `Helium <https://developer.arm.com/documentation/102102/0103/?lang=en>`__.
+-  The device vendor provides an arm-2d compliant driver for their
+   proprietary 2D accelerators and/or ACI (Arm Customized Instruction).
+-  The target device contains
+   `DMAC-350 <https://community.arm.com/arm-community-blogs/b/internet-of-things-blog/posts/arm-corelink-dma-350-next-generation-direct-memory-access-for-endpoint-ai>`__
+
+Examples
+********
+
+-  `A Cortex-M55 (supports Helium) based MDK Project, PC emulation is
+   available. <https://github.com/lvgl/lv_port_an547_cm55_sim>`__
+
+API
+***
+
+:ref:`lv_draw_sw_arm2d_h`
+
+:ref:`lv_blend_arm2d_h`

docs/details/integration/renderers/index.rst

@@ -0,0 +1,14 @@
+==================
+Renderers and GPUs
+==================
+
+.. toctree::
+    :maxdepth: 2
+
+    sw
+    arm2d
+    nema_gfx
+    nxp_pxp
+    nxp_vglite
+    sdl
+    stm32_dma2d

docs/details/integration/renderers/nema_gfx.rst

@@ -0,0 +1,94 @@
+.. _stm32_nema_gfx:
+
+===================================
+NemaGFX Acceleration (AKA NeoChrom)
+===================================
+
+Some of the more powerful STM32 MCUs such as the
+STM32U5 feature a 2.5D GPU which can natively draw most
+LVGL primitives.
+
+Get Started with the Riverdi STM32U5 5-inch Display
+***************************************************
+
+`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
+is a ready-to-use port for the Riverdi STM32 5.0" Embedded Display
+(STM32U599NJH6Q or STM32U5A9NJH6Q) which has Nema enabled.
+Follow the instructions in the readme to get started.
+
+Usage and Configuration
+***********************
+
+Enable the renderer by setting :c:macro:`LV_USE_NEMA_GFX` to ``1`` in
+lv_conf.h. If using :c:macro:`LV_USE_NEMA_VG`,
+set :c:macro:`LV_NEMA_GFX_MAX_RESX` and :c:macro:`LV_NEMA_GFX_MAX_RESY`
+to the size of the display you will be using so that enough static
+memory will be reserved for VG. Without VG, more task types will be
+performed by the software renderer.
+
+"libs/nema_gfx" contains pre-compiled binaries for the Nema GPU
+drivers. In `lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
+the project is already configured to link the binaries when building.
+With a different STM32CubeIDE project, you can configure the libraries to be linked
+by right-clicking the project in the "Project Explorer" sidebar, clicking
+"Properties", navigating to "C/C++ Build", "Settings", "MCU G++ Linker", and then
+"Libraries". Add an entry under "Libraries (-l)" that is "nemagfx-float-abi-hard".
+Add an entry under "Library search path (-L)" which is a path to
+"libs/nema_gfx/lib/core/cortex_m33/gcc" e.g.
+"${workspace_loc:/${ProjName}/Middlewares/LVGL/lvgl/libs/nema_gfx/lib/core/cortex_m33/gcc}".
+You will also want to add the "libs/nema_gfx/include" directory to your include
+search paths. Under "MCU GCC Compiler", "Include paths", add an entry to "Include paths (-I)"
+which is a path to "libs/nema_gfx/include" e.g.
+"${workspace_loc:/${ProjName}/Middlewares/LVGL/lvgl/libs/nema_gfx/include}".
+Click "Apply and Close".
+
+32 and 16 bit :c:macro:`LV_COLOR_DEPTH` is supported.
+
+At the time of writing, :c:macro:`LV_USE_OS` support is experimental
+and not yet working in
+`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
+
+"src/draw/nema_gfx/lv_draw_nema_gfx_hal.c" implements the HAL functionality
+required by Nema to allocate memory and lock resources (in this implementation,
+no locking is done). It may conflict with existing definitions
+if you have an existing Nema HAL implementation. You may
+simply be able to remove yours.
+
+TSC Images
+**********
+
+TSC (ThinkSillicon Compression) images can be drawn by this renderer. The
+TSC 4/6/6A/12/12A color formats are part of :cpp:type:`lv_color_format_t`.
+All other renderers will ignore images with these color formats.
+Define an image descriptor variable with the corresponding
+TSC color format and the GPU will be able to draw it directly.
+Stride does not need to be specified because it will be computed by the
+renderer.
+
+.. code-block:: c
+
+    const lv_image_dsc_t img_demo_widgets_avatar_tsc6a = {
+        .header.cf = LV_COLOR_FORMAT_NEMA_TSC6A,
+        .header.w = 144,
+        .header.h = 144,
+        .data = img_demo_widgets_avatar_tsc6a_map,
+        .data_size = sizeof(img_demo_widgets_avatar_tsc6a_map),
+    };
+
+DMA2D
+*****
+
+The Nema renderer uses DMA2D to flush in parallel with rendering in
+`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__.
+
+If your STM does not have the Nema GPU, it may still support
+DMA2D. DMA2D is a simple peripheral which can draw fills
+and images independently of the CPU.
+See the LVGL :ref:`DMA2D support <dma2d>`.
+
+API
+***
+
+:ref:`lv_draw_nema_gfx_h`
+
+:ref:`lv_draw_nema_gfx_utils_h`

docs/details/integration/renderers/nxp_pxp.rst

@@ -0,0 +1,15 @@
+===========
+NXP PXP GPU
+===========
+
+API
+***
+
+:ref:`lv_draw_pxp_h`
+
+:ref:`lv_pxp_cfg_h`
+
+:ref:`lv_pxp_osa_h`
+
+:ref:`lv_pxp_utils_h`
+

docs/details/integration/renderers/nxp_vglite.rst

@@ -0,0 +1,86 @@
+.. _vglite:
+
+===============
+NXP VG-Lite GPU
+===============
+
+This is a generic VG-Lite rendering backend implementation that is designed to utilize
+`VeriSilicon <https://verisilicon.com/>`_'s generic API to operate GPU hardware as much as possible.
+
+Even with different chip manufacturers, as long as they use the same version of VG-Lite API as the rendering backend,
+LVGL rendering acceleration can be supported without the need for LVGL adaptation work.
+
+
+Configuration
+*************
+
+1. Set :c:macro:`LV_USE_DRAW_VG_LITE` to 1 in ``lv_conf.h`` to enabled the VG-Lite rendering backend.
+   Make sure that your hardware has been adapted to the VG-Lite API and that the absolute path to ``vg_lite.h``, which can be directly referenced by lvgl, has been exposed.
+
+2. Confirm the GPU initialization method, there are two ways:
+
+   - The SDK calls the GPU initialization function on its own during system startup, and the GPU is available when LVGL starts; set :c:macro:`LV_VG_LITE_USE_GPU_INIT` to 0.
+   - LVGL actively calls the GPU initialization function, and the SDK needs to implement the public function `gpu_init()`.
+     LVGL will call it to complete the GPU hardware initialization during startup; set :c:macro:`LV_VG_LITE_USE_GPU_INIT` to 1.
+
+3. Set the :c:macro:`LV_VG_LITE_USE_ASSERT` configuration to enable GPU call parameter checking.
+   Due to the complexity of the parameters used in GPU calls, incorrect parameters can result in abnormal GPU hardware operation, such as forgetting to add an end symbol
+   to the path or not meeting the alignment requirements for buffer stride.
+   To quickly resolve such issues, strict parameter checking has been added before each VG-Lite call, including buffer stride validation and matrix invertibility check.
+   When an error parameter is detected, an assertion will occur to print out the error parameter, allowing the user to promptly make corrections and reduce the time wasted on hardware simulation.
+   Please note that enabling this check will decrease runtime performance. It is recommended to enable it in Debug mode and disable it in the Release version.
+
+4. Set the :c:macro:`LV_VG_LITE_FLUSH_MAX_COUNT` configuration to specify the flush method.
+   VG-Lite uses two sets of command buffer buffers to render instructions, and utilizing this mechanism well can greatly improve drawing efficiency.
+   Currently, two buffering methods are supported:
+
+   - Set :c:macro:`LV_VG_LITE_FLUSH_MAX_COUNT` to zero (recommended). The rendering backend will obtain the GPU's working status every time it writes rendering instructions to the command buffer.
+
+   When the GPU is idle, it will immediately call ``vg_lite_flush`` to notify the GPU to start rendering and swap the command buffer. When the GPU is busy, it will continue to fill the command buffer cache with rendering instructions.
+   The underlying driver will automatically determine if the command buffer has been filled. When it is about to be filled, it will forcibly wait for the unfinished drawing tasks to end and swap the command buffer.
+   This method can effectively improve GPU utilization, especially in scenarios where rendering text, as the GPU's drawing time and the CPU's data preparation time are very close, allowing the CPU and GPU to run in parallel.
+
+   - Set :c:macro:`LV_VG_LITE_FLUSH_MAX_COUNT` to a value greater than zero, such as 8. After writing 8 rendering instructions to the command buffer, the rendering backend
+
+   will call ``vg_lite_flush`` to notify the GPU to start rendering and swap the command buffer.
+
+5. Set the :c:macro:`LV_VG_LITE_USE_BOX_SHADOW` configuration to use GPU rendering for shadows.
+   In fact, GPU hardware does not actually support shadow rendering. However, through experimentation, it has been found that a similar shadow effect
+   can be achieved by using multiple layers of borders with different levels of transparency.
+   It is recommended to enable this configuration in scenarios where the shadow quality requirements are not high, as it can significantly improve rendering efficiency.
+
+6. Set the :c:macro:`LV_VG_LITE_GRAD_CACHE_CNT` configuration to specify the number of gradient cache entries.
+   Gradient drawing includes linear gradients and radial gradients. Using a cache can effectively reduce the number of times the gradient image is created and improve drawing efficiency.
+   Each individual gradient consumes around 4K of GPU memory pool. If there are many gradients used in the interface, you can try increasing the number of gradient cache entries.
+   If the VG-Lite API returns the :c:macro:`VG_LITE_OUT_OF_RESOURCES` error, you can try increasing the size of the GPU memory pool or reducing the number of gradient cache entries.
+
+7. Set the :c:macro:`LV_VG_LITE_STROKE_CACHE_CNT` configuration to specify the number of stroke path caches.
+   When the stroke parameters do not change, the previously generated stroke parameters are automatically retrieved from the cache to improve rendering performance.
+   The memory occupied by the stroke is strongly related to the path length. If the VG-Lite API returns the :c:macro:`VG_LITE_OUT_OF_RESOURCES` error,
+   you can try increasing the size of the GPU memory pool or reducing the number of stroke cache entries.
+
+NOTE: VG-Lite rendering backend does not support multi-threaded calls, please make sure :c:macro:`LV_USE_OS` is always configured as :c:macro:`LV_OS_NONE`.
+
+
+VG-Lite Simulator
+*****************
+
+LVGL integrates a VG-Lite simulator based on ThorVG.
+Its purpose is to simplify the debugging of VG-Lite adaptation and reduce the time of debugging and locating problems on hardware devices.
+For detailed instructions, see :ref:`vg_lite_tvg`.
+
+
+API
+***
+
+:ref:`lv_draw_vglite_h`
+
+:ref:`lv_vglite_buf_h`
+
+:ref:`lv_vglite_matrix_h`
+
+:ref:`lv_vglite_path_h`
+
+:ref:`lv_vglite_utils_h`
+
+

docs/details/integration/renderers/sdl.rst

@@ -0,0 +1,9 @@
+============
+SDL Renderer
+============
+
+API
+***
+
+:ref:`lv_draw_sdl_h`
+

docs/details/integration/renderers/stm32_dma2d.rst

@@ -0,0 +1,9 @@
+===============
+STM32 DMA2D GPU
+===============
+
+API
+***
+
+:ref:`lv_draw_dma2d_h`
+

docs/details/integration/renderers/sw.rst

@@ -0,0 +1,12 @@
+=================
+Software Renderer
+=================
+
+API
+***
+
+:ref:`lv_draw_sw_h`
+
+:ref:`lv_draw_sw_blend_h`
+
+:ref:`lv_draw_sw_gradient_h`