IGraphicBufferProducer.h revision 399184a4cd728ea1421fb0bc1722274a29e38f4a
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 - one of the below conditions occurred: 155 // * both in async mode and buffer count was less than the 156 // max numbers of buffers that can be allocated at once 157 // * attempting dequeue more than one buffer at a time 158 // without setting the buffer count with setBufferCount() 159 // * -EBUSY - attempting to dequeue too many buffers at a time 160 // * WOULD_BLOCK - no buffer is currently available, and blocking is disabled 161 // since both the producer/consumer are controlled by app 162 // * NO_MEMORY - out of memory, cannot allocate the graphics buffer. 163 // 164 // All other negative values are an unknown error returned downstream 165 // from the graphics allocator (typically errno). 166 virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, bool async, 167 uint32_t w, uint32_t h, uint32_t format, uint32_t usage) = 0; 168 169 // queueBuffer indicates that the client has finished filling in the 170 // contents of the buffer associated with slot and transfers ownership of 171 // that slot back to the server. 172 // 173 // It is not valid to call queueBuffer on a slot that is not owned 174 // by the client or one for which a buffer associated via requestBuffer 175 // (an attempt to do so will fail with a return value of BAD_VALUE). 176 // 177 // In addition, the input must be described by the client (as documented 178 // below). Any other properties (zero point, etc) 179 // are client-dependent, and should be documented by the client. 180 // 181 // The slot must be in the range of [0, NUM_BUFFER_SLOTS). 182 // 183 // Upon success, the output will be filled with meaningful values 184 // (refer to the documentation below). 185 // 186 // Return of a value other than NO_ERROR means an error has occurred: 187 // * NO_INIT - the buffer queue has been abandoned. 188 // * BAD_VALUE - one of the below conditions occurred: 189 // * fence was NULL 190 // * scaling mode was unknown 191 // * both in async mode and buffer count was less than the 192 // max numbers of buffers that can be allocated at once 193 // * slot index was out of range (see above). 194 // * the slot was not in the dequeued state 195 // * the slot was enqueued without requesting a buffer 196 // * crop rect is out of bounds of the buffer dimensions 197 198 struct QueueBufferInput : public Flattenable<QueueBufferInput> { 199 friend class Flattenable<QueueBufferInput>; 200 inline QueueBufferInput(const Parcel& parcel); 201 // timestamp - a monotonically increasing value in nanoseconds 202 // isAutoTimestamp - if the timestamp was synthesized at queue time 203 // crop - a crop rectangle that's used as a hint to the consumer 204 // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h> 205 // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h> 206 // async - if the buffer is queued in asynchronous mode 207 // fence - a fence that the consumer must wait on before reading the buffer, 208 // set this to Fence::NO_FENCE if the buffer is ready immediately 209 inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp, 210 const Rect& crop, int scalingMode, uint32_t transform, bool async, 211 const sp<Fence>& fence) 212 : timestamp(timestamp), isAutoTimestamp(isAutoTimestamp), crop(crop), 213 scalingMode(scalingMode), transform(transform), async(async), 214 fence(fence) { } 215 inline void deflate(int64_t* outTimestamp, bool* outIsAutoTimestamp, 216 Rect* outCrop, int* outScalingMode, uint32_t* outTransform, 217 bool* outAsync, sp<Fence>* outFence) const { 218 *outTimestamp = timestamp; 219 *outIsAutoTimestamp = bool(isAutoTimestamp); 220 *outCrop = crop; 221 *outScalingMode = scalingMode; 222 *outTransform = transform; 223 *outAsync = bool(async); 224 *outFence = fence; 225 } 226 227 // Flattenable protocol 228 size_t getFlattenedSize() const; 229 size_t getFdCount() const; 230 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const; 231 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count); 232 233 private: 234 int64_t timestamp; 235 int isAutoTimestamp; 236 Rect crop; 237 int scalingMode; 238 uint32_t transform; 239 int async; 240 sp<Fence> fence; 241 }; 242 243 // QueueBufferOutput must be a POD structure 244 struct __attribute__ ((__packed__)) QueueBufferOutput { 245 inline QueueBufferOutput() { } 246 // outWidth - filled with default width applied to the buffer 247 // outHeight - filled with default height applied to the buffer 248 // outTransformHint - filled with default transform applied to the buffer 249 // outNumPendingBuffers - num buffers queued that haven't yet been acquired 250 // (counting the currently queued buffer) 251 inline void deflate(uint32_t* outWidth, 252 uint32_t* outHeight, 253 uint32_t* outTransformHint, 254 uint32_t* outNumPendingBuffers) const { 255 *outWidth = width; 256 *outHeight = height; 257 *outTransformHint = transformHint; 258 *outNumPendingBuffers = numPendingBuffers; 259 } 260 inline void inflate(uint32_t inWidth, uint32_t inHeight, 261 uint32_t inTransformHint, uint32_t inNumPendingBuffers) { 262 width = inWidth; 263 height = inHeight; 264 transformHint = inTransformHint; 265 numPendingBuffers = inNumPendingBuffers; 266 } 267 private: 268 uint32_t width; 269 uint32_t height; 270 uint32_t transformHint; 271 uint32_t numPendingBuffers; 272 }; 273 274 virtual status_t queueBuffer(int slot, 275 const QueueBufferInput& input, QueueBufferOutput* output) = 0; 276 277 // cancelBuffer indicates that the client does not wish to fill in the 278 // buffer associated with slot and transfers ownership of the slot back to 279 // the server. 280 // 281 // The buffer is not queued for use by the consumer. 282 // 283 // The buffer will not be overwritten until the fence signals. The fence 284 // will usually be the one obtained from dequeueBuffer. 285 virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0; 286 287 // query retrieves some information for this surface 288 // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h> 289 // 290 // Return of a value other than NO_ERROR means an error has occurred: 291 // * NO_INIT - the buffer queue has been abandoned. 292 // * BAD_VALUE - what was out of range 293 virtual int query(int what, int* value) = 0; 294 295 // connect attempts to connect a client API to the IGraphicBufferProducer. 296 // This must be called before any other IGraphicBufferProducer methods are 297 // called except for getAllocator. A consumer must be already connected. 298 // 299 // This method will fail if the connect was previously called on the 300 // IGraphicBufferProducer and no corresponding disconnect call was made. 301 // 302 // The token needs to be any opaque binder object that lives in the 303 // producer process -- it is solely used for obtaining a death notification 304 // when the producer is killed. 305 // 306 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 307 // 308 // The producerControlledByApp should be set to true if the producer is hosted 309 // by an untrusted process (typically app_process-forked processes). If both 310 // the producer and the consumer are app-controlled then all buffer queues 311 // will operate in async mode regardless of the async flag. 312 // 313 // Upon success, the output will be filled with meaningful data 314 // (refer to QueueBufferOutput documentation above). 315 // 316 // Return of a value other than NO_ERROR means an error has occurred: 317 // * NO_INIT - one of the following occurred: 318 // * the buffer queue was abandoned 319 // * no consumer has yet connected 320 // * BAD_VALUE - one of the following has occurred: 321 // * the producer is already connected 322 // * api was out of range (see above). 323 // * output was NULL. 324 // * DEAD_OBJECT - the token is hosted by an already-dead process 325 // 326 // Additional negative errors may be returned by the internals, they 327 // should be treated as opaque fatal unrecoverable errors. 328 virtual status_t connect(const sp<IBinder>& token, 329 int api, bool producerControlledByApp, QueueBufferOutput* output) = 0; 330 331 // disconnect attempts to disconnect a client API from the 332 // IGraphicBufferProducer. Calling this method will cause any subsequent 333 // calls to other IGraphicBufferProducer methods to fail except for 334 // getAllocator and connect. Successfully calling connect after this will 335 // allow the other methods to succeed again. 336 // 337 // This method will fail if the the IGraphicBufferProducer is not currently 338 // connected to the specified client API. 339 // 340 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 341 // 342 // Disconnecting from an abandoned IGraphicBufferProducer is legal and 343 // is considered a no-op. 344 // 345 // Return of a value other than NO_ERROR means an error has occurred: 346 // * BAD_VALUE - one of the following has occurred: 347 // * the api specified does not match the one that was connected 348 // * api was out of range (see above). 349 // * DEAD_OBJECT - the token is hosted by an already-dead process 350 virtual status_t disconnect(int api) = 0; 351 352 // Attaches a sideband buffer stream to the IGraphicBufferProducer. 353 // 354 // A sideband stream is a device-specific mechanism for passing buffers 355 // from the producer to the consumer without using dequeueBuffer/ 356 // queueBuffer. If a sideband stream is present, the consumer can choose 357 // whether to acquire buffers from the sideband stream or from the queued 358 // buffers. 359 // 360 // Passing NULL or a different stream handle will detach the previous 361 // handle if any. 362 virtual status_t setSidebandStream(const sp<NativeHandle>& stream) = 0; 363}; 364 365// ---------------------------------------------------------------------------- 366 367class BnGraphicBufferProducer : public BnInterface<IGraphicBufferProducer> 368{ 369public: 370 virtual status_t onTransact( uint32_t code, 371 const Parcel& data, 372 Parcel* reply, 373 uint32_t flags = 0); 374}; 375 376// ---------------------------------------------------------------------------- 377}; // namespace android 378 379#endif // ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H 380