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 |
class |
SurfaceRequest.TransformationInfo
Transformation associated the preview output. |
interface |
SurfaceRequest.TransformationInfoListener
Listener that receives updates of the |
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 |
Size
|
getResolution()
Returns the resolution of the requested |
void
|
provideSurface(Surface surface, Executor executor, Consumer<SurfaceRequest.Result> resultListener)
Completes the request for a |
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.
|
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-09-30 UTC.