2 * Copyright (C) 2010 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H
18 #define ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H
21 #include <sys/types.h>
23 #include <utils/Errors.h>
24 #include <utils/RefBase.h>
26 #include <binder/IInterface.h>
29 #include <ui/GraphicBuffer.h>
33 // ----------------------------------------------------------------------------
35 class IProducerListener;
40 * This class defines the Binder IPC interface for the producer side of
41 * a queue of graphics buffers. It's used to send graphics data from one
42 * component to another. For example, a class that decodes video for
43 * playback might use this to provide frames. This is typically done
44 * indirectly, through Surface.
46 * The underlying mechanism is a BufferQueue, which implements
47 * BnGraphicBufferProducer. In normal operation, the producer calls
48 * dequeueBuffer() to get an empty buffer, fills it with data, then
49 * calls queueBuffer() to make it available to the consumer.
51 * This class was previously called ISurfaceTexture.
53 class IGraphicBufferProducer : public IInterface
56 DECLARE_META_INTERFACE(GraphicBufferProducer);
59 // A flag returned by dequeueBuffer when the client needs to call
60 // requestBuffer immediately thereafter.
61 BUFFER_NEEDS_REALLOCATION = 0x1,
62 // A flag returned by dequeueBuffer when all mirrored slots should be
63 // released by the client. This flag should always be processed first.
64 RELEASE_ALL_BUFFERS = 0x2,
67 // requestBuffer requests a new buffer for the given index. The server (i.e.
68 // the IGraphicBufferProducer implementation) assigns the newly created
69 // buffer to the given slot index, and the client is expected to mirror the
70 // slot->buffer mapping so that it's not necessary to transfer a
71 // GraphicBuffer for every dequeue operation.
73 // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
75 // Return of a value other than NO_ERROR means an error has occurred:
76 // * NO_INIT - the buffer queue has been abandoned.
77 // * BAD_VALUE - one of the two conditions occurred:
78 // * slot was out of range (see above)
79 // * buffer specified by the slot is not dequeued
80 virtual status_t requestBuffer(int slot, sp<GraphicBuffer>* buf) = 0;
82 // setBufferCount sets the number of buffer slots available. Calling this
83 // will also cause all buffer slots to be emptied. The caller should empty
84 // its mirrored copy of the buffer slots when calling this method.
86 // This function should not be called when there are any dequeued buffer
87 // slots, doing so will result in a BAD_VALUE error returned.
89 // The buffer count should be at most NUM_BUFFER_SLOTS (inclusive), but at least
90 // the minimum undequeued buffer count (exclusive). The minimum value
91 // can be obtained by calling query(NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS).
92 // In particular the range is (minUndequeudBuffers, NUM_BUFFER_SLOTS].
94 // The buffer count may also be set to 0 (the default), to indicate that
95 // the producer does not wish to set a value.
97 // Return of a value other than NO_ERROR means an error has occurred:
98 // * NO_INIT - the buffer queue has been abandoned.
99 // * BAD_VALUE - one of the below conditions occurred:
100 // * bufferCount was out of range (see above)
101 // * client has one or more buffers dequeued
102 virtual status_t setBufferCount(int bufferCount) = 0;
104 // dequeueBuffer requests a new buffer slot for the client to use. Ownership
105 // of the slot is transfered to the client, meaning that the server will not
106 // use the contents of the buffer associated with that slot.
108 // The slot index returned may or may not contain a buffer (client-side).
109 // If the slot is empty the client should call requestBuffer to assign a new
110 // buffer to that slot.
112 // Once the client is done filling this buffer, it is expected to transfer
113 // buffer ownership back to the server with either cancelBuffer on
114 // the dequeued slot or to fill in the contents of its associated buffer
115 // contents and call queueBuffer.
117 // If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is
118 // expected to call requestBuffer immediately.
120 // If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is
121 // expected to release all of the mirrored slot->buffer mappings.
123 // The fence parameter will be updated to hold the fence associated with
124 // the buffer. The contents of the buffer must not be overwritten until the
125 // fence signals. If the fence is Fence::NO_FENCE, the buffer may be written
128 // The async parameter sets whether we're in asynchronous mode for this
129 // dequeueBuffer() call.
131 // The width and height parameters must be no greater than the minimum of
132 // GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see: glGetIntegerv).
133 // An error due to invalid dimensions might not be reported until
134 // updateTexImage() is called. If width and height are both zero, the
135 // default values specified by setDefaultBufferSize() are used instead.
137 // The pixel formats are enumerated in <graphics.h>, e.g.
138 // HAL_PIXEL_FORMAT_RGBA_8888. If the format is 0, the default format
141 // The usage argument specifies gralloc buffer usage flags. The values
142 // are enumerated in <gralloc.h>, e.g. GRALLOC_USAGE_HW_RENDER. These
143 // will be merged with the usage flags specified by
144 // IGraphicBufferConsumer::setConsumerUsageBits.
146 // This call will block until a buffer is available to be dequeued. If
147 // both the producer and consumer are controlled by the app, then this call
148 // can never block and will return WOULD_BLOCK if no buffer is available.
150 // A non-negative value with flags set (see above) will be returned upon
153 // Return of a negative means an error has occurred:
154 // * NO_INIT - the buffer queue has been abandoned.
155 // * BAD_VALUE - both in async mode and buffer count was less than the
156 // max numbers of buffers that can be allocated at once.
157 // * INVALID_OPERATION - cannot attach the buffer because it would cause
158 // too many buffers to be dequeued, either because
159 // the producer already has a single buffer dequeued
160 // and did not set a buffer count, or because a
161 // buffer count was set and this call would cause
162 // it to be exceeded.
163 // * WOULD_BLOCK - no buffer is currently available, and blocking is disabled
164 // since both the producer/consumer are controlled by app
165 // * NO_MEMORY - out of memory, cannot allocate the graphics buffer.
167 // All other negative values are an unknown error returned downstream
168 // from the graphics allocator (typically errno).
169 virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, bool async,
170 uint32_t w, uint32_t h, uint32_t format, uint32_t usage) = 0;
172 // detachBuffer attempts to remove all ownership of the buffer in the given
173 // slot from the buffer queue. If this call succeeds, the slot will be
174 // freed, and there will be no way to obtain the buffer from this interface.
175 // The freed slot will remain unallocated until either it is selected to
176 // hold a freshly allocated buffer in dequeueBuffer or a buffer is attached
177 // to the slot. The buffer must have already been dequeued, and the caller
178 // must already possesses the sp<GraphicBuffer> (i.e., must have called
181 // Return of a value other than NO_ERROR means an error has occurred:
182 // * NO_INIT - the buffer queue has been abandoned.
183 // * BAD_VALUE - the given slot number is invalid, either because it is
184 // out of the range [0, NUM_BUFFER_SLOTS), or because the slot
185 // it refers to is not currently dequeued and requested.
186 virtual status_t detachBuffer(int slot) = 0;
188 // detachNextBuffer is equivalent to calling dequeueBuffer, requestBuffer,
189 // and detachBuffer in sequence, except for two things:
191 // 1) It is unnecessary to know the dimensions, format, or usage of the
193 // 2) It will not block, since if it cannot find an appropriate buffer to
194 // return, it will return an error instead.
196 // Only slots that are free but still contain a GraphicBuffer will be
197 // considered, and the oldest of those will be returned. outBuffer is
198 // equivalent to outBuffer from the requestBuffer call, and outFence is
199 // equivalent to fence from the dequeueBuffer call.
201 // Return of a value other than NO_ERROR means an error has occurred:
202 // * NO_INIT - the buffer queue has been abandoned.
203 // * BAD_VALUE - either outBuffer or outFence were NULL.
204 // * NO_MEMORY - no slots were found that were both free and contained a
206 virtual status_t detachNextBuffer(sp<GraphicBuffer>* outBuffer,
207 sp<Fence>* outFence) = 0;
209 // attachBuffer attempts to transfer ownership of a buffer to the buffer
210 // queue. If this call succeeds, it will be as if this buffer was dequeued
211 // from the returned slot number. As such, this call will fail if attaching
212 // this buffer would cause too many buffers to be simultaneously dequeued.
214 // If attachBuffer returns the RELEASE_ALL_BUFFERS flag, the caller is
215 // expected to release all of the mirrored slot->buffer mappings.
217 // A non-negative value with flags set (see above) will be returned upon
220 // Return of a negative value means an error has occurred:
221 // * NO_INIT - the buffer queue has been abandoned.
222 // * BAD_VALUE - outSlot or buffer were NULL or invalid combination of
223 // async mode and buffer count override.
224 // * INVALID_OPERATION - cannot attach the buffer because it would cause
225 // too many buffers to be dequeued, either because
226 // the producer already has a single buffer dequeued
227 // and did not set a buffer count, or because a
228 // buffer count was set and this call would cause
229 // it to be exceeded.
230 // * WOULD_BLOCK - no buffer slot is currently available, and blocking is
231 // disabled since both the producer/consumer are
232 // controlled by the app.
233 virtual status_t attachBuffer(int* outSlot,
234 const sp<GraphicBuffer>& buffer) = 0;
236 // queueBuffer indicates that the client has finished filling in the
237 // contents of the buffer associated with slot and transfers ownership of
238 // that slot back to the server.
240 // It is not valid to call queueBuffer on a slot that is not owned
241 // by the client or one for which a buffer associated via requestBuffer
242 // (an attempt to do so will fail with a return value of BAD_VALUE).
244 // In addition, the input must be described by the client (as documented
245 // below). Any other properties (zero point, etc)
246 // are client-dependent, and should be documented by the client.
248 // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
250 // Upon success, the output will be filled with meaningful values
251 // (refer to the documentation below).
253 // Return of a value other than NO_ERROR means an error has occurred:
254 // * NO_INIT - the buffer queue has been abandoned.
255 // * BAD_VALUE - one of the below conditions occurred:
257 // * scaling mode was unknown
258 // * both in async mode and buffer count was less than the
259 // max numbers of buffers that can be allocated at once
260 // * slot index was out of range (see above).
261 // * the slot was not in the dequeued state
262 // * the slot was enqueued without requesting a buffer
263 // * crop rect is out of bounds of the buffer dimensions
265 struct QueueBufferInput : public Flattenable<QueueBufferInput> {
266 friend class Flattenable<QueueBufferInput>;
267 inline QueueBufferInput(const Parcel& parcel);
268 // timestamp - a monotonically increasing value in nanoseconds
269 // isAutoTimestamp - if the timestamp was synthesized at queue time
270 // crop - a crop rectangle that's used as a hint to the consumer
271 // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h>
272 // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h>
273 // async - if the buffer is queued in asynchronous mode
274 // fence - a fence that the consumer must wait on before reading the buffer,
275 // set this to Fence::NO_FENCE if the buffer is ready immediately
276 // sticky - the sticky transform set in Surface (only used by the LEGACY
278 inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp,
279 const Rect& crop, int scalingMode, uint32_t transform, bool async,
280 const sp<Fence>& fence, uint32_t sticky = 0)
281 : timestamp(timestamp), isAutoTimestamp(isAutoTimestamp), crop(crop),
282 scalingMode(scalingMode), transform(transform), stickyTransform(sticky),
283 async(async), fence(fence) { }
284 inline void deflate(int64_t* outTimestamp, bool* outIsAutoTimestamp,
285 Rect* outCrop, int* outScalingMode, uint32_t* outTransform,
286 bool* outAsync, sp<Fence>* outFence,
287 uint32_t* outStickyTransform = NULL) const {
288 *outTimestamp = timestamp;
289 *outIsAutoTimestamp = bool(isAutoTimestamp);
291 *outScalingMode = scalingMode;
292 *outTransform = transform;
293 *outAsync = bool(async);
295 if (outStickyTransform != NULL) {
296 *outStickyTransform = stickyTransform;
300 // Flattenable protocol
301 size_t getFlattenedSize() const;
302 size_t getFdCount() const;
303 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const;
304 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count);
312 uint32_t stickyTransform;
317 // QueueBufferOutput must be a POD structure
318 struct __attribute__ ((__packed__)) QueueBufferOutput {
319 inline QueueBufferOutput() { }
320 // outWidth - filled with default width applied to the buffer
321 // outHeight - filled with default height applied to the buffer
322 // outTransformHint - filled with default transform applied to the buffer
323 // outNumPendingBuffers - num buffers queued that haven't yet been acquired
324 // (counting the currently queued buffer)
325 inline void deflate(uint32_t* outWidth,
327 uint32_t* outTransformHint,
328 uint32_t* outNumPendingBuffers) const {
331 *outTransformHint = transformHint;
332 *outNumPendingBuffers = numPendingBuffers;
334 inline void inflate(uint32_t inWidth, uint32_t inHeight,
335 uint32_t inTransformHint, uint32_t inNumPendingBuffers) {
338 transformHint = inTransformHint;
339 numPendingBuffers = inNumPendingBuffers;
344 uint32_t transformHint;
345 uint32_t numPendingBuffers;
348 virtual status_t queueBuffer(int slot,
349 const QueueBufferInput& input, QueueBufferOutput* output) = 0;
351 // cancelBuffer indicates that the client does not wish to fill in the
352 // buffer associated with slot and transfers ownership of the slot back to
355 // The buffer is not queued for use by the consumer.
357 // The buffer will not be overwritten until the fence signals. The fence
358 // will usually be the one obtained from dequeueBuffer.
359 virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0;
361 // query retrieves some information for this surface
362 // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h>
364 // Return of a value other than NO_ERROR means an error has occurred:
365 // * NO_INIT - the buffer queue has been abandoned.
366 // * BAD_VALUE - what was out of range
367 virtual int query(int what, int* value) = 0;
369 // connect attempts to connect a client API to the IGraphicBufferProducer.
370 // This must be called before any other IGraphicBufferProducer methods are
371 // called except for getAllocator. A consumer must be already connected.
373 // This method will fail if the connect was previously called on the
374 // IGraphicBufferProducer and no corresponding disconnect call was made.
376 // The listener is an optional binder callback object that can be used if
377 // the producer wants to be notified when the consumer releases a buffer
378 // back to the BufferQueue. It is also used to detect the death of the
379 // producer. If only the latter functionality is desired, there is a
380 // DummyProducerListener class in IProducerListener.h that can be used.
382 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
384 // The producerControlledByApp should be set to true if the producer is hosted
385 // by an untrusted process (typically app_process-forked processes). If both
386 // the producer and the consumer are app-controlled then all buffer queues
387 // will operate in async mode regardless of the async flag.
389 // Upon success, the output will be filled with meaningful data
390 // (refer to QueueBufferOutput documentation above).
392 // Return of a value other than NO_ERROR means an error has occurred:
393 // * NO_INIT - one of the following occurred:
394 // * the buffer queue was abandoned
395 // * no consumer has yet connected
396 // * BAD_VALUE - one of the following has occurred:
397 // * the producer is already connected
398 // * api was out of range (see above).
399 // * output was NULL.
400 // * DEAD_OBJECT - the token is hosted by an already-dead process
402 // Additional negative errors may be returned by the internals, they
403 // should be treated as opaque fatal unrecoverable errors.
404 virtual status_t connect(const sp<IProducerListener>& listener,
405 int api, bool producerControlledByApp, QueueBufferOutput* output) = 0;
407 // disconnect attempts to disconnect a client API from the
408 // IGraphicBufferProducer. Calling this method will cause any subsequent
409 // calls to other IGraphicBufferProducer methods to fail except for
410 // getAllocator and connect. Successfully calling connect after this will
411 // allow the other methods to succeed again.
413 // This method will fail if the the IGraphicBufferProducer is not currently
414 // connected to the specified client API.
416 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
418 // Disconnecting from an abandoned IGraphicBufferProducer is legal and
419 // is considered a no-op.
421 // Return of a value other than NO_ERROR means an error has occurred:
422 // * BAD_VALUE - one of the following has occurred:
423 // * the api specified does not match the one that was connected
424 // * api was out of range (see above).
425 // * DEAD_OBJECT - the token is hosted by an already-dead process
426 virtual status_t disconnect(int api) = 0;
428 // Attaches a sideband buffer stream to the IGraphicBufferProducer.
430 // A sideband stream is a device-specific mechanism for passing buffers
431 // from the producer to the consumer without using dequeueBuffer/
432 // queueBuffer. If a sideband stream is present, the consumer can choose
433 // whether to acquire buffers from the sideband stream or from the queued
436 // Passing NULL or a different stream handle will detach the previous
438 virtual status_t setSidebandStream(const sp<NativeHandle>& stream) = 0;
440 // Allocates buffers based on the given dimensions/format.
442 // This function will allocate up to the maximum number of buffers
443 // permitted by the current BufferQueue configuration. It will use the
444 // given format, dimensions, and usage bits, which are interpreted in the
445 // same way as for dequeueBuffer, and the async flag must be set the same
446 // way as for dequeueBuffer to ensure that the correct number of buffers are
447 // allocated. This is most useful to avoid an allocation delay during
448 // dequeueBuffer. If there are already the maximum number of buffers
449 // allocated, this function has no effect.
450 virtual void allocateBuffers(bool async, uint32_t width, uint32_t height,
451 uint32_t format, uint32_t usage) = 0;
454 // ----------------------------------------------------------------------------
456 class BnGraphicBufferProducer : public BnInterface<IGraphicBufferProducer>
459 virtual status_t onTransact( uint32_t code,
465 // ----------------------------------------------------------------------------
466 }; // namespace android
468 #endif // ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H