Google is committed to advancing racial equity for Black communities. See how.

CameraController

abstract class CameraController
kotlin.Any
   ↳ androidx.camera.view.CameraController

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 an experimental video capture. Preview is required and always enabled. ImageCapture and ImageAnalysis are enabled by default. The video capture feature is experimental. It's disabled by default because it might conflict with 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

Constants
static Int

Bitmask option to enable ImageAnalysis.

static Int

Bitmask option to enable ImageCapture.

static Int

Bitmask option to enable video capture use case.

Public methods
open Unit

Removes a previously set analyzer.

open ListenableFuture<Void!>
enableTorch(torchEnabled: Boolean)

Enable the torch or disable the torch.

open CameraSelector

Gets the CameraSelector.

open Int

Returns the mode with which images are acquired.

open Int

Gets the image queue depth of ImageAnalysis.

open Int

Gets the flash mode for ImageCapture.

open ListenableFuture<Void!>

Gets a ListenableFuture that completes when camera initialization completes.

open LiveData<Int!>

Returns a LiveData of current TorchState.

open LiveData<ZoomState!>

Returns a LiveData of ZoomState.

open Boolean
hasCamera(@NonNull cameraSelector: CameraSelector)

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

open Boolean

Checks if ImageAnalysis is enabled.

open Boolean

Checks if ImageCapture is enabled.

open Boolean

Returns whether pinch-to-zoom is enabled.

open Boolean

Returns whether there is a in progress video recording.

open Boolean

Returns whether tap-to-focus is enabled.

open Boolean

Checks if video capture is enabled.

open Unit
setCameraSelector(@NonNull cameraSelector: CameraSelector)

Sets the CameraSelector.

open Unit
setEnabledUseCases(enabledUseCases: Int)

Enables or disables use cases.

open Unit
setImageAnalysisAnalyzer(@NonNull executor: Executor, @NonNull analyzer: ImageAnalysis.Analyzer)

Sets an analyzer to receive and analyze images.

open 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.

open Unit

Sets the image queue depth of ImageAnalysis.

open Unit

Sets the flash mode for ImageCapture.

open ListenableFuture<Void!>
setLinearZoom(linearZoom: Float)

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

open Unit

Enables/disables pinch-to-zoom.

open Unit

Enables/disables tap-to-focus.

open ListenableFuture<Void!>
setZoomRatio(zoomRatio: Float)

Sets current zoom by ratio.

open Unit
startRecording(@NonNull outputFileOptions: OutputFileOptions, @NonNull executor: Executor, @NonNull callback: OnVideoSavedCallback)

Takes a video and calls the OnVideoSavedCallback when done.

open Unit

Stops a in progress video recording.

open Unit
takePicture(@NonNull outputFileOptions: ImageCapture.OutputFileOptions, @NonNull executor: Executor, @NonNull imageSavedCallback: ImageCapture.OnImageSavedCallback)

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

open Unit
takePicture(@NonNull executor: Executor, @NonNull callback: ImageCapture.OnImageCapturedCallback)

Captures a new still image for in memory access.

Constants

IMAGE_ANALYSIS

static val IMAGE_ANALYSIS: Int

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

Value: 1 << 1

IMAGE_CAPTURE

static val IMAGE_CAPTURE: Int

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

Value: 1

VIDEO_CAPTURE

static val VIDEO_CAPTURE: Int

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

Value: 1 << 2

Public methods

clearImageAnalysisAnalyzer

@MainThread open fun clearImageAnalysisAnalyzer(): Unit

Removes a previously set analyzer.

This will stop data from streaming to the ImageAnalysis.

enableTorch

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

Enable the torch or disable the torch.

No-ops if the camera is not ready. The ListenableFuture completes successfully in this case.

Parameters
torchEnabled Boolean: true to turn on the torch, false to turn it off.
Return
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.

getCameraSelector

@NonNull @MainThread open fun getCameraSelector(): CameraSelector

Gets the CameraSelector.

The default value isCameraSelector#DEFAULT_BACK_CAMERA.

See Also

getImageAnalysisBackpressureStrategy

@MainThread open fun getImageAnalysisBackpressureStrategy(): Int

Returns the mode with which images are acquired.

If not set, it defaults to ImageAnalysis#STRATEGY_KEEP_ONLY_LATEST.

Return
Int The backpressure strategy applied to the image producer.

getImageAnalysisImageQueueDepth

@MainThread open fun getImageAnalysisImageQueueDepth(): Int

Gets the image queue depth of ImageAnalysis.