CameraCaptureSession
abstract class CameraCaptureSession : AutoCloseable
| kotlin.Any | |
| ↳ | android.hardware.camera2.CameraCaptureSession |
A configured capture session for a 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 android.hardware.camera2.CameraDevice#createCaptureSession, or by providing an android.hardware.camera2.params.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 android.hardware.camera2.CameraDevice#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.
Summary
| Nested classes | |
|---|---|
| abstract |
A callback object for tracking the progress of a |
| abstract |
A callback object for receiving updates about the state of a camera capture session. |
| Public constructors | |
|---|---|
| Public methods | |
|---|---|
| abstract Unit |
Discard all captures currently pending and in-progress as fast as possible. |
| abstract Int |
capture(request: CaptureRequest, listener: CameraCaptureSession.CaptureCallback?, handler: Handler?)Submit a request for an image to be captured by the camera device. |
| abstract Int |
captureBurst(requests: MutableList<CaptureRequest!>, listener: CameraCaptureSession.CaptureCallback?, handler: Handler?)Submit a list of requests to be captured in sequence as a burst. |
| open Int |
captureBurstRequests(requests: MutableList<CaptureRequest!>, executor: Executor, listener: CameraCaptureSession.CaptureCallback)Submit a list of requests to be captured in sequence as a burst. |
| open Int |
captureSingleRequest(request: CaptureRequest, executor: Executor, listener: CameraCaptureSession.CaptureCallback)Submit a request for an image to be captured by the camera device. |
| abstract Unit |
close()Close this capture session asynchronously. |
| abstract Unit |
finalizeOutputConfigurations(outputConfigs: MutableList<OutputConfiguration!>!)Finalize the output configurations that now have their deferred and/or extra Surfaces included. |
| abstract CameraDevice |
Get the camera device that this session is created for. |
| abstract Surface? |
Get the input Surface associated with a reprocessable capture session. |
| abstract Boolean |
Return if the application can submit reprocess capture requests with this camera capture session. |
| abstract Unit |
Pre-allocate all buffers for an output Surface. |
| abstract Int |
setRepeatingBurst(requests: MutableList<CaptureRequest!>, listener: CameraCaptureSession.CaptureCallback?, handler: Handler?)Request endlessly repeating capture of a sequence of images by this capture session. |
| open Int |
setRepeatingBurstRequests(requests: MutableList<CaptureRequest!>, executor: Executor, listener: CameraCaptureSession.CaptureCallback)Request endlessly repeating capture of a sequence of images by this capture session. |
| abstract Int |
setRepeatingRequest(request: CaptureRequest, listener: CameraCaptureSession.CaptureCallback?, handler: Handler?)Request endlessly repeating capture of images by this capture session. |
| open Int |
setSingleRepeatingRequest(request: CaptureRequest, executor: Executor, listener: CameraCaptureSession.CaptureCallback)Request endlessly repeating capture of images by this capture session. |
| abstract Unit |
Cancel any ongoing repeating capture set by either |
| open Boolean |
supportsOfflineProcessing(surface: Surface)Query whether a given Surface is able to support offline mode. |
| open CameraOfflineSession? |
switchToOffline(offlineSurfaces: MutableCollection<Surface!>, executor: Executor, listener: CameraOfflineSession.CameraOfflineSessionCallback)Switch the current capture session and a given set of registered camera surfaces to offline processing mode. |
| open Unit |
updateOutputConfiguration(config: OutputConfiguration!)Update |
| open Unit |
updateOutputConfigurations(configurations: MutableList<OutputConfiguration!>)Update the output configurations for this camera session. |
Public constructors
CameraCaptureSession
CameraCaptureSession()
Public methods
abortCaptures
abstract fun abortCaptures(): Unit
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 CaptureCallback.onCaptureCompleted, while others will trigger their CaptureCallback.onCaptureFailed 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 android.hardware.camera2.CameraDevice#createCaptureSession or CameraDevice.createReprocessableCaptureSession, 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 StateCallback.onReady callback will be called, if the session has not been closed. Otherwise, the StateCallback.onClosed 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).
| Exceptions | |
|---|---|
android.hardware.camera2.CameraAccessException |
if the camera device is no longer connected or has encountered a fatal error |
java.lang.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. |
capture
abstract fun capture(
request: CaptureRequest,
listener: CameraCaptureSession.CaptureCallback?,
handler: Handler?
): Int
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 method. The target surfaces (set with CaptureRequest.Builder.addTarget) 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 requests 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 or setRepeatingBurst, 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.
Submitting a request that targets Surfaces with an unsupported dynamic range combination will result in an IllegalArgumentException.
| Parameters | |
|---|---|
request |
CaptureRequest: the settings for this capture. This value cannot be null. |
listener |
CameraCaptureSession.CaptureCallback?: 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 |
Handler?: the handler on which the listener should be invoked, or null to use the current thread's looper. |
| Return | |
|---|---|
Int |
int A unique capture sequence ID used by CaptureCallback.onCaptureSequenceCompleted. |
| Exceptions | |
|---|---|
android.hardware.camera2.CameraAccessException |
if the camera device is no longer connected or has encountered a fatal error |
java.lang.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; or the request targets Surfaces with an unsupported dynamic range combination |
java.lang.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. |
captureBurst
abstract fun captureBurst(
requests: MutableList<CaptureRequest!>,
listener: CameraCaptureSession.CaptureCallback?,
handler: Handler?
): Int
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.
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) must be a subset of the surfaces provided when this capture session was created.
The main difference between this method and simply calling capture 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.
Submitting a request that targets Surfaces with an unsupported dynamic range combination will result in an IllegalArgumentException.
| Parameters | |
|---|---|
requests |
MutableList<CaptureRequest!>: the list of settings for this burst capture. This value cannot be null. |
listener |
CameraCaptureSession.CaptureCallback?: 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 |
Handler?: the handler on which the listener should be invoked, or null to use the current thread's looper. |
| Return | |
|---|---|
Int |
int A unique capture sequence ID used by CaptureCallback.onCaptureSequenceCompleted. |
| Exceptions | |
|---|---|
android.hardware.camera2.CameraAccessException |
if the camera device is no longer connected or has encountered a fatal error |
java.lang.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; or the request targets Surfaces with an unsupported dynamic range combination. |
java.lang.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. |
captureBurstRequests
open fun captureBurstRequests(
requests: MutableList<CaptureRequest!>,
executor: Executor,
listener: CameraCaptureSession.CaptureCallback
): Int
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 behavior of this method matches that of captureBurst(List,CaptureCallback,Handler), except that it uses java.util.concurrent.Executor as an argument instead of android.os.Handler.
| Parameters | |
|---|---|
requests |
MutableList<CaptureRequest!>: the list of settings for this burst capture. This value cannot be null. |
executor |
Executor: the executor which will be used for invoking the listener. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
CameraCaptureSession.CaptureCallback: The callback object to notify each time one of the requests in the burst has been processed. This value cannot be null. |
| Return | |
|---|---|
Int |
int A unique capture sequence ID used by CaptureCallback.onCaptureSequenceCompleted. |
| Exceptions | |
|---|---|
android.hardware.camera2.CameraAccessException |
if the camera device is no longer connected or has encountered a fatal error |
java.lang.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 executor is null; or if the listener is null; or the request targets Surfaces with an unsupported dynamic range combination. |
java.lang.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. |
captureSingleRequest
open fun captureSingleRequest(
request: CaptureRequest,
executor: Executor,
listener: CameraCaptureSession.CaptureCallback
): Int
Submit a request for an image to be captured by the camera device.
The behavior of this method matches that of capture(CaptureRequest,CaptureCallback,Handler), except that it uses java.util.concurrent.Executor as an argument instead of android.os.Handler.
| Parameters | |
|---|---|
request |
CaptureRequest: the settings for this capture. This value cannot be null. |
executor |
Executor: the executor which will be used for invoking the listener. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
CameraCaptureSession.CaptureCallback: The callback object to notify once this request has been processed. This value cannot be null. |
| Return | |
|---|---|
Int |
int A unique capture sequence ID used by CaptureCallback.onCaptureSequenceCompleted. |
| Exceptions | |
|---|---|
android.hardware.camera2.CameraAccessException |
if the camera device is no longer connected or has encountered a fatal error |
java.lang.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 executor is null, or the listener is not null; or the request targets Surfaces with an unsupported dynamic range combination; |
java.lang.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. |
close
abstract fun close(): Unit
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 for common usage scenarios like creating a new session or closing the camera device, it is faster to call respective APIs directly (see below for more details) without calling into this method. This API is only useful when application wants to unconfigure the camera but keep the device open for later use.
Creating a new capture session with android.hardware.camera2.CameraDevice#createCaptureSession will close any existing capture session automatically, and call the older session listener's StateCallback.onClosed callback. Using android.hardware.camera2.CameraDevice#createCaptureSession directly without closing is the recommended approach for quickly switching to a new session, since unchanged target outputs can be reused more efficiently.
Closing the device with CameraDevice.close directly without calling this API is also recommended for quickly closing the camera.
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; o