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 quadruple (igbp, generation, bqId, 194 * bqSlot), where igbp is the IGraphicBufferProducer instance of the 195 * bufferqueue, generation is the latest generation number, of the 196 * bufferqueue, bqId is the globally unique id of the bufferqueue, and 197 * bqSlot is the slot in the bufferqueue. 198 * 199 * igbp is the instance of IGraphicBufferProducer on which cancelBuffer() 200 * will be called if "held" status is true when the block is destroyed. 201 * (bqSlot is an input to cancelBuffer().) However, only generation, bqId 202 * and bqSlot are retained when a block is transferred from one process to 203 * another. It is the responsibility of both the sending and receiving 204 * processes to maintain consistency of "held" status and igbp. Below are 205 * functions provided for this purpose: 206 * 207 * - GetBufferQueueData(): Returns generation, bqId and bqSlot. 208 * - HoldBlockFromBufferQueue(): Sets "held" status to true. 209 * - YieldBlockToBufferQueue(): Sets "held" status to false. 210 * - AssignBlockToBufferQueue(): Sets the bufferqueue assignment and 211 * "held" status. 212 * 213 * All these functions operate on _C2BlockPoolData, which can be obtained by 214 * calling GetGraphicBlockPoolData(). 215 * 216 * HoldBlockFromBufferQueue() will mark the block as held, while 217 * YieldBlockToBufferQueue() will do the opposite. These two functions do 218 * not modify the bufferqueue assignment, so it is not wrong to call 219 * HoldBlockFromBufferQueue() after YieldBlockToBufferQueue() if it can be 220 * guaranteed that the block is not destroyed during the period between the 221 * two calls. 222 * 223 * AssingBlockToBufferQueue() has a "held" status as an optional argument. 224 * The default value is true. 225 * 226 * Maintaining Consistency with IGraphicBufferProducer Operations 227 * ============================================================== 228 * 229 * dequeueBuffer() 230 * - This function is called by the blockpool. It should not be called 231 * manually. The blockpool will automatically generate the correct 232 * information for _C2BlockPoolData, with "held" status set to true. 233 * 234 * queueBuffer() 235 * - After queueBuffer() is called, YieldBlockToBufferQueue() should be 236 * called. 237 * 238 * attachBuffer() 239 * - After attachBuffer() is called, AssignBlockToBufferQueue() should be 240 * called with "held" status set to true. 241 * 242 * detachBuffer() 243 * - After detachBuffer() is called, HoldBlockFromBufferQueue() should be 244 * called. 245 */ 246 247 /** 248 * Get bufferqueue data from the blockpool data. 249 * 250 * Calling this function with \p generation set to nullptr will return 251 * whether the block comes from a bufferqueue-based blockpool, but will not 252 * fill in the values for \p generation, \p bqId or \p bqSlot. 253 * 254 * \param[in] poolData blockpool data. 255 * \param[out] generation Generation number attached to the buffer. 256 * \param[out] bqId Id of the bufferqueue owning the buffer (block). 257 * \param[out] bqSlot Slot number of the buffer. 258 * 259 * \return \c true when there is valid bufferqueue data; 260 * \c false otherwise. 261 */ 262 static 263 bool GetBufferQueueData( 264 const std::shared_ptr<_C2BlockPoolData>& poolData, 265 uint32_t* generation = nullptr, 266 uint64_t* bqId = nullptr, 267 int32_t* bqSlot = nullptr); 268 269 /** 270 * Set bufferqueue assignment and "held" status to a block created by a 271 * bufferqueue-based blockpool. 272 * 273 * \param poolData blockpool data associated to the block. 274 * \param igbp \c IGraphicBufferProducer instance from the designated 275 * bufferqueue. 276 * \param generation Generation number that the buffer belongs to. 277 * \param bqId Id of the bufferqueue that will own the buffer (block). 278 * \param bqSlot Slot number of the buffer. 279 * \param held Whether the block is held. This "held" status can be 280 * changed later by calling YieldBlockToBufferQueue() or 281 * HoldBlockFromBufferQueue(). 282 * 283 * \return \c true if \p poolData is valid bufferqueue data; 284 * \c false otherwise. 285 * 286 * Note: \p generation should match the latest generation number set on the 287 * bufferqueue, and \p bqId should match the unique id for the bufferqueue 288 * (obtainable by calling igbp->getUniqueId()). 289 */ 290 static 291 bool AssignBlockToBufferQueue( 292 const std::shared_ptr<_C2BlockPoolData>& poolData, 293 const ::android::sp<::android::hardware::graphics::bufferqueue:: 294 V1_0::IGraphicBufferProducer>& igbp, 295 uint32_t generation, 296 uint64_t bqId, 297 int32_t bqSlot, 298 bool held = true); 299 300 /** 301 * Hold a block from the designated bufferqueue. This causes the destruction 302 * of the block to trigger a call to cancelBuffer(). 303 * 304 * This function assumes that \p poolData comes from a bufferqueue-based 305 * block. It does not check if that is the case. 306 * 307 * \param poolData blockpool data associated to the block. 308 * \param igbp \c IGraphicBufferProducer instance to be assigned to the 309 * block. This is not needed when the block is local. 310 * 311 * \return The previous held status. 312 */ 313 static 314 bool HoldBlockFromBufferQueue( 315 const std::shared_ptr<_C2BlockPoolData>& poolData, 316 const ::android::sp<::android::hardware::graphics::bufferqueue:: 317 V1_0::IGraphicBufferProducer>& igbp = nullptr); 318 319 /** 320 * Yield a block to the designated bufferqueue. This causes the destruction 321 * of the block not to trigger a call to cancelBuffer(); 322 * 323 * This function assumes that \p poolData comes from a bufferqueue-based 324 * block. It does not check if that is the case. 325 * 326 * \param poolData blockpool data associated to the block. 327 * 328 * \return The previous held status. 329 */ 330 static 331 bool YieldBlockToBufferQueue( 332 const std::shared_ptr<_C2BlockPoolData>& poolData); 333 334 }; 335 336 #endif // ANDROID_STAGEFRIGHT_C2BLOCK_INTERNAL_H_ 337 338