# Print output for @column tags ?>
public
abstract
class
CameraExtensionSession
extends Object
implements
AutoCloseable
java.lang.Object | |
↳ | android.hardware.camera2.CameraExtensionSession |
A camera capture session that enables access to device-specific camera extensions, which often use multi-frame bursts and sophisticated post-process algorithms for image capture.
The capture session will be returned after a successful call to
CameraDevice#createExtensionSession
as part of the argument
in the registered state callback StateCallback#onConfigured
method.
Note that CameraExtensionSession is currently limited to a maximum of two output surfaces for continuous repeating and multi-frame processing respectively. Some features such as capture settings will not be supported as the device-specific Extension is allowed to override all capture parameters.
Information about support for specific device-specific extensions can be queried
from CameraExtensionCharacteristics
.
Nested classes | |
---|---|
class |
CameraExtensionSession.ExtensionCaptureCallback
A callback object for tracking the progress of a
|
class |
CameraExtensionSession.StateCallback
A callback object for receiving updates about the state of a camera extension session. |
Public methods | |
---|---|
int
|
capture(CaptureRequest request, Executor executor, CameraExtensionSession.ExtensionCaptureCallback listener)
Submit a request for device-specific processing using input from the camera device, to produce a single high-quality output result. |
void
|
close()
Close this capture session asynchronously. |
CameraDevice
|
getDevice()
Get the camera device that this session is created for. |
int
|
setRepeatingRequest(CaptureRequest request, Executor executor, CameraExtensionSession.ExtensionCaptureCallback listener)
Request endlessly repeating device-specific extension processing of camera images. |
void
|
stopRepeating()
Cancel any ongoing repeating capture set by
|
Inherited methods | |
---|---|
public int capture (CaptureRequest request, Executor executor, CameraExtensionSession.ExtensionCaptureCallback listener)
Submit a request for device-specific processing using input from the camera device, to produce a single high-quality output result.
Note that single capture requests currently do not support
client parameters except for orientation
and
quality
in case of ImageFormat.JPEG output target.
The rest of the settings included in the request will be entirely overridden by
the device-specific extension.
The CaptureRequest.Builder#addTarget
supports only one
ImageFormat.YUV_420_888 or ImageFormat.JPEG target surface. CaptureRequest
arguments that include further targets will cause
IllegalArgumentException to be thrown.
Each request will produce one new frame for one target Surface, set
with the CaptureRequest builder's
CaptureRequest.Builder#addTarget
method.
Multiple requests can be in progress at once. Requests are processed in first-in, first-out order.
Requests submitted through this method have higher priority than
those submitted through setRepeatingRequest(CaptureRequest, Executor, CameraExtensionSession.ExtensionCaptureCallback)
, and will be
processed as soon as the current repeat processing completes.
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 . |
listener |
CameraExtensionSession.ExtensionCaptureCallback : The callback object to notify once this request has
been processed.
This value cannot be null . |
Returns | |
---|---|
int |
int A unique capture sequence ID used by
ExtensionCaptureCallback#onCaptureSequenceCompleted . |
Throws | |
---|---|
CameraAccessException |
if the camera device is no longer connected or has encountered a fatal error |
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. |
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. |
public 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(SessionConfiguration)
or
CameraDevice.createExtensionSession(ExtensionSessionConfiguration)
will close any existing capture session automatically, and call the
older session listener's StateCallback#onClosed
callback.
Using
CameraDevice.createCaptureSession(SessionConfiguration)
or
CameraDevice.createExtensionSession(ExtensionSessionConfiguration)
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 are
stopped (as if stopRepeating()
was called).
Closing a session is idempotent; closing more than once has no effect.
Throws | |
---|---|
CameraAccessException |
public CameraDevice getDevice ()
Get the camera device that this session is created for.
Returns | |
---|---|
CameraDevice |
This value cannot be null . |
public int setRepeatingRequest (CaptureRequest request, Executor executor, CameraExtensionSession.ExtensionCaptureCallback listener)
Request endlessly repeating device-specific extension processing of camera images.
With this method, the camera device will continually capture images and process them using the device-specific extension at the maximum rate possible.
Note that repeating capture requests currently do not support client parameters. Settings included in the request will be completely overridden by the device-specific extension.
The CaptureRequest.Builder#addTarget
supports only one
target surface. CaptureRequest
arguments that include further
targets will cause IllegalArgumentException to be thrown.
Repeating requests are a simple way for an application to maintain a preview or other continuous stream of frames.
Repeat requests have lower priority than those submitted
through capture(CaptureRequest, Executor, CameraExtensionSession.ExtensionCaptureCallback)
, so if capture(CaptureRequest, Executor, CameraExtensionSession.ExtensionCaptureCallback)
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.
Parameters | |
---|---|
request |
CaptureRequest : the request to repeat indefinitely
This value cannot be null . |
executor |
Executor : the executor which will be used for invoking the
listener.
This value cannot be null . |
listener |
CameraExtensionSession.ExtensionCaptureCallback : The callback object to notify every time the
request finishes processing.
This value cannot be null . |
Returns | |
---|---|
int |
int A unique capture sequence ID used by
ExtensionCaptureCallback#onCaptureSequenceCompleted . |
Throws | |
---|---|
CameraAccessException |
if the camera device is no longer connected or has encountered a fatal error |
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. |
IllegalArgumentException |
If the request references no Surfaces or references Surfaces that are not currently configured as outputs. |
public void stopRepeating ()
Cancel any ongoing repeating capture set by
setRepeatingRequest
. Has no effect on
requests submitted through capture
.
Any currently in-flight captures will still complete.
Throws | |
---|---|
CameraAccessException |
if the camera device is no longer connected or has encountered a fatal error |
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. |