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 Apart from the Wayland libraries, there are no further library dependencies.
18 The documentation is autogenerated using Doxygen, therefore doxygen as
19 well as graphviz is required.
25 To build the library, `cmake ..` needs to executed in a newly created
26 `build` directory in the root directory of the repository, followed
27 by a `make`. After that, `make install` will install the library.
29 There are several CMake variables that can be set in order to
30 customise the build and install process:
32 CMake Variable | Effect
33 --------------------------- | ------
34 `CMAKE_CXX_COMPILER` | C++ compiler to use
35 `CMAKE_CXX_FLAGS` | Additional flags for the C++ compiler
36 `CMAKE_INSTALL_PREFIX` | Prefix folder, under which everything is installed
37 `CMAKE_INSTALL_LIBDIR` | Library folder relative to the prefix
38 `CMAKE_INSTALL_INCLUDEDIR` | Header folder relative to the prefix
39 `CMAKE_INSTALL_BINDIR` | Binary folder relative to the prefix
40 `CMAKE_INSTALL_DATAROOTDIR` | Shared folder relative to the prefix
41 `CMAKE_INSTALL_DOCDIR` | Dcoumentation folder relative to the prefix
42 `CMAKE_INSTALL_MANDIR` | Manpage folder relative to the prefix
43 `BUILD_SCANNER` | Whether to build the scanner
44 `BUILD_LIBRARIES` | Whether to build the libraries
45 `BUILD_DOCUMENTATION` | Whether to build the documentation
46 `BUILD_EXAMPLES` | Whether to build the examples
48 The installation root can also be changed using the environment variable
49 `DESTDIR` when using `make install`.
53 If the requirements are met, the documentation will normally be built
54 automatically. HTML pages, LaTeX source files as well as manpages are generated.
56 To build the documentation manually, `doxygen` needs to be executed
57 in the root directory of the repository. The resulting documentation
58 can then be found in the `doc` directory. The required Doxyfile is
59 available after the library has been built. The documentaion is also
60 online availabe [here](http://nilsbrause.de/waylandpp/).
64 To build the example programs the `BUILD_EXAMPLES` option needs to be enabled
65 during the build. The resulting binaries will be put under the `example`
66 directory inside the build directory. They can be run directly without
67 installing the library first.
69 To build the example programs manually, `make` can executed in
70 the example directory after the library has been built and installed.
74 In the following, it is assumed that the reader is familiar with
75 basic Wayland concepts and at least version 11 of the C++
78 Each interface is represented by a class. E.g. the `wl_registry`
79 interface is represented by the `registry_t` class.
81 An instance of a class is a wrapper for a Wayland object (a `wl_proxy`
82 pointer). If a copy is made of a particualr instance, both instances
83 refer to the same Wayland object. The underlying Wayland object is
84 destroyed once there are no copies of this object left. Only a few
85 classes are non-copyable, namely `display_t` and `egl_window_t`.
86 There are also special rules for proxy wrappers and the use of
87 foreigen objects. Refer to the documentation for more details.
89 A request to an object of a specific interface corresponds to a method
90 in this class. E.g. to marshal the `create_pool` request on an
91 `wl_shm` interface, the `create_pool()` method of an instance of
92 `shm_t` has to be called:
97 // ... insert the initialisation of the above here ...
98 shm_pool_t shm_pool = shm.create_pool(fd, size);
100 Some methods return newly created instances of other classes. In this
101 example an instance of the class `shm_pool_t` is returned.
103 Events are implemented using function objects. To react to an event, a
104 function object with the correct signature has to be assigned to
105 it. These can not only be static functions, but also member functions
106 or closures. E.g. to react to global events from the registry using a
107 lambda expression, one could write:
109 registry.on_global() = [] (uint32_t name, std::string interface,
111 { std::cout << interface << " v" << version << std::endl; };
113 An example for using member functions can be found in
114 example/opengles.cpp or example/shm.cpp.
116 The Wayland protocol uses arrays in some of its events and requests.
117 Since these arrays can have arbitrary content, they are not directly
118 mapped to a std::vector. Instead there is a new type array_t, which
119 can converted to and from a std::vectory with an user specified type.
122 keyboard.on_enter() = [] (uint32_t serial, surface_t surface,
124 { std::vector<uint32_t> vec = keys; };
126 To compile code that using this library, pkg-config can be used to
127 take care of the compiler flags. Assuming the source file is called
128 `foo.cpp` and the executable shall be called `foo` type:
130 $ c++ -c foo.cpp `pkg-config --cflags wayland-client++` -o foo.o
131 $ c++ foo.o `pkg-config --libs wayland-client++` -o foo
133 If the library and headers are installed in the default search paths
134 of the compiler, the linker flag `-lwayland-client++` can also
135 directly be specified on the command line.
137 If the Wayland cursor classes and/or EGL is used, the corresponding
138 libreries `wayland-cursor++` and/or `wayland-egl++` need to be linked
139 in as well. If any extension protocols such as xdg-shell are used,
140 the library `wayland-client-extra++` should be linked in as well.
142 Further examples can be found in the examples/Makefile.