1# NXP 2NXP has integrated LVGL into the MCUXpresso SDK packages for general purpose and crossover microcontrollers, allowing 3easy evaluation and migration into your product design. 4[Download an SDK for a supported board](https://www.nxp.com/design/software/embedded-software/littlevgl-open-source-graphics-library:LITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY?&tid=vanLITTLEVGL-OPEN-SOURCE-GRAPHICS-LIBRARY) 5today and get started with your next GUI application. 6 7## Creating new project with LVGL 8Downloading the MCU SDK example project is recommended as a starting point. It comes fully configured with LVGL (and 9with PXP/VGLite support if the modules are present), no additional integration work is required. 10 11## HW acceleration for NXP iMX RT platforms 12Depending on the RT platform used, the acceleration can be done by NXP PXP (PiXel Pipeline) and/or the Verisilicon GPU 13through an API named VGLite. Each accelerator has its own context that allows them to be used individually as well 14simultaneously (in LVGL multithreading mode). 15 16### PXP accelerator 17Several drawing features in LVGL can be offloaded to the PXP engine. The CPU is available for other operations while the 18PXP is running. RTOS is required to block the LVGL drawing thread and switch to another task or suspend the CPU for 19power savings. 20 21Supported draw callbacks are available in "src/draw/nxp/pxp/lv_draw_pxp.c": 22```c 23 pxp_draw_ctx->base_draw.draw_img_decoded = lv_draw_pxp_img_decoded; 24 pxp_draw_ctx->blend = lv_draw_pxp_blend; 25 pxp_draw_ctx->base_draw.wait_for_finish = lv_draw_pxp_wait_for_finish; 26 pxp_draw_ctx->base_draw.buffer_copy = lv_draw_pxp_buffer_copy; 27``` 28 29#### Features supported: 30 All operations can be used in conjunction with optional transparency. 31 32 - RGB565 and ARGB8888 color formats 33 - Area fill with color 34 - BLIT (BLock Image Transfer) 35 - Screen Rotation (90, 180, 270 degree) 36 - Color keying 37 - Recoloring (color tint) 38 - Image Rotation (90, 180, 270 degree) 39 - Buffer copy 40 - RTOS integration layer 41 - Default FreeRTOS and bare metal code provided 42 43 - Combination of recolor and/or rotation + color key/alpha blend/transparency is supported. 44 That is achieved by PXP in two steps: 45 - First step is to recolor/rotate the image to a temporary buffer (statically allocated) 46 - Second step is required to handle color keying, alpha channel or to apply transparency 47 48#### Known limitations: 49 - Rotation is not supported for images unaligned to blocks of 16x16 pixels. 50PXP is set to process 16x16 blocks to optimize the system for memory bandwidth and image processing time. 51The output engine essentially truncates any output pixels after the desired number of pixels has been written. 52When rotating a source image and the output is not divisible by the block size, the incorrect pixels could be truncated 53and the final output image can look shifted. 54 55#### Basic configuration: 56 - Select NXP PXP engine in lv_conf.h: Set `LV_USE_GPU_NXP_PXP` to 1 57 - Enable default implementation for interrupt handling, PXP start function and automatic initialization: 58 Set `LV_USE_GPU_NXP_PXP_AUTO_INIT` to 1 59 - If `SDK_OS_FREE_RTOS` symbol is defined, FreeRTOS implementation will be used, otherwise bare metal code will be 60 included 61 62#### Basic initialization: 63 - If `LV_USE_GPU_NXP_PXP_AUTO_INIT` is enabled, no user code is required; PXP is initialized automatically in 64 `lv_init()` 65 - For manual PXP initialization, default configuration structure for callbacks can be used. Initialize PXP before 66 calling `lv_init()` 67```c 68 #if LV_USE_GPU_NXP_PXP 69 #include "src/draw/nxp/pxp/lv_gpu_nxp_pxp.h" 70 #endif 71 . . . 72 #if LV_USE_GPU_NXP_PXP 73 PXP_COND_STOP(!lv_gpu_nxp_pxp_init(), "PXP init failed."); 74 #endif 75``` 76 77#### Project setup: 78 - Add PXP related files to project: 79 - src/draw/nxp/pxp/lv_draw_pxp.c[.h]: draw context callbacks 80 - src/draw/nxp/pxp/lv_draw_pxp_blend.c[.h]: fill and blit (with optional transformation) 81 - src/draw/nxp/pxp/lv_gpu_nxp_pxp.c[.h]: init, uninit, run/wait PXP device 82 - src/draw/nxp/pxp/lv_gpu_nxp_pxp_osa.c[.h]: OS abstraction (FreeRTOS or bare metal) 83 - optional, required only if `LV_USE_GPU_NXP_PXP_AUTO_INIT` is set to 1 84 - PXP related code depends on two drivers provided by MCU SDK. These drivers need to be added to project: 85 - fsl_pxp.c[.h]: PXP driver 86 - fsl_cache.c[.h]: CPU cache handling functions 87 88#### Logging: 89 - By default, `LV_GPU_NXP_PXP_LOG_ERRORS` is enabled so that any PXP error will be seen on SDK debug console 90 - By default, `LV_GPU_NXP_PXP_LOG_TRACES` is disabled. Enable it for tracing logs (like PXP limitations) 91 92#### Advanced configuration: 93 - Implementation depends on multiple OS-specific functions. The struct `lv_nxp_pxp_cfg_t` with callback pointers is 94 used as a parameter for the `lv_gpu_nxp_pxp_init()` function. Default implementation for FreeRTOS and bare metal is 95 provided in lv_gpu_nxp_pxp_osa.c 96 - `pxp_interrupt_init()`: Initialize PXP interrupt (HW setup, OS setup) 97 - `pxp_interrupt_deinit()`: Deinitialize PXP interrupt (HW setup, OS setup) 98 - `pxp_run()`: Start PXP job. Use OS-specific mechanism to block drawing thread. PXP must finish drawing before 99 leaving this function. 100 - Area threshold (size limit) is configurable and used to decide whether the area will be processed by PXP or not. 101 Areas smaller than the defined value will be processed by CPU and those bigger than the threshold will be processed by 102 PXP. The threshold is defined as a macro in lv_draw_pxp.c 103 - `LV_GPU_NXP_PXP_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation) 104 105### VGLite accelerator 106Extra drawing features in LVGL can be handled by the VGLite engine. The CPU is available for other operations while the 107VGLite is running. An RTOS is required to block the LVGL drawing thread and switch to another task or suspend the CPU 108for power savings. 109 110Supported draw callbacks are available in "src/draw/nxp/vglite/lv_draw_vglite.c": 111```c 112 vglite_draw_ctx->base_draw.init_buf = lv_draw_vglite_init_buf; 113 vglite_draw_ctx->base_draw.draw_line = lv_draw_vglite_line; 114 vglite_draw_ctx->base_draw.draw_arc = lv_draw_vglite_arc; 115 vglite_draw_ctx->base_draw.draw_rect = lv_draw_vglite_rect; 116 vglite_draw_ctx->base_draw.draw_img_decoded = lv_draw_vglite_img_decoded; 117 vglite_draw_ctx->blend = lv_draw_vglite_blend; 118 vglite_draw_ctx->base_draw.wait_for_finish = lv_draw_vglite_wait_for_finish; 119 vglite_draw_ctx->base_draw.buffer_copy = lv_draw_vglite_buffer_copy; 120``` 121 122#### Features supported: 123 All operations can be used in conjunction with optional transparency. 124 125 - RGB565 and ARGB8888 color formats 126 - Area fill with color 127 - BLIT (BLock Image Transfer) 128 - Image Rotation (any degree with decimal) 129 - Image Scale 130 - Draw rectangle background with optional radius or gradient 131 - Blit rectangle background image 132 - Draw rectangle border/outline with optional rounded corners 133 - Draw arc with optional rounded ending 134 - Draw line or dashed line with optional rounded ending 135 - Buffer copy 136 137#### Known limitations: 138 - Source image alignment: 139 The byte alignment requirement for a pixel depends on the specific pixel format. Both buffer address and buffer stride 140 must be aligned. As general rule, the alignment is set to 16 pixels. This makes the buffer address alignment to be 141 32 bytes for RGB565 and 64 bytes for ARGB8888. 142 - For pixel engine (PE) destination, the alignment should be 64 bytes for all tiled (4x4) buffer layouts. 143 The pixel engine has no additional alignment requirement for linear buffer layouts (`VG_LITE_LINEAR`). 144 145#### Basic configuration: 146 - Select NXP VGLite engine in lv_conf.h: Set `LV_USE_GPU_NXP_VG_LITE` to 1 147 - `SDK_OS_FREE_RTOS` symbol needs to be defined so that the FreeRTOS implementation will be used 148 149#### Basic initialization: 150 - Initialize VGLite before calling `lv_init()` by specifying the width/height of tessellation window. Value should be 151 a multiple of 16; minimum value is 16 pixels, maximum cannot be greater than the frame width. If less than or equal 152 to 0, then no tessellation buffer is created, in which case VGLite is initialized only for blitting. 153```c 154 #if LV_USE_GPU_NXP_VG_LITE 155 #include "vg_lite.h" 156 #endif 157 . . . 158 #if LV_USE_GPU_NXP_VG_LITE 159 VG_LITE_COND_STOP(vg_lite_init(64, 64) != VG_LITE_SUCCESS, "VGLite init failed."); 160 #endif 161``` 162 163#### Project setup: 164 - Add VGLite related files to project: 165 - src/draw/nxp/vglite/lv_draw_vglite.c[.h]: draw context callbacks 166 - src/draw/nxp/vglite/lv_draw_vglite_blend.c[.h]: fill and blit (with optional transformation) 167 - src/draw/nxp/vglite/lv_draw_vglite_rect.c[.h]: draw rectangle 168 - src/draw/nxp/vglite/lv_draw_vglite_arc.c[.h]: draw arc 169 - src/draw/nxp/vglite/lv_draw_vglite_line.c[.h]: draw line 170 - src/draw/nxp/vglite/lv_vglite_buf.c[.h]: init/get vglite buffer 171 - src/draw/nxp/vglite/lv_vglite_utils.c[.h]: function helpers 172 173#### Logging: 174 - By default, `LV_GPU_NXP_VG_LITE_LOG_ERRORS` is enabled so that any VGLite error will be seen on SDK debug console 175 - By default, `LV_GPU_NXP_VG_LITE_LOG_TRACES` is disabled. Enable it for tracing logs (like blit split workaround or 176 VGLite fallback to CPU due to any error on the driver) 177 178#### Advanced configuration: 179 - Area threshold (size limit) is configurable and used to decide whether the area will be processed by VGLite or not. 180 Areas smaller than the defined value will be processed by CPU and those bigger than the threshold will be processed by 181 VGLite. The threshold is defined as a macro in lv_draw_vglite.c 182 - `LV_GPU_NXP_VG_LITE_SIZE_LIMIT`: size threshold for fill/blit (with optional transformation) 183
