• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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);
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 
~RingBufferComparatorRingBufferComparator119         virtual ~RingBufferComparator() {}
120     };
121 
122     struct PinnedBufferItem : public LightRefBase<PinnedBufferItem> {
PinnedBufferItemPinnedBufferItem123         PinnedBufferItem(wp<RingBufferConsumer> consumer,
124                          const BufferItem& item) :
125                 mConsumer(consumer),
126                 mBufferItem(item) {
127         }
128 
~PinnedBufferItemPinnedBufferItem129         ~PinnedBufferItem() {
130             sp<RingBufferConsumer> consumer = mConsumer.promote();
131             if (consumer != NULL) {
132                 consumer->unpinBuffer(mBufferItem);
133             }
134         }
135 
isEmptyPinnedBufferItem136         bool isEmpty() {
137             return mBufferItem.mBuf == BufferQueue::INVALID_BUFFER_SLOT;
138         }
139 
getBufferItemPinnedBufferItem140         BufferItem& getBufferItem() { return mBufferItem; }
getBufferItemPinnedBufferItem141         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     // Return 0 if RingBuffer is empty, otherwise return timestamp of latest buffer.
163     nsecs_t getLatestTimestamp();
164 
165   private:
166 
167     // Override ConsumerBase::onFrameAvailable
168     virtual void onFrameAvailable();
169 
170     void pinBufferLocked(const BufferItem& item);
171     void unpinBuffer(const BufferItem& item);
172 
173     // Releases oldest buffer. Returns NO_BUFFER_AVAILABLE
174     // if all the buffers were pinned.
175     // Returns NOT_ENOUGH_DATA if list was empty.
176     status_t releaseOldestBufferLocked(size_t* pinnedFrames);
177 
178     struct RingBufferItem : public BufferItem {
RingBufferItemRingBufferItem179         RingBufferItem() : BufferItem(), mPinCount(0) {}
180         int mPinCount;
181     };
182 
183     // List of acquired buffers in our ring buffer
184     List<RingBufferItem>       mBufferItemList;
185     const int                  mBufferCount;
186 
187     // Timestamp of latest buffer
188     nsecs_t mLatestTimestamp;
189 };
190 
191 } // namespace android
192 
193 #endif // ANDROID_GUI_CPUCONSUMER_H
194