Flutter Impeller
impeller::android::SurfaceTransaction Class Reference

A wrapper for ASurfaceTransaction. https://developer.android.com/ndk/reference/group/native-activity#asurfacetransaction. More...

#include <surface_transaction.h>

Public Types

using OnCompleteCallback = std::function< void(ASurfaceTransactionStats *)>
 

Public Member Functions

 SurfaceTransaction ()
 
 ~SurfaceTransaction ()
 
 SurfaceTransaction (const SurfaceTransaction &)=delete
 
SurfaceTransactionoperator= (const SurfaceTransaction &)=delete
 
 SurfaceTransaction (ASurfaceTransaction *transaction)
 
bool IsValid () const
 
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. The update will not be committed till the call to Apply however. More...
 
bool SetBackgroundColor (const SurfaceControl &control, const Color &color)
 Encodes the updated background color of the surface control. The update will not be committed till the call to Apply however. More...
 
bool Apply (OnCompleteCallback callback=nullptr)
 Applies the updated encoded in the transaction and invokes the callback when the updated are complete. More...
 
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 control hierarchy. More...
 

Static Public Member Functions

static bool IsAvailableOnPlatform ()
 

Detailed Description

A wrapper for ASurfaceTransaction. https://developer.android.com/ndk/reference/group/native-activity#asurfacetransaction.

A surface transaction is a collection of updates to the hierarchy of surfaces (represented by ASurfaceControl instances) that are applied atomically in the compositor.

This wrapper is only available on Android API 29 and above.

Note
Transactions should be short lived objects (create, apply, collect). But, if these are used on multiple threads, they must be externally synchronized.

Definition at line 54 of file surface_transaction.h.

Member Typedef Documentation

◆ OnCompleteCallback

using impeller::android::SurfaceTransaction::OnCompleteCallback = std::function<void(ASurfaceTransactionStats*)>

Definition at line 108 of file surface_transaction.h.

Constructor & Destructor Documentation

◆ SurfaceTransaction() [1/3]

impeller::android::SurfaceTransaction::SurfaceTransaction ( )

Definition at line 13 of file surface_transaction.cc.

14  : transaction_(
15  WrappedSurfaceTransaction{GetProcTable().ASurfaceTransaction_create(),
16  /*owned=*/true}) {}
const ProcTable & GetProcTable()
Definition: proc_table.cc:12

◆ ~SurfaceTransaction()

impeller::android::SurfaceTransaction::~SurfaceTransaction ( )
default

◆ SurfaceTransaction() [2/3]

impeller::android::SurfaceTransaction::SurfaceTransaction ( const SurfaceTransaction )
delete

◆ SurfaceTransaction() [3/3]

impeller::android::SurfaceTransaction::SurfaceTransaction ( ASurfaceTransaction *  transaction)
explicit

Definition at line 18 of file surface_transaction.cc.

19  : transaction_(WrappedSurfaceTransaction{transaction, /*owned=*/false}) {}

Member Function Documentation

◆ Apply()

bool impeller::android::SurfaceTransaction::Apply ( OnCompleteCallback  callback = nullptr)

Applies the updated encoded in the transaction and invokes the callback when the updated are complete.

Warning
The callback will be invoked on a system managed thread.
Note
It is fine to immediately destroy the transaction after the call to apply. It is not necessary to wait for transaction completion to collect the transaction handle.
Parameters
[in]callbackThe callback
Returns
true if the surface transaction was applied. true does not indicate the application was completed however. Only the invocation of the callback denotes transaction completion.

Definition at line 31 of file surface_transaction.cc.

31  {
32  if (!IsValid()) {
33  return false;
34  }
35 
36  if (!callback) {
37  callback = [](auto) {};
38  }
39 
40  const auto& proc_table = GetProcTable();
41 
42  auto data = std::make_unique<TransactionInFlightData>();
43  data->callback = callback;
44  proc_table.ASurfaceTransaction_setOnComplete(
45  transaction_.get().tx, //
46  data.release(), //
47  [](void* context, ASurfaceTransactionStats* stats) -> void {
48  auto data = reinterpret_cast<TransactionInFlightData*>(context);
49  data->callback(stats);
50  delete data;
51  });
52  // If the transaction was created in Java, then it must be applied in
53  // the Java PlatformViewController and not as a part of the engine render
54  // loop.
55  if (!transaction_.get().owned) {
56  transaction_.reset();
57  return true;
58  }
59 
60  proc_table.ASurfaceTransaction_apply(transaction_.get().tx);
61 
62  // Transactions may not be applied over and over.
63  transaction_.reset();
64  return true;
65 }
std::shared_ptr< const fml::Mapping > data
Definition: texture_gles.cc:68

References data, impeller::android::GetProcTable(), and IsValid().

Referenced by impeller::android::SurfaceControl::RemoveFromParent(), and impeller::android::testing::TEST().

◆ IsAvailableOnPlatform()

bool impeller::android::SurfaceTransaction::IsAvailableOnPlatform ( )
static
Returns
true if any surface transactions can be created on this platform.

Definition at line 115 of file surface_transaction.cc.

115  {
116  return GetProcTable().IsValid() &&
117  GetProcTable().ASurfaceTransaction_create.IsAvailable();
118 }
bool IsValid() const
If a valid proc table could be setup. This may fail in case of setup on non-Android platforms.
Definition: proc_table.cc:65

References impeller::android::GetProcTable(), and impeller::android::ProcTable::IsValid().

Referenced by impeller::android::testing::TEST().

◆ IsValid()

bool impeller::android::SurfaceTransaction::IsValid ( ) const

Definition at line 23 of file surface_transaction.cc.

23  {
24  return transaction_.is_valid();
25 }

Referenced by Apply(), SetBackgroundColor(), SetParent(), and impeller::android::testing::TEST().

◆ operator=()

SurfaceTransaction& impeller::android::SurfaceTransaction::operator= ( const SurfaceTransaction )
delete

◆ SetBackgroundColor()

bool impeller::android::SurfaceTransaction::SetBackgroundColor ( const SurfaceControl control,
const Color color 
)

Encodes the updated background color of the surface control. The update will not be committed till the call to Apply however.

See also
SurfaceTransaction::Apply.
Parameters
[in]controlThe control
[in]colorThe color
Returns
true if the background control will be set when transaction is applied.

Definition at line 83 of file surface_transaction.cc.

84  {
85  if (!IsValid() || !control.IsValid()) {
86  return false;
87  }
88  GetProcTable().ASurfaceTransaction_setColor(transaction_.get().tx, //
89  control.GetHandle(), //
90  color.red, //
91  color.green, //
92  color.blue, //
93  color.alpha, //
94  ADATASPACE_SRGB_LINEAR //
95  );
96  return true;
97 }

References impeller::Color::alpha, impeller::Color::blue, impeller::android::SurfaceControl::GetHandle(), impeller::android::GetProcTable(), impeller::Color::green, impeller::android::SurfaceControl::IsValid(), IsValid(), and impeller::Color::red.

◆ SetContents()

bool impeller::android::SurfaceTransaction::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. The update will not be committed till the call to Apply however.

See also
SurfaceTransaction::Apply.
Parameters
[in]controlThe control.
[in]bufferThe hardware buffer.
[in]acquire_fenceThe fence to wait on before setting the contents.
Returns
If the update was encoded in the transaction.

Definition at line 67 of file surface_transaction.cc.

69  {
70  if (control == nullptr || buffer == nullptr) {
71  VALIDATION_LOG << "Invalid control or buffer.";
72  return false;
73  }
74  GetProcTable().ASurfaceTransaction_setBuffer(
75  transaction_.get().tx, //
76  control->GetHandle(), //
77  buffer->GetHandle(), //
78  acquire_fence.is_valid() ? acquire_fence.release() : -1 //
79  );
80  return true;
81 }
#define VALIDATION_LOG
Definition: validation.h:91

References impeller::android::HardwareBuffer::GetHandle(), impeller::android::SurfaceControl::GetHandle(), impeller::android::GetProcTable(), and VALIDATION_LOG.

◆ SetParent()

bool impeller::android::SurfaceTransaction::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 control hierarchy.

Parameters
[in]controlThe control
[in]new_parentThe new parent
Returns
true if the control will be re-parented when the transaction is applied.

Definition at line 99 of file surface_transaction.cc.

100  {
101  if (!IsValid() || !control.IsValid()) {
102  return false;
103  }
104  if (new_parent && !new_parent->IsValid()) {
105  return false;
106  }
107  GetProcTable().ASurfaceTransaction_reparent(
108  transaction_.get().tx, //
109  control.GetHandle(), //
110  new_parent == nullptr ? nullptr : new_parent->GetHandle() //
111  );
112  return true;
113 }

References impeller::android::SurfaceControl::GetHandle(), impeller::android::GetProcTable(), impeller::android::SurfaceControl::IsValid(), and IsValid().

Referenced by impeller::android::SurfaceControl::RemoveFromParent().


The documentation for this class was generated from the following files: