BufferQueue: Add producer buffer-released callback

Add a callback to the producer side, onBufferReleased, which will be
called every time the consumer releases a buffer back to the
BufferQueue. This will enable a buffer stream splitter to work
autonomously without having to block on dequeueBuffer.

The binder object used for the callback replaces the generic IBinder
token that was passed into IGraphicBufferProducer::connect to detect
the death of the producer. If a producer does not wish to listen for
buffer release events, it can pass in an instance of the
DummyProducerListener class defined in IProducerListener.h, if it even
cares about death events (BufferQueue doesn't enforce the token being
non-NULL, though perhaps we should).

Change-Id: I23935760673524abeafea2b58dccc3583b368710

5 files changed, 79 insertions, 17 deletions

diff --git a/include/gui/BufferQueue.h b/include/gui/BufferQueue.h
index f74dc26..85bf5a9 100644
--- a/include/gui/BufferQueue.h
+++ b/include/gui/BufferQueue.h
@@ -232,16 +232,8 @@ public:
     // will usually be the one obtained from dequeueBuffer.
     virtual void cancelBuffer(int buf, const sp<Fence>& fence);
 
-    // connect attempts to connect a producer API to the BufferQueue.  This
-    // must be called before any other IGraphicBufferProducer methods are
-    // called except for getAllocator.  A consumer must already be connected.
-    //
-    // This method will fail if connect was previously called on the
-    // BufferQueue and no corresponding disconnect call was made (i.e. if
-    // it's still connected to a producer).
-    //
-    // APIs are enumerated in window.h (e.g. NATIVE_WINDOW_API_CPU).
-    virtual status_t connect(const sp<IBinder>& token,
+    // See IGraphicBufferProducer::connect
+    virtual status_t connect(const sp<IProducerListener>& listener,
             int api, bool producerControlledByApp, QueueBufferOutput* output);
 
     // disconnect attempts to disconnect a producer API from the BufferQueue.
diff --git a/include/gui/BufferQueueCore.h b/include/gui/BufferQueueCore.h
index 89f2779..cfcb7a5 100644
--- a/include/gui/BufferQueueCore.h
+++ b/include/gui/BufferQueueCore.h
@@ -46,9 +46,9 @@
 namespace android {
 
 class BufferItem;
-class IBinder;
 class IConsumerListener;
 class IGraphicBufferAlloc;
+class IProducerListener;
 
 class BufferQueueCore : public virtual RefBase {
 
@@ -162,7 +162,7 @@ private:
 
     // mConnectedProducerToken is used to set a binder death notification on
     // the producer.
-    sp<IBinder> mConnectedProducerToken;
+    sp<IProducerListener> mConnectedProducerListener;
 
     // mSlots is an array of buffer slots that must be mirrored on the producer
     // side. This allows buffer ownership to be transferred between the producer
diff --git a/include/gui/BufferQueueProducer.h b/include/gui/BufferQueueProducer.h
index 0013b0a..04692a5 100644
--- a/include/gui/BufferQueueProducer.h
+++ b/include/gui/BufferQueueProducer.h
@@ -140,7 +140,7 @@ public:
     // it's still connected to a producer).
     //
     // APIs are enumerated in window.h (e.g. NATIVE_WINDOW_API_CPU).
-    virtual status_t connect(const sp<IBinder>& token,
+    virtual status_t connect(const sp<IProducerListener>& listener,
             int api, bool producerControlledByApp, QueueBufferOutput* output);
 
     // disconnect attempts to disconnect a producer API from the BufferQueue.
diff --git a/include/gui/IGraphicBufferProducer.h b/include/gui/IGraphicBufferProducer.h
index 0874f03..2b61ab3 100644
--- a/include/gui/IGraphicBufferProducer.h
+++ b/include/gui/IGraphicBufferProducer.h
@@ -32,6 +32,7 @@
 namespace android {
 // ----------------------------------------------------------------------------
 
+class IProducerListener;
 class NativeHandle;
 class Surface;
 
@@ -344,9 +345,11 @@ public:
     // This method will fail if the connect was previously called on the
     // IGraphicBufferProducer and no corresponding disconnect call was made.
     //
-    // 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 listener is an optional binder callback object that can be used if
+    // the producer wants to be notified when the consumer releases a buffer
+    // back to the BufferQueue. It is also used to detect the death of the
+    // producer. If only the latter functionality is desired, there is a
+    // DummyProducerListener class in IProducerListener.h that can be used.
     //
     // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
     //
@@ -370,7 +373,7 @@ public:
     //
     // 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,
+    virtual status_t connect(const sp<IProducerListener>& listener,
             int api, bool producerControlledByApp, QueueBufferOutput* output) = 0;
 
     // disconnect attempts to disconnect a client API from the
diff --git a/include/gui/IProducerListener.h b/include/gui/IProducerListener.h
new file mode 100644
index 0000000..3848a6c
--- /dev/null
+++ b/include/gui/IProducerListener.h
@@ -0,0 +1,67 @@
+/*
+ * Copyright 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef ANDROID_GUI_IPRODUCERLISTENER_H
+#define ANDROID_GUI_IPRODUCERLISTENER_H
+
+#include <binder/IInterface.h>
+
+#include <utils/RefBase.h>
+
+namespace android {
+
+// ProducerListener is the interface through which the BufferQueue notifies the
+// producer of events that the producer may wish to react to. Because the
+// producer will generally have a mutex that is locked during calls from the
+// producer to the BufferQueue, these calls from the BufferQueue to the
+// producer *MUST* be called only when the BufferQueue mutex is NOT locked.
+
+class ProducerListener : public virtual RefBase
+{
+public:
+    ProducerListener() {}
+    virtual ~ProducerListener() {}
+
+    // onBufferReleased is called from IGraphicBufferConsumer::releaseBuffer to
+    // notify the producer that a new buffer is free and ready to be dequeued.
+    //
+    // This is called without any lock held and can be called concurrently by
+    // multiple threads.
+    virtual void onBufferReleased() = 0; // Asynchronous
+};
+
+class IProducerListener : public ProducerListener, public IInterface
+{
+public:
+    DECLARE_META_INTERFACE(ProducerListener)
+};
+
+class BnProducerListener : public BnInterface<IProducerListener>
+{
+public:
+    virtual status_t onTransact(uint32_t code, const Parcel& data,
+            Parcel* reply, uint32_t flags = 0);
+};
+
+class DummyProducerListener : public BnProducerListener
+{
+public:
+    virtual void onBufferReleased() {}
+};
+
+} // namespace android
+
+#endif