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