SurfaceRequest | API reference | Android Developers

public final class SurfaceRequest

A completable, single-use request of a Surface.

Contains requirements for surface characteristics along with methods for completing the request and listening for request cancellation.

Acts as a bridge between the surface provider and the surface requester. The diagram below describes how it works:

The surface provider gives a reference to surface requester for providing Surface (e.g. setSurfaceProvider).
The surface requester uses the reference to send a SurfaceRequest to get a Surface (e.g. onSurfaceRequested).
The surface provider can use provideSurface to provide a Surface or inform the surface requester no Surface will be provided with willNotProvideSurface. If a Surface is provided, the connection between surface provider and surface requester is established.
If the connection is established, the surface requester can get the Surface through getDeferrableSurface and start to send frame data.
If for some reason the provided Surface is no longer valid (e.g. when the SurfaceView destroys its surface due to page being slid out in ViewPager2), the surface provider can use invalidate method to inform the surface requester and the established connection will be closed.
The surface requester will re-send a new SurfaceRequest to establish a new connection.

Summary

Public methods

addRequestCancellationListener

public void addRequestCancellationListener(
    @NonNull Executor executor,
    @NonNull Runnable listener
)

Adds a listener to be informed when the camera cancels the surface request.

A surface request may be cancelled by the camera if the surface is no longer required. Examples of why cancellation may occur include (1) a UseCase being unbound from the camera, (2) surface requirements, such as resolution, changing due to newly bound use cases, or (3) the camera requiring a new Surface object on lower API levels to work around compatibility issues.

When a request is cancelled, the Runnables provided here will be invoked on the Executor they are added with, and can be used as a signal to stop any work that may be in progress to fulfill the surface request.

Once a surface request has been cancelled by the camera, willNotProvideSurface will have no effect and will return false. Attempting to complete the request via provideSurface will also have no effect, and any resultListener passed to provideSurface will be invoked with a Result containing RESULT_REQUEST_CANCELLED.

Note that due to the asynchronous nature of this listener, it is not guaranteed that the listener will be called before an attempt to complete the request with provideSurface or willNotProvideSurface, so the return values of these methods can always be checked if your workflow for producing a surface expects them to complete successfully.

Parameters
`@NonNull Executor executor`	The executor used to notify the listener.
`@NonNull Runnable listener`	The listener which will be run upon request cancellation.

getResolution

public @NonNull Size getResolution()

Returns the resolution of the requested Surface.

The surface which fulfills this request must have the resolution specified here in order to fulfill the resource requirements of the camera. Fulfillment of the request with a surface of a different resolution may cause the resultListener passed to provideSurface to be invoked with a Result containing RESULT_INVALID_SURFACE.

Returns
`@NonNull Size`	The guaranteed supported resolution.

invalidate

public boolean invalidate()

Invalidates the previously provided Surface to provide a new Surface.

Call this method to inform the surface requester that the previously provided Surface is no longer valid (e.g. when the SurfaceView destroys its surface due to page being slid out in ViewPager2) and should re-send a SurfaceRequest to obtain a new Surface.

Calling this method will cause the camera to be reconfigured. The app should call this method when the surface provider is ready to provide a new Surface. (e.g. a SurfaceView's surface is created when its window is visible.)

If the provided Surface was already invalidated, invoking this method will return false, and will have no effect. The surface requester will not be notified again, so there will not be another SurfaceRequest.

Calling this method without provideSurface (regardless of whether @link #willNotProvideSurface()} has been called) will still trigger the surface requester to re-send a SurfaceRequest.

Since calling this method also means that the SurfaceRequest will not be fulfilled, if the SurfaceRequest has not responded, it will respond as if calling willNotProvideSurface.

Returns
`boolean`	true if the provided `Surface` is invalidated or false if it was already invalidated.

willNotProvideSurface

public boolean willNotProvideSurface()

Signals that the request will never be fulfilled.

This may be called in the case where the application may be shutting down and a surface will never be produced to fulfill the request.

This should always be called as soon as it is known that the request will not be fulfilled. Failure to complete the SurfaceRequest via willNotProvideSurface() or provideSurface may cause long delays in shutting down the camera.

Upon returning from this method, the request is guaranteed to be complete, regardless of the return value. If the request was previously successfully completed by provideSurface, invoking this method will return false, and will have no effect on how the surface is used by the camera.

Returns
`boolean`	`true` if this call to `willNotProvideSurface()` successfully completes the request, i.e., the request has not already been completed via `provideSurface` or by a previous call to `willNotProvideSurface()` and has not already been cancelled by the camera.

Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.