Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

SurfaceRequest

public final class SurfaceRequest
extends Object

java.lang.Object
   ↳ 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

class SurfaceRequest.Result

Result of providing a surface to a SurfaceRequest via SurfaceRequest.provideSurface(Surface, Executor, Consumer). 

class SurfaceRequest.TransformationInfo

Transformation associated the preview output. 

interface SurfaceRequest.TransformationInfoListener

Listener that receives updates of the SurfaceRequest.TransformationInfo associated with the SurfaceRequest. 

Public methods

void addRequestCancellationListener(Executor executor, Runnable listener)

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

void clearTransformationInfoListener()

Clears the SurfaceRequest.TransformationInfoListener set via setTransformationInfoListener(Executor, SurfaceRequest.TransformationInfoListener).

Size getResolution()

Returns the resolution of the requested Surface.

void provideSurface(Surface surface, Executor executor, Consumer<SurfaceRequest.Result> resultListener)

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

void setTransformationInfoListener(Executor executor, SurfaceRequest.TransformationInfoListener listener)

Sets a listener to receive updates on transformation info.

boolean willNotProvideSurface()

Signals that the request will never be fulfilled.

Inherited methods

Public methods

addRequestCancellationListener

public void addRequestCancellationListener (Executor executor, 
                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(Surface, Executor, Consumer) will also have no effect, and any resultListener passed to provideSurface(Surface, Executor, Consumer) will be invoked with a SurfaceRequest.Result containing SurfaceRequest.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

public void clearTransformationInfoListener ()

Clears the SurfaceRequest.TransformationInfoListener set via setTransformationInfoListener(Executor, SurfaceRequest.TransformationInfoListener).

getResolution

public 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(Surface, Executor, Consumer) to be invoked with a SurfaceRequest.Result containing SurfaceRequest.Result.RESULT_INVALID_SURFACE.

Returns
Size The guaranteed supported resolution.

provideSurface

public void provideSurface (Surface surface, 
                Executor executor, 
                Consumer<SurfaceRequest.Result> resultListener)

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 SurfaceRequest.Result containing SurfaceRequest.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 SurfaceRequest.Result containing SurfaceRequest.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 SurfaceRequest.Result containing SurfaceRequest.Result.RESULT_WILL_NOT_PROVIDE_SURFACE.

Upon returning from this method, the surface request is guaranteed to be complete. However, only the resultListener provided to 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 invoke the resultListener with a SurfaceRequest.Result containing SurfaceRequest.Result.RESULT_SURFACE_ALREADY_PROVIDED.

Parameters
surface Surface: The surface which will complete the request.
executor Executor: Executor used to execute the resultListener.
resultListener Consumer: Listener used to track how the surface is used by the camera in response to being provided by this method.

setTransformationInfoListener

public void setTransformationInfoListener (Executor executor, 
                SurfaceRequest.TransformationInfoListener listener)

Sets a listener to receive updates on transformation info.

Sets a listener to receive the transformation info associated with this SurfaceRequest when it changes or becomes available. The listener is called immediately if transformation info is available at the time of setting.

Parameters
executor Executor: The executor used to notify the listener.
listener SurfaceRequest.TransformationInfoListener: the listener which will be called when transformation info changes.

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(Surface, Executor, Consumer) 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(Surface, Executor, Consumer), 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(Surface, Executor, Consumer) or by a previous call to willNotProvideSurface() and has not already been cancelled by the camera.