IGraphicBufferProducer.h revision 82c6bcc9705eabcaf5b9e45bc81867b0e2d61a02
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 32namespace android { 33// ---------------------------------------------------------------------------- 34 35class IProducerListener; 36class NativeHandle; 37class Surface; 38 39/* 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. 45 * 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. 50 * 51 * This class was previously called ISurfaceTexture. 52 */ 53class IGraphicBufferProducer : public IInterface 54{ 55public: 56 DECLARE_META_INTERFACE(GraphicBufferProducer); 57 58 enum { 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, 65 }; 66 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. 72 // 73 // The slot must be in the range of [0, NUM_BUFFER_SLOTS). 74 // 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; 81 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. 85 // 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. 88 // 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]. 93 // 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. 96 // 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; 103 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. 107 // 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. 111 // 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. 116 // 117 // If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is 118 // expected to call requestBuffer immediately. 119 // 120 // If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is 121 // expected to release all of the mirrored slot->buffer mappings. 122 // 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 126 // immediately. 127 // 128 // The async parameter sets whether we're in asynchronous mode for this 129 // dequeueBuffer() call. 130 // 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. 136 // 137 // If the format is 0, the default format will be used. 138 // 139 // The usage argument specifies gralloc buffer usage flags. The values 140 // are enumerated in <gralloc.h>, e.g. GRALLOC_USAGE_HW_RENDER. These 141 // will be merged with the usage flags specified by 142 // IGraphicBufferConsumer::setConsumerUsageBits. 143 // 144 // This call will block until a buffer is available to be dequeued. If 145 // both the producer and consumer are controlled by the app, then this call 146 // can never block and will return WOULD_BLOCK if no buffer is available. 147 // 148 // A non-negative value with flags set (see above) will be returned upon 149 // success. 150 // 151 // Return of a negative means an error has occurred: 152 // * NO_INIT - the buffer queue has been abandoned. 153 // * BAD_VALUE - both in async mode and buffer count was less than the 154 // max numbers of buffers that can be allocated at once. 155 // * INVALID_OPERATION - cannot attach the buffer because it would cause 156 // too many buffers to be dequeued, either because 157 // the producer already has a single buffer dequeued 158 // and did not set a buffer count, or because a 159 // buffer count was set and this call would cause 160 // it to be exceeded. 161 // * WOULD_BLOCK - no buffer is currently available, and blocking is disabled 162 // since both the producer/consumer are controlled by app 163 // * NO_MEMORY - out of memory, cannot allocate the graphics buffer. 164 // 165 // All other negative values are an unknown error returned downstream 166 // from the graphics allocator (typically errno). 167 virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, bool async, 168 uint32_t w, uint32_t h, PixelFormat format, uint32_t usage) = 0; 169 170 // detachBuffer attempts to remove all ownership of the buffer in the given 171 // slot from the buffer queue. If this call succeeds, the slot will be 172 // freed, and there will be no way to obtain the buffer from this interface. 173 // The freed slot will remain unallocated until either it is selected to 174 // hold a freshly allocated buffer in dequeueBuffer or a buffer is attached 175 // to the slot. The buffer must have already been dequeued, and the caller 176 // must already possesses the sp<GraphicBuffer> (i.e., must have called 177 // requestBuffer). 178 // 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 - the given slot number is invalid, either because it is 182 // out of the range [0, NUM_BUFFER_SLOTS), or because the slot 183 // it refers to is not currently dequeued and requested. 184 virtual status_t detachBuffer(int slot) = 0; 185 186 // detachNextBuffer is equivalent to calling dequeueBuffer, requestBuffer, 187 // and detachBuffer in sequence, except for two things: 188 // 189 // 1) It is unnecessary to know the dimensions, format, or usage of the 190 // next buffer. 191 // 2) It will not block, since if it cannot find an appropriate buffer to 192 // return, it will return an error instead. 193 // 194 // Only slots that are free but still contain a GraphicBuffer will be 195 // considered, and the oldest of those will be returned. outBuffer is 196 // equivalent to outBuffer from the requestBuffer call, and outFence is 197 // equivalent to fence from the dequeueBuffer call. 198 // 199 // Return of a value other than NO_ERROR means an error has occurred: 200 // * NO_INIT - the buffer queue has been abandoned. 201 // * BAD_VALUE - either outBuffer or outFence were NULL. 202 // * NO_MEMORY - no slots were found that were both free and contained a 203 // GraphicBuffer. 204 virtual status_t detachNextBuffer(sp<GraphicBuffer>* outBuffer, 205 sp<Fence>* outFence) = 0; 206 207 // attachBuffer attempts to transfer ownership of a buffer to the buffer 208 // queue. If this call succeeds, it will be as if this buffer was dequeued 209 // from the returned slot number. As such, this call will fail if attaching 210 // this buffer would cause too many buffers to be simultaneously dequeued. 211 // 212 // If attachBuffer returns the RELEASE_ALL_BUFFERS flag, the caller is 213 // expected to release all of the mirrored slot->buffer mappings. 214 // 215 // A non-negative value with flags set (see above) will be returned upon 216 // success. 217 // 218 // Return of a negative value means an error has occurred: 219 // * NO_INIT - the buffer queue has been abandoned. 220 // * BAD_VALUE - outSlot or buffer were NULL or invalid combination of 221 // async mode and buffer count override. 222 // * INVALID_OPERATION - cannot attach the buffer because it would cause 223 // too many buffers to be dequeued, either because 224 // the producer already has a single buffer dequeued 225 // and did not set a buffer count, or because a 226 // buffer count was set and this call would cause 227 // it to be exceeded. 228 // * WOULD_BLOCK - no buffer slot is currently available, and blocking is 229 // disabled since both the producer/consumer are 230 // controlled by the app. 231 virtual status_t attachBuffer(int* outSlot, 232 const sp<GraphicBuffer>& buffer) = 0; 233 234 // queueBuffer indicates that the client has finished filling in the 235 // contents of the buffer associated with slot and transfers ownership of 236 // that slot back to the server. 237 // 238 // It is not valid to call queueBuffer on a slot that is not owned 239 // by the client or one for which a buffer associated via requestBuffer 240 // (an attempt to do so will fail with a return value of BAD_VALUE). 241 // 242 // In addition, the input must be described by the client (as documented 243 // below). Any other properties (zero point, etc) 244 // are client-dependent, and should be documented by the client. 245 // 246 // The slot must be in the range of [0, NUM_BUFFER_SLOTS). 247 // 248 // Upon success, the output will be filled with meaningful values 249 // (refer to the documentation below). 250 // 251 // Return of a value other than NO_ERROR means an error has occurred: 252 // * NO_INIT - the buffer queue has been abandoned. 253 // * BAD_VALUE - one of the below conditions occurred: 254 // * fence was NULL 255 // * scaling mode was unknown 256 // * both in async mode and buffer count was less than the 257 // max numbers of buffers that can be allocated at once 258 // * slot index was out of range (see above). 259 // * the slot was not in the dequeued state 260 // * the slot was enqueued without requesting a buffer 261 // * crop rect is out of bounds of the buffer dimensions 262 263 struct QueueBufferInput : public Flattenable<QueueBufferInput> { 264 friend class Flattenable<QueueBufferInput>; 265 inline QueueBufferInput(const Parcel& parcel); 266 // timestamp - a monotonically increasing value in nanoseconds 267 // isAutoTimestamp - if the timestamp was synthesized at queue time 268 // dataSpace - description of the contents, interpretation depends on format 269 // crop - a crop rectangle that's used as a hint to the consumer 270 // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h> 271 // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h> 272 // async - if the buffer is queued in asynchronous mode 273 // fence - a fence that the consumer must wait on before reading the buffer, 274 // set this to Fence::NO_FENCE if the buffer is ready immediately 275 // sticky - the sticky transform set in Surface (only used by the LEGACY 276 // camera mode). 277 inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp, 278 android_dataspace dataSpace, const Rect& crop, int scalingMode, 279 uint32_t transform, bool async, const sp<Fence>& fence, 280 uint32_t sticky = 0) 281 : timestamp(timestamp), isAutoTimestamp(isAutoTimestamp), 282 dataSpace(dataSpace), crop(crop), scalingMode(scalingMode), 283 transform(transform), stickyTransform(sticky), 284 async(async), fence(fence) { } 285 inline void deflate(int64_t* outTimestamp, bool* outIsAutoTimestamp, 286 android_dataspace* outDataSpace, 287 Rect* outCrop, int* outScalingMode, 288 uint32_t* outTransform, bool* outAsync, sp<Fence>* outFence, 289 uint32_t* outStickyTransform = NULL) const { 290 *outTimestamp = timestamp; 291 *outIsAutoTimestamp = bool(isAutoTimestamp); 292 *outDataSpace = dataSpace; 293 *outCrop = crop; 294 *outScalingMode = scalingMode; 295 *outTransform = transform; 296 *outAsync = bool(async); 297 *outFence = fence; 298 if (outStickyTransform != NULL) { 299 *outStickyTransform = stickyTransform; 300 } 301 } 302 303 // Flattenable protocol 304 size_t getFlattenedSize() const; 305 size_t getFdCount() const; 306 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const; 307 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count); 308 309 private: 310 int64_t timestamp; 311 int isAutoTimestamp; 312 android_dataspace dataSpace; 313 Rect crop; 314 int scalingMode; 315 uint32_t transform; 316 uint32_t stickyTransform; 317 int async; 318 sp<Fence> fence; 319 }; 320 321 // QueueBufferOutput must be a POD structure 322 struct __attribute__ ((__packed__)) QueueBufferOutput { 323 inline QueueBufferOutput() { } 324 // outWidth - filled with default width applied to the buffer 325 // outHeight - filled with default height applied to the buffer 326 // outTransformHint - filled with default transform applied to the buffer 327 // outNumPendingBuffers - num buffers queued that haven't yet been acquired 328 // (counting the currently queued buffer) 329 inline void deflate(uint32_t* outWidth, 330 uint32_t* outHeight, 331 uint32_t* outTransformHint, 332 uint32_t* outNumPendingBuffers) const { 333 *outWidth = width; 334 *outHeight = height; 335 *outTransformHint = transformHint; 336 *outNumPendingBuffers = numPendingBuffers; 337 } 338 inline void inflate(uint32_t inWidth, uint32_t inHeight, 339 uint32_t inTransformHint, uint32_t inNumPendingBuffers) { 340 width = inWidth; 341 height = inHeight; 342 transformHint = inTransformHint; 343 numPendingBuffers = inNumPendingBuffers; 344 } 345 private: 346 uint32_t width; 347 uint32_t height; 348 uint32_t transformHint; 349 uint32_t numPendingBuffers; 350 }; 351 352 virtual status_t queueBuffer(int slot, 353 const QueueBufferInput& input, QueueBufferOutput* output) = 0; 354 355 // cancelBuffer indicates that the client does not wish to fill in the 356 // buffer associated with slot and transfers ownership of the slot back to 357 // the server. 358 // 359 // The buffer is not queued for use by the consumer. 360 // 361 // The buffer will not be overwritten until the fence signals. The fence 362 // will usually be the one obtained from dequeueBuffer. 363 virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0; 364 365 // query retrieves some information for this surface 366 // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h> 367 // 368 // Return of a value other than NO_ERROR means an error has occurred: 369 // * NO_INIT - the buffer queue has been abandoned. 370 // * BAD_VALUE - what was out of range 371 virtual int query(int what, int* value) = 0; 372 373 // connect attempts to connect a client API to the IGraphicBufferProducer. 374 // This must be called before any other IGraphicBufferProducer methods are 375 // called except for getAllocator. A consumer must be already connected. 376 // 377 // This method will fail if the connect was previously called on the 378 // IGraphicBufferProducer and no corresponding disconnect call was made. 379 // 380 // The listener is an optional binder callback object that can be used if 381 // the producer wants to be notified when the consumer releases a buffer 382 // back to the BufferQueue. It is also used to detect the death of the 383 // producer. If only the latter functionality is desired, there is a 384 // DummyProducerListener class in IProducerListener.h that can be used. 385 // 386 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 387 // 388 // The producerControlledByApp should be set to true if the producer is hosted 389 // by an untrusted process (typically app_process-forked processes). If both 390 // the producer and the consumer are app-controlled then all buffer queues 391 // will operate in async mode regardless of the async flag. 392 // 393 // Upon success, the output will be filled with meaningful data 394 // (refer to QueueBufferOutput documentation above). 395 // 396 // Return of a value other than NO_ERROR means an error has occurred: 397 // * NO_INIT - one of the following occurred: 398 // * the buffer queue was abandoned 399 // * no consumer has yet connected 400 // * BAD_VALUE - one of the following has occurred: 401 // * the producer is already connected 402 // * api was out of range (see above). 403 // * output was NULL. 404 // * DEAD_OBJECT - the token is hosted by an already-dead process 405 // 406 // Additional negative errors may be returned by the internals, they 407 // should be treated as opaque fatal unrecoverable errors. 408 virtual status_t connect(const sp<IProducerListener>& listener, 409 int api, bool producerControlledByApp, QueueBufferOutput* output) = 0; 410 411 // disconnect attempts to disconnect a client API from the 412 // IGraphicBufferProducer. Calling this method will cause any subsequent 413 // calls to other IGraphicBufferProducer methods to fail except for 414 // getAllocator and connect. Successfully calling connect after this will 415 // allow the other methods to succeed again. 416 // 417 // This method will fail if the the IGraphicBufferProducer is not currently 418 // connected to the specified client API. 419 // 420 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 421 // 422 // Disconnecting from an abandoned IGraphicBufferProducer is legal and 423 // is considered a no-op. 424 // 425 // Return of a value other than NO_ERROR means an error has occurred: 426 // * BAD_VALUE - one of the following has occurred: 427 // * the api specified does not match the one that was connected 428 // * api was out of range (see above). 429 // * DEAD_OBJECT - the token is hosted by an already-dead process 430 virtual status_t disconnect(int api) = 0; 431 432 // Attaches a sideband buffer stream to the IGraphicBufferProducer. 433 // 434 // A sideband stream is a device-specific mechanism for passing buffers 435 // from the producer to the consumer without using dequeueBuffer/ 436 // queueBuffer. If a sideband stream is present, the consumer can choose 437 // whether to acquire buffers from the sideband stream or from the queued 438 // buffers. 439 // 440 // Passing NULL or a different stream handle will detach the previous 441 // handle if any. 442 virtual status_t setSidebandStream(const sp<NativeHandle>& stream) = 0; 443 444 // Allocates buffers based on the given dimensions/format. 445 // 446 // This function will allocate up to the maximum number of buffers 447 // permitted by the current BufferQueue configuration. It will use the 448 // given format, dimensions, and usage bits, which are interpreted in the 449 // same way as for dequeueBuffer, and the async flag must be set the same 450 // way as for dequeueBuffer to ensure that the correct number of buffers are 451 // allocated. This is most useful to avoid an allocation delay during 452 // dequeueBuffer. If there are already the maximum number of buffers 453 // allocated, this function has no effect. 454 virtual void allocateBuffers(bool async, uint32_t width, uint32_t height, 455 PixelFormat format, uint32_t usage) = 0; 456}; 457 458// ---------------------------------------------------------------------------- 459 460class BnGraphicBufferProducer : public BnInterface<IGraphicBufferProducer> 461{ 462public: 463 virtual status_t onTransact( uint32_t code, 464 const Parcel& data, 465 Parcel* reply, 466 uint32_t flags = 0); 467}; 468 469// ---------------------------------------------------------------------------- 470}; // namespace android 471 472#endif // ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H 473