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"
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 ///
35  public:
36  //----------------------------------------------------------------------------
37  /// @return `true` if any surface transactions can be created on this
38  /// platform.
39  ///
40  static bool IsAvailableOnPlatform();
41 
43 
45 
46  SurfaceTransaction(const SurfaceTransaction&) = delete;
47 
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