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