blob: 67b2b04f08cdce3f0b3e89897d5f82a892825647 [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
Mathias Agopiana4e19522013-07-31 20:09:53 -070033class Fence;
Jesse Hall399184a2014-03-03 15:42:54 -080034class GraphicBuffer;
35class IConsumerListener;
36class NativeHandle;
Mathias Agopiana4e19522013-07-31 20:09:53 -070037
38class IGraphicBufferConsumer : public IInterface {
39
40public:
41
42 // public facing structure for BufferSlot
43 class BufferItem : public Flattenable<BufferItem> {
44 friend class Flattenable<BufferItem>;
45 size_t getPodSize() const;
46 size_t getFlattenedSize() const;
47 size_t getFdCount() const;
48 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const;
49 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count);
50
51 public:
Igor Murashkin7d2d1602013-11-12 18:02:20 -080052 // The default value of mBuf, used to indicate this doesn't correspond to a slot.
Mathias Agopiana4e19522013-07-31 20:09:53 -070053 enum { INVALID_BUFFER_SLOT = -1 };
54 BufferItem();
55
56 // mGraphicBuffer points to the buffer allocated for this slot, or is NULL
57 // if the buffer in this slot has been acquired in the past (see
58 // BufferSlot.mAcquireCalled).
59 sp<GraphicBuffer> mGraphicBuffer;
60
61 // mFence is a fence that will signal when the buffer is idle.
62 sp<Fence> mFence;
63
64 // mCrop is the current crop rectangle for this buffer slot.
65 Rect mCrop;
66
67 // mTransform is the current transform flags for this buffer slot.
Igor Murashkin7d2d1602013-11-12 18:02:20 -080068 // refer to NATIVE_WINDOW_TRANSFORM_* in <window.h>
Mathias Agopiana4e19522013-07-31 20:09:53 -070069 uint32_t mTransform;
70
71 // mScalingMode is the current scaling mode for this buffer slot.
Igor Murashkin7d2d1602013-11-12 18:02:20 -080072 // refer to NATIVE_WINDOW_SCALING_* in <window.h>
Mathias Agopiana4e19522013-07-31 20:09:53 -070073 uint32_t mScalingMode;
74
75 // mTimestamp is the current timestamp for this buffer slot. This gets
Igor Murashkin7d2d1602013-11-12 18:02:20 -080076 // to set by queueBuffer each time this slot is queued. This value
77 // is guaranteed to be monotonically increasing for each newly
78 // acquired buffer.
Mathias Agopiana4e19522013-07-31 20:09:53 -070079 int64_t mTimestamp;
80
Andy McFadden3c256212013-08-16 14:55:39 -070081 // mIsAutoTimestamp indicates whether mTimestamp was generated
82 // automatically when the buffer was queued.
83 bool mIsAutoTimestamp;
84
Mathias Agopiana4e19522013-07-31 20:09:53 -070085 // mFrameNumber is the number of the queued frame for this slot.
86 uint64_t mFrameNumber;
87
Igor Murashkin7d2d1602013-11-12 18:02:20 -080088 // mBuf is the slot index of this buffer (default INVALID_BUFFER_SLOT).
Mathias Agopiana4e19522013-07-31 20:09:53 -070089 int mBuf;
90
91 // mIsDroppable whether this buffer was queued with the
92 // property that it can be replaced by a new buffer for the purpose of
93 // making sure dequeueBuffer() won't block.
94 // i.e.: was the BufferQueue in "mDequeueBufferCannotBlock" when this buffer
95 // was queued.
96 bool mIsDroppable;
97
98 // Indicates whether this buffer has been seen by a consumer yet
99 bool mAcquireCalled;
Mathias Agopianc1c05de2013-09-17 23:45:22 -0700100
101 // Indicates this buffer must be transformed by the inverse transform of the screen
102 // it is displayed onto. This is applied after mTransform.
103 bool mTransformToDisplayInverse;
Mathias Agopiana4e19522013-07-31 20:09:53 -0700104 };
105
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800106 enum {
107 // Returned by releaseBuffer, after which the consumer must
108 // free any references to the just-released buffer that it might have.
109 STALE_BUFFER_SLOT = 1,
110 // Returned by dequeueBuffer if there are no pending buffers available.
111 NO_BUFFER_AVAILABLE,
112 // Returned by dequeueBuffer if it's too early for the buffer to be acquired.
113 PRESENT_LATER,
114 };
Mathias Agopiana4e19522013-07-31 20:09:53 -0700115
116 // acquireBuffer attempts to acquire ownership of the next pending buffer in
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800117 // the BufferQueue. If no buffer is pending then it returns
118 // NO_BUFFER_AVAILABLE. If a buffer is successfully acquired, the
119 // information about the buffer is returned in BufferItem.
120 //
121 // If the buffer returned had previously been
Mathias Agopiana4e19522013-07-31 20:09:53 -0700122 // acquired then the BufferItem::mGraphicBuffer field of buffer is set to
123 // NULL and it is assumed that the consumer still holds a reference to the
124 // buffer.
125 //
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800126 // If presentWhen is non-zero, it indicates the time when the buffer will
Mathias Agopiana4e19522013-07-31 20:09:53 -0700127 // be displayed on screen. If the buffer's timestamp is farther in the
128 // future, the buffer won't be acquired, and PRESENT_LATER will be
129 // returned. The presentation time is in nanoseconds, and the time base
130 // is CLOCK_MONOTONIC.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800131 //
132 // Return of NO_ERROR means the operation completed as normal.
133 //
134 // Return of a positive value means the operation could not be completed
135 // at this time, but the user should try again later:
136 // * NO_BUFFER_AVAILABLE - no buffer is pending (nothing queued by producer)
137 // * PRESENT_LATER - the buffer's timestamp is farther in the future
138 //
139 // Return of a negative value means an error has occurred:
140 // * INVALID_OPERATION - too many buffers have been acquired
141 virtual status_t acquireBuffer(BufferItem* buffer, nsecs_t presentWhen) = 0;
Mathias Agopiana4e19522013-07-31 20:09:53 -0700142
143 // releaseBuffer releases a buffer slot from the consumer back to the
144 // BufferQueue. This may be done while the buffer's contents are still
145 // being accessed. The fence will signal when the buffer is no longer
146 // in use. frameNumber is used to indentify the exact buffer returned.
147 //
148 // If releaseBuffer returns STALE_BUFFER_SLOT, then the consumer must free
149 // any references to the just-released buffer that it might have, as if it
150 // had received a onBuffersReleased() call with a mask set for the released
151 // buffer.
152 //
153 // Note that the dependencies on EGL will be removed once we switch to using
154 // the Android HW Sync HAL.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800155 //
156 // Return of NO_ERROR means the operation completed as normal.
157 //
158 // Return of a positive value means the operation could not be completed
159 // at this time, but the user should try again later:
160 // * STALE_BUFFER_SLOT - see above (second paragraph)
161 //
162 // Return of a negative value means an error has occurred:
163 // * BAD_VALUE - one of the following could've happened:
164 // * the buffer slot was invalid
165 // * the fence was NULL
166 // * the buffer slot specified is not in the acquired state
Mathias Agopiana4e19522013-07-31 20:09:53 -0700167 virtual status_t releaseBuffer(int buf, uint64_t frameNumber,
168 EGLDisplay display, EGLSyncKHR fence,
169 const sp<Fence>& releaseFence) = 0;
170
171 // consumerConnect connects a consumer to the BufferQueue. Only one
172 // consumer may be connected, and when that consumer disconnects the
173 // BufferQueue is placed into the "abandoned" state, causing most
174 // interactions with the BufferQueue by the producer to fail.
175 // controlledByApp indicates whether the consumer is controlled by
176 // the application.
177 //
178 // consumer may not be NULL.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800179 //
180 // Return of a value other than NO_ERROR means an error has occurred:
181 // * NO_INIT - the buffer queue has been abandoned
182 // * BAD_VALUE - a NULL consumer was provided
Mathias Agopiana4e19522013-07-31 20:09:53 -0700183 virtual status_t consumerConnect(const sp<IConsumerListener>& consumer, bool controlledByApp) = 0;
184
185 // consumerDisconnect disconnects a consumer from the BufferQueue. All
186 // buffers will be freed and the BufferQueue is placed in the "abandoned"
187 // state, causing most interactions with the BufferQueue by the producer to
188 // fail.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800189 //
190 // Return of a value other than NO_ERROR means an error has occurred:
191 // * BAD_VALUE - no consumer is currently connected
Mathias Agopiana4e19522013-07-31 20:09:53 -0700192 virtual status_t consumerDisconnect() = 0;
193
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800194 // getReleasedBuffers sets the value pointed to by slotMask to a bit set.
195 // Each bit index with a 1 corresponds to a released buffer slot with that
196 // index value. In particular, a released buffer is one that has
197 // been released by the BufferQueue but have not yet been released by the consumer.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700198 //
199 // This should be called from the onBuffersReleased() callback.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800200 //
201 // Return of a value other than NO_ERROR means an error has occurred:
202 // * NO_INIT - the buffer queue has been abandoned.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700203 virtual status_t getReleasedBuffers(uint32_t* slotMask) = 0;
204
205 // setDefaultBufferSize is used to set the size of buffers returned by
206 // dequeueBuffer when a width and height of zero is requested. Default
207 // is 1x1.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800208 //
209 // Return of a value other than NO_ERROR means an error has occurred:
210 // * BAD_VALUE - either w or h was zero
Mathias Agopiana4e19522013-07-31 20:09:53 -0700211 virtual status_t setDefaultBufferSize(uint32_t w, uint32_t h) = 0;
212
213 // setDefaultMaxBufferCount sets the default value for the maximum buffer
214 // count (the initial default is 2). If the producer has requested a
215 // buffer count using setBufferCount, the default buffer count will only
216 // take effect if the producer sets the count back to zero.
217 //
218 // The count must be between 2 and NUM_BUFFER_SLOTS, inclusive.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800219 //
220 // Return of a value other than NO_ERROR means an error has occurred:
221 // * BAD_VALUE - bufferCount was out of range (see above).
Mathias Agopiana4e19522013-07-31 20:09:53 -0700222 virtual status_t setDefaultMaxBufferCount(int bufferCount) = 0;
223
224 // disableAsyncBuffer disables the extra buffer used in async mode
225 // (when both producer and consumer have set their "isControlledByApp"
226 // flag) and has dequeueBuffer() return WOULD_BLOCK instead.
227 //
228 // This can only be called before consumerConnect().
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800229 //
230 // Return of a value other than NO_ERROR means an error has occurred:
231 // * INVALID_OPERATION - attempting to call this after consumerConnect.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700232 virtual status_t disableAsyncBuffer() = 0;
233
234 // setMaxAcquiredBufferCount sets the maximum number of buffers that can
235 // be acquired by the consumer at one time (default 1). This call will
236 // fail if a producer is connected to the BufferQueue.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800237 //
238 // maxAcquiredBuffers must be (inclusive) between 1 and MAX_MAX_ACQUIRED_BUFFERS.
239 //
240 // Return of a value other than NO_ERROR means an error has occurred:
241 // * BAD_VALUE - maxAcquiredBuffers was out of range (see above).
242 // * INVALID_OPERATION - attempting to call this after a producer connected.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700243 virtual status_t setMaxAcquiredBufferCount(int maxAcquiredBuffers) = 0;
244
245 // setConsumerName sets the name used in logging
246 virtual void setConsumerName(const String8& name) = 0;
247
248 // setDefaultBufferFormat allows the BufferQueue to create
249 // GraphicBuffers of a defaultFormat if no format is specified
250 // in dequeueBuffer. Formats are enumerated in graphics.h; the
251 // initial default is HAL_PIXEL_FORMAT_RGBA_8888.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800252 //
253 // Return of a value other than NO_ERROR means an unknown error has occurred.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700254 virtual status_t setDefaultBufferFormat(uint32_t defaultFormat) = 0;
255
256 // setConsumerUsageBits will turn on additional usage bits for dequeueBuffer.
257 // These are merged with the bits passed to dequeueBuffer. The values are
258 // enumerated in gralloc.h, e.g. GRALLOC_USAGE_HW_RENDER; the default is 0.
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800259 //
260 // Return of a value other than NO_ERROR means an unknown error has occurred.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700261 virtual status_t setConsumerUsageBits(uint32_t usage) = 0;
262
263 // setTransformHint bakes in rotation to buffers so overlays can be used.
264 // The values are enumerated in window.h, e.g.
265 // NATIVE_WINDOW_TRANSFORM_ROT_90. The default is 0 (no transform).
Igor Murashkin7d2d1602013-11-12 18:02:20 -0800266 //
267 // Return of a value other than NO_ERROR means an unknown error has occurred.
Mathias Agopiana4e19522013-07-31 20:09:53 -0700268 virtual status_t setTransformHint(uint32_t hint) = 0;
269
Jesse Hall399184a2014-03-03 15:42:54 -0800270 // Retrieve the sideband buffer stream, if any.
271 virtual sp<NativeHandle> getSidebandStream() const = 0;
272
Mathias Agopiandb89edc2013-08-02 01:40:18 -0700273 // dump state into a string
274 virtual void dump(String8& result, const char* prefix) const = 0;
275
Mathias Agopiana4e19522013-07-31 20:09:53 -0700276public:
277 DECLARE_META_INTERFACE(GraphicBufferConsumer);
278};
279
280// ----------------------------------------------------------------------------
281
282class BnGraphicBufferConsumer : public BnInterface<IGraphicBufferConsumer>
283{
284public:
285 virtual status_t onTransact( uint32_t code,
286 const Parcel& data,
287 Parcel* reply,
288 uint32_t flags = 0);
289};
290
291// ----------------------------------------------------------------------------
292}; // namespace android
293
294#endif // ANDROID_GUI_IGRAPHICBUFFERCONSUMER_H