AVCaptureDevice: rampToVideoZoomFactor() method
The rampToVideoZoomFactor() method zooms the picture smoothly to a given factor at a given speed, instead of jumping there at once.
Syntax
rampToVideoZoomFactor(factor, { withRate })Parameters
factor
The target factor, a number. Converted with Number(). Should be between minAvailableVideoZoomFactor and maxAvailableVideoZoomFactor.
options.withRate
The speed, a number, required. Each second the picture zooms by a factor of 2 to the power of withRate: 1 doubles the zoom each second, 2 quadruples it. Converted with Number().
Return value
None (undefined). The method returns right away, and the zoom happens over the following moments. That the zoom is visible in the picture is not verified on a device. There is no event when the zoom finishes.
Exceptions
TypeError
withRateis missing:rampToVideoZoomFactor needs options.withRate(verified by testing).factorcan't be converted to a finite number:rampToVideoZoomFactor must be a finite number, got ….withRatecan't be converted to a finite number:withRate must be a finite number, got ….- The system refuses the factor for a reason that isn't one of the two below. Which values are refused is not verified on a device.
RangeError, DOMException
When the system refuses, the exception depends on the system's reason: RangeError when the system says a value is out of range, a DOMException whose name is 'InvalidStateError' when it says the current state doesn't allow it, and TypeError otherwise. The message is rampToVideoZoomFactor: the system refused (…), with the reason the system gave in the parentheses. This comes from the code and is not verified on a device.
Description
- Calling it without
lockForConfiguration()doesn't throw either (verified by testing). It's still best to call it while holding the lock, together with other settings. - To stop midway, call
cancelVideoZoomRamp().
Examples
const device = AVCaptureDevice.defaultDeviceWithMediaType('video');
if (device !== null) {
device.lockForConfiguration();
try {
device.rampToVideoZoomFactor(Math.min(2, device.maxAvailableVideoZoomFactor), { withRate: 4 });
} finally {
device.unlockForConfiguration();
}
}Effect: the picture zooms smoothly to 2× in a short time. Not verified on a device.
Corresponding iOS API
-[AVCaptureDevice rampToVideoZoomFactor:withRate:]. The second part goes in an options object: { withRate }.
See also
videoZoomFactor: set the factor directlycancelVideoZoomRamp(): stop- Zoom in