blob: a03736d10efbba8eda4b4dd56a3723d4f070196b [file] [log] [blame]
Igor Murashkin40602742013-04-29 10:31:06 -07001/*
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
31namespace 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 */
51class 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.
Mathias Agopiandeeef542013-08-02 01:50:59 -070066 RingBufferConsumer(const sp<IGraphicBufferConsumer>& consumer, uint32_t consumerUsage,
Igor Murashkin054aab32013-11-18 11:39:27 -080067 int bufferCount);
Igor Murashkin40602742013-04-29 10:31:06 -070068
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
Igor Murashkin40602742013-04-29 10:31:06 -070075 // 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