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>
31 #include <ui/Region.h>
34 // ----------------------------------------------------------------------------
36 class IProducerListener;
41 * This class defines the Binder IPC interface for the producer side of
42 * a queue of graphics buffers. It's used to send graphics data from one
43 * component to another. For example, a class that decodes video for
44 * playback might use this to provide frames. This is typically done
45 * indirectly, through Surface.
47 * The underlying mechanism is a BufferQueue, which implements
48 * BnGraphicBufferProducer. In normal operation, the producer calls
49 * dequeueBuffer() to get an empty buffer, fills it with data, then
50 * calls queueBuffer() to make it available to the consumer.
52 * This class was previously called ISurfaceTexture.
54 class IGraphicBufferProducer : public IInterface
57 DECLARE_META_INTERFACE(GraphicBufferProducer);
60 // A flag returned by dequeueBuffer when the client needs to call
61 // requestBuffer immediately thereafter.
62 BUFFER_NEEDS_REALLOCATION = 0x1,
63 // A flag returned by dequeueBuffer when all mirrored slots should be
64 // released by the client. This flag should always be processed first.
65 RELEASE_ALL_BUFFERS = 0x2,
68 // requestBuffer requests a new buffer for the given index. The server (i.e.
69 // the IGraphicBufferProducer implementation) assigns the newly created
70 // buffer to the given slot index, and the client is expected to mirror the
71 // slot->buffer mapping so that it's not necessary to transfer a
72 // GraphicBuffer for every dequeue operation.
74 // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
76 // Return of a value other than NO_ERROR means an error has occurred:
77 // * NO_INIT - the buffer queue has been abandoned or the producer is not
79 // * BAD_VALUE - one of the two conditions occurred:
80 // * slot was out of range (see above)
81 // * buffer specified by the slot is not dequeued
82 virtual status_t requestBuffer(int slot, sp<GraphicBuffer>* buf) = 0;
84 // setMaxDequeuedBufferCount sets the maximum number of buffers that can be
85 // dequeued by the producer at one time. If this method succeeds, any new
86 // buffer slots will be both unallocated and owned by the BufferQueue object
87 // (i.e. they are not owned by the producer or consumer). Calling this may
88 // also cause some buffer slots to be emptied. If the caller is caching the
89 // contents of the buffer slots, it should empty that cache after calling
92 // This function should not be called with a value of maxDequeuedBuffers
93 // that is less than the number of currently dequeued buffer slots. Doing so
94 // will result in a BAD_VALUE error.
96 // The buffer count should be at least 1 (inclusive), but at most
97 // (NUM_BUFFER_SLOTS - the minimum undequeued buffer count) (exclusive). The
98 // minimum undequeued buffer count can be obtained by calling
99 // query(NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS).
101 // Return of a value other than NO_ERROR means an error has occurred:
102 // * NO_INIT - the buffer queue has been abandoned.
103 // * BAD_VALUE - one of the below conditions occurred:
104 // * bufferCount was out of range (see above).
105 // * client would have more than the requested number of dequeued
106 // buffers after this call.
107 // * this call would cause the maxBufferCount value to be exceeded.
108 // * failure to adjust the number of available slots.
109 virtual status_t setMaxDequeuedBufferCount(int maxDequeuedBuffers) = 0;
111 // Set the async flag if the producer intends to asynchronously queue
112 // buffers without blocking. Typically this is used for triple-buffering
113 // and/or when the swap interval is set to zero.
115 // Enabling async mode will internally allocate an additional buffer to
116 // allow for the asynchronous behavior. If it is not enabled queue/dequeue
119 // Return of a value other than NO_ERROR means an error has occurred:
120 // * NO_INIT - the buffer queue has been abandoned.
121 // * BAD_VALUE - one of the following has occurred:
122 // * this call would cause the maxBufferCount value to be
124 // * failure to adjust the number of available slots.
125 virtual status_t setAsyncMode(bool async) = 0;
127 // dequeueBuffer requests a new buffer slot for the client to use. Ownership
128 // of the slot is transfered to the client, meaning that the server will not
129 // use the contents of the buffer associated with that slot.
131 // The slot index returned may or may not contain a buffer (client-side).
132 // If the slot is empty the client should call requestBuffer to assign a new
133 // buffer to that slot.
135 // Once the client is done filling this buffer, it is expected to transfer
136 // buffer ownership back to the server with either cancelBuffer on
137 // the dequeued slot or to fill in the contents of its associated buffer
138 // contents and call queueBuffer.
140 // If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is
141 // expected to call requestBuffer immediately.
143 // If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is
144 // expected to release all of the mirrored slot->buffer mappings.
146 // The fence parameter will be updated to hold the fence associated with
147 // the buffer. The contents of the buffer must not be overwritten until the
148 // fence signals. If the fence is Fence::NO_FENCE, the buffer may be written
151 // The width and height parameters must be no greater than the minimum of
152 // GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see: glGetIntegerv).
153 // An error due to invalid dimensions might not be reported until
154 // updateTexImage() is called. If width and height are both zero, the
155 // default values specified by setDefaultBufferSize() are used instead.
157 // If the format is 0, the default format will be used.
159 // The usage argument specifies gralloc buffer usage flags. The values
160 // are enumerated in <gralloc.h>, e.g. GRALLOC_USAGE_HW_RENDER. These
161 // will be merged with the usage flags specified by
162 // IGraphicBufferConsumer::setConsumerUsageBits.
164 // This call will block until a buffer is available to be dequeued. If
165 // both the producer and consumer are controlled by the app, then this call
166 // can never block and will return WOULD_BLOCK if no buffer is available.
168 // A non-negative value with flags set (see above) will be returned upon
171 // Return of a negative means an error has occurred:
172 // * NO_INIT - the buffer queue has been abandoned or the producer is not
174 // * BAD_VALUE - both in async mode and buffer count was less than the
175 // max numbers of buffers that can be allocated at once.
176 // * INVALID_OPERATION - cannot attach the buffer because it would cause
177 // too many buffers to be dequeued, either because
178 // the producer already has a single buffer dequeued
179 // and did not set a buffer count, or because a
180 // buffer count was set and this call would cause
181 // it to be exceeded.
182 // * WOULD_BLOCK - no buffer is currently available, and blocking is disabled
183 // since both the producer/consumer are controlled by app
184 // * NO_MEMORY - out of memory, cannot allocate the graphics buffer.
185 // * TIMED_OUT - the timeout set by setDequeueTimeout was exceeded while
186 // waiting for a buffer to become available.
188 // All other negative values are an unknown error returned downstream
189 // from the graphics allocator (typically errno).
190 virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, uint32_t w,
191 uint32_t h, PixelFormat format, uint32_t usage) = 0;
193 // detachBuffer attempts to remove all ownership of the buffer in the given
194 // slot from the buffer queue. If this call succeeds, the slot will be
195 // freed, and there will be no way to obtain the buffer from this interface.
196 // The freed slot will remain unallocated until either it is selected to
197 // hold a freshly allocated buffer in dequeueBuffer or a buffer is attached
198 // to the slot. The buffer must have already been dequeued, and the caller
199 // must already possesses the sp<GraphicBuffer> (i.e., must have called
202 // Return of a value other than NO_ERROR means an error has occurred:
203 // * NO_INIT - the buffer queue has been abandoned or the producer is not
205 // * BAD_VALUE - the given slot number is invalid, either because it is
206 // out of the range [0, NUM_BUFFER_SLOTS), or because the slot
207 // it refers to is not currently dequeued and requested.
208 virtual status_t detachBuffer(int slot) = 0;
210 // detachNextBuffer is equivalent to calling dequeueBuffer, requestBuffer,
211 // and detachBuffer in sequence, except for two things:
213 // 1) It is unnecessary to know the dimensions, format, or usage of the
215 // 2) It will not block, since if it cannot find an appropriate buffer to
216 // return, it will return an error instead.
218 // Only slots that are free but still contain a GraphicBuffer will be
219 // considered, and the oldest of those will be returned. outBuffer is
220 // equivalent to outBuffer from the requestBuffer call, and outFence is
221 // equivalent to fence from the dequeueBuffer call.
223 // Return of a value other than NO_ERROR means an error has occurred:
224 // * NO_INIT - the buffer queue has been abandoned or the producer is not
226 // * BAD_VALUE - either outBuffer or outFence were NULL.
227 // * NO_MEMORY - no slots were found that were both free and contained a
229 virtual status_t detachNextBuffer(sp<GraphicBuffer>* outBuffer,
230 sp<Fence>* outFence) = 0;
232 // attachBuffer attempts to transfer ownership of a buffer to the buffer
233 // queue. If this call succeeds, it will be as if this buffer was dequeued
234 // from the returned slot number. As such, this call will fail if attaching
235 // this buffer would cause too many buffers to be simultaneously dequeued.
237 // If attachBuffer returns the RELEASE_ALL_BUFFERS flag, the caller is
238 // expected to release all of the mirrored slot->buffer mappings.
240 // A non-negative value with flags set (see above) will be returned upon
243 // Return of a negative value means an error has occurred:
244 // * NO_INIT - the buffer queue has been abandoned or the producer is not
246 // * BAD_VALUE - outSlot or buffer were NULL, invalid combination of
247 // async mode and buffer count override, or the generation
248 // number of the buffer did not match the buffer queue.
249 // * INVALID_OPERATION - cannot attach the buffer because it would cause
250 // too many buffers to be dequeued, either because
251 // the producer already has a single buffer dequeued
252 // and did not set a buffer count, or because a
253 // buffer count was set and this call would cause
254 // it to be exceeded.
255 // * WOULD_BLOCK - no buffer slot is currently available, and blocking is
256 // disabled since both the producer/consumer are
257 // controlled by the app.
258 // * TIMED_OUT - the timeout set by setDequeueTimeout was exceeded while
259 // waiting for a slot to become available.
260 virtual status_t attachBuffer(int* outSlot,
261 const sp<GraphicBuffer>& buffer) = 0;
263 // queueBuffer indicates that the client has finished filling in the
264 // contents of the buffer associated with slot and transfers ownership of
265 // that slot back to the server.
267 // It is not valid to call queueBuffer on a slot that is not owned
268 // by the client or one for which a buffer associated via requestBuffer
269 // (an attempt to do so will fail with a return value of BAD_VALUE).
271 // In addition, the input must be described by the client (as documented
272 // below). Any other properties (zero point, etc)
273 // are client-dependent, and should be documented by the client.
275 // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
277 // Upon success, the output will be filled with meaningful values
278 // (refer to the documentation below).
280 // Return of a value other than NO_ERROR means an error has occurred:
281 // * NO_INIT - the buffer queue has been abandoned or the producer is not
283 // * BAD_VALUE - one of the below conditions occurred:
285 // * scaling mode was unknown
286 // * both in async mode and buffer count was less than the
287 // max numbers of buffers that can be allocated at once
288 // * slot index was out of range (see above).
289 // * the slot was not in the dequeued state
290 // * the slot was enqueued without requesting a buffer
291 // * crop rect is out of bounds of the buffer dimensions
293 struct QueueBufferInput : public Flattenable<QueueBufferInput> {
294 friend class Flattenable<QueueBufferInput>;
295 inline QueueBufferInput(const Parcel& parcel);
296 // timestamp - a monotonically increasing value in nanoseconds
297 // isAutoTimestamp - if the timestamp was synthesized at queue time
298 // dataSpace - description of the contents, interpretation depends on format
299 // crop - a crop rectangle that's used as a hint to the consumer
300 // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h>
301 // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h>
302 // fence - a fence that the consumer must wait on before reading the buffer,
303 // set this to Fence::NO_FENCE if the buffer is ready immediately
304 // sticky - the sticky transform set in Surface (only used by the LEGACY
306 inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp,
307 android_dataspace dataSpace, const Rect& crop, int scalingMode,
308 uint32_t transform, const sp<Fence>& fence, uint32_t sticky = 0)
309 : timestamp(timestamp), isAutoTimestamp(isAutoTimestamp),
310 dataSpace(dataSpace), crop(crop), scalingMode(scalingMode),
311 transform(transform), stickyTransform(sticky), fence(fence),
313 inline void deflate(int64_t* outTimestamp, bool* outIsAutoTimestamp,
314 android_dataspace* outDataSpace,
315 Rect* outCrop, int* outScalingMode,
316 uint32_t* outTransform, sp<Fence>* outFence,
317 uint32_t* outStickyTransform = NULL) const {
318 *outTimestamp = timestamp;
319 *outIsAutoTimestamp = bool(isAutoTimestamp);
320 *outDataSpace = dataSpace;
322 *outScalingMode = scalingMode;
323 *outTransform = transform;
325 if (outStickyTransform != NULL) {
326 *outStickyTransform = stickyTransform;
330 // Flattenable protocol
331 size_t getFlattenedSize() const;
332 size_t getFdCount() const;
333 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const;
334 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count);
336 const Region& getSurfaceDamage() const { return surfaceDamage; }
337 void setSurfaceDamage(const Region& damage) { surfaceDamage = damage; }
342 android_dataspace dataSpace;
346 uint32_t stickyTransform;
348 Region surfaceDamage;
351 // QueueBufferOutput must be a POD structure
352 struct __attribute__ ((__packed__)) QueueBufferOutput {
353 inline QueueBufferOutput() { }
354 // outWidth - filled with default width applied to the buffer
355 // outHeight - filled with default height applied to the buffer
356 // outTransformHint - filled with default transform applied to the buffer
357 // outNumPendingBuffers - num buffers queued that haven't yet been acquired
358 // (counting the currently queued buffer)
359 inline void deflate(uint32_t* outWidth,
361 uint32_t* outTransformHint,
362 uint32_t* outNumPendingBuffers) const {
365 *outTransformHint = transformHint;
366 *outNumPendingBuffers = numPendingBuffers;
368 inline void inflate(uint32_t inWidth, uint32_t inHeight,
369 uint32_t inTransformHint, uint32_t inNumPendingBuffers) {
372 transformHint = inTransformHint;
373 numPendingBuffers = inNumPendingBuffers;
378 uint32_t transformHint;
379 uint32_t numPendingBuffers;
382 virtual status_t queueBuffer(int slot, const QueueBufferInput& input,
383 QueueBufferOutput* output) = 0;
385 // cancelBuffer indicates that the client does not wish to fill in the
386 // buffer associated with slot and transfers ownership of the slot back to
389 // The buffer is not queued for use by the consumer.
391 // The slot must be in the range of [0, NUM_BUFFER_SLOTS).
393 // The buffer will not be overwritten until the fence signals. The fence
394 // will usually be the one obtained from dequeueBuffer.
396 // Return of a value other than NO_ERROR means an error has occurred:
397 // * NO_INIT - the buffer queue has been abandoned or the producer is not
399 // * BAD_VALUE - one of the below conditions occurred:
401 // * slot index was out of range (see above).
402 // * the slot was not in the dequeued state
403 virtual status_t cancelBuffer(int slot, const sp<Fence>& fence) = 0;
405 // query retrieves some information for this surface
406 // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h>
408 // Return of a value other than NO_ERROR means an error has occurred:
409 // * NO_INIT - the buffer queue has been abandoned.
410 // * BAD_VALUE - what was out of range
411 virtual int query(int what, int* value) = 0;
413 // connect attempts to connect a client API to the IGraphicBufferProducer.
414 // This must be called before any other IGraphicBufferProducer methods are
415 // called except for getAllocator. A consumer must be already connected.
417 // This method will fail if the connect was previously called on the
418 // IGraphicBufferProducer and no corresponding disconnect call was made.
420 // The listener is an optional binder callback object that can be used if
421 // the producer wants to be notified when the consumer releases a buffer
422 // back to the BufferQueue. It is also used to detect the death of the
423 // producer. If only the latter functionality is desired, there is a
424 // DummyProducerListener class in IProducerListener.h that can be used.
426 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
428 // The producerControlledByApp should be set to true if the producer is hosted
429 // by an untrusted process (typically app_process-forked processes). If both
430 // the producer and the consumer are app-controlled then all buffer queues
431 // will operate in async mode regardless of the async flag.
433 // Upon success, the output will be filled with meaningful data
434 // (refer to QueueBufferOutput documentation above).
436 // Return of a value other than NO_ERROR means an error has occurred:
437 // * NO_INIT - one of the following occurred:
438 // * the buffer queue was abandoned
439 // * no consumer has yet connected
440 // * BAD_VALUE - one of the following has occurred:
441 // * the producer is already connected
442 // * api was out of range (see above).
443 // * output was NULL.
444 // * Failure to adjust the number of available slots. This can
445 // happen because of trying to allocate/deallocate the async
446 // buffer in response to the value of producerControlledByApp.
447 // * DEAD_OBJECT - the token is hosted by an already-dead process
449 // Additional negative errors may be returned by the internals, they
450 // should be treated as opaque fatal unrecoverable errors.
451 virtual status_t connect(const sp<IProducerListener>& listener,
452 int api, bool producerControlledByApp, QueueBufferOutput* output) = 0;
454 // disconnect attempts to disconnect a client API from the
455 // IGraphicBufferProducer. Calling this method will cause any subsequent
456 // calls to other IGraphicBufferProducer methods to fail except for
457 // getAllocator and connect. Successfully calling connect after this will
458 // allow the other methods to succeed again.
460 // This method will fail if the the IGraphicBufferProducer is not currently
461 // connected to the specified client API.
463 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h>
465 // Disconnecting from an abandoned IGraphicBufferProducer is legal and
466 // is considered a no-op.
468 // Return of a value other than NO_ERROR means an error has occurred:
469 // * BAD_VALUE - one of the following has occurred:
470 // * the api specified does not match the one that was connected
471 // * api was out of range (see above).
472 // * DEAD_OBJECT - the token is hosted by an already-dead process
473 virtual status_t disconnect(int api) = 0;
475 // Attaches a sideband buffer stream to the IGraphicBufferProducer.
477 // A sideband stream is a device-specific mechanism for passing buffers
478 // from the producer to the consumer without using dequeueBuffer/
479 // queueBuffer. If a sideband stream is present, the consumer can choose
480 // whether to acquire buffers from the sideband stream or from the queued
483 // Passing NULL or a different stream handle will detach the previous
485 virtual status_t setSidebandStream(const sp<NativeHandle>& stream) = 0;
487 // Allocates buffers based on the given dimensions/format.
489 // This function will allocate up to the maximum number of buffers
490 // permitted by the current BufferQueue configuration. It will use the
491 // given format, dimensions, and usage bits, which are interpreted in the
492 // same way as for dequeueBuffer, and the async flag must be set the same
493 // way as for dequeueBuffer to ensure that the correct number of buffers are
494 // allocated. This is most useful to avoid an allocation delay during
495 // dequeueBuffer. If there are already the maximum number of buffers
496 // allocated, this function has no effect.
497 virtual void allocateBuffers(uint32_t width, uint32_t height,
498 PixelFormat format, uint32_t usage) = 0;
500 // Sets whether dequeueBuffer is allowed to allocate new buffers.
502 // Normally dequeueBuffer does not discriminate between free slots which
503 // already have an allocated buffer and those which do not, and will
504 // allocate a new buffer if the slot doesn't have a buffer or if the slot's
505 // buffer doesn't match the requested size, format, or usage. This method
506 // allows the producer to restrict the eligible slots to those which already
507 // have an allocated buffer of the correct size, format, and usage. If no
508 // eligible slot is available, dequeueBuffer will block or return an error
510 virtual status_t allowAllocation(bool allow) = 0;
512 // Sets the current generation number of the BufferQueue.
514 // This generation number will be inserted into any buffers allocated by the
515 // BufferQueue, and any attempts to attach a buffer with a different
516 // generation number will fail. Buffers already in the queue are not
517 // affected and will retain their current generation number. The generation
518 // number defaults to 0.
519 virtual status_t setGenerationNumber(uint32_t generationNumber) = 0;
521 // Returns the name of the connected consumer.
522 virtual String8 getConsumerName() const = 0;
524 // Returns the number of the next frame which will be dequeued.
525 virtual uint64_t getNextFrameNumber() const = 0;
527 // Used to enable/disable single buffer mode.
529 // When single buffer mode is enabled the first buffer that is queued or
530 // dequeued will be cached and returned to all subsequent calls to
531 // dequeueBuffer and acquireBuffer. This allows the producer and consumer to
532 // simultaneously access the same buffer.
533 virtual status_t setSingleBufferMode(bool singleBufferMode) = 0;
535 // Used to enable/disable auto-refresh.
537 // Auto refresh has no effect outside of single buffer mode. In single
538 // buffer mode, when enabled, it indicates to the consumer that it should
539 // attempt to acquire buffers even if it is not aware of any being
541 virtual status_t setAutoRefresh(bool autoRefresh) = 0;
543 // Sets how long dequeueBuffer will wait for a buffer to become available
544 // before returning an error (TIMED_OUT).
546 // This timeout also affects the attachBuffer call, which will block if
547 // there is not a free slot available into which the attached buffer can be
550 // By default, the BufferQueue will wait forever, which is indicated by a
551 // timeout of -1. If set (to a value other than -1), this will disable
552 // non-blocking mode and its corresponding spare buffer (which is used to
553 // ensure a buffer is always available).
555 // Return of a value other than NO_ERROR means an error has occurred:
556 // * BAD_VALUE - Failure to adjust the number of available slots. This can
557 // happen because of trying to allocate/deallocate the async
559 virtual status_t setDequeueTimeout(nsecs_t timeout) = 0;
562 // ----------------------------------------------------------------------------
564 class BnGraphicBufferProducer : public BnInterface<IGraphicBufferProducer>
567 virtual status_t onTransact( uint32_t code,
573 // ----------------------------------------------------------------------------
574 }; // namespace android
576 #endif // ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H