2 files changed, 22 insertions, 3 deletions
diff --git a/include/wlr/types/wlr_buffer.h b/include/wlr/types/wlr_buffer.h
index fc348a1c..eabc8b51 100644
--- a/include/wlr/types/wlr_buffer.h
+++ b/include/wlr/types/wlr_buffer.h
@@ -8,8 +8,15 @@
  * A client buffer.
  */
 struct wlr_buffer {
-	struct wl_resource *resource; // can be NULL
-	struct wlr_texture *texture; // can be NULL
+	/**
+	 * The buffer resource, if any. Will be NULL if the client destroys it.
+	 */
+	struct wl_resource *resource;
+	/**
+	 * The buffer's texture, if any. A buffer will not have a texture if the
+	 * client destroys the buffer before it has been released.
+	 */
+	struct wlr_texture *texture;
 	bool released;
 	size_t n_refs;
 
diff --git a/include/wlr/types/wlr_surface.h b/include/wlr/types/wlr_surface.h
index 64503e78..8517934a 100644
--- a/include/wlr/types/wlr_surface.h
+++ b/include/wlr/types/wlr_surface.h
@@ -69,8 +69,13 @@ struct wlr_subsurface {
 struct wlr_surface {
 	struct wl_resource *resource;
 	struct wlr_renderer *renderer;
+	/**
+	 * The surface's buffer, if any. A surface has an attached buffer when it
+	 * commits with a non-null buffer in its pending state. A surface will not
+	 * have a buffer if it has never committed one, has committed a null buffer,
+	 * or something went wrong with uploading the buffer.
+	 */
 	struct wlr_buffer *buffer;
-	struct wlr_texture *texture;
 	struct wlr_surface_state *current, *pending;
 	const char *role; // the lifetime-bound role or null
 
@@ -126,6 +131,13 @@ int wlr_surface_set_role(struct wlr_surface *surface, const char *role,
 bool wlr_surface_has_buffer(struct wlr_surface *surface);
 
 /**
+ * Get the texture of the buffer currently attached to this surface. Returns
+ * NULL if no buffer is currently attached or if something went wrong with
+ * uploading the buffer.
+ */
+struct wlr_texture *wlr_surface_get_texture(struct wlr_surface *surface);
+
+/**
  * Create a new subsurface resource with the provided new ID. If `resource_list`
  * is non-NULL, adds the subsurface's resource to the list.
  */