En esta página

Qt Wayland Compositor

El módulo « Qt Wayland Compositor » proporciona unas API de QML y C++ prácticas y potentes para desarrollar servidores de pantalla personalizados basados en el protocolo Wayland. El servidor de pantalla, a menudo denominado «compositor», muestra el contenido de las aplicaciones cliente compatibles con el protocolo Wayland.

La filosofía de diseño de Wayland consiste en mantener el protocolo básico sencillo y minimalista. De este modo, los desarrolladores pueden ampliar este protocolo básico con extensiones específicas para cada caso de uso. Qt Wayland Compositor admite muchas extensiones comunes de forma predeterminada y también cuenta con API que permiten la creación de nuevas extensiones personalizadas.

Normalmente, un compositor escrito con Qt Wayland Compositor se convierte en un subsistema dentro de un proceso de gestión de aplicaciones más amplio. Qt Wayland Compositor proporciona las API para comunicarse con los clientes y mostrar su contenido en pantalla. Las API de Qt Qml contienen interfaces de alto nivel que se integran fácilmente con el resto de Qt, lo que permite crear animaciones, efectos y una interfaz de usuario cómodos a través de Qt Quick. También hay disponibles API en C++, en caso de que se necesite un acceso de más bajo nivel.

Un gestor de aplicaciones suele implementar características adicionales, como el ciclo de vida de las aplicaciones, la entrada mediante teclado virtual, la seguridad y la comunicación entre procesos (IPC). Qt proporciona las API que se pueden utilizar para desarrollar el resto de componentes de un gestor de aplicaciones en otros módulos. De hecho, Qt también ofrece Qt Application Managerun gestor de aplicaciones completo que incluye una API QML de nivel superior basada en Qt Wayland Compositor para implementar un compositor personalizado.

Para obtener más información sobre Wayland, consulta Wayland y Qt.

Características de Qt Wayland Compositor

Qt Wayland Compositor incluye las características necesarias para crear un compositor:

  • Una API de QML para mostrar y manipular el contenido del cliente, totalmente integrada con todas las características de Qt Quick.
  • Una API de C++ para el acceso y el control de bajo nivel.
  • Compatibilidad con extensiones comunes, como XDG Shell y IVI Application.
  • API para ampliar fácilmente la compatibilidad con extensiones personalizadas.

Variables de entorno y argumentos de línea de comandos

A continuación se muestra una lista incompleta de las variables de entorno y los argumentos de línea de comandos que reconoce Qt Wayland Compositor:

  • Variables de entorno:
    • QT_WAYLAND_HARDWARE_INTEGRATION Define las integraciones del búfer del cliente (hardware) que debe ofrecer el compositor. Acepta una lista separada por punto y coma (p. ej., «linux-dmabuf-unstable-v1;wayland-egl»).
    • QT_WAYLAND_CLIENT_BUFFER_INTEGRATION Es igual que QT_WAYLAND_HARDWARE_INTEGRATION (que tiene prioridad) para el compositor, pero también es evaluada por los clientes. Los clientes solo aceptan una única integración.
    • QT_IVI_SURFACE_ID Especifica el identificador de superficie IVI para la superficie del cliente en entornos IVI-compositor.
  • Argumentos de la línea de comandos:
    • --wayland-socket-name <name> Anula el nombre de socket predeterminado utilizado para comunicarse con los clientes.

Ejecución del compositor Wayland

Siempre que no dependa de ninguna característica específica de la plataforma que no esté disponible, el compositor se puede probar fácilmente en un sistema de escritorio basado en X11. Esto puede resultar útil durante el desarrollo, tanto para simplificar la depuración como para acelerar la puesta a prueba de nuevas funciones.

Qt Wayland admite varios backends para compartir búferes gráficos entre los clientes y el servidor. El principal es:

  • wayland-egl: Este es el backend predeterminado y debe utilizarse siempre que sea posible. Para que funcione, es necesario que el controlador OpenGL del sistema lo admita.

Se pueden seleccionar otros backends configurando la variable de entorno ` QT_WAYLAND_HARDWARE_INTEGRATION `.

Nota: Si Qt Wayland Compositor no puede inicializar el backend de búfer del cliente, recurrirá al backend de «memoria compartida» (basado en wl_shm) como medida de seguridad. Este backend utilizará la memoria de la CPU para compartir los búferes gráficos y copiará los datos de un lado a otro según sea necesario. Esto tiene implicaciones en el rendimiento, especialmente en pantallas de alta densidad y con hardware gráfico limitado. Al investigar problemas de rendimiento con Qt Wayland Compositor, empieza por comprobar que se utiliza la integración correcta del búfer de cliente.

Ten en cuenta también que, si tu sistema ya ejecuta un compositor Wayland, es posible que tengas que configurar XDG_RUNTIME_DIR para que apunte a una ubicación diferente. Si este es el caso, aparecerán advertencias al iniciar el compositor. El XDG_RUNTIME_DIR puede apuntar a cualquier ubicación accesible que no esté ya en uso.

Por ejemplo, si quieres ejecutar el ejemplo «fancy-compositor» con el backend « linux-dmabuf-v1 », podrías utilizar la siguiente línea de comandos:

% XDG_RUNTIME_DIR=~/my_temporary_runtime QT_XCB_GL_INTEGRATION=xcb_egl QT_WAYLAND_HARDWARE_INTEGRATION=linux-dmabuf-v1 ./fancy-compositor

Posteriormente, el cliente se puede ejecutar en el compositor configurando el mismo XDG_RUNTIME_DIR y pasando «-platform wayland» como argumento de la línea de comandos. La variable de entorno QT_QPA_PLATFORM también se puede utilizar para seleccionar el complemento QPA de Wayland en el lado del cliente.

Nota: En la mayoría de los casos, el cliente se adaptará al mismo OpenGL que el servidor cuando se conecte. Sin embargo, al ejecutarse con el backend EGL en algunos controladores específicos, es necesario que la inicialización se realice antes. Si te encuentras con este problema, puedes pasar «-platform wayland-egl» en su lugar para preinicializar el cliente en EGL.

Resolución de problemas

A veces, al desarrollar un compositor complejo, pueden surgir problemas que requieran una investigación más profunda.

Establecer la variable de entorno ` WAYLAND_DEBUG ` en «1» habilitará la salida de registros de la propia biblioteca Wayland. Esto puede resultar muy útil, por ejemplo, al depurar extensiones personalizadas del protocolo Wayland. Te mostrará exactamente qué eventos y solicitudes se transmiten entre el cliente y el servidor, así como las marcas de tiempo correspondientes.

Además, Qt dispone de las categorías de registro qt.waylandcompositor.* y qt.qpa.wayland.* para habilitar registros adicionales. Esta última debe configurarse en el lado del cliente, ya que habilita el registro desde el complemento QPA de Wayland.

Ejemplos

Echa un vistazo a los ejemplos deQt Wayland Compositor para aprender cómo se pueden utilizar estas API para escribir compositores personalizados.

Referencia de la API

Qt Wayland Compositor se puede utilizar desde C++ o QML:

Además, el módulo proporciona la función de CMake qt_generate_wayland_protocol_server_sources().

Evolución del módulo

La página«Porting to Qt 6 - Qt Wayland Compositor » enumera los cambios importantes en la API y la funcionalidad del módulo que se han realizado para la serie Qt 6 de Qt.

Licencias y atribuciones

Qt Wayland Compositor y el complemento de integración de Qt Wayland están disponibles bajo licencias comerciales de The Qt Company.

Además, Qt Wayland Compositor está disponible bajo la Licencia Pública General de GNU, versión 3, mientras que el complemento de integración de Qt Wayland está disponible bajo la Licencia Pública General Reducida de GNU, versión 3, o la Licencia Pública General de GNU, versión 2.

Consulte Licencias de Qt para obtener más detalles.

Qt Wayland Compositor y el complemento de integración Qt Wayland utilizan definiciones de protocolo bajo las siguientes licencias permisivas:

Presentation Time Protocol, version 1

Licencia MIT

Wayland Color Management Protocol, version 1

Licencia MIT

Wayland Dialog Protocol, version 1

Licencia MIT

Wayland EGLStream Controller Protocol, version 1.1.1

Licencia MIT

Wayland Fractional Scale Protocol, version 1

Licencia MIT

Wayland Fullscreen Shell Protocol, version unstable v1

Licencia MIT

Wayland IVI Extension Protocol, version 1.9.1

Licencia MIT

Wayland KDE DBus Menu Protocol, version 1

Licencia Pública General Reducida de GNU 2.1 o posterior

Wayland Linux Dmabuf Unstable V1 Protocol, version unstable v1, version 3

Licencia MIT

Wayland Linux Dmabuf V1 Protocol, version v1, version 5

Licencia MIT

Wayland Pointer Gestures Protocol, version unstable v1, version 2

Licencia MIT

Wayland Pointer Warp Protocol, version version 1

Licencia MIT

Wayland Primary Selection Protocol, version 1

Licencia MIT

Wayland Protocol, version 1.24.0

Licencia MIT

Wayland Scaler Protocol, version 2

Licencia MIT

Wayland Session Management Protocol, version experimental V1

Licencia MIT

Wayland Tablet Protocol, version unstable v2, version 1

Licencia MIT

Wayland Text Input Protocol v1, version unstable v1

Licencia MIT

Wayland Text Input Protocol v2, version unstable v2

Licencia HPND

Wayland Text Input Protocol, version unstable v3

Licencia MIT

Wayland Viewporter Protocol, version 1

Licencia MIT

Wayland XDG Foreign Protocol, version 1

Licencia MIT

Wayland XDG Output Protocol, version unstable v1, version 3

Licencia MIT

Wayland XDG Shell Protocol, version 1.18

Licencia MIT

Wayland XDG System Bell Protocol, version 1.18

Licencia MIT

Wayland xdg-activation Protocol, version unstable v1, version 1

Licencia MIT

Wayland xdg-decoration Protocol, version unstable v1, version 1

Licencia MIT

Wayland xdg-toplevel-icon Protocol, version version 1

Licencia MIT

Wlr Data Control Unstable V1 Protocol, version 2

Licencia MIT

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.