Locking AE/AF/AWB

import { Tab, Tabs } from 'fumadocs-ui/components/tabs'

Exposure, Focus and White-Balance are typically automatically adjusted as the scene changes. For pro-Camera apps, you can manually adjust Exposure Duration/ISO, Focus Lens Position and White-Balance Temperature and Tint Value and lock them in-place, if the device supports it.

Setting specific values

Setting custom Exposure Duration/ISO

If the CameraDevice supports Exposure Locking (see supportsExposureLocking) you can set a custom Exposure Duration/ISO via setExposureLocked(...):

const controller = ...
const format = ...
if (controller.device.supportsExposureLocking) {
  const exposureDuration = 1 / 60
  const iso = 200
  await controller.setExposureLocked(exposureDuration, iso)
}

[!WARNING] Make sure the given exposureDuration value is inside the current CameraController's minExposureDuration and maxExposureDuration bounds.

Make sure the given iso value is inside the currently selected CameraController's minISO and maxISO bounds.

Setting custom Focus Lens Position

If the CameraDevice supports Focus Locking (see supportsFocusLocking) you can set a custom Focus Lens Position via setFocusLocked(...):

const controller = ...
if (controller.device.supportsFocusLocking) {
  const lensPosition = 0.5
  await controller.setFocusLocked(lensPosition)
}

[!WARNING] Make sure the given lensPosition value is between 0.0 and 1.0.

Setting custom White Balance Temperature and Tint

If the CameraDevice supports White-Balance Locking (see supportsWhiteBalanceLocking) you can set custom White Balance Temperature and Tint values via setWhiteBalanceLocked(...):

const controller = ...
if (controller.device.supportsWhiteBalanceLocking) {
  const temperature = 4500
  const tint = 20
  await controller.setWhiteBalanceLocked(temperature, tint)
}

[!WARNING] A good range for temperature is between 2500K and 8000K, and a good value for tint is usually between -150 and 150.

Getting current values

At any point in time you can get the Camera's current Exposure, Focus or White-Balance values.

Getting current Exposure Duration/ISO

To get the current exposure values (for example to use VisionCamera as a light meter) use exposureDuration or iso:

const controller = ...
console.log(controller.exposureDuration)
console.log(controller.iso)

Getting current Focus Lens Position

To figure out how far away the current focus point is, simply get the current lensPosition:

const controller = ...
console.log(controller.lensPosition) // between 0...1

Getting current White Balance Gains

Lastly, the CameraController also exposes its current White-Balance Gains via whiteBalanceGains:

const controller = ...
console.log(controller.whiteBalanceGains)

[!WARNING] If the device does not support manual control over AE/AF/AWB, invalid values (e.g. 0) will be returned.

Locking current values

To lock the current Exposure/Focus/White-Balance values at their current value (for example, after a tap to focus action), use lockCurrentExposure(), lockCurrentFocus() or lockCurrentWhiteBalance():

const controller = ...
const meteringPoint = ...
await controller.focusTo(meteringPoint, {
  autoResetAfter: null
})

if (controller.device.supportsExposureLocking) {
  await controller.lockCurrentExposure()
}
if (controller.device.supportsFocusLocking) {
  await controller.lockCurrentFocus()
}
if (controller.device.supportsWhiteBalanceLocking) {
  await controller.lockCurrentWhiteBalance()
}

To reset Exposure/Focus/White-Balance back to auto, use resetFocus():

const controller = ...
await controller.resetFocus()

Reacting to subject area changes

Once you lock AE/AF/AWB, the Camera keeps those values frozen no matter what the user points the device at. That's usually fine for a deliberate tap-to-focus, but if the user pans the Camera away from the subject, the scene becomes very under- or over-exposed and out-of-focus; so the locked values no longer make sense.

VisionCamera fires an onSubjectAreaChanged() listener whenever the scene substantially changes - for example, when the focus point drifts off the previously-focused subject. You can listen for this event and automatically reset AE/AF/AWB back to continuously auto-adjusting via resetFocus():

<Tabs items={["<Camera /> (view)", "useCamera(...) (hook)", "CameraSession (imperative)"]} groupId="api-style" persist> <Tab value="<Camera /> (view)">

function App() {
  const camera = useRef<Camera>(null)

  return (
    <Camera
      style={StyleSheet.absoluteFill}
      isActive={true}
      device="back"
      ref={camera}
      // [!code ++:3]
      onSubjectAreaChanged={() => {
        camera.current?.resetFocus()
      }}
    />
  )
}