CameraController

interface CameraController extends HybridObject

A CameraController allows controlling an opened Camera.

You obtain one CameraController per configured connection via CameraSession.configure(...), or via the useCamera(...) hook.

After a CameraSession is reconfigured (e.g. when binding new inputs, outputs, or connection settings), you receive a new CameraController.

Examples

Via the useCamera(...) hook:

const device = useCameraDevice('back')
const camera = useCamera({
  isActive: true,
  input: device,
  outputs: []
})
useEffect(() => {
  camera?.setZoom(device.maxZoom)
}, [camera, device])

Via the imperative CameraSession APIs:

const devicesFactory = await HybridCameraFactory.createDeviceFactory()
const device = devicesFactory.getDefaultCamera('back')
const cameraSession = await HybridCameraFactory.createCameraSession(false)
const controller = await cameraSession.configure([
  {
    input: device,
    outputs: [],
    config: {}
  }
])
await cameraSession.start()
controller.setZoom(device.maxZoom)

Properties

colorSpace

readonly colorSpace: ColorSpace

Gets the currently selected ColorSpace.

You can select a custom ColorSpace by disabling automatic colorspace selection on the CameraSession (see CameraSessionConfiguration.automaticallyAdjustsColorSpace), and then configuring the CameraController with a custom colorspace via configure(...).

Example

Selecting a custom colorspace:

const session = ...
const device = ...
const srgbFormat = device.formats.find((f) =>
  f.supportedColorSpaces.includes('srgb')
)
if (srgbFormat != null) {
  // Configure session with that `srgb` format,
  // and disable automatic colorspace selection
  const [controller] = await session.configure([
    {
      input: device,
      outputs: [],
      format: srgbFormat
    }
  ], {
    automaticallyAdjustsColorSpace: false
  })
  // Select colorspace on controller
  await controller.configure({
    colorSpace: 'srgb'
  })
  await session.start()
}

device

readonly device: CameraDevice

Gets the CameraDevice this CameraController is bound to.

You can use the device to query support for available features.

Example

Querying if the device supports focus metering:

const controller = ...
if (controller.supportsFocusMetering) {
  const meteringPoint = ...
  controller.focusTo(meteringPoint, {
    modes: ['AF']
  })
}

displayableZoomFactor

readonly displayableZoomFactor: number

A user-displayable zoom factor.

Example

const controller = ...           // Triple-Camera
controller.zoom                  // 1
controller.displayableZoomFactor // 0.5

exposureBias

readonly exposureBias: number

Get the current exposure compensation bias.

A positive value (like 1) means over-exposed ("brighter"), whereas a negative value (like -1) means under-exposed ("darker"). The default exposure bias is 0.

You can set exposure bias to a supported value via setExposureBias(...).

exposureDuration

readonly exposureDuration: number

Represents the current exposure duration, in seconds.

The exposureDuration value changes over time (via continuous auto-focus/3A), when focused to a specific point (via focusTo(...)), or when locked to a specific duration/ISO value (via setExposureLocked(...)).

exposureMode

readonly exposureMode: ExposureMode

Represents the current ExposureMode.

• 'continuous-auto-exposure': The session is continuously adjusting AE as the scene changes. (the default)
• 'auto-exposure': The session is currently metering to a specific exposure value via focusTo(...).
• 'locked': The session is currently locked at a specific exposureDuration/iso via setExposureLocked(...).

focusMode

readonly focusMode: FocusMode

Represents the current FocusMode.

• 'continuous-auto-focus': The session is continuously adjusting AF as the scene changes. (the default)
• 'auto-focus': The session is currently metering to a specific focus length position via focusTo(...).
• 'locked': The session is currently locked at a specific lensPosition via setFocusLocked(...).

isConnected

readonly isConnected: boolean

Gets whether this CameraController is currently connected to the session.

isDistortionCorrectionEnabled

readonly isDistortionCorrectionEnabled: boolean

Gets whether geometric distortion correction is currently enabled.

You can enable or disable distortion correction via configure(...) if the CameraDevice supports distortion correction (see CameraDevice.supportsDistortionCorrection).

isLowLightBoostEnabled

readonly isLowLightBoostEnabled: boolean

Gets whether low light boost is currently enabled.

You can enable low light boost via configure(...).

Example

Enabling low light boost:

const controller = ...
if (controller.device.supportsLowLightBoost) {
  await controller.configure({ enableLowLightBoost: true })
}

iso

readonly iso: number

Represents the current ISO value.

The iso value changes over time (via continuous auto-focus/3A), when focused to a specific point (via focusTo(...)), or when locked to a specific duration/ISO value (via setExposureLocked(...)).

isSmoothAutoFocusEnabled

readonly isSmoothAutoFocusEnabled: boolean

Gets whether smooth auto-focus is currently enabled.

You can enable or disable smooth auto-focus via configure(...) if the CameraDevice supports smooth auto-focus (see CameraDevice.supportsSmoothAutoFocus).

isSuspended

readonly isSuspended: boolean

Gets whether this CameraController is currently suspended.

A CameraController may be suspended when the system receives an interruption, such as thermal pressure.

isUsedByAnotherApp

readonly isUsedByAnotherApp: boolean

Gets whether this CameraController is currently used by another app with higher priority Camera access, for example when multi-tasking on iPad.

lensPosition

readonly lensPosition: number

Represents the current focus length, from 0.0 (closest) to 1.0 (furthest).

The lensPosition changes over time (via continuous auto-focus/3A), when focused to a specific point (via focusTo(...)), or when locked to a specific lens-position value (via setFocusLocked(...)).

torchMode

readonly torchMode: TorchMode

Get the current TorchMode.

The torch can be enabled or disabled via setTorchMode(...).

torchStrength

readonly torchStrength: number

Get the current Torch's strength, which is a value from 0.0 (weakest) to 1.0 (brightest).

The torch's strength can be configured via setTorchMode('on', ...).

whiteBalanceGains

readonly whiteBalanceGains: WhiteBalanceGains

Represents the current white balance gains.

The whiteBalanceGains change over time (via continuous auto-focus/3A), when focused to a specific point (via focusTo(...)), or when locked to specific WhiteBalanceGains (via setWhiteBalanceLocked(...)).

whiteBalanceMode

readonly whiteBalanceMode: WhiteBalanceMode

Represents the current WhiteBalanceMode.

• 'continuous-auto-white-balance': The session is continuously adjusting AWB as the scene changes. (the default)
• 'auto-white-balance': The session is currently metering to a specific white-balance value via focusTo(...).
• 'locked': The session is currently locked at a specific whiteBalanceGains value via setWhiteBalanceLocked(...).

zoom

readonly zoom: number

Represents the current zoom value. Zoom can be set via setZoom(...).

Methods

cancelZoomAnimation()

cancelZoomAnimation(): Promise<void>

Cancels any zoom animations previously started with startZoomAnimation(...).

configure()

configure(config: CameraControllerConfiguration): Promise<void>

Configures this CameraController with the given CameraControllerConfiguration.

Like a diff-map, setting a value inside the config object to undefined, causes the prop to be left at whatever its current value is.

convertWhiteBalanceTemperatureAndTintValues()

convertWhiteBalanceTemperatureAndTintValues(whiteBalanceTemperatureAndTint: WhiteBalanceTemperatureAndTint): WhiteBalanceGains

Converts the given whiteBalanceTemperatureAndTint values to WhiteBalanceGains.

focusTo()

focusTo(point: MeteringPoint, options: FocusOptions): Promise<void>

Focuses the Camera pipeline to the specified MeteringPoint, using the specified MeteringModes.

By default, all 3A metering modes are enabled - AE, AF and AWB - also known as 3A.

The returned Promise resolves once focusing has been fully settled, or rejects if the focusing operation timed out or was canceled. A focus operation can be canceled by calling focusTo(...) again, or by calling resetFocus().

After the metering operation has settled, the Camera pipeline either keeps the specified MeteringPoint continuously focused even if the scene at the specific point changes ('continuous'), or locks the focus/exposure/white-balance values in-place ('locked'). You can adjust this behaviour via FocusOptions.adaptiveness.

Parameters

point

The MeteringPoint to focus to.

options

Options for this focus operation.

Examples

Focus center:

const point = HybridCameraFactory.createNormalizedMeteringPoint(0.5, 0.5)
await controller.focusTo(point, { responsiveness: 'steady' })

Focus on tap

const onViewTapped = (tapX: number, tapY: number) => {
  const point = previewViewRef.createMeteringPoint(tapX, tapY)
  await controller.focusTo(point, { responsiveness: 'snappy' })
}

Lock focus until controller.resetFocus() is called:

const point = previewViewRef.createMeteringPoint(tapX, tapY)
await controller.focusTo(point, {
  responsiveness: 'snappy',
  adaptiveness: 'locked',
  autoResetAfter: null
})

lockCurrentExposure()

lockCurrentExposure(): Promise<void>

Locks the current exposure values.

You can read the current exposure values via exposureDuration and iso.

Example

const controller = ...
if (controller.device.supportsExposureLocking) {
  await controller.lockCurrentExposure()
}

lockCurrentFocus()

lockCurrentFocus(): Promise<void>

Locks the current focus values.

You can read the current focus values via lensPosition.

Example

const controller = ...
if (controller.device.supportsFocusLocking) {
  await controller.lockCurrentFocus()
}

lockCurrentWhiteBalance()

lockCurrentWhiteBalance(): Promise<void>

Locks the current white-balance values.

You can read the current white-balance values via whiteBalanceGains.

Example

const controller = ...
if (controller.device.supportsWhiteBalanceLocking) {
  await controller.lockCurrentWhiteBalance()
}

resetFocus()

resetFocus(): Promise<void>

Cancels any current focus operations from focusTo(...), resets back all 3A focus modes to continuously auto-focus, and resets the focus point of interest to be in the center.

Example

await controller.resetFocus()

setExposureBias()

setExposureBias(exposure: number): Promise<void>

Sets the exposureBias to the given exposure bias value.

A positive value (like 1) means over-exposed ("brighter"), whereas a negative value (like -1) means under-exposed ("darker"). The default exposure bias is 0.

Example

Set Camera to maximum exposure:

const controller = ...
if (controller.device.supportsExposureBias) {
  const maxExposure = controller.device.maxExposureBias
  await controller.setExposureBias(maxExposure)
}

setExposureLocked()

setExposureLocked(duration: number, iso: number): Promise<void>

Locks the exposure at the specified duration and iso value.

Parameters

duration

The duration in seconds a single shutter is timed at. It must be a value between the currently selected format's CameraFormat.minExposureDuration and CameraFormat.maxExposureDuration.

iso

The ISO value for the Camera. It must be a value between the currently selected format's CameraFormat.minISO and CameraFormat.maxISO.

setFocusLocked()

setFocusLocked(lensPosition: number): Promise<void>

Locks the focus at the specified lensPosition.

Parameters

lensPosition

The position of the Camera lens, from 0.0 (closest) to 1.0 (furthest).

setTorchMode()

setTorchMode(mode: TorchMode, strength?: number): Promise<void>

Sets the torch to the specified mode.

• When mode == 'on', you can pass strength to configure the Torch's strength, from 0.0 to 1.0.
• When mode != 'on', the strength parameter is ignored.

setWhiteBalanceLocked()

setWhiteBalanceLocked(whiteBalanceGains: WhiteBalanceGains): Promise<void>

Locks the white-balance at the specified whiteBalanceGains value.

Parameters

whiteBalanceGains

The WhiteBalanceGains values. Each channel's value must be within 1 and the current device's maxWhiteBalanceGain value.

setZoom()

setZoom(zoom: number): Promise<void>

Sets the Camera's zoom to the specified zoom value.

Example

Zoom to the maximum:

const controller = ...
const maxZoom = controller.device.maxZoom
await controller.setZoom(maxZoom)

startZoomAnimation()

startZoomAnimation(zoom: number, rate: number): Promise<void>

Starts animating the Camera's zoom to the specified zoom value, at the specified rate.

Example

Zoom to the maximum:

const controller = ...
const maxZoom = controller.device.maxZoom
await controller.startZoomAnimation(maxZoom, 2)