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