| 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 /// @brief A wrapper class that indicates whether a SurfaceTransaction was
22 /// created by the flutter engine or was borrowed from Java for platform
23 /// interop.
24 struct WrappedSurfaceTransaction {
25 ASurfaceTransaction* tx = nullptr;
26
27 /// Whether this SurfaceTransaction was created by the engine or imported from
28 /// Java.
29 bool owned = true;
30
31 constexpr bool operator==(const WrappedSurfaceTransaction& other) const {
32 return other.tx == tx;
33 }
34
35 constexpr bool operator!=(const WrappedSurfaceTransaction& other) const {
36 return !(*this == other);
37 }
38 };
39
40 //------------------------------------------------------------------------------
41 /// @brief A wrapper for ASurfaceTransaction.
42 /// https://developer.android.com/ndk/reference/group/native-activity#asurfacetransaction
43 ///
44 /// A surface transaction is a collection of updates to the
45 /// hierarchy of surfaces (represented by `ASurfaceControl`
46 /// instances) that are applied atomically in the compositor.
47 ///
48 /// This wrapper is only available on Android API 29 and above.
49 ///
50 /// @note Transactions should be short lived objects (create, apply,
51 /// collect). But, if these are used on multiple threads, they must
52 /// be externally synchronized.
53 ///
54 class SurfaceTransaction {
55 public:
56 //----------------------------------------------------------------------------
57 /// @return `true` if any surface transactions can be created on this
58 /// platform.
59 ///
60 static bool IsAvailableOnPlatform();
61
62 SurfaceTransaction();
63
64 ~SurfaceTransaction();
65
66 SurfaceTransaction(const SurfaceTransaction&) = delete;
67
68 SurfaceTransaction& operator=(const SurfaceTransaction&) = delete;
69
70 explicit SurfaceTransaction(ASurfaceTransaction* transaction);
71
72 bool IsValid() const;
73
74 //----------------------------------------------------------------------------
75 /// @brief Encodes that the updated contents of a surface control are
76 /// specified by the given hardware buffer. The update will not be
77 /// committed till the call to `Apply` however.
78 ///
79 /// @see `SurfaceTransaction::Apply`.
80 ///
81 /// @param[in] control The control.
82 /// @param[in] buffer The hardware buffer.
83 /// @param[in] acquire_fence The fence to wait on before setting the
84 /// contents.
85 ///
86 /// @return If the update was encoded in the transaction.
87 ///
88 [[nodiscard]] bool SetContents(const SurfaceControl* control,
89 const HardwareBuffer* buffer,
90 fml::UniqueFD acquire_fence = {});
91
92 //----------------------------------------------------------------------------
93 /// @brief Encodes the updated background color of the surface control.
94 /// The update will not be committed till the call to `Apply`
95 /// however.
96 ///
97 /// @see `SurfaceTransaction::Apply`.
98 ///
99 /// @param[in] control The control
100 /// @param[in] color The color
101 ///
102 /// @return `true` if the background control will be set when transaction
103 /// is applied.
104 ///
105 [[nodiscard]] bool SetBackgroundColor(const SurfaceControl& control,
106 const Color& color);
107
108 using OnCompleteCallback = std::function<void(ASurfaceTransactionStats*)>;
109
110 //----------------------------------------------------------------------------
111 /// @brief Applies the updated encoded in the transaction and invokes the
112 /// callback when the updated are complete.
113 ///
114 /// @warning The callback will be invoked on a system managed thread.
115 ///
116 /// @note It is fine to immediately destroy the transaction after the
117 /// call to apply. It is not necessary to wait for transaction
118 /// completion to collect the transaction handle.
119 ///
120 /// @param[in] callback The callback
121 ///
122 /// @return `true` if the surface transaction was applied. `true` does not
123 /// indicate the application was completed however. Only the
124 /// invocation of the callback denotes transaction completion.
125 ///
126 [[nodiscard]] bool Apply(OnCompleteCallback callback = nullptr);
127
128 //----------------------------------------------------------------------------
129 /// @brief Set the new parent control of the given control. If the new
130 /// parent is null, it is removed from the control hierarchy.
131 ///
132 /// @param[in] control The control
133 /// @param[in] new_parent The new parent
134 ///
135 /// @return `true` if the control will be re-parented when the transaction
136 /// is applied.
137 ///
138 [[nodiscard]] bool SetParent(const SurfaceControl& control,
139 const SurfaceControl* new_parent = nullptr);
140
141 private:
142 struct UniqueASurfaceTransactionTraits {
143 static WrappedSurfaceTransaction InvalidValue() { return {}; }
144
145 static bool IsValid(const WrappedSurfaceTransaction& value) {
146 return value.tx != nullptr;
147 }
148
149 static void Free(const WrappedSurfaceTransaction& value) {
150 if (value.owned && value.tx) {
151 GetProcTable().ASurfaceTransaction_delete(value.tx);
152 }
153 }
154 };
155
156 fml::UniqueObject<WrappedSurfaceTransaction, UniqueASurfaceTransactionTraits>
157 transaction_;
158 };
159
160 } // namespace impeller::android
161
162 #endif // FLUTTER_IMPELLER_TOOLKIT_ANDROID_SURFACE_TRANSACTION_H_
proc_table.h
impeller::android::HardwareBuffer
A wrapper for AHardwareBuffer https://developer.android.com/ndk/reference/group/a-hardware-buffer.
Definition: hardware_buffer.h:95
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
A wrapper for ASurfaceTransaction. https://developer.android.com/ndk/reference/group/native-activity#...
Definition: surface_transaction.h:54
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:67
impeller::android::SurfaceTransaction::OnCompleteCallback
std::function< void(ASurfaceTransactionStats *)> OnCompleteCallback
Definition: surface_transaction.h:108
impeller::android::SurfaceTransaction::SurfaceTransaction
SurfaceTransaction()
Definition: surface_transaction.cc:13
impeller::android::SurfaceTransaction::operator=
SurfaceTransaction & operator=(const SurfaceTransaction &)=delete
impeller::android::SurfaceTransaction::IsValid
bool IsValid() const
Definition: surface_transaction.cc:23
impeller::android::SurfaceTransaction::SurfaceTransaction
SurfaceTransaction(const SurfaceTransaction &)=delete
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:31
impeller::android::SurfaceTransaction::~SurfaceTransaction
~SurfaceTransaction()
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:83
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:99
impeller::android::SurfaceTransaction::IsAvailableOnPlatform
static bool IsAvailableOnPlatform()
Definition: surface_transaction.cc:115
color.h
value
int32_t value
Definition: dl_golden_unittests.cc:459
impeller::android
Definition: ahb_texture_source_vk_unittests.cc:16
impeller::android::GetProcTable
const ProcTable & GetProcTable()
Definition: proc_table.cc:12
impeller::Color
Definition: color.h:124
impeller::android::WrappedSurfaceTransaction
A wrapper class that indicates whether a SurfaceTransaction was created by the flutter engine or was ...
Definition: surface_transaction.h:24
impeller::android::WrappedSurfaceTransaction::tx
ASurfaceTransaction * tx
Definition: surface_transaction.h:25
impeller::android::WrappedSurfaceTransaction::owned
bool owned
Definition: surface_transaction.h:29
impeller::android::WrappedSurfaceTransaction::operator==
constexpr bool operator==(const WrappedSurfaceTransaction &other) const
Definition: surface_transaction.h:31
impeller::android::WrappedSurfaceTransaction::operator!=
constexpr bool operator!=(const WrappedSurfaceTransaction &other) const
Definition: surface_transaction.h:35