676296749a
Implement the get_release request of the zwp_surface_synchronization_v1
interface.
This commit implements the zwp_buffer_release_v1 interface. It supports
the zwp_buffer_release_v1.fenced_release event for surfaces rendered by
the GL renderer, and the zwp_buffer_release_v1.immediate_release event
for other cases.
Note that the immediate_release event is safe to be used for surface
buffers used as planes in the DRM backend, since the backend releases
them only after the next page flip that doesn't use the buffers has
finished.
Changes in v7:
- Remove "partial" from commit title and description.
- Fix inverted check when clearing used_in_output_repaint flag.
Changes in v5:
- Use the new, generic explicit sync server error reporting function.
- Introduce and use weston_buffer_release_move.
- Introduce internally and use weston_buffer_release_destroy.
Changes in v4:
- Support the zwp_buffer_release_v1.fenced_release event.
- Support release fences in the GL renderer.
- Assert that pending state buffer_release is always NULL after a
commit.
- Simplify weston_buffer_release_reference.
- Move removal of destroy listener before resource destruction to
avoid concerns about use-after-free in
weston_buffer_release_reference
- Rename weston_buffer_release_reference.busy_count to ref_count.
- Add documentation for weston_buffer_release and ..._reference.
Changes in v3:
- Raise NO_BUFFER for get_release if no buffer has been committed,
don't raise UNSUPPORTED_BUFFER for non-dmabuf buffers,
so get_release works for all valid buffers.
- Destroy the buffer_release object after sending an event.
- Track lifetime of buffer_release objects per commit, independently
of any buffers.
- Use updated protocol interface names.
- Use correct format specifier for resource ids.
Changes in v2:
- Raise UNSUPPORTED_BUFFER at commit if client has requested a
buffer_release, but the committed buffer is not a valid linux_dmabuf.
- Remove tests that are not viable anymore due to our inability to
create dmabuf buffers and fences in a unit-test environment.
Signed-off-by: Alexandros Frantzis <alexandros.frantzis@collabora.com>
Weston
Weston is the reference implementation of a Wayland compositor, as well as a useful environment in and of itself.
Out of the box, Weston provides a very basic desktop, or a full-featured environment for non-desktop uses such as automotive, embedded, in-flight, industrial, kiosks, set-top boxes and TVs. It also provides a library allowing other projects to build their own full-featured environments on top of Weston's core.
The core focus of Weston is correctness and reliability. Weston aims to be lean and fast, but more importantly, to be predictable. Whilst Weston does have known bugs and shortcomings, we avoid unknown or variable behaviour as much as possible, including variable performance such as occasional spikes in frame display time.
A small suite of example or demo clients are also provided: though they can be useful in themselves, their main purpose is to be an example or test case for others building compositors or clients.
If you are after a more mainline desktop experience, the GNOME and KDE projects provide full-featured desktop environments built on the Wayland protocol. Many other projects also exist providing Wayland clients and desktop environments: you are not limited to just what you can find in Weston.
Reporting issues and contributing
Weston's development is hosted on freedesktop.org GitLab. Please also see the contributing document, which details how to make code or non-technical contributions to Weston.
Building Weston
Weston is built using autotools, with autogen.sh and make. It often depends
on the current release versions of
Wayland and
wayland-protocols.
Every push to the Weston master repository and its forks is built using GitLab CI. Reading the configuration may provide a useful example of how to build and install Weston.
More detailed documentation on building Weston is available on the Wayland site. There are also more details on how to run and write tests.
Running Weston
Once Weston is installed, most users can simply run it by typing weston. This
will launch Weston inside whatever environment you launch it from: when launched
from a text console, it will take over that console. When launched from inside
an existing Wayland or X11 session, it will start a 'nested' instance of Weston
inside a window in that session.
Help is available by running weston --help, or man weston, which will list
the available configuration options and display backends. It can also be
configured through a file on disk; more information on this can be found through
man weston.ini.
In some special cases, such as when running remotely or without logind's session
control, Weston may not be able to run directly from a text console. In these
situations, you can instead execute the weston-launch helper, which will gain
privileged access to input and output devices by running as root, then granting
access to the main Weston binary running as your user. Running Weston this way
is not recommended unless necessary.
Libweston
Libweston is an effort to separate the re-usable parts of Weston into a library. Libweston provides most of the boring and tedious bits of correctly implementing core Wayland protocols and interfacing with input and output systems, so that people who just want to write a new "Wayland window manager" (WM) or a small desktop environment (DE) can focus on the WM part.
Libweston was first introduced in Weston 1.12, and is expected to continue evolving through many Weston releases before it achieves a stable API and feature completeness.
API/ABI (in)stability and parallel installability
As libweston's API surface is huge, it is impossible to get it right in one go. Therefore developers reserve the right to break the API/ABI and bump the major version to signify that. For git snapshots of the master branch, the API/ABI can break any time without warning.
Libweston major can be bumped only once during a development cycle. This should happen on the first patch that breaks the API or ABI. Further breaks before the next Weston major.0.0 release do not cause a bump. This means that libweston API and ABI are allowed to break also after an alpha release, up to the final release. However, breaks after alpha should be judged by the usual practices for allowing minor features, fixes only, or critical fixes only.
To make things tolerable for libweston users despite API/ABI breakages, different libweston major versions are designed to be perfectly parallel-installable. This way external projects can easily depend on a particular API/ABI-version. Thus they do not have to fight over which ABI-version is installed in a user's system. This allows a user to install many different compositors each requiring a different libweston ABI-version without tricks or conflicts.
Note, that versions of Weston itself will not be parallel-installable, only libweston is.
For more information about parallel installability, see http://ometer.com/parallel.html
Versioning scheme
In order to provide consistent, easy to use versioning, libweston follows the rules in the Apache Portable Runtime Project http://apr.apache.org/versioning.html.
The document provides the full details, with the gist summed below:
- Major - backward incompatible changes.
- Minor - new backward compatible features.
- Patch - internal (implementation specific) fixes.
Weston and libweston have separate version numbers in configure.ac. All releases are made by the Weston version number. Libweston version number matches the Weston version number in all releases except maybe pre-releases. Pre-releases have the Weston micro version 91 or greater.
A pre-release is allowed to install a libweston version greater than the Weston version in case libweston major was bumped. In that case, the libweston version must be Weston major + 1 and with minor and patch versions zero.
Pkg-config files are named after libweston major, but carry the Weston version number. This means that Weston pre-release 2.1.91 may install libweston-3.pc for the future libweston 3.0.0, but the .pc file says the version is still 2.1.91. When a libweston user wants to depend on the fully stable API and ABI of a libweston major, he should use (e.g. for major 3):
PKG_CHECK_MODULES(LIBWESTON, [libweston-3 >= 3.0.0])
Depending only on libweston-3 without a specific version number still allows pre-releases which might have different API or ABI.
Forward compatibility
Inspired by ATK, Qt and KDE programs/libraries, libjpeg-turbo, GDK, NetworkManager, js17, lz4 and many others, libweston uses a macro to restrict the API visible to the developer - REQUIRE_LIBWESTON_API_VERSION.
Note that different projects focus on different aspects - upper and/or lower version check, default to visible/hidden old/new symbols and so on.
libweston aims to guard all newly introduced API, in order to prevent subtle breaks that a simple recompile (against a newer version) might cause.
The macro is of the format 0x$MAJOR$MINOR and does not include PATCH version. As mentioned in the Versioning scheme section, the latter does not reflect any user visible API changes, thus should be not considered part of the API version.
All new symbols should be guarded by the macro like the example given below:
#if REQUIRE_LIBWESTON_API_VERSION >= 0x0101
bool weston_ham_sandwich(void);
#endif
In order to use the said symbol, the one will have a similar code in their configure.ac:
PKG_CHECK_MODULES(LIBWESTON, [libweston-1 >= 1.1]) AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101])
If the user is not interested in forward compatibility, they can use 0xffff or similar high value. Yet doing so is not recommended.
Libweston design goals
The high-level goal of libweston is to decouple the compositor from the shell implementation (what used to be shell plugins).
Thus, instead of launching 'weston' with various arguments to choose the shell, one would launch the shell itself, e.g. 'weston-desktop', 'weston-ivi', 'orbital', etc. The main executable (the hosting program) will implement the shell, while libweston will be used for a fundamental compositor implementation.
Libweston is also intended for use by other project developers who want to create new "Wayland WMs".
Details:
-
All configuration and user interfaces will be outside of libweston. This includes command line parsing, configuration files, and runtime (graphical) UI.
-
The hosting program (main executable) will be in full control of all libweston options. Libweston should not have user settable options that would work behind the hosting program's back, except perhaps debugging features and such.
-
Signal handling will be outside of libweston.
-
Child process execution and management will be outside of libweston.
-
The different backends (drm, fbdev, x11, etc) will be an internal detail of libweston. Libweston will not support third party backends. However, hosting programs need to handle backend-specific configuration due to differences in behaviour and available features.
-
Renderers will be libweston internal details too, though again the hosting program may affect the choice of renderer if the backend allows, and maybe set renderer-specific options.
-
plugin design ???
-
xwayland ???
-
weston-launch is still with libweston even though it can only launch Weston and nothing else. We would like to allow it to launch any compositor, but since it gives by design root access to input devices and DRM, how can we restrict it to intended programs?
There are still many more details to be decided.
For packagers
Always build Weston with --with-cairo=image.
The Weston project is (will be) intended to be split into several binary packages, each with its own dependencies. The maximal split would be roughly like this:
-
libweston (minimal dependencies):
- headless backend
- wayland backend
-
gl-renderer (depends on GL libs etc.)
-
drm-backend (depends on libdrm, libgbm, libudev, libinput, ...)
-
x11-backend (depends of X11/xcb libs)
-
xwayland (depends on X11/xcb libs)
-
fbdev-backend (depends on libudev...)
-
rdp-backend (depends on freerdp)
-
weston (the executable, not parallel-installable):
- desktop shell
- ivi-shell
- fullscreen shell
- weston-info, weston-terminal, etc. we install by default
- screen-share
-
weston demos (not parallel-installable)
- weston-simple-* programs
- possibly all the programs we build but do not install by default
-
and possibly more...
Everything should be parallel-installable across libweston major ABI-versions (libweston-1.so, libweston-2.so, etc.), except those explicitly mentioned.
Weston's build may not sanely allow this yet, but this is the intention.