services/surfaceflinger/DisplayHardware/BufferQueueInterposer.h

   1 /*
   2  * Copyright 2013 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_SF_BUFFERQUEUEINTERPOSER_H
  18 #define ANDROID_SF_BUFFERQUEUEINTERPOSER_H
  19
  20 #include <gui/IGraphicBufferProducer.h>
  21 #include <utils/Mutex.h>
  22 #include <utils/Vector.h>
  23
  24 // ---------------------------------------------------------------------------
  25 namespace android {
  26 // ---------------------------------------------------------------------------
  27
  28 // BufferQueueInterposers introduce an extra stage between a buffer producer
  29 // (the source) and a buffer consumer (the sink), which communicate via the
  30 // IGraphicBufferProducer interface. It is designed to be as transparent as
  31 // possible to both endpoints, so that they can work the same whether an
  32 // interposer is present or not.
  33 //
  34 // When the interpose is present, the source queues buffers to the
  35 // IGraphicBufferProducer implemented by BufferQueueInterposer. A client of
  36 // the BufferQueueInterposer can acquire each buffer in turn and read or
  37 // modify it, releasing the buffer when finished. When the buffer is released,
  38 // the BufferQueueInterposer queues it to the original IGraphicBufferProducer
  39 // interface representing the sink.
  40 //
  41 // A BufferQueueInterposer can be used to do additional rendering to a buffer
  42 // before it is consumed -- essentially pipelining two producers. As an
  43 // example, SurfaceFlinger uses this to implement mixed GLES and HWC
  44 // compositing to the same buffer for virtual displays. If it used two separate
  45 // buffer queues, then in GLES-only or mixed GLES+HWC compositing, the HWC
  46 // would have to copy the GLES output buffer to the HWC output buffer, using
  47 // more bandwidth than having HWC do additional composition "in place" on the
  48 // GLES output buffer.
  49 //
  50 // The goal for this class is to be usable in a variety of situations and be
  51 // part of libgui. But both the interface and implementation need some
  52 // iteration before then, so for now it should only be used by
  53 // VirtualDisplaySurface, which is why it's currently in SurfaceFlinger.
  54 //
  55 // Some of the problems that still need to be solved are:
  56 //
  57 // - Refactor the interposer interface along with BufferQueue and ConsumerBase,
  58 //   so that there is a common interface for the consumer end of a queue. The
  59 //   existing interfaces have some problems when the implementation isn't the
  60 //   final consumer.
  61 //
  62 // - The interposer needs at least one buffer in addition to those used by the
  63 //   source and sink. setBufferCount and QueueBufferOutput both need to
  64 //   account for this. It's not possible currently to do this generically,
  65 //   since we can't find out how many buffers the source and sink need. (See
  66 //   the horrible hack in the BufferQueueInterposer constructor).
  67 //
  68 // - Abandoning, disconnecting, and connecting need to pass through somehow.
  69 //   There needs to be a way to tell the interposer client to release its
  70 //   buffer immediately so it can be queued/released, e.g. when the source
  71 //   calls disconnect().
  72 //
  73 // - Right now the source->BQI queue is synchronous even if the BQI->sink
  74 //   queue is asynchronous. Need to figure out how asynchronous should behave
  75 //   and implement that.
  76
  77 class BufferQueueInterposer : public BnGraphicBufferProducer {
  78 public:
  79     BufferQueueInterposer(const sp<IGraphicBufferProducer>& sink,
  80             const String8& name);
  81
  82     //
  83     // IGraphicBufferProducer interface
  84     //
  85     virtual status_t requestBuffer(int slot, sp<GraphicBuffer>* outBuf);
  86     virtual status_t setBufferCount(int bufferCount);
  87     virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence,
  88             uint32_t w, uint32_t h, uint32_t format, uint32_t usage);
  89     virtual status_t queueBuffer(int slot,
  90             const QueueBufferInput& input, QueueBufferOutput* output);
  91     virtual void cancelBuffer(int slot, const sp<Fence>& fence);
  92     virtual int query(int what, int* value);
  93     virtual status_t setSynchronousMode(bool enabled);
  94     virtual status_t connect(int api, QueueBufferOutput* output);
  95     virtual status_t disconnect(int api);
  96
  97     //
  98     // Interposer interface
  99     //
 100
 101     enum {
 102         NO_BUFFER_AVAILABLE = 2,    // matches BufferQueue
 103         BUFFER_NOT_ACQUIRED,
 104         BUFFER_ALREADY_ACQUIRED,
 105     };
 106
 107     // Acquire the oldest queued buffer. If no buffers are pending, returns
 108     // NO_BUFFER_AVAILABLE. If a buffer is currently acquired, returns
 109     // BUFFER_ALREADY_ACQUIRED.
 110     status_t acquireBuffer(sp<GraphicBuffer>* buf, sp<Fence>* fence);
 111
 112     // Release the currently acquired buffer, queueing it to the sink. If the
 113     // current buffer hasn't been acquired, returns BUFFER_NOT_ACQUIRED.
 114     status_t releaseBuffer(const sp<Fence>& fence);
 115
 116     // pullEmptyBuffer dequeues a buffer from the sink, then immediately
 117     // queues it to the interposer. This makes a buffer available for the
 118     // client to acquire even if the source hasn't queued one.
 119     status_t pullEmptyBuffer();
 120
 121 private:
 122     struct QueuedBuffer {
 123         QueuedBuffer(): slot(-1) {}
 124         QueuedBuffer(int slot, const QueueBufferInput& qbi): slot(slot) {
 125             qbi.deflate(&timestamp, &crop, &scalingMode, &transform, &fence);
 126         }
 127         int slot;
 128         int64_t timestamp;
 129         Rect crop;
 130         int scalingMode;
 131         uint32_t transform;
 132         sp<Fence> fence;
 133     };
 134
 135     virtual ~BufferQueueInterposer();
 136     status_t flushQueuedBuffersLocked();
 137
 138     const sp<IGraphicBufferProducer> mSink;
 139     String8 mName;
 140
 141     Mutex mMutex;
 142     Vector<sp<GraphicBuffer> > mBuffers;
 143     Vector<QueuedBuffer> mQueue;
 144     bool mAcquired;
 145     QueueBufferOutput mQueueBufferOutput;
 146 };
 147
 148 // ---------------------------------------------------------------------------
 149 } // namespace android
 150 // ---------------------------------------------------------------------------
 151
 152 #endif // ANDROID_SF_BUFFERQUEUEINTERPOSER_H