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
SurfaceTransaction &	operator= (const SurfaceTransaction &)=delete
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 35 of file surface_transaction.h.

Member Typedef Documentation

OnCompleteCallback

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

Definition at line 87 of file surface_transaction.h.

Constructor & Destructor Documentation

SurfaceTransaction() [1/2]

impeller::android::SurfaceTransaction::SurfaceTransaction

(

)

Definition at line 13 of file surface_transaction.cc.

    : transaction_(GetProcTable().ASurfaceTransaction_create()) {}

~SurfaceTransaction()

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

default

SurfaceTransaction() [2/2]

impeller::android::SurfaceTransaction::SurfaceTransaction ( const SurfaceTransaction &  )

delete

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]

callback

The 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 26 of file surface_transaction.cc.

                                                          {
  if (!IsValid()) {
    return false;
  }
 
  if (!callback) {
    callback = [](auto) {};
  }
 
  const auto& proc_table = GetProcTable();
 
  auto data = std::make_unique<TransactionInFlightData>();
  data->callback = callback;
  proc_table.ASurfaceTransaction_setOnComplete(
      transaction_.get(),  //
      data.release(),      //
      [](void* context, ASurfaceTransactionStats* stats) -> void {
        auto data = reinterpret_cast<TransactionInFlightData*>(context);
        data->callback(stats);
        delete data;
      });
  proc_table.ASurfaceTransaction_apply(transaction_.get());
 
  // Transactions may not be applied over and over.
  transaction_.reset();
  return true;
}

IsAvailableOnPlatform()

bool impeller::android::SurfaceTransaction::IsAvailableOnPlatform ( )

static

Returns

true if any surface transactions can be created on this platform.

Definition at line 108 of file surface_transaction.cc.

                                               {
  return GetProcTable().IsValid() &&
         GetProcTable().ASurfaceTransaction_create.IsAvailable();
}

IsValid()

bool impeller::android::SurfaceTransaction::IsValid

(

)

const

Definition at line 18 of file surface_transaction.cc.

                                       {
  return transaction_.is_valid();
}

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]	control	The control
[in]	color	The color

Returns

true if the background control will be set when transaction is applied.

Definition at line 76 of file surface_transaction.cc.

                                                                {
  if (!IsValid() || !control.IsValid()) {
    return false;
  }
  GetProcTable().ASurfaceTransaction_setColor(transaction_.get(),     //
                                              control.GetHandle(),    //
                                              color.red,              //
                                              color.green,            //
                                              color.blue,             //
                                              color.alpha,            //
                                              ADATASPACE_SRGB_LINEAR  //
  );
  return true;
}

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]	control	The control.
[in]	buffer	The hardware buffer.
[in]	acquire_fence	The fence to wait on before setting the contents.

Returns

If the update was encoded in the transaction.

Definition at line 54 of file surface_transaction.cc.

                                                                {
  if (control == nullptr || buffer == nullptr) {
    VALIDATION_LOG << "Invalid control or buffer.";
    return false;
  }
 
  const auto& proc_table = GetProcTable();
 
  proc_table.ASurfaceTransaction_setEnableBackPressure(
      transaction_.get(), control->GetHandle(), true);
 
  proc_table.ASurfaceTransaction_setBuffer(
      transaction_.get(),                                      //
      control->GetHandle(),                                    //
      buffer->GetHandle(),                                     //
      acquire_fence.is_valid() ? acquire_fence.release() : -1  //
  );
  return true;
}

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]	control	The control
[in]	new_parent	The new parent

Returns

true if the control will be re-parented when the transaction is applied.

Definition at line 92 of file surface_transaction.cc.

                                                                     {
  if (!IsValid() || !control.IsValid()) {
    return false;
  }
  if (new_parent && !new_parent->IsValid()) {
    return false;
  }
  GetProcTable().ASurfaceTransaction_reparent(
      transaction_.get(),                                        //
      control.GetHandle(),                                       //
      new_parent == nullptr ? nullptr : new_parent->GetHandle()  //
  );
  return true;
}

---

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

• impeller/toolkit/android/surface_transaction.h
• impeller/toolkit/android/surface_transaction.cc