KWayland

buffer_interface.h
1 /*
2  SPDX-FileCopyrightText: 2014 Martin Gräßlin <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 #ifndef WAYLAND_SERVER_BUFFER_INTERFACE_H
7 #define WAYLAND_SERVER_BUFFER_INTERFACE_H
8 
9 #include <QImage>
10 #include <QObject>
11 
12 #include <KWayland/Server/kwaylandserver_export.h>
13 
14 struct wl_resource;
15 struct wl_shm_buffer;
16 
17 namespace KWayland
18 {
19 namespace Server
20 {
21 class SurfaceInterface;
22 class LinuxDmabufBuffer;
23 
24 /**
25  * @brief Reference counted representation of a Wayland buffer on Server side.
26  *
27  * This class encapsulates a rendering buffer which is normally attached to a SurfaceInterface.
28  * A client should not render to a Wayland buffer as long as the buffer gets used by the server.
29  * The server signals whether it's still used. This class provides a convenience access for this
30  * functionality by performing reference counting and deleting the BufferInterface instance
31  * automatically once it is no longer accessed.
32  *
33  * The BufferInterface is referenced as long as it is attached to a SurfaceInterface. If one wants
34  * to keep access to the BufferInterface for a longer time ensure to call ref on first usage and
35  * unref again once access to it is no longer needed.
36  *
37  * In Wayland the buffer is an abstract concept and a buffer might represent multiple different
38  * concrete buffer techniques. This class has direct support for shared memory buffers built and
39  * provides access to the native buffer for different (e.g. EGL/drm) buffers.
40  *
41  * If the EGL display has been registered in the Display the BufferInterface can also provide
42  * some information about an EGL/drm buffer.
43  *
44  * For shared memory buffers a direct conversion to a memory-mapped QImage possible using the
45  * data method. Please refer to the documentation for notes on the restrictions when using the
46  * shared memory-mapped QImages.
47  *
48  * @see Display
49  * @see SurfaceInterace
50  **/
51 class KWAYLANDSERVER_EXPORT BufferInterface : public QObject
52 {
53  Q_OBJECT
54 public:
55  virtual ~BufferInterface();
56  /**
57  * Reference the BufferInterface.
58  *
59  * As long as the reference counting has not reached @c 0 the BufferInterface is valid
60  * and blocked for usage by the client.
61  *
62  * @see unref
63  * @see isReferenced
64  **/
65  void ref();
66  /**
67  * Unreference the BufferInterface.
68  *
69  * If the reference counting reached @c 0 the BufferInterface is released, so that the
70  * client can use it again. The instance of this BufferInterface will be automatically
71  * deleted.
72  *
73  * @see ref
74  * @see isReferenced
75  **/
76  void unref();
77  /**
78  * @returns whether the BufferInterface is currently referenced
79  *
80  * @see ref
81  * @see unref
82  **/
83  bool isReferenced() const;
84 
85  /**
86  * @returns The SurfaceInterface this BufferInterface is attached to.
87  **/
88  SurfaceInterface *surface() const;
89  /**
90  * @returns The native wl_shm_buffer if the BufferInterface represents a shared memory buffer, otherwise @c nullptr.
91  **/
92  wl_shm_buffer *shmBuffer();
93  /**
94  * Returns a pointer to the LinuxDmabufBuffer when the buffer is a dmabuf buffer, and nullptr otherwise.
95  */
96  LinuxDmabufBuffer *linuxDmabufBuffer();
97  /**
98  * @returns the native wl_resource wrapped by this BufferInterface.
99  **/
100  wl_resource *resource() const;
101 
102  /**
103  * Creates a QImage for the shared memory buffer.
104  *
105  * If the BufferInterface does not reference a shared memory buffer a null QImage is returned.
106  *
107  * The QImage shares the memory with the buffer and this constraints how the returned
108  * QImage can be used and when this method can be invoked.
109  *
110  * It is not safe to have two shared memory QImages for different BufferInterfaces at
111  * the same time. This method ensures that this does not happen and returns a null
112  * QImage if a different BufferInterface's data is still mapped to a QImage. Please note
113  * that this also applies to all implicitly data shared copies.
114  *
115  * In case it is needed to keep a copy, a deep copy has to be performed by using QImage::copy.
116  *
117  * As the underlying shared memory buffer is owned by a different client it is not safe to
118  * write to the returned QImage. The image is a read-only buffer. If there is need to modify
119  * the image, perform a deep copy.
120  *
121  **/
122  QImage data();
123 
124  /**
125  * Returns the size of this BufferInterface.
126  * Note: only for shared memory buffers (shmBuffer) the size can be derived,
127  * for other buffers it might be possible to derive the size if an EGL display
128  * is set on Display otherwise the user of the BufferInterface has to use setSize to
129  * provide the proper size.
130  * @see setSize
131  * @see Display::setEglDisplay
132  * @since 5.3
133  **/
134  QSize size() const;
135  /**
136  * Sets the @p size for non shared memory buffers.
137  * @see size
138  * @see sizeChanged
139  * @since 5.3
140  **/
141  void setSize(const QSize &size);
142 
143  /**
144  * Returns whether the format of the BufferInterface has an alpha channel.
145  * For shared memory buffers returns @c true for format @c WL_SHM_FORMAT_ARGB8888,
146  * for all other formats returns @c false.
147  *
148  * For EGL buffers returns @c true for format @c EGL_TEXTURE_RGBA, for all other formats
149  * returns @c false.
150  *
151  * If the format cannot be queried the default value (@c false) is returned.
152  *
153  * @since 5.4
154  **/
155  bool hasAlphaChannel() const;
156 
157  static BufferInterface *get(wl_resource *r);
158 
159 Q_SIGNALS:
160  void aboutToBeDestroyed(KWayland::Server::BufferInterface *);
161  /**
162  * Emitted when the size of the Buffer changes.
163  * @since 5.3
164  **/
165  void sizeChanged();
166 
167 private:
168  friend class SurfaceInterface;
169  explicit BufferInterface(wl_resource *resource, SurfaceInterface *parent);
170  class Private;
172 };
173 
174 }
175 }
176 
177 Q_DECLARE_METATYPE(KWayland::Server::BufferInterface *)
178 
179 #endif
Resource representing a wl_surface.
Reference counted representation of a Wayland buffer on Server side.
The base class for linux-dmabuf buffers.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:51:07 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.