Document ANativeWindow's buffer refcounting
Change-Id: I5454e90afd1a1b7d4a75c503f8dca712dba33790
diff --git a/include/system/window.h b/include/system/window.h
index 959bd23..1cc4a0a 100644
--- a/include/system/window.h
+++ b/include/system/window.h
@@ -340,9 +340,15 @@
int interval);
/*
- * hook called by EGL to acquire a buffer. After this call, the buffer
- * is not locked, so its content cannot be modified.
- * this call may block if no buffers are available.
+ * Hook called by EGL to acquire a buffer. After this call, the buffer
+ * is not locked, so its content cannot be modified. This call may block if
+ * no buffers are available.
+ *
+ * The window holds a reference to the buffer between dequeueBuffer and
+ * either queueBuffer or cancelBuffer, so clients only need their own
+ * reference if they might use the buffer after queueing or canceling it.
+ * Holding a reference to a buffer after queueing or canceling it is only
+ * allowed if a specific buffer count has been set.
*
* Returns 0 on success or -errno on error.
*/
@@ -358,14 +364,20 @@
*/
int (*lockBuffer)(struct ANativeWindow* window,
struct ANativeWindowBuffer* buffer);
- /*
- * hook called by EGL when modifications to the render buffer are done.
- * This unlocks and post the buffer.
- *
- * Buffers MUST be queued in the same order than they were dequeued.
- *
- * Returns 0 on success or -errno on error.
- */
+ /*
+ * Hook called by EGL when modifications to the render buffer are done.
+ * This unlocks and post the buffer.
+ *
+ * The window holds a reference to the buffer between dequeueBuffer and
+ * either queueBuffer or cancelBuffer, so clients only need their own
+ * reference if they might use the buffer after queueing or canceling it.
+ * Holding a reference to a buffer after queueing or canceling it is only
+ * allowed if a specific buffer count has been set.
+ *
+ * Buffers MUST be queued in the same order than they were dequeued.
+ *
+ * Returns 0 on success or -errno on error.
+ */
int (*queueBuffer)(struct ANativeWindow* window,
struct ANativeWindowBuffer* buffer);
@@ -411,10 +423,16 @@
int operation, ... );
/*
- * hook used to cancel a buffer that has been dequeued.
+ * Hook used to cancel a buffer that has been dequeued.
* No synchronization is performed between dequeue() and cancel(), so
* either external synchronization is needed, or these functions must be
* called from the same thread.
+ *
+ * The window holds a reference to the buffer between dequeueBuffer and
+ * either queueBuffer or cancelBuffer, so clients only need their own
+ * reference if they might use the buffer after queueing or canceling it.
+ * Holding a reference to a buffer after queueing or canceling it is only
+ * allowed if a specific buffer count has been set.
*/
int (*cancelBuffer)(struct ANativeWindow* window,
struct ANativeWindowBuffer* buffer);
