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