1 /* 2 * Copyright (C) 2010 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_IGRAPHICBUFFERPRODUCER_H 18 #define ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H 19 20 #include <stdint.h> 21 #include <sys/types.h> 22 23 #include <utils/Errors.h> 24 #include <utils/RefBase.h> 25 26 #include <binder/IInterface.h> 27 28 #include <ui/Fence.h> 29 #include <ui/GraphicBuffer.h> 30 #include <ui/Rect.h> 31 #include <ui/Region.h> 32 33 namespace android { 34 // ---------------------------------------------------------------------------- 35 36 class IProducerListener; 37 class NativeHandle; 38 class Surface; 39 40 /* 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. 46 * 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. 51 * 52 * This class was previously called ISurfaceTexture. 53 */ 54 class IGraphicBufferProducer : public IInterface 55 { 56 public: 57 DECLARE_META_INTERFACE(GraphicBufferProducer); 58 59 enum { 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, 66 }; 67 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. 73 // 74 // The slot must be in the range of [0, NUM_BUFFER_SLOTS). 75 // 76 // Return of a value other than NO_ERROR means an error has occurred: 77 // * NO_INIT - the buffer queue has been abandoned. 78 // * BAD_VALUE - one of the two conditions occurred: 79 // * slot was out of range (see above) 80 // * buffer specified by the slot is not dequeued 81 virtual status_t requestBuffer(int slot, sp<GraphicBuffer>* buf) = 0; 82 83 // setBufferCount sets the number of buffer slots available. Calling this 84 // will also cause all buffer slots to be emptied. The caller should empty 85 // its mirrored copy of the buffer slots when calling this method. 86 // 87 // This function should not be called when there are any dequeued buffer 88 // slots, doing so will result in a BAD_VALUE error returned. 89 // 90 // The buffer count should be at most NUM_BUFFER_SLOTS (inclusive), but at least 91 // the minimum undequeued buffer count (exclusive). The minimum value 92 // can be obtained by calling query(NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS). 93 // In particular the range is (minUndequeudBuffers, NUM_BUFFER_SLOTS]. 94 // 95 // The buffer count may also be set to 0 (the default), to indicate that 96 // the producer does not wish to set a value. 97 // 98 // Return of a value other than NO_ERROR means an error has occurred: 99 // * NO_INIT - the buffer queue has been abandoned. 100 // * BAD_VALUE - one of the below conditions occurred: 101 // * bufferCount was out of range (see above) 102 // * client has one or more buffers dequeued 103 virtual status_t setBufferCount(int bufferCount) = 0; 104 105 // dequeueBuffer requests a new buffer slot for the client to use. Ownership 106 // of the slot is transfered to the client, meaning that the server will not 107 // use the contents of the buffer associated with that slot. 108 // 109 // The slot index returned may or may not contain a buffer (client-side). 110 // If the slot is empty the client should call requestBuffer to assign a new 111 // buffer to that slot. 112 // 113 // Once the client is done filling this buffer, it is expected to transfer 114 // buffer ownership back to the server with either cancelBuffer on 115 // the dequeued slot or to fill in the contents of its associated buffer 116 // contents and call queueBuffer. 117 // 118 // If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is 119 // expected to call requestBuffer immediately. 120 // 121 // If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is 122 // expected to release all of the mirrored slot->buffer mappings. 123 // 124 // The fence parameter will be updated to hold the fence associated with 125 // the buffer. The contents of the buffer must not be overwritten until the 126 // fence signals. If the fence is Fence::NO_FENCE, the buffer may be written 127 // immediately. 128 // 129 // The async parameter sets whether we're in asynchronous mode for this 130 // dequeueBuffer() call. 131 // 132 // The width and height parameters must be no greater than the minimum of 133 // GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see: glGetIntegerv). 134 // An error due to invalid dimensions might not be reported until 135 // updateTexImage() is called. If width and height are both zero, the 136 // default values specified by setDefaultBufferSize() are used instead. 137 // 138 // If the format is 0, the default format will be used. 139 // 140 // The usage argument specifies gralloc buffer usage flags. The values 141 // are enumerated in <gralloc.h>, e.g. GRALLOC_USAGE_HW_RENDER. These 142 // will be merged with the usage flags specified by 143 // IGraphicBufferConsumer::setConsumerUsageBits. 144 // 145 // This call will block until a buffer is available to be dequeued. If 146 // both the producer and consumer are controlled by the app, then this call 147 // can never block and will return WOULD_BLOCK if no buffer is available. 148 // 149 // A non-negative value with flags set (see above) will be returned upon 150 // success. 151 // 152 // Return of a negative means an error has occurred: 153 // * NO_INIT - the buffer queue has been abandoned. 154 // * BAD_VALUE - both in async mode and buffer count was less than the 155 // max numbers of buffers that can be allocated at once. 156 // * INVALID_OPERATION - cannot attach the buffer because it would cause 157 // too many buffers to be dequeued, either because 158 // the producer already has a single buffer dequeued 159 // and did not set a buffer count, or because a 160 // buffer count was set and this call would cause 161 // it to be exceeded. 162 // * WOULD_BLOCK - no buffer is currently available, and blocking is disabled 163 // since both the producer/consumer are controlled by app 164 // * NO_MEMORY - out of memory, cannot allocate the graphics buffer. 165 // 166 // All other negative values are an unknown error returned downstream 167 // from the graphics allocator (typically errno). 168 virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, bool async, 169 uint32_t w, uint32_t h, PixelFormat format, uint32_t usage) = 0; 170 171 // detachBuffer attempts to remove all ownership of the buffer in the given 172 // slot from the buffer queue. If this call succeeds, the slot will be 173 // freed, and there will be no way to obtain the buffer from this interface. 174 // The freed slot will remain unallocated until either it is selected to 175 // hold a freshly allocated buffer in dequeueBuffer or a buffer is attached 176 // to the slot. The buffer must have already been dequeued, and the caller 177 // must already possesses the sp<GraphicBuffer> (i.e., must have called 178 // requestBuffer). 179 // 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 - the given slot number is invalid, either because it is 183 // out of the range [0, NUM_BUFFER_SLOTS), or because the slot 184 // it refers to is not currently dequeued and requested. 185 virtual status_t detachBuffer(int slot) = 0; 186 187 // detachNextBuffer is equivalent to calling dequeueBuffer, requestBuffer, 188 // and detachBuffer in sequence, except for two things: 189 // 190 // 1) It is unnecessary to know the dimensions, format, or usage of the 191 // next buffer. 192 // 2) It will not block, since if it cannot find an appropriate buffer to 193 // return, it will return an error instead. 194 // 195 // Only slots that are free but still contain a GraphicBuffer will be 196 // considered, and the oldest of those will be returned. outBuffer is 197 // equivalent to outBuffer from the requestBuffer call, and outFence is 198 // equivalent to fence from the dequeueBuffer call. 199 // 200 // Return of a value other than NO_ERROR means an error has occurred: 201 // * NO_INIT - the buffer queue has been abandoned. 202 // * BAD_VALUE - either outBuffer or outFence were NULL. 203 // * NO_MEMORY - no slots were found that were both free and contained a 204 // GraphicBuffer. 205 virtual status_t detachNextBuffer(sp<GraphicBuffer>* outBuffer, 206 sp<Fence>* outFence) = 0; 207 208 // attachBuffer attempts to transfer ownership of a buffer to the buffer 209 // queue. If this call succeeds, it will be as if this buffer was dequeued 210 // from the returned slot number. As such, this call will fail if attaching 211 // this buffer would cause too many buffers to be simultaneously dequeued. 212 // 213 // If attachBuffer returns the RELEASE_ALL_BUFFERS flag, the caller is 214 // expected to release all of the mirrored slot->buffer mappings. 215 // 216 // A non-negative value with flags set (see above) will be returned upon 217 // success. 218 // 219 // Return of a negative value means an error has occurred: 220 // * NO_INIT - the buffer queue has been abandoned. 221 // * BAD_VALUE - outSlot or buffer were NULL, invalid combination of 222 // async mode and buffer count override, or the generation 223 // number of the buffer did not match the buffer queue. 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; 235 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. 239 // 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). 243 // 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. 247 // 248 // The slot must be in the range of [0, NUM_BUFFER_SLOTS). 249 // 250 // Upon success, the output will be filled with meaningful values 251 // (refer to the documentation below). 252 // 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: 256 // * fence was NULL 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 264 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 // dataSpace - description of the contents, interpretation depends on format 271 // crop - a crop rectangle that's used as a hint to the consumer 272 // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h> 273 // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h> 274 // async - if the buffer is queued in asynchronous mode 275 // fence - a fence that the consumer must wait on before reading the buffer, 276 // set this to Fence::NO_FENCE if the buffer is ready immediately 277 // sticky - the sticky transform set in Surface (only used by the LEGACY 278 // camera mode). 279 inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp, 280 android_dataspace dataSpace, const Rect& crop, int scalingMode, 281 uint32_t transform, bool async, const sp<Fence>& fence, 282 uint32_t sticky = 0) 283 : timestamp(timestamp), isAutoTimestamp(isAutoTimestamp), 284 dataSpace(dataSpace), crop(crop), scalingMode(scalingMode), 285 transform(transform), stickyTransform(sticky), 286 async(async), fence(fence), surfaceDamage() { } 287 inline void deflate(int64_t* outTimestamp, bool* outIsAutoTimestamp, 288 android_dataspace* outDataSpace, 289 Rect* outCrop, int* outScalingMode, 290 uint32_t* outTransform, bool* outAsync, sp<Fence>* outFence, 291 uint32_t* outStickyTransform = NULL) const { 292 *outTimestamp = timestamp; 293 *outIsAutoTimestamp = bool(isAutoTimestamp); 294 *outDataSpace = dataSpace; 295 *outCrop = crop; 296 *outScalingMode = scalingMode; 297 *outTransform = transform; 298 *outAsync = bool(async); 299 *outFence = fence; 300 if (outStickyTransform != NULL) { 301 *outStickyTransform = stickyTransform; 302 } 303 } 304 305 // Flattenable protocol 306 size_t getFlattenedSize() const; 307 size_t getFdCount() const; 308 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const; 309 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count); 310 311 const Region& getSurfaceDamage() const { return surfaceDamage; } 312 void setSurfaceDamage(const Region& damage) { surfaceDamage = damage; } 313 314 private: 315 int64_t timestamp; 316 int isAutoTimestamp; 317 android_dataspace dataSpace; 318 Rect crop; 319 int scalingMode; 320 uint32_t transform; 321 uint32_t stickyTransform; 322 int async; 323 sp<Fence> fence; 324 Region surfaceDamage; 325 }; 326 327 // QueueBufferOutput must be a POD structure 328 struct __attribute__ ((__packed__)) QueueBufferOutput { 329 inline QueueBufferOutput() { } 330 // outWidth - filled with default width applied to the buffer 331 // outHeight - filled with default height applied to the buffer 332 // outTransformHint - filled with default transform applied to the buffer 333 // outNumPendingBuffers - num buffers queued that haven't yet been acquired 334 // (counting the currently queued buffer) 335 inline void deflate(uint32_t* outWidth, 336 uint32_t* outHeight, 337 uint32_t* outTransformHint, 338 uint32_t* outNumPendingBuffers) const { 339 *outWidth = width; 340 *outHeight = height; 341 *outTransformHint = transformHint; 342 *outNumPendingBuffers = numPendingBuffers; 343 } 344 inline void inflate(uint32_t inWidth, uint32_t inHeight, 345 uint32_t inTransformHint, uint32_t inNumPendingBuffers) { 346 width = inWidth; 347 height = inHeight; 348 transformHint = inTransformHint; 349 numPendingBuffers = inNumPendingBuffers; 350 } 351 private: 352 uint32_t width; 353 uint32_t height; 354 uint32_t transformHint; 355 uint32_t numPendingBuffers; 356 }; 357 358 virtual status_t queueBuffer(int slot, 359 const QueueBufferInput& input, QueueBufferOutput* output) = 0; 360 361 // cancelBuffer indicates that the client does not wish to fill in the 362 // buffer associated with slot and transfers ownership of the slot back to 363 // the server. 364 // 365 // The buffer is not queued for use by the consumer. 366 // 367 // The buffer will not be overwritten until the fence signals. The fence 368 // will usually be the one obtained from dequeueBuffer. 369 virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0; 370 371 // query retrieves some information for this surface 372 // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h> 373 // 374 // Return of a value other than NO_ERROR means an error has occurred: 375 // * NO_INIT - the buffer queue has been abandoned. 376 // * BAD_VALUE - what was out of range 377 virtual int query(int what, int* value) = 0; 378 379 // connect attempts to connect a client API to the IGraphicBufferProducer. 380 // This must be called before any other IGraphicBufferProducer methods are 381 // called except for getAllocator. A consumer must be already connected. 382 // 383 // This method will fail if the connect was previously called on the 384 // IGraphicBufferProducer and no corresponding disconnect call was made. 385 // 386 // The listener is an optional binder callback object that can be used if 387 // the producer wants to be notified when the consumer releases a buffer 388 // back to the BufferQueue. It is also used to detect the death of the 389 // producer. If only the latter functionality is desired, there is a 390 // DummyProducerListener class in IProducerListener.h that can be used. 391 // 392 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 393 // 394 // The producerControlledByApp should be set to true if the producer is hosted 395 // by an untrusted process (typically app_process-forked processes). If both 396 // the producer and the consumer are app-controlled then all buffer queues 397 // will operate in async mode regardless of the async flag. 398 // 399 // Upon success, the output will be filled with meaningful data 400 // (refer to QueueBufferOutput documentation above). 401 // 402 // Return of a value other than NO_ERROR means an error has occurred: 403 // * NO_INIT - one of the following occurred: 404 // * the buffer queue was abandoned 405 // * no consumer has yet connected 406 // * BAD_VALUE - one of the following has occurred: 407 // * the producer is already connected 408 // * api was out of range (see above). 409 // * output was NULL. 410 // * DEAD_OBJECT - the token is hosted by an already-dead process 411 // 412 // Additional negative errors may be returned by the internals, they 413 // should be treated as opaque fatal unrecoverable errors. 414 virtual status_t connect(const sp<IProducerListener>& listener, 415 int api, bool producerControlledByApp, QueueBufferOutput* output) = 0; 416 417 // disconnect attempts to disconnect a client API from the 418 // IGraphicBufferProducer. Calling this method will cause any subsequent 419 // calls to other IGraphicBufferProducer methods to fail except for 420 // getAllocator and connect. Successfully calling connect after this will 421 // allow the other methods to succeed again. 422 // 423 // This method will fail if the the IGraphicBufferProducer is not currently 424 // connected to the specified client API. 425 // 426 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 427 // 428 // Disconnecting from an abandoned IGraphicBufferProducer is legal and 429 // is considered a no-op. 430 // 431 // Return of a value other than NO_ERROR means an error has occurred: 432 // * BAD_VALUE - one of the following has occurred: 433 // * the api specified does not match the one that was connected 434 // * api was out of range (see above). 435 // * DEAD_OBJECT - the token is hosted by an already-dead process 436 virtual status_t disconnect(int api) = 0; 437 438 // Attaches a sideband buffer stream to the IGraphicBufferProducer. 439 // 440 // A sideband stream is a device-specific mechanism for passing buffers 441 // from the producer to the consumer without using dequeueBuffer/ 442 // queueBuffer. If a sideband stream is present, the consumer can choose 443 // whether to acquire buffers from the sideband stream or from the queued 444 // buffers. 445 // 446 // Passing NULL or a different stream handle will detach the previous 447 // handle if any. 448 virtual status_t setSidebandStream(const sp<NativeHandle>& stream) = 0; 449 450 // Allocates buffers based on the given dimensions/format. 451 // 452 // This function will allocate up to the maximum number of buffers 453 // permitted by the current BufferQueue configuration. It will use the 454 // given format, dimensions, and usage bits, which are interpreted in the 455 // same way as for dequeueBuffer, and the async flag must be set the same 456 // way as for dequeueBuffer to ensure that the correct number of buffers are 457 // allocated. This is most useful to avoid an allocation delay during 458 // dequeueBuffer. If there are already the maximum number of buffers 459 // allocated, this function has no effect. 460 virtual void allocateBuffers(bool async, uint32_t width, uint32_t height, 461 PixelFormat format, uint32_t usage) = 0; 462 463 // Sets whether dequeueBuffer is allowed to allocate new buffers. 464 // 465 // Normally dequeueBuffer does not discriminate between free slots which 466 // already have an allocated buffer and those which do not, and will 467 // allocate a new buffer if the slot doesn't have a buffer or if the slot's 468 // buffer doesn't match the requested size, format, or usage. This method 469 // allows the producer to restrict the eligible slots to those which already 470 // have an allocated buffer of the correct size, format, and usage. If no 471 // eligible slot is available, dequeueBuffer will block or return an error 472 // as usual. 473 virtual status_t allowAllocation(bool allow) = 0; 474 475 // Sets the current generation number of the BufferQueue. 476 // 477 // This generation number will be inserted into any buffers allocated by the 478 // BufferQueue, and any attempts to attach a buffer with a different 479 // generation number will fail. Buffers already in the queue are not 480 // affected and will retain their current generation number. The generation 481 // number defaults to 0. 482 virtual status_t setGenerationNumber(uint32_t generationNumber) = 0; 483 484 // Returns the name of the connected consumer. 485 virtual String8 getConsumerName() const = 0; 486 }; 487 488 // ---------------------------------------------------------------------------- 489 490 class BnGraphicBufferProducer : public BnInterface<IGraphicBufferProducer> 491 { 492 public: 493 virtual status_t onTransact( uint32_t code, 494 const Parcel& data, 495 Parcel* reply, 496 uint32_t flags = 0); 497 }; 498 499 // ---------------------------------------------------------------------------- 500 }; // namespace android 501 502 #endif // ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H 503