1 /* 2 * Copyright (C) 2018 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_STAGEFRIGHT_C2BLOCK_INTERNAL_H_ 18 #define ANDROID_STAGEFRIGHT_C2BLOCK_INTERNAL_H_ 19 20 #include <android/hardware/graphics/bufferqueue/1.0/IGraphicBufferProducer.h> 21 22 #include <C2Buffer.h> 23 24 namespace android { 25 namespace hardware { 26 namespace media { 27 namespace bufferpool { 28 29 struct BufferPoolData; 30 31 } 32 } 33 } 34 } 35 36 /** 37 * Stores informations from C2BlockPool implementations which are required by C2Block. 38 */ 39 struct C2_HIDE _C2BlockPoolData { 40 enum type_t : int { 41 TYPE_BUFFERPOOL = 0, 42 TYPE_BUFFERQUEUE, 43 }; 44 45 virtual type_t getType() const = 0; 46 47 protected: 48 _C2BlockPoolData() = default; 49 50 virtual ~_C2BlockPoolData() = default; 51 }; 52 53 struct C2BufferQueueBlockPoolData; 54 55 /** 56 * Internal only interface for creating blocks by block pool/buffer passing implementations. 57 * 58 * \todo this must be hidden 59 */ 60 struct _C2BlockFactory { 61 /** 62 * Create a linear block from an allocation for an allotted range. 63 * 64 * \param alloc parent allocation 65 * \param data blockpool data 66 * \param offset allotted range offset 67 * \param size allotted size 68 * 69 * \return shared pointer to the linear block. nullptr if there was not enough memory to 70 * create this block. 71 */ 72 static 73 std::shared_ptr<C2LinearBlock> CreateLinearBlock( 74 const std::shared_ptr<C2LinearAllocation> &alloc, 75 const std::shared_ptr<_C2BlockPoolData> &data = nullptr, 76 size_t offset = 0, 77 size_t size = ~(size_t)0); 78 79 /** 80 * Create a graphic block from an allocation for an allotted section. 81 * 82 * \param alloc parent allocation 83 * \param data blockpool data 84 * \param crop allotted crop region 85 * 86 * \return shared pointer to the graphic block. nullptr if there was not enough memory to 87 * create this block. 88 */ 89 static 90 std::shared_ptr<C2GraphicBlock> CreateGraphicBlock( 91 const std::shared_ptr<C2GraphicAllocation> &alloc, 92 const std::shared_ptr<_C2BlockPoolData> &data = nullptr, 93 const C2Rect &allottedCrop = C2Rect(~0u, ~0u)); 94 95 /** 96 * Return a block pool data from 1D block. 97 * 98 * \param shared pointer to the 1D block which is already created. 99 */ 100 static 101 std::shared_ptr<_C2BlockPoolData> GetLinearBlockPoolData( 102 const C2Block1D& block); 103 104 /** 105 * Return a block pool data from 2D block. 106 * 107 * \param shared pointer to the 2D block which is already created. 108 */ 109 static 110 std::shared_ptr<_C2BlockPoolData> GetGraphicBlockPoolData( 111 const C2Block2D& block); 112 113 /** 114 * Create a linear block from the received native handle. 115 * 116 * \param handle native handle to a linear block 117 * 118 * \return shared pointer to the linear block. nullptr if there was not enough memory to 119 * create this block. 120 */ 121 static 122 std::shared_ptr<C2LinearBlock> CreateLinearBlock( 123 const C2Handle *handle); 124 125 /** 126 * Create a graphic block from the received native handle. 127 * 128 * \param handle native handle to a graphic block 129 * 130 * \return shared pointer to the graphic block. nullptr if there was not enough memory to 131 * create this block. 132 */ 133 static 134 std::shared_ptr<C2GraphicBlock> CreateGraphicBlock( 135 const C2Handle *handle); 136 137 /** 138 * Create a linear block from the received bufferpool data. 139 * 140 * \param data bufferpool data to a linear block 141 * 142 * \return shared pointer to the linear block. nullptr if there was not enough memory to 143 * create this block. 144 */ 145 static 146 std::shared_ptr<C2LinearBlock> CreateLinearBlock( 147 const C2Handle *handle, 148 const std::shared_ptr<android::hardware::media::bufferpool::BufferPoolData> &data); 149 150 /** 151 * Create a graphic block from the received bufferpool data. 152 * 153 * \param data bufferpool data to a graphic block 154 * 155 * \return shared pointer to the graphic block. nullptr if there was not enough memory to 156 * create this block. 157 */ 158 static 159 std::shared_ptr<C2GraphicBlock> CreateGraphicBlock( 160 const C2Handle *handle, 161 const std::shared_ptr<android::hardware::media::bufferpool::BufferPoolData> &data); 162 163 /** 164 * Get bufferpool data from the blockpool data. 165 * 166 * \param poolData blockpool data 167 * \param bufferPoolData pointer to bufferpool data where the bufferpool 168 * data is stored. 169 * 170 * \return {\code true} when there is valid bufferpool data, {\code false} otherwise. 171 */ 172 static 173 bool GetBufferPoolData( 174 const std::shared_ptr<const _C2BlockPoolData> &poolData, 175 std::shared_ptr<android::hardware::media::bufferpool::BufferPoolData> *bufferPoolData); 176 177 /* 178 * Life Cycle Management of BufferQueue-Based Blocks 179 * ================================================= 180 * 181 * A block that is created by a bufferqueue-based blockpool requires some 182 * special treatment when it is destroyed. In particular, if the block 183 * corresponds to a held (dequeued/attached) GraphicBuffer in a slot of a 184 * bufferqueue, its destruction should trigger a call to 185 * IGraphicBufferProducer::cancelBuffer(). On the other hand, if the 186 * GraphicBuffer is not held, i.e., if it has been queued or detached, 187 * cancelBuffer() should not be called upon the destruction of the block. 188 * 189 * _C2BlockPoolData created by a bufferqueue-based blockpool includes two 190 * main pieces of information: 191 * - "held" status: Whether cancelBuffer() should be called upon 192 * destruction of the block. 193 * - bufferqueue assignment: The triple (igbp, bqId, bqSlot), where igbp 194 * is the IGraphicBufferProducer instance of the bufferqueue, bqId is 195 * the globally unique id of the bufferqueue, and bqSlot is the slot in 196 * the bufferqueue. 197 * 198 * igbp is the instance of IGraphicBufferProducer on which cancelBuffer() 199 * will be called if "held" status is true when the block is destroyed. 200 * (bqSlot is an input to cancelBuffer().) However, only bqId and bqSlot 201 * are retained when a block is transferred from one process to another. It 202 * is the responsibility of both the sending and receiving processes to 203 * maintain consistency of "held" status and igbp. Below are functions 204 * provided for this purpose: 205 * 206 * - GetBufferQueueData(): Returns bqId and bqSlot. 207 * - HoldBlockFromBufferQueue(): Sets "held" status to true. 208 * - YieldBlockToBufferQueue(): Sets "held" status to false. 209 * - AssignBlockToBufferQueue(): Sets the bufferqueue assignment and 210 * "held" status. 211 * 212 * All these functions operate on _C2BlockPoolData, which can be obtained by 213 * calling GetGraphicBlockPoolData(). 214 * 215 * HoldBlockFromBufferQueue() will mark the block as held, while 216 * YieldBlockToBufferQueue() will do the opposite. These two functions do 217 * not modify the bufferqueue assignment, so it is not wrong to call 218 * HoldBlockFromBufferQueue() after YieldBlockToBufferQueue() if it can be 219 * guaranteed that the block is not destroyed during the period between the 220 * two calls. 221 * 222 * AssingBlockToBufferQueue() has a "held" status as an optional argument. 223 * The default value is true. 224 * 225 * Maintaining Consistency with IGraphicBufferProducer Operations 226 * ============================================================== 227 * 228 * dequeueBuffer() 229 * - This function is called by the blockpool. It should not be called 230 * manually. The blockpool will automatically generate the correct 231 * information for _C2BlockPoolData, with "held" status set to true. 232 * 233 * queueBuffer() 234 * - After queueBuffer() is called, YieldBlockToBufferQueue() should be 235 * called. 236 * 237 * attachBuffer() 238 * - After attachBuffer() is called, AssignBlockToBufferQueue() should be 239 * called with "held" status set to true. 240 * 241 * detachBuffer() 242 * - After detachBuffer() is called, HoldBlockFromBufferQueue() should be 243 * called. 244 */ 245 246 /** 247 * Get bufferqueue data from the blockpool data. 248 * 249 * Calling this function with \p bpId set to nullptr will return whether the 250 * block comes from a bufferqueue-based blockpool. 251 * 252 * \param[in] poolData blockpool data 253 * \param[out] bqId Id of the bufferqueue owning the buffer (block) 254 * \param[out] bqSlot Slot number of the buffer 255 * 256 * \return {\code true} when there is valid bufferqueue data; 257 * {\code false} otherwise. 258 */ 259 static 260 bool GetBufferQueueData( 261 const std::shared_ptr<_C2BlockPoolData>& poolData, 262 uint64_t* bqId = nullptr, int32_t* bqSlot = nullptr); 263 264 /** 265 * Set bufferqueue assignment and "held" status to a block created by a 266 * bufferqueue-based blockpool. 267 * 268 * \param poolData blockpool data associated to the block. 269 * \param igbp \c IGraphicBufferProducer instance from the designated 270 * bufferqueue. 271 * \param bqId Id of the bufferqueue that will own the buffer (block). 272 * \param bqSlot Slot number of the buffer. 273 * \param held Whether the block is held. This "held" status can be 274 * changed later by calling YieldBlockToBufferQueue() or 275 * HoldBlockFromBufferQueue(). 276 * 277 * \return \c true if \p poolData is valid bufferqueue data; 278 * \c false otherwise. 279 * 280 * Note: bqId should match the unique id obtained from igbp->getUniqueId(). 281 */ 282 static 283 bool AssignBlockToBufferQueue( 284 const std::shared_ptr<_C2BlockPoolData>& poolData, 285 const ::android::sp<::android::hardware::graphics::bufferqueue:: 286 V1_0::IGraphicBufferProducer>& igbp, 287 uint64_t bqId, 288 int32_t bqSlot, 289 bool held = true); 290 291 /** 292 * Hold a block from the designated bufferqueue. This causes the destruction 293 * of the block to trigger a call to cancelBuffer(). 294 * 295 * This function assumes that \p poolData comes from a bufferqueue-based 296 * block. It does not check if that is the case. 297 * 298 * \param poolData blockpool data associated to the block. 299 * \param igbp \c IGraphicBufferProducer instance to be assigned to the 300 * block. This is not needed when the block is local. 301 * 302 * \return The previous held status. 303 */ 304 static 305 bool HoldBlockFromBufferQueue( 306 const std::shared_ptr<_C2BlockPoolData>& poolData, 307 const ::android::sp<::android::hardware::graphics::bufferqueue:: 308 V1_0::IGraphicBufferProducer>& igbp = nullptr); 309 310 /** 311 * Yield a block to the designated bufferqueue. This causes the destruction 312 * of the block not to trigger a call to cancelBuffer(); 313 * 314 * This function assumes that \p poolData comes from a bufferqueue-based 315 * block. It does not check if that is the case. 316 * 317 * \param poolData blockpool data associated to the block. 318 * 319 * \return The previous held status. 320 */ 321 static 322 bool YieldBlockToBufferQueue( 323 const std::shared_ptr<_C2BlockPoolData>& poolData); 324 325 }; 326 327 #endif // ANDROID_STAGEFRIGHT_C2BLOCK_INTERNAL_H_ 328 329