gui: Update header docs for IGraphicBufferConsumer/Producer/BufferQueue

Also fix compiler warnings for libgui

Change-Id: I0ee38d9ad5eaa82d55bf812d291da8c433581cef

1 files changed, 163 insertions, 25 deletions

diff --git a/include/gui/IGraphicBufferProducer.h b/include/gui/IGraphicBufferProducer.h
index 342ba0811..461be6f6e 100644
--- a/include/gui/IGraphicBufferProducer.h
+++ b/include/gui/IGraphicBufferProducer.h
@@ -54,7 +54,11 @@ public:
     DECLARE_META_INTERFACE(GraphicBufferProducer);
 
     enum {
+        // A flag returned by dequeueBuffer when the client needs to call
+        // requestBuffer immediately thereafter.
         BUFFER_NEEDS_REALLOCATION = 0x1,
+        // A flag returned by dequeueBuffer when all mirrored slots should be
+        // released by the client. This flag should always be processed first.
         RELEASE_ALL_BUFFERS       = 0x2,
     };
 
@@ -63,51 +67,140 @@ public:
     // buffer to the given slot index, and the client is expected to mirror the
     // slot->buffer mapping so that it's not necessary to transfer a
     // GraphicBuffer for every dequeue operation.
+    //
+    // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - one of the two conditions occurred:
+    //              * slot was out of range (see above)
+    //              * buffer specified by the slot is not dequeued
     virtual status_t requestBuffer(int slot, sp<GraphicBuffer>* buf) = 0;
 
     // setBufferCount sets the number of buffer slots available. Calling this
     // will also cause all buffer slots to be emptied. The caller should empty
     // its mirrored copy of the buffer slots when calling this method.
+    //
+    // This function should not be called when there are any dequeued buffer
+    // slots, doing so will result in a BAD_VALUE error returned.
+    //
+    // The buffer count should be at most NUM_BUFFER_SLOTS, but at least
+    // the minimum undequeued buffer count (inclusive). The minimum value
+    // can be obtained by calling query(NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS);
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - one of the below conditions occurred:
+    //              * bufferCount was out of range (see above)
+    //              * client has one or more buffers dequeued
     virtual status_t setBufferCount(int bufferCount) = 0;
 
     // dequeueBuffer requests a new buffer slot for the client to use. Ownership
     // of the slot is transfered to the client, meaning that the server will not
-    // use the contents of the buffer associated with that slot. The slot index
-    // returned may or may not contain a buffer. If the slot is empty the client
-    // should call requestBuffer to assign a new buffer to that slot. The client
-    // is expected to either call cancelBuffer on the dequeued slot or to fill
-    // in the contents of its associated buffer contents and call queueBuffer.
-    // If dequeueBuffer return BUFFER_NEEDS_REALLOCATION, the client is
+    // use the contents of the buffer associated with that slot.
+    //
+    // The slot index returned may or may not contain a buffer (client-side).
+    // If the slot is empty the client should call requestBuffer to assign a new
+    // buffer to that slot.
+    //
+    // Once the client is done filling this buffer, it is expected to transfer
+    // buffer ownership back to the server with either cancelBuffer on
+    // the dequeued slot or to fill in the contents of its associated buffer
+    // contents and call queueBuffer.
+    //
+    // If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is
     // expected to call requestBuffer immediately.
     //
+    // If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is
+    // expected to release all of the mirrored slot->buffer mappings.
+    //
     // The fence parameter will be updated to hold the fence associated with
     // the buffer. The contents of the buffer must not be overwritten until the
-    // fence signals. If the fence is NULL, the buffer may be written
+    // fence signals. If the fence is Fence::NO_FENCE, the buffer may be written
     // immediately.
     //
-    // The async parameter sets whether we're in asynchrnous mode for this
-    // deququeBuffer() call.
-    virtual status_t dequeueBuffer(int *slot, sp<Fence>* fence, bool async,
+    // The async parameter sets whether we're in asynchronous mode for this
+    // dequeueBuffer() call.
+    //
+    // The width and height parameters must be no greater than the minimum of
+    // GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see: glGetIntegerv).
+    // An error due to invalid dimensions might not be reported until
+    // updateTexImage() is called.  If width and height are both zero, the
+    // default values specified by setDefaultBufferSize() are used instead.
+    //
+    // The pixel formats are enumerated in <graphics.h>, e.g.
+    // HAL_PIXEL_FORMAT_RGBA_8888.  If the format is 0, the default format
+    // will be used.
+    //
+    // The usage argument specifies gralloc buffer usage flags.  The values
+    // are enumerated in <gralloc.h>, e.g. GRALLOC_USAGE_HW_RENDER.  These
+    // will be merged with the usage flags specified by
+    // IGraphicBufferConsumer::setConsumerUsageBits.
+    //
+    // This call will block until a buffer is available to be dequeued. If
+    // both the producer and consumer are controlled by the app, then this call
+    // can never block and will return WOULD_BLOCK if no buffer is available.
+    //
+    // A non-negative value with flags set (see above) will be returned upon
+    // success.
+    //
+    // Return of a negative means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - one of the below conditions occurred:
+    //              * both in async mode and buffer count was less than the
+    //                max numbers of buffers that can be allocated at once
+    //              * attempting dequeue more than one buffer at a time
+    //                without setting the buffer count with setBufferCount()
+    // * -EBUSY - attempting to dequeue too many buffers at a time
+    // * WOULD_BLOCK - no buffer is currently available, and blocking is disabled
+    //                 since both the producer/consumer are controlled by app
+    // * NO_MEMORY - out of memory, cannot allocate the graphics buffer.
+    //
+    // All other negative values are an unknown error returned downstream
+    // from the graphics allocator (typically errno).
+    virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, bool async,
             uint32_t w, uint32_t h, uint32_t format, uint32_t usage) = 0;
 
     // queueBuffer indicates that the client has finished filling in the
     // contents of the buffer associated with slot and transfers ownership of
-    // that slot back to the server. It is not valid to call queueBuffer on a
-    // slot that is not owned by the client or one for which a buffer associated
-    // via requestBuffer. In addition, a timestamp must be provided by the
-    // client for this buffer. The timestamp is measured in nanoseconds, and
-    // must be monotonically increasing. Its other properties (zero point, etc)
+    // that slot back to the server.
+    //
+    // It is not valid to call queueBuffer on a slot that is not owned
+    // by the client or one for which a buffer associated via requestBuffer
+    // (an attempt to do so will fail with a return value of BAD_VALUE).
+    //
+    // In addition, the input must be described by the client (as documented
+    // below). Any other properties (zero point, etc)
     // are client-dependent, and should be documented by the client.
     //
-    // The async parameter sets whether we're queuing a buffer in asynchronous mode.
+    // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
+    //
+    // Upon success, the output will be filled with meaningful values
+    // (refer to the documentation below).
     //
-    // outWidth, outHeight and outTransform are filled with the default width
-    // and height of the window and current transform applied to buffers,
-    // respectively.
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - one of the below conditions occurred:
+    //              * fence was NULL
+    //              * scaling mode was unknown
+    //              * both in async mode and buffer count was less than the
+    //                max numbers of buffers that can be allocated at once
+    //              * slot index was out of range (see above).
+    //              * the slot was not in the dequeued state
+    //              * the slot was enqueued without requesting a buffer
+    //              * crop rect is out of bounds of the buffer dimensions
 
     struct QueueBufferInput : public Flattenable<QueueBufferInput> {
         friend class Flattenable<QueueBufferInput>;
         inline QueueBufferInput(const Parcel& parcel);
+        // timestamp - a monotonically increasing value in nanoseconds
+        // isAutoTimestamp - if the timestamp was synthesized at queue time
+        // crop - a crop rectangle that's used as a hint to the consumer
+        // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h>
+        // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h>
+        // async - if the buffer is queued in asynchronous mode
+        // fence - a fence that the consumer must wait on before reading the buffer,
+        //         set this to Fence::NO_FENCE if the buffer is ready immediately
         inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp,
                 const Rect& crop, int scalingMode, uint32_t transform, bool async,
                 const sp<Fence>& fence)
@@ -143,8 +236,13 @@ public:
     };
 
     // QueueBufferOutput must be a POD structure
-    struct QueueBufferOutput {
+    struct __attribute__ ((__packed__)) QueueBufferOutput {
         inline QueueBufferOutput() { }
+        // outWidth - filled with default width applied to the buffer
+        // outHeight - filled with default height applied to the buffer
+        // outTransformHint - filled with default transform applied to the buffer
+        // outNumPendingBuffers - num buffers queued that haven't yet been acquired
+        //                        (counting the currently queued buffer)
         inline void deflate(uint32_t* outWidth,
                 uint32_t* outHeight,
                 uint32_t* outTransformHint,
@@ -174,24 +272,53 @@ public:
     // cancelBuffer indicates that the client does not wish to fill in the
     // buffer associated with slot and transfers ownership of the slot back to
     // the server.
+    //
+    // The buffer is not queued for use by the consumer.
+    //
+    // The buffer will not be overwritten until the fence signals.  The fence
+    // will usually be the one obtained from dequeueBuffer.
     virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0;
 
     // query retrieves some information for this surface
-    // 'what' tokens allowed are that of android_natives.h
+    // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h>
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - the buffer queue has been abandoned.
+    // * BAD_VALUE - what was out of range
     virtual int query(int what, int* value) = 0;
 
     // connect attempts to connect a client API to the IGraphicBufferProducer.
     // This must be called before any other IGraphicBufferProducer methods are
-    // called except for getAllocator.
+    // called except for getAllocator. A consumer must be already connected.
     //
     // This method will fail if the connect was previously called on the
     // IGraphicBufferProducer and no corresponding disconnect call was made.
     //
-    // outWidth, outHeight and outTransform are filled with the default width
-    // and height of the window and current transform applied to buffers,
-    // respectively. The token needs to be any binder object that lives in the
+    // The token needs to be any opaque binder object that lives in the
     // producer process -- it is solely used for obtaining a death notification
     // when the producer is killed.
+    //
+    // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
+    //
+    // The producerControlledByApp should be set to true if the producer is hosted
+    // by an untrusted process (typically app_process-forked processes). If both
+    // the producer and the consumer are app-controlled then all buffer queues
+    // will operate in async mode regardless of the async flag.
+    //
+    // Upon success, the output will be filled with meaningful data
+    // (refer to QueueBufferOutput documentation above).
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * NO_INIT - one of the following occurred:
+    //             * the buffer queue was abandoned
+    //             * no consumer has yet connected
+    // * BAD_VALUE - one of the following has occurred:
+    //             * the producer is already connected
+    //             * api was out of range (see above).
+    // * DEAD_OBJECT - the token is hosted by an already-dead process
+    //
+    // Additional negative errors may be returned by the internals, they
+    // should be treated as opaque fatal unrecoverable errors.
     virtual status_t connect(const sp<IBinder>& token,
             int api, bool producerControlledByApp, QueueBufferOutput* output) = 0;
 
@@ -203,6 +330,17 @@ public:
     //
     // This method will fail if the the IGraphicBufferProducer is not currently
     // connected to the specified client API.
+    //
+    // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
+    //
+    // Disconnecting from an abandoned IGraphicBufferProducer is legal and
+    // is considered a no-op.
+    //
+    // Return of a value other than NO_ERROR means an error has occurred:
+    // * BAD_VALUE - one of the following has occurred:
+    //             * the api specified does not match the one that was connected
+    //             * api was out of range (see above).
+    // * DEAD_OBJECT - the token is hosted by an already-dead process
     virtual status_t disconnect(int api) = 0;
 };