# SurfaceControlCompat.Transaction

Artifact: [androidx.graphics:graphics-core](https://developer.android.com/jetpack/androidx/releases/graphics) [View Source](https://cs.android.com/search?q=file:androidx/graphics/surface/SurfaceControlCompat.kt+class:androidx.graphics.surface.SurfaceControlCompat.Transaction) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

*** ** * ** ***


```
@RequiresApi(value = 29)
class SurfaceControlCompat.Transaction : AutoCloseable
```

<br />

*** ** * ** ***

An atomic set of changes to a set of `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#Transaction()()` |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 31) https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#addTransactionCommittedListener(java.util.concurrent.Executor,androidx.graphics.surface.SurfaceControlCompat.TransactionCommittedListener)( executor: https://developer.android.com/reference/java/util/concurrent/Executor.html, listener: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.TransactionCommittedListener )` Request to add a `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.TransactionCommittedListener`. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#clearFrameRate(androidx.graphics.surface.SurfaceControlCompat)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat)` Clears the frame rate which was set for the surface SurfaceControl. |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#close()()` Release the native transaction object, without committing it. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#commit()()` Commit the transaction, clearing it's state, and making it usable as a new transaction. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 33) https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#commitTransactionOnDraw(android.view.AttachedSurfaceControl)(attachedSurfaceControl: https://developer.android.com/reference/android/view/AttachedSurfaceControl.html)` Consume the passed in transaction, and request the View hierarchy to apply it atomically with the next draw. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 33) https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#reparent(androidx.graphics.surface.SurfaceControlCompat,android.view.AttachedSurfaceControl)( surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, attachedSurfaceControl: https://developer.android.com/reference/android/view/AttachedSurfaceControl.html )` Re-parents a given `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to be a child of the `https://developer.android.com/reference/android/view/AttachedSurfaceControl.html`. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#reparent(androidx.graphics.surface.SurfaceControlCompat,androidx.graphics.surface.SurfaceControlCompat)( surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, newParent: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat? )` Re-parents a given `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to a new parent. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setAlpha(androidx.graphics.surface.SurfaceControlCompat,kotlin.Float)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, alpha: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)` Set the alpha for a given surface. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setBuffer(androidx.graphics.surface.SurfaceControlCompat,android.hardware.HardwareBuffer,androidx.hardware.SyncFenceCompat,kotlin.Function1)( surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, buffer: https://developer.android.com/reference/android/hardware/HardwareBuffer.html?, fence: https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat?, releaseCallback: ((https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? )` Updates the `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` displayed for the `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat`. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setBufferTransform(androidx.graphics.surface.SurfaceControlCompat,kotlin.Int)( surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, transformation: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` Sets the buffer transform that should be applied to the current buffer |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setCrop(androidx.graphics.surface.SurfaceControlCompat,android.graphics.Rect)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, crop: https://developer.android.com/reference/android/graphics/Rect.html?)` Bounds the surface and its children to the bounds specified. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setDamageRegion(androidx.graphics.surface.SurfaceControlCompat,android.graphics.Region)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, region: https://developer.android.com/reference/android/graphics/Region.html?)` Updates the region for the content on this surface updated in this transaction. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setDataSpace(androidx.graphics.surface.SurfaceControlCompat,kotlin.Int)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, dataSpace: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Set the `https://developer.android.com/reference/kotlin/androidx/hardware/DataSpace` for the SurfaceControl. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `@https://developer.android.com/reference/kotlin/androidx/annotation/RequiresApi(value = 34) https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setExtendedRangeBrightness(androidx.graphics.surface.SurfaceControlCompat,kotlin.Float,kotlin.Float)( surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, currentBufferRatio: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 1.0, fromInclusive = true) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, desiredRatio: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 1.0, fromInclusive = true) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html )` Sets the desired extended range brightness for the layer. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setFrameRate(androidx.graphics.surface.SurfaceControlCompat,kotlin.Float,kotlin.Int,kotlin.Int)( surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, frameRate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, compatibility: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, changeFrameRateStrategy: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` Sets the intended frame rate for `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat`. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setLayer(androidx.graphics.surface.SurfaceControlCompat,kotlin.Int)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, z: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Set the Z-order for a given `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat`, relative to its siblings. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setOpaque(androidx.graphics.surface.SurfaceControlCompat,kotlin.Boolean)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, isOpaque: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Indicates whether the surface must be considered opaque, even if its pixel format is set to translucent. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setPosition(androidx.graphics.surface.SurfaceControlCompat,kotlin.Float,kotlin.Float)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, x: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, y: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)` Sets the SurfaceControl to the specified position relative to the parent SurfaceControl |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setScale(androidx.graphics.surface.SurfaceControlCompat,kotlin.Float,kotlin.Float)( surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, scaleX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, scaleY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html )` Sets the SurfaceControl to the specified scale with (0, 0) as the center point of the scale. |
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setVisibility(androidx.graphics.surface.SurfaceControlCompat,kotlin.Boolean)(surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat, visible: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Sets the visibility of a given Layer and it's sub-tree. |

## Public constructors

### Transaction

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
Transaction()
```

## Public functions

### addTransactionCommittedListener

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
@RequiresApi(value = 31)
fun addTransactionCommittedListener(
    executor: Executor,
    listener: SurfaceControlCompat.TransactionCommittedListener
): SurfaceControlCompat.Transaction
```

Request to add a `https://developer.android.com/reference/kotlin/androidx/graphics/surface/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.

| Parameters |
|---|---|
| `executor: https://developer.android.com/reference/java/util/concurrent/Executor.html` | `https://developer.android.com/reference/java/util/concurrent/Executor.html` to provide the thread the callback is invoked on. |
| `listener: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.TransactionCommittedListener` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.TransactionCommittedListener` instance that is invoked when the transaction has been committed. |

### clearFrameRate

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun clearFrameRate(surfaceControl: SurfaceControlCompat): SurfaceControlCompat.Transaction
```

Clears the frame rate which was set for the surface SurfaceControl.

This is equivalent to calling `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setFrameRate(androidx.graphics.surface.SurfaceControlCompat,kotlin.Float,kotlin.Int,kotlin.Int)` with 0 for the framerate and `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#FRAME_RATE_COMPATIBILITY_DEFAULT()`

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.

This is only supported on Android R and above. This is ignored on older Android versions.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to clear the frame rate |

### close

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
open fun close(): Unit
```

Release the native transaction object, without committing it.

### commit

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun commit(): Unit
```

Commit the transaction, clearing it's state, and making it usable as a new transaction. This will not release any resources and `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#close()` must be called to release the transaction.

### commitTransactionOnDraw

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
@RequiresApi(value = 33)
fun commitTransactionOnDraw(attachedSurfaceControl: AttachedSurfaceControl): Unit
```

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()

| Parameters |
|---|---|
| `attachedSurfaceControl: https://developer.android.com/reference/android/view/AttachedSurfaceControl.html` | `https://developer.android.com/reference/android/view/AttachedSurfaceControl.html` associated with the ViewRoot that will apply the provided transaction on the next draw pass |

### reparent

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
@RequiresApi(value = 33)
fun reparent(
    surfaceControl: SurfaceControlCompat,
    attachedSurfaceControl: AttachedSurfaceControl
): SurfaceControlCompat.Transaction
```

Re-parents a given `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to be a child of the `https://developer.android.com/reference/android/view/AttachedSurfaceControl.html`. Children inherit transform (position, scaling) crop, visibility, and Z-ordering from their parents, as if the children were pixels within the parent `https://developer.android.com/reference/android/view/Surface.html`.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | Target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` instance to reparent |
| `attachedSurfaceControl: https://developer.android.com/reference/android/view/AttachedSurfaceControl.html` | `https://developer.android.com/reference/android/view/AttachedSurfaceControl.html` instance that acts as the new parent of the provided `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` instance. |

### reparent

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun reparent(
    surfaceControl: SurfaceControlCompat,
    newParent: SurfaceControlCompat?
): SurfaceControlCompat.Transaction
```

Re-parents a given `https://developer.android.com/reference/kotlin/androidx/graphics/surface/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 `https://developer.android.com/reference/android/view/Surface.html`.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | Target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` instance to reparent |
| `newParent: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat?` | Parent `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` that the target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` instance is added to. This can be null indicating that the target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` should be removed from the scene. |

### setAlpha

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setAlpha(surfaceControl: SurfaceControlCompat, alpha: Float): SurfaceControlCompat.Transaction
```

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.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | Target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to set the alpha of. |
| `alpha: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | The alpha to set. Value is between 0.0 and 1.0 inclusive. |

### setBuffer

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setBuffer(
    surfaceControl: SurfaceControlCompat,
    buffer: HardwareBuffer?,
    fence: SyncFenceCompat? = null,
    releaseCallback: ((SyncFenceCompat) -> Unit)? = null
): SurfaceControlCompat.Transaction
```

Updates the `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` displayed for the `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat`. Note that the buffer must be allocated with `https://developer.android.com/reference/android/hardware/HardwareBuffer.html#USAGE_COMPOSER_OVERLAY` as well as `https://developer.android.com/reference/android/hardware/HardwareBuffer.html#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.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | Target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to configure the provided buffer. |
| `buffer: https://developer.android.com/reference/android/hardware/HardwareBuffer.html?` | `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` instance to be rendered by the `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` instance. Use null to remove the current buffer that was previously configured on this `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` instance. |
| `fence: https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat? = null` | Optional `https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat` that serves as the presentation fence. If set, the `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` will not apply until the fence signals. |
| `releaseCallback: ((https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | Optional callback invoked when the buffer is ready for re-use after being presented to the display. This also includes a `https://developer.android.com/reference/kotlin/androidx/hardware/SyncFenceCompat` instance that consumers must wait on before consuming the buffer |

### setBufferTransform

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setBufferTransform(
    surfaceControl: SurfaceControlCompat,
    transformation: Int
): SurfaceControlCompat.Transaction
```

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

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | the `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to update. This value cannot be null. |
| `transformation: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The transform to apply to the buffer. Value is `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_IDENTITY()`, `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_MIRROR_HORIZONTAL()`, `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_MIRROR_VERTICAL()`, `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_ROTATE_90()`, `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_ROTATE_180()`, `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_ROTATE_270()`, `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_MIRROR_HORIZONTAL()` \| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_ROTATE_90()`, or `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_MIRROR_VERTICAL()` \| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_ROTATE_90()` Value is one of the following: - `0` - `1` - `2` - `3` - `4` - `7` <br /> |

### setCrop

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setCrop(surfaceControl: SurfaceControlCompat, crop: Rect?): SurfaceControlCompat.Transaction
```

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.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | The `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to apply the crop to. This value cannot be null. |
| `crop: https://developer.android.com/reference/android/graphics/Rect.html?` | Bounds of the crop to apply. This value can be null. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html` | if crop is not a valid rectangle. |

### setDamageRegion

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setDamageRegion(surfaceControl: SurfaceControlCompat, region: Region?): SurfaceControlCompat.Transaction
```

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.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | Target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to set damage region of. |
| `region: https://developer.android.com/reference/android/graphics/Region.html?` | The region to be set. If null, the entire buffer is assumed dirty. This is equivalent to not setting a damage region at all. |

### setDataSpace

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setDataSpace(surfaceControl: SurfaceControlCompat, dataSpace: Int): SurfaceControlCompat.Transaction
```

Set the `https://developer.android.com/reference/kotlin/androidx/hardware/DataSpace` for the SurfaceControl. This will control how the buffer set with `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setBuffer(androidx.graphics.surface.SurfaceControlCompat,android.hardware.HardwareBuffer,androidx.hardware.SyncFenceCompat,kotlin.Function1)` is displayed.

**NOTE** it is strongly recommended to verify that the display supports the corresponding `https://developer.android.com/reference/kotlin/androidx/hardware/DataSpace` in advance before configuring the data space. For example, if `https://developer.android.com/reference/kotlin/androidx/hardware/DataSpace#DATASPACE_DISPLAY_P3()` is desired, consumers should verify that `https://developer.android.com/reference/android/view/Window.html#isWideColorGamut()` returns true before proceeding.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | The SurfaceControl to update |
| `dataSpace: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The `https://developer.android.com/reference/kotlin/androidx/hardware/DataSpace` to set it to. Must be one of named `https://developer.android.com/reference/android/hardware/DataSpace.html` types. Value is either `0` or a combination of the following: - `4096` - `4098` - `4100` - `4101` - `0` - `406913024` - `142671872` - `411107328` - `143261696` - `168165376` - `163971072` - `151715840` - `146931712` - `281149440` - `281280512` - `147193856` - `281083904` - `155844608` - `138477568` <br /> |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | this |

| See also |
|---|---|
| `https://developer.android.com/reference/android/view/SurfaceControl.Transaction.html#setDataSpace(android.view.SurfaceControl, int)` |   |

### setExtendedRangeBrightness

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
@RequiresApi(value = 34)
fun setExtendedRangeBrightness(
    surfaceControl: SurfaceControlCompat,
    currentBufferRatio: @FloatRange(from = 1.0, fromInclusive = true) Float,
    desiredRatio: @FloatRange(from = 1.0, fromInclusive = true) Float
): SurfaceControlCompat.Transaction
```

Sets the desired extended range brightness for the layer. This only applies for layers that are displaying `https://developer.android.com/reference/android/hardware/HardwareBuffer.html` instances with a DataSpace of `https://developer.android.com/reference/kotlin/androidx/hardware/DataSpace#RANGE_EXTENDED()`.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | The layer whose extended range brightness is being specified |
| `currentBufferRatio: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 1.0, fromInclusive = true) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | The current hdr/sdr ratio of the current buffer. For example if the buffer was rendered with a target SDR whitepoint of 100 nits and a max display brightness of 200 nits, this should be set to 2.0f. Default value is 1.0f. Transfer functions that encode their own brightness ranges, such as HLG or PQ, should also set this to 1.0f and instead communicate extended content brightness information via metadata such as CTA861_3 or SMPTE2086. Must be finite \&\&\>= 1.0f |
| `desiredRatio: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 1.0, fromInclusive = true) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | The desired hdr/sdr ratio. This can be used to communicate the max desired brightness range. This is similar to the "max luminance" value in other HDR metadata formats, but represented as a ratio of the target SDR whitepoint to the max display brightness. The system may not be able to, or may choose not to, deliver the requested range. While requesting a large desired ratio will result in the most dynamic range, voluntarily reducing the requested range can help improve battery life as well as can improve quality by ensuring greater bit depth is allocated to the luminance range in use. Default value is 1.0f and indicates that extended range brightness is not being used, so the resulting SDR or HDR behavior will be determined entirely by the dataspace being used (ie, typically SDR however PQ or HLG transfer functions will still result in HDR) Must be finite \&\&\>= 1.0f |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction` | this |

### setFrameRate

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setFrameRate(
    surfaceControl: SurfaceControlCompat,
    frameRate: Float,
    compatibility: Int,
    changeFrameRateStrategy: Int
): SurfaceControlCompat.Transaction
```

Sets the intended frame rate for `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat`.

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.

This method is only supported on Android R+ and is ignored on older platform versions.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | The target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` that will have it's frame rate changed |
| `frameRate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | The intended frame rate of this surface, in frames per second. 0 is a special value that indicates the app will accept the system's choice for the display frame rate, which is the default behavior if this function isn't called. Must be greater than or equal to 0. The frameRate param does not need to be a valid refresh rate for this device's display - e.g., it's fine to pass 30fps to a device that can only run the display at 60fps. |
| `compatibility: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The frame rate compatibility of this surface. The compatibility value may influence the system's choice of display frame rate. This must be either `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#FRAME_RATE_COMPATIBILITY_DEFAULT()` or `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#FRAME_RATE_COMPATIBILITY_FIXED_SOURCE()` This parameter is ignored when frameRate is 0. Value is one of the following: - `0` - `1` <br /> |
| `changeFrameRateStrategy: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | Whether display refresh rate transitions should be seamless. A seamless transition does not have any visual interruptions, such as a black screen for a second or two. Must be either `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#CHANGE_FRAME_RATE_ALWAYS()` or `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat#CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS()`. This parameter is only supported on Android S and when `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setFrameRate(androidx.graphics.surface.SurfaceControlCompat,kotlin.Float,kotlin.Int,kotlin.Int)` is not 0. This is ignored on older Android versions and when `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat.Transaction#setFrameRate(androidx.graphics.surface.SurfaceControlCompat,kotlin.Float,kotlin.Int,kotlin.Int)` is 0. Value is one of the following: - `0` - `1` <br /> |

### setLayer

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setLayer(surfaceControl: SurfaceControlCompat, z: Int): SurfaceControlCompat.Transaction
```

Set the Z-order for a given `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat`, relative to its siblings. If two siblings share the same Z order the ordering is undefined. `https://developer.android.com/reference/android/view/Surface.html`s with a negative Z will be placed below the parent `https://developer.android.com/reference/android/view/Surface.html`.

### setOpaque

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setOpaque(surfaceControl: SurfaceControlCompat, isOpaque: Boolean): SurfaceControlCompat.Transaction
```

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.

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | Target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to change the opaque flag for |
| `isOpaque: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | Flag indicating if the `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` should be fully opaque or transparent |

### setPosition

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setPosition(surfaceControl: SurfaceControlCompat, x: Float, y: Float): SurfaceControlCompat.Transaction
```

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

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | The `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to change position. This value cannot be null |
| `x: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | the X position |
| `y: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | the Y position |

### setScale

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setScale(
    surfaceControl: SurfaceControlCompat,
    scaleX: Float,
    scaleY: Float
): SurfaceControlCompat.Transaction
```

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

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | The `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to change scale. This value cannot be null. |
| `scaleX: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | the X scale |
| `scaleY: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | the Y scale |

### setVisibility

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

```
fun setVisibility(surfaceControl: SurfaceControlCompat, visible: Boolean): SurfaceControlCompat.Transaction
```

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

| Parameters |
|---|---|
| `surfaceControl: https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` | Target `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` to change the visibility |
| `visible: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `true` to indicate the `https://developer.android.com/reference/kotlin/androidx/graphics/surface/SurfaceControlCompat` should be visible, `false` otherwise |