From 30122f1e056bee707f471987aab4810c2e26c10c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Gr=C3=A4=C3=9Flin?= Date: Wed, 9 Sep 2015 13:49:58 +0200 Subject: [PATCH] API doc improvements --- src/wayland/clientconnection.h | 61 +++++++++++++++++++++++++++ src/wayland/display.h | 5 +++ src/wayland/keyboard_interface.h | 7 +++ src/wayland/pointer_interface.h | 8 ++++ src/wayland/server/buffer_interface.h | 61 +++++++++++++++++++++++++++ src/wayland/server/global.h | 44 +++++++++++++++++++ src/wayland/server/resource.h | 20 +++++++++ src/wayland/touch_interface.h | 4 ++ 8 files changed, 210 insertions(+) diff --git a/src/wayland/clientconnection.h b/src/wayland/clientconnection.h index cb79359333..835055f9f8 100644 --- a/src/wayland/clientconnection.h +++ b/src/wayland/clientconnection.h @@ -35,13 +35,35 @@ namespace Server class Display; +/** + * @brief Convenient Class which represents a wl_client. + * + * The ClientConnection gets automatically created for a wl_client when a wl_client is + * first used in the context of KWayland::Server. In particular the signal + * @link Display::clientConnected @endlink will be emitted. + * + * @see Display + **/ class KWAYLANDSERVER_EXPORT ClientConnection : public QObject { Q_OBJECT public: virtual ~ClientConnection(); + /** + * Flushes the connection to this client. Ensures that all events are pushed to the client. + **/ void flush(); + /** + * Creates a new wl_resource for the provided @p interface. + * + * Thus a convenient wrapper around wl_resource_create + * + * @param interface + * @param version + * @param id + * @returns the created native wl_resource + **/ wl_resource *createResource(const wl_interface *interface, quint32 version, quint32 id); /** * Get the wl_resource associated with the given @p id. @@ -49,17 +71,56 @@ public: **/ wl_resource *getResource(quint32 id); + /** + * @returns the native wl_client this ClientConnection represents. + **/ wl_client *client(); + /** + * @returns The Display this ClientConnection is connected to + **/ Display *display(); + /** + * The pid of the ClientConnection endpoint. + * + * Please note: if the ClientConnection got created with @link Display::createClient @endlink + * the pid will be identical to the process running the KWayland::Server::Display. + * + * @returns The pid of the connection. + **/ pid_t processId() const; + /** + * The uid of the ClientConnection endpoint. + * + * Please note: if the ClientConnection got created with @link Display::createClient @endlink + * the uid will be identical to the process running the KWayland::Server::Display. + * + * @returns The uid of the connection. + **/ uid_t userId() const; + /** + * The gid of the ClientConnection endpoint. + * + * Please note: if the ClientConnection got created with @link Display::createClient @endlink + * the gid will be identical to the process running the KWayland::Server::Display. + * + * @returns The gid of the connection. + **/ gid_t groupId() const; + /** + * Cast operator the native wl_client this ClientConnection represents. + **/ operator wl_client*(); + /** + * Cast operator the native wl_client this ClientConnection represents. + **/ operator wl_client*() const; Q_SIGNALS: + /** + * Signal emitted when the ClientConnection got disconnected from the server. + **/ void disconnected(KWayland::Server::ClientConnection*); private: diff --git a/src/wayland/display.h b/src/wayland/display.h index e5f1ed5853..fa4f865c5a 100644 --- a/src/wayland/display.h +++ b/src/wayland/display.h @@ -51,6 +51,11 @@ class ContrastManagerInterface; class ShellInterface; class SubCompositorInterface; +/** + * @brief Class holding the Wayland server display loop. + * + * @todo Improve documentation + **/ class KWAYLANDSERVER_EXPORT Display : public QObject { Q_OBJECT diff --git a/src/wayland/keyboard_interface.h b/src/wayland/keyboard_interface.h index 2921f73152..17d1d20297 100644 --- a/src/wayland/keyboard_interface.h +++ b/src/wayland/keyboard_interface.h @@ -32,12 +32,19 @@ namespace Server class SeatInterface; class SurfaceInterface; +/** + * @brief Resource for the wl_keyboard interface. + * + **/ class KWAYLANDSERVER_EXPORT KeyboardInterface : public Resource { Q_OBJECT public: virtual ~KeyboardInterface(); + /** + * @returns the focused SurfaceInterface on this keyboard resource, if any. + **/ SurfaceInterface *focusedSurface() const; private: diff --git a/src/wayland/pointer_interface.h b/src/wayland/pointer_interface.h index 254f7f2379..6d23e75709 100644 --- a/src/wayland/pointer_interface.h +++ b/src/wayland/pointer_interface.h @@ -33,11 +33,19 @@ class Cursor; class SeatInterface; class SurfaceInterface; +/** + * @brief Resource for the wl_pointer interface. + * + **/ class KWAYLANDSERVER_EXPORT PointerInterface : public Resource { Q_OBJECT public: virtual ~PointerInterface(); + + /** + * @returns the focused SurfaceInterface on this pointer resource, if any. + **/ SurfaceInterface *focusedSurface() const; /** diff --git a/src/wayland/server/buffer_interface.h b/src/wayland/server/buffer_interface.h index f3638797a9..1a764e1f2d 100644 --- a/src/wayland/server/buffer_interface.h +++ b/src/wayland/server/buffer_interface.h @@ -35,17 +35,78 @@ namespace Server class SurfaceInterface; +/** + * @brief Reference counted representation of a Wayland buffer on Server side. + * + * This class encapsulates a rendering buffer which is normally attached to a SurfaceInterface. + * A client should not render to a Wayland buffer as long as the buffer gets used by the server. + * The server signals whether it's still used. This class provides a convenience access for this + * functionality by performing reference counting and deleting the BufferInterface instance + * automatically once it is no longer accessed. + * + * The BufferInterface is referenced as long as it is attached to a SurfaceInterface. If one wants + * to keep access to the BufferInterface for a longer time ensure to call ref on first usage and + * unref again once access to it is no longer needed. + * + * In Wayland the buffer is an abstract concept and a buffer might represent multiple different + * concrete buffer techniques. This class has direct support for shared memory buffers built and + * provides access to the native buffer for different (e.g. EGL/drm) buffers. + * + * If the EGL display has been registered in the Display the BufferInterface can also provide + * some information about an EGL/drm buffer. + * + * For shared memory buffers a direct conversion to a memory-mapped QImage possible using the + * data method. Please refer to the documentation for notes on the restrictions when using the + * shared memory-mapped QImages. + * + * @see Display + * @see SurfaceInterace + **/ class KWAYLANDSERVER_EXPORT BufferInterface : public QObject { Q_OBJECT public: virtual ~BufferInterface(); + /** + * Reference the BufferInterface. + * + * As long as the reference counting has not reached @c 0 the BufferInterface is valid + * and blocked for usage by the client. + * + * @see unref + * @see isReferenced + **/ void ref(); + /** + * Unreference the BufferInterface. + * + * If the reference counting reached @c 0 the BufferInterface is released, so that the + * client can use it again. The instance of this BufferInterface will be automatically + * deleted. + * + * @see ref + * @see isReferenced + **/ void unref(); + /** + * @returns whether the BufferInterface is currently referenced + * + * @see ref + * @see unref + **/ bool isReferenced() const; + /** + * @returns The SurfaceInterface this BufferInterface is attached to. + **/ SurfaceInterface *surface() const; + /** + * @returns The native wl_shm_buffer if the BufferInterface represents a shared memory buffer, otherwise @c nullptr. + **/ wl_shm_buffer *shmBuffer(); + /** + * @returns the native wl_resource wrapped by this BufferInterface. + **/ wl_resource *resource() const; /** diff --git a/src/wayland/server/global.h b/src/wayland/server/global.h index 35a02acae0..6883a98a15 100644 --- a/src/wayland/server/global.h +++ b/src/wayland/server/global.h @@ -32,18 +32,62 @@ namespace Server { class Display; +/** + * @brief Base class for all Globals. + * + * Any class representing a Global should be derived from this base class. + * This class provides common functionality for all globals. A global is an + * object listed as an interface on the registry on client side. + * + * Normally a Global gets factored by the Display. For each Global-derived class there + * is a dedicated factory method. After creating an instance through the factory method + * it is not yet announced on the registry. One needs to call ::create on it. This allows + * to setup the Global before it gets announced, ensuring that the client's state is correct + * from the start. + * + * As an example shown for @link OutputInterface @endlink: + * @code + * Display *display; // The existing display + * auto o = display->createOutput(); + * o->setManufacturer(QStringLiteral("The KDE Community")); + * // setup further data on the OutputInterface + * o->create(); // announces OutputInterface + * @endcode + * + * @see Display + * + **/ class KWAYLANDSERVER_EXPORT Global : public QObject { Q_OBJECT public: virtual ~Global(); + /** + * Creates the global by creating a native wl_global and by that announcing it + * to the clients. + **/ void create(); + /** + * Destroys the low level wl_global. Afterwards the Global is no longer shown to clients. + **/ void destroy(); + /** + * @returns whether the Global got created + **/ bool isValid() const; + /** + * @returns the Display the Global got created on. + */ Display *display(); + /** + * Cast operator to the native wl_global this Global represents. + **/ operator wl_global*(); + /** + * Cast operator to the native wl_global this Global represents. + **/ operator wl_global*() const; protected: diff --git a/src/wayland/server/resource.h b/src/wayland/server/resource.h index a501bf72d9..e2edc1070c 100644 --- a/src/wayland/server/resource.h +++ b/src/wayland/server/resource.h @@ -35,6 +35,14 @@ namespace Server class ClientConnection; class Global; +/** + * @brief Represents a bound Resource. + * + * A Resource normally gets created by a @link Global @endlink. + * + * The Resource is a base class for all specific resources and provides + * access to various common aspects. + **/ class KWAYLANDSERVER_EXPORT Resource : public QObject { Q_OBJECT @@ -42,9 +50,21 @@ public: virtual ~Resource(); void create(ClientConnection *client, quint32 version, quint32 id); + /** + * @returns the native wl_resource this Resource was created for. + **/ wl_resource *resource(); + /** + * @returns The ClientConnection for which the Resource was created. + **/ ClientConnection *client(); + /** + * @returns The Global which created the Resource. + **/ Global *global(); + /** + * @returns the native parent wl_resource, e.g. the wl_resource bound on the Global + **/ wl_resource *parentResource() const; /** * @returns The id of this Resource if it is created, otherwise @c 0. diff --git a/src/wayland/touch_interface.h b/src/wayland/touch_interface.h index e41d784864..63b33c6122 100644 --- a/src/wayland/touch_interface.h +++ b/src/wayland/touch_interface.h @@ -31,6 +31,10 @@ namespace Server class SeatInterface; +/** + * @brief Resource for the wl_touch interface. + * + **/ class KWAYLANDSERVER_EXPORT TouchInterface : public Resource { Q_OBJECT