# SurfaceControlCompat

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) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/graphics#1.0.0)

*** ** * ** ***


```
@RequiresApi(value = 29)
public final class SurfaceControlCompat
```

<br />

*** ** * ** ***

Handle to an on-screen Surface managed by the system compositor. `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat` is a combination of a buffer source, and metadata about how to display the buffers. By constructing a `https://developer.android.com/reference/android/view/Surface.html` from this `https://developer.android.com/reference/android/view/SurfaceControl.html` you can submit buffers to be composited. Using `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat.Transaction` you can manipulate various properties of how the buffer will be displayed on-screen. `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat`s are arranged into a scene-graph like hierarchy, and as such any `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat` may have a parent. Geometric properties like transform, crop, and Z-ordering will be inherited from the parent, as if the child were content in the parents buffer stream.

This class differs slightly than `https://developer.android.com/reference/android/view/SurfaceControl.html` in that it backports some functionality to Android R and above by delegating to the related APIs available in the NDK. For newer Android versions, this leverages the equivalent `https://developer.android.com/reference/android/view/SurfaceControl.html` API available in the SDK

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat.Builder` Builder class for `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat` objects. |
| `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 29) public final class https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat.Transaction implements https://developer.android.com/reference/java/lang/AutoCloseable.html` An atomic set of changes to a set of `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat`. |
| `public interface https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat.TransactionCommittedListener` Interface to handle request to `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat.Transaction#addTransactionCommittedListener(java.util.concurrent.Executor,androidx.graphics.surface.SurfaceControlCompat.TransactionCommittedListener)` |

| ### Constants |
|---|---|
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_IDENTITY() = 0` The identity transformation. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_MIRROR_HORIZONTAL() = 1` Mirrors the buffer horizontally. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_MIRROR_VERTICAL() = 2` Mirrors the buffer vertically. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_ROTATE_180() = 3` Rotates the buffer 180 degrees clockwise. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_ROTATE_270() = 7` Rotates the buffer 270 degrees clockwise. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#BUFFER_TRANSFORM_ROTATE_90() = 4` Rotates the buffer 90 degrees clockwise. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#CHANGE_FRAME_RATE_ALWAYS() = 1` Change the frame rate even if the transition is going to be non-seamless, i.e. with visual interruptions for the user. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS() = 0` Change the frame rate only if the transition is going to be seamless. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#FRAME_RATE_COMPATIBILITY_DEFAULT() = 0` There are no inherent restrictions on the frame rate. |
| `static final int` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#FRAME_RATE_COMPATIBILITY_FIXED_SOURCE() = 1` This compositing layer is being used to display content with an inherently fixed frame rate, e.g. a video that has a specific frame rate. |

| ### Public methods |
|---|---|
| `final boolean` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#isValid()()` Check whether this instance points to a valid layer with the system-compositor. |
| `final void` | `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#release()()` Release the local reference to the server-side surface. |

## Constants

### BUFFER_TRANSFORM_IDENTITY

```
public static final int BUFFER_TRANSFORM_IDENTITY = 0
```

The identity transformation. Maps a coordinate (x, y) onto itself.

### BUFFER_TRANSFORM_MIRROR_HORIZONTAL

```
public static final int BUFFER_TRANSFORM_MIRROR_HORIZONTAL = 1
```

Mirrors the buffer horizontally. Maps a point (x, y) to (-x, y)

### BUFFER_TRANSFORM_MIRROR_VERTICAL

```
public static final int BUFFER_TRANSFORM_MIRROR_VERTICAL = 2
```

Mirrors the buffer vertically. Maps a point (x, y) to (x, -y)

### BUFFER_TRANSFORM_ROTATE_180

```
public static final int BUFFER_TRANSFORM_ROTATE_180 = 3
```

Rotates the buffer 180 degrees clockwise. Maps a point (x, y) to (-x, -y)

### BUFFER_TRANSFORM_ROTATE_270

```
public static final int BUFFER_TRANSFORM_ROTATE_270 = 7
```

Rotates the buffer 270 degrees clockwise. Maps a point (x, y) to (y, -x)

### BUFFER_TRANSFORM_ROTATE_90

```
public static final int BUFFER_TRANSFORM_ROTATE_90 = 4
```

Rotates the buffer 90 degrees clockwise. Maps a point (x, y) to (-y, x)

### CHANGE_FRAME_RATE_ALWAYS

```
public static final int CHANGE_FRAME_RATE_ALWAYS = 1
```

Change the frame rate even if the transition is going to be non-seamless, i.e. with visual interruptions for the user.

### CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS

```
public static final int CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS = 0
```

Change the frame rate only if the transition is going to be seamless.

### FRAME_RATE_COMPATIBILITY_DEFAULT

```
public static final int FRAME_RATE_COMPATIBILITY_DEFAULT = 0
```

There are no inherent restrictions on the frame rate. When the system selects a frame rate other than what the app requested, the app will be able to run at the system frame rate without requiring pull down (the mechanical process of "pulling", physically moving, frame content downward to advance it from one frame to the next at a repetitive rate). This value should be used when displaying game content, UIs, and anything that isn't video.

### FRAME_RATE_COMPATIBILITY_FIXED_SOURCE

```
public static final int FRAME_RATE_COMPATIBILITY_FIXED_SOURCE = 1
```

This compositing layer is being used to display content with an inherently fixed frame rate, e.g. a video that has a specific frame rate. When the system selects a frame rate other than what the app requested, the app will need to do pull down or use some other technique to adapt to the system's frame rate. Pull down involves the mechanical process of "pulling", physically moving, frame content downward to advance it from one frame to the next at a repetitive rate). The user experience is likely to be worse (e.g. more frame stuttering) than it would be if the system had chosen the app's requested frame rate. This value should be used for video content.

## Public methods

### isValid

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

```
public final boolean isValid()
```

Check whether this instance points to a valid layer with the system-compositor. For example this may be false if the layer was released (`https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#release()`).

### release

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

```
public final void release()
```

Release the local reference to the server-side surface. The `https://developer.android.com/reference/android/view/Surface.html` may continue to exist on-screen as long as its parent continues to exist. To explicitly remove a `https://developer.android.com/reference/android/view/Surface.html` from the screen use `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat.Transaction#reparent(androidx.graphics.surface.SurfaceControlCompat,androidx.graphics.surface.SurfaceControlCompat)` with a null-parent. After release, `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#isValid()` will return false and other methods will throw an exception. Always call `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat#release()` when you are done with a `https://developer.android.com/reference/androidx/graphics/surface/SurfaceControlCompat` instance.