# 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 />

```
public interface SurfaceOutput extends 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/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 public abstract class https://developer.android.com/reference/androidx/camera/core/SurfaceOutput.Event` Events of the `https://developer.android.com/reference/android/view/Surface.html` retrieved from `https://developer.android.com/reference/androidx/camera/core/SurfaceOutput#getSurface(java.util.concurrent.Executor,androidx.core.util.Consumer<androidx.camera.core.SurfaceOutput.Event>)`. |

| ### Public methods |
|---|---|
| `abstract void` | `https://developer.android.com/reference/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. |
| `default @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Matrix.html` | `https://developer.android.com/reference/androidx/camera/core/SurfaceOutput#getSensorToBufferTransform()()` Returns the sensor to image buffer transform matrix. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/util/Size.html` | `https://developer.android.com/reference/androidx/camera/core/SurfaceOutput#getSize()()` Gets the size of the `https://developer.android.com/reference/android/view/Surface.html`. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/view/Surface.html` | `https://developer.android.com/reference/androidx/camera/core/SurfaceOutput#getSurface(java.util.concurrent.Executor,androidx.core.util.Consumer<androidx.camera.core.SurfaceOutput.Event>)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/core/util/Consumer<https://developer.android.com/reference/androidx/camera/core/SurfaceOutput.Event> listener )` Gets the `https://developer.android.com/reference/android/view/Surface.html` for drawing processed frames. |
| `abstract int` | `https://developer.android.com/reference/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. |
| `abstract void` | `https://developer.android.com/reference/androidx/camera/core/SurfaceOutput#updateTransformMatrix(float[],float[])(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html float[] updated, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html float[] original)` Applies an additional 4x4 transformation on the original matrix. |

## Public methods

### close

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

```
abstract void close()
```

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

```
default @NonNull Matrix getSensorToBufferTransform()
```

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/androidx/camera/core/UseCase` to another. For example, detecting face with `https://developer.android.com/reference/androidx/camera/core/ImageAnalysis`, and then highlighting the face in `https://developer.android.com/reference/androidx/camera/core/Preview`.

Code sample

```
 // 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)

```
abstract @NonNull Size getSize()
```

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)

```
abstract @NonNull Surface getSurface(
    @NonNull Executor executor,
    @NonNull Consumer<SurfaceOutput.Event> listener
)
```

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/androidx/core/util/Consumer` from the last call will be triggered.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor` | on which the listener should be invoked. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/core/util/Consumer<https://developer.android.com/reference/androidx/camera/core/SurfaceOutput.Event> listener` | a listener to notify the implementation about the end-of-life of the `https://developer.android.com/reference/androidx/camera/core/SurfaceOutput`. The implementation should then invoke `https://developer.android.com/reference/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)

```
abstract int getTargets()
```

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/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/androidx/camera/core/Preview`.

### updateTransformMatrix

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

```
abstract void updateTransformMatrix(@NonNull float[] updated, @NonNull float[] original)
```

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/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/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/androidx/camera/core/ViewPort` associated with the target `https://developer.android.com/reference/androidx/camera/core/UseCase`. The value could also include workarounds for device specific bugs. For example, correcting a stretched camera output stream.

Code sample:

```
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:

```
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 |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html float[] updated` | the array into which the 4x4 matrix will be stored. The array must have exactly 16 elements. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html float[] original` | the original 4x4 matrix. The array must have exactly 16 elements. |

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