Home | History | Annotate | Download | only in gui
      1 /*
      2  * Copyright (C) 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_GUI_RINGBUFFERCONSUMER_H
     18 #define ANDROID_GUI_RINGBUFFERCONSUMER_H
     19 
     20 #include <gui/ConsumerBase.h>
     21 
     22 #include <ui/GraphicBuffer.h>
     23 
     24 #include <utils/String8.h>
     25 #include <utils/Vector.h>
     26 #include <utils/threads.h>
     27 #include <utils/List.h>
     28 
     29 #define ANDROID_GRAPHICS_RINGBUFFERCONSUMER_JNI_ID "mRingBufferConsumer"
     30 
     31 namespace android {
     32 
     33 /**
     34  * The RingBufferConsumer maintains a ring buffer of BufferItem objects,
     35  * (which are 'acquired' as long as they are part of the ring buffer, and
     36  *  'released' when they leave the ring buffer).
     37  *
     38  * When new buffers are produced, the oldest non-pinned buffer item is immediately
     39  * dropped from the ring buffer, and overridden with the newest buffer.
     40  *
     41  * Users can only access a buffer item after pinning it (which also guarantees
     42  * that during its duration it will not be released back into the BufferQueue).
     43  *
     44  * Note that the 'oldest' buffer is the one with the smallest timestamp.
     45  *
     46  * Edge cases:
     47  *  - If ringbuffer is not full, no drops occur when a buffer is produced.
     48  *  - If all the buffers get filled or pinned then there will be no empty
     49  *    buffers left, so the producer will block on dequeue.
     50  */
     51 class RingBufferConsumer : public ConsumerBase,
     52                            public ConsumerBase::FrameAvailableListener
     53 {
     54   public:
     55     typedef ConsumerBase::FrameAvailableListener FrameAvailableListener;
     56 
     57     typedef BufferQueue::BufferItem BufferItem;
     58 
     59     enum { INVALID_BUFFER_SLOT = BufferQueue::INVALID_BUFFER_SLOT };
     60     enum { NO_BUFFER_AVAILABLE = BufferQueue::NO_BUFFER_AVAILABLE };
     61 
     62     // Create a new ring buffer consumer. The consumerUsage parameter determines
     63     // the consumer usage flags passed to the graphics allocator. The
     64     // bufferCount parameter specifies how many buffers can be pinned for user
     65     // access at the same time.
     66     RingBufferConsumer(const sp<IGraphicBufferConsumer>& consumer, uint32_t consumerUsage,
     67             int bufferCount = BufferQueue::MIN_UNDEQUEUED_BUFFERS);
     68 
     69     virtual ~RingBufferConsumer();
     70 
     71     // set the name of the RingBufferConsumer that will be used to identify it in
     72     // log messages.
     73     void setName(const String8& name);
     74 
     75     // setDefaultBufferSize is used to set the size of buffers returned by
     76     // requestBuffers when a with and height of zero is requested.
     77     status_t setDefaultBufferSize(uint32_t w, uint32_t h);
     78 
     79     // setDefaultBufferFormat allows the BufferQueue to create
     80     // GraphicBuffers of a defaultFormat if no format is specified
     81     // by the producer endpoint.
     82     status_t setDefaultBufferFormat(uint32_t defaultFormat);
     83 
     84     // setConsumerUsage allows the BufferQueue consumer usage to be
     85     // set at a later time after construction.
     86     status_t setConsumerUsage(uint32_t usage);
     87 
     88     // Buffer info, minus the graphics buffer/slot itself.
     89     struct BufferInfo {
     90         // mCrop is the current crop rectangle for this buffer slot.
     91         Rect mCrop;
     92 
     93         // mTransform is the current transform flags for this buffer slot.
     94         uint32_t mTransform;
     95 
     96         // mScalingMode is the current scaling mode for this buffer slot.
     97         uint32_t mScalingMode;
     98 
     99         // mTimestamp is the current timestamp for this buffer slot. This gets
    100         // to set by queueBuffer each time this slot is queued.
    101         int64_t mTimestamp;
    102 
    103         // mFrameNumber is the number of the queued frame for this slot.
    104         uint64_t mFrameNumber;
    105 
    106         // mPinned is whether or not the buffer has been pinned already.
    107         bool mPinned;
    108     };
    109 
    110     struct RingBufferComparator {
    111         // Return < 0 to select i1, > 0 to select i2, 0 for neither
    112         // i1 or i2 can be NULL.
    113         //
    114         // The comparator has to implement a total ordering. Otherwise
    115         // a linear scan won't find the most preferred buffer.
    116         virtual int compare(const BufferInfo* i1,
    117                             const BufferInfo* i2) const = 0;
    118 
    119         virtual ~RingBufferComparator() {}
    120     };
    121 
    122     struct PinnedBufferItem : public LightRefBase<PinnedBufferItem> {
    123         PinnedBufferItem(wp<RingBufferConsumer> consumer,
    124                          const BufferItem& item) :
    125                 mConsumer(consumer),
    126                 mBufferItem(item) {
    127         }
    128 
    129         ~PinnedBufferItem() {
    130             sp<RingBufferConsumer> consumer = mConsumer.promote();
    131             if (consumer != NULL) {
    132                 consumer->unpinBuffer(mBufferItem);
    133             }
    134         }
    135 
    136         bool isEmpty() {
    137             return mBufferItem.mBuf == BufferQueue::INVALID_BUFFER_SLOT;
    138         }
    139 
    140         BufferItem& getBufferItem() { return mBufferItem; }
    141         const BufferItem& getBufferItem() const { return mBufferItem; }
    142 
    143       private:
    144         wp<RingBufferConsumer> mConsumer;
    145         BufferItem             mBufferItem;
    146     };
    147 
    148     // Find a buffer using the filter, then pin it before returning it.
    149     //
    150     // The filter will be invoked on each buffer item in the ring buffer,
    151     // passing the item that was selected from each previous iteration,
    152     // as well as the current iteration's item.
    153     //
    154     // Pinning will ensure that the buffer will not be dropped when a new
    155     // frame is available.
    156     sp<PinnedBufferItem> pinSelectedBuffer(const RingBufferComparator& filter,
    157                                            bool waitForFence = true);
    158 
    159     // Release all the non-pinned buffers in the ring buffer
    160     status_t clear();
    161 
    162   private:
    163 
    164     // Override ConsumerBase::onFrameAvailable
    165     virtual void onFrameAvailable();
    166 
    167     void pinBufferLocked(const BufferItem& item);
    168     void unpinBuffer(const BufferItem& item);
    169 
    170     // Releases oldest buffer. Returns NO_BUFFER_AVAILABLE
    171     // if all the buffers were pinned.
    172     // Returns NOT_ENOUGH_DATA if list was empty.
    173     status_t releaseOldestBufferLocked(size_t* pinnedFrames);
    174 
    175     struct RingBufferItem : public BufferItem {
    176         RingBufferItem() : BufferItem(), mPinCount(0) {}
    177         int mPinCount;
    178     };
    179 
    180     // List of acquired buffers in our ring buffer
    181     List<RingBufferItem>       mBufferItemList;
    182     const int                  mBufferCount;
    183 };
    184 
    185 } // namespace android
    186 
    187 #endif // ANDROID_GUI_CPUCONSUMER_H
    188