Added in [API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#nestedclasses) \| [Methods](https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#inhmethods)

# CameraExtensionSession

*** ** * ** ***

` public abstract class CameraExtensionSession `   
` extends https://developer.android.com/reference/java/lang/Object ` ` implements https://developer.android.com/reference/java/lang/AutoCloseable `

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.hardware.camera2.CameraExtensionSession |

<br />

*** ** * ** ***

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 `https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createExtensionSession(android.hardware.camera2.params.ExtensionSessionConfiguration)` as part of the argument in the registered state callback `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.StateCallback#onConfigured(android.hardware.camera2.CameraExtensionSession)` 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 `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionCharacteristics`.

<br />

## Summary

| ### Nested classes ||
|---|---|
| ` class` | `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.ExtensionCaptureCallback` A callback object for tracking the progress of a `https://developer.android.com/reference/android/hardware/camera2/CaptureRequest` submitted to the camera device. |
| ` class` | `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.StateCallback` A callback object for receiving updates about the state of a camera extension session. |
| ` class` | `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.StillCaptureLatency` Realtime calculated still `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#capture(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)` latency. |

| ### Public methods ||
|---|---|
| ` int` | ` https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#capture(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)(https://developer.android.com/reference/android/hardware/camera2/CaptureRequest request, https://developer.android.com/reference/java/util/concurrent/Executor executor, https://developer.android.com/reference/android/hardware/camera2/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` | ` https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#close()() ` Close this capture session asynchronously. |
| ` https://developer.android.com/reference/android/hardware/camera2/CameraDevice` | ` https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#getDevice()() ` Get the camera device that this session is created for. |
| ` https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.StillCaptureLatency` | ` https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#getRealtimeStillCaptureLatency()() ` Return the realtime still `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#capture(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)` latency. |
| ` int` | ` https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#setRepeatingRequest(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)(https://developer.android.com/reference/android/hardware/camera2/CaptureRequest request, https://developer.android.com/reference/java/util/concurrent/Executor executor, https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.ExtensionCaptureCallback listener) ` Request endlessly repeating device-specific extension processing of camera images. |
| ` void` | ` https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#stopRepeating()() ` Cancel any ongoing repeating capture set by `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#setRepeatingRequest(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)`. |

### Inherited methods

From class ` https://developer.android.com/reference/java/lang/Object ` ` https://developer.android.com/reference/java/lang/Object` ` https://developer.android.com/reference/java/lang/Object#clone()() `

Creates and returns a copy of this object.
` boolean` ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) `

Indicates whether some other object is "equal to" this one.
` void` ` https://developer.android.com/reference/java/lang/Object#finalize()() `

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
` final https://developer.android.com/reference/java/lang/Class<?>` ` https://developer.android.com/reference/java/lang/Object#getClass()() `

Returns the runtime class of this `Object`.
` int` ` https://developer.android.com/reference/java/lang/Object#hashCode()() `

Returns a hash code value for the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#notify()() `

Wakes up a single thread that is waiting on this object's monitor.
` final void` ` https://developer.android.com/reference/java/lang/Object#notifyAll()() `

Wakes up all threads that are waiting on this object's monitor.
` https://developer.android.com/reference/java/lang/String` ` https://developer.android.com/reference/java/lang/Object#toString()() `

Returns a string representation of the object.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) `

Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) `

Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed.
` final void` ` https://developer.android.com/reference/java/lang/Object#wait()() `

Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*.
From interface ` https://developer.android.com/reference/java/lang/AutoCloseable ` ` abstract void` ` https://developer.android.com/reference/java/lang/AutoCloseable#close()() `

Closes this resource, relinquishing any underlying resources.

## Public methods

### capture

Added in [API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionCharacteristics#getAvailableCaptureRequestKeys(int)`. The rest of the settings included in the request will be entirely overridden by the device-specific extension.

If `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionCharacteristics#isPostviewAvailable(int)` returns false, the `https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#addTarget(android.view.Surface)` will support only one ImageFormat.YUV_420_888 or ImageFormat.JPEG target surface. `https://developer.android.com/reference/android/hardware/camera2/CaptureRequest` arguments that include further targets will cause IllegalArgumentException to be thrown. If postview is available, `https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#addTarget(android.view.Surface)` 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 `https://developer.android.com/reference/android/os/Build.VERSION_CODES#TIRAMISU` single capture requests will also support the preview `https://developer.android.com/reference/android/graphics/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 `https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#addTarget(android.view.Surface)` 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 `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#setRepeatingRequest(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)`, and will be processed as soon as the current repeat processing completes.

<br />

<br />

| Parameters ||
|---|---|
| `request` | `CaptureRequest`: the settings for this capture. This value cannot be `null`. <br /> |
| `executor` | `Executor`: the executor which will be used for invoking the listener. This value cannot be `null`. <br /> |
| `listener` | `CameraExtensionSession.ExtensionCaptureCallback`: The callback object to notify once this request has been processed. This value cannot be `null`. <br /> |

| Returns ||
|---|---|
| `int` | int A unique capture sequence ID used by `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.ExtensionCaptureCallback#onCaptureSequenceCompleted(android.hardware.camera2.CameraExtensionSession,%20int)`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/hardware/camera2/CameraAccessException` | if the camera device is no longer connected or has encountered a fatal error |
| `https://developer.android.com/reference/java/lang/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. |
| `https://developer.android.com/reference/java/lang/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. |

### close

Added in [API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 `https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createCaptureSession(android.hardware.camera2.params.SessionConfiguration)` or `https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createExtensionSession(android.hardware.camera2.params.ExtensionSessionConfiguration)` will close any existing capture session automatically, and call the older session listener's `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.StateCallback#onClosed(android.hardware.camera2.CameraExtensionSession)` callback. Using `https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createCaptureSession(android.hardware.camera2.params.SessionConfiguration)` or `https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createExtensionSession(android.hardware.camera2.params.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 `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#stopRepeating()` was called).

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

<br />

<br />

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/hardware/camera2/CameraAccessException` |   |

### getDevice

Added in [API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public CameraDevice getDevice ()
```

Get the camera device that this session is created for.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/hardware/camera2/CameraDevice` | This value cannot be `null`. <br /> |

### getRealtimeStillCaptureLatency

Added in [API level 34](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public CameraExtensionSession.StillCaptureLatency getRealtimeStillCaptureLatency ()
```

Return the realtime still `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#capture(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.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.

<br />

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.StillCaptureLatency` | The realtime still capture latency, or `null` if the estimation is not supported. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/hardware/camera2/CameraAccessException` |   |

### setRepeatingRequest

Added in [API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
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 `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionCharacteristics#getAvailableCaptureRequestKeys(int)`. The rest of the settings included in the request will be entirely overridden by the device-specific extension.

The `https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#addTarget(android.view.Surface)` supports only one target surface. `https://developer.android.com/reference/android/hardware/camera2/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 `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#capture(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)`, so if `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#capture(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.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 `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#stopRepeating()`.

Calling this method will replace any earlier repeating request.

<br />

<br />

| Parameters ||
|---|---|
| `request` | `CaptureRequest`: the request to repeat indefinitely. This value cannot be `null`. <br /> |
| `executor` | `Executor`: the executor which will be used for invoking the listener. This value cannot be `null`. <br /> |
| `listener` | `CameraExtensionSession.ExtensionCaptureCallback`: The callback object to notify every time the request finishes processing. This value cannot be `null`. <br /> |

| Returns ||
|---|---|
| `int` | int A unique capture sequence ID used by `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession.ExtensionCaptureCallback#onCaptureSequenceCompleted(android.hardware.camera2.CameraExtensionSession,%20int)`. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/hardware/camera2/CameraAccessException` | if the camera device is no longer connected or has encountered a fatal error |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException` | If the request references no Surfaces or references Surfaces that are not currently configured as outputs. |
| `https://developer.android.com/reference/java/lang/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. |

**See also:**

- `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#capture(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)`

### stopRepeating

Added in [API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public void stopRepeating ()
```

Cancel any ongoing repeating capture set by `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#setRepeatingRequest(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)`. Has no effect on requests submitted through `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#capture(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)`.

Any currently in-flight captures will still complete.

<br />

<br />

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/hardware/camera2/CameraAccessException` | if the camera device is no longer connected or has encountered a fatal error |
| `https://developer.android.com/reference/java/lang/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. |

**See also:**

- `https://developer.android.com/reference/android/hardware/camera2/CameraExtensionSession#setRepeatingRequest(android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback)`