Warning, /plasma/kwayland/README.md is written in an unsupported language. File is not indexed.
0001 # KWayland 0002 0003 KWayland is a Qt-style API to interact with the wayland-client and wayland-server API. 0004 0005 ## Introduction 0006 0007 KWayland provides two libraries: 0008 0009 - KWayland::Client 0010 - KWayland::Server 0011 0012 As the names suggest they implement a Client respectively a Server API for the Wayland 0013 protocol. The API is Qt-styled removing the needs to interact with a for a Qt developer 0014 uncomfortable low-level C-API. For example the callback mechanism from the Wayland API 0015 is replaced by signals; data types are adjusted to be what a Qt developer expects, e.g. 0016 two arguments of int are represented by a QPoint or a QSize. 0017 0018 ## KWayland Server 0019 0020 ### Head-less API 0021 0022 The server library can be used to implement a Wayland server with Qt. The API is head-less 0023 meaning it does not perform any output and does not restrict on the way how one wants to 0024 render. This allows to easily integrate in existing rendering code based on e.g. OpenGL or 0025 QPainter. Applications built on top of KWayland Server integrated the graphics with the 0026 following technologies: 0027 0028 - OpenGL over DRM/KMS 0029 - OpenGL over X11 0030 - OpenGL over Wayland 0031 - OpenGL over Android's hwcomposer enabled through libhybris 0032 - QPainter over DRM/KMs 0033 - QPainter over fbdev 0034 - QPainter over X11 0035 - QPainter over Wayland 0036 - QWidget 0037 - QtQuick 0038 0039 Although the library does not perform any output, it makes it very easy to enable rendering. 0040 The representation for a [Buffer](@ref KWayland::Server::BufferInterface) allows easy conversion 0041 to a (memory-shared) QImage in case the buffer represents a shared memory buffer. This QImage 0042 can be used for rendering in a QPainter based API or to generate an OpenGL texture. 0043 0044 ### Easy usage of Wayland API 0045 0046 The library hides many Wayland implementation details. For all Wayland interfaces which have 0047 double buffered state the classes always only provide access to the committed state. The pending 0048 state is an internal detail. On commit of the pending state Qt signals are emitted about what 0049 changed. 0050 0051 Buffers are ref-counted and automatically released if it is no longer referenced allowing the 0052 client to reuse it. This happens fully automatically when a surface no longer references a buffer. 0053 As long as a buffer is attached surface, the surface has it referenced and the user of the API can 0054 access the buffer without needing to care about referencing it. 0055 0056 The API of KWayland is hand-crafted to make usage easier. The representation of a 0057 [Surface](@ref KWayland::Server::SurfaceInterface) combines multiple aspects about a Surface even 0058 if in Wayland API it is added to other elements. E.g. a Surface contains all 0059 [SubSurfaces](@ref KWayland::Server::SubSurfaceInterface) attached to it instead of the user 0060 having to monitor for which Surface a SubSurface got created. 0061 0062 Similar the representation of a [Seat](@ref KWayland::Server::SeatInterface) combines all aspects of 0063 the Seat. A user of the API only needs to interact with the Seat, there is no need to track all the 0064 created [keyboards](@ref KWayland::Server::KeyboardInterface), [pointers](@ref KWayland::Server::PointerInterface), etc. The 0065 representation of Seat tracks which keyboards are generated and is able to forward events to the 0066 proper focus surface, send enter and leave notifications when needed without the user of the API 0067 to care about it. 0068 0069 ### Handling input events 0070 0071 Just like with output the server API does not restrict on how to get input events. This allows to 0072 integrate with existing input handlers and also allows to easily filter the input before it is passed 0073 to the server and from there delegated to the client. By that one can filter out e.g. global touch 0074 gestures or keyboard shortcuts without having to implement handlers inside KWayland. The SeatInterface 0075 provides a very easy to use API to forward events which can be easily integrated with Qt's own 0076 input event system, e.g. there is a mapping from Qt::MouseButton to the Linux input code. 0077 0078 Applications built on top of KWayland Server integrated input events with the following technologies: 0079 0080 - libinput 0081 - X11 0082 - Wayland 0083 - Android's inputstack enabled through libhybris 0084 - QInputEvent 0085 0086 ### Private IPC with child processes 0087 0088 KWayland Server is well suited for having a private IPC with child processes. The [Display](@ref KWayland::Server::Display) can be 0089 setup in a way that it doesn't create a public socket but only allows connections through socket 0090 pairs. This allows to create a socketpair, pass one file descriptor to KWayland server and the other 0091 to the forked process, e.g. through the WAYLAND_SOCKET environment variable. Thus a dedicated IPC 0092 is created which can be used even for running your own custom protocol. For example KDE Plasma uses 0093 such a dedicated parent-child Wayland server in it's screen locker architecture. 0094 0095 Of course private sockets can be added at any time in addition to a publicly available socket. This 0096 can be used to recognize specific clients and to restrict access to interfaces for only some dedicated 0097 clients. 0098 0099 ## KWayland Client 0100 0101 The idea around KWayland Client is to provide a drop-in API for the Wayland client library which at 0102 the same time provides convenience Qt-style API. It is not intended to be used as a replacement for 0103 the QtWayland QPA plugin, but rather as a way to interact with Wayland in case one needs Qt to use 0104 a different QPA plugin or in combination with QtWayland to allow a more low-level interaction without 0105 requiring to write C code. 0106 0107 ### Convenience API 0108 0109 The convenience API in KWayland Client provides one class wrapping a Wayland object. Each class can 0110 be casted into the wrapped Wayland type. The API represents events as signals and provides simple 0111 method calls for requests. 0112 0113 Classes representing global Wayland resources can be created through the [Registry](@ref KWayland::Client::Registry). This class eases 0114 the interaction with the Wayland registry and emits signals whenever a new global is announced or gets 0115 removed. The Registry has a list of known interfaces (e.g. common Wayland protocols like `wl_compositor` 0116 or `wl_shell`) which have dedicated announce/removed signals and objects can be factored by the Registry 0117 for those globals. 0118 0119 Many globals function as a factory for further resources. E.g. the Compositor has a factory method for 0120 Surfaces. All objects can also be created in a low-level way interacting directly with the Wayland API, 0121 but provide convenience factory methods in addition. This allows both an easy usage or a more low level 0122 control of the Wayland API if needed. 0123 0124 ### Integration with QtWayland QPA 0125 0126 If the QGuiApplication uses the QtWayland QPA, KWayland allows to integrate with it. That is one does 0127 not need to create a new connection to the Wayland server, but can reuse the one used by Qt. If there 0128 is a way to get a Wayland object from Qt, the respective class provides a static method normally called 0129 `fromApplication`. In addition the API allows to get the Surface from a QWindow. 0130 0131 ## Using KWayland in your application 0132 0133 ### With CMake 0134 0135 KWayland installs a CMake Config file which allows to use KWayland as imported targets. There is 0136 one library for Client and one for Server. 0137 0138 To find the package use for example: 0139 0140 find_package(KF5Wayland CONFIG) 0141 set_package_properties(KF5Wayland PROPERTIES TYPE OPTIONAL ) 0142 add_feature_info("KF5Wayland" KF5Wayland_FOUND "Required for the awesome Wayland on Qt demo") 0143 0144 Now to link against the Client library use: 0145 0146 add_executable(exampleApp example.cpp) 0147 target_link_libraries(exampleApp KF5::WaylandClient) 0148 0149 To link against the Server library use: 0150 0151 add_executable(exampleServer exampleServer.cpp) 0152 target_link_libraries(exampleServer KF5::WaylandServer) 0153 0154 ### With QMake 0155 0156 KWayland installs .pri files for the Client and Server library allowing easy usage in QMake based 0157 applications. 0158 0159 Just use: 0160 0161 QT += KWaylandClient 0162 0163 Respectively: 0164 0165 QT += KWaylandServer 0166 0167 Please make sure that your project is configured with C++11 support: 0168 0169 CONFIG += c++11