CameraController

Added in 1.1.0

Kotlin |Java

abstract class CameraController

Known direct subclasses

LifecycleCameraController

LifecycleCameraController

A controller that provides most of the CameraX features.

The abstract base camera controller class.

This a high level controller that provides most of the CameraX core features in a single class. It handles camera initialization, creates and configures UseCases. It also listens to device motion sensor and set the target rotation for the use cases.

The controller is required to be used with a PreviewView. PreviewView provides the UI elements to display camera preview. The layout of the PreviewView is used to set the crop rect so the output from other use cases matches the preview display in a WYSIWYG way. The controller also listens to PreviewView's touch events to handle tap-to-focus and pinch-to-zoom features.

This class provides features of 4 UseCases: Preview, ImageCapture, ImageAnalysis and VideoCapture. Preview is required and always enabled. ImageCapture and ImageAnalysis are enabled by default. The video capture is disabled by default because it might affect other use cases, especially on lower end devices. It might be necessary to disable ImageCapture and/or ImageAnalysis before the video capture feature can be enabled. Disabling/enabling UseCases freezes the preview for a short period of time. To avoid the glitch, the UseCases need to be enabled/disabled before the controller is set on PreviewView.

Summary

Nested types
`class CameraController.OutputSize` This class is deprecated. Use `ResolutionSelector` instead.

Nested types

class CameraController.OutputSize

This class is deprecated.

Use ResolutionSelector instead.

Constants
`const Int`	`COORDINATE_SYSTEM_VIEW_REFERENCED = 1` This property is deprecated. Use `COORDINATE_SYSTEM_VIEW_REFERENCED` instead.
`const Int`	`IMAGE_ANALYSIS = 2` Bitmask option to enable `ImageAnalysis`.
`const Int`	`IMAGE_CAPTURE = 1` Bitmask option to enable `ImageCapture`.
`const Int`	`TAP_TO_FOCUS_FAILED = 4` The previous tap-to-focus action was failed to complete.
`const Int`	`TAP_TO_FOCUS_FOCUSED = 2` The previous tap-to-focus action was completed successfully and the camera is focused.
`const Int`	`TAP_TO_FOCUS_NOT_FOCUSED = 3` The previous tap-to-focus action was completed successfully but the camera is still unfocused, similar to the `CONTROL_AF_STATE_NOT_FOCUSED_LOCKED` state.
`const Int`	`TAP_TO_FOCUS_NOT_STARTED = 0` No tap-to-focus action has been started by the end user.
`const Int`	`TAP_TO_FOCUS_STARTED = 1` A tap-to-focus action has started but not completed.
`const Int`	`VIDEO_CAPTURE = 4` Bitmask option to enable video capture use case.

Public functions
`Unit`	`@MainThread clearEffects()` Removes all effects.
`Unit`	`@MainThread clearImageAnalysisAnalyzer()` Removes a previously set analyzer.
`ListenableFuture<Void!>`	`@MainThread enableTorch(torchEnabled: Boolean)` Enable the torch or disable the torch.
`CameraControl?`	`@MainThread getCameraControl()` Gets the `CameraControl` of the currently attached camera.
`CameraInfo?`	`@MainThread getCameraInfo()` Gets the `CameraInfo` of the currently attached camera.
`CameraSelector`	`@MainThread getCameraSelector()` Gets the `CameraSelector`.
`Executor?`	`@MainThread getImageAnalysisBackgroundExecutor()` Gets the default executor for `ImageAnalysis` background tasks.
`Int`	`@MainThread getImageAnalysisBackpressureStrategy()` Returns the mode with which images are acquired.
`Int`	`@MainThread getImageAnalysisImageQueueDepth()` Gets the image queue depth of `ImageAnalysis`.
`Int`	`@MainThread getImageAnalysisOutputImageFormat()` Gets the output image format for `ImageAnalysis`.
`ResolutionSelector?`	`@MainThread getImageAnalysisResolutionSelector()` Returns the `ResolutionSelector` for `ImageAnalysis`.
`CameraController.OutputSize?`	`@MainThread getImageAnalysisTargetSize()` This function is deprecated. Use `getImageAnalysisResolutionSelector` instead.
`Int`	`@MainThread getImageCaptureFlashMode()` Gets the flash mode for `ImageCapture`.
`Executor?`	`@MainThread getImageCaptureIoExecutor()` Gets the default executor for `ImageCapture` IO tasks.
`Int`	`@MainThread getImageCaptureMode()` Returns the image capture mode.
`ResolutionSelector?`	`@MainThread getImageCaptureResolutionSelector()` Returns the `ResolutionSelector` for `ImageCapture`.
`CameraController.OutputSize?`	`@MainThread getImageCaptureTargetSize()` This function is deprecated. Use `getImageCaptureResolutionSelector` instead.
`ListenableFuture<Void!>`	`getInitializationFuture()` Gets a `ListenableFuture` that completes when camera initialization completes.
`ResolutionSelector?`	`@MainThread getPreviewResolutionSelector()` Returns the `ResolutionSelector` for `Preview`.
`CameraController.OutputSize?`	`@MainThread getPreviewTargetSize()` This function is deprecated. Use `getPreviewResolutionSelector` instead.
`LiveData<Int!>`	`@MainThread getTapToFocusState()` Returns a `LiveData` with the latest tap-to-focus state.
`LiveData<Int!>`	`@MainThread getTorchState()` Returns a `LiveData` of current `TorchState`.
`DynamicRange`	`@MainThread getVideoCaptureDynamicRange()` Gets the `DynamicRange` for video capture.
`Int`	`@MainThread getVideoCaptureMirrorMode()` Gets the mirror mode for video capture.
`QualitySelector`	`@MainThread getVideoCaptureQualitySelector()` Returns the `QualitySelector` for `VIDEO_CAPTURE`.
`Range<Int!>`	`@MainThread getVideoCaptureTargetFrameRate()` Gets the target frame rate in frames per second for video capture.
`LiveData<ZoomState!>`	`@MainThread getZoomState()` Returns a `LiveData` of `ZoomState`.
`Boolean`	`@MainThread hasCamera(cameraSelector: CameraSelector)` Checks if the given `CameraSelector` can be resolved to a camera.
`Boolean`	`@MainThread isImageAnalysisEnabled()` Checks if `ImageAnalysis` is enabled.
`Boolean`	`@MainThread isImageCaptureEnabled()` Checks if `ImageCapture` is enabled.
`Boolean`	`@MainThread isPinchToZoomEnabled()` Returns whether pinch-to-zoom is enabled.
`Boolean`	`@MainThread isRecording()` Returns whether there is an in-progress video recording.
`Boolean`	`@MainThread isTapToFocusEnabled()` Returns whether tap-to-focus is enabled.
`Boolean`	`@MainThread isVideoCaptureEnabled()` Checks if video capture is enabled.
`Unit`	`@MainThread setCameraSelector(cameraSelector: CameraSelector)` Sets the `CameraSelector`.
`Unit`	`@MainThread setEffects(effects: (Mutable)Set<CameraEffect!>)` Sets `CameraEffect`.
`Unit`	`@MainThread setEnabledUseCases(enabledUseCases: Int)` Enables or disables use cases.
`Unit`	`@MainThread setImageAnalysisAnalyzer( executor: Executor, analyzer: ImageAnalysis.Analyzer )` Sets an analyzer to receive and analyze images.
`Unit`	`@MainThread setImageAnalysisBackgroundExecutor(executor: Executor?)` Sets the executor that will be used for `ImageAnalysis` background tasks.
`Unit`	`@MainThread setImageAnalysisBackpressureStrategy(strategy: Int)` Sets the backpressure strategy to apply to the image producer to deal with scenarios where images may be produced faster than they can be analyzed.
`Unit`	`@MainThread setImageAnalysisImageQueueDepth(depth: Int)` Sets the image queue depth of `ImageAnalysis`.
`Unit`	`@MainThread setImageAnalysisOutputImageFormat(imageAnalysisOutputImageFormat: Int)` Sets the output image format for `ImageAnalysis`.
`Unit`	`@MainThread setImageAnalysisResolutionSelector( resolutionSelector: ResolutionSelector? )` Sets the `ResolutionSelector` for `ImageAnalysis`.
`Unit`	`@MainThread setImageAnalysisTargetSize(targetSize: CameraController.OutputSize?)` This function is deprecated. Use `setImageAnalysisResolutionSelector` instead.
`Unit`	`@MainThread setImageCaptureFlashMode(flashMode: Int)` Sets the flash mode for `ImageCapture`.
`Unit`	`@MainThread setImageCaptureIoExecutor(executor: Executor?)` Sets the default executor that will be used for `ImageCapture` IO tasks.
`Unit`	`@MainThread setImageCaptureMode(captureMode: Int)` Sets the image capture mode.
`Unit`	`@MainThread setImageCaptureResolutionSelector( resolutionSelector: ResolutionSelector? )` Sets the `ResolutionSelector` for `ImageCapture`.
`Unit`	`@MainThread setImageCaptureTargetSize(targetSize: CameraController.OutputSize?)` This function is deprecated. Use `setImageCaptureResolutionSelector` instead.
`ListenableFuture<Void!>`	`@MainThread setLinearZoom(linearZoom: @FloatRange(from = 0.0, to = 1.0) Float)` Sets current zoom by a linear zoom value ranging from 0f to 1.0f.
`Unit`	`@MainThread setPinchToZoomEnabled(enabled: Boolean)` Enables/disables pinch-to-zoom.
`Unit`	`@MainThread setPreviewResolutionSelector(resolutionSelector: ResolutionSelector?)` Sets the `ResolutionSelector` for `Preview`.
`Unit`	`@MainThread setPreviewTargetSize(targetSize: CameraController.OutputSize?)` This function is deprecated. Use `setPreviewResolutionSelector` instead.
`Unit`	`@MainThread setTapToFocusEnabled(enabled: Boolean)` Enables/disables tap-to-focus.
`Unit`	`@MainThread setVideoCaptureDynamicRange(dynamicRange: DynamicRange)` Sets the `DynamicRange` for video capture.
`Unit`	`@MainThread setVideoCaptureMirrorMode(mirrorMode: Int)` Sets the mirror mode for video capture.
`Unit`	`@MainThread setVideoCaptureQualitySelector(qualitySelector: QualitySelector)` Sets the `QualitySelector` for `VIDEO_CAPTURE`.
`Unit`	`@MainThread setVideoCaptureTargetFrameRate(targetFrameRate: Range<Int!>)` Sets the target frame rate range in frames per second for video capture.
`ListenableFuture<Void!>`	`@MainThread setZoomRatio(zoomRatio: Float)` Sets current zoom by ratio.
`Recording`	`@RequiresApi(value = 26) @MainThread startRecording( outputOptions: FileDescriptorOutputOptions, audioConfig: AudioConfig, executor: Executor, listener: Consumer<VideoRecordEvent!> )` Takes a video to a given file descriptor.
`Recording`	`@MainThread startRecording( outputOptions: FileOutputOptions, audioConfig: AudioConfig, executor: Executor, listener: Consumer<VideoRecordEvent!> )` Takes a video to a given file.
`Recording`	`@MainThread startRecording( outputOptions: MediaStoreOutputOptions, audioConfig: AudioConfig, executor: Executor, listener: Consumer<VideoRecordEvent!> )` Takes a video to MediaStore.
`Unit`	`@MainThread takePicture( executor: Executor, callback: ImageCapture.OnImageCapturedCallback )` Captures a new still image for in memory access.
`Unit`	`@MainThread takePicture( outputFileOptions: ImageCapture.OutputFileOptions, executor: Executor, imageSavedCallback: ImageCapture.OnImageSavedCallback )` Captures a new still image and saves to a file along with application specified metadata.

Constants

COORDINATE_SYSTEM_VIEW_REFERENCED

Added in 1.1.0

Deprecated in 1.4.0

const val COORDINATE_SYSTEM_VIEW_REFERENCED = 1: Int

ImageAnalysis.Analyzer option for returning PreviewView coordinates.

When the ImageAnalysis.Analyzer is configured with this option, it will receive a Matrix that will receive a value that represents the transformation from camera sensor to the PreviewView, which can be used for highlighting detected result in PreviewView. For example, laying over a bounding box on top of the detected face.

Note this option only works if the ImageAnalysis.Analyzer is set via setImageAnalysisAnalyzer. It will not be effective when used with camera-core directly.

See also
`ImageAnalysis.Analyzer`

IMAGE_ANALYSIS

Added in 1.1.0

const val IMAGE_ANALYSIS = 2: Int

Bitmask option to enable ImageAnalysis. In setEnabledUseCases, if (enabledUseCases & IMAGE_ANALYSIS) != 0, then controller will enable image analysis features.

IMAGE_CAPTURE

Added in 1.1.0

const val IMAGE_CAPTURE = 1: Int

Bitmask option to enable ImageCapture. In setEnabledUseCases, if (enabledUseCases & IMAGE_CAPTURE) != 0, then controller will enable image capture features.

TAP_TO_FOCUS_FAILED

Added in 1.1.0

const val TAP_TO_FOCUS_FAILED = 4: Int

The previous tap-to-focus action was failed to complete. This is usually due to device limitations.

TAP_TO_FOCUS_FOCUSED

Added in 1.1.0

const val TAP_TO_FOCUS_FOCUSED = 2: Int

The previous tap-to-focus action was completed successfully and the camera is focused.

TAP_TO_FOCUS_NOT_FOCUSED

Added in 1.1.0

const val TAP_TO_FOCUS_NOT_FOCUSED = 3: Int

The previous tap-to-focus action was completed successfully but the camera is still unfocused, similar to the CONTROL_AF_STATE_NOT_FOCUSED_LOCKED state. The end user might be able to get a better result by trying again with different camera distances and/or lighting.

TAP_TO_FOCUS_NOT_STARTED

Added in 1.1.0

const val TAP_TO_FOCUS_NOT_STARTED = 0: Int

No tap-to-focus action has been started by the end user.

TAP_TO_FOCUS_STARTED

Added in 1.1.0

const val TAP_TO_FOCUS_STARTED = 1: Int

A tap-to-focus action has started but not completed. The app also gets notified with this state if a new action happens before the previous one could finish.

VIDEO_CAPTURE

Added in 1.1.0

const val VIDEO_CAPTURE = 4: Int

Bitmask option to enable video capture use case. In setEnabledUseCases, if (enabledUseCases & VIDEO_CAPTURE) != 0, then controller will enable video capture features.

Public functions

clearEffects

Added in 1.3.0

@MainThread
fun clearEffects(): Unit

Removes all effects.

Once called, CameraX will remove all the effects and rebind the UseCase.

clearImageAnalysisAnalyzer

Added in 1.1.0

@MainThread
fun clearImageAnalysisAnalyzer(): Unit

Removes a previously set analyzer.

This will stop data from streaming to the ImageAnalysis.

If the current getDefaultTargetResolution returns non-null value, calling this method will reconfigure the camera which might cause additional latency. To avoid this, call this method when the lifecycle is not active.

See also
`clearAnalyzer`

enableTorch

Added in 1.1.0

@MainThread
fun enableTorch(torchEnabled: Boolean): ListenableFuture<Void!>

Enable the torch or disable the torch.

If the value is set before the camera is ready, CameraController waits for the camera to be ready and then enables the torch.

Parameters
`torchEnabled: Boolean`	`true` to turn on the torch, `false` to turn it off.

Returns
`ListenableFuture<Void!>`	A `ListenableFuture` which is successful when the torch was changed to the value specified. It fails when it is unable to change the torch state. Cancellation of this future is a no-op.

See also
`enableTorch`

getCameraControl

Added in 1.1.0

@MainThread
fun getCameraControl(): CameraControl?

Gets the CameraControl of the currently attached camera.

For controls available directly through CameraController as well as CameraControl, it's recommended to use the ones with CameraController, e.g. setLinearZoom v.s. setLinearZoom. CameraControl is a lower-layer API and may require more steps to achieve the same effect, and will not maintain control values when switching between cameras.

Returns
`CameraControl?`	The `CameraControl` of the current camera. Returns `null` if camera is not ready.

See also
`getCameraControl`

getCameraInfo

Added in 1.1.0

@MainThread
fun getCameraInfo(): CameraInfo?

Gets the CameraInfo of the currently attached camera.

For info available directly through CameraController as well as CameraInfo, it's recommended to use the ones with CameraController, e.g. getTorchState v.s. getTorchState. CameraInfo is a lower-layer API and may require more steps to achieve the same effect, and will not maintain values when switching between cameras.

Returns
`CameraInfo?`	The `CameraInfo` of the current camera. Returns `null` if camera is not ready.

See also
`getCameraInfo`

getCameraSelector

Added in 1.1.0

@MainThread
fun getCameraSelector(): CameraSelector

Gets the CameraSelector.

The default value isDEFAULT_BACK_CAMERA.

See also
`CameraSelector`

getImageAnalysisBackgroundExecutor

Added in 1.1.0

@MainThread
fun getImageAnalysisBackgroundExecutor(): Executor?

Gets the default executor for ImageAnalysis background tasks.

See also
`setBackgroundExecutor`

getImageAnalysisBackpressureStrategy

Added in 1.1.0

@MainThread
fun getImageAnalysisBackpressureStrategy(): Int

Returns the mode with which images are acquired.

If not set, it defaults to STRATEGY_KEEP_ONLY_LATEST.

Returns
`Int`	The backpressure strategy applied to the image producer.

See also
`getBackpressureStrategy`

getImageAnalysisImageQueueDepth

Added in 1.1.0

@MainThread
fun getImageAnalysisImageQueueDepth(): Int

Gets the image queue depth of ImageAnalysis.

See also
`getImageQueueDepth`

getImageAnalysisOutputImageFormat

Added in 1.4.0

@MainThread
fun getImageAnalysisOutputImageFormat(): Int

Gets the output image format for ImageAnalysis.

The returned image format can be either OUTPUT_IMAGE_FORMAT_YUV_420_888 or OUTPUT_IMAGE_FORMAT_RGBA_8888.

See also
`setOutputImageFormat`
`getOutputImageFormat`
`getOutputImageFormat`

getImageAnalysisResolutionSelector

Added in 1.4.0

@MainThread
fun getImageAnalysisResolutionSelector(): ResolutionSelector?

Returns the ResolutionSelector for ImageAnalysis.

This method returns the value set by setImageAnalysisResolutionSelector. It returns null if the value has not been set.

getImageAnalysisTargetSize

Added in 1.1.0

Deprecated in 1.4.0

@MainThread
fun getImageAnalysisTargetSize(): CameraController.OutputSize?

Returns the intended output size for ImageAnalysis set by setImageAnalysisTargetSize, or null if not set.

getImageCaptureFlashMode

Added in 1.1.0

@MainThread
fun getImageCaptureFlashMode(): Int

Gets the flash mode for ImageCapture.

Returns
`Int`	the flashMode. Value is `FLASH_MODE_AUTO`, `FLASH_MODE_ON`, or `FLASH_MODE_OFF`.

See also
`ImageCapture`

getImageCaptureIoExecutor

Added in 1.1.0

@MainThread
fun getImageCaptureIoExecutor(): Executor?

Gets the default executor for ImageCapture IO tasks.

getImageCaptureMode

Added in 1.1.0

@MainThread
fun getImageCaptureMode(): Int

Returns the image capture mode.

See also
`getCaptureMode`

getImageCaptureResolutionSelector

Added in 1.4.0

@MainThread
fun getImageCaptureResolutionSelector(): ResolutionSelector?

Returns the ResolutionSelector for ImageCapture.

This method returns the value set by setImageCaptureResolutionSelector (ResolutionSelector)}. It returns null if the value has not been set.

getImageCaptureTargetSize

Added in 1.1.0

Deprecated in 1.4.0

@MainThread
fun getImageCaptureTargetSize(): CameraController.OutputSize?

Returns the intended output size for ImageCapture set by setImageCaptureTargetSize, or null if not set.

getInitializationFuture

Added in 1.1.0

fun getInitializationFuture(): ListenableFuture<Void!>

Gets a ListenableFuture that completes when camera initialization completes.

This future may fail with an InitializationException and associated cause that can be retrieved by getCause. The cause will be a CameraUnavailableException if it fails to access any camera during initialization.

In the rare case that the future fails with CameraUnavailableException, the camera will become unusable. This could happen for various reasons, for example hardware failure or the camera being held by another process. If the failure is temporary, killing and restarting the app might fix the issue.

The initialization also try to bind use cases before completing the ListenableFuture. The ListenableFuture will complete successfully regardless of whether the use cases are ready to be bound, e.g. it will complete successfully even if the controller is not set on a PreviewView. However the ListenableFuture will fail if the enabled use cases are not supported by the current camera.

See also
`getInstance`

getPreviewResolutionSelector

Added in 1.4.0

@MainThread
fun getPreviewResolutionSelector(): ResolutionSelector?

Returns the ResolutionSelector for Preview.

This method returns the value set by setPreviewResolutionSelector. It returns null if the value has not been set.

getPreviewTargetSize

Added in 1.1.0

Deprecated in 1.4.0

@MainThread
fun getPreviewTargetSize(): CameraController.OutputSize?

Returns the intended output size for Preview set by setPreviewTargetSize, or null if not set.

getTapToFocusState

Added in 1.1.0

@MainThread
fun getTapToFocusState(): LiveData<Int!>

Returns a LiveData with the latest tap-to-focus state.

When tap-to-focus feature is enabled, the LiveData will receive updates of focusing states. This happens when the end user taps on PreviewView, and then again when focusing is finished either successfully or unsuccessfully. The following table displays the states the LiveData can be in, and the possible transitions between them.

State	Transition cause	New State
TAP_TO_FOCUS_NOT_STARTED	User taps on `PreviewView`	TAP_TO_FOCUS_STARTED
TAP_TO_FOCUS_SUCCESSFUL	User taps on `PreviewView`	TAP_TO_FOCUS_STARTED
TAP_TO_FOCUS_UNSUCCESSFUL	User taps on `PreviewView`	TAP_TO_FOCUS_STARTED
TAP_TO_FOCUS_FAILED	User taps on `PreviewView`	TAP_TO_FOCUS_STARTED
TAP_TO_FOCUS_STARTED	Focusing succeeded	TAP_TO_FOCUS_SUCCESSFUL
Focusing failed due to lighting and/or camera distance	TAP_TO_FOCUS_UNSUCCESSFUL
Focusing failed due to device constraints	TAP_TO_FOCUS_FAILED

See also
`setTapToFocusEnabled`
`startFocusAndMetering`

getTorchState

Added in 1.1.0

@MainThread
fun getTorchState(): LiveData<Int!>

Returns a LiveData of current TorchState.

The torch can be turned on and off via enableTorch which will trigger the change event to the returned LiveData.

Returns
`LiveData<Int!>`	A `LiveData` containing current torch state.

See also
`getTorchState`

getVideoCaptureDynamicRange

Added in 1.4.0

@MainThread
fun getVideoCaptureDynamicRange(): DynamicRange

Gets the DynamicRange for video capture.

getVideoCaptureMirrorMode

Added in 1.4.0

@MainThread
fun getVideoCaptureMirrorMode(): Int

Gets the mirror mode for video capture.

getVideoCaptureQualitySelector

Added in 1.3.0

@MainThread
fun getVideoCaptureQualitySelector(): QualitySelector

Returns the QualitySelector for VIDEO_CAPTURE.

Returns
`QualitySelector`	the `QualitySelector` provided to `setVideoCaptureQualitySelector` or the default value of `DEFAULT_QUALITY_SELECTOR` if no quality selector was provided.

getVideoCaptureTargetFrameRate

Added in 1.4.0

@MainThread
fun getVideoCaptureTargetFrameRate(): Range<Int!>

Gets the target frame rate in frames per second for video capture.

getZoomState

Added in 1.1.0

@MainThread
fun getZoomState(): LiveData<ZoomState!>

Returns a LiveData of ZoomState.

The LiveData will be updated whenever the set zoom state has been changed. This can occur when the application updates the zoom via setZoomRatio or setLinearZoom. The zoom state can also change anytime a camera starts up, for example when setCameraSelector is called.

See also
`getZoomState`

hasCamera

Added in 1.1.0

@MainThread
fun hasCamera(cameraSelector: CameraSelector): Boolean

Checks if the given CameraSelector can be resolved to a camera.

Use this method to check if the device has the given camera.

Only call this method after camera is initialized. e.g. after the ListenableFuture from getInitializationFuture is finished. Calling it prematurely throws IllegalStateException. Example:

controller.getInitializationFuture().addListener(() -> {
    if (controller.hasCamera(cameraSelector)) {
        controller.setCameraSelector(cameraSelector);
    } else {
        // Update UI if the camera is not available.
    }
    // Attach PreviewView after we know the camera is available.
    previewView.setController(controller);
}, ContextCompat.getMainExecutor(requireContext()));

Returns
`Boolean`	`true` if the `CameraSelector` can be resolved to a camera.

Throws
`java.lang.IllegalStateException`	if the camera is not initialized.

isImageAnalysisEnabled

Added in 1.1.0

@MainThread
fun isImageAnalysisEnabled(): Boolean

Checks if ImageAnalysis is enabled.

See also
`ImageAnalysis`

isImageCaptureEnabled

Added in 1.1.0

@MainThread
fun isImageCaptureEnabled(): Boolean

Checks if ImageCapture is enabled.

ImageCapture is enabled by default. It has to be enabled before takePicture can be called.

See also
`ImageCapture`

isPinchToZoomEnabled

Added in 1.1.0

@MainThread
fun isPinchToZoomEnabled(): Boolean

Returns whether pinch-to-zoom is enabled.

By default pinch-to-zoom is enabled.

Returns
`Boolean`	`true` if pinch-to-zoom is enabled.

isRecording

Added in 1.1.0

@MainThread
fun isRecording(): Boolean

Returns whether there is an in-progress video recording.

isTapToFocusEnabled

Added in 1.1.0

@MainThread
fun isTapToFocusEnabled(): Boolean

Returns whether tap-to-focus is enabled.

By default tap-to-focus is enabled.

Returns
`Boolean`	`true` if tap-to-focus is enabled.

isVideoCaptureEnabled

Added in 1.1.0

@MainThread
fun isVideoCaptureEnabled(): Boolean

Checks if video capture is enabled.

Video capture is disabled by default. It has to be enabled before startRecording can be called.

setCameraSelector

Added in 1.1.0

@MainThread
fun setCameraSelector(cameraSelector: CameraSelector): Unit

Sets the CameraSelector.

Calling this method with a CameraSelector that resolves to a different camera will change the camera being used by the controller. If camera initialization is complete, the controller will immediately rebind use cases with the new CameraSelector; otherwise, the new CameraSelector will be used when the camera becomes ready.

The default value is DEFAULT_BACK_CAMERA.

Throws
`java.lang.IllegalStateException`	If the provided camera selector is unable to resolve a camera to be used for the enabled use cases.

See also
`CameraSelector`

setEffects

Added in 1.3.0

@MainThread
fun setEffects(effects: (Mutable)Set<CameraEffect!>): Unit

Sets CameraEffect.

Call this method to set a list of active effects. There is maximum one effect per UseCase. Adding effects with duplicate or invalid targets throws IllegalArgumentException. Once called, CameraX will rebind the UseCase with the effects applied. Effects not in the list are automatically removed.

The method throws IllegalArgumentException if the effects combination is not supported by CameraX. Please see the Javadoc of addEffect to see the supported effects combinations.

Parameters
`effects: (Mutable)Set<CameraEffect!>`	The effects applied to camera output.

Throws
`java.lang.IllegalArgumentException`	if the combination of effects is not supported by CameraX.

See also
`addEffect`

setEnabledUseCases

Added in 1.1.0

@MainThread
fun setEnabledUseCases(enabledUseCases: Int): Unit

Enables or disables use cases.

Use cases need to be enabled before they can be used. By default, IMAGE_CAPTURE and IMAGE_ANALYSIS are enabled, and VIDEO_CAPTURE is disabled. This is necessary because VIDEO_CAPTURE may affect the available resolutions for other use cases, especially on lower end devices.

To make sure getting the maximum resolution, only enable VIDEO_CAPTURE when shooting video. For example:

// By default, image capture is enabled. Taking picture works.
controller.takePicture(...);

// Switch to video capture to shoot video.
controller.setEnabledUseCases(VIDEO_CAPTURE);
controller.startRecording(...);

// Switch back to image capture and image analysis before taking another picture.
controller.setEnabledUseCases(IMAGE_CAPTURE|IMAGE_ANALYSIS);
controller.takePicture(...);

Parameters
`enabledUseCases: Int`	one or more of the following use cases, bitwise-OR-ed together: `IMAGE_CAPTURE`, `IMAGE_ANALYSIS` and/or `VIDEO_CAPTURE`.

Throws
`java.lang.IllegalStateException`	If the current camera selector is unable to resolve a camera to be used for the enabled use cases.

See also
`UseCase`
`ImageCapture`
`ImageAnalysis`

setImageAnalysisAnalyzer

Added in 1.1.0

@MainThread
fun setImageAnalysisAnalyzer(
    executor: Executor,
    analyzer: ImageAnalysis.Analyzer
): Unit

Sets an analyzer to receive and analyze images.

Applications can process or copy the image by implementing the ImageAnalysis.Analyzer. The image needs to be closed by calling close when the analyzing is done.

Setting an analyzer function replaces any previous analyzer. Only one analyzer can be set at any time.

If the getTargetCoordinateSystem returns COORDINATE_SYSTEM_VIEW_REFERENCED, the analyzer will receive a transformation via updateTransform that converts coordinates from the ImageAnalysis's coordinate system to the PreviewView's coordinate system.

If the getDefaultTargetResolution returns a non-null value, calling this method will reconfigure the camera which might cause additional latency. To avoid this, set the value before controller is bound to the lifecycle.

Parameters
`executor: Executor`	The executor in which the `analyze` will be run.
`analyzer: ImageAnalysis.Analyzer`	of the images.

See also
`setAnalyzer`

setImageAnalysisBackgroundExecutor

Added in 1.1.0

@MainThread
fun setImageAnalysisBackgroundExecutor(executor: Executor?): Unit

Sets the executor that will be used for ImageAnalysis background tasks.

If not set, the background executor will default to an automatically generated Executor.

Changing the value will reconfigure the camera, which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`executor: Executor?`	The executor for `ImageAnalysis` background tasks.

See also
`setBackgroundExecutor`

setImageAnalysisBackpressureStrategy

Added in 1.1.0

@MainThread
fun setImageAnalysisBackpressureStrategy(strategy: Int): Unit

Sets the backpressure strategy to apply to the image producer to deal with scenarios where images may be produced faster than they can be analyzed.

The available values are STRATEGY_BLOCK_PRODUCER and STRATEGY_KEEP_ONLY_LATEST. If not set, the backpressure strategy will default to STRATEGY_KEEP_ONLY_LATEST.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`strategy: Int`	The strategy to use.

See also
`setBackpressureStrategy`

setImageAnalysisImageQueueDepth

Added in 1.1.0

@MainThread
fun setImageAnalysisImageQueueDepth(depth: Int): Unit

Sets the image queue depth of ImageAnalysis.

This sets the number of images available in parallel to ImageAnalysis.Analyzer. The value is only used if the backpressure strategy is STRATEGY_BLOCK_PRODUCER.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`depth: Int`	The total number of images available.

See also
`setImageQueueDepth`

setImageAnalysisOutputImageFormat

Added in 1.4.0

@MainThread
fun setImageAnalysisOutputImageFormat(imageAnalysisOutputImageFormat: Int): Unit

Sets the output image format for ImageAnalysis.

The supported output image format are OUTPUT_IMAGE_FORMAT_YUV_420_888 and OUTPUT_IMAGE_FORMAT_RGBA_8888.

If not set, OUTPUT_IMAGE_FORMAT_YUV_420_888 will be used.

Requesting OUTPUT_IMAGE_FORMAT_RGBA_8888 causes extra overhead because format conversion takes time.

Changing the value will reconfigure the camera, which may cause additional latency. To avoid this, set the value before controller is bound to lifecycle. If the value is changed when the camera is active, check the getFormat value to determine when the new format takes effect.

See also
`setOutputImageFormat`
`getOutputImageFormat`
`getOutputImageFormat`

setImageAnalysisResolutionSelector

Added in 1.4.0

@MainThread
fun setImageAnalysisResolutionSelector(
    resolutionSelector: ResolutionSelector?
): Unit

Sets the ResolutionSelector for ImageAnalysis.

CameraX uses this value as a hint to select the resolution for images. The actual output may differ from the requested value due to device constraints. When set to null, CameraX will use the default config of ImageAnalysis. ImageAnalysis has a default ResolutionStrategy with bound size as 640x480 and fallback rule of FALLBACK_RULE_CLOSEST_HIGHER_THEN_LOWER.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

See also
`setResolutionSelector`

setImageAnalysisTargetSize

Added in 1.1.0

Deprecated in 1.4.0

@MainThread
fun setImageAnalysisTargetSize(targetSize: CameraController.OutputSize?): Unit

Sets the intended output size for ImageAnalysis.

The value is used as a hint when determining the resolution and aspect ratio of the output buffer. The actual output may differ from the requested value due to device constraints.

When set to null, the output will be based on the default config of ImageAnalysis.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`targetSize: CameraController.OutputSize?`	The intended output size for `ImageAnalysis`.

See also
`setTargetAspectRatio`
`setTargetResolution`

setImageCaptureFlashMode

Added in 1.1.0

@MainThread
fun setImageCaptureFlashMode(flashMode: Int): Unit

Sets the flash mode for ImageCapture.

If not set, the flash mode will default to FLASH_MODE_OFF.

If FLASH_MODE_SCREEN is set, a valid android.view.Window instance must be set to a PreviewView or ScreenFlashView which this controller is set to. Trying to use FLASH_MODE_SCREEN with a non-front camera or without setting a non-null window will be no-op. While switching the camera, it is the application's responsibility to change flash mode to the desired one if it leads to a no-op case (e.g. switching to rear camera while FLASH_MODE_SCREEN is still set). Otherwise, FLASH_MODE_OFF will be set.

Parameters
`flashMode: Int`	the flash mode for `ImageCapture`.

Throws
`java.lang.IllegalArgumentException`	If flash mode is invalid or `FLASH_MODE_SCREEN` is used without a front camera.

See also
`setScreenFlashWindow`
`setScreenFlashWindow`

setImageCaptureIoExecutor

Added in 1.1.0

@MainThread
fun setImageCaptureIoExecutor(executor: Executor?): Unit

Sets the default executor that will be used for ImageCapture IO tasks.

This executor will be used for any IO tasks specifically for ImageCapture, such as takePicture. If no executor is set, then a default Executor specifically for IO will be used instead.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`executor: Executor?`	The executor which will be used for IO tasks.

setImageCaptureMode

Added in 1.1.0

@MainThread
fun setImageCaptureMode(captureMode: Int): Unit

Sets the image capture mode.

Valid capture modes are CAPTURE_MODE_MINIMIZE_LATENCY, which prioritizes latency over image quality, or CAPTURE_MODE_MAXIMIZE_QUALITY, which prioritizes image quality over latency.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`captureMode: Int`	The requested image capture mode.

setImageCaptureResolutionSelector

Added in 1.4.0

@MainThread
fun setImageCaptureResolutionSelector(
    resolutionSelector: ResolutionSelector?
): Unit

Sets the ResolutionSelector for ImageCapture.

CameraX uses this value as a hint to select the resolution for captured images. The actual output may differ from the requested value due to device constraints. When set to null, CameraX will use the default config of ImageCapture. The default resolution strategy for ImageCapture is HIGHEST_AVAILABLE_STRATEGY, which will select the largest available resolution to use.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

See also
`setResolutionSelector`

setImageCaptureTargetSize

Added in 1.1.0

Deprecated in 1.4.0

@MainThread
fun setImageCaptureTargetSize(targetSize: CameraController.OutputSize?): Unit

Sets the intended image size for ImageCapture.

The value is used as a hint when determining the resolution and aspect ratio of the captured image. The actual output may differ from the requested value due to device constraints.

When set to null, the output will be based on the default config of ImageCapture.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`targetSize: CameraController.OutputSize?`	The intended image size for `ImageCapture`.

setLinearZoom

Added in 1.1.0

@MainThread
fun setLinearZoom(linearZoom: @FloatRange(from = 0.0, to = 1.0) Float): ListenableFuture<Void!>

Sets current zoom by a linear zoom value ranging from 0f to 1.0f.

LinearZoom 0f represents the minimum zoom while linearZoom 1.0f represents the maximum zoom. The advantage of linearZoom is that it ensures the field of view (FOV) varies linearly with the linearZoom value, for use with slider UI elements (while setZoomRatio works well for pinch-zoom gestures).

If the value is set before the camera is ready, CameraController waits for the camera to be ready and then sets the linear zoom.

Returns
`ListenableFuture<Void!>`	A `ListenableFuture` which is finished when camera is set to the given ratio. It fails with `CameraControl.OperationCanceledException` if there is newer value being set or camera is closed. If the ratio is out of range, it fails with `IllegalArgumentException`. Cancellation of this future is a no-op.

See also
`setLinearZoom`

setPinchToZoomEnabled

Added in 1.1.0

@MainThread
fun setPinchToZoomEnabled(enabled: Boolean): Unit

Enables/disables pinch-to-zoom.

Once enabled, end user can pinch on the PreviewView to zoom in/out if the bound camera supports zooming.

Parameters
`enabled: Boolean`	`true` to enable pinch-to-zoom.

setPreviewResolutionSelector

Added in 1.4.0

@MainThread
fun setPreviewResolutionSelector(resolutionSelector: ResolutionSelector?): Unit

Sets the ResolutionSelector for Preview.

CameraX uses this value as a hint to select the resolution for preview. The actual output may differ from the requested value due to device constraints. When set to null, CameraX will use the default config of Preview. By default, the selected resolution will be limited by the PREVIEW size which is defined as the best size match to the device's screen resolution, or to 1080p (1920x1080), whichever is smaller.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

See also
`setResolutionSelector`

setPreviewTargetSize

Added in 1.1.0

Deprecated in 1.4.0

@MainThread
fun setPreviewTargetSize(targetSize: CameraController.OutputSize?): Unit

Sets the intended output size for Preview.

The value is used as a hint when determining the resolution and aspect ratio of the preview. The actual output may differ from the requested value due to device constraints.

When set to null, the output will be based on the default config of Preview.

Changing the value will reconfigure the camera which will cause additional latency. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`targetSize: CameraController.OutputSize?`	the intended output size for `Preview`.

See also
`setTargetAspectRatio`
`setTargetResolution`

setTapToFocusEnabled

Added in 1.1.0

@MainThread
fun setTapToFocusEnabled(enabled: Boolean): Unit

Enables/disables tap-to-focus.

Once enabled, end user can tap on the PreviewView to set focus point.

Parameters
`enabled: Boolean`	`true` to enable tap-to-focus.

setVideoCaptureDynamicRange

Added in 1.4.0

@MainThread
fun setVideoCaptureDynamicRange(dynamicRange: DynamicRange): Unit

Sets the DynamicRange for video capture.

The dynamic range specifies how the range of colors, highlights and shadows that are captured by the video producer are displayed on a display. Some dynamic ranges will allow the video to make full use of the extended range of brightness of a display when the video is played back.

The supported dynamic ranges for video capture can be queried through the androidx.camera.video.VideoCapabilities returned by getVideoCapabilities via getSupportedDynamicRanges.

It is possible to choose a high dynamic range (HDR) with unspecified encoding by providing HDR_UNSPECIFIED_10_BIT.

If the dynamic range is not provided, the default value is SDR.

See also
`setDynamicRange`

setVideoCaptureMirrorMode

Added in 1.4.0

@MainThread
fun setVideoCaptureMirrorMode(mirrorMode: Int): Unit

Sets the mirror mode for video capture.

Valid values include: MIRROR_MODE_OFF, MIRROR_MODE_ON and MIRROR_MODE_ON_FRONT_ONLY. If not set, it defaults to MIRROR_MODE_OFF.

See also
`setMirrorMode`

setVideoCaptureQualitySelector

Added in 1.3.0

@MainThread
fun setVideoCaptureQualitySelector(qualitySelector: QualitySelector): Unit

Sets the QualitySelector for VIDEO_CAPTURE.

The provided quality selector is used to select the resolution of the recording depending on the resolutions supported by the camera and codec capabilities.

If no quality selector is provided, the default is DEFAULT_QUALITY_SELECTOR.

Changing the value will reconfigure the camera which will cause video capture to stop. To avoid this, set the value before controller is bound to lifecycle.

Parameters
`qualitySelector: QualitySelector`	The quality selector for `VIDEO_CAPTURE`.

See also
`QualitySelector`

setVideoCaptureTargetFrameRate

Added in 1.4.0

@MainThread
fun setVideoCaptureTargetFrameRate(targetFrameRate: Range<Int!>): Unit

Sets the target frame rate range in frames per second for video capture.

This target will be used as a part of the heuristics for the algorithm that determines the final frame rate range and resolution of all concurrently bound use cases.

It is not guaranteed that this target frame rate will be the final range, as other use cases as well as frame rate restrictions of the device may affect the outcome of the algorithm that chooses the actual frame rate.

By default, the value is FRAME_RATE_RANGE_UNSPECIFIED. For supported frame rates, see getSupportedFrameRateRanges.

See also
`setTargetFrameRate`

setZoomRatio

Added in 1.1.0

@MainThread
fun setZoomRatio(zoomRatio: Float): ListenableFuture<Void!>

Sets current zoom by ratio.

Valid zoom values range from getMinZoomRatio to getMaxZoomRatio.

If the value is set before the camera is ready, CameraController waits for the camera to be ready and then sets the zoom ratio.

Parameters
`zoomRatio: Float`	The requested zoom ratio.

Returns
`ListenableFuture<Void!>`	A `ListenableFuture` which is finished when camera is set to the given ratio. It fails with `CameraControl.OperationCanceledException` if there is newer value being set or camera is closed. If the ratio is out of range, it fails with `IllegalArgumentException`. Cancellation of this future is a no-op.

See also
`getZoomState`
`setZoomRatio`

startRecording

Added in 1.3.0

@RequiresApi(value = 26)
@MainThread
fun startRecording(
    outputOptions: FileDescriptorOutputOptions,
    audioConfig: AudioConfig,
    executor: Executor,
    listener: Consumer<VideoRecordEvent!>
): Recording

Takes a video to a given file descriptor.

Currently, file descriptors as output destinations are not supported on pre-Android O (API 26) devices.

Only a single recording can be active at a time, so if isRecording is true, this will throw an IllegalStateException.

Upon successfully starting the recording, a VideoRecordEvent.Start event will be the first event sent to the provided event listener.

If errors occur while starting the recording, a VideoRecordEvent.Finalize event will be the first event sent to the provided listener, and information about the error can be found in that event's getError method.

Recording with audio requires the RECORD_AUDIO permission; without it, starting a recording will fail with a SecurityException.

Parameters
`outputOptions: FileDescriptorOutputOptions`	The options to store the newly captured video.
`audioConfig: AudioConfig`	The configuration of audio.
`executor: Executor`	The executor that the event listener will be run on.
`listener: Consumer<VideoRecordEvent!>`	The event listener to handle video record events.

Returns
`Recording`	a `Recording` that provides controls for new active recordings.

Throws
`java.lang.IllegalStateException`	if there is an unfinished active recording.
`java.lang.SecurityException`	if the audio config specifies audio should be enabled but the `RECORD_AUDIO` permission is denied.

startRecording

Added in 1.3.0

@MainThread
fun startRecording(
    outputOptions: FileOutputOptions,
    audioConfig: AudioConfig,
    executor: Executor,
    listener: Consumer<VideoRecordEvent!>
): Recording

Takes a video to a given file.

Only a single recording can be active at a time, so if isRecording is true, this will throw an IllegalStateException.

Upon successfully starting the recording, a VideoRecordEvent.Start event will be the first event sent to the provided event listener.

Recording with audio requires the RECORD_AUDIO permission; without it, starting a recording will fail with a SecurityException.

Parameters
`outputOptions: FileOutputOptions`	The options to store the newly captured video.
`audioConfig: AudioConfig`	The configuration of audio.
`executor: Executor`	The executor that the event listener will be run on.
`listener: Consumer<VideoRecordEvent!>`	The event listener to handle video record events.

Returns
`Recording`	a `Recording` that provides controls for new active recordings.

Throws
`java.lang.IllegalStateException`	if there is an unfinished active recording.
`java.lang.SecurityException`	if the audio config specifies audio should be enabled but the `RECORD_AUDIO` permission is denied.

startRecording

Added in 1.3.0

@MainThread
fun startRecording(
    outputOptions: MediaStoreOutputOptions,
    audioConfig: AudioConfig,
    executor: Executor,
    listener: Consumer<VideoRecordEvent!>
): Recording

Takes a video to MediaStore.

Only a single recording can be active at a time, so if isRecording is true, this will throw an IllegalStateException.

Upon successfully starting the recording, a VideoRecordEvent.Start event will be the first event sent to the provided event listener.

Recording with audio requires the RECORD_AUDIO permission; without it, starting a recording will fail with a SecurityException.

Parameters
`outputOptions: MediaStoreOutputOptions`	The options to store the newly captured video.
`audioConfig: AudioConfig`	The configuration of audio.
`executor: Executor`	The executor that the event listener will be run on.
`listener: Consumer<VideoRecordEvent!>`	The event listener to handle video record events.

Returns
`Recording`	a `Recording` that provides controls for new active recordings.

Throws
`java.lang.IllegalStateException`	if there is an unfinished active recording.
`java.lang.SecurityException`	if the audio config specifies audio should be enabled but the `RECORD_AUDIO` permission is denied.

takePicture

Added in 1.1.0

@MainThread
fun takePicture(
    executor: Executor,
    callback: ImageCapture.OnImageCapturedCallback
): Unit

Captures a new still image for in memory access.

The listener is responsible for calling close on the returned image.

Parameters
`executor: Executor`	The executor in which the callback methods will be run.
`callback: ImageCapture.OnImageCapturedCallback`	Callback to be invoked for the newly captured image

Throws
`java.lang.IllegalStateException`	If `FLASH_MODE_SCREEN` is set to the `CameraController`, but a non-null `Window` instance has not been set with `setScreenFlashWindow`.

See also
`takePicture`

takePicture

Added in 1.1.0

@MainThread
fun takePicture(
    outputFileOptions: ImageCapture.OutputFileOptions,
    executor: Executor,
    imageSavedCallback: ImageCapture.OnImageSavedCallback
): Unit

Captures a new still image and saves to a file along with application specified metadata.

The callback will be called only once for every invocation of this method.

By default, the saved image is mirrored to match the output of the preview if front camera is used. To override this behavior, the app needs to explicitly set the flag to false using setReversedHorizontal and setMetadata.

The saved image is cropped to match the aspect ratio of the PreviewView. To take a picture with the maximum available resolution, make sure that the PreviewView's aspect ratio matches the max JPEG resolution supported by the camera.

Parameters
`outputFileOptions: ImageCapture.OutputFileOptions`	Options to store the newly captured image.
`executor: Executor`	The executor in which the callback methods will be run.
`imageSavedCallback: ImageCapture.OnImageSavedCallback`	Callback to be called for the newly captured image.

Throws
`java.lang.IllegalStateException`	If `FLASH_MODE_SCREEN` is set to the `CameraController`, but a non-null `Window` instance has not been set with `setScreenFlashWindow`.

See also
`takePicture`