1 /* 2 * Copyright 2016, 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_HARDWARE_GRAPHICS_BUFFERQUEUE_V1_0_CONVERSION_H_ 18 #define ANDROID_HARDWARE_GRAPHICS_BUFFERQUEUE_V1_0_CONVERSION_H_ 19 20 #include <vector> 21 #include <list> 22 23 #include <unistd.h> 24 25 #include <hidl/MQDescriptor.h> 26 #include <hidl/Status.h> 27 28 #include <binder/Binder.h> 29 #include <binder/Status.h> 30 #include <ui/FenceTime.h> 31 #include <cutils/native_handle.h> 32 #include <gui/IGraphicBufferProducer.h> 33 34 #include <android/hardware/graphics/bufferqueue/1.0/IProducerListener.h> 35 36 namespace android { 37 namespace conversion { 38 39 using ::android::hardware::hidl_array; 40 using ::android::hardware::hidl_string; 41 using ::android::hardware::hidl_vec; 42 using ::android::hardware::hidl_handle; 43 using ::android::hardware::Return; 44 using ::android::hardware::Void; 45 using ::android::sp; 46 using ::android::status_t; 47 48 using ::android::String8; 49 50 using ::android::hardware::media::V1_0::Rect; 51 using ::android::hardware::media::V1_0::Region; 52 53 using ::android::hardware::graphics::common::V1_0::Dataspace; 54 55 using ::android::hardware::graphics::common::V1_0::PixelFormat; 56 57 using ::android::hardware::media::V1_0::AnwBuffer; 58 using ::android::GraphicBuffer; 59 60 typedef ::android::hardware::graphics::bufferqueue::V1_0::IGraphicBufferProducer 61 HGraphicBufferProducer; 62 typedef ::android::IGraphicBufferProducer 63 BGraphicBufferProducer; 64 65 // native_handle_t helper functions. 66 67 /** 68 * \brief Take an fd and create a native handle containing only the given fd. 69 * The created handle will need to be deleted manually with 70 * `native_handle_delete()`. 71 * 72 * \param[in] fd The source file descriptor (of type `int`). 73 * \return The create `native_handle_t*` that contains the given \p fd. If the 74 * supplied \p fd is negative, the created native handle will contain no file 75 * descriptors. 76 * 77 * If the native handle cannot be created, the return value will be 78 * `nullptr`. 79 * 80 * This function does not duplicate the file descriptor. 81 */ 82 native_handle_t* native_handle_create_from_fd(int fd); 83 84 /** 85 * \brief Extract a file descriptor from a native handle. 86 * 87 * \param[in] nh The source `native_handle_t*`. 88 * \param[in] index The index of the file descriptor in \p nh to read from. This 89 * input has the default value of `0`. 90 * \return The `index`-th file descriptor in \p nh. If \p nh does not have 91 * enough file descriptors, the returned value will be `-1`. 92 * 93 * This function does not duplicate the file descriptor. 94 */ 95 int native_handle_read_fd(native_handle_t const* nh, int index = 0); 96 97 /** 98 * Conversion functions 99 * ==================== 100 * 101 * There are two main directions of conversion: 102 * - `inTargetType(...)`: Create a wrapper whose lifetime depends on the 103 * input. The wrapper has type `TargetType`. 104 * - `toTargetType(...)`: Create a standalone object of type `TargetType` that 105 * corresponds to the input. The lifetime of the output does not depend on the 106 * lifetime of the input. 107 * - `wrapIn(TargetType*, ...)`: Same as `inTargetType()`, but for `TargetType` 108 * that cannot be copied and/or moved efficiently, or when there are multiple 109 * output arguments. 110 * - `convertTo(TargetType*, ...)`: Same as `toTargetType()`, but for 111 * `TargetType` that cannot be copied and/or moved efficiently, or when there 112 * are multiple output arguments. 113 * 114 * `wrapIn()` and `convertTo()` functions will take output arguments before 115 * input arguments. Some of these functions might return a value to indicate 116 * success or error. 117 * 118 * In converting or wrapping something as a Treble type that contains a 119 * `hidl_handle`, `native_handle_t*` will need to be created and returned as 120 * an additional output argument, hence only `wrapIn()` or `convertTo()` would 121 * be available. The caller must call `native_handle_delete()` to deallocate the 122 * returned native handle when it is no longer needed. 123 * 124 * For types that contain file descriptors, `inTargetType()` and `wrapAs()` do 125 * not perform duplication of file descriptors, while `toTargetType()` and 126 * `convertTo()` do. 127 */ 128 129 /** 130 * \brief Convert `Return<void>` to `binder::Status`. 131 * 132 * \param[in] t The source `Return<void>`. 133 * \return The corresponding `binder::Status`. 134 */ 135 // convert: Return<void> -> ::android::binder::Status 136 ::android::binder::Status toBinderStatus(Return<void> const& t); 137 138 /** 139 * \brief Convert `Return<void>` to `status_t`. This is for legacy binder calls. 140 * 141 * \param[in] t The source `Return<void>`. 142 * \return The corresponding `status_t`. 143 */ 144 // convert: Return<void> -> status_t 145 status_t toStatusT(Return<void> const& t); 146 147 /** 148 * \brief Wrap `native_handle_t*` in `hidl_handle`. 149 * 150 * \param[in] nh The source `native_handle_t*`. 151 * \return The `hidl_handle` that points to \p nh. 152 */ 153 // wrap: native_handle_t* -> hidl_handle 154 hidl_handle inHidlHandle(native_handle_t const* nh); 155 156 /** 157 * \brief Convert `int32_t` to `Dataspace`. 158 * 159 * \param[in] l The source `int32_t`. 160 * \result The corresponding `Dataspace`. 161 */ 162 // convert: int32_t -> Dataspace 163 Dataspace toHardwareDataspace(int32_t l); 164 165 /** 166 * \brief Convert `Dataspace` to `int32_t`. 167 * 168 * \param[in] t The source `Dataspace`. 169 * \result The corresponding `int32_t`. 170 */ 171 // convert: Dataspace -> int32_t 172 int32_t toRawDataspace(Dataspace const& t); 173 174 /** 175 * \brief Wrap an opaque buffer inside a `hidl_vec<uint8_t>`. 176 * 177 * \param[in] l The pointer to the beginning of the opaque buffer. 178 * \param[in] size The size of the buffer. 179 * \return A `hidl_vec<uint8_t>` that points to the buffer. 180 */ 181 // wrap: void*, size_t -> hidl_vec<uint8_t> 182 hidl_vec<uint8_t> inHidlBytes(void const* l, size_t size); 183 184 /** 185 * \brief Create a `hidl_vec<uint8_t>` that is a copy of an opaque buffer. 186 * 187 * \param[in] l The pointer to the beginning of the opaque buffer. 188 * \param[in] size The size of the buffer. 189 * \return A `hidl_vec<uint8_t>` that is a copy of the input buffer. 190 */ 191 // convert: void*, size_t -> hidl_vec<uint8_t> 192 hidl_vec<uint8_t> toHidlBytes(void const* l, size_t size); 193 194 /** 195 * \brief Wrap `GraphicBuffer` in `AnwBuffer`. 196 * 197 * \param[out] t The wrapper of type `AnwBuffer`. 198 * \param[in] l The source `GraphicBuffer`. 199 */ 200 // wrap: GraphicBuffer -> AnwBuffer 201 void wrapAs(AnwBuffer* t, GraphicBuffer const& l); 202 203 /** 204 * \brief Convert `AnwBuffer` to `GraphicBuffer`. 205 * 206 * \param[out] l The destination `GraphicBuffer`. 207 * \param[in] t The source `AnwBuffer`. 208 * 209 * This function will duplicate all file descriptors in \p t. 210 */ 211 // convert: AnwBuffer -> GraphicBuffer 212 // Ref: frameworks/native/libs/ui/GraphicBuffer.cpp: GraphicBuffer::flatten 213 bool convertTo(GraphicBuffer* l, AnwBuffer const& t); 214 215 /** 216 * Conversion functions for types outside media 217 * ============================================ 218 * 219 * Some objects in libui and libgui that were made to go through binder calls do 220 * not expose ways to read or write their fields to the public. To pass an 221 * object of this kind through the HIDL boundary, translation functions need to 222 * work around the access restriction by using the publicly available 223 * `flatten()` and `unflatten()` functions. 224 * 225 * All `flatten()` and `unflatten()` overloads follow the same convention as 226 * follows: 227 * 228 * status_t flatten(ObjectType const& object, 229 * [OtherType const& other, ...] 230 * void*& buffer, size_t& size, 231 * int*& fds, size_t& numFds) 232 * 233 * status_t unflatten(ObjectType* object, 234 * [OtherType* other, ...,] 235 * void*& buffer, size_t& size, 236 * int*& fds, size_t& numFds) 237 * 238 * The number of `other` parameters varies depending on the `ObjectType`. For 239 * example, in the process of unflattening an object that contains 240 * `hidl_handle`, `other` is needed to hold `native_handle_t` objects that will 241 * be created. 242 * 243 * The last four parameters always work the same way in all overloads of 244 * `flatten()` and `unflatten()`: 245 * - For `flatten()`, `buffer` is the pointer to the non-fd buffer to be filled, 246 * `size` is the size (in bytes) of the non-fd buffer pointed to by `buffer`, 247 * `fds` is the pointer to the fd buffer to be filled, and `numFds` is the 248 * size (in ints) of the fd buffer pointed to by `fds`. 249 * - For `unflatten()`, `buffer` is the pointer to the non-fd buffer to be read 250 * from, `size` is the size (in bytes) of the non-fd buffer pointed to by 251 * `buffer`, `fds` is the pointer to the fd buffer to be read from, and 252 * `numFds` is the size (in ints) of the fd buffer pointed to by `fds`. 253 * - After a successful call to `flatten()` or `unflatten()`, `buffer` and `fds` 254 * will be advanced, while `size` and `numFds` will be decreased to reflect 255 * how much storage/data of the two buffers (fd and non-fd) have been used. 256 * - After an unsuccessful call, the values of `buffer`, `size`, `fds` and 257 * `numFds` are invalid. 258 * 259 * The return value of a successful `flatten()` or `unflatten()` call will be 260 * `OK` (also aliased as `NO_ERROR`). Any other values indicate a failure. 261 * 262 * For each object type that supports flattening, there will be two accompanying 263 * functions: `getFlattenedSize()` and `getFdCount()`. `getFlattenedSize()` will 264 * return the size of the non-fd buffer that the object will need for 265 * flattening. `getFdCount()` will return the size of the fd buffer that the 266 * object will need for flattening. 267 * 268 * The set of these four functions, `getFlattenedSize()`, `getFdCount()`, 269 * `flatten()` and `unflatten()`, are similar to functions of the same name in 270 * the abstract class `Flattenable`. The only difference is that functions in 271 * this file are not member functions of the object type. For example, we write 272 * 273 * flatten(x, buffer, size, fds, numFds) 274 * 275 * instead of 276 * 277 * x.flatten(buffer, size, fds, numFds) 278 * 279 * because we cannot modify the type of `x`. 280 * 281 * There is one exception to the naming convention: `hidl_handle` that 282 * represents a fence. The four functions for this "Fence" type have the word 283 * "Fence" attched to their names because the object type, which is 284 * `hidl_handle`, does not carry the special meaning that the object itself can 285 * only contain zero or one file descriptor. 286 */ 287 288 // Ref: frameworks/native/libs/ui/Fence.cpp 289 290 /** 291 * \brief Return the size of the non-fd buffer required to flatten a fence. 292 * 293 * \param[in] fence The input fence of type `hidl_handle`. 294 * \return The required size of the flat buffer. 295 * 296 * The current version of this function always returns 4, which is the number of 297 * bytes required to store the number of file descriptors contained in the fd 298 * part of the flat buffer. 299 */ 300 size_t getFenceFlattenedSize(hidl_handle const& fence); 301 302 /** 303 * \brief Return the number of file descriptors contained in a fence. 304 * 305 * \param[in] fence The input fence of type `hidl_handle`. 306 * \return `0` if \p fence does not contain a valid file descriptor, or `1` 307 * otherwise. 308 */ 309 size_t getFenceFdCount(hidl_handle const& fence); 310 311 /** 312 * \brief Unflatten `Fence` to `hidl_handle`. 313 * 314 * \param[out] fence The destination `hidl_handle`. 315 * \param[out] nh The underlying native handle. 316 * \param[in,out] buffer The pointer to the flat non-fd buffer. 317 * \param[in,out] size The size of the flat non-fd buffer. 318 * \param[in,out] fds The pointer to the flat fd buffer. 319 * \param[in,out] numFds The size of the flat fd buffer. 320 * \return `NO_ERROR` on success; other value on failure. 321 * 322 * If the return value is `NO_ERROR`, \p nh will point to a newly created 323 * native handle, which needs to be deleted with `native_handle_delete()` 324 * afterwards. 325 */ 326 status_t unflattenFence(hidl_handle* fence, native_handle_t** nh, 327 void const*& buffer, size_t& size, int const*& fds, size_t& numFds); 328 329 /** 330 * \brief Flatten `hidl_handle` as `Fence`. 331 * 332 * \param[in] t The source `hidl_handle`. 333 * \param[in,out] buffer The pointer to the flat non-fd buffer. 334 * \param[in,out] size The size of the flat non-fd buffer. 335 * \param[in,out] fds The pointer to the flat fd buffer. 336 * \param[in,out] numFds The size of the flat fd buffer. 337 * \return `NO_ERROR` on success; other value on failure. 338 */ 339 status_t flattenFence(hidl_handle const& fence, 340 void*& buffer, size_t& size, int*& fds, size_t& numFds); 341 342 /** 343 * \brief Wrap `Fence` in `hidl_handle`. 344 * 345 * \param[out] t The wrapper of type `hidl_handle`. 346 * \param[out] nh The native handle pointed to by \p t. 347 * \param[in] l The source `Fence`. 348 * 349 * On success, \p nh will hold a newly created native handle, which must be 350 * deleted manually with `native_handle_delete()` afterwards. 351 */ 352 // wrap: Fence -> hidl_handle 353 bool wrapAs(hidl_handle* t, native_handle_t** nh, Fence const& l); 354 355 /** 356 * \brief Convert `hidl_handle` to `Fence`. 357 * 358 * \param[out] l The destination `Fence`. `l` must not have been used 359 * (`l->isValid()` must return `false`) before this function is called. 360 * \param[in] t The source `hidl_handle`. 361 * 362 * If \p t contains a valid file descriptor, it will be duplicated. 363 */ 364 // convert: hidl_handle -> Fence 365 bool convertTo(Fence* l, hidl_handle const& t); 366 367 // Ref: frameworks/native/libs/ui/FenceTime.cpp: FenceTime::Snapshot 368 369 /** 370 * \brief Return the size of the non-fd buffer required to flatten 371 * `FenceTimeSnapshot`. 372 * 373 * \param[in] t The input `FenceTimeSnapshot`. 374 * \return The required size of the flat buffer. 375 */ 376 size_t getFlattenedSize(HGraphicBufferProducer::FenceTimeSnapshot const& t); 377 378 /** 379 * \brief Return the number of file descriptors contained in 380 * `FenceTimeSnapshot`. 381 * 382 * \param[in] t The input `FenceTimeSnapshot`. 383 * \return The number of file descriptors contained in \p snapshot. 384 */ 385 size_t getFdCount(HGraphicBufferProducer::FenceTimeSnapshot const& t); 386 387 /** 388 * \brief Flatten `FenceTimeSnapshot`. 389 * 390 * \param[in] t The source `FenceTimeSnapshot`. 391 * \param[in,out] buffer The pointer to the flat non-fd buffer. 392 * \param[in,out] size The size of the flat non-fd buffer. 393 * \param[in,out] fds The pointer to the flat fd buffer. 394 * \param[in,out] numFds The size of the flat fd buffer. 395 * \return `NO_ERROR` on success; other value on failure. 396 * 397 * This function will duplicate the file descriptor in `t.fence` if `t.state == 398 * FENCE`. 399 */ 400 status_t flatten(HGraphicBufferProducer::FenceTimeSnapshot const& t, 401 void*& buffer, size_t& size, int*& fds, size_t& numFds); 402 403 /** 404 * \brief Unflatten `FenceTimeSnapshot`. 405 * 406 * \param[out] t The destination `FenceTimeSnapshot`. 407 * \param[out] nh The underlying native handle. 408 * \param[in,out] buffer The pointer to the flat non-fd buffer. 409 * \param[in,out] size The size of the flat non-fd buffer. 410 * \param[in,out] fds The pointer to the flat fd buffer. 411 * \param[in,out] numFds The size of the flat fd buffer. 412 * \return `NO_ERROR` on success; other value on failure. 413 * 414 * If the return value is `NO_ERROR` and the constructed snapshot contains a 415 * file descriptor, \p nh will be created to hold that file descriptor. In this 416 * case, \p nh needs to be deleted with `native_handle_delete()` afterwards. 417 */ 418 status_t unflatten( 419 HGraphicBufferProducer::FenceTimeSnapshot* t, native_handle_t** nh, 420 void const*& buffer, size_t& size, int const*& fds, size_t& numFds); 421 422 // Ref: frameworks/native/libs/gui/FrameTimestamps.cpp: FrameEventsDelta 423 424 /** 425 * \brief Return the size of the non-fd buffer required to flatten 426 * `FrameEventsDelta`. 427 * 428 * \param[in] t The input `FrameEventsDelta`. 429 * \return The required size of the flat buffer. 430 */ 431 size_t getFlattenedSize(HGraphicBufferProducer::FrameEventsDelta const& t); 432 433 /** 434 * \brief Return the number of file descriptors contained in 435 * `FrameEventsDelta`. 436 * 437 * \param[in] t The input `FrameEventsDelta`. 438 * \return The number of file descriptors contained in \p t. 439 */ 440 size_t getFdCount(HGraphicBufferProducer::FrameEventsDelta const& t); 441 442 /** 443 * \brief Unflatten `FrameEventsDelta`. 444 * 445 * \param[out] t The destination `FrameEventsDelta`. 446 * \param[out] nh The underlying array of native handles. 447 * \param[in,out] buffer The pointer to the flat non-fd buffer. 448 * \param[in,out] size The size of the flat non-fd buffer. 449 * \param[in,out] fds The pointer to the flat fd buffer. 450 * \param[in,out] numFds The size of the flat fd buffer. 451 * \return `NO_ERROR` on success; other value on failure. 452 * 453 * If the return value is `NO_ERROR`, \p nh will have length 4, and it will be 454 * populated with `nullptr` or newly created handles. Each non-null slot in \p 455 * nh will need to be deleted manually with `native_handle_delete()`. 456 */ 457 status_t unflatten(HGraphicBufferProducer::FrameEventsDelta* t, 458 std::vector<native_handle_t*>* nh, 459 void const*& buffer, size_t& size, int const*& fds, size_t& numFds); 460 461 /** 462 * \brief Flatten `FrameEventsDelta`. 463 * 464 * \param[in] t The source `FrameEventsDelta`. 465 * \param[in,out] buffer The pointer to the flat non-fd buffer. 466 * \param[in,out] size The size of the flat non-fd buffer. 467 * \param[in,out] fds The pointer to the flat fd buffer. 468 * \param[in,out] numFds The size of the flat fd buffer. 469 * \return `NO_ERROR` on success; other value on failure. 470 * 471 * This function will duplicate file descriptors contained in \p t. 472 */ 473 // Ref: frameworks/native/libs/gui/FrameTimestamp.cpp: 474 // FrameEventsDelta::flatten 475 status_t flatten(HGraphicBufferProducer::FrameEventsDelta const& t, 476 void*& buffer, size_t& size, int*& fds, size_t numFds); 477 478 // Ref: frameworks/native/libs/gui/FrameTimestamps.cpp: FrameEventHistoryDelta 479 480 /** 481 * \brief Return the size of the non-fd buffer required to flatten 482 * `HGraphicBufferProducer::FrameEventHistoryDelta`. 483 * 484 * \param[in] t The input `HGraphicBufferProducer::FrameEventHistoryDelta`. 485 * \return The required size of the flat buffer. 486 */ 487 size_t getFlattenedSize( 488 HGraphicBufferProducer::FrameEventHistoryDelta const& t); 489 490 /** 491 * \brief Return the number of file descriptors contained in 492 * `HGraphicBufferProducer::FrameEventHistoryDelta`. 493 * 494 * \param[in] t The input `HGraphicBufferProducer::FrameEventHistoryDelta`. 495 * \return The number of file descriptors contained in \p t. 496 */ 497 size_t getFdCount( 498 HGraphicBufferProducer::FrameEventHistoryDelta const& t); 499 500 /** 501 * \brief Unflatten `FrameEventHistoryDelta`. 502 * 503 * \param[out] t The destination `FrameEventHistoryDelta`. 504 * \param[out] nh The underlying array of arrays of native handles. 505 * \param[in,out] buffer The pointer to the flat non-fd buffer. 506 * \param[in,out] size The size of the flat non-fd buffer. 507 * \param[in,out] fds The pointer to the flat fd buffer. 508 * \param[in,out] numFds The size of the flat fd buffer. 509 * \return `NO_ERROR` on success; other value on failure. 510 * 511 * If the return value is `NO_ERROR`, \p nh will be populated with `nullptr` or 512 * newly created handles. The second dimension of \p nh will be 4. Each non-null 513 * slot in \p nh will need to be deleted manually with `native_handle_delete()`. 514 */ 515 status_t unflatten( 516 HGraphicBufferProducer::FrameEventHistoryDelta* t, 517 std::vector<std::vector<native_handle_t*> >* nh, 518 void const*& buffer, size_t& size, int const*& fds, size_t& numFds); 519 520 /** 521 * \brief Flatten `FrameEventHistoryDelta`. 522 * 523 * \param[in] t The source `FrameEventHistoryDelta`. 524 * \param[in,out] buffer The pointer to the flat non-fd buffer. 525 * \param[in,out] size The size of the flat non-fd buffer. 526 * \param[in,out] fds The pointer to the flat fd buffer. 527 * \param[in,out] numFds The size of the flat fd buffer. 528 * \return `NO_ERROR` on success; other value on failure. 529 * 530 * This function will duplicate file descriptors contained in \p t. 531 */ 532 status_t flatten( 533 HGraphicBufferProducer::FrameEventHistoryDelta const& t, 534 void*& buffer, size_t& size, int*& fds, size_t& numFds); 535 536 /** 537 * \brief Wrap `::android::FrameEventHistoryData` in 538 * `HGraphicBufferProducer::FrameEventHistoryDelta`. 539 * 540 * \param[out] t The wrapper of type 541 * `HGraphicBufferProducer::FrameEventHistoryDelta`. 542 * \param[out] nh The array of array of native handles that are referred to by 543 * members of \p t. 544 * \param[in] l The source `::android::FrameEventHistoryDelta`. 545 * 546 * On success, each member of \p nh will be either `nullptr` or a newly created 547 * native handle. All the non-`nullptr` elements must be deleted individually 548 * with `native_handle_delete()`. 549 */ 550 bool wrapAs(HGraphicBufferProducer::FrameEventHistoryDelta* t, 551 std::vector<std::vector<native_handle_t*> >* nh, 552 ::android::FrameEventHistoryDelta const& l); 553 554 /** 555 * \brief Convert `HGraphicBufferProducer::FrameEventHistoryDelta` to 556 * `::android::FrameEventHistoryDelta`. 557 * 558 * \param[out] l The destination `::android::FrameEventHistoryDelta`. 559 * \param[in] t The source `HGraphicBufferProducer::FrameEventHistoryDelta`. 560 * 561 * This function will duplicate all file descriptors contained in \p t. 562 */ 563 bool convertTo( 564 ::android::FrameEventHistoryDelta* l, 565 HGraphicBufferProducer::FrameEventHistoryDelta const& t); 566 567 // Ref: frameworks/native/libs/ui/Region.cpp 568 569 /** 570 * \brief Return the size of the buffer required to flatten `Region`. 571 * 572 * \param[in] t The input `Region`. 573 * \return The required size of the flat buffer. 574 */ 575 size_t getFlattenedSize(Region const& t); 576 577 /** 578 * \brief Unflatten `Region`. 579 * 580 * \param[out] t The destination `Region`. 581 * \param[in,out] buffer The pointer to the flat buffer. 582 * \param[in,out] size The size of the flat buffer. 583 * \return `NO_ERROR` on success; other value on failure. 584 */ 585 status_t unflatten(Region* t, void const*& buffer, size_t& size); 586 587 /** 588 * \brief Flatten `Region`. 589 * 590 * \param[in] t The source `Region`. 591 * \param[in,out] buffer The pointer to the flat buffer. 592 * \param[in,out] size The size of the flat buffer. 593 * \return `NO_ERROR` on success; other value on failure. 594 */ 595 status_t flatten(Region const& t, void*& buffer, size_t& size); 596 597 /** 598 * \brief Convert `::android::Region` to `Region`. 599 * 600 * \param[out] t The destination `Region`. 601 * \param[in] l The source `::android::Region`. 602 */ 603 // convert: ::android::Region -> Region 604 bool convertTo(Region* t, ::android::Region const& l); 605 606 /** 607 * \brief Convert `Region` to `::android::Region`. 608 * 609 * \param[out] l The destination `::android::Region`. 610 * \param[in] t The source `Region`. 611 */ 612 // convert: Region -> ::android::Region 613 bool convertTo(::android::Region* l, Region const& t); 614 615 // Ref: frameworks/native/libs/gui/BGraphicBufferProducer.cpp: 616 // BGraphicBufferProducer::QueueBufferInput 617 618 /** 619 * \brief Return the size of the buffer required to flatten 620 * `HGraphicBufferProducer::QueueBufferInput`. 621 * 622 * \param[in] t The input `HGraphicBufferProducer::QueueBufferInput`. 623 * \return The required size of the flat buffer. 624 */ 625 size_t getFlattenedSize(HGraphicBufferProducer::QueueBufferInput const& t); 626 627 /** 628 * \brief Return the number of file descriptors contained in 629 * `HGraphicBufferProducer::QueueBufferInput`. 630 * 631 * \param[in] t The input `HGraphicBufferProducer::QueueBufferInput`. 632 * \return The number of file descriptors contained in \p t. 633 */ 634 size_t getFdCount( 635 HGraphicBufferProducer::QueueBufferInput const& t); 636 /** 637 * \brief Flatten `HGraphicBufferProducer::QueueBufferInput`. 638 * 639 * \param[in] t The source `HGraphicBufferProducer::QueueBufferInput`. 640 * \param[out] nh The native handle cloned from `t.fence`. 641 * \param[in,out] buffer The pointer to the flat non-fd buffer. 642 * \param[in,out] size The size of the flat non-fd buffer. 643 * \param[in,out] fds The pointer to the flat fd buffer. 644 * \param[in,out] numFds The size of the flat fd buffer. 645 * \return `NO_ERROR` on success; other value on failure. 646 * 647 * This function will duplicate the file descriptor in `t.fence`. */ 648 status_t flatten(HGraphicBufferProducer::QueueBufferInput const& t, 649 native_handle_t** nh, 650 void*& buffer, size_t& size, int*& fds, size_t& numFds); 651 652 /** 653 * \brief Unflatten `HGraphicBufferProducer::QueueBufferInput`. 654 * 655 * \param[out] t The destination `HGraphicBufferProducer::QueueBufferInput`. 656 * \param[out] nh The underlying native handle for `t->fence`. 657 * \param[in,out] buffer The pointer to the flat non-fd buffer. 658 * \param[in,out] size The size of the flat non-fd buffer. 659 * \param[in,out] fds The pointer to the flat fd buffer. 660 * \param[in,out] numFds The size of the flat fd buffer. 661 * \return `NO_ERROR` on success; other value on failure. 662 * 663 * If the return value is `NO_ERROR` and `t->fence` contains a valid file 664 * descriptor, \p nh will be a newly created native handle holding that file 665 * descriptor. \p nh needs to be deleted with `native_handle_delete()` 666 * afterwards. 667 */ 668 status_t unflatten( 669 HGraphicBufferProducer::QueueBufferInput* t, native_handle_t** nh, 670 void const*& buffer, size_t& size, int const*& fds, size_t& numFds); 671 672 /** 673 * \brief Wrap `BGraphicBufferProducer::QueueBufferInput` in 674 * `HGraphicBufferProducer::QueueBufferInput`. 675 * 676 * \param[out] t The wrapper of type 677 * `HGraphicBufferProducer::QueueBufferInput`. 678 * \param[out] nh The underlying native handle for `t->fence`. 679 * \param[in] l The source `BGraphicBufferProducer::QueueBufferInput`. 680 * 681 * If the return value is `true` and `t->fence` contains a valid file 682 * descriptor, \p nh will be a newly created native handle holding that file 683 * descriptor. \p nh needs to be deleted with `native_handle_delete()` 684 * afterwards. 685 */ 686 bool wrapAs( 687 HGraphicBufferProducer::QueueBufferInput* t, 688 native_handle_t** nh, 689 BGraphicBufferProducer::QueueBufferInput const& l); 690 691 /** 692 * \brief Convert `HGraphicBufferProducer::QueueBufferInput` to 693 * `BGraphicBufferProducer::QueueBufferInput`. 694 * 695 * \param[out] l The destination `BGraphicBufferProducer::QueueBufferInput`. 696 * \param[in] t The source `HGraphicBufferProducer::QueueBufferInput`. 697 * 698 * If `t.fence` has a valid file descriptor, it will be duplicated. 699 */ 700 bool convertTo( 701 BGraphicBufferProducer::QueueBufferInput* l, 702 HGraphicBufferProducer::QueueBufferInput const& t); 703 704 // Ref: frameworks/native/libs/gui/BGraphicBufferProducer.cpp: 705 // BGraphicBufferProducer::QueueBufferOutput 706 707 /** 708 * \brief Wrap `BGraphicBufferProducer::QueueBufferOutput` in 709 * `HGraphicBufferProducer::QueueBufferOutput`. 710 * 711 * \param[out] t The wrapper of type 712 * `HGraphicBufferProducer::QueueBufferOutput`. 713 * \param[out] nh The array of array of native handles that are referred to by 714 * members of \p t. 715 * \param[in] l The source `BGraphicBufferProducer::QueueBufferOutput`. 716 * 717 * On success, each member of \p nh will be either `nullptr` or a newly created 718 * native handle. All the non-`nullptr` elements must be deleted individually 719 * with `native_handle_delete()`. 720 */ 721 // wrap: BGraphicBufferProducer::QueueBufferOutput -> 722 // HGraphicBufferProducer::QueueBufferOutput 723 bool wrapAs(HGraphicBufferProducer::QueueBufferOutput* t, 724 std::vector<std::vector<native_handle_t*> >* nh, 725 BGraphicBufferProducer::QueueBufferOutput const& l); 726 727 /** 728 * \brief Convert `HGraphicBufferProducer::QueueBufferOutput` to 729 * `BGraphicBufferProducer::QueueBufferOutput`. 730 * 731 * \param[out] l The destination `BGraphicBufferProducer::QueueBufferOutput`. 732 * \param[in] t The source `HGraphicBufferProducer::QueueBufferOutput`. 733 * 734 * This function will duplicate all file descriptors contained in \p t. 735 */ 736 // convert: HGraphicBufferProducer::QueueBufferOutput -> 737 // BGraphicBufferProducer::QueueBufferOutput 738 bool convertTo( 739 BGraphicBufferProducer::QueueBufferOutput* l, 740 HGraphicBufferProducer::QueueBufferOutput const& t); 741 742 /** 743 * \brief Convert `BGraphicBufferProducer::DisconnectMode` to 744 * `HGraphicBufferProducer::DisconnectMode`. 745 * 746 * \param[in] l The source `BGraphicBufferProducer::DisconnectMode`. 747 * \return The corresponding `HGraphicBufferProducer::DisconnectMode`. 748 */ 749 HGraphicBufferProducer::DisconnectMode toHidlDisconnectMode( 750 BGraphicBufferProducer::DisconnectMode l); 751 752 /** 753 * \brief Convert `HGraphicBufferProducer::DisconnectMode` to 754 * `BGraphicBufferProducer::DisconnectMode`. 755 * 756 * \param[in] l The source `HGraphicBufferProducer::DisconnectMode`. 757 * \return The corresponding `BGraphicBufferProducer::DisconnectMode`. 758 */ 759 BGraphicBufferProducer::DisconnectMode toGuiDisconnectMode( 760 HGraphicBufferProducer::DisconnectMode t); 761 762 } // namespace conversion 763 } // namespace android 764 765 #endif // ANDROID_HARDWARE_GRAPHICS_BUFFERQUEUE_V1_0_CONVERSION_H_ 766