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