# SurfaceOutput

Artifact: [androidx.camera:camera-core](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/core/SurfaceOutput.java+class:androidx.camera.core.SurfaceOutput) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/camera#1.3.0)

*** ** * ** ***

<br />

```
interface SurfaceOutput : Closeable
```

<br />

*** ** * ** ***

A `https://developer.android.com/reference/android/view/Surface.html` for drawing processed camera frames.

Contains a `https://developer.android.com/reference/android/view/Surface.html` and its characteristics along with methods to manage the lifecycle of the `https://developer.android.com/reference/android/view/Surface.html`.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceProcessor#onOutputSurface(androidx.camera.core.SurfaceOutput)` |   |

## Summary

| ### Nested types |
|---|
| `@https://www.javadoc.io/doc/com.google.auto.value/auto-value/latest/com/google/auto/value/AutoValue.html abstract class https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput.Event` Events of the `https://developer.android.com/reference/android/view/Surface.html` retrieved from `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput#getSurface(java.util.concurrent.Executor,androidx.core.util.Consumer<androidx.camera.core.SurfaceOutput.Event>)`. |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput#close()()` Call this method to mark the `https://developer.android.com/reference/android/view/Surface.html` as no longer in use. |
| `https://developer.android.com/reference/android/graphics/Matrix.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput#getSensorToBufferTransform()()` Returns the sensor to image buffer transform matrix. |
| `https://developer.android.com/reference/android/util/Size.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput#getSize()()` Gets the size of the `https://developer.android.com/reference/android/view/Surface.html`. |
| `https://developer.android.com/reference/android/view/Surface.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput#getSurface(java.util.concurrent.Executor,androidx.core.util.Consumer<androidx.camera.core.SurfaceOutput.Event>)(executor: https://developer.android.com/reference/java/util/concurrent/Executor.html, listener: https://developer.android.com/reference/kotlin/androidx/core/util/Consumer<https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput.Event!>)` Gets the `https://developer.android.com/reference/android/view/Surface.html` for drawing processed frames. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput#getTargets()()` This field indicates that what purpose the `https://developer.android.com/reference/android/view/Surface.html` will be used for. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput#updateTransformMatrix(float[],float[])( updated: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>, original: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html> )` Applies an additional 4x4 transformation on the original matrix. |

## Public functions

### close

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

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

Call this method to mark the `https://developer.android.com/reference/android/view/Surface.html` as no longer in use.

Once the `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceProcessor` implementation receives a request to close the `https://developer.android.com/reference/android/view/Surface.html`, it should call this method to acknowledge after stop writing to the `https://developer.android.com/reference/android/view/Surface.html`. Writing to the `https://developer.android.com/reference/android/view/Surface.html` after calling this method might cause errors.

### getSensorToBufferTransform

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

```
fun getSensorToBufferTransform(): Matrix
```

Returns the sensor to image buffer transform matrix.

The value is a mapping from sensor coordinates to buffer coordinates, which is, from the rect of `https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics.html#SENSOR_INFO_ACTIVE_ARRAY_SIZE` to the rect defined by `(0, 0, #getSize()#getWidth(), #getSize()#getHeight())`. The matrix can be used to map the coordinates from one `https://developer.android.com/reference/kotlin/androidx/camera/core/UseCase` to another. For example, detecting face with `https://developer.android.com/reference/kotlin/androidx/camera/core/ImageAnalysis`, and then highlighting the face in `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview`.

Code sample

```kotlin
 // Get the transformation from sensor to effect output.
 Matrix sensorToEffect = surfaceOutput.getSensorToBufferTransform();
 // Get the transformation from sensor to ImageAnalysis.
 Matrix sensorToAnalysis = imageProxy.getSensorToBufferTransform();
 // Concatenate the two matrices to get the transformation from ImageAnalysis to effect.
 Matrix analysisToEffect = Matrix()
 sensorToAnalysis.invert(analysisToEffect);
 analysisToEffect.postConcat(sensorToEffect);
```

### getSize

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

```
fun getSize(): Size
```

Gets the size of the `https://developer.android.com/reference/android/view/Surface.html`.

### getSurface

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

```
fun getSurface(executor: Executor, listener: Consumer<SurfaceOutput.Event!>): Surface
```

Gets the `https://developer.android.com/reference/android/view/Surface.html` for drawing processed frames.

If there are multiple calls to the method, only the `https://developer.android.com/reference/kotlin/androidx/core/util/Consumer` from the last call will be triggered.

| Parameters |
|---|---|
| `executor: https://developer.android.com/reference/java/util/concurrent/Executor.html` | on which the listener should be invoked. |
| `listener: https://developer.android.com/reference/kotlin/androidx/core/util/Consumer<https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput.Event!>` | a listener to notify the implementation about the end-of-life of the `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput`. The implementation should then invoke `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceOutput#close()` to mark the `https://developer.android.com/reference/android/view/Surface.html` as no longer in use. |

### getTargets

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

```
fun getTargets(): Int
```

This field indicates that what purpose the `https://developer.android.com/reference/android/view/Surface.html` will be used for.

`https://developer.android.com/reference/kotlin/androidx/camera/core/CameraEffect#PREVIEW()` if the `https://developer.android.com/reference/android/view/Surface.html` will be used for `https://developer.android.com/reference/kotlin/androidx/camera/core/Preview`.

### updateTransformMatrix

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

```
fun updateTransformMatrix(
    updated: FloatArray<Float>,
    original: FloatArray<Float>
): Unit
```

Applies an additional 4x4 transformation on the original matrix.

When the input `https://developer.android.com/reference/android/view/Surface.html` of `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceProcessor` is backed by a `https://developer.android.com/reference/android/graphics/SurfaceTexture.html`, use this method to update the texture transform matrix.

Typically, after retrieving the transform matrix from `https://developer.android.com/reference/android/graphics/SurfaceTexture.html#getTransformMatrix(float[])`, the `https://developer.android.com/reference/kotlin/androidx/camera/core/SurfaceProcessor` implementation should always call this method to update the value. The result is a matrix of the same format, which is a transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s and t in the inclusive range \[0, 1\] to the texture coordinate that should be used to sample that location from the texture. The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via the ` glLoadMatrixf` or `glUniformMatrix4fv` functions.

The additional transformation is calculated based on the target rotation, target resolution and the `https://developer.android.com/reference/kotlin/androidx/camera/core/ViewPort` associated with the target `https://developer.android.com/reference/kotlin/androidx/camera/core/UseCase`. The value could also include workarounds for device specific bugs. For example, correcting a stretched camera output stream.

Code sample:

```kotlin
float[] transform = new float[16];
float[] updatedTransform = new float[16];

surfaceTexture.setOnFrameAvailableListener(surfaceTexture -> {
    surfaceTexture.getTransformMatrix(transform);
    outputSurface.updateTransformMatrix(updatedTransform, transform);
    // Use the value of updatedTransform for OpenGL rendering.
});
```

To get the value of the additional transformation, pass in an identity matrix as the original value. This is useful when `https://developer.android.com/reference/android/graphics/SurfaceTexture.html#getTransformMatrix(float[])` is not applied by the implementation.

Code sample:

```kotlin
float[] identity = new float[16];
Matrix.setIdentityM(identity, 0);
float[] updatedTransform = new float[16];

surfaceTexture.setOnFrameAvailableListener(surfaceTexture -> {
    outputSurface.updateTransformMatrix(updatedTransform, identity);
    // Use the value of updatedTransform for OpenGL rendering.
});
```

| Parameters |
|---|---|
| `updated: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>` | the array into which the 4x4 matrix will be stored. The array must have exactly 16 elements. |
| `original: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html>` | the original 4x4 matrix. The array must have exactly 16 elements. |

| See also |
|---|---|
| `https://developer.android.com/reference/android/graphics/SurfaceTexture.html#getTransformMatrix(float[])` |   |