buffer: replace get_data_ptr with {begin,end}_data_ptr_access

This new API allows buffer implementations to know when a user is
actively accessing the buffer's underlying storage. This is
important for the upcoming client-backed wlr_buffer implementation.

2 files changed, 12 insertions, 7 deletions

diff --git a/include/types/wlr_buffer.h b/include/types/wlr_buffer.h
index f9d2974d..56b50f3d 100644
--- a/include/types/wlr_buffer.h
+++ b/include/types/wlr_buffer.h
@@ -16,13 +16,16 @@ enum wlr_buffer_cap {
 };
 
 /**
- * Access a pointer to the allocated data from the underlying implementation,
- * its format and its stride.
+ * Get a pointer to a region of memory referring to the buffer's underlying
+ * storage. The format and stride can be used to interpret the memory region
+ * contents.
  *
- * The returned pointer should be pointing to a valid memory location for read
- * and write operations.
+ * The returned pointer should be pointing to a valid memory region for read
+ * and write operations. The returned pointer is only valid up to the next
+ * buffer_end_data_ptr_access call.
  */
-bool buffer_get_data_ptr(struct wlr_buffer *buffer, void **data,
+bool buffer_begin_data_ptr_access(struct wlr_buffer *buffer, void **data,
 	uint32_t *format, size_t *stride);
+void buffer_end_data_ptr_access(struct wlr_buffer *buffer);
 
 #endif
diff --git a/include/wlr/types/wlr_buffer.h b/include/wlr/types/wlr_buffer.h
index 3b8b76f6..47f17cce 100644
--- a/include/wlr/types/wlr_buffer.h
+++ b/include/wlr/types/wlr_buffer.h
@@ -26,10 +26,11 @@ struct wlr_buffer_impl {
 	void (*destroy)(struct wlr_buffer *buffer);
 	bool (*get_dmabuf)(struct wlr_buffer *buffer,
 		struct wlr_dmabuf_attributes *attribs);
-	bool (*get_data_ptr)(struct wlr_buffer *buffer, void **data,
-		uint32_t *format, size_t *stride);
 	bool (*get_shm)(struct wlr_buffer *buffer,
 		struct wlr_shm_attributes *attribs);
+	bool (*begin_data_ptr_access)(struct wlr_buffer *buffer, void **data,
+		uint32_t *format, size_t *stride);
+	void (*end_data_ptr_access)(struct wlr_buffer *buffer);
 };
 
 /**
@@ -47,6 +48,7 @@ struct wlr_buffer {
 
 	bool dropped;
 	size_t n_locks;
+	bool accessing_data_ptr;
 
 	struct {
 		struct wl_signal destroy;