java.lang.Object | |
↳ | android.hardware.camera2.CameraCaptureSession |
A configured capture session for a CameraDevice
, used for capturing
images from the camera.
A CameraCaptureSession is created by providing a set of target output surfaces to
createCaptureSession
. Once created, the session is
active until a new session is created by the camera device, or the camera device is closed.
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
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.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
CameraCaptureSession.CaptureListener | A listener for tracking the progress of a |
||||||||||
CameraCaptureSession.StateListener | A listener for tracking the state of a camera capture session. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Discard all captures currently pending and in-progress as fast as possible.
| |||||||||||
Submit a request for an image to be captured by the camera device. | |||||||||||
Submit a list of requests to be captured in sequence as a burst.
| |||||||||||
Close this capture session asynchronously.
| |||||||||||
Get the camera device that this session is created for.
| |||||||||||
Request endlessly repeating capture of a sequence of images by this capture session. | |||||||||||
Request endlessly repeating capture of images by this capture session.
| |||||||||||
Cancel any ongoing repeating capture set by either
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
From interface
java.lang.AutoCloseable
|
Discard all captures currently pending and in-progress as fast as possible.
The camera device will discard all of its current work as fast as possible. Some in-flight
captures may complete successfully and call onCaptureCompleted(CameraCaptureSession, CaptureRequest, TotalCaptureResult)
, while
others will trigger their onCaptureFailed(CameraCaptureSession, CaptureRequest, 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
createCaptureSession(List
, 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 onReady(CameraCaptureSession)
callback will be called,
if the session has not been closed. Otherwise, the onClosed(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 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. |
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
addTarget(Surface)
method. The target surfaces (set with
addTarget(Surface)
) must be a subset of the surfaces provided when this
capture session was created.
Multiple requests can be in progress at once. They are processed in
first-in, first-out order, with minimal delays between each
capture. Requests submitted through this method have higher priority than
those submitted through setRepeatingRequest(CaptureRequest, CameraCaptureSession.CaptureListener, Handler)
or
setRepeatingBurst(List
, and will be processed as soon as the current
repeat/repeatBurst processing completes.
request | the settings for this capture |
---|---|
listener | 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 . |
onCaptureSequenceCompleted(CameraCaptureSession, int, long)
.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 request targets Surfaces that are not configured as outputs for this session. Or if the handler is null, the listener is not null, and the calling thread has no looper. |
Submit a list of requests to be captured in sequence as a burst. The burst will be captured in the minimum amount of time possible, and will not be interleaved with requests submitted by other capture or repeat calls.
The requests will be captured in order, each capture producing one CaptureResult
and image buffers for one or more target surfaces
. The target
surfaces (set with addTarget(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(CaptureRequest, CameraCaptureSession.CaptureListener, Handler)
repeatedly is that this method guarantees that no
other requests will be interspersed with the burst.
requests | the list of settings for this burst capture |
---|---|
listener | 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 . |
onCaptureSequenceCompleted(CameraCaptureSession, int, long)
.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 requests target Surfaces not currently configured as outputs. Or if the handler is null, the listener is not null, and the calling thread has no looper. |
Close this capture session asynchronously.
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 createCaptureSession(List
will close any existing capture session automatically, and call the older session listener's
onClosed(CameraCaptureSession)
callback. Using createCaptureSession(List
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,
onClosed(CameraCaptureSession)
will be called.
Closing a session is idempotent; closing more than once has no effect.
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(CaptureRequest, CameraCaptureSession.CaptureListener, Handler)
or
captureBurst(List
, 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(List
.
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(CaptureRequest, CameraCaptureSession.CaptureListener, Handler)
, although any
in-progress burst will be completed before the new repeat burst will be
used.
requests | the list of requests to cycle through indefinitely |
---|---|
listener | 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 . |
onCaptureSequenceCompleted(CameraCaptureSession, int, long)
.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 requests reference Surfaces not currently configured as outputs. Or if the handler is null, the listener is not null, and the calling thread has no looper. Or if no requests were passed in. |
Request endlessly repeating capture of images by this capture session.
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(CaptureRequest, CameraCaptureSession.CaptureListener, Handler)
.
Repeat requests have lower priority than those submitted
through capture(CaptureRequest, CameraCaptureSession.CaptureListener, Handler)
or captureBurst(List
, so if
capture(CaptureRequest, CameraCaptureSession.CaptureListener, 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(List
, although any
in-progress burst will be completed before the new repeat request will be
used.
request | the request to repeat indefinitely |
---|---|
listener | 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 . |
onCaptureSequenceCompleted(CameraCaptureSession, int, long)
.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 requests reference Surfaces that are not currently configured as outputs. Or if the handler is null, the listener is not null, and the calling thread has no looper. Or if no requests were passed in. |
Cancel any ongoing repeating capture set by either
setRepeatingRequest
or
setRepeatingBurst(List
. 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 onReady(CameraCaptureSession)
callback after
calling this method.
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. |