SurfaceControl.Transaction

CREATOR

public static final Creator<SurfaceControl.Transaction> CREATOR

Transaction

public Transaction ()

Open a new transaction object. The transaction may be filed with commands to manipulate SurfaceControl instances, and then applied atomically with apply(). Eventually the user should invoke close(), when the object is no longer required. Note however that re-using a transaction after a call to apply is allowed as a convenience.

addTransactionCommittedListener

public SurfaceControl.Transaction addTransactionCommittedListener (Executor executor, 
                SurfaceControl.TransactionCommittedListener listener)

Request to add a TransactionCommittedListener. The callback is invoked when transaction is applied and the updates are ready to be presented. 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.

apply

public void apply ()

Apply the transaction, clearing it's state, and making it usable as a new transaction.

close

public void close ()

Release the native transaction object, without applying it.

describeContents

public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

merge

public SurfaceControl.Transaction merge (SurfaceControl.Transaction other)

Merge the other transaction into this transaction, clearing the other transaction as if it had been applied.

reparent

public SurfaceControl.Transaction reparent (SurfaceControl sc, 
                SurfaceControl newParent)

Re-parents a given layer 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 SurfaceControl.Transaction setAlpha (SurfaceControl sc, 
                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 SurfaceControl.Transaction setBuffer (SurfaceControl sc, 
                HardwareBuffer buffer, 
                SyncFence fence)

Updates the HardwareBuffer displayed for the SurfaceControl. 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 EGLExt.eglDupNativeFenceFDANDROID(EGLDisplay, EGLSync) 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.

setBuffer

public SurfaceControl.Transaction setBuffer (SurfaceControl sc, 
                HardwareBuffer buffer)

Updates the HardwareBuffer displayed for the SurfaceControl. 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.

setBuffer

public SurfaceControl.Transaction setBuffer (SurfaceControl sc, 
                HardwareBuffer buffer, 
                SyncFence fence, 
                Consumer<SyncFence> releaseCallback)

Updates the HardwareBuffer displayed for the SurfaceControl. 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 EGLExt.eglDupNativeFenceFDANDROID(EGLDisplay, EGLSync) 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. A releaseCallback may be passed to know when the buffer is safe to be reused. This is recommended when attempting to render continuously using SurfaceControl transactions instead of through Surface, as it provides a safe & reliable way to know when a buffer can be re-used. The callback will be invoked with a SyncFence which, if valid, must be waited on prior to using the buffer. This can either be done directly with SyncFence#awaitForever() or it may be done indirectly such as passing it as a release fence to Image.setFence(SyncFence) when using ImageReader.

setBufferSize

public SurfaceControl.Transaction setBufferSize (SurfaceControl sc, 
                int w, 
                int h)

Set the default buffer size for the SurfaceControl, if there is a Surface associated with the control, then this will be the default size for buffers dequeued from it.

setBufferTransform

public SurfaceControl.Transaction setBufferTransform (SurfaceControl sc, 
                int transform)

Sets the buffer transform that should be applied to the current buffer. This can be used in combination with AttachedSurfaceControl#addOnBufferTransformHintChangedListener(AttachedSurfaceControl.OnBufferTransformHintChangedListener) to pre-rotate the buffer for the current display orientation. This can improve the performance of displaying the associated buffer.

setCrop

public SurfaceControl.Transaction setCrop (SurfaceControl sc, 
                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 SurfaceControl.Transaction setDamageRegion (SurfaceControl sc, 
                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.

setDataSpace

public SurfaceControl.Transaction setDataSpace (SurfaceControl sc, 
                int dataspace)

Set the dataspace for the SurfaceControl. This will control how the buffer set with setBuffer(android.view.SurfaceControl, android.hardware.HardwareBuffer) is displayed.

setFrameRate

public SurfaceControl.Transaction setFrameRate (SurfaceControl sc, 
                float frameRate, 
                int compatibility, 
                int changeFrameRateStrategy)

Sets the intended frame rate for the surface SurfaceControl.

On devices that are capable of running the display at different refresh rates, the system may choose a display refresh rate to better match this surface's frame rate. Usage of this API won't directly affect the application's frame production pipeline. However, because the system may change the display refresh rate, calls to this function may result in changes to Choreographer callback timings, and changes to the time interval at which the system releases buffers back to the application.

Note that this only has an effect for surfaces presented on the display. If this surface is consumed by something other than the system compositor, e.g. a media codec, this call has no effect.

setFrameRate

public SurfaceControl.Transaction setFrameRate (SurfaceControl sc, 
                float frameRate, 
                int compatibility)

Sets the intended frame rate for this surface. Any switching of refresh rates is most probably going to be seamless.

setGeometry

public SurfaceControl.Transaction setGeometry (SurfaceControl sc, 
                Rect sourceCrop, 
                Rect destFrame, 
                int orientation)

This method was deprecated in API level 33.
Use setCrop(android.view.SurfaceControl, android.graphics.Rect), setBufferTransform(android.view.SurfaceControl, int), setPosition(android.view.SurfaceControl, float, float) and setScale(android.view.SurfaceControl, float, float) instead.

Specify how the buffer associated with this Surface is mapped in to the parent coordinate space. The source frame will be scaled to fit the destination frame, after being rotated according to the orientation parameter.

setLayer

public SurfaceControl.Transaction setLayer (SurfaceControl sc, 
                int z)

Set the Z-order for a given SurfaceControl, 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 SurfaceControl.Transaction setOpaque (SurfaceControl sc, 
                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

setPosition

public SurfaceControl.Transaction setPosition (SurfaceControl sc, 
                float x, 
                float y)

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

setScale

public SurfaceControl.Transaction setScale (SurfaceControl sc, 
                float scaleX, 
                float scaleY)

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

setVisibility

public SurfaceControl.Transaction setVisibility (SurfaceControl sc, 
                boolean visible)

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

writeToParcel

public void writeToParcel (Parcel dest, 
                int flags)

Writes the transaction to parcel, clearing the transaction as if it had been applied so it can be used to store future transactions. It's the responsibility of the parcel reader to apply the original transaction.