From 1bf245e0fe8ab41308459f4c49ab1c1c31f054e7 Mon Sep 17 00:00:00 2001
From: Kirill Primak <vyivel@eclair.cafe>
Date: Wed, 7 Jun 2023 09:31:06 +0300
Subject: compositor: improve role-specific documentation
---
include/wlr/types/wlr_compositor.h | 26 +++++++++++++++++++++++---
1 file changed, 23 insertions(+), 3 deletions(-)
diff --git a/include/wlr/types/wlr_compositor.h b/include/wlr/types/wlr_compositor.h
index b1b6f4a9..649f5ab3 100644
--- a/include/wlr/types/wlr_compositor.h
+++ b/include/wlr/types/wlr_compositor.h
@@ -73,8 +73,17 @@ struct wlr_surface_state {
struct wlr_surface_role {
const char *name;
+ /**
+ * Called when a new surface state is committed. May be NULL.
+ */
void (*commit)(struct wlr_surface *surface);
+ /**
+ * Called when the surface is unmapped. May be NULL.
+ */
void (*unmap)(struct wlr_surface *surface);
+ /**
+ * Called when the object representing the role is destroyed. May be NULL.
+ */
void (*destroy)(struct wlr_surface *surface);
};
@@ -138,8 +147,16 @@ struct wlr_surface {
bool mapped;
- const struct wlr_surface_role *role; // the lifetime-bound role or NULL
- void *role_data; // role-specific data
+ /**
+ * The lifetime-bound role of the surface. NULL if the role was never set.
+ */
+ const struct wlr_surface_role *role;
+
+ /**
+ * The role object representing the role. NULL if the role isn't
+ * represented by any object or the object was destroyed.
+ */
+ void *role_data;
struct {
struct wl_signal client_commit;
@@ -213,7 +230,10 @@ bool wlr_surface_set_role(struct wlr_surface *surface,
struct wl_resource *error_resource, uint32_t error_code);
/**
- * Destroy the role object for this surface. This doesn't reset the role.
+ * Destroy the object representing the surface's role. If it doesn't exist,
+ * this function is no-op.
+ *
+ * This doesn't reset the surface role itself.
*/
void wlr_surface_destroy_role_object(struct wlr_surface *surface);
--
cgit v1.2.3