CameraCaptureSessionpublic abstract class CameraCaptureSession extends Object implements AutoCloseable| A configured capture session for a {@link CameraDevice}, used for capturing
images from the camera.
A CameraCaptureSession is created by providing a set of target output surfaces to
{@link CameraDevice#createCaptureSession 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
{@link CameraDevice#createCaptureSession createCaptureSession} will send the ready-to-use
CameraCaptureSession to the provided listener's
{@link CameraCaptureSession.StateCallback#onConfigured onConfigured} callback. If configuration
cannot be completed, then the
{@link CameraCaptureSession.StateCallback#onConfigureFailed 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 {@link StateCallback#onClosed 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 {@link #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. |
| Methods Summary |
|---|
| public abstract void | abortCaptures()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 {@link CaptureCallback#onCaptureCompleted}, while
others will trigger their {@link 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
{@link CameraDevice#createCaptureSession}, 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 {@link StateCallback#onReady} callback will be called,
if the session has not been closed. Otherwise, the {@link 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 {@code 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).
| | public abstract int | capture(CaptureRequest request, android.hardware.camera2.CameraCaptureSession$CaptureCallback listener, android.os.Handler handler)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 {@link CaptureResult} and produce new frames for one or more
target Surfaces, set with the CaptureRequest builder's
{@link CaptureRequest.Builder#addTarget} method. The target surfaces (set with
{@link CaptureRequest.Builder#addTarget}) 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 {@link #setRepeatingRequest} or
{@link #setRepeatingBurst}, and will be processed as soon as the current
repeat/repeatBurst processing completes.
| | public abstract int | captureBurst(java.util.List requests, android.hardware.camera2.CameraCaptureSession$CaptureCallback listener, android.os.Handler handler)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 {@link CaptureResult}
and image buffers for one or more target {@link android.view.Surface surfaces}. The target
surfaces (set with {@link 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
{@link #capture} repeatedly is that this method guarantees that no
other requests will be interspersed with the burst.
| | public abstract void | close()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 {@link CameraDevice#createCaptureSession}
will close any existing capture session automatically, and call the older session listener's
{@link StateCallback#onClosed} callback. Using {@link 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.
Once a session is closed, all methods on it will throw an IllegalStateException, and any
repeating requests or bursts are stopped (as if {@link #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,
{@link StateCallback#onClosed} will be called.
Closing a session is idempotent; closing more than once has no effect.
| | public abstract CameraDevice | getDevice()Get the camera device that this session is created for.
| | public abstract int | setRepeatingBurst(java.util.List requests, android.hardware.camera2.CameraCaptureSession$CaptureCallback listener, android.os.Handler handler)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
{@link CaptureRequest CaptureRequests}, at the maximum rate possible.
If a request is submitted through {@link #capture} or
{@link #captureBurst}, 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 {@link #captureBurst}.
To stop the repeating capture, call {@link #stopRepeating}. Any
ongoing burst will still be completed, however. Calling
{@link #abortCaptures} will also clear the request.
Calling this method will replace a previously-set repeating request or
burst set up by this method or {@link #setRepeatingRequest}, although any
in-progress burst will be completed before the new repeat burst will be
used.
| | public abstract int | setRepeatingRequest(CaptureRequest request, android.hardware.camera2.CameraCaptureSession$CaptureCallback listener, android.os.Handler handler)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 {@link 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 {@link #capture}.
Repeat requests have lower priority than those submitted
through {@link #capture} or {@link #captureBurst}, so if
{@link #capture} 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 {@link #stopRepeating}. Calling
{@link #abortCaptures} will also clear the request.
Calling this method will replace any earlier repeating request or
burst set up by this method or {@link #setRepeatingBurst}, although any
in-progress burst will be completed before the new repeat request will be
used.
| | public abstract void | stopRepeating()Cancel any ongoing repeating capture set by either
{@link #setRepeatingRequest setRepeatingRequest} or
{@link #setRepeatingBurst}. Has no effect on requests submitted through
{@link #capture capture} or {@link #captureBurst 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 {@link StateCallback#onReady} callback after
calling this method.
|
|
