1.. _nema_gfx:
2
3====================
4NemaGFX Acceleration
5====================
6
7NemaGFX is a high-level graphics API supported
8by many embedded 2.5D GPUs. LVGL can use it to
9natively render LVGL graphics.
10
11Get Started with the Riverdi STM32U5 5-inch Display
12***************************************************
13
14`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
15is a ready-to-use port for the Riverdi STM32 5.0" Embedded Display
16(STM32U599NJH6Q or STM32U5A9NJH6Q) which has Nema enabled.
17Follow the instructions in the readme to get started.
18
19Usage and Configuration
20***********************
21
22Enable the renderer by setting :c:macro:`LV_USE_NEMA_GFX` to ``1`` in
23lv_conf.h. If using :c:macro:`LV_USE_NEMA_VG`,
24set :c:macro:`LV_NEMA_GFX_MAX_RESX` and :c:macro:`LV_NEMA_GFX_MAX_RESY`
25to the size of the display you will be using so that enough static
26memory will be reserved for VG. Without VG, more task types will be
27performed by the software renderer.
28
29"libs/nema_gfx" contains pre-compiled binaries for the Nema GPU
30drivers. In `lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
31the project is already configured to link the binaries when building.
32With a different STM32CubeIDE project, you can configure the libraries to be linked
33by right-clicking the project in the "Project Explorer" sidebar, clicking
34"Properties", navigating to "C/C++ Build", "Settings", "MCU G++ Linker", and then
35"Libraries". Add an entry under "Libraries (-l)" that is "nemagfx-float-abi-hard".
36Add an entry under "Library search path (-L)" which is a path to
37"libs/nema_gfx/lib/core/cortex_m33/gcc" e.g.
38"${workspace_loc:/${ProjName}/Middlewares/LVGL/lvgl/libs/nema_gfx/lib/core/cortex_m33/gcc}".
39You will also want to add the "libs/nema_gfx/include" directory to your include
40search paths. Under "MCU GCC Compiler", "Include paths", add an entry to "Include paths (-I)"
41which is a path to "libs/nema_gfx/include" e.g.
42"${workspace_loc:/${ProjName}/Middlewares/LVGL/lvgl/libs/nema_gfx/include}".
43Click "Apply and Close".
44
4532 and 16 bit :c:macro:`LV_COLOR_DEPTH` is supported.
46
47At the time of writing, :c:macro:`LV_USE_OS` support is experimental
48and not yet working in
49`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__
50
51NemaGFX requires a simple HAL implementation to allocate memory and optionally
52lock resources. You may use a custom HAL implementation for your platform or use one of the
53provided implementations by setting :c:macro:`LV_USE_NEMA_HAL` to a value other than
54:c:macro:`LV_NEMA_HAL_CUSTOM`.
55
56TSC Images
57**********
58
59TSC (ThinkSillicon Compression) images can be drawn by this renderer. The
60TSC 4/6/6A/12/12A color formats are part of :cpp:type:`lv_color_format_t`.
61All other renderers will ignore images with these color formats.
62Define an image descriptor variable with the corresponding
63TSC color format and the GPU will be able to draw it directly.
64Stride does not need to be specified because it will be computed by the
65renderer.
66
67.. code-block:: c
68
69    const lv_image_dsc_t img_demo_widgets_avatar_tsc6a = {
70        .header.cf = LV_COLOR_FORMAT_NEMA_TSC6A,
71        .header.w = 144,
72        .header.h = 144,
73        .data = img_demo_widgets_avatar_tsc6a_map,
74        .data_size = sizeof(img_demo_widgets_avatar_tsc6a_map),
75    };
76
77DMA2D
78*****
79
80The Nema renderer uses DMA2D to flush in parallel with rendering in
81`lv_port_riverdi_stm32u5 <https://github.com/lvgl/lv_port_riverdi_stm32u5>`__.
82
83If your STM does not have the Nema GPU, it may still support
84DMA2D. DMA2D is a simple peripheral which can draw fills
85and images independently of the CPU.
86See the LVGL :ref:`DMA2D support <dma2d>`.
87
88API
89***
90
91:ref:`lv_draw_nema_gfx_h`
92
93:ref:`lv_draw_nema_gfx_utils_h`
94