CameraCaptureSession

CameraCaptureSession

CameraCaptureSession ()

abortCaptures

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 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, CameraCaptureSession.StateCallback, Handler) or createReprocessableCaptureSession(InputConfiguration, List, CameraCaptureSession.StateCallback, 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 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).

capture

int capture (CaptureRequest request, 
                CameraCaptureSession.CaptureCallback listener, 
                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 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.

Requests submitted through this method have higher priority than those submitted through setRepeatingRequest(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler) or setRepeatingBurst(List, CameraCaptureSession.CaptureCallback, 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.

captureBurst

int captureBurst (List<CaptureRequest> requests, 
                CameraCaptureSession.CaptureCallback listener, 
                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.

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.

The main difference between this method and simply calling capture(CaptureRequest, CameraCaptureSession.CaptureCallback, 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.

close

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 createCaptureSession(List, CameraCaptureSession.StateCallback, Handler) will close any existing capture session automatically, and call the older session listener's onClosed(CameraCaptureSession) callback. Using createCaptureSession(List, CameraCaptureSession.StateCallback, 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, onClosed(CameraCaptureSession) will be called.

Closing a session is idempotent; closing more than once has no effect.

getDevice

CameraDevice getDevice ()

Get the camera device that this session is created for.

getInputSurface

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

isReprocessable

boolean isReprocessable ()

Return if the application can submit reprocess capture requests with this camera capture session.

prepare

void prepare (Surface surface)

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

LEGACY devices cannot pre-allocate output buffers; for those devices, onSurfacePrepared(CameraCaptureSession, Surface) will be immediately called, and no preallocation is done.

setRepeatingBurst

int setRepeatingBurst (List<CaptureRequest> requests, 
                CameraCaptureSession.CaptureCallback listener, 
                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 CaptureRequests, at the maximum rate possible.

If a request is submitted through capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler) or captureBurst(List, CameraCaptureSession.CaptureCallback, 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(List, CameraCaptureSession.CaptureCallback, 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(CaptureRequest, CameraCaptureSession.CaptureCallback, 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.

setRepeatingRequest

int setRepeatingRequest (CaptureRequest request, 
                CameraCaptureSession.CaptureCallback listener, 
                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 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.CaptureCallback, Handler).

Repeat requests have lower priority than those submitted through capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler) or captureBurst(List, CameraCaptureSession.CaptureCallback, Handler), so if capture(CaptureRequest, CameraCaptureSession.CaptureCallback, 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, CameraCaptureSession.CaptureCallback, 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.

stopRepeating

void stopRepeating ()

Cancel any ongoing repeating capture set by either setRepeatingRequest or setRepeatingBurst(List, CameraCaptureSession.CaptureCallback, 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 onReady(CameraCaptureSession) callback after calling this method.