1 /* 2 * Copyright (C) 2013 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 #pragma once 18 19 #include <gui/OccupancyTracker.h> 20 21 #include <binder/IInterface.h> 22 #include <binder/SafeInterface.h> 23 24 #include <EGL/egl.h> 25 #include <EGL/eglext.h> 26 27 #include <ui/PixelFormat.h> 28 29 #include <utils/Errors.h> 30 31 namespace android { 32 33 class BufferItem; 34 class Fence; 35 class GraphicBuffer; 36 class IConsumerListener; 37 class NativeHandle; 38 39 class IGraphicBufferConsumer : public IInterface { 40 public: 41 DECLARE_META_INTERFACE(GraphicBufferConsumer) 42 43 enum { 44 // Returned by releaseBuffer, after which the consumer must free any references to the 45 // just-released buffer that it might have. 46 STALE_BUFFER_SLOT = 1, 47 // Returned by dequeueBuffer if there are no pending buffers available. 48 NO_BUFFER_AVAILABLE, 49 // Returned by dequeueBuffer if it's too early for the buffer to be acquired. 50 PRESENT_LATER, 51 }; 52 53 // acquireBuffer attempts to acquire ownership of the next pending buffer in the BufferQueue. 54 // If no buffer is pending then it returns NO_BUFFER_AVAILABLE. If a buffer is successfully 55 // acquired, the information about the buffer is returned in BufferItem. 56 // 57 // If the buffer returned had previously been acquired then the BufferItem::mGraphicBuffer field 58 // of buffer is set to NULL and it is assumed that the consumer still holds a reference to the 59 // buffer. 60 // 61 // If presentWhen is non-zero, it indicates the time when the buffer will be displayed on 62 // screen. If the buffer's timestamp is farther in the future, the buffer won't be acquired, and 63 // PRESENT_LATER will be returned. The presentation time is in nanoseconds, and the time base 64 // is CLOCK_MONOTONIC. 65 // 66 // If maxFrameNumber is non-zero, it indicates that acquireBuffer should only return a buffer 67 // with a frame number less than or equal to maxFrameNumber. If no such frame is available 68 // (such as when a buffer has been replaced but the consumer has not received the 69 // onFrameReplaced callback), then PRESENT_LATER will be returned. 70 // 71 // Return of NO_ERROR means the operation completed as normal. 72 // 73 // Return of a positive value means the operation could not be completed at this time, but the 74 // user should try again later: 75 // * NO_BUFFER_AVAILABLE - no buffer is pending (nothing queued by producer) 76 // * PRESENT_LATER - the buffer's timestamp is farther in the future 77 // 78 // Return of a negative value means an error has occurred: 79 // * INVALID_OPERATION - too many buffers have been acquired 80 virtual status_t acquireBuffer(BufferItem* buffer, nsecs_t presentWhen, 81 uint64_t maxFrameNumber = 0) = 0; 82 83 // detachBuffer attempts to remove all ownership of the buffer in the given slot from the buffer 84 // queue. If this call succeeds, the slot will be freed, and there will be no way to obtain the 85 // buffer from this interface. The freed slot will remain unallocated until either it is 86 // selected to hold a freshly allocated buffer in dequeueBuffer or a buffer is attached to the 87 // slot. The buffer must have already been acquired. 88 // 89 // Return of a value other than NO_ERROR means an error has occurred: 90 // * BAD_VALUE - the given slot number is invalid, either because it is out of the range 91 // [0, NUM_BUFFER_SLOTS) or because the slot it refers to is not 92 // currently acquired. 93 virtual status_t detachBuffer(int slot) = 0; 94 95 // attachBuffer attempts to transfer ownership of a buffer to the BufferQueue. If this call 96 // succeeds, it will be as if this buffer was acquired from the returned slot number. As such, 97 // this call will fail if attaching this buffer would cause too many buffers to be 98 // simultaneously acquired. 99 // 100 // If the buffer is successfully attached, its frameNumber is initialized to 0. This must be 101 // passed into the releaseBuffer call or else the buffer will be deallocated as stale. 102 // 103 // Return of a value other than NO_ERROR means an error has occurred: 104 // * BAD_VALUE - outSlot or buffer were NULL, or the generation number of the buffer did not 105 // match the BufferQueue. 106 // * INVALID_OPERATION - cannot attach the buffer because it would cause too many buffers 107 // to be acquired. 108 // * NO_MEMORY - no free slots available 109 virtual status_t attachBuffer(int* outSlot, const sp<GraphicBuffer>& buffer) = 0; 110 111 // releaseBuffer releases a buffer slot from the consumer back to the BufferQueue. This may be 112 // done while the buffer's contents are still being accessed. The fence will signal when the 113 // buffer is no longer in use. frameNumber is used to identify the exact buffer returned. 114 // 115 // If releaseBuffer returns STALE_BUFFER_SLOT, then the consumer must free any references to the 116 // just-released buffer that it might have, as if it had received a onBuffersReleased() call 117 // with a mask set for the released buffer. 118 // 119 // Note that the dependencies on EGL will be removed once we switch to using the Android HW 120 // Sync HAL. 121 // 122 // Return of NO_ERROR means the operation completed as normal. 123 // 124 // Return of a positive value means the operation could not be completed at this time, but the 125 // user should try again later: 126 // * STALE_BUFFER_SLOT - see above (second paragraph) 127 // 128 // Return of a negative value means an error has occurred: 129 // * BAD_VALUE - one of the following could've happened: 130 // * the buffer slot was invalid 131 // * the fence was NULL 132 // * the buffer slot specified is not in the acquired state 133 virtual status_t releaseBuffer(int buf, uint64_t frameNumber, EGLDisplay display, 134 EGLSyncKHR fence, const sp<Fence>& releaseFence) = 0; 135 136 status_t releaseHelper(int buf, uint64_t frameNumber, const sp<Fence>& releaseFence) { 137 return releaseBuffer(buf, frameNumber, EGL_NO_DISPLAY, EGL_NO_SYNC_KHR, releaseFence); 138 } 139 // This is explicitly *not* the actual signature of IGBC::releaseBuffer, but: 140 // 1) We have no easy way to send the EGL objects across Binder 141 // 2) This has always been broken, probably because 142 // 3) IGBC is rarely remoted 143 // For now, we will choose to bury our heads in the sand and ignore this problem until such time 144 // as we can finally finish converting away from EGL sync to native Android sync 145 using ReleaseBuffer = decltype(&IGraphicBufferConsumer::releaseHelper); 146 147 // consumerConnect connects a consumer to the BufferQueue. Only one consumer may be connected, 148 // and when that consumer disconnects the BufferQueue is placed into the "abandoned" state, 149 // causing most interactions with the BufferQueue by the producer to fail. controlledByApp 150 // indicates whether the consumer is controlled by the application. 151 // 152 // consumer may not be NULL. 153 // 154 // Return of a value other than NO_ERROR means an error has occurred: 155 // * NO_INIT - the BufferQueue has been abandoned 156 // * BAD_VALUE - a NULL consumer was provided 157 virtual status_t consumerConnect(const sp<IConsumerListener>& consumer, 158 bool controlledByApp) = 0; 159 160 // consumerDisconnect disconnects a consumer from the BufferQueue. All buffers will be freed and 161 // the BufferQueue is placed in the "abandoned" state, causing most interactions with the 162 // BufferQueue by the producer to fail. 163 // 164 // Return of a value other than NO_ERROR means an error has occurred: 165 // * BAD_VALUE - no consumer is currently connected 166 virtual status_t consumerDisconnect() = 0; 167 168 // getReleasedBuffers sets the value pointed to by slotMask to a bit set. Each bit index with a 169 // 1 corresponds to a released buffer slot with that index value. In particular, a released 170 // buffer is one that has been released by the BufferQueue but has not yet been released by 171 // the consumer. 172 // 173 // This should be called from the onBuffersReleased() callback. 174 // 175 // Return of a value other than NO_ERROR means an error has occurred: 176 // * NO_INIT - the BufferQueue has been abandoned. 177 virtual status_t getReleasedBuffers(uint64_t* slotMask) = 0; 178 179 // setDefaultBufferSize is used to set the size of buffers returned by dequeueBuffer when a 180 // width and height of zero is requested. Default is 1x1. 181 // 182 // Return of a value other than NO_ERROR means an error has occurred: 183 // * BAD_VALUE - either w or h was zero 184 virtual status_t setDefaultBufferSize(uint32_t w, uint32_t h) = 0; 185 186 // setMaxBufferCount sets the maximum value for the number of buffers used in the BufferQueue 187 // (the initial default is NUM_BUFFER_SLOTS). If a call to setMaxAcquiredBufferCount (by the 188 // consumer), or a call to setAsyncMode or setMaxDequeuedBufferCount (by the producer), would 189 // cause this value to be exceeded then that call will fail. This call will fail if a producer 190 // is connected to the BufferQueue. 191 // 192 // The count must be between 1 and NUM_BUFFER_SLOTS, inclusive. The count cannot be less than 193 // maxAcquiredBufferCount. 194 // 195 // Return of a value other than NO_ERROR means an error has occurred: 196 // * BAD_VALUE - one of the below conditions occurred: 197 // * bufferCount was out of range (see above). 198 // * failure to adjust the number of available slots. 199 // * INVALID_OPERATION - attempting to call this after a producer connected. 200 virtual status_t setMaxBufferCount(int bufferCount) = 0; 201 202 // setMaxAcquiredBufferCount sets the maximum number of buffers that can be acquired by the 203 // consumer at one time (default 1). If this method succeeds, any new buffer slots will be both 204 // unallocated and owned by the BufferQueue object (i.e. they are not owned by the producer or 205 // consumer). Calling this may also cause some buffer slots to be emptied. 206 // 207 // This function should not be called with a value of maxAcquiredBuffers that is less than the 208 // number of currently acquired buffer slots. Doing so will result in a BAD_VALUE error. 209 // 210 // maxAcquiredBuffers must be (inclusive) between 1 and MAX_MAX_ACQUIRED_BUFFERS. It also cannot 211 // cause the maxBufferCount value to be exceeded. 212 // 213 // Return of a value other than NO_ERROR means an error has occurred: 214 // * NO_INIT - the BufferQueue has been abandoned 215 // * BAD_VALUE - one of the below conditions occurred: 216 // * maxAcquiredBuffers was out of range (see above). 217 // * failure to adjust the number of available slots. 218 // * client would have more than the requested number of acquired buffers after 219 // this call 220 // * INVALID_OPERATION - attempting to call this after a producer connected. 221 virtual status_t setMaxAcquiredBufferCount(int maxAcquiredBuffers) = 0; 222 223 // setConsumerName sets the name used in logging 224 virtual status_t setConsumerName(const String8& name) = 0; 225 226 // setDefaultBufferFormat allows the BufferQueue to create GraphicBuffers of a defaultFormat if 227 // no format is specified in dequeueBuffer. The initial default is PIXEL_FORMAT_RGBA_8888. 228 // 229 // Return of a value other than NO_ERROR means an unknown error has occurred. 230 virtual status_t setDefaultBufferFormat(PixelFormat defaultFormat) = 0; 231 232 // setDefaultBufferDataSpace is a request to the producer to provide buffers of the indicated 233 // dataSpace. The producer may ignore this request. The initial default is 234 // HAL_DATASPACE_UNKNOWN. 235 // 236 // Return of a value other than NO_ERROR means an unknown error has occurred. 237 virtual status_t setDefaultBufferDataSpace(android_dataspace defaultDataSpace) = 0; 238 239 // setConsumerUsageBits will turn on additional usage bits for dequeueBuffer. These are merged 240 // with the bits passed to dequeueBuffer. The values are enumerated in gralloc.h, 241 // e.g. GRALLOC_USAGE_HW_RENDER; the default is 0. 242 // 243 // Return of a value other than NO_ERROR means an unknown error has occurred. 244 virtual status_t setConsumerUsageBits(uint32_t usage) = 0; 245 246 // setConsumerIsProtected will turn on an internal bit that indicates whether 247 // the consumer can handle protected gralloc buffers (i.e. with 248 // GRALLOC_USAGE_PROTECTED set). IGraphicBufferProducer can query this 249 // capability using NATIVE_WINDOW_CONSUMER_IS_PROTECTED. 250 virtual status_t setConsumerIsProtected(bool isProtected) = 0; 251 252 // setTransformHint bakes in rotation to buffers so overlays can be used. The values are 253 // enumerated in window.h, e.g. NATIVE_WINDOW_TRANSFORM_ROT_90. The default is 0 254 // (no transform). 255 // 256 // Return of a value other than NO_ERROR means an unknown error has occurred. 257 virtual status_t setTransformHint(uint32_t hint) = 0; 258 259 // Retrieve the sideband buffer stream, if any. 260 virtual status_t getSidebandStream(sp<NativeHandle>* outStream) const = 0; 261 262 // Retrieves any stored segments of the occupancy history of this BufferQueue and clears them. 263 // Optionally closes out the pending segment if forceFlush is true. 264 virtual status_t getOccupancyHistory(bool forceFlush, 265 std::vector<OccupancyTracker::Segment>* outHistory) = 0; 266 267 // discardFreeBuffers releases all currently-free buffers held by the BufferQueue, in order to 268 // reduce the memory consumption of the BufferQueue to the minimum possible without 269 // discarding data. 270 // The consumer invoking this method is responsible for calling getReleasedBuffers() after this 271 // call to free up any of its locally cached buffers. 272 virtual status_t discardFreeBuffers() = 0; 273 274 // dump state into a string 275 virtual status_t dumpState(const String8& prefix, String8* outResult) const = 0; 276 277 // Provide backwards source compatibility 278 void dumpState(String8& result, const char* prefix) { 279 String8 returned; 280 dumpState(String8(prefix), &returned); 281 result.append(returned); 282 } 283 }; 284 285 class BnGraphicBufferConsumer : public SafeBnInterface<IGraphicBufferConsumer> { 286 public: 287 BnGraphicBufferConsumer() 288 : SafeBnInterface<IGraphicBufferConsumer>("BnGraphicBufferConsumer") {} 289 290 status_t onTransact(uint32_t code, const Parcel& data, Parcel* reply, 291 uint32_t flags = 0) override; 292 }; 293 294 } // namespace android 295
