blob: 9a6645cf21546433fec252d3d7b37b5e1451dacc [file] [log] [blame]
Mathias Agopiana4e19522013-07-31 20:09:53 -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_IGRAPHICBUFFERCONSUMER_H
18#define ANDROID_GUI_IGRAPHICBUFFERCONSUMER_H
19
20#include <stdint.h>
21#include <sys/types.h>
22
23#include <utils/Errors.h>
24#include <utils/RefBase.h>
25#include <utils/Timers.h>
26
27#include <binder/IInterface.h>
28#include <ui/Rect.h>
29
30namespace android {
31// ----------------------------------------------------------------------------
32
33class IConsumerListener;
34class GraphicBuffer;
35class Fence;
36
37class IGraphicBufferConsumer : public IInterface {
38
39public:
40
41 // public facing structure for BufferSlot
42 class BufferItem : public Flattenable<BufferItem> {
43 friend class Flattenable<BufferItem>;
44 size_t getPodSize() const;
45 size_t getFlattenedSize() const;
46 size_t getFdCount() const;
47 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const;
48 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count);
49
50 public:
Igor Murashkin7d2d1602013-11-12 18:02:20 -080051 // The default value of mBuf, used to indicate this doesn't correspond to a slot.
Mathias Agopiana4e19522013-07-31 20:09:53 -070052 enum { INVALID_BUFFER_SLOT = -1 };
53 BufferItem();
54
55 // mGraphicBuffer points to the buffer allocated for this slot, or is NULL
56 // if the buffer in this slot has been acquired in the past (see
57 // BufferSlot.mAcquireCalled).
58 sp<GraphicBuffer> mGraphicBuffer;
59
60 // mFence is a fence that will signal when the buffer is idle.
61 sp<Fence> mFence;
62
63 // mCrop is the current crop rectangle for this buffer slot.
64 Rect mCrop;
65
66 // mTransform is the current transform flags for this buffer slot.
Igor Murashkin7d2d1602013-11-12 18:02:20 -080067 // refer to NATIVE_WINDOW_TRANSFORM_* in <window.h>
Mathias Agopiana4e19522013-07-31 20:09:53 -070068 uint32_t mTransform;
69
70 // mScalingMode is the current scaling mode for this buffer slot.
Igor Murashkin7d2d1602013-11-12 18:02:20 -080071 // refer to NATIVE_WINDOW_SCALING_* in <window.h>
Mathias Agopiana4e19522013-07-31 20:09:53 -070072 uint32_t mScalingMode;
73
74 // mTimestamp is the current timestamp for this buffer slot. This gets
Igor Murashkin7d2d1602013-11-12 18:02:20 -080075 // to set by queueBuffer each time this slot is queued. This value
76 // is guaranteed to be monotonically increasing for each newly
77 // acquired buffer.
Mathias Agopiana4e19522013-07-31 20:09:53 -070078 int64_t mTimestamp;
79
Andy McFadden3c256212013-08-16 14:55:39 -070080 // mIsAutoTimestamp indicates whether mTimestamp was generated
81 // automatically when the buffer was queued.
82 bool mIsAutoTimestamp;
83
Mathias Agopiana4e19522013-07-31 20:09:53 -070084 // mFrameNumber is the number of the queued frame for this slot.
85 uint64_t mFrameNumber;
86
Igor Murashkin7d2d1602013-11-12 18:02:20 -080087 // mBuf is the slot index of this buffer (default INVALID_BUFFER_SLOT).
Mathias Agopiana4e19522013-07-31 20:09:53 -070088 int mBuf;
89
90 // mIsDroppable whether this buffer was queued with the
91 // property that it can be replaced by a new buffer for the purpose of
92 // making sure dequeueBuffer() won't block.
93 // i.e.: was the BufferQueue in "mDequeueBufferCannotBlock" when this buffer
94 // was queued.
95 bool mIsDroppable;
96
97 // Indicates whether this buffer has been seen by a consumer yet
98 bool mAcquireCalled;
Mathias Agopianc1c05de2013-09-17 23:45:22 -070099
100 // Indicates this buffer must be transformed by the inverse transform of the screen
101 // it is displayed onto. This is applied after mTransform.
102 bool mTransformToDisplayInverse;
Mathias Agopiana4e19522013-07-31 20:09:53 -0700103 };
104
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800105 enum {
106 // Returned by releaseBuffer, after which the consumer must
107 // free any references to the just-released buffer that it might have.
108 STALE_BUFFER_SLOT = 1,
109 // Returned by dequeueBuffer if there are no pending buffers available.
110 NO_BUFFER_AVAILABLE,
111 // Returned by dequeueBuffer if it's too early for the buffer to be acquired.
112 PRESENT_LATER,
113 };
Mathias Agopiana4e19522013-07-31 20:09:53 -0700114
115 // acquireBuffer attempts to acquire ownership of the next pending buffer in
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800116 // the BufferQueue. If no buffer is pending then it returns
117 // NO_BUFFER_AVAILABLE. If a buffer is successfully acquired, the
118 // information about the buffer is returned in BufferItem.
119 //
120 // If the buffer returned had previously been
Mathias Agopiana4e19522013-07-31 20:09:53 -0700121 // acquired then the BufferItem::mGraphicBuffer field of buffer is set to
122 // NULL and it is assumed that the consumer still holds a reference to the
123 // buffer.
124 //
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800125 // If presentWhen is non-zero, it indicates the time when the buffer will
Mathias Agopiana4e19522013-07-31 20:09:53 -0700126 // be displayed on screen. If the buffer's timestamp is farther in the
127 // future, the buffer won't be acquired, and PRESENT_LATER will be
128 // returned. The presentation time is in nanoseconds, and the time base
129 // is CLOCK_MONOTONIC.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800130 //
131 // Return of NO_ERROR means the operation completed as normal.
132 //
133 // Return of a positive value means the operation could not be completed
134 // at this time, but the user should try again later:
135 // * NO_BUFFER_AVAILABLE - no buffer is pending (nothing queued by producer)
136 // * PRESENT_LATER - the buffer's timestamp is farther in the future
137 //
138 // Return of a negative value means an error has occurred:
139 // * INVALID_OPERATION - too many buffers have been acquired
140 virtual status_t acquireBuffer(BufferItem* buffer, nsecs_t presentWhen) = 0;
Mathias Agopiana4e19522013-07-31 20:09:53 -0700141
142 // releaseBuffer releases a buffer slot from the consumer back to the
143 // BufferQueue. This may be done while the buffer's contents are still
144 // being accessed. The fence will signal when the buffer is no longer
145 // in use. frameNumber is used to indentify the exact buffer returned.
146 //
147 // If releaseBuffer returns STALE_BUFFER_SLOT, then the consumer must free
148 // any references to the just-released buffer that it might have, as if it
149 // had received a onBuffersReleased() call with a mask set for the released
150 // buffer.
151 //
152 // Note that the dependencies on EGL will be removed once we switch to using
153 // the Android HW Sync HAL.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800154 //
155 // Return of NO_ERROR means the operation completed as normal.
156 //
157 // Return of a positive value means the operation could not be completed
158 // at this time, but the user should try again later:
159 // * STALE_BUFFER_SLOT - see above (second paragraph)
160 //
161 // Return of a negative value means an error has occurred:
162 // * BAD_VALUE - one of the following could've happened:
163 // * the buffer slot was invalid
164 // * the fence was NULL
165 // * the buffer slot specified is not in the acquired state
Mathias Agopiana4e19522013-07-31 20:09:53 -0700166 virtual status_t releaseBuffer(int buf, uint64_t frameNumber,
167 EGLDisplay display, EGLSyncKHR fence,
168 const sp<Fence>& releaseFence) = 0;
169
170 // consumerConnect connects a consumer to the BufferQueue. Only one
171 // consumer may be connected, and when that consumer disconnects the
172 // BufferQueue is placed into the "abandoned" state, causing most
173 // interactions with the BufferQueue by the producer to fail.
174 // controlledByApp indicates whether the consumer is controlled by
175 // the application.
176 //
177 // consumer may not be NULL.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800178 //
179 // Return of a value other than NO_ERROR means an error has occurred:
180 // * NO_INIT - the buffer queue has been abandoned
181 // * BAD_VALUE - a NULL consumer was provided
Mathias Agopiana4e19522013-07-31 20:09:53 -0700182 virtual status_t consumerConnect(const sp<IConsumerListener>& consumer, bool controlledByApp) = 0;
183
184 // consumerDisconnect disconnects a consumer from the BufferQueue. All
185 // buffers will be freed and the BufferQueue is placed in the "abandoned"
186 // state, causing most interactions with the BufferQueue by the producer to
187 // fail.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800188 //
189 // Return of a value other than NO_ERROR means an error has occurred:
190 // * BAD_VALUE - no consumer is currently connected
Mathias Agopiana4e19522013-07-31 20:09:53 -0700191 virtual status_t consumerDisconnect() = 0;
192
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800193 // getReleasedBuffers sets the value pointed to by slotMask to a bit set.
194 // Each bit index with a 1 corresponds to a released buffer slot with that
195 // index value. In particular, a released buffer is one that has
196 // been released by the BufferQueue but have not yet been released by the consumer.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700197 //
198 // This should be called from the onBuffersReleased() callback.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800199 //
200 // Return of a value other than NO_ERROR means an error has occurred:
201 // * NO_INIT - the buffer queue has been abandoned.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700202 virtual status_t getReleasedBuffers(uint32_t* slotMask) = 0;
203
204 // setDefaultBufferSize is used to set the size of buffers returned by
205 // dequeueBuffer when a width and height of zero is requested. Default
206 // is 1x1.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800207 //
208 // Return of a value other than NO_ERROR means an error has occurred:
209 // * BAD_VALUE - either w or h was zero
Mathias Agopiana4e19522013-07-31 20:09:53 -0700210 virtual status_t setDefaultBufferSize(uint32_t w, uint32_t h) = 0;
211
212 // setDefaultMaxBufferCount sets the default value for the maximum buffer
213 // count (the initial default is 2). If the producer has requested a
214 // buffer count using setBufferCount, the default buffer count will only
215 // take effect if the producer sets the count back to zero.
216 //
217 // The count must be between 2 and NUM_BUFFER_SLOTS, inclusive.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800218 //
219 // Return of a value other than NO_ERROR means an error has occurred:
220 // * BAD_VALUE - bufferCount was out of range (see above).
Mathias Agopiana4e19522013-07-31 20:09:53 -0700221 virtual status_t setDefaultMaxBufferCount(int bufferCount) = 0;
222
223 // disableAsyncBuffer disables the extra buffer used in async mode
224 // (when both producer and consumer have set their "isControlledByApp"
225 // flag) and has dequeueBuffer() return WOULD_BLOCK instead.
226 //
227 // This can only be called before consumerConnect().
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800228 //
229 // Return of a value other than NO_ERROR means an error has occurred:
230 // * INVALID_OPERATION - attempting to call this after consumerConnect.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700231 virtual status_t disableAsyncBuffer() = 0;
232
233 // setMaxAcquiredBufferCount sets the maximum number of buffers that can
234 // be acquired by the consumer at one time (default 1). This call will
235 // fail if a producer is connected to the BufferQueue.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800236 //
237 // maxAcquiredBuffers must be (inclusive) between 1 and MAX_MAX_ACQUIRED_BUFFERS.
238 //
239 // Return of a value other than NO_ERROR means an error has occurred:
240 // * BAD_VALUE - maxAcquiredBuffers was out of range (see above).
241 // * INVALID_OPERATION - attempting to call this after a producer connected.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700242 virtual status_t setMaxAcquiredBufferCount(int maxAcquiredBuffers) = 0;
243
244 // setConsumerName sets the name used in logging
245 virtual void setConsumerName(const String8& name) = 0;
246
247 // setDefaultBufferFormat allows the BufferQueue to create
248 // GraphicBuffers of a defaultFormat if no format is specified
249 // in dequeueBuffer. Formats are enumerated in graphics.h; the
250 // initial default is HAL_PIXEL_FORMAT_RGBA_8888.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800251 //
252 // Return of a value other than NO_ERROR means an unknown error has occurred.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700253 virtual status_t setDefaultBufferFormat(uint32_t defaultFormat) = 0;
254
255 // setConsumerUsageBits will turn on additional usage bits for dequeueBuffer.
256 // These are merged with the bits passed to dequeueBuffer. The values are
257 // enumerated in gralloc.h, e.g. GRALLOC_USAGE_HW_RENDER; the default is 0.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800258 //
259 // Return of a value other than NO_ERROR means an unknown error has occurred.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700260 virtual status_t setConsumerUsageBits(uint32_t usage) = 0;
261
262 // setTransformHint bakes in rotation to buffers so overlays can be used.
263 // The values are enumerated in window.h, e.g.
264 // NATIVE_WINDOW_TRANSFORM_ROT_90. The default is 0 (no transform).
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800265 //
266 // Return of a value other than NO_ERROR means an unknown error has occurred.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700267 virtual status_t setTransformHint(uint32_t hint) = 0;
268
Mathias Agopiandb89edc2013-08-02 01:40:18 -0700269 // dump state into a string
270 virtual void dump(String8& result, const char* prefix) const = 0;
271
Mathias Agopiana4e19522013-07-31 20:09:53 -0700272public:
273 DECLARE_META_INTERFACE(GraphicBufferConsumer);
274};
275
276// ----------------------------------------------------------------------------
277
278class BnGraphicBufferConsumer : public BnInterface<IGraphicBufferConsumer>
279{
280public:
281 virtual status_t onTransact( uint32_t code,
282 const Parcel& data,
283 Parcel* reply,
284 uint32_t flags = 0);
285};
286
287// ----------------------------------------------------------------------------
288}; // namespace android
289
290#endif // ANDROID_GUI_IGRAPHICBUFFERCONSUMER_H