From 7cd3e0a3a2f9b104cd6c04f699ae62c4577787e2 Mon Sep 17 00:00:00 2001 From: Jesse Hall Date: Mon, 12 Dec 2011 10:32:55 -0800 Subject: Document ANativeWindow's buffer refcounting Change-Id: I5454e90afd1a1b7d4a75c503f8dca712dba33790 --- include/system/window.h | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) (limited to 'include') 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 @@ struct ANativeWindow 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 @@ struct ANativeWindow */ 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 @@ struct ANativeWindow 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); -- cgit v1.1