Camera2InteropEx

Added in 1.7.0-rc01

public final class Camera2InteropEx

Summary

Public methods
static final void
applyCamera2Interop(
    @NonNull CameraControl receiver,
    @NonNull Function1<@NonNull CameraControlCamera2Interop, Unit> block
)

Applies Camera2 options to a CameraControl asynchronously within a coroutine.
static final @NonNull ListenableFuture<@NonNull Void>

Applies Camera2 options to a CameraControl asynchronously.
static final @NonNull ImageCapture.Builder

Applies Camera2 options to an ImageCapture.Builder.
static final void
camera2Interop(
    @NonNull ImageCaptureScope receiver,
    @NonNull Function1<@NonNull ImageCaptureCamera2Interop, Unit> block
)

Applies Camera2 options inside an ImageCaptureScope DSL block.
static final void

Applies Camera2 options inside an InteropConfigurableScope DSL block.
static final @NonNull SessionConfig.Builder

Applies Camera2 options to a SessionConfig.Builder.
static final void
camera2Interop(
    @NonNull SessionConfigScope receiver,
    @NonNull Function1<@NonNull SessionConfigCamera2Interop, Unit> block
)

Applies Camera2 options inside a SessionConfigScope DSL block.
static final @NonNull B
<B extends UseCase.InteropConfigurable<@NonNull B>> camera2Interop(
    @NonNull B receiver,
    @NonNull Function1<@NonNull UseCaseCamera2Interop, Unit> block
)

Applies Camera2 options to a UseCase builder.
static final @NonNull CameraCharacteristics

Returns the CameraCharacteristics from this CameraInfo.
static final @NonNull String

Returns the Camera2 camera ID from this CameraInfo.
static final @NonNull CameraSelector

Creates a CameraSelector targeting this camera ID string.

Public methods

applyCamera2Interop

public static final void applyCamera2Interop(
    @NonNull CameraControl receiver,
    @NonNull Function1<@NonNull CameraControlCamera2Interop, Unit> block
)

Applies Camera2 options to a CameraControl asynchronously within a coroutine.

Dynamically updates repeating capture request parameters or capture request keys on an active camera session. Options configured within a single block are applied atomically in a single repeating capture request update. Subsequent calls to applyCamera2Interop update parameters incrementally without clearing previously set keys, unless explicitly cleared using CameraControlCamera2Interop.clearCaptureRequestOption or CameraControlCamera2Interop.clearAllCaptureRequestOptions. This overwrites options set with SessionConfigCamera2Interop via androidx.camera.core.SessionConfig.Builder.setInterop (or SessionConfig.Builder.camera2Interop).

This function suspends until all specified interoperability options have been successfully updated in the underlying repeating capture request. Throws CameraControl.OperationCanceledException if a newer configuration is applied before this operation takes effect or if the camera is closed.

Options configured via CameraControlCamera2Interop include:

Note: Using Camera2 interop options can override internal CameraX configurations. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior or interfere with 3A routines and camera control APIs.

Warning: Callbacks configured via interop receive raw android.hardware.camera2.CameraCaptureSession instances. Directly invoking state-altering, lifecycle, or request-submitting methods on these raw objects bypasses CameraX pipeline management and causes state desynchronization, stream freezing, or crashes. Do not invoke:

import androidx.camera.camera2.interop.applyCamera2Interop

cameraControl.applyCamera2Interop {
    captureRequest[CaptureRequest.CONTROL_AE_MODE] = CaptureRequest.CONTROL_AE_MODE_OFF
    repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {}
}
Parameters
@NonNull Function1<@NonNull CameraControlCamera2Interop, Unit> block

configuration block setting Camera2 options on CameraControlCamera2Interop
Throws
CameraControl.OperationCanceledException

if a newer configuration is applied before this operation takes effect or if the camera is closed

applyCamera2InteropAsync

public static final @NonNull ListenableFuture<@NonNull Void> applyCamera2InteropAsync(
    @NonNull CameraControl receiver,
    @NonNull Function1<@NonNull CameraControlCamera2Interop, Unit> block
)

Applies Camera2 options to a CameraControl asynchronously.

Dynamically updates repeating capture request parameters or capture request keys on an active camera session. Options configured within a single block are applied atomically in a single repeating capture request update. Subsequent calls to applyCamera2InteropAsync update parameters incrementally without clearing previously set keys, unless explicitly cleared using CameraControlCamera2Interop.clearCaptureRequestOption or CameraControlCamera2Interop.clearAllCaptureRequestOptions. This overwrites options set with SessionConfigCamera2Interop via androidx.camera.core.SessionConfig.Builder.setInterop (or SessionConfig.Builder.camera2Interop).

Options configured via CameraControlCamera2Interop include:

Note: Using Camera2 interop options can override internal CameraX configurations. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior or interfere with 3A routines and camera control APIs.

Warning: Callbacks configured via interop receive raw android.hardware.camera2.CameraCaptureSession instances. Directly invoking state-altering, lifecycle, or request-submitting methods on these raw objects bypasses CameraX pipeline management and causes state desynchronization, stream freezing, or crashes. Do not invoke:

import androidx.camera.camera2.interop.applyCamera2Interop
import androidx.camera.camera2.interop.applyCamera2InteropAsync

cameraControl.applyCamera2InteropAsync {
    captureRequest[CaptureRequest.CONTROL_AE_MODE] = CaptureRequest.CONTROL_AE_MODE_OFF
    repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {}
}
Parameters
@NonNull Function1<@NonNull CameraControlCamera2Interop, Unit> block

configuration block setting Camera2 options on CameraControlCamera2Interop
Returns
@NonNull ListenableFuture<@NonNull Void>

ListenableFuture completing with null when all specified interoperability options have been successfully updated in the underlying repeating capture request. The future fails with CameraControl.OperationCanceledException if a newer configuration is applied before this operation takes effect or if the camera is closed. Cancelling the future is a no-op.

camera2Interop

public static final @NonNull ImageCapture.Builder camera2Interop(
    @NonNull ImageCapture.Builder receiver,
    @NonNull Function1<@NonNull ImageCaptureCamera2Interop, Unit> block
)

Applies Camera2 options to an ImageCapture.Builder.

Configures Camera2 options specific to ImageCapture.Builder.

Options configured via ImageCaptureCamera2Interop include:

Note: Using Camera2 interop options can override internal CameraX configurations. The capture request keys for one-shot still captures (such as androidx.camera.core.ImageCapture.takePicture) are determined by copying all repeating request keys (which may include keys added via androidx.camera.core.SessionConfig.Builder.setInterop or androidx.camera.core.CameraControl.applyInteropAsync) and then overriding them with the still capture request keys configured here. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior.

Warning: Callbacks configured via interop receive raw android.hardware.camera2.CameraCaptureSession instances. Directly invoking state-altering, lifecycle, or request-submitting methods on these raw objects bypasses CameraX pipeline management and causes state desynchronization, stream freezing, or crashes. Do not invoke:

import androidx.camera.camera2.interop.camera2Interop
import androidx.camera.core.ImageCapture
import androidx.camera.core.imageCapture

val imageCapture =
    ImageCapture.Builder()
        .camera2Interop {
            stillCaptureRequestTemplateType = CameraDevice.TEMPLATE_STILL_CAPTURE
            stillCaptureRequest[CaptureRequest.CONTROL_AF_MODE] =
                CaptureRequest.CONTROL_AF_MODE_OFF
            stillCaptureCallback =
                object : CameraCaptureSession.CaptureCallback() {
                    override fun onCaptureCompleted(
                        session: CameraCaptureSession,
                        request: CaptureRequest,
                        result: TotalCaptureResult,
                    ) {}
                }
            physicalCameraId = "5"
        }
        .build()
Parameters
@NonNull Function1<@NonNull ImageCaptureCamera2Interop, Unit> block

configuration block setting Camera2 options on ImageCaptureCamera2Interop
Returns
@NonNull ImageCapture.Builder

this builder

camera2Interop

public static final void camera2Interop(
    @NonNull ImageCaptureScope receiver,
    @NonNull Function1<@NonNull ImageCaptureCamera2Interop, Unit> block
)

Applies Camera2 options inside an ImageCaptureScope DSL block.

Configures Camera2 options on the underlying ImageCapture.Builder within an imageCapture { ... } DSL block.

Options configured via ImageCaptureCamera2Interop include:

Note: Using Camera2 interop options can override internal CameraX configurations. The capture request keys for one-shot still captures (such as androidx.camera.core.ImageCapture.takePicture) are determined by copying all repeating request keys (which may include keys added via androidx.camera.core.SessionConfig.Builder.setInterop or androidx.camera.core.CameraControl.applyInteropAsync) and then overriding them with the still capture request keys configured here. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior.

Warning: Callbacks configured via interop receive raw android.hardware.camera2.CameraCaptureSession instances. Directly invoking state-altering, lifecycle, or request-submitting methods on these raw objects bypasses CameraX pipeline management and causes state desynchronization, stream freezing, or crashes. Do not invoke:

import androidx.camera.camera2.interop.camera2Interop
import androidx.camera.core.imageCapture

val imageCapture = imageCapture {
    camera2Interop {
        stillCaptureRequestTemplateType = CameraDevice.TEMPLATE_PREVIEW
        stillCaptureRequest[CaptureRequest.CONTROL_AF_MODE] = CaptureRequest.CONTROL_AF_MODE_OFF
        stillCaptureCallback =
            object : CameraCaptureSession.CaptureCallback() {
                override fun onCaptureCompleted(
                    session: CameraCaptureSession,
                    request: CaptureRequest,
                    result: TotalCaptureResult,
                ) {}
            }
        physicalCameraId = "5"
    }
}
Parameters
@NonNull Function1<@NonNull ImageCaptureCamera2Interop, Unit> block

configuration block setting Camera2 options on ImageCaptureCamera2Interop

camera2Interop

public static final void <B extends UseCase.InteropConfigurable<@NonNull B>> camera2Interop(
    @NonNull InteropConfigurableScope<@NonNull B> receiver,
    @NonNull Function1<@NonNull UseCaseCamera2Interop, Unit> block
)

Applies Camera2 options inside an InteropConfigurableScope DSL block.

Configures Camera2 options on the underlying UseCase builder within Kotlin DSL blocks such as preview { ... }, imageAnalysis { ... }, or videoCapture { ... }. For imageCapture { ... }, use the dedicated ImageCaptureScope.camera2Interop extension function.

Options configured via UseCaseCamera2Interop include:

Note: Using Camera2 interop options can override internal CameraX configurations. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior.

import androidx.camera.camera2.interop.camera2Interop
import androidx.camera.core.preview

val preview = preview {
    camera2Interop {
        physicalCameraId = "0"
        mirrorMode = OutputConfiguration.MIRROR_MODE_H
    }
}
Parameters
@NonNull Function1<@NonNull UseCaseCamera2Interop, Unit> block

configuration block setting Camera2 options on UseCaseCamera2Interop

camera2Interop

public static final @NonNull SessionConfig.Builder camera2Interop(
    @NonNull SessionConfig.Builder receiver,
    @NonNull Function1<@NonNull SessionConfigCamera2Interop, Unit> block
)

Applies Camera2 options to a SessionConfig.Builder.

Configures Camera2 options for a capture session builder. Can be called on a SessionConfig.Builder directly or within a androidx.camera.core.sessionConfig DSL block.

Options configured via SessionConfigCamera2Interop include:

Note: Using Camera2 interop options can override internal CameraX configurations. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior.

Warning: Callbacks configured via interop receive raw android.hardware.camera2.CameraDevice and android.hardware.camera2.CameraCaptureSession instances. Directly invoking state-altering, lifecycle, or request-submitting methods on these raw objects bypasses CameraX pipeline management and causes state desynchronization, stream freezing, or crashes. Do not invoke:

import androidx.camera.camera2.interop.camera2Interop
import androidx.camera.core.SessionConfig
import androidx.camera.core.preview
import androidx.camera.core.sessionConfig

val sessionConfig =
    SessionConfig.Builder(preview)
        .camera2Interop {
            colorSpace = ColorSpace.Named.DISPLAY_P3
            sessionParameter[CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE] = Range(60, 60)
            captureRequest[CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE] = Range(60, 60)
            repeatingCaptureRequestTemplate = CameraDevice.TEMPLATE_PREVIEW
            repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {}
        }
        .build()
 
import androidx.camera.camera2.interop.camera2Interop
import androidx.camera.core.preview
import androidx.camera.core.sessionConfig

val sessionConfig =
    sessionConfig(listOf(preview)) {
        camera2Interop {
            colorSpace = ColorSpace.Named.DISPLAY_P3
            sessionParameter[CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE] = Range(60, 60)
            captureRequest[CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE] = Range(60, 60)
            repeatingCaptureRequestTemplate = CameraDevice.TEMPLATE_PREVIEW
            repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {}
        }
    }
Parameters
@NonNull Function1<@NonNull SessionConfigCamera2Interop, Unit> block

configuration block setting Camera2 options on SessionConfigCamera2Interop
Returns
@NonNull SessionConfig.Builder

this builder

camera2Interop

public static final void camera2Interop(
    @NonNull SessionConfigScope receiver,
    @NonNull Function1<@NonNull SessionConfigCamera2Interop, Unit> block
)

Applies Camera2 options inside a SessionConfigScope DSL block.

Configures Camera2 options on the underlying SessionConfig.Builder within a sessionConfig { ... } DSL block.

import androidx.camera.camera2.interop.camera2Interop
import androidx.camera.core.preview
import androidx.camera.core.sessionConfig

val sessionConfig =
    sessionConfig(listOf(preview)) {
        camera2Interop {
            colorSpace = ColorSpace.Named.DISPLAY_P3
            sessionParameter[CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE] = Range(60, 60)
            captureRequest[CaptureRequest.CONTROL_AE_TARGET_FPS_RANGE] = Range(60, 60)
            repeatingCaptureRequestTemplate = CameraDevice.TEMPLATE_PREVIEW
            repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {}
        }
    }
Parameters
@NonNull Function1<@NonNull SessionConfigCamera2Interop, Unit> block

configuration block setting Camera2 options on SessionConfigCamera2Interop

camera2Interop

public static final @NonNull B <B extends UseCase.InteropConfigurable<@NonNull B>> camera2Interop(
    @NonNull B receiver,
    @NonNull Function1<@NonNull UseCaseCamera2Interop, Unit> block
)

Applies Camera2 options to a UseCase builder.

Configures Camera2 options on builders implementing UseCase.InteropConfigurable (such as androidx.camera.core.Preview.Builder, androidx.camera.core.ImageAnalysis.Builder, or androidx.camera.video.VideoCapture.Builder). For ImageCapture.Builder, use the dedicated ImageCapture.Builder.camera2Interop extension function.

Options configured via UseCaseCamera2Interop include:

Note: Using Camera2 interop options can override internal CameraX configurations. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior.

import androidx.camera.camera2.interop.camera2Interop
import androidx.camera.core.Preview
import androidx.camera.core.preview

val preview =
    Preview.Builder()
        .camera2Interop {
            physicalCameraId = "5"
            mirrorMode = OutputConfiguration.MIRROR_MODE_H
        }
        .build()
Parameters
@NonNull Function1<@NonNull UseCaseCamera2Interop, Unit> block

configuration block setting Camera2 options on UseCaseCamera2Interop
Returns
@NonNull B

this builder

getCameraCharacteristics

public static final @NonNull CameraCharacteristics getCameraCharacteristics(@NonNull CameraInfo receiver)

Returns the CameraCharacteristics from this CameraInfo.

Throws
IllegalArgumentException

if this CameraInfo does not contain Camera2 information

getCameraId

public static final @NonNull String getCameraId(@NonNull CameraInfo receiver)

Returns the Camera2 camera ID from this CameraInfo.

Throws
IllegalArgumentException

if this CameraInfo does not contain Camera2 information

toCameraSelector

public static final @NonNull CameraSelector toCameraSelector(@NonNull String receiver)

Creates a CameraSelector targeting this camera ID string.

Returns
@NonNull CameraSelector

CameraSelector matching this camera ID