查看“Wayland Weston overview”的源代码

This article gives information about the Linux<sup>&reg;</sup> Wayland/Weston framework.
It explains how to configure it and, based on examples, how to use it.

== Framework purpose ==
The '''Wayland/Weston'''<ref name="wayland">http://wayland.freedesktop.org</ref> framework is dedicated to the management of the displays, including the composition<ref name="compositor">[https://en.wikipedia.org/wiki/Compositing_window_manager Compositing window manager or Compositor (Wikipedia)]</ref> of their contents, the support of their related input device events (touchscreen, mouse, keyboard...) and their settings (background wallpapers, resolutions, multi-screens...):
* '''Wayland'''<ref name="wayland_wikipedia">[https://en.wikipedia.org/wiki/Wayland_(display_server_protocol) Wayland display server protocol (Wikipedia)]</ref> is a protocol that specifies the communication between a display server and its clients. Wayland is intended as a simpler replacement for the X Window system<ref name="x11">[https://en.wikipedia.org/wiki/X_Window_System X Window System (Wikipedia)]</ref>, easier to develop and maintain.
* '''Weston''' is the reference implementation of a Wayland compositor that is a display server using the Wayland protocol. Weston is a minimal and fast compositor and is suitable for many embedded and mobile use cases. 

The purpose of this article is to provide a quick overview of the Wayland/Weston framework, giving some hints on how to use and configure Weston and some external references to better understand the Wayland/Weston structure.

== System overview ==
[[File:Wayland_Weston_overview.png|center|800px|link=|alt=Alternate text|Wayland/Weston framework]]

=== Component description ===
''From Application/Middleware to Hardware''
* '''Application/Middleware''' (User space): The Wayland client application or middleware relying on the Wayland protocol. This client can be traditional applications or middleware, X servers (rootless or fullscreen) or other display servers.
* '''Wayland/Weston''' (User space): The Wayland libraries implementing the Wayland display server protocol and the Weston libraries using this Wayland protocol for implementing the display server running on the [[DRM KMS overview | Linux Kernel Mode Setting (KMS)]], the composition based on [[OpenGLES overview | OpenGLES]] and [[DRM KMS overview | Direct Rendering Manager (DRM)]] and the management of Linux input devices.
* '''OpenGLES''' (User space): The [[OpenGLES overview | OpenGLES]] libraries used by Weston for the GPU-based composition.
* '''libdrm/libkms''' (User space): The libdrm and libkms libraries are used by the Weston compositor to configure the display path and refresh the display content.
* '''GPU driver''' (Kernel space): The Linux kernel driver used to transfer OpenGLES commands to the [[GPU_internal_peripheral | GPU hardware block]].
* '''DRM/KMS driver''' (Kernel Space): The [[DRM KMS overview | DRM/KMS]] Linux kernel driver to access the [[LTDC_internal_peripheral | display hardware block]].
* '''GPU''' (Hardware): The [[GPU_internal_peripheral | GPU hardware block]].
* '''Display''' (Hardware): The [[LTDC_internal_peripheral | display hardware block]].
* '''LCD device''' (Hardware): The physical [[:Category:Display hardware components|LCD device]] to display contents.

=== API description ===
The Wayland protocol API is described in the official Wayland documentation https://wayland.freedesktop.org/docs/html .

== Configuration ==
The '''/etc/xdg/weston/weston.ini''' file allows the user to set its Weston shell look and behaviour preferences.

In this file you will be able to configure:
* the shell appearance:
** deactivation of the panel bar  using panel-location variable
** color of the panel bar using panel-color variable
** background color using background-color variable
** background image using background-image variable
** keyboard layout (qwerty, azerty...) using keymap_layout variable (''us'', ''fr''...)
** ...
* the animation during transition (to enable if GPU is supported)
* the launcher bar by adding some icons and associated script
* the display output (HDMI, DSI, DVO, LVDS, ...)


Please refer to the '''Ubuntu weston.ini manpage'''<ref name="weston.ini">[http://manpages.ubuntu.com/manpages/cosmic/man5/weston.ini.5.html Ubuntu weston.ini manpage]</ref> to know how to configure it.

You may want also to configure:
* the Weston screen resolution: [[How to configure Weston screen resolution]].
* the Weston keyboard layout: [[How to configure the Weston keyboard layout]].

== How to use the framework ==
=== Start Weston ===
Weston is automatically started at boot by ''systemd'' using '''/lib/systemd/system/weston.service'''.

You can plug a keyboard and a mouse on the board and enjoy the Weston desktop mode.

To start/stop or enable/disable the Weston service, please refer to [[How to stop and start Weston]] article.

=== Weston utilities ===
Once Weston is started you can launch simple Wayland client examples.

Here below some interesting utilities...

==== Display some images ====
{{Info|Don't have an image ? [[Template:Image_ref_file#Download_this_file| Download one here]]}}

{{highlight|weston-image}} utility decodes and displays in Wayland window image contents:
 {{Board$}} weston-image <file(s)>

Variety of image types are supported such as jpeg, png or webp. If the image is bigger than display, the image is resized transparently. Several files can be given in argument, one window being opened per file:
 {{Board$}} weston-image {{image_ref_file}} {{image_ref_file}}

[[File:weston-image-screenshot.png|center|480px|link=]]

==== Embedded terminal ====
{{highlight|weston-terminal}} opens a new Wayland window with a terminal session. Connect a keyboard and a mouse and you can use your board as an autonomous personal computer.

Start first a Weston terminal session using your PC console:
 {{Board$}} weston-terminal

Then switch to keyboard connected to board and type:
 '''Wayland Terminal$>''' weston-image {{image_ref_file}}
[[File:weston-terminal-screenshot.png|center|480px|link=]]

====  OpenGLES application ====
{{highlight|weston-simple-egl}} aims to check that GPU is up & running and well integrated within the Wayland/Weston system. It opens a new alpha transparent Wayland window with a rotating colorized triangle.

 {{Board$}} weston-simple-egl
<pre>
has EGL_EXT_buffer_age and EGL_EXT_swap_buffers_with_damage
244 frames in 5 seconds: 48.799999 fps
242 frames in 5 seconds: 48.400002 fps
</pre>
[[File:weston-simple-egl-screenshot.png|center|480px|link=]]

Other options are available, check usage below:
 {{Board$}} weston-simple-egl -h
<pre>
Usage: simple-egl [OPTIONS]

  -f    Run in fullscreen mode
  -o    Create an opaque surface
  -s    Use a 16 bpp EGL config
  -b    Don't sync to compositor redraw (eglSwapInterval 0)
  -h    This help text
</pre>

==== Make screen or video capture ====
Please refer to the following articles:
* [[How to make a screen capture in Weston]]
* [[How to make a video capture of Weston desktop]]

==== List of Weston utilities ====
Client example binaries location:
 {{Board$}} ls -1 /usr/bin/weston*
<pre>
/usr/bin/weston
/usr/bin/weston-calibrator
/usr/bin/weston-clickdot
/usr/bin/weston-cliptest
/usr/bin/weston-confine
/usr/bin/weston-dnd
/usr/bin/weston-editor
/usr/bin/weston-eventdemo
/usr/bin/weston-flower
/usr/bin/weston-fullscreen
/usr/bin/weston-image
/usr/bin/weston-info
/usr/bin/weston-launch
/usr/bin/weston-multi-resource
/usr/bin/weston-presentation-shm
/usr/bin/weston-resizor
/usr/bin/weston-scaler
/usr/bin/weston-simple-damage
/usr/bin/weston-simple-dmabuf-v4l
/usr/bin/weston-simple-egl
/usr/bin/weston-simple-shm
/usr/bin/weston-simple-touch
/usr/bin/weston-smoke
/usr/bin/weston-stacking
/usr/bin/weston-start
/usr/bin/weston-subsurfaces
/usr/bin/weston-terminal
/usr/bin/weston-transformed
</pre>

=== Wayland "Hello World" ===
You can find various Wayland "Hello World" applications on internet. We suggest to browse:
* https://jan.newmarch.name/Wayland/index.html (contains EGL, Cairo, GTK, Qt and SDL Wayland examples)
* https://github.com/emersion/hello-wayland
* https://gitlab.com/hdante/hello_wayland


You can refer to the official Wayland documentation: https://wayland.freedesktop.org/docs/html/index.html

== How to trace and debug the framework == 
To debug weston and enable log traces, please refer to [[How to debug Weston]] article.

== Source code location ==
* [https://cgit.freedesktop.org/wayland/wayland/ Core Wayland protocol source code]
* [https://cgit.freedesktop.org/wayland/wayland-protocols Additional Wayland protocols source code]
* [https://cgit.freedesktop.org/wayland/weston Weston compositor source code]

== To go further ==
You can find a good overview of the Wayland/Weston implementation in the '''Wayland/Weston overview chapter''' of the
presentation held at the 2015 Automotive Linux Summit: [http://events.linuxfoundation.org/sites/events/files/slides/als2015_wayland_weston_v2.pdf  Using Linux Media Controller for Wayland/Weston Renderer]

You can refer to the official Wayland documentation: https://wayland.freedesktop.org/docs/html/index.html

== References ==
<references />

<noinclude>
{{ArticleBasedOnModel | Framework overview article model}}
{{PublicationRequestId | 10153 | 2019-01-03 | AlainF}}

[[Category:Wayland Weston]]
</noinclude>