---
title: "setWhiteBalanceModeLocked(with:completionHandler:)"
framework: avfoundation
role: symbol
role_heading: Instance Method
path: "avfoundation/avcapturedevice/setwhitebalancemodelocked(with:completionhandler:)"
---

# setWhiteBalanceModeLocked(with:completionHandler:)

Sets the white balance to locked mode with the specified white balance gains.

## Declaration

```swift
func setWhiteBalanceModeLocked(with whiteBalanceGains: AVCaptureDevice.WhiteBalanceGains, completionHandler handler: (@Sendable (CMTime) -> Void)? = nil)
```

```swift
func setWhiteBalanceModeLocked(with whiteBalanceGains: AVCaptureDevice.WhiteBalanceGains) async -> CMTime
```

## Parameters

- `whiteBalanceGains`: The white balance gains to set. Pass a value of doc://com.apple.avfoundation/documentation/AVFoundation/AVCaptureDevice/currentWhiteBalanceGains to leave the current white balance unchanged.
- `handler`: A callback the system invokes when the adjustment to the white balance is complete and the doc://com.apple.avfoundation/documentation/AVFoundation/AVCaptureDevice/whiteBalanceMode-swift.property set to a locked state. If you call this method multiple times, the system calls the completion handlers in FIFO order. The system passes a time value that matches that of the first buffer to which its applied all settings. It synchronizes the timestamp to the device clock, and you must convert the timestamp to the doc://com.apple.avfoundation/documentation/AVFoundation/AVCaptureSession/synchronizationClock prior to comparison with the timestamps of buffers delivered through an doc://com.apple.avfoundation/documentation/AVFoundation/AVCaptureVideoDataOutput. You can pass nil for this parameter if you don’t require this information.

## Discussion

Discussion Each channel in the white balance gains structure supports values between 1.0 and maxWhiteBalanceGain. Setting a channel value outside this range generates an exception. The system normalizes gain values to the minimum channel value to avoid brightness changes (for example, R:2 G:2 B:4 normalizes to R:1 G:1 B:2). Before changing the value the white balance gains, you must call lockForConfiguration() to acquire exclusive access to the device’s configuration properties. Otherwise, setting the value of this property raises an exception. When you finish configuring the device, call unlockForConfiguration() to release the lock and allow other devices to configure the settings.

## Topics

### White balance constants

- [currentWhiteBalanceGains](avfoundation/avcapturedevice/currentwhitebalancegains.md)

## See Also

### Setting white balance manually

- [isLockingWhiteBalanceWithCustomDeviceGainsSupported](avfoundation/avcapturedevice/islockingwhitebalancewithcustomdevicegainssupported.md)
- [setWhiteBalanceModeLocked(whiteBalanceTemperatureAndTintValues:handler:)](avfoundation/avcapturedevice/setwhitebalancemodelocked(whitebalancetemperatureandtintvalues:handler:).md)