Mirrors_UI_SDK/lvgl
1
0
Fork 0
mirror of https://github.com/lvgl/lvgl.git synced 2026-05-28 05:26:18 +08:00
Code Issues Actions 82 Packages Projects Releases Wiki Activity

feat(wayland): rewrite driver (#9195)

Browse Source 
Co-authored-by: ychsiao168 <ychsiao168@pm.me>
This commit is contained in:
André Costa
2025-12-01 18:02:27 +01:00
committed by GitHub
parent 5cf3c8e887
commit 6cd095724e
31 changed files with 2295 additions and 4358 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/integration/embedded_linux/drivers/wayland.rst
+130 -73
View File
@@ -4,20 +4,22 @@
Wayland Display/Inputs driver
=============================
Overview
--------
********
The **Wayland** `driver <https://github.com/lvgl/lvgl/tree/master/src/drivers/wayland>`__
offers support for simulating the LVGL display and keyboard/mouse inputs in a desktop
window.
The Wayland `driver <https://github.com/lvgl/lvgl/tree/master/src/drivers/wayland>`__ 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 makes it suitable
for production deployments, such as kiosk interfaces, control panels, or other embedded GUIs where Wayland is the display server.
In addition to production use, the driver is also useful for development on linux desktop environments, offering a convenient way to simulate and validate
your LVGL applications without dedicated hardware. It serves as an alternative to the X11 and SDL2 drivers.
It is an alternative to **X11** or **SDL2**
The main purpose for this driver is for testing/debugging the LVGL application. It can
also be used to run applications in "kiosk mode".
Dependencies
------------
************
The wayland driver requires some dependencies.
@@ -34,8 +36,64 @@ On Fedora
sudo dnf install wayland-devel libxkbcommon-devel wayland-utils wayland-protocols-devel
Rendering Backends
******************
The Wayland driver supports multiple rendering backends, allowing you to choose the most appropriate rendering method for your hardware and use case.
SHM Backend (Default)
---------------------
The **SHM (Shared Memory)** backend is the default rendering backend used by the Wayland driver.
It uses Wayland's shared memory protocol (``wl_shm``) for rendering, which is supported across all Wayland compositors.
**Features:**
* Double-buffered direct rendering
* Universal compatibility with all Wayland compositors
* No special hardware requirements
**Limitations:**
* Rotation is not currently supported
**Usage:**
The SHM backend is enabled by default and requires no additional configuration.
G2D Backend
-----------
The G2D backend leverages NXP's hardware-accelerated 2D graphics engine available on i.MX processors. This backend provides improved performance on NXP platforms.
**Features:**
* Hardware-accelerated rendering
* Double-buffered direct rendering
* Rotation support (0°, 90°, 180°, 270°)
**Requirements:**
* Hardware with G2D support (e.g., NXP i.MX6/i.MX8 series)
* G2D library and drivers installed on the system
**Usage:**
Enable the G2D backend in ``lv_conf.h``:
.. code:: c
#define LV_USE_DRAW_G2D 1
When ``LV_USE_DRAW_G2D`` is enabled, the Wayland driver will automatically use the G2D backend instead of the default SHM backend.
Configuring the wayland driver
------------------------------
******************************
1. Enable the wayland driver in ``lv_conf.h``
@@ -43,46 +101,18 @@ Configuring the wayland driver
#define LV_USE_WAYLAND 1
2. Optional configuration options:
Some optional settings depend on whether DMA buffer support is enabled (`LV_WAYLAND_USE_DMABUF`). The table below summarizes valid combinations and limitations:
.. list-table:: Configuration possibilities
:widths: 50 25 25
:header-rows: 1
Reference Project
*****************
* - Configuration Option
- Without DMABUF
- With DMABUF
`LVGL Linux port <https://github.com/lvgl/lv_port_linux/>`__ serves as a reference project for setting up wayland. It uses CMake to generate
the required protocols at build time.
* - `LV_DRAW_USE_G2D`
- Not required
- **Required**
* - `LV_WAYLAND_BUF_COUNT`
- `1`
- `1` or `2`
* - `LV_WAYLAND_RENDER_MODE`
- `LV_DISPLAY_RENDER_MODE_PARTIAL`
- `LV_DISPLAY_RENDER_MODE_DIRECT` or `LV_DISPLAY_RENDER_MODE_FULL`
* - `LV_WAYLAND_WINDOW_DECORATIONS`
- `1` or `0`
- `0`
Additional notes
* DMABUF support (`LV_WAYLAND_USE_DMABUF`) improves performance and enables more render modes but has specific requirements and restrictions.
* `LV_WAYLAND_WINDOW_DECORATIONS` is only required for some compositors (e.g., GNOME/Mutter or Weston).
Example
-------
An example simulator is available in this `repo <https://github.com/lvgl/lv_port_linux/>`__
Usage
-----
Getting started
***************
#. In ``main.c`` ``#include "lv_drivers/wayland/wayland.h"``
#. Enable the Wayland driver in ``lv_conf.h`` with ``LV_USE_WAYLAND 1``
@@ -113,14 +143,29 @@ Handles for input devices of each display can be obtained using
``lv_wayland_get_indev_keyboard()``, ``lv_wayland_get_indev_touchscreen()``,
``lv_wayland_get_indev_pointer()`` and ``lv_wayland_get_indev_pointeraxis()`` respectively.
Fullscreen mode
^^^^^^^^^^^^^^^
---------------
To programmatically fullscreen the window, use the ``lv_wayland_window_set_fullscreen()``
function respectively with ``true`` or ``false`` for the ``fullscreen`` argument.
Maximized mode
--------------
To programmatically maximize the window,
use the ``lv_wayland_window_set_maximized()`` function respectively with ``true``
or ``false`` for the ``maximized`` argument.
Minimize window
---------------
To programmatically minimize the window, use the ``lv_wayland_window_set_minimized()`` function.
Physical display assignment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---------------------------
When using multiple physical displays, you can control which display a fullscreen window
appears on by assigning it to a specific physical display before entering fullscreen mode.
@@ -142,12 +187,6 @@ To remove the physical display assignment and return to default behavior, use
lv_wayland_unassign_physical_display(disp);
Maximized mode
^^^^^^^^^^^^^^
To programmatically maximize the window,
use the ``lv_wayland_window_set_maximized()`` function respectively with ``true``
or ``false`` for the ``maximized`` argument.
Custom timer handler
@@ -164,22 +203,15 @@ Wrapping the call to ``lv_timer_handler()`` is a necessity to have more control
when the LVGL flush callback is called.
Building the wayland driver
---------------------------
***************************
An example simulator is available in this `repo <https://github.com/lvgl/lv_port_linux/>`__
The `reference project <https://github.com/lvgl/lv_port_linux/>`__ uses CMakeLists to generate the necessary dependencies at build time.
If there is a need to use driver with another build system. The source and header files for the XDG shell
must be generated from the definitions for the XDG shell protocol.
Mainly, the project generates the necessary protocols with the ``wayland-scanner`` utility.
In the example CMake is used to perform the operation by invoking the ``wayland-scanner`` utility
The wayland protocols are defined using XML files which are present in ``/usr/share/wayland-protocols``
To achieve this manually,
Make sure the dependencies listed at the start of the article are installed.
The wayland protocol is defined using XML files which are present in ``/usr/share/wayland-protocols``
To generate the required files run the following commands:
By default, LVGL relies on the ``xdg-shell`` protocol for window management to generate it run the following commands:
.. code-block:: sh
@@ -198,19 +230,45 @@ The resulting files can then be integrated into the project, it's better to re-r
each build to ensure that the correct versions are generated, they must match the version of the ``wayland-client``
dynamically linked library installed on the system.
Current state and objectives
----------------------------
* Add direct rendering mode
* Refactor the shell integrations to avoid excessive conditional compilation
* Technically, the wayland driver allows to create multiple windows - but this feature is experimental.
* Eventually add enhanced support for XDG shell to allow the creation of desktop apps on Unix-like platforms,
similar to what the win32 driver does.
* Add a support for Mesa, currently wl_shm is used and it's not the most effective technique.
Window Decorations
******************
.. note::
As of LVGL v9.5, the `LV_WAYLAND_WINDOW_DECORATIONS` option has been removed.
Window decorations (title bars, borders, close buttons, etc.) are now the responsibility of the application developer, not LVGL.
This change gives you full control over the appearance and behavior of your window decorations.
Creating Window Decorations
---------------------------
You can create your own window decorations using LVGL widgets. For example, use the :ref:`lv_win` widget to add a title bar with buttons,
or build custom decorations from basic widgets like containers, labels, and buttons.
This approach allows you to:
- Design decorations that match your application's style
- Add custom controls and functionality
- Maintain consistent UI across different Wayland compositors
- Have complete control over the look and feel
For applications that don't need decorations (fullscreen, kiosk mode, etc.), simply create your UI without them.
Current state and objectives
****************************
* EGL Support
* Server-side window decorations
* Rotation support for the SHM backend
Bug reports
-----------
***********
The wayland driver is currently under construction, bug reports, contributions and feedback are always welcome.
@@ -226,4 +284,3 @@ This will create a log file called ``debug`` in the ``/tmp`` directory, copy-pas
The log file contains LVGL logs and the wayland messages.
Be sure to replicate the problem quickly otherwise the logs become too big