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 | |
|---|---|
| abstract |
Result of providing a surface to a |
| abstract |
Transformation associated the preview output. |
| abstract |
Listener that receives updates of the |
| Public methods | |
|---|---|
| Unit |
addRequestCancellationListener(@NonNull executor: Executor, @NonNull listener: Runnable)Adds a listener to be informed when the camera cancels the surface request. |
| Unit |
Clears the |
| Size |
Returns the resolution of the requested |
| Unit |
provideSurface(@NonNull surface: Surface, @NonNull executor: Executor, @NonNull resultListener: Consumer<SurfaceRequest.Result!>)Completes the request for a |
| Unit |
setTransformationInfoListener(@NonNull executor: Executor, @NonNull listener: SurfaceRequest.TransformationInfoListener)Sets a listener to receive updates on transformation info. |
| 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, willNotProvideSurface() will have no effect and will return false. Attempting to complete the request via provideSurface(Surface, Executor, Consumer) will also have no effect, and any resultListener passed to provideSurface(Surface, Executor, Consumer) will be invoked with a Result containing Result#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(Surface, Executor, Consumer) 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 | |
|---|---|
executor |
Executor: The executor used to notify the listener. |
listener |
Runnable: The listener which will be run upon request cancellation. |
clearTransformationInfoListener
fun clearTransformationInfoListener(): Unit
Clears the TransformationInfoListener set via setTransformationInfoListener.
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 resultListener passed to provideSurface(Surface, Executor, Consumer) to be invoked with a Result containing Result#RESULT_INVALID_SURFACE.
| Return | |
|---|---|
Size |
The guaranteed supported resolution. |
provideSurface
fun provideSurface(
@NonNull surface: Surface,
@NonNull executor: Executor,
@NonNull resultListener: Consumer<SurfaceRequest.Result!>
): Unit
Completes the request for a Surface if it has not already been completed or cancelled.
Once the camera no longer needs the provided surface, the resultListener will be invoked with a Result containing Result#RESULT_SURFACE_USED_SUCCESSFULLY. At this point it is safe to release the surface and any underlying resources. Releasing the surface before receiving this signal may cause undesired behavior on lower API levels.
If the request is cancelled by the camera before successfully attaching the provided surface to the camera, then the resultListener will be invoked with a Result containing Result#RESULT_REQUEST_CANCELLED. In addition, any cancellation listeners provided to addRequestCancellationListener(Executor, Runnable) will be invoked.
If the request was previously completed via willNotProvideSurface(), then resultListener will be invoked with a Result containing Result#RESULT_WILL_NOT_PROVIDE_SURFACE.
Upon returning from this method, the surface request is gu