Class CaptureSession¶

java.lang.Object
- com.iristick.smartglass.core.camera.CaptureSession

public abstract class CaptureSession
extends Object

A configured capture session for a CameraDevice, used for capturing images from the camera.

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

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.

Capture requests can be submitted as one-shots for capturing still images through capture or captureBurst. Alternatively, a capture request can be submitted as a repeating request through setRepeatingRequest to capture video.

Capture requests must be created through a builder obtained by calling CameraDevice.createCaptureRequest(int) on the camera device to which the request will be submitted. It is not recommended to submit a capture request constructed by another camera.

Nested Class Summary¶

Modifier and Type	Class and Description
`static interface`	`CaptureSession.Listener` Listener interface for receiving updates about the state of a capture session.

Constructor Summary¶

Constructor and Description
`CaptureSession()`

Method Summary¶

Modifier and Type	Method and Description
`abstract void`	`abortCaptures()` Discard all captures currently pending and in-progress as fast as possible.
`int`	`capture(CaptureRequest request, CaptureListener listener, Handler handler)` Submits a request for an image to be captured by the camera.
`abstract int`	`captureBurst(List<CaptureRequest> requests, CaptureListener listener, Handler handler)` Submits a list of requests to be captured in sequence as a burst.
`abstract void`	`close()` Close this capture session asynchronously.
`abstract int`	`setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener, Handler handler)` Requests an endlessly repeating capture of a sequence of images.
`int`	`setRepeatingRequest(CaptureRequest request, CaptureListener listener, Handler handler)` Requests an endlessly repeating capture of images by this camera.
`abstract void`	`stopRepeating()` Cancels any ongoing repeating capture set by `setRepeatingRequest(CaptureRequest, CaptureListener, Handler)`.

Methods inherited from class java.lang.Object ¶

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail¶

CaptureSession¶

public CaptureSession()

Method Detail¶

close¶

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 CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, com.iristick.smartglass.core.camera.CaptureSession.Listener, android.os.Handler) will close any existing capture session automatically, and call the older session listener's CaptureSession.Listener.onClosed(com.iristick.smartglass.core.camera.CaptureSession) callback. Using CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, com.iristick.smartglass.core.camera.CaptureSession.Listener, android.os.Handler) directly without closing is the recommended approach for quickly switching to a new session.

Once a session is closed, any repeating requests 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, CaptureSession.Listener.onClosed(com.iristick.smartglass.core.camera.CaptureSession) will be called.

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

abortCaptures¶

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 CaptureListener.onCaptureCompleted(com.iristick.smartglass.core.camera.CaptureSession, com.iristick.smartglass.core.camera.CaptureRequest, com.iristick.smartglass.core.camera.CaptureResult), while others will trigger their CaptureListener.onCaptureFailed(com.iristick.smartglass.core.camera.CaptureSession, com.iristick.smartglass.core.camera.CaptureRequest, com.iristick.smartglass.core.camera.CaptureFailure) callbacks. If a repeating request is set, it will be cleared.

This method is the fastest way to switch the camera device to a new session with CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, com.iristick.smartglass.core.camera.CaptureSession.Listener, android.os.Handler), at the cost of discarding in-progress work. It must be called before the new session is created.

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

See Also:: setRepeatingRequest(com.iristick.smartglass.core.camera.CaptureRequest, com.iristick.smartglass.core.camera.CaptureListener, android.os.Handler), CameraDevice.createCaptureSession(java.util.List<android.view.Surface>, com.iristick.smartglass.core.camera.CaptureSession.Listener, android.os.Handler)

capture¶

public int capture(@NonNull
                   CaptureRequest request,
                   @Nullable
                   CaptureListener listener,
                   @Nullable
                   Handler handler)

Submits a request for an image to be captured by the camera.

The request defines all the parameters for capturing the single image, including sensor, lens, flash, and post-processing settings.

The request will produce a new frame for one or more target Surfaces, set with the CaptureRequest builder's addTarget method. If a listener is given, the request will also produce one CaptureResult.

Requests submitted through this method have higher priority than those submitted through setRepeatingRequest, and will be processed as soon as the current repeat processing completes.

If the session is closed, the request will be silently ignored.

Parameters:: request - The settings for the requested capture.; listener - The listener to notify once this request has been processed, or null if no notification is needed.; handler - The handler on which the listener should be invoked, or null to use the current thread's looper.
Returns:: A unique capture sequence ID used by CaptureListener.onCaptureSequenceCompleted(com.iristick.smartglass.core.camera.CaptureSession, int, long).
Throws:: IllegalArgumentException - If the request targets no Surfaces.
See Also:: captureBurst(java.util.List<com.iristick.smartglass.core.camera.CaptureRequest>, com.iristick.smartglass.core.camera.CaptureListener, android.os.Handler), setRepeatingRequest(com.iristick.smartglass.core.camera.CaptureRequest, com.iristick.smartglass.core.camera.CaptureListener, android.os.Handler)

captureBurst¶

public abstract int captureBurst(@NonNull
                                 List<CaptureRequest> requests,
                                 @Nullable
                                 CaptureListener listener,
                                 @Nullable
                                 Handler handler)

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

Each request will produce a new frame for one or more target Surfaces, set with the CaptureRequest builder's addTarget method. If a listener is given, each request will also produce one CaptureResult.

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.

If the session is closed, the requests will be silently ignored.

Parameters:: requests - The list of settings for this burst capture.; listener - The listener to notify each time one of the requests in the burst has been processed, or null if no notifications are needed.; handler - The handler on which the listener should be invoked, or null to use the current thread's looper.
Returns:: A unique capture sequence ID used by CaptureListener.onCaptureSequenceCompleted(com.iristick.smartglass.core.camera.CaptureSession, int, long).
Throws:: IllegalArgumentException - If the requests target no Surfaces.
See Also:: capture(com.iristick.smartglass.core.camera.CaptureRequest, com.iristick.smartglass.core.camera.CaptureListener, android.os.Handler), setRepeatingRequest(com.iristick.smartglass.core.camera.CaptureRequest, com.iristick.smartglass.core.camera.CaptureListener, android.os.Handler)

setRepeatingRequest¶

public int setRepeatingRequest(@NonNull
                               CaptureRequest request,
                               @Nullable
                               CaptureListener listener,
                               @Nullable
                               Handler handler)

Requests an endlessly repeating capture of images by this camera.

With this method, the camera 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.

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

Calling this method will replace any earlier repeating request set up by this method, although any in-progress request will be completed before the new repeat request will be used.

If the session is closed, this method has no effect.

Parameters:: request - The request to repeat indefinitely.; listener - The listener to notify once the request has been processed, or null if no notification is needed.; handler - The handler on which the listener should be invoked, or null to use the current thread's looper.
Returns:: A unique capture sequence ID used by CaptureListener.onCaptureSequenceCompleted(com.iristick.smartglass.core.camera.CaptureSession, int, long).
Throws:: IllegalArgumentException - If the request references no Surfaces.
See Also:: capture(CaptureRequest, CaptureListener, Handler), captureBurst(List, CaptureListener, Handler), setRepeatingBurst(List, CaptureListener, Handler)

setRepeatingBurst¶

public abstract int setRepeatingBurst(@NonNull
                                      List<CaptureRequest> requests,
                                      @Nullable
                                      CaptureListener listener,
                                      @Nullable
                                      Handler handler)

Requests an endlessly repeating capture of a sequence of images.

With this method, the camera device will continually capture images, cycling through the settings in the provided list of CaptureRequests.

If a request is submitted through capture or 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 a 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 predictable way, without having to continually submit requests through captureBurst.

To stop the repeating capture, call stopRepeating(). Any ongoing burst will still be completed, however. Calling abortCaptures() will also clear the ongoing request.

Parameters:: requests - The list of settings for this burst capture.; listener - The listener to notify once this request has been processed, or null if no notification is needed.; handler - The handler on which the listener should be invoked, or null to use the current thread's looper.
Returns:: A unique capture sequence ID used by CaptureListener.onCaptureSequenceCompleted(com.iristick.smartglass.core.camera.CaptureSession, int, long).
Throws:: IllegalArgumentException - If the requests target no Surfaces.
See Also:: capture(com.iristick.smartglass.core.camera.CaptureRequest, com.iristick.smartglass.core.camera.CaptureListener, android.os.Handler), captureBurst(java.util.List<com.iristick.smartglass.core.camera.CaptureRequest>, com.iristick.smartglass.core.camera.CaptureListener, android.os.Handler), setRepeatingRequest(com.iristick.smartglass.core.camera.CaptureRequest, com.iristick.smartglass.core.camera.CaptureListener, android.os.Handler)

stopRepeating¶

public abstract void stopRepeating()

Cancels any ongoing repeating capture set by setRepeatingRequest(CaptureRequest, CaptureListener, Handler). Has no effect on requests submitted through capture or captureBurst.

Any currently in-flight captures will still complete.