IGraphicBufferProducer.h revision 73ed82f809a40560fd3a6d53d18e5c846362d764
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 NativeHandle; 36class Surface; 37 38/* 39 * This class defines the Binder IPC interface for the producer side of 40 * a queue of graphics buffers. It's used to send graphics data from one 41 * component to another. For example, a class that decodes video for 42 * playback might use this to provide frames. This is typically done 43 * indirectly, through Surface. 44 * 45 * The underlying mechanism is a BufferQueue, which implements 46 * BnGraphicBufferProducer. In normal operation, the producer calls 47 * dequeueBuffer() to get an empty buffer, fills it with data, then 48 * calls queueBuffer() to make it available to the consumer. 49 * 50 * This class was previously called ISurfaceTexture. 51 */ 52class IGraphicBufferProducer : public IInterface 53{ 54public: 55 DECLARE_META_INTERFACE(GraphicBufferProducer); 56 57 enum { 58 // A flag returned by dequeueBuffer when the client needs to call 59 // requestBuffer immediately thereafter. 60 BUFFER_NEEDS_REALLOCATION = 0x1, 61 // A flag returned by dequeueBuffer when all mirrored slots should be 62 // released by the client. This flag should always be processed first. 63 RELEASE_ALL_BUFFERS = 0x2, 64 }; 65 66 // requestBuffer requests a new buffer for the given index. The server (i.e. 67 // the IGraphicBufferProducer implementation) assigns the newly created 68 // buffer to the given slot index, and the client is expected to mirror the 69 // slot->buffer mapping so that it's not necessary to transfer a 70 // GraphicBuffer for every dequeue operation. 71 // 72 // The slot must be in the range of [0, NUM_BUFFER_SLOTS). 73 // 74 // Return of a value other than NO_ERROR means an error has occurred: 75 // * NO_INIT - the buffer queue has been abandoned. 76 // * BAD_VALUE - one of the two conditions occurred: 77 // * slot was out of range (see above) 78 // * buffer specified by the slot is not dequeued 79 virtual status_t requestBuffer(int slot, sp<GraphicBuffer>* buf) = 0; 80 81 // setBufferCount sets the number of buffer slots available. Calling this 82 // will also cause all buffer slots to be emptied. The caller should empty 83 // its mirrored copy of the buffer slots when calling this method. 84 // 85 // This function should not be called when there are any dequeued buffer 86 // slots, doing so will result in a BAD_VALUE error returned. 87 // 88 // The buffer count should be at most NUM_BUFFER_SLOTS (inclusive), but at least 89 // the minimum undequeued buffer count (exclusive). The minimum value 90 // can be obtained by calling query(NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS). 91 // In particular the range is (minUndequeudBuffers, NUM_BUFFER_SLOTS]. 92 // 93 // The buffer count may also be set to 0 (the default), to indicate that 94 // the producer does not wish to set a value. 95 // 96 // Return of a value other than NO_ERROR means an error has occurred: 97 // * NO_INIT - the buffer queue has been abandoned. 98 // * BAD_VALUE - one of the below conditions occurred: 99 // * bufferCount was out of range (see above) 100 // * client has one or more buffers dequeued 101 virtual status_t setBufferCount(int bufferCount) = 0; 102 103 // dequeueBuffer requests a new buffer slot for the client to use. Ownership 104 // of the slot is transfered to the client, meaning that the server will not 105 // use the contents of the buffer associated with that slot. 106 // 107 // The slot index returned may or may not contain a buffer (client-side). 108 // If the slot is empty the client should call requestBuffer to assign a new 109 // buffer to that slot. 110 // 111 // Once the client is done filling this buffer, it is expected to transfer 112 // buffer ownership back to the server with either cancelBuffer on 113 // the dequeued slot or to fill in the contents of its associated buffer 114 // contents and call queueBuffer. 115 // 116 // If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is 117 // expected to call requestBuffer immediately. 118 // 119 // If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is 120 // expected to release all of the mirrored slot->buffer mappings. 121 // 122 // The fence parameter will be updated to hold the fence associated with 123 // the buffer. The contents of the buffer must not be overwritten until the 124 // fence signals. If the fence is Fence::NO_FENCE, the buffer may be written 125 // immediately. 126 // 127 // The async parameter sets whether we're in asynchronous mode for this 128 // dequeueBuffer() call. 129 // 130 // The width and height parameters must be no greater than the minimum of 131 // GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see: glGetIntegerv). 132 // An error due to invalid dimensions might not be reported until 133 // updateTexImage() is called. If width and height are both zero, the 134 // default values specified by setDefaultBufferSize() are used instead. 135 // 136 // The pixel formats are enumerated in <graphics.h>, e.g. 137 // HAL_PIXEL_FORMAT_RGBA_8888. If the format is 0, the default format 138 // 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, uint32_t 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 // attachBuffer attempts to transfer ownership of a buffer to the buffer 188 // queue. If this call succeeds, it will be as if this buffer was dequeued 189 // from the returned slot number. As such, this call will fail if attaching 190 // this buffer would cause too many buffers to be simultaneously dequeued. 191 // 192 // If attachBuffer returns the RELEASE_ALL_BUFFERS flag, the caller is 193 // expected to release all of the mirrored slot->buffer mappings. 194 // 195 // A non-negative value with flags set (see above) will be returned upon 196 // success. 197 // 198 // Return of a negative value means an error has occurred: 199 // * NO_INIT - the buffer queue has been abandoned. 200 // * BAD_VALUE - outSlot or buffer were NULL or invalid combination of 201 // async mode and buffer count override. 202 // * INVALID_OPERATION - cannot attach the buffer because it would cause 203 // too many buffers to be dequeued, either because 204 // the producer already has a single buffer dequeued 205 // and did not set a buffer count, or because a 206 // buffer count was set and this call would cause 207 // it to be exceeded. 208 // * WOULD_BLOCK - no buffer slot is currently available, and blocking is 209 // disabled since both the producer/consumer are 210 // controlled by the app. 211 virtual status_t attachBuffer(int* outSlot, 212 const sp<GraphicBuffer>& buffer) = 0; 213 214 // queueBuffer indicates that the client has finished filling in the 215 // contents of the buffer associated with slot and transfers ownership of 216 // that slot back to the server. 217 // 218 // It is not valid to call queueBuffer on a slot that is not owned 219 // by the client or one for which a buffer associated via requestBuffer 220 // (an attempt to do so will fail with a return value of BAD_VALUE). 221 // 222 // In addition, the input must be described by the client (as documented 223 // below). Any other properties (zero point, etc) 224 // are client-dependent, and should be documented by the client. 225 // 226 // The slot must be in the range of [0, NUM_BUFFER_SLOTS). 227 // 228 // Upon success, the output will be filled with meaningful values 229 // (refer to the documentation below). 230 // 231 // Return of a value other than NO_ERROR means an error has occurred: 232 // * NO_INIT - the buffer queue has been abandoned. 233 // * BAD_VALUE - one of the below conditions occurred: 234 // * fence was NULL 235 // * scaling mode was unknown 236 // * both in async mode and buffer count was less than the 237 // max numbers of buffers that can be allocated at once 238 // * slot index was out of range (see above). 239 // * the slot was not in the dequeued state 240 // * the slot was enqueued without requesting a buffer 241 // * crop rect is out of bounds of the buffer dimensions 242 243 struct QueueBufferInput : public Flattenable<QueueBufferInput> { 244 friend class Flattenable<QueueBufferInput>; 245 inline QueueBufferInput(const Parcel& parcel); 246 // timestamp - a monotonically increasing value in nanoseconds 247 // isAutoTimestamp - if the timestamp was synthesized at queue time 248 // crop - a crop rectangle that's used as a hint to the consumer 249 // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h> 250 // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h> 251 // async - if the buffer is queued in asynchronous mode 252 // fence - a fence that the consumer must wait on before reading the buffer, 253 // set this to Fence::NO_FENCE if the buffer is ready immediately 254 inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp, 255 const Rect& crop, int scalingMode, uint32_t transform, bool async, 256 const sp<Fence>& fence) 257 : timestamp(timestamp), isAutoTimestamp(isAutoTimestamp), crop(crop), 258 scalingMode(scalingMode), transform(transform), async(async), 259 fence(fence) { } 260 inline void deflate(int64_t* outTimestamp, bool* outIsAutoTimestamp, 261 Rect* outCrop, int* outScalingMode, uint32_t* outTransform, 262 bool* outAsync, sp<Fence>* outFence) const { 263 *outTimestamp = timestamp; 264 *outIsAutoTimestamp = bool(isAutoTimestamp); 265 *outCrop = crop; 266 *outScalingMode = scalingMode; 267 *outTransform = transform; 268 *outAsync = bool(async); 269 *outFence = fence; 270 } 271 272 // Flattenable protocol 273 size_t getFlattenedSize() const; 274 size_t getFdCount() const; 275 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const; 276 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count); 277 278 private: 279 int64_t timestamp; 280 int isAutoTimestamp; 281 Rect crop; 282 int scalingMode; 283 uint32_t transform; 284 int async; 285 sp<Fence> fence; 286 }; 287 288 // QueueBufferOutput must be a POD structure 289 struct __attribute__ ((__packed__)) QueueBufferOutput { 290 inline QueueBufferOutput() { } 291 // outWidth - filled with default width applied to the buffer 292 // outHeight - filled with default height applied to the buffer 293 // outTransformHint - filled with default transform applied to the buffer 294 // outNumPendingBuffers - num buffers queued that haven't yet been acquired 295 // (counting the currently queued buffer) 296 inline void deflate(uint32_t* outWidth, 297 uint32_t* outHeight, 298 uint32_t* outTransformHint, 299 uint32_t* outNumPendingBuffers) const { 300 *outWidth = width; 301 *outHeight = height; 302 *outTransformHint = transformHint; 303 *outNumPendingBuffers = numPendingBuffers; 304 } 305 inline void inflate(uint32_t inWidth, uint32_t inHeight, 306 uint32_t inTransformHint, uint32_t inNumPendingBuffers) { 307 width = inWidth; 308 height = inHeight; 309 transformHint = inTransformHint; 310 numPendingBuffers = inNumPendingBuffers; 311 } 312 private: 313 uint32_t width; 314 uint32_t height; 315 uint32_t transformHint; 316 uint32_t numPendingBuffers; 317 }; 318 319 virtual status_t queueBuffer(int slot, 320 const QueueBufferInput& input, QueueBufferOutput* output) = 0; 321 322 // cancelBuffer indicates that the client does not wish to fill in the 323 // buffer associated with slot and transfers ownership of the slot back to 324 // the server. 325 // 326 // The buffer is not queued for use by the consumer. 327 // 328 // The buffer will not be overwritten until the fence signals. The fence 329 // will usually be the one obtained from dequeueBuffer. 330 virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0; 331 332 // query retrieves some information for this surface 333 // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h> 334 // 335 // Return of a value other than NO_ERROR means an error has occurred: 336 // * NO_INIT - the buffer queue has been abandoned. 337 // * BAD_VALUE - what was out of range 338 virtual int query(int what, int* value) = 0; 339 340 // connect attempts to connect a client API to the IGraphicBufferProducer. 341 // This must be called before any other IGraphicBufferProducer methods are 342 // called except for getAllocator. A consumer must be already connected. 343 // 344 // This method will fail if the connect was previously called on the 345 // IGraphicBufferProducer and no corresponding disconnect call was made. 346 // 347 // The token needs to be any opaque binder object that lives in the 348 // producer process -- it is solely used for obtaining a death notification 349 // when the producer is killed. 350 // 351 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 352 // 353 // The producerControlledByApp should be set to true if the producer is hosted 354 // by an untrusted process (typically app_process-forked processes). If both 355 // the producer and the consumer are app-controlled then all buffer queues 356 // will operate in async mode regardless of the async flag. 357 // 358 // Upon success, the output will be filled with meaningful data 359 // (refer to QueueBufferOutput documentation above). 360 // 361 // Return of a value other than NO_ERROR means an error has occurred: 362 // * NO_INIT - one of the following occurred: 363 // * the buffer queue was abandoned 364 // * no consumer has yet connected 365 // * BAD_VALUE - one of the following has occurred: 366 // * the producer is already connected 367 // * api was out of range (see above). 368 // * output was NULL. 369 // * DEAD_OBJECT - the token is hosted by an already-dead process 370 // 371 // Additional negative errors may be returned by the internals, they 372 // should be treated as opaque fatal unrecoverable errors. 373 virtual status_t connect(const sp<IBinder>& token, 374 int api, bool producerControlledByApp, QueueBufferOutput* output) = 0; 375 376 // disconnect attempts to disconnect a client API from the 377 // IGraphicBufferProducer. Calling this method will cause any subsequent 378 // calls to other IGraphicBufferProducer methods to fail except for 379 // getAllocator and connect. Successfully calling connect after this will 380 // allow the other methods to succeed again. 381 // 382 // This method will fail if the the IGraphicBufferProducer is not currently 383 // connected to the specified client API. 384 // 385 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 386 // 387 // Disconnecting from an abandoned IGraphicBufferProducer is legal and 388 // is considered a no-op. 389 // 390 // Return of a value other than NO_ERROR means an error has occurred: 391 // * BAD_VALUE - one of the following has occurred: 392 // * the api specified does not match the one that was connected 393 // * api was out of range (see above). 394 // * DEAD_OBJECT - the token is hosted by an already-dead process 395 virtual status_t disconnect(int api) = 0; 396 397 // Attaches a sideband buffer stream to the IGraphicBufferProducer. 398 // 399 // A sideband stream is a device-specific mechanism for passing buffers 400 // from the producer to the consumer without using dequeueBuffer/ 401 // queueBuffer. If a sideband stream is present, the consumer can choose 402 // whether to acquire buffers from the sideband stream or from the queued 403 // buffers. 404 // 405 // Passing NULL or a different stream handle will detach the previous 406 // handle if any. 407 virtual status_t setSidebandStream(const sp<NativeHandle>& stream) = 0; 408}; 409 410// ---------------------------------------------------------------------------- 411 412class BnGraphicBufferProducer : public BnInterface<IGraphicBufferProducer> 413{ 414public: 415 virtual status_t onTransact( uint32_t code, 416 const Parcel& data, 417 Parcel* reply, 418 uint32_t flags = 0); 419}; 420 421// ---------------------------------------------------------------------------- 422}; // namespace android 423 424#endif // ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H 425