3 Wayland is an object oriented display protocol, which features request
4 and events. Requests can be seen as method calls on certain objects,
5 whereas events can be seen as signals of an object. This makes the
6 Wayland protocol a perfect candidate for a C++ binding.
8 The goal of this library is to create such a C++ binding for Wayland
9 using the most modern C++ technology currently available, providing
10 an easy to use C++ API to Wayland.
14 To build this library, a recent version of cmake is required. Furthermore,
15 a recent C++ Compiler with C++11 support, such as GCC or clang, is required.
16 Also, pugixml is required to build the XML protocol scanner. Apart from the
17 Wayland libraries, there are no further library dependencies.
19 The documentation is autogenerated using Doxygen, therefore doxygen as
20 well as graphviz is required.
26 To build the library, `cmake ..` needs to executed in a newly created
27 `build` directory in the root directory of the repository, followed
28 by a `make`. After that, `make install` will install the library.
30 There are several CMake variables that can be set in order to
31 customise the build and install process:
33 CMake Variable | Effect
34 ---------------------------- | ------
35 `CMAKE_CXX_COMPILER` | C++ compiler to use
36 `CMAKE_CXX_FLAGS` | Additional flags for the C++ compiler
37 `CMAKE_INSTALL_PREFIX` | Prefix folder, under which everything is installed
38 `CMAKE_INSTALL_LIBDIR` | Library folder relative to the prefix
39 `CMAKE_INSTALL_INCLUDEDIR` | Header folder relative to the prefix
40 `CMAKE_INSTALL_BINDIR` | Binary folder relative to the prefix
41 `CMAKE_INSTALL_DATAROOTDIR` | Shared folder relative to the prefix
42 `CMAKE_INSTALL_DOCDIR` | Documentation folder relative to the prefix
43 `CMAKE_INSTALL_MANDIR` | Manpage folder relative to the prefix
44 `BUILD_SCANNER` | Whether to build the scanner
45 `BUILD_LIBRARIES` | Whether to build the libraries
46 `BUILD_DOCUMENTATION` | Whether to build the documentation
47 `BUILD_EXAMPLES` | Whether to build the examples
48 `INSTALL_UNSTABLE_PROTOCOLS` | Whether to install the unstable protocols
50 The installation root can also be changed using the environment variable
51 `DESTDIR` when using `make install`.
55 If the requirements are met, the documentation will normally be built
56 automatically. HTML pages, LaTeX source files as well as manpages are generated.
58 To build the documentation manually, `doxygen` needs to be executed
59 in the root directory of the repository. The resulting documentation
60 can then be found in the `doc` directory. The required Doxyfile is
61 available after the library has been built. The documentaion is also
62 online availabe [here](https://nilsbrause.github.io/waylandpp_docs/).
66 To build the example programs the `BUILD_EXAMPLES` option needs to be enabled
67 during the build. The resulting binaries will be put under the `example`
68 directory inside the build directory. They can be run directly without
69 installing the library first.
71 To build the example programs manually, `make` can executed in
72 the example directory after the library has been built and installed.
76 In the following, it is assumed that the reader is familiar with
77 basic Wayland concepts and at least version 11 of the C++
82 Each interface is represented by a class. E.g. the `wl_registry`
83 interface is represented by the `registry_t` class.
85 An instance of a class is a wrapper for a Wayland object (a `wl_proxy`
86 pointer). If a copy is made of a particualr instance, both instances
87 refer to the same Wayland object. The underlying Wayland object is
88 destroyed once there are no copies of this object left. Only a few
89 classes are non-copyable, namely `display_t` and `egl_window_t`.
90 There are also special rules for proxy wrappers and the use of
91 foreigen objects. Refer to the documentation for more details.
93 A request to an object of a specific interface corresponds to a method
94 in this class. E.g. to marshal the `create_pool` request on an
95 `wl_shm` interface, the `create_pool()` method of an instance of
96 `shm_t` has to be called:
101 // ... insert the initialisation of the above here ...
102 shm_pool_t shm_pool = shm.create_pool(fd, size);
104 Some methods return newly created instances of other classes. In this
105 example an instance of the class `shm_pool_t` is returned.
107 Events are implemented using function objects. To react to an event, a
108 function object with the correct signature has to be assigned to
109 it. These can not only be static functions, but also member functions
110 or closures. E.g. to react to global events from the registry using a
111 lambda expression, one could write:
113 registry.on_global() = [] (uint32_t name, std::string interface,
115 { std::cout << interface << " v" << version << std::endl; };
117 An example for using member functions can be found in
118 example/opengles.cpp or example/shm.cpp.
120 The Wayland protocol uses arrays in some of its events and requests.
121 Since these arrays can have arbitrary content, they are not directly
122 mapped to a std::vector. Instead there is a new type array_t, which
123 can converted to and from a std::vectory with an user specified type.
126 keyboard.on_enter() = [] (uint32_t serial, surface_t surface,
128 { std::vector<uint32_t> vec = keys; };
132 Instead of proxies the object wrappers of a specific interface are
133 called resources and are represented by a `resource_t` object. They
134 are pretty similar to proxies, as they have events and requests.
136 The server bindings allow the creation of global objects. These can
137 be constructed by prepending `global_` to the class name. They have
138 to be initialised with the display object:
141 global_output_t output(display);
143 Global objects only have a single event called "on_bind", that is
144 called whenever a client binds to this interface. The event then
145 supplies the corresponding resource:
147 output.on_bind() = [this] (client_t client, output_t output) { /* ... */ }
149 A `client_t` object which represents the client connected to the
150 server is also supplied with the bind event.
152 The client and resource objects should be saved for later to be able
153 to identify the exact origin of a request. To help with that, all
154 server-side wrapper classes allow saving of user data through the
155 `user_data()` member which returns a reference to an `any` type.
159 To compile code that using this library, pkg-config can be used to
160 take care of the compiler flags. Assuming the source file is called
161 `foo.cpp` and the executable shall be called `foo` type:
163 $ c++ -c foo.cpp `pkg-config --cflags wayland-client++` -o foo.o
164 $ c++ foo.o `pkg-config --libs wayland-client++` -o foo
166 If the library and headers are installed in the default search paths
167 of the compiler, the linker flag `-lwayland-client++` can also
168 directly be specified on the command line.
170 If the Wayland cursor classes and/or EGL is used, the corresponding
171 libreries `wayland-cursor++` and/or `wayland-egl++` need to be linked
172 in as well. If any extension protocols such as xdg-shell are used,
173 the library `wayland-client-extra++` should be linked in as well,
174 and if the Waylans server bindings are used, the library
175 `wayland-server++` needs to be linked in as well.
177 Further examples can be found in the examples/Makefile.