AVCaptureDevice: focusMode property
The focusMode property indicates how the camera focuses.
Value
A string, one of these three:
| Value | Effect |
|---|---|
'continuousAutoFocus' | Keeps focusing automatically: when things in the picture move nearer or farther, the camera refocuses |
'autoFocus' | Focuses once, then locks |
'locked' | The focus is locked and doesn't move |
- Readable and writable.
- Default: measured as
'continuousAutoFocus'on the rear camera of an iPhone 14. That's fine for scanning; no need to change it. - Call
lockForConfiguration()before writing it, andunlockForConfiguration()afterwards. - Ask which modes a camera supports with
isFocusModeSupported(). - After writing, it reads back as the written value (verified by testing). The effect of focusing on the picture is not verified on a device.
- After changing
focusPointOfInterest, writefocusModeonce more for the new focus point to take effect. This is not verified on a device. - Whether the value reads
'locked'after'autoFocus'finishes focusing is not verified on a device. - There is no event when it changes.
Invalid values
- Writing without the lock: throws a
DOMExceptionwhosenameis'InvalidStateError', and the value doesn't change (verified by testing). The message isfocusMode: the system refused (…); the parentheses hold the reason the system gave, which says to lock first (-lockForConfiguration:). - The camera doesn't support this mode: the system refuses, and it throws a
DOMExceptionwhosenameis'InvalidStateError', with the reason the system gave in the message. Not verified on a device. - Writing a value not in the table doesn't throw: a warning listing all valid values is printed to the console, and
focusModekeeps its previous value (verified by testing).
Examples
js
const device = AVCaptureDevice.defaultDeviceWithMediaType('video');
if (device !== null && device.isFocusModeSupported('locked')) {
device.lockForConfiguration();
try {
device.focusMode = 'locked';
} finally {
device.unlockForConfiguration();
}
console.log(device.focusMode);
}Effect: the focus is locked, and locked is printed.
Corresponding iOS API
AVCaptureDevice.focusMode. AVCaptureFocusModeContinuousAutoFocus is written as 'continuousAutoFocus', and so on. In ObjC, writing without the lock throws NSGenericException; here it throws a DOMException whose name is 'InvalidStateError'.
See also
isFocusModeSupported(): whether a mode is supportedfocusPointOfInterest: the focus pointautoFocusRangeRestriction: which distance autofocus searches