| Flutter Impeller |

surface_transaction.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #ifndef FLUTTER_IMPELLER_TOOLKIT_ANDROID_SURFACE_TRANSACTION_H_
6 #define FLUTTER_IMPELLER_TOOLKIT_ANDROID_SURFACE_TRANSACTION_H_
7
8 #include <functional>
9 #include <map>
10
11 #include "flutter/fml/unique_fd.h"
12 #include "flutter/fml/unique_object.h"
13 #include "impeller/geometry/color.h"
14 #include "impeller/toolkit/android/proc_table.h"
15
16 namespace impeller::android {
17
18 class SurfaceControl;
19 class HardwareBuffer;
20
21 //------------------------------------------------------------------------------
22 /// @brief A wrapper for ASurfaceTransaction.
23 /// https://developer.android.com/ndk/reference/group/native-activity#asurfacetransaction
24 ///
25 /// A surface transaction is a collection of updates to the
26 /// hierarchy of surfaces (represented by `ASurfaceControl`
27 /// instances) that are applied atomically in the compositor.
28 ///
29 /// This wrapper is only available on Android API 29 and above.
30 ///
31 /// @note Transactions should be short lived objects (create, apply,
32 /// collect). But, if these are used on multiple threads, they must
33 /// be externally synchronized.
34 ///
35 class SurfaceTransaction {
36 public:
37 //----------------------------------------------------------------------------
38 /// @return `true` if any surface transactions can be created on this
39 /// platform.
40 ///
41 static bool IsAvailableOnPlatform();
42
43 SurfaceTransaction();
44
45 ~SurfaceTransaction();
46
47 SurfaceTransaction(const SurfaceTransaction&) = delete;
48
49 SurfaceTransaction& operator=(const SurfaceTransaction&) = delete;
50
51 bool IsValid() const;
52
53 //----------------------------------------------------------------------------
54 /// @brief Encodes that the updated contents of a surface control are
55 /// specified by the given hardware buffer. The update will not be
56 /// committed till the call to `Apply` however.
57 ///
58 /// @see `SurfaceTransaction::Apply`.
59 ///
60 /// @param[in] control The control.
61 /// @param[in] buffer The hardware buffer.
62 /// @param[in] acquire_fence The fence to wait on before setting the
63 /// contents.
64 ///
65 /// @return If the update was encoded in the transaction.
66 ///
67 [[nodiscard]] bool SetContents(const SurfaceControl* control,
68 const HardwareBuffer* buffer,
69 fml::UniqueFD acquire_fence = {});
70
71 //----------------------------------------------------------------------------
72 /// @brief Encodes the updated background color of the surface control.
73 /// The update will not be committed till the call to `Apply`
74 /// however.
75 ///
76 /// @see `SurfaceTransaction::Apply`.
77 ///
78 /// @param[in] control The control
79 /// @param[in] color The color
80 ///
81 /// @return `true` if the background control will be set when transaction
82 /// is applied.
83 ///
84 [[nodiscard]] bool SetBackgroundColor(const SurfaceControl& control,
85 const Color& color);
86
87 using OnCompleteCallback = std::function<void(ASurfaceTransactionStats*)>;
88
89 //----------------------------------------------------------------------------
90 /// @brief Applies the updated encoded in the transaction and invokes the
91 /// callback when the updated are complete.
92 ///
93 /// @warning The callback will be invoked on a system managed thread.
94 ///
95 /// @note It is fine to immediately destroy the transaction after the
96 /// call to apply. It is not necessary to wait for transaction
97 /// completion to collect the transaction handle.
98 ///
99 /// @param[in] callback The callback
100 ///
101 /// @return `true` if the surface transaction was applied. `true` does not
102 /// indicate the application was completed however. Only the
103 /// invocation of the callback denotes transaction completion.
104 ///
105 [[nodiscard]] bool Apply(OnCompleteCallback callback = nullptr);
106
107 //----------------------------------------------------------------------------
108 /// @brief Set the new parent control of the given control. If the new
109 /// parent is null, it is removed from the control hierarchy.
110 ///
111 /// @param[in] control The control
112 /// @param[in] new_parent The new parent
113 ///
114 /// @return `true` if the control will be re-parented when the transaction
115 /// is applied.
116 ///
117 [[nodiscard]] bool SetParent(const SurfaceControl& control,
118 const SurfaceControl* new_parent = nullptr);
119
120 private:
121 struct UniqueASurfaceTransactionTraits {
122 static ASurfaceTransaction* InvalidValue() { return nullptr; }
123
124 static bool IsValid(ASurfaceTransaction* value) {
125 return value != InvalidValue();
126 }
127
128 static void Free(ASurfaceTransaction* value) {
129 GetProcTable().ASurfaceTransaction_delete(value);
130 }
131 };
132
133 fml::UniqueObject<ASurfaceTransaction*, UniqueASurfaceTransactionTraits>
134 transaction_;
135 };
136
137 } // namespace impeller::android
138
139 #endif // FLUTTER_IMPELLER_TOOLKIT_ANDROID_SURFACE_TRANSACTION_H_
impeller::android::SurfaceTransaction::SetParent
bool SetParent(const SurfaceControl &control, const SurfaceControl *new_parent=nullptr)
Set the new parent control of the given control. If the new parent is null, it is removed from the co...
Definition: surface_transaction.cc:86
impeller::android::SurfaceTransaction::~SurfaceTransaction
~SurfaceTransaction()
impeller::android::SurfaceTransaction::OnCompleteCallback
std::function< void(ASurfaceTransactionStats *)> OnCompleteCallback
Definition: surface_transaction.h:87
impeller::android::SurfaceTransaction
A wrapper for ASurfaceTransaction. https://developer.android.com/ndk/reference/group/native-activity#...
Definition: surface_transaction.h:35
proc_table.h
impeller::Color
Definition: color.h:123
value
int32_t value
Definition: dl_golden_unittests.cc:444
impeller::android::SurfaceControl
A wrapper for ASurfaceControl. https://developer.android.com/ndk/reference/group/native-activity#asur...
Definition: surface_control.h:22
impeller::android::SurfaceTransaction::SetBackgroundColor
bool SetBackgroundColor(const SurfaceControl &control, const Color &color)
Encodes the updated background color of the surface control. The update will not be committed till th...
Definition: surface_transaction.cc:70
impeller::android
Definition: choreographer.cc:9
impeller::android::HardwareBuffer
A wrapper for AHardwareBuffer https://developer.android.com/ndk/reference/group/a-hardware-buffer.
Definition: hardware_buffer.h:95
impeller::android::SurfaceTransaction::Apply
bool Apply(OnCompleteCallback callback=nullptr)
Applies the updated encoded in the transaction and invokes the callback when the updated are complete...
Definition: surface_transaction.cc:26
impeller::android::SurfaceTransaction::IsValid
bool IsValid() const
Definition: surface_transaction.cc:18
impeller::android::GetProcTable
const ProcTable & GetProcTable()
Definition: proc_table.cc:12
color.h
impeller::android::SurfaceTransaction::SurfaceTransaction
SurfaceTransaction()
Definition: surface_transaction.cc:13
impeller::android::SurfaceTransaction::operator=
SurfaceTransaction & operator=(const SurfaceTransaction &)=delete
impeller::android::SurfaceTransaction::IsAvailableOnPlatform
static bool IsAvailableOnPlatform()
Definition: surface_transaction.cc:102
impeller::android::SurfaceTransaction::SetContents
bool SetContents(const SurfaceControl *control, const HardwareBuffer *buffer, fml::UniqueFD acquire_fence={})
Encodes that the updated contents of a surface control are specified by the given hardware buffer....
Definition: surface_transaction.cc:54