SurfaceRequest

class SurfaceRequest
kotlin.Any
   ↳ androidx.camera.core.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.

Summary

Nested classes

An exception used to signal that the camera has cancelled a request for a Surface.

Public methods

Unit
addRequestCancellationListener(@NonNull executor: Executor, @NonNull listener: Runnable)

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

Size

Returns the resolution of the requested Surface.

ListenableFuture<Void!>
setSurface(@NonNull surface: Surface)

Completes the request for a Surface if it has not already been completed or cancelled.

Boolean

Signals that the request will never be fulfilled.

Public methods

addRequestCancellationListener

fun addRequestCancellationListener(
    @NonNull executor: Executor,
    @NonNull listener: Runnable
): Unit

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, setWillNotComplete() will have no effect and will return false. Attempting to complete the request via setSurface(Surface) will also have no effect, and the returned ListenableFuture will contain a RequestCancelledException.

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 setSurface(Surface) or setWillNotComplete(), so the return values of these methods can always be checked if your workflow for producing a surface expects them to complete successfully.

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

getResolution

@NonNull fun getResolution(): Size

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 future returned by setSurface(Surface) to fail with an IllegalArgumentException.

Return
Size: The guaranteed supported resolution.

setSurface

@NonNull fun setSurface(@NonNull surface: Surface): ListenableFuture<Void!>

Completes the request for a Surface if it has not already been completed or cancelled.

Upon returning from this method, the surface request is guaranteed to be complete. However, only the ListenableFuture returned by the first invocation of this method should be used to track when the provided Surface is no longer in use by the camera, as subsequent invocations will always return a ListenableFuture that immediately contains an IllegalStateException.

Parameters
surface Surface: The surface which will complete the request.
Return
ListenableFuture<Void!>: A ListenableFuture which can be used to track when the provided surface is no longer being used. Successful completion of this future means the surface is no longer in use by the camera, and all resources associated with the surface can be safely cleaned up. If the SurfaceRequest was successfully completed by setSurface(Surface) or setWillNotComplete() prior to setting the surface, then this future will fail with a IllegalStateException. If the SurfaceRequest was cancelled by the camera prior to calling setSurface(Surface), then this future will fail with an RequestCancelledException. If the surface does not meet the requirements, such has not having a resolution that matches getResolution(), this future may fail with an IllegalArgumentException. Cancelling the returned future via ListenableFuture#cancel(boolean) is a no-op, and should be avoided in most cases as this bypasses the signal that the Surface is no longer in use by the camera. Releasing the Surface before the camera is done using it may lead to undesired behavior.

setWillNotComplete

fun setWillNotComplete(): Boolean

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 setWillNotComplete() or setSurface(Surface) 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 setSurface(Surface), invoking this method will not affection completion of the returned ListenableFuture.

Return
Boolean: true if this call to setWillNotComplete() successfully completes the request, i.e., the request has not already been completed via setSurface(Surface) or by a previous call to setWillNotComplete() and has not already been cancelled by the camera.