Metering

We refer to metering as the act of gauging the scene luminosity, depth and color and adjusting the camera sensor settings for optimal results. It's what happens, for instance, when you tap on screen to focus on a certain subject.

The CameraMeter APIs will help you implement things like "tap to focus" functionality and exposure, focus and/or white balance locking. You can find them in the CameraMeter class:

swift
Copy
let device: CameraDevice = ...
guard let meter: CameraMeter = device.meter else { return } // Device is not open?

kotlin
Copy
val device: CameraDevice = ...
val meter: CameraMeter = device.meter ?: return // Device is not open?

All APIs provide fine-grained metering control. For example, you may lock focus while running an exposure and white balance routine.

Default behavior

Continuous Metering

By default, camera sensors will continuously meter the scene to improve output. This may be disabled in certain scenarios:

• for exposure, it's always enabled
• for focus, it's always enabled as long as the device supports it (front cameras sometimes won't)
• for white balance, it's enabled if the device supports it and if CameraConfiguration.whiteBalance is set to WhiteBalance.AutoWhiteBalance.auto, which is the default value

Picture Metering

By default, when taking pictures, a special metering routine will take place to improve the output and ensure maximum quality in terms of exposure, focus and white balance. This can be disabled by passing false to the meterIfNeeded parameter, as explained in the pictures documentation.

Scanning

Whenever your application determines that a new metering routine should be started, you can use CameraMeter.scan(). This API should be used, for example, to implement "tap to focus" in your app.

kotlin
Copy
// CameraMeter API
suspend fun scan(
    center: Point?,
    surface: String?,
    lockDuration: Long = 6000,
    exposure: Boolean = true,
    focus: Boolean = true,
    whiteBalance: Boolean = true,
    throwIfUnsupported: Boolean = false,
) { ... }

swift
Copy
// CameraMeter API
func scan(
    center: Point?,
    surface: String?,
    lockDuration: TimeInterval = 6.0,
    exposure: Bool = true,
    focus: Bool = true,
    whiteBalance: Bool = true,
    throwIfUnsupported: Bool = false
) async throws { ... }

Let's go through the parameters:

• center: a x/y pair of normalized coordinates that you get from your gesture detection logic. Coordinates should be in the 0...1 range, and you should make make sure that the exact name of the preview surface is passed to surface as well.
• surface: the name of the preview surface that center refers to, very important for orientation calculations that are needed under the hood. If absent, engine will assume the first valid preview is the desired one.
• lockDuration: in principle, metering only makes sense if the updated values are kept for a while. Pass an infinite or non-positive value to lock forever.
• exposure: whether exposure should be adjusted.
• focus: whether focus should be adjusted.
• whiteBalance: whether white balance should be adjusted.
• throwIfUnsupported: whether scan should throw an error if any of the routines (AE, AF, AWB) are unsupported by the device. You typically want to keep this false which in practical terms means "do your best".

The function returns after scan is complete, without waiting for the lock duration.

Metering Modes

During device configuration, you can decide how scan() calls will handle center locations:

You can inspect which modes are supported by checking the device capabilities.

Locking and unlocking

In addition to the scan() APIs, you can also lock - as with scan, with fine-grained routine control - the settings to their current values, and unlock later. To lock:

kotlin
Copy
// CameraMeter API
suspend fun lock(
    duration: Long = -1L,
    exposure: Boolean = true,
    focus: Boolean = true,
    whiteBalance: Boolean = true,
    throwIfUnsupported: Boolean = false,
) { ... }

swift
Copy
// CameraMeter API
func lock(
    duration: TimeInterval = -1.0,
    exposure: Bool = true,
    focus: Bool = true,
    whiteBalance: Bool = true,
    throwIfUnsupported: Bool = false
) async throws { ... }

The duration property determines how long the settings should be locked for. Non-positive or infinite values mean locking forever. To unlock:

kotlin
Copy
// CameraMeter API
suspend fun unlock(
    exposure: Boolean = true,
    focus: Boolean = true,
    whiteBalance: Boolean = true,
) { ... }

swift
Copy
// CameraMeter API
func unlock(
    exposure: Bool = true,
    focus: Bool = true,
    whiteBalance: Bool = true
) async throws { ... }

Scene state

Using any of the metering APIs will change the sensor's understanding of the scene, represented by CameraScene. Use CameraDevice.scene to retrieve it:

kotlin
Copy
val current: CameraScene? = device.scene.value
val flow: StateFlow<CameraScene?> = device.scene

swift
Copy
let current: CameraScene? = device.scene
let publisher: AnyPublisher<CameraScene?, Never> = device.scenePublisher

In the scene, you'll find a status enum for each of the three parameters (exposure, focus and white balance). This can be used to implement things like touch-to-focus markers on screen, or deciding when to take a picture for best results.