CameraExtensionSession
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
.
Summary
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. |
class |
CameraExtensionSession.StillCaptureLatency
Realtime calculated still |
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. |
CameraExtensionSession.StillCaptureLatency
|
getRealtimeStillCaptureLatency()
Return the realtime still |
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 methods
capture
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 controls advertised in
CameraExtensionCharacteristics#getAvailableCaptureRequestKeys
.
The rest of the settings included in the request will be entirely overridden by
the device-specific extension.
If CameraExtensionCharacteristics#isPostviewAvailable
returns
false, the CaptureRequest.Builder#addTarget
will support only one
ImageFormat.YUV_420_888 or ImageFormat.JPEG target surface. CaptureRequest
arguments that include further targets will cause IllegalArgumentException to be thrown.
If postview is available, CaptureRequest.Builder#addTarget
will support up to two
ImageFormat.YUV_420_888 or ImageFormat.JPEG target surfaces for the still capture and
postview. IllegalArgumentException will be thrown if a postview target is added without
a still capture target, if more than two target surfaces are added, or if the surface
formats for postview and capture are not equivalent.
Starting with Android Build.VERSION_CODES.TIRAMISU
single capture
requests will also support the preview ImageFormat.PRIVATE
target
surface. These can typically be used for enabling AF/AE triggers. Do note, that single
capture requests referencing both output surfaces remain unsupported.
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, 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. |
close
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 |
getDevice
public CameraDevice getDevice ()
Get the camera device that this session is created for.
Returns | |
---|---|
CameraDevice |
This value cannot be null . |
getRealtimeStillCaptureLatency
public CameraExtensionSession.StillCaptureLatency getRealtimeStillCaptureLatency ()
Return the realtime still capture(CaptureRequest, Executor, ExtensionCaptureCallback)
latency.
The estimations will take into account the current environment conditions, the camera state and will include the time spent processing the multi-frame capture request along with any additional time for encoding of the processed buffer if necessary.
Returns | |
---|---|
CameraExtensionSession.StillCaptureLatency |
The realtime still capture latency,
or null if the estimation is not supported. |
Throws | |
---|---|
CameraAccessException |
setRepeatingRequest
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 except for controls advertised in
CameraExtensionCharacteristics#getAvailableCaptureRequestKeys
.
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
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, ExtensionCaptureCallback)
, so if capture(CaptureRequest, Executor, 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. |
stopRepeating
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. |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-04 UTC.