Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for a specific release, use the drop-down menu on the left.

VG-Lite GPU and Examples

Overview

K230’s VG-Lite stack is now maintained jointly by the RT-Smart kernel driver and the user-space HAL, and no longer depends on the legacy libgpu.a and the legacy userapps/src/vg_lite copy in MPP.

Application / LVGL
    -> libvg_lite.a (user-space command building and API)
    -> /dev device ioctl
    -> RT-Smart VG-Lite kernel driver
    -> GCNanoUltraV GPU

Source locations:

src/rtsmart/rtsmart/kernel/bsp/maix3/drivers/interdrv/gpu/
src/rtsmart/libs/rtsmart_hal/components/vg_lite/
src/rtsmart/examples/peripheral/vglite_tiger/

Configuration

Enable the kernel and user-space separately:

RT_USING_VG_LITE=y
RTSMART_HAL_ENABLE_VG_LITE=y

RT_USING_VG_LITE is enabled by default when RT-Smart userspace is enabled; the Tiger example also selects the user-space HAL. Building the example requires:

RTSMART_ENABLE_PERIPHERAL_EXAMPLES=y
RTSMART_PERIPHERAL_ENABLE_VGLITE_TIGER=y

The user-space build installs vg_lite.h and libvg_lite.a. The example Makefile obtains the header files and linker parameters through librtsmart_hal.mk; custom applications should reuse the same build fragment.

API Usage Flow

The minimum flow is as follows:

#include <vg_lite.h>

vg_lite_buffer_t target = {0};
vg_lite_error_t error;

error = vg_lite_init(640, 480);
if (error != VG_LITE_SUCCESS)
    return error;

target.width = 640;
target.height = 480;
target.format = VG_LITE_RGBA8888;

error = vg_lite_allocate(&target);
if (error == VG_LITE_SUCCESS) {
    vg_lite_clear(&target, NULL, 0xff202020);
    vg_lite_finish();
    vg_lite_free(&target);
}

vg_lite_close();

Buffers created by vg_lite_allocate() use GPU-accessible contiguous pages and uncached mappings. Externally allocated contiguous buffers for display, MPP, or other modules should have their physical address, stride, format, and user address filled in before calling vg_lite_map(), and vg_lite_unmap() should be called before exiting. The driver validates the user virtual address and physically contiguous range; do not pass ordinary non-contiguous heap buffers.

The drawing API first writes commands to the user-space command buffer. vg_lite_flush() submits the current batch and allows the CPU to build the next batch, while vg_lite_finish() waits for all GPU work to complete. Before the CPU reads GPU results or passes a buffer to a module that does not share the synchronization semantics, the corresponding synchronization must be completed.

Tiger Example

Run without a display and view rendering performance:

vglite_tiger.elf --no-display --frames=100 --profile

After connecting a display, first use list_connector to query the connector enumeration value, and then run:

vglite_tiger.elf -c <connector_type> --animate --profile

Common parameters:

Parameter	Description
--frames=N	Number of frames to render; defaults to a static frame when --animate is not specified
--animate	Updates the Tiger transformation each frame
--fps=N / --no-sync	Target frame rate for display synchronization, or disables synchronization waits
--pipeline	Enables a multi-display-buffer pipeline during animated display
--buffers=1..8	Number of display buffers
--quality=high|upper|medium|low	Path tessellation quality
--cmd-buf-kb=N	Command buffer size; takes effect before initialization
--tess-width=N、--tess-height=N	Tessellation dimensions
--no-upload	Inlines path data each frame, for comparison with uploaded paths
--profile	Outputs timing for the clear, draw, submit, finish, and display stages
--trace、--trace-paths	Outputs runtime or path-level tracing information

--pipeline can only be used together with --animate and display output. Press Ctrl+C to end continuous display.

Performance and Memory Considerations

• Static or repeated paths should be uploaded first and reused across frames to avoid copying path data each time.

• Keep the transformed bounds of paths compact; excessively large tessellation regions increase tile stalls.

• Combine multiple draws into the same batch and use flush()/finish() to define explicit synchronization points.

• VG-Lite’s own buffers are uncached; when mapping external cacheable buffers, necessary cache clean/invalidate operations still occur.

• The current user-space HAL uses a global context, and multiple threads should not build commands concurrently.

For the LVGL GPU renderer and image conversion paths, see LVGL Example.