docs(linux): add overview page and update opengl overview (#10053)

2026-05-25 01:04:25 +08:00 · 2026-05-12 09:35:12 +02:00
parent 1ca082b7a5
commit fc4c7cee6a
29 changed files with 152 additions and 118 deletions
@@ -1,10 +1,9 @@
 ---
-title: Update RootFS
-description: "LVGL application ################"
+title: LVGL Application on Buildroot
+description: "How to build and deploy an LVGL application into a Buildroot rootfs overlay."
 ---

-LVGL application
-################
+# LVGL application

 This section provides information about the steps to follow to get a custom
 application using LVGL running on the board.
@@ -160,4 +159,4 @@ sysroot was updated as expected.
 find . -name lvgl-app
 ```

-[Flash the image](/integration/embedded_linux/os/buildroot/image_generation) and run the benchmark application on the board.
+See the [Flash the image](/integration/embedded_linux/distros/buildroot/custom_image#flash-the-image) section to test the system.
@@ -1,10 +1,9 @@
 ---
-title: build
-description: "RPi4 custom image #################"
+title: Custom Buildroot Image
+description: "Step-by-step guide to creating a custom Buildroot image, using the Raspberry Pi 4 as an example. Adaptable to other boards."
 ---

-RPi4 custom image
-#################
+# Custom image for buildroot

 This chapter offers a detailed guide for creating a custom image for the
 Raspberry Pi 4 (RPi4). Key Buildroot components and concepts will be
@@ -169,9 +168,6 @@ If it is mounted on /dev/sda, run the following command
 sudo dd if=images/sdcard.img of=/dev/sda
 ```

-As mentioned in [images](/integration/embedded_linux/os/buildroot/image_generation), the output image is in `images` and named
-`sdcard.img`.
-
 Connect an Ethernet cable to the RPi4 and ensure the laptop and the RPi4 are on
 the same network.

@@ -1,13 +1,11 @@
 ---
-title: ""
-description: "Buildroot #########"
+title: Buildroot
+description: "Buildroot integration guide for building LVGL applications on embedded Linux."
 ---

-Buildroot
-#########
-
 Buildroot is a set of Makefiles and patches that simplifies and automates the
 process of building a complete and bootable Linux environment for an embedded
 system, while using cross-compilation to allow building for multiple target
 platforms on a single Linux-based development system.
+
 <DirectoryIndex />
@@ -0,0 +1,3 @@
+{
+  "pages": ["quick_start", "custom_image", "app_deployment"]
+}
@@ -1,10 +1,9 @@
 ---
-title: ""
-description: "Quick Setup ###########"
+title: Quick Start
+description: "Get up and running quickly with a pre-configured Buildroot setup for LVGL."
 ---

-Quick Setup
-###########
+# Quick Start

 A Git repository is available that includes everything needed to test the
 Buildroot setup without following the guide. It is intended for testing
@@ -57,4 +56,4 @@ cd output
 make
 ```

-Go to [Flash the image](/integration/embedded_linux/os/buildroot/image_generation) to test the system.
+See the [Flash the image](/integration/embedded_linux/distros/buildroot/custom_image#flash-the-image) section to test the system.
@@ -1,5 +1,5 @@
 ---
-title: OS Support
+title: Distro and OS Support
 ---


@@ -0,0 +1,4 @@
+{
+  "title": "Distro and OS Support",
+  "pages": ["buildroot", "yocto", "torizon"]
+}
@@ -1,5 +1,5 @@
 ---
-title: Torizon OS
+title: Torizon
 description: "Torizon OS is an open-source software platform that aims to simplify the development and maintenance of embedded Linux software."
 ---

@@ -0,0 +1,6 @@
+---
+title: Linux-specific Draw Units
+---
+
+
+<DirectoryIndex />
@@ -0,0 +1,4 @@
+{
+  "title": "Draw Units",
+  "pages": ["draw_nanovg", "draw_opengl", "draw_sdl"]
+}
@@ -1,5 +1,5 @@
 ---
-title: X11 Display/Inputs driver
+title: X11
 description: The X11 display/input driver offers support for simulating the LVGL display and keyboard/mouse inputs in an X11 desktop window.
 ---

@@ -24,34 +24,37 @@ The X11 driver uses XLib to access the linux window manager.
 ### Configure X11 driver

 1. Enable the X11 driver support in lv_conf.h, by cmake compiler define or by KConfig
-    .. code-block:: c
-   
-        #define LV_USE_X11  1
+
+    ```c
+    #define LV_USE_X11  1
+    ```
+
 2. Optional configuration options:
    -  Direct Exit
-        .. code-block:: c
-   
-            #define LV_X11_DIRECT_EXIT  1 /* preferred default - ends the application automatically if last window has been closed */
-            // or
-            #define LV_X11_DIRECT_EXIT  0 /* application is responsible for ending the application (e.g. by own LV_EVENT_DELETE handler */
+
+    ```c
+    #define LV_X11_DIRECT_EXIT  1 /* preferred default - ends the application automatically if last window has been closed */
+    // or
+    #define LV_X11_DIRECT_EXIT  0 /* application is responsible for ending the application (e.g. by own LV_EVENT_DELETE handler) */
+    ```

 -  Double buffering

-```c
-#define LV_X11_DOUBLE_BUFFER  1 /* preferred default */
-// or
-#define LV_X11_DOUBLE_BUFFER  0 /* not recommended */
-```
+    ```c
+    #define LV_X11_DOUBLE_BUFFER  1 /* preferred default */
+    // or
+    #define LV_X11_DOUBLE_BUFFER  0 /* not recommended */
+    ```

 - Render mode

-```c
-#define LV_X11_RENDER_MODE_PARTIAL 1  /* LV_DISPLAY_RENDER_MODE_PARTIAL, preferred default */
-// or
-#define LV_X11_RENDER_MODE_DIRECT  1  /* LV_DISPLAY_RENDER_MODE_DIRECT, not recommended for X11 driver */
-// or
-#define LV_X11_RENDER_MODE_DULL    1  /* LV_DISPLAY_RENDER_MODE_FULL, not recommended for X11 driver */
-```
+    ```c
+    #define LV_X11_RENDER_MODE_PARTIAL 1  /* LV_DISPLAY_RENDER_MODE_PARTIAL, preferred default */
+    // or
+    #define LV_X11_RENDER_MODE_DIRECT  1  /* LV_DISPLAY_RENDER_MODE_DIRECT, not recommended for X11 driver */
+    // or
+    #define LV_X11_RENDER_MODE_DULL    1  /* LV_DISPLAY_RENDER_MODE_FULL, not recommended for X11 driver */
+    ```

 ### Usage

@@ -35,9 +35,10 @@ sudo apt-get install libdrm-dev

 1. Enable the DRM driver support in `lv_conf.h`, by CMake compiler define, or by KConfig:
   
-   .. code-block:: c
-   
-       #define LV_USE_LINUX_DRM   1
+```c
+#define LV_USE_LINUX_DRM   1
+```
+
 2. Link against `libdrm` when building.

 ##### Basic Usage
@@ -1,5 +1,5 @@
 ---
-title: Linux Framebuffer Driver
+title: Linux Framebuffer
 description: "The Linux framebuffer (fbdev) is a linux subsystem used to display graphics. It is a hardware-independent API that gives user space software access to the framebuffer (the part of a computer's vide..."
 ---

@@ -19,12 +19,13 @@ The GLFW driver is a quick way to get started on PC-like platforms.

 ##### Configure GLFW Driver

-1. Required linked libraries: -lGL -lglfw
-2. Enable the OpenGL driver support in lv_conf.h, by cmake compiler define or by KConfig
+1. Required linked libraries: -lglfw
+2. Enable the GLFW driver and Opengles support in `lv_conf.h`, via cmake compiler define or via KConfig
   
-    .. code-block:: c
-   
-        #define LV_USE_OPENGLES  1
+```c
+#define LV_USE_GLFW  1
+#define LV_USE_OPENGLES  1
+```

 ##### Basic Usage

@@ -1,5 +1,5 @@
 ---
-title: OpenGL
+title: OpenGL Driver
 description: The OpenGL display driver is a generic driver that creates textures for embedding LVGL content in other applications. The goal is to create textures that people can embed in other applications.
 ---

@@ -24,9 +24,9 @@ An OpenGL context must be created before using the OpenGL driver. You can create

 1. Enable the OpenGL driver support in lv_conf.h, by cmake compiler define or by KConfig
   
-    .. code-block:: c
-   
-        #define LV_USE_OPENGLES  1
+```c
+#define LV_USE_OPENGLES  1
+```

 ##### Basic Usage

@@ -1,5 +1,5 @@
 ---
-title: Wayland Display/Inputs driver
+title: Wayland
 description: "The Wayland driver provides integration between LVGL and Wayland-based systems, allowing LVGL applications to render directly into a Wayland surface and handle keyboard, mouse and touch input. This..."
 ---

@@ -73,14 +73,15 @@ To enable the EGL backend:

 1. Enable OpenGL ES support in your LVGL configuration:
   
-   .. code-block:: c
-   
-      #define LV_USE_OPENGLES 1
+    ```c
+    #define LV_USE_OPENGLES 1
+    ```
+
 2. Link your application with the `wayland-egl` library (add to your build system):
   
-   .. code-block:: bash
-   
-      -lwayland-egl
+    ```bash
+    -lwayland-egl
+    ```

 **Note:** If your target board has OpenGL ES 2.0 support, this backend can be used with LVGL's 3D rendering
 capabilities for glTF model visualization. See [3D/glTF Support](/integration/embedded_linux/opengl) for details on 3D rendering support.
@@ -106,23 +107,24 @@ To enable the G2D backend:

 1. Enable G2D support in your LVGL configuration:
   
-   .. code-block:: c
-   
-      #define LV_USE_G2D 1
-      #define LV_USE_DRAW_G2D 1
+    ```c
+    #define LV_USE_G2D 1
+    #define LV_USE_DRAW_G2D 1
+    ```
+
 2. Link your application with the `g2d` library (add to your build system):
   
-   .. code-block:: bash
-   
-      -lg2d
+    ```bash
+    -lg2d
+    ```

 ## Configuring the wayland driver

 1. Enable the wayland driver in `lv_conf.h`

-```c
-#define LV_USE_WAYLAND  1
-```
+    ```c
+    #define LV_USE_WAYLAND  1
+    ```

 ## Reference Project

@@ -1,6 +1,52 @@
 ---
 title: Embedded Linux Support
+description: "LVGL runs as a native Linux application and supports a wide range of display backends, input systems, rendering accelerators, and Linux distributions out of the box."
 ---

+## Overview
+
+LVGL supports Linux as a first-class target, running as a standard Linux application without requiring an RTOS. It integrates with the
+display and input infrastructure available on your platform through a modular set of drivers and rendering backends, giving you the
+flexibility to target anything from a minimal framebuffer setup to a fully GPU-accelerated Wayland compositor.
+
+The recommended way to get started is the [lv_port_linux](https://github.com/lvgl/lv_port_linux) reference project. It provides a
+ready-to-build CMake project with the most common drivers pre-configured, and is the fastest path to a running LVGL application on Linux hardware.
+
+## What LVGL supports
+
+### Display and input drivers
+
+LVGL provides drivers for the most common Linux display and input interfaces:
+
+- **[Framebuffer (fbdev)](/integration/embedded_linux/drivers/fbdev)**: the simplest option, works on virtually any Linux system with no compositor required
+- **[DRM/KMS](/integration/embedded_linux/drivers/drm)**: modern direct rendering, recommended for production embedded targets
+- **[Wayland](/integration/embedded_linux/drivers/wayland)**: suitable for systems running a Wayland compositor, with SHM, EGL, and G2D backends. Also useful for development
+- **[X11](/integration/embedded_linux/drivers/X11)**: useful for development and desktop simulation
+- **[EGL](/integration/embedded_linux/drivers/egl)**: hardware-accelerated OpenGL ES rendering, usable via DRM or Wayland
+- **[evdev](/integration/embedded_linux/drivers/evdev) / [libinput](/integration/embedded_linux/drivers/libinput)**: touchscreen, mouse, and keyboard input
+- **[GLFW](/integration/embedded_linux/drivers/glfw)**: cross-platform windowing, primarily for development
+
+### Rendering acceleration
+
+Beyond the CPU-based software renderer, LVGL supports GPU-accelerated draw units on Linux:
+
+- **[NanoVG](/integration/embedded_linux/draw_units/draw_nanovg)** (`draw_nanovg`): GPU-accelerated vector graphics including 3D/glTF support via OpenGL; the recommended default for most use cases, supports all LVGL features
+- **[OpenGL](/integration/embedded_linux/draw_units/draw_opengl)** (`draw_opengl`): direct OpenGL ES rendering, including 3D/glTF support
+- **[SDL](/integration/embedded_linux/draw_units/draw_sdl)** (`draw_sdl`):  SDL2-based rendering
+
+### OS and distribution support
+
+LVGL works with standard Linux distributions and embedded build systems. Dedicated integration guides are available for:
+
+- **[Buildroot](/integration/embedded_linux/distros/buildroot)**: minimal embedded Linux images
+- **[Yocto](/integration/embedded_linux/distros/yocto)**: layer-based embedded Linux build system
+- **[Torizon](/integration/embedded_linux/distros/torizon/torizon)**: container-based embedded Linux platform by Toradex
+
+### Multimedia
+
+LVGL supports hardware-accelerated video playback on Linux through:
+
+- **[FFmpeg](/libs/video_support/ffmpeg)** — video decoding and playback
+- **[GStreamer](/libs/video_support/gstreamer)** — pipeline-based multimedia framework

 <DirectoryIndex />
@@ -1,11 +1,4 @@
 {
  "title": "Embedded Linux Support",
-  "pages": [
-    "opengl",
-    "draw_opengl",
-    "draw_sdl",
-    "nanovg",
-    "os",
-    "drivers"
-  ]
+  "pages": ["opengl", "drivers", "draw_units", "distros"]
 }
@@ -5,17 +5,17 @@ description: "OpenGL (Open Graphics Library) is a cross-platform, hardware-accel

 # Introduction

-### Overview
+## Overview

 OpenGL (Open Graphics Library) is a cross-platform, hardware-accelerated graphics API that provides a standardized interface for rendering 2D and 3D graphics.
 Originally developed by Silicon Graphics in 1992, OpenGL has become one of the most widely adopted graphics APIs across desktop, mobile, and embedded platforms.

-### OpenGL Support in LVGL
+## OpenGL Support in LVGL

 The OpenGL integration consists of two main components:

 - OpenGL Display Drivers: Handle output by showing the LVGL rendered content on the display, window, or texture in OpenGL-based environments
- OpenGL Draw Unit (see [OpenGL Draw Unit](/integration/embedded_linux/draw_opengl)): When enabled, LVGL uses OpenGL for hardware-accelerated rendering operations, including texture caching for improved performance
+- OpenGL Draw Units: When enabled, LVGL uses OpenGL for hardware-accelerated rendering operations.

 OpenGL support addresses several key use cases:

@@ -23,18 +23,8 @@ OpenGL support addresses several key use cases:
 2. Cross-Platform compatibility: OpenGL's wide platform support enables LVGL UIs on desktop, mobile, and embedded systems.
 3. Integration with existing applications: Embed LVGL UI elements into games, visualization tools, or other OpenGL applications.

-### Performance Considerations
-
-The OpenGL implementation provides significant performance benefits in most scenarios:
-
- Best Performance: UIs with static or infrequently changing content benefit most from texture caching
- Moderate Performance: Dynamic content with predictable patterns still sees improvements
- Potential Overhead: Continuously changing content (e.g., random colors every frame) may perform similarly to software rendering
-
 # OpenGL Driver Options

-The following drivers can be used with OpenGL
-
 The following drivers can be used and will automatically create and maintain an OpenGL context.

 - [SDL driver](/integration/pc/sdl)
@@ -50,6 +40,17 @@ and generates textures with hardware acceleration for integration into custom gr

 For complete implementation details, see [OpenGL driver](/integration/embedded_linux/drivers/opengl_driver).

+# OpenGL Draw Unit Options
+
+When one of these draw units is enabled as well as one of the supporting drivers, LVGL will use OpenGL for 
+hardware-accelerated rendering.
+
+- [NanoVG](/integration/embedded_linux/draw_units/draw_nanovg)
+- [OpenGL](/integration/embedded_linux/draw_units/draw_opengl)
+
+[NanoVG](/integration/embedded_linux/draw_units/draw_nanovg) is the recommended choice. It makes better use of the GPU
+and supports more LVGL features. OpenGL is also available but the performance is worse and it supports fewer features.
+
 # 3D/glTF Support

 The glTF module provides support for loading and rendering 3D models using the glTF 2.0 specification within LVGL applications.
@@ -57,10 +58,3 @@ This support requires OpenGL ES 2.0 with some extra extensions and provides comp
 animations, and interactive camera controls for embedded 3D visualization.

 For complete implementation details, see [glTF](/libs/gltf).
-
-# NanoVG Draw Unit
-
-The NanoVG draw unit provides a hardware-accelerated 2D vector graphics rendering backend for LVGL.
-It leverages GPU capabilities for antialiased path rendering, efficient image compositing, and text rendering.
-
-For complete implementation details, see [NanoVG Draw Unit](/integration/embedded_linux/nanovg).
@@ -1,7 +0,0 @@
-{
-  "pages": [
-    "quick_setup",
-    "image_generation",
-    "lvgl_app"
-  ]
-}
@@ -1,8 +0,0 @@
-{
-  "title": "OS Support",
-  "pages": [
-    "buildroot",
-    "yocto",
-    "torizon_os"
-  ]
-}