public abstract class CameraCaptureSession extends Object implements AutoCloseable
CameraDevice
, used for capturing images from the
camera or reprocessing images captured from the camera in the same session previously.
A CameraCaptureSession is created by providing a set of target output surfaces to
createCaptureSession
, or by providing an
InputConfiguration
and a set of target output surfaces to
createReprocessableCaptureSession
for a
reprocessable capture session. Once created, the session is active until a new session is
created by the camera device, or the camera device is closed.
All capture sessions can be used for capturing images from the camera but only reprocessable capture sessions can reprocess images captured from the camera in the same session previously.
Creating a session is an expensive operation and can take several hundred milliseconds, since
it requires configuring the camera device's internal pipelines and allocating memory buffers for
sending images to the desired targets. Therefore the setup is done asynchronously, and
createCaptureSession
and
createReprocessableCaptureSession
will
send the ready-to-use CameraCaptureSession to the provided listener's
onConfigured
callback. If configuration
cannot be completed, then the
onConfigureFailed
is called, and the
session will not become active.
If a new session is created by the camera device, then the previous session is closed, and its
associated onClosed
callback will be invoked. All
of the session methods will throw an IllegalStateException if called once the session is
closed.
A closed session clears any repeating requests (as if stopRepeating()
had been called),
but will still complete all of its in-progress capture requests as normal, before a newly
created session takes over and reconfigures the camera device.
Modifier and Type | Class and Description |
---|---|
static class |
CameraCaptureSession.CaptureCallback
A callback object for tracking the progress of a
CaptureRequest submitted to the
camera device. |
static class |
CameraCaptureSession.CaptureListener
Temporary for migrating to Callback naming
|
static class |
CameraCaptureSession.StateCallback
A callback object for receiving updates about the state of a camera capture session.
|
static class |
CameraCaptureSession.StateListener
Temporary for migrating to Callback naming
|
Modifier and Type | Field and Description |
---|---|
static int |
SESSION_ID_NONE
Used to identify invalid session ID.
|
Constructor and Description |
---|
CameraCaptureSession() |
Modifier and Type | Method and Description |
---|---|
abstract void |
abortCaptures()
Discard all captures currently pending and in-progress as fast as possible.
|
abstract int |
capture(CaptureRequest request,
CameraCaptureSession.CaptureCallback listener,
Handler handler)
Submit a request for an image to be captured by the camera device.
|
abstract int |
captureBurst(List<CaptureRequest> requests,
CameraCaptureSession.CaptureCallback listener,
Handler handler)
Submit a list of requests to be captured in sequence as a burst.
|
abstract void |
close()
Close this capture session asynchronously.
|
abstract void |
finishDeferredConfiguration(List<OutputConfiguration> deferredOutputConfigs)
Finish the deferred output configurations where the output Surface was not configured before.
|
abstract CameraDevice |
getDevice()
Get the camera device that this session is created for.
|
abstract Surface |
getInputSurface()
Get the input Surface associated with a reprocessable capture session.
|
abstract boolean |
isReprocessable()
Return if the application can submit reprocess capture requests with this camera capture
session.
|
abstract void |
prepare(int maxCount,
Surface surface)
Pre-allocate at most maxCount buffers for an output Surface.
|
abstract void |
prepare(Surface surface)
Pre-allocate all buffers for an output Surface.
|
abstract int |
setRepeatingBurst(List<CaptureRequest> requests,
CameraCaptureSession.CaptureCallback listener,
Handler handler)
Request endlessly repeating capture of a sequence of images by this
capture session.
|
abstract int |
setRepeatingRequest(CaptureRequest request,
CameraCaptureSession.CaptureCallback listener,
Handler handler)
Request endlessly repeating capture of images by this capture session.
|
abstract void |
stopRepeating()
Cancel any ongoing repeating capture set by either
setRepeatingRequest or
setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler) . |
abstract void |
tearDown(Surface surface)
Free all buffers allocated for an output Surface.
|
public static final int SESSION_ID_NONE
public abstract CameraDevice getDevice()
public abstract void prepare(Surface surface) throws CameraAccessException
Pre-allocate all buffers for an output Surface.
Normally, the image buffers for a given output Surface are allocated on-demand, to minimize startup latency and memory overhead.
However, in some cases, it may be desirable for the buffers to be allocated before any requests targeting the Surface are actually submitted to the device. Large buffers may take some time to allocate, which can result in delays in submitting requests until sufficient buffers are allocated to reach steady-state behavior. Such delays can cause bursts to take longer than desired, or cause skips or stutters in preview output.
The prepare() method can be used to perform this preallocation. It may only be called for a given output Surface before that Surface is used as a target for a request. The number of buffers allocated is the sum of the count needed by the consumer providing the output Surface, and the maximum number needed by the camera device to fill its pipeline. Since this may be a larger number than what is actually required for steady-state operation, using prepare may result in higher memory consumption than the normal on-demand behavior results in. Prepare() will also delay the time to first output to a given Surface, in exchange for smoother frame rate once the allocation is complete.
For example, an application that creates an
ImageReader
with a maxImages argument of 10,
but only uses 3 simultaneous Images at once would normally only cause those 3 images to be
allocated (plus what is needed by the camera device for smooth operation). But using
prepare() on the ImageReader Surface will result in all 10 Images being allocated. So
applications using this method should take care to request only the number of buffers
actually necessary for their application.
If the same output Surface is used in consecutive sessions (without closing the first session explicitly), then its already-allocated buffers are carried over, and if it was used as a target of a capture request in the first session, prepare cannot be called on it in the second session.
Once allocation is complete, CameraCaptureSession.StateCallback.onSurfacePrepared(android.hardware.camera2.CameraCaptureSession, android.view.Surface)
will be invoked with
the Surface provided to this method. Between the prepare call and the onSurfacePrepared call,
the Surface provided to prepare must not be used as a target of a CaptureRequest submitted
to this session.
LEGACY
devices cannot pre-allocate output buffers; for those devices,
CameraCaptureSession.StateCallback.onSurfacePrepared(android.hardware.camera2.CameraCaptureSession, android.view.Surface)
will be immediately called, and no preallocation is
done.
surface
- the output Surface for which buffers should be pre-allocated. Must be one of
the output Surfaces used to create this session.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorIllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created
or the camera device has been closed.IllegalArgumentException
- if the Surface is invalid, not part of this Session, or has
already been used as a target of a CaptureRequest in this
session or immediately prior sessions.CameraCaptureSession.StateCallback.onSurfacePrepared(android.hardware.camera2.CameraCaptureSession, android.view.Surface)
public abstract void prepare(int maxCount, Surface surface) throws CameraAccessException
Pre-allocate at most maxCount buffers for an output Surface.
Like the prepare(Surface)
method, this method can be used to allocate output
buffers for a given Surface. However, while the prepare(Surface)
method allocates
the maximum possible buffer count, this method allocates at most maxCount buffers.
If maxCount is greater than the possible maximum count (which is the sum of the buffer
count requested by the creator of the Surface and the count requested by the camera device),
only the possible maximum count is allocated, in which case the function acts exactly like
prepare(Surface)
.
The restrictions on when this method can be called are the same as for
prepare(Surface)
.
Repeated calls to this method are allowed, and a mix of prepare(Surface)
and
this method is also allowed. Note that after the first call to prepare(Surface)
,
subsequent calls to either prepare method are effectively no-ops. In addition, this method
is not additive in terms of buffer count. This means calling it twice with maxCount = 2
will only allocate 2 buffers, not 4 (assuming the possible maximum is at least 2); to
allocate two buffers on the first call and two on the second, the application needs to call
prepare with prepare(surface, 2) and prepare(surface, 4).
maxCount
- the buffer count to try to allocate. If this is greater than the possible
maximum for this output, the possible maximum is allocated instead. If
maxCount buffers are already allocated, then prepare will do nothing.surface
- the output Surface for which buffers should be pre-allocated.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal error.IllegalStateException
- if this session is no longer active, either because the
session was explicitly closed, a new session has been created
or the camera device has been closed.IllegalArgumentException
- if the Surface is invalid, not part of this Session,
or has already been used as a target of a CaptureRequest in
this session or immediately prior sessions without an
intervening tearDown call.public abstract void tearDown(Surface surface) throws CameraAccessException
Free all buffers allocated for an output Surface.
Normally, once allocated, the image buffers for a given output Surface remain allocated for the lifetime of the capture session, to minimize latency of captures and to reduce memory allocation overhead.
However, in some cases, it may be desirable for allocated buffers to be freed to reduce the application's memory consumption, if the particular output Surface will not be used by the application for some time.
The tearDown() method can be used to perform this operation. After the call finishes, all unfilled image buffers will have been freed. Any future use of the target Surface may require allocation of additional buffers, as if the session had just been created. Buffers being held by the application (either explicitly as Image objects from ImageReader, or implicitly as the current texture in a SurfaceTexture or the current contents of a RS Allocation, will remain valid and allocated even when tearDown is invoked.
A Surface that has had tearDown() called on it is eligible to have prepare() invoked on it again even if it was used as a request target before the tearDown() call, as long as it doesn't get used as a target of a request between the tearDown() and prepare() calls.
surface
- the output Surface for which buffers should be freed. Must be one of the
the output Surfaces used to create this session.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal error.IllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created
or the camera device has been closed.IllegalArgumentException
- if the Surface is invalid, not part of this Session, or has
already been used as a target of a CaptureRequest in this
session or immediately prior sessions.public abstract void finishDeferredConfiguration(List<OutputConfiguration> deferredOutputConfigs) throws CameraAccessException
Finish the deferred output configurations where the output Surface was not configured before.
For camera use cases where a preview and other output configurations need to be configured,
it can take some time for the preview Surface to be ready (e.g., if the preview Surface is
obtained from SurfaceView
, the SurfaceView is ready after the UI layout
is done, then it takes some time to get the preview Surface).
To speed up camera startup time, the application can configure the
CameraCaptureSession
with the desired preview size, and defer the preview output
configuration until the Surface is ready. After the CameraCaptureSession
is created
successfully with this deferred configuration and other normal configurations, the
application can submit requests that don't include deferred output Surfaces. Once the
deferred Surface is ready, the application can set the Surface to the same deferred output
configuration with the OutputConfiguration.setDeferredSurface(android.view.Surface)
method, and then finish
the deferred output configuration via this method, before it can submit requests with this
output target.
The output Surfaces included by this list of deferred OutputConfigurations
can be used as CaptureRequest
targets as soon as this call
returns;
This method is not supported by Legacy devices.
deferredOutputConfigs
- a list of OutputConfigurations
that
have had setDeferredSurface
invoked
with a valid output Surface.CameraAccessException
- if the camera device is no longer connected or has encountered
a fatal error.IllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created or the camera device has
been closed. Or if this output configuration was already finished with the
included surface before.IllegalArgumentException
- for invalid output configurations, including ones where the
source of the Surface is no longer valid or the Surface is from a unsupported
source.public abstract int capture(CaptureRequest request, CameraCaptureSession.CaptureCallback listener, Handler handler) throws CameraAccessException
Submit a request for an image to be captured by the camera device.
The request defines all the parameters for capturing the single image, including sensor, lens, flash, and post-processing settings.
Each request will produce one CaptureResult
and produce new frames for one or more
target Surfaces, set with the CaptureRequest builder's
CaptureRequest.Builder.addTarget(android.view.Surface)
method. The target surfaces (set with
CaptureRequest.Builder.addTarget(android.view.Surface)
) must be a subset of the surfaces provided when this
capture session was created.
Multiple regular and reprocess requests can be in progress at once. If there are only regular requests or reprocess requests in progress, they are processed in first-in, first-out order. If there are both regular and reprocess requests in progress, regular requests are processed in first-in, first-out order and reprocess requests are processed in first-in, first-out order, respectively. However, the processing order of a regular request and a reprocess request in progress is not specified. In other words, a regular request will always be processed before regular requets that are submitted later. A reprocess request will always be processed before reprocess requests that are submitted later. However, a regular request may not be processed before reprocess requests that are submitted later.
Requests submitted through this method have higher priority than
those submitted through setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
or
setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, and will be processed as soon as the current
repeat/repeatBurst processing completes.
All capture sessions can be used for capturing images from the camera but only capture
sessions created by
createReprocessableCaptureSession
can submit reprocess capture requests. Submitting a reprocess request to a regular capture
session will result in an IllegalArgumentException
.
request
- the settings for this capturelistener
- The callback object to notify once this request has been
processed. If null, no metadata will be produced for this capture,
although image data will still be produced.handler
- the handler on which the listener should be invoked, or
null
to use the current thread's looper
.CameraCaptureSession.CaptureCallback.onCaptureSequenceCompleted(android.hardware.camera2.CameraCaptureSession, int, long)
.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorIllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created
or the camera device has been closed.IllegalArgumentException
- if the request targets no Surfaces or Surfaces that are not
configured as outputs for this session; or the request
targets a set of Surfaces that cannot be submitted
simultaneously in a reprocessable capture session; or a
reprocess capture request is submitted in a
non-reprocessable capture session; or the reprocess capture
request was created with a TotalCaptureResult
from
a different session; or the capture targets a Surface in
the middle of being prepared
; or the
handler is null, the listener is not null, and the calling
thread has no looper.captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
abortCaptures()
,
CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
public abstract int captureBurst(List<CaptureRequest> requests, CameraCaptureSession.CaptureCallback listener, Handler handler) throws CameraAccessException
Regular and reprocess requests can be mixed together in a single burst. Regular requests
will be captured in order and reprocess requests will be processed in order, respectively.
However, the processing order between a regular request and a reprocess request is not
specified. Each capture produces one CaptureResult
and image buffers for one or more
target surfaces
. The target surfaces (set with
CaptureRequest.Builder.addTarget(android.view.Surface)
) must be a subset of the surfaces provided when
this capture session was created.
The main difference between this method and simply calling
capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
repeatedly is that this method guarantees that no
other requests will be interspersed with the burst.
All capture sessions can be used for capturing images from the camera but only capture
sessions created by
createReprocessableCaptureSession
can submit reprocess capture requests. Submitting a reprocess request to a regular
capture session will result in an IllegalArgumentException
.
requests
- the list of settings for this burst capturelistener
- The callback object to notify each time one of the
requests in the burst has been processed. If null, no metadata will be
produced for any requests in this burst, although image data will still
be produced.handler
- the handler on which the listener should be invoked, or
null
to use the current thread's looper
.CameraCaptureSession.CaptureCallback.onCaptureSequenceCompleted(android.hardware.camera2.CameraCaptureSession, int, long)
.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorIllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created
or the camera device has been closed.IllegalArgumentException
- If the requests target no Surfaces, or the requests target
Surfaces not currently configured as outputs; or one of the
requests targets a set of Surfaces that cannot be submitted
simultaneously in a reprocessable capture session; or a
reprocess capture request is submitted in a
non-reprocessable capture session; or one of the reprocess
capture requests was created with a
TotalCaptureResult
from a different session; or one
of the captures targets a Surface in the middle of being
prepared
; or if the handler is null, the
listener is not null, and the calling thread has no looper.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
abortCaptures()
public abstract int setRepeatingRequest(CaptureRequest request, CameraCaptureSession.CaptureCallback listener, Handler handler) throws CameraAccessException
With this method, the camera device will continually capture images
using the settings in the provided CaptureRequest
, at the maximum
rate possible.
Repeating requests are a simple way for an application to maintain a
preview or other continuous stream of frames, without having to
continually submit identical requests through capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
.
Repeat requests have lower priority than those submitted
through capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
or captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, so if
capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
is called when a repeating request is active, the
capture request will be processed before any further repeating
requests are processed.
To stop the repeating capture, call stopRepeating()
. Calling
abortCaptures()
will also clear the request.
Calling this method will replace any earlier repeating request or
burst set up by this method or setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, although any
in-progress burst will be completed before the new repeat request will be
used.
This method does not support reprocess capture requests because each reprocess
CaptureRequest
must be created from the TotalCaptureResult
that matches
the input image to be reprocessed. This is either the TotalCaptureResult
of capture
that is sent for reprocessing, or one of the TotalCaptureResults
of a set of captures, when data from the whole set is combined by the application into a
single reprocess input image. The request must be capturing images from the camera. If a
reprocess capture request is submitted, this method will throw IllegalArgumentException.
request
- the request to repeat indefinitelylistener
- The callback object to notify every time the
request finishes processing. If null, no metadata will be
produced for this stream of requests, although image data will
still be produced.handler
- the handler on which the listener should be invoked, or
null
to use the current thread's looper
.CameraCaptureSession.CaptureCallback.onCaptureSequenceCompleted(android.hardware.camera2.CameraCaptureSession, int, long)
.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorIllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created
or the camera device has been closed.IllegalArgumentException
- If the request references no Surfaces or references Surfaces
that are not currently configured as outputs; or the request
is a reprocess capture request; or the capture targets a
Surface in the middle of being prepared
; or
the handler is null, the listener is not null, and the
calling thread has no looper; or no requests were passed in.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
stopRepeating()
,
abortCaptures()
public abstract int setRepeatingBurst(List<CaptureRequest> requests, CameraCaptureSession.CaptureCallback listener, Handler handler) throws CameraAccessException
Request endlessly repeating capture of a sequence of images by this capture session.
With this method, the camera device will continually capture images,
cycling through the settings in the provided list of
CaptureRequests
, at the maximum rate possible.
If a request is submitted through capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
or
captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, the current repetition of the request list will be
completed before the higher-priority request is handled. This guarantees
that the application always receives a complete repeat burst captured in
minimal time, instead of bursts interleaved with higher-priority
captures, or incomplete captures.
Repeating burst requests are a simple way for an application to
maintain a preview or other continuous stream of frames where each
request is different in a predicatable way, without having to continually
submit requests through captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
.
To stop the repeating capture, call stopRepeating()
. Any
ongoing burst will still be completed, however. Calling
abortCaptures()
will also clear the request.
Calling this method will replace a previously-set repeating request or
burst set up by this method or setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
, although any
in-progress burst will be completed before the new repeat burst will be
used.
This method does not support reprocess capture requests because each reprocess
CaptureRequest
must be created from the TotalCaptureResult
that matches
the input image to be reprocessed. This is either the TotalCaptureResult
of capture
that is sent for reprocessing, or one of the TotalCaptureResults
of a set of captures, when data from the whole set is combined by the application into a
single reprocess input image. The request must be capturing images from the camera. If a
reprocess capture request is submitted, this method will throw IllegalArgumentException.
requests
- the list of requests to cycle through indefinitelylistener
- The callback object to notify each time one of the
requests in the repeating bursts has finished processing. If null, no
metadata will be produced for this stream of requests, although image
data will still be produced.handler
- the handler on which the listener should be invoked, or
null
to use the current thread's looper
.CameraCaptureSession.CaptureCallback.onCaptureSequenceCompleted(android.hardware.camera2.CameraCaptureSession, int, long)
.CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorIllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created
or the camera device has been closed.IllegalArgumentException
- If the requests reference no Surfaces or reference Surfaces
not currently configured as outputs; or one of the requests
is a reprocess capture request; or one of the captures
targets a Surface in the middle of being
prepared
; or the handler is null, the
listener is not null, and the calling thread has no looper;
or no requests were passed in.capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
captureBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
stopRepeating()
,
abortCaptures()
public abstract void stopRepeating() throws CameraAccessException
Cancel any ongoing repeating capture set by either
setRepeatingRequest
or
setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
. Has no effect on requests submitted through
capture
or captureBurst
.
Any currently in-flight captures will still complete, as will any burst that is
mid-capture. To ensure that the device has finished processing all of its capture requests
and is in ready state, wait for the CameraCaptureSession.StateCallback.onReady(android.hardware.camera2.CameraCaptureSession)
callback after
calling this method.
CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorIllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created
or the camera device has been closed.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
StateCallback#onIdle
public abstract void abortCaptures() throws CameraAccessException
The camera device will discard all of its current work as fast as possible. Some in-flight
captures may complete successfully and call CameraCaptureSession.CaptureCallback.onCaptureCompleted(android.hardware.camera2.CameraCaptureSession, android.hardware.camera2.CaptureRequest, android.hardware.camera2.TotalCaptureResult)
, while
others will trigger their CameraCaptureSession.CaptureCallback.onCaptureFailed(android.hardware.camera2.CameraCaptureSession, android.hardware.camera2.CaptureRequest, android.hardware.camera2.CaptureFailure)
callbacks. If a repeating
request or a repeating burst is set, it will be cleared.
This method is the fastest way to switch the camera device to a new session with
CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
or
CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
, at the cost of discarding in-progress
work. It must be called before the new session is created. Once all pending requests are
either completed or thrown away, the CameraCaptureSession.StateCallback.onReady(android.hardware.camera2.CameraCaptureSession)
callback will be called,
if the session has not been closed. Otherwise, the CameraCaptureSession.StateCallback.onClosed(android.hardware.camera2.CameraCaptureSession)
callback will be fired when a new session is created by the camera device.
Cancelling will introduce at least a brief pause in the stream of data from the camera device, since once the camera device is emptied, the first new request has to make it through the entire camera pipeline before new output buffers are produced.
This means that using abortCaptures()
to simply remove pending requests is not
recommended; it's best used for quickly switching output configurations, or for cancelling
long in-progress requests (such as a multi-second capture).
CameraAccessException
- if the camera device is no longer connected or has
encountered a fatal errorIllegalStateException
- if this session is no longer active, either because the session
was explicitly closed, a new session has been created
or the camera device has been closed.setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
setRepeatingBurst(java.util.List<android.hardware.camera2.CaptureRequest>, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)
,
CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
,
CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
public abstract boolean isReprocessable()
true
if the application can submit reprocess capture requests with this
camera capture session. false
otherwise.CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
public abstract Surface getInputSurface()
Each reprocessable capture session has an input Surface
where the reprocess
capture requests get the input images from, rather than the camera device. The application
can create a ImageWriter
with this input Surface
and use it to provide input images for reprocess capture requests. When the reprocessable
capture session is closed, the input Surface
is abandoned and becomes invalid.
Surface
where reprocessing capture requests get the input images from. If
this is not a reprocess capture session, null
will be returned.CameraDevice.createReprocessableCaptureSession(android.hardware.camera2.params.InputConfiguration, java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
,
ImageWriter
,
ImageReader
public abstract void close()
Closing a session frees up the target output Surfaces of the session for reuse with either a new session, or to other APIs that can draw to Surfaces.
Note that creating a new capture session with CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
will close any existing capture session automatically, and call the older session listener's
CameraCaptureSession.StateCallback.onClosed(android.hardware.camera2.CameraCaptureSession)
callback. Using CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, android.hardware.camera2.CameraCaptureSession.StateCallback, android.os.Handler)
directly without closing is the recommended approach for quickly switching to a new session,
since unchanged target outputs can be reused more efficiently.
Once a session is closed, all methods on it will throw an IllegalStateException, and any
repeating requests or bursts are stopped (as if stopRepeating()
was called).
However, any in-progress capture requests submitted to the session will be completed as
normal; once all captures have completed and the session has been torn down,
CameraCaptureSession.StateCallback.onClosed(android.hardware.camera2.CameraCaptureSession)
will be called.
Closing a session is idempotent; closing more than once has no effect.
close
in interface AutoCloseable