A constrained high speed capture session for a CameraDevice, used for capturing high
speed images from the CameraDevice for high speed video recording use case.

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
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.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

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).

capture

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 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.

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.

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

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
addTarget(Surface)) must be a subset of the surfaces provided when
this capture session was created.

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.

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.

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.

finalizeOutputConfigurations

Finalize the output configurations that now have their deferred and/or extra Surfaces
included.

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. For example, if the
preview Surface is obtained from SurfaceView, the SurfaceView will only
be ready after the UI layout is done, potentially delaying camera startup.

To speed up camera startup time, the application can configure the
CameraCaptureSession with the eventual preview size (via
a deferred OutputConfiguration),
and defer the preview output configuration until the Surface is ready. After the
CameraCaptureSession is created successfully with this deferred output and other
normal outputs, the application can start submitting requests as long as they do not include
deferred output Surfaces. Once a deferred Surface is ready, the application can add the
Surface to the deferred output configuration with the
addSurface(Surface) method, and then update the deferred output
configuration via this method, before it can submit capture requests with this output
target.

This function can also be called in case where multiple surfaces share the same
OutputConfiguration, and one of the surfaces becomes available after the CameraCaptureSession is created. In that case, the application must first create the
OutputConfiguration with the available Surface, then enable furture surface sharing via
enableSurfaceSharing(), before creating the CameraCaptureSession.
After the CameraCaptureSession is created, and once the extra Surface becomes available, the
application must then call addSurface(Surface) before finalizing the
configuration with this method.

If the provided OutputConfigurations are unchanged from session creation, this function
call has no effect. This function must only be called once for a particular output
configuration.

for invalid output configurations, including ones where the
source of the Surface is no longer valid or the Surface is from a unsupported
source. Or if one of the output configuration was already finished with an
included surface in a prior call.

getInputSurface

Get the input Surface associated with a reprocessable capture session.

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.

prepare

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, onSurfacePrepared(CameraCaptureSession, 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.

Note that if 2 surfaces share the same stream via enableSurfaceSharing() and addSurface(Surface),
prepare() only needs to be called on one surface, and {link
StateCallback#onSurfacePrepared} will be triggered for both surfaces.

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.

Parameters

requests

List: the list of requests to cycle through indefinitely

This value must never be null.

listener

CameraCaptureSession.CaptureCallback: 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

Handler: the handler on which the listener should be invoked, or
null to use the current thread's looper.

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.

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.

Parameters

request

CaptureRequest: the request to repeat indefinitely

This value must never be null.

listener

CameraCaptureSession.CaptureCallback: 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

Handler: the handler on which the listener should be invoked, or
null to use the current thread's looper.

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.

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.