Wayland++  0.2.2
C++ Bindings for Wayland
README.md
1 # Introduction
2 
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.
7 
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.
11 
12 # Requirements
13 
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.
17 
18 The documentation is autogenerated using Doxygen, therefore doxygen as
19 well as graphviz is required.
20 
21 # Building
22 
23 ## Library
24 
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.
28 
29 There are several CMake variables that can be set in order to
30 customise the build and install process:
31 
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
47 
48 The installation root can also be changed using the environment variable
49 `DESTDIR` when using `make install`.
50 
51 ## Documentation
52 
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.
55 
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/).
61 
62 ## Example programs
63 
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.
68 
69 To build the example programs manually, `make` can executed in
70 the example directory after the library has been built and installed.
71 
72 # Usage
73 
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++
76 programming language.
77 
78 Each interface is represented by a class. E.g. the `wl_registry`
79 interface is represented by the `registry_t` class.
80 
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.
88 
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:
93 
94  shm_t shm;
95  int fd;
96  int32_t size;
97  // ... insert the initialisation of the above here ...
98  shm_pool_t shm_pool = shm.create_pool(fd, size);
99 
100 Some methods return newly created instances of other classes. In this
101 example an instance of the class `shm_pool_t` is returned.
102 
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:
108 
109  registry.on_global() = [] (uint32_t name, std::string interface,
110  uint32_t version)
111  { std::cout << interface << " v" << version << std::endl; };
112 
113 An example for using member functions can be found in
114 example/opengles.cpp or example/shm.cpp.
115 
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.
120 For example:
121 
122  keyboard.on_enter() = [] (uint32_t serial, surface_t surface,
123  array_t keys)
124  { std::vector<uint32_t> vec = keys; };
125 
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:
129 
130  $ c++ -c foo.cpp `pkg-config --cflags wayland-client++` -o foo.o
131  $ c++ foo.o `pkg-config --libs wayland-client++` -o foo
132 
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.
136 
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.
141 
142 Further examples can be found in the examples/Makefile.