# Preview.SurfaceProvider

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/Preview.java+class:androidx.camera.core.Preview.SurfaceProvider) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

*** ** * ** ***


```
public interface Preview.SurfaceProvider
```

<br />

*** ** * ** ***

A interface implemented by the application to provide a `https://developer.android.com/reference/android/view/Surface.html` for `https://developer.android.com/reference/androidx/camera/core/Preview`.

This interface is implemented by the application to provide a `https://developer.android.com/reference/android/view/Surface.html`. This will be called by CameraX when it needs a Surface for Preview. It also signals when the Surface is no longer in use by CameraX.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/camera/core/Preview#setSurfaceProvider(java.util.concurrent.Executor,androidx.camera.core.Preview.SurfaceProvider)` |   |

## Summary

| ### Public methods |
|---|---|
| `abstract void` | `https://developer.android.com/reference/androidx/camera/core/Preview.SurfaceProvider#onSurfaceRequested(androidx.camera.core.SurfaceRequest)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/SurfaceRequest request)` Called when a new `https://developer.android.com/reference/android/view/Surface.html` has been requested by the camera. |

## Public methods

### onSurfaceRequested

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

```
abstract void onSurfaceRequested(@NonNull SurfaceRequest request)
```

Called when a new `https://developer.android.com/reference/android/view/Surface.html` has been requested by the camera.

This is called every time a new surface is required to keep the preview running. The camera may repeatedly request surfaces throughout usage of a Preview use case, but only a single request will be active at a time.

A request is considered active until it is `https://developer.android.com/reference/androidx/camera/core/SurfaceRequest#provideSurface(android.view.Surface,java.util.concurrent.Executor,androidx.core.util.Consumer<androidx.camera.core.SurfaceRequest.Result>)`, `https://developer.android.com/reference/androidx/camera/core/SurfaceRequest#willNotProvideSurface()`, or `https://developer.android.com/reference/androidx/camera/core/SurfaceRequest#addRequestCancellationListener(java.util.concurrent.Executor,java.lang.Runnable)`. After one of these conditions occurs, a request is considered completed.

Once a request is successfully completed, it is guaranteed that if a new request is made, the `https://developer.android.com/reference/android/view/Surface.html` used to fulfill the previous request will be detached from the camera and `https://developer.android.com/reference/androidx/camera/core/SurfaceRequest#provideSurface(android.view.Surface,java.util.concurrent.Executor,androidx.core.util.Consumer<androidx.camera.core.SurfaceRequest.Result>)` will be invoked with a `https://developer.android.com/reference/androidx/camera/core/SurfaceRequest.Result` containing `https://developer.android.com/reference/androidx/camera/core/SurfaceRequest.Result#RESULT_SURFACE_USED_SUCCESSFULLY()`. Example:

```
class MyGlSurfaceProvider implements Preview.SurfaceProvider {
    // This executor must have also been used with Preview.setSurfaceProvider() to
    // ensure onSurfaceRequested() is called on our GL thread.
    Executor mGlExecutor;

    @Override
    public void onSurfaceRequested(@NonNull SurfaceRequest request) {
        // If our GL thread/context is shutting down. Signal we will not fulfill
        // the request.
        if (isShuttingDown()) {
            request.willNotProvideSurface();
            return;
        }

        // Create the surface and attempt to provide it to the camera.
        Surface surface = resetGlInputSurface(request.getResolution());

        // Provide the surface and wait for the result to clean up the surface.
        request.provideSurface(surface, mGlExecutor, (result) -> {
            // In all cases (even errors), we can clean up the state. As an
            // optimization, we could also optionally check for REQUEST_CANCELLED
            // since we may be able to reuse the surface on subsequent surface requests.
            closeGlInputSurface(surface);
        });
    }
}
```

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/SurfaceRequest request` | the request for a surface which contains the requirements of the surface and methods for completing the request. |