CameraController


public abstract class CameraController

Known direct subclasses
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

public final class CameraController.OutputSize

This class is deprecated.

Use ResolutionSelector instead.

Constants

static final int

This field is deprecated.

Use COORDINATE_SYSTEM_VIEW_REFERENCED instead.

static final int

Bitmask option to enable ImageAnalysis.

static final int

Bitmask option to enable ImageCapture.

static final int

The previous tap-to-focus action was failed to complete.

static final int

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

static final 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.

static final int

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

static final int

A tap-to-focus action has started but not completed.

static final int

Bitmask option to enable video capture use case.

Public methods

void

Removes all effects.

void

Removes a previously set analyzer.

@NonNull ListenableFuture<Void>
@MainThread
enableTorch(boolean torchEnabled)

Enable the torch or disable the torch.

@Nullable CameraControl

Gets the CameraControl of the currently attached camera.

@Nullable CameraInfo

Gets the CameraInfo of the currently attached camera.

@NonNull CameraSelector

Gets the CameraSelector.

@Nullable Executor

Gets the default executor for ImageAnalysis background tasks.

int

Returns the mode with which images are acquired.

int

Gets the image queue depth of ImageAnalysis.

int

Gets the output image format for ImageAnalysis.

@Nullable ResolutionSelector

Returns the ResolutionSelector for ImageAnalysis.

@Nullable CameraController.OutputSize

This method is deprecated.

Use getImageAnalysisResolutionSelector instead.

int

Gets the flash mode for ImageCapture.

@Nullable Executor

Gets the default executor for ImageCapture IO tasks.

int

Returns the image capture mode.

@Nullable ResolutionSelector

Returns the ResolutionSelector for ImageCapture.

@Nullable CameraController.OutputSize

This method is deprecated.

Use getImageCaptureResolutionSelector instead.

@NonNull ListenableFuture<Void>

Gets a ListenableFuture that completes when camera initialization completes.

@Nullable ResolutionSelector

Returns the ResolutionSelector for Preview.

@Nullable CameraController.OutputSize

This method is deprecated.

Use getPreviewResolutionSelector instead.

@NonNull LiveData<TapToFocusInfo>

Returns a LiveData with a TapToFocusInfo containing the latest focus state and corresponding tap position.

@NonNull LiveData<Integer>

This method is deprecated.

Use getTapToFocusInfoState instead.

@NonNull LiveData<Integer>

Returns a LiveData of current TorchState.

@NonNull DynamicRange

Gets the DynamicRange for video capture.

int

Gets the mirror mode for video capture.

@NonNull QualitySelector

Returns the QualitySelector for VIDEO_CAPTURE.

@NonNull Range<Integer>

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

@NonNull LiveData<ZoomState>

Returns a LiveData of ZoomState.

boolean

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

boolean

Checks if ImageAnalysis is enabled.

boolean

Checks if ImageCapture is enabled.

boolean

Returns whether pinch-to-zoom is enabled.

boolean

Returns whether there is an in-progress video recording.

boolean

Returns whether tap-to-focus is enabled.

boolean

Checks if video capture is enabled.

void

Sets the CameraSelector.

void

Sets CameraEffect.

void
@MainThread
setEnabledUseCases(int enabledUseCases)

Enables or disables use cases.

void

Sets an analyzer to receive and analyze images.

void

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

void

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.

void

Sets the image queue depth of ImageAnalysis.

void
@MainThread
setImageAnalysisOutputImageFormat(int imageAnalysisOutputImageFormat)

Sets the output image format for ImageAnalysis.

void

Sets the ResolutionSelector for ImageAnalysis.

void

This method is deprecated.

Use setImageAnalysisResolutionSelector instead.

void

Sets the flash mode for ImageCapture.

void

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

void

Sets the image capture mode.

void

Sets the ResolutionSelector for ImageCapture.

void

This method is deprecated.

Use setImageCaptureResolutionSelector instead.

@NonNull ListenableFuture<Void>
@MainThread
setLinearZoom(@FloatRange(from = 0.0, to = 1.0) float linearZoom)

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

void

Enables/disables pinch-to-zoom.

void

Sets the ResolutionSelector for Preview.

void

This method is deprecated.

Use setPreviewResolutionSelector instead.

void
@MainThread
setTapToFocusAutoCancelDuration(
    @IntRange(from = 0) long duration,
    @NonNull TimeUnit timeUnit
)

Sets the auto-cancel duration for tap-to-focus events.

void

Enables/disables tap-to-focus.

void

Sets the DynamicRange for video capture.

void

Sets the mirror mode for video capture.

void

Sets the QualitySelector for VIDEO_CAPTURE.

void

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

@NonNull ListenableFuture<Void>
@MainThread
setZoomRatio(float zoomRatio)

Sets current zoom by ratio.

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

Takes a video to a given file descriptor.

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

Takes a video to a given file.

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

Takes a video to MediaStore.

void

Captures a new still image for in memory access.

void
@MainThread
takePicture(
    @NonNull ImageCapture.OutputFileOptions outputFileOptions,
    @NonNull Executor executor,
    @NonNull ImageCapture.OnImageSavedCallback imageSavedCallback
)

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
public static final int COORDINATE_SYSTEM_VIEW_REFERENCED = 1

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.

IMAGE_ANALYSIS

Added in 1.1.0
public static final int IMAGE_ANALYSIS = 2

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
public static final int IMAGE_CAPTURE = 1

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
public static final int TAP_TO_FOCUS_FAILED = 4

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
public static final int TAP_TO_FOCUS_FOCUSED = 2

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

TAP_TO_FOCUS_NOT_FOCUSED

Added in 1.1.0
public static final 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. 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
public static final int TAP_TO_FOCUS_NOT_STARTED = 0

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

TAP_TO_FOCUS_STARTED

Added in 1.1.0
public static final int TAP_TO_FOCUS_STARTED = 1

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
public static final int VIDEO_CAPTURE = 4

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

Public methods

clearEffects

Added in 1.3.0
@MainThread
public void clearEffects()

Removes all effects.

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

clearImageAnalysisAnalyzer

Added in 1.1.0
@MainThread
public void clearImageAnalysisAnalyzer()

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
public @NonNull ListenableFuture<VoidenableTorch(boolean torchEnabled)

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
boolean torchEnabled

true to turn on the torch, false to turn it off.

Returns
@NonNull 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
public @Nullable CameraControl getCameraControl()

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
@Nullable CameraControl

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

See also
getCameraControl

getCameraInfo

Added in 1.1.0
@MainThread
public @Nullable CameraInfo getCameraInfo()

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
@Nullable CameraInfo

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

See also
getCameraInfo

getCameraSelector

Added in 1.1.0
@MainThread
public @NonNull CameraSelector getCameraSelector()

Gets the CameraSelector.

The default value isDEFAULT_BACK_CAMERA.

See also
CameraSelector

getImageAnalysisBackgroundExecutor