SurfaceControlCompat.Transaction

Transaction

public Transaction()

addTransactionCommittedListener

@RequiresApi(value = 31)
public final @NonNull SurfaceControlCompat.Transaction addTransactionCommittedListener(
    @NonNull Executor executor,
    @NonNull SurfaceControlCompat.TransactionCommittedListener listener
)

Request to add a SurfaceControlCompat.TransactionCommittedListener. The callback is invoked when transaction is applied and the updates are ready to be presented. Once applied, any callbacks added before the commit will be cleared from the Transaction. This callback does not mean buffers have been released! It simply means that any new transactions applied will not overwrite the transaction for which we are receiving a callback and instead will be included in the next frame. If you are trying to avoid dropping frames (overwriting transactions), and unable to use timestamps (Which provide a more efficient solution), then this method provides a method to pace your transaction application.

close

public void close()

Release the native transaction object, without committing it.

commit

public final void commit()

Commit the transaction, clearing it's state, and making it usable as a new transaction. This will not release any resources and SurfaceControlCompat.Transaction.close must be called to release the transaction.

commitTransactionOnDraw

@RequiresApi(value = 33)
public final void commitTransactionOnDraw(
    @NonNull AttachedSurfaceControl attachedSurfaceControl
)

Consume the passed in transaction, and request the View hierarchy to apply it atomically with the next draw. This transaction will be merged with the buffer transaction from the ViewRoot and they will show up on-screen atomically synced. This will not cause a draw to be scheduled, and if there are no other changes to the View hierarchy you may need to call View.invalidate()

reparent

@RequiresApi(value = 33)
public final @NonNull SurfaceControlCompat.Transaction reparent(
    @NonNull SurfaceControlCompat surfaceControl,
    @NonNull AttachedSurfaceControl attachedSurfaceControl
)

Re-parents a given SurfaceControlCompat to be a child of the AttachedSurfaceControl. Children inherit transform (position, scaling) crop, visibility, and Z-ordering from their parents, as if the children were pixels within the parent Surface.

reparent

public final @NonNull SurfaceControlCompat.Transaction reparent(
    @NonNull SurfaceControlCompat surfaceControl,
    SurfaceControlCompat newParent
)

Re-parents a given SurfaceControlCompat to a new parent. Children inherit transform (position, scaling) crop, visibility, and Z-ordering from their parents, as if the children were pixels within the parent Surface.

setAlpha

public final @NonNull SurfaceControlCompat.Transaction setAlpha(@NonNull SurfaceControlCompat surfaceControl, float alpha)

Set the alpha for a given surface. If the alpha is non-zero the SurfaceControl will be blended with the Surfaces under it according to the specified ratio.

setBuffer

public final @NonNull SurfaceControlCompat.Transaction setBuffer(
    @NonNull SurfaceControlCompat surfaceControl,
    @NonNull HardwareBuffer buffer,
    SyncFenceCompat fence,
    Function0<Unit> releaseCallback
)

Updates the HardwareBuffer displayed for the SurfaceControlCompat. Note that the buffer must be allocated with HardwareBuffer.USAGE_COMPOSER_OVERLAY as well as HardwareBuffer.USAGE_GPU_SAMPLED_IMAGE as the surface control might be composited using either an overlay or using the GPU. A presentation fence may be passed to improve performance by allowing the buffer to complete rendering while it is waiting for the transaction to be applied. For example, if the buffer is being produced by rendering with OpenGL ES then a fence created with the eglDupNativeFenceFDANDROID EGL extension API can be used to allow the GPU rendering to be concurrent with the transaction. The compositor will wait for the fence to be signaled before the buffer is displayed. If multiple buffers are set as part of the same transaction, the presentation fences of all of them must signal before any buffer is displayed. That is, the entire transaction is delayed until all presentation fences have signaled, ensuring the transaction remains consistent.

setBufferTransform

public final @NonNull SurfaceControlCompat.Transaction setBufferTransform(
    @NonNull SurfaceControlCompat surfaceControl,
    @SurfaceControlCompat.Companion.BufferTransform int transformation
)

Sets the buffer transform that should be applied to the current buffer

setCrop

public final @NonNull SurfaceControlCompat.Transaction setCrop(@NonNull SurfaceControlCompat surfaceControl, Rect crop)

Bounds the surface and its children to the bounds specified. Size of the surface will be ignored and only the crop and buffer size will be used to determine the bounds of the surface. If no crop is specified and the surface has no buffer, the surface bounds is only constrained by the size of its parent bounds.

setDamageRegion

public final @NonNull SurfaceControlCompat.Transaction setDamageRegion(
    @NonNull SurfaceControlCompat surfaceControl,
    Region region
)

Updates the region for the content on this surface updated in this transaction. The damage region is the area of the buffer that has changed since the previously sent buffer. This can be used to reduce the amount of recomposition that needs to happen when only a small region of the buffer is being updated, such as for a small blinking cursor or a loading indicator.

setLayer

public final @NonNull SurfaceControlCompat.Transaction setLayer(@NonNull SurfaceControlCompat surfaceControl, int z)

Set the Z-order for a given SurfaceControlCompat, relative to it's siblings. If two siblings share the same Z order the ordering is undefined. Surfaces with a negative Z will be placed below the parent Surface.

setOpaque

public final @NonNull SurfaceControlCompat.Transaction setOpaque(@NonNull SurfaceControlCompat surfaceControl, boolean isOpaque)

Indicates whether the surface must be considered opaque, even if its pixel format is set to translucent. This can be useful if an application needs full RGBA 8888 support for instance but will still draw every pixel opaque. This flag only determines whether opacity will be sampled from the alpha channel. Plane-alpha from calls to setAlpha() can still result in blended composition regardless of the opaque setting. Combined effects are (assuming a buffer format with an alpha channel):

OPAQUE + alpha(1.0) == opaque composition OPAQUE + alpha(0.x) == blended composition OPAQUE + alpha(0.0) == no composition !OPAQUE + alpha(1.0) == blended composition !OPAQUE + alpha(0.x) == blended composition !OPAQUE + alpha(0.0) == no composition If the underlying buffer lacks an alpha channel, it is as if setOpaque(true) were set automatically.

setPosition

public final @NonNull SurfaceControlCompat.Transaction setPosition(
    @NonNull SurfaceControlCompat surfaceControl,
    float x,
    float y
)

Sets the SurfaceControl to the specified position relative to the parent SurfaceControl

setScale

public final @NonNull SurfaceControlCompat.Transaction setScale(
    @NonNull SurfaceControlCompat surfaceControl,
    float scaleX,
    float scaleY
)

Sets the SurfaceControl to the specified scale with (0, 0) as the center point of the scale.

setVisibility

public final @NonNull SurfaceControlCompat.Transaction setVisibility(
    @NonNull SurfaceControlCompat surfaceControl,
    boolean visible
)

Sets the visibility of a given Layer and it's sub-tree.