IGraphicBufferProducer.h revision 7d2d160cdc3cba9f4454f38433c94b68376cb843
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, but at least 88 // the minimum undequeued buffer count (inclusive). The minimum value 89 // can be obtained by calling query(NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS); 90 // 91 // Return of a value other than NO_ERROR means an error has occurred: 92 // * NO_INIT - the buffer queue has been abandoned. 93 // * BAD_VALUE - one of the below conditions occurred: 94 // * bufferCount was out of range (see above) 95 // * client has one or more buffers dequeued 96 virtual status_t setBufferCount(int bufferCount) = 0; 97 98 // dequeueBuffer requests a new buffer slot for the client to use. Ownership 99 // of the slot is transfered to the client, meaning that the server will not 100 // use the contents of the buffer associated with that slot. 101 // 102 // The slot index returned may or may not contain a buffer (client-side). 103 // If the slot is empty the client should call requestBuffer to assign a new 104 // buffer to that slot. 105 // 106 // Once the client is done filling this buffer, it is expected to transfer 107 // buffer ownership back to the server with either cancelBuffer on 108 // the dequeued slot or to fill in the contents of its associated buffer 109 // contents and call queueBuffer. 110 // 111 // If dequeueBuffer returns the BUFFER_NEEDS_REALLOCATION flag, the client is 112 // expected to call requestBuffer immediately. 113 // 114 // If dequeueBuffer returns the RELEASE_ALL_BUFFERS flag, the client is 115 // expected to release all of the mirrored slot->buffer mappings. 116 // 117 // The fence parameter will be updated to hold the fence associated with 118 // the buffer. The contents of the buffer must not be overwritten until the 119 // fence signals. If the fence is Fence::NO_FENCE, the buffer may be written 120 // immediately. 121 // 122 // The async parameter sets whether we're in asynchronous mode for this 123 // dequeueBuffer() call. 124 // 125 // The width and height parameters must be no greater than the minimum of 126 // GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see: glGetIntegerv). 127 // An error due to invalid dimensions might not be reported until 128 // updateTexImage() is called. If width and height are both zero, the 129 // default values specified by setDefaultBufferSize() are used instead. 130 // 131 // The pixel formats are enumerated in <graphics.h>, e.g. 132 // HAL_PIXEL_FORMAT_RGBA_8888. If the format is 0, the default format 133 // will be used. 134 // 135 // The usage argument specifies gralloc buffer usage flags. The values 136 // are enumerated in <gralloc.h>, e.g. GRALLOC_USAGE_HW_RENDER. These 137 // will be merged with the usage flags specified by 138 // IGraphicBufferConsumer::setConsumerUsageBits. 139 // 140 // This call will block until a buffer is available to be dequeued. If 141 // both the producer and consumer are controlled by the app, then this call 142 // can never block and will return WOULD_BLOCK if no buffer is available. 143 // 144 // A non-negative value with flags set (see above) will be returned upon 145 // success. 146 // 147 // Return of a negative means an error has occurred: 148 // * NO_INIT - the buffer queue has been abandoned. 149 // * BAD_VALUE - one of the below conditions occurred: 150 // * both in async mode and buffer count was less than the 151 // max numbers of buffers that can be allocated at once 152 // * attempting dequeue more than one buffer at a time 153 // without setting the buffer count with setBufferCount() 154 // * -EBUSY - attempting to dequeue too many buffers at a time 155 // * WOULD_BLOCK - no buffer is currently available, and blocking is disabled 156 // since both the producer/consumer are controlled by app 157 // * NO_MEMORY - out of memory, cannot allocate the graphics buffer. 158 // 159 // All other negative values are an unknown error returned downstream 160 // from the graphics allocator (typically errno). 161 virtual status_t dequeueBuffer(int* slot, sp<Fence>* fence, bool async, 162 uint32_t w, uint32_t h, uint32_t format, uint32_t usage) = 0; 163 164 // queueBuffer indicates that the client has finished filling in the 165 // contents of the buffer associated with slot and transfers ownership of 166 // that slot back to the server. 167 // 168 // It is not valid to call queueBuffer on a slot that is not owned 169 // by the client or one for which a buffer associated via requestBuffer 170 // (an attempt to do so will fail with a return value of BAD_VALUE). 171 // 172 // In addition, the input must be described by the client (as documented 173 // below). Any other properties (zero point, etc) 174 // are client-dependent, and should be documented by the client. 175 // 176 // The slot must be in the range of [0, NUM_BUFFER_SLOTS). 177 // 178 // Upon success, the output will be filled with meaningful values 179 // (refer to the documentation below). 180 // 181 // Return of a value other than NO_ERROR means an error has occurred: 182 // * NO_INIT - the buffer queue has been abandoned. 183 // * BAD_VALUE - one of the below conditions occurred: 184 // * fence was NULL 185 // * scaling mode was unknown 186 // * both in async mode and buffer count was less than the 187 // max numbers of buffers that can be allocated at once 188 // * slot index was out of range (see above). 189 // * the slot was not in the dequeued state 190 // * the slot was enqueued without requesting a buffer 191 // * crop rect is out of bounds of the buffer dimensions 192 193 struct QueueBufferInput : public Flattenable<QueueBufferInput> { 194 friend class Flattenable<QueueBufferInput>; 195 inline QueueBufferInput(const Parcel& parcel); 196 // timestamp - a monotonically increasing value in nanoseconds 197 // isAutoTimestamp - if the timestamp was synthesized at queue time 198 // crop - a crop rectangle that's used as a hint to the consumer 199 // scalingMode - a set of flags from NATIVE_WINDOW_SCALING_* in <window.h> 200 // transform - a set of flags from NATIVE_WINDOW_TRANSFORM_* in <window.h> 201 // async - if the buffer is queued in asynchronous mode 202 // fence - a fence that the consumer must wait on before reading the buffer, 203 // set this to Fence::NO_FENCE if the buffer is ready immediately 204 inline QueueBufferInput(int64_t timestamp, bool isAutoTimestamp, 205 const Rect& crop, int scalingMode, uint32_t transform, bool async, 206 const sp<Fence>& fence) 207 : timestamp(timestamp), isAutoTimestamp(isAutoTimestamp), crop(crop), 208 scalingMode(scalingMode), transform(transform), async(async), 209 fence(fence) { } 210 inline void deflate(int64_t* outTimestamp, bool* outIsAutoTimestamp, 211 Rect* outCrop, int* outScalingMode, uint32_t* outTransform, 212 bool* outAsync, sp<Fence>* outFence) const { 213 *outTimestamp = timestamp; 214 *outIsAutoTimestamp = bool(isAutoTimestamp); 215 *outCrop = crop; 216 *outScalingMode = scalingMode; 217 *outTransform = transform; 218 *outAsync = bool(async); 219 *outFence = fence; 220 } 221 222 // Flattenable protocol 223 size_t getFlattenedSize() const; 224 size_t getFdCount() const; 225 status_t flatten(void*& buffer, size_t& size, int*& fds, size_t& count) const; 226 status_t unflatten(void const*& buffer, size_t& size, int const*& fds, size_t& count); 227 228 private: 229 int64_t timestamp; 230 int isAutoTimestamp; 231 Rect crop; 232 int scalingMode; 233 uint32_t transform; 234 int async; 235 sp<Fence> fence; 236 }; 237 238 // QueueBufferOutput must be a POD structure 239 struct __attribute__ ((__packed__)) QueueBufferOutput { 240 inline QueueBufferOutput() { } 241 // outWidth - filled with default width applied to the buffer 242 // outHeight - filled with default height applied to the buffer 243 // outTransformHint - filled with default transform applied to the buffer 244 // outNumPendingBuffers - num buffers queued that haven't yet been acquired 245 // (counting the currently queued buffer) 246 inline void deflate(uint32_t* outWidth, 247 uint32_t* outHeight, 248 uint32_t* outTransformHint, 249 uint32_t* outNumPendingBuffers) const { 250 *outWidth = width; 251 *outHeight = height; 252 *outTransformHint = transformHint; 253 *outNumPendingBuffers = numPendingBuffers; 254 } 255 inline void inflate(uint32_t inWidth, uint32_t inHeight, 256 uint32_t inTransformHint, uint32_t inNumPendingBuffers) { 257 width = inWidth; 258 height = inHeight; 259 transformHint = inTransformHint; 260 numPendingBuffers = inNumPendingBuffers; 261 } 262 private: 263 uint32_t width; 264 uint32_t height; 265 uint32_t transformHint; 266 uint32_t numPendingBuffers; 267 }; 268 269 virtual status_t queueBuffer(int slot, 270 const QueueBufferInput& input, QueueBufferOutput* output) = 0; 271 272 // cancelBuffer indicates that the client does not wish to fill in the 273 // buffer associated with slot and transfers ownership of the slot back to 274 // the server. 275 // 276 // The buffer is not queued for use by the consumer. 277 // 278 // The buffer will not be overwritten until the fence signals. The fence 279 // will usually be the one obtained from dequeueBuffer. 280 virtual void cancelBuffer(int slot, const sp<Fence>& fence) = 0; 281 282 // query retrieves some information for this surface 283 // 'what' tokens allowed are that of NATIVE_WINDOW_* in <window.h> 284 // 285 // Return of a value other than NO_ERROR means an error has occurred: 286 // * NO_INIT - the buffer queue has been abandoned. 287 // * BAD_VALUE - what was out of range 288 virtual int query(int what, int* value) = 0; 289 290 // connect attempts to connect a client API to the IGraphicBufferProducer. 291 // This must be called before any other IGraphicBufferProducer methods are 292 // called except for getAllocator. A consumer must be already connected. 293 // 294 // This method will fail if the connect was previously called on the 295 // IGraphicBufferProducer and no corresponding disconnect call was made. 296 // 297 // The token needs to be any opaque binder object that lives in the 298 // producer process -- it is solely used for obtaining a death notification 299 // when the producer is killed. 300 // 301 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 302 // 303 // The producerControlledByApp should be set to true if the producer is hosted 304 // by an untrusted process (typically app_process-forked processes). If both 305 // the producer and the consumer are app-controlled then all buffer queues 306 // will operate in async mode regardless of the async flag. 307 // 308 // Upon success, the output will be filled with meaningful data 309 // (refer to QueueBufferOutput documentation above). 310 // 311 // Return of a value other than NO_ERROR means an error has occurred: 312 // * NO_INIT - one of the following occurred: 313 // * the buffer queue was abandoned 314 // * no consumer has yet connected 315 // * BAD_VALUE - one of the following has occurred: 316 // * the producer is already connected 317 // * api was out of range (see above). 318 // * DEAD_OBJECT - the token is hosted by an already-dead process 319 // 320 // Additional negative errors may be returned by the internals, they 321 // should be treated as opaque fatal unrecoverable errors. 322 virtual status_t connect(const sp<IBinder>& token, 323 int api, bool producerControlledByApp, QueueBufferOutput* output) = 0; 324 325 // disconnect attempts to disconnect a client API from the 326 // IGraphicBufferProducer. Calling this method will cause any subsequent 327 // calls to other IGraphicBufferProducer methods to fail except for 328 // getAllocator and connect. Successfully calling connect after this will 329 // allow the other methods to succeed again. 330 // 331 // This method will fail if the the IGraphicBufferProducer is not currently 332 // connected to the specified client API. 333 // 334 // The api should be one of the NATIVE_WINDOW_API_* values in <window.h> 335 // 336 // Disconnecting from an abandoned IGraphicBufferProducer is legal and 337 // is considered a no-op. 338 // 339 // Return of a value other than NO_ERROR means an error has occurred: 340 // * BAD_VALUE - one of the following has occurred: 341 // * the api specified does not match the one that was connected 342 // * api was out of range (see above). 343 // * DEAD_OBJECT - the token is hosted by an already-dead process 344 virtual status_t disconnect(int api) = 0; 345}; 346 347// ---------------------------------------------------------------------------- 348 349class BnGraphicBufferProducer : public BnInterface<IGraphicBufferProducer> 350{ 351public: 352 virtual status_t onTransact( uint32_t code, 353 const Parcel& data, 354 Parcel* reply, 355 uint32_t flags = 0); 356}; 357 358// ---------------------------------------------------------------------------- 359}; // namespace android 360 361#endif // ANDROID_GUI_IGRAPHICBUFFERPRODUCER_H 362