Skip to main content

camera/
controls.rs

1//! Controls carry units and report whether readback is actual or only requested.
2use crate::api::CaptureSession;
3use crate::backends::BackendCamera;
4use crate::{
5    BackendType, CameraControlType as Raw, CameraControlValue as RawValue, CameraError,
6    CameraResult,
7};
8#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
9/// Backend-neutral identifier for a camera control.
10pub enum ControlId {
11    /// The `ExposureMode` variant.
12    ExposureMode,
13    /// The `ExposureTime` variant.
14    ExposureTime,
15    /// The `ExposureCompensation` variant.
16    ExposureCompensation,
17    /// The `FocusMode` variant.
18    FocusMode,
19    /// The `FocusPosition` variant.
20    FocusPosition,
21    /// The `WhiteBalanceMode` variant.
22    WhiteBalanceMode,
23    /// The `WhiteBalanceTemperature` variant.
24    WhiteBalanceTemperature,
25    /// The `Zoom` variant.
26    Zoom,
27    /// The `Brightness` variant.
28    Brightness,
29    /// The `Contrast` variant.
30    Contrast,
31    /// The `Hue` variant.
32    Hue,
33    /// The `Saturation` variant.
34    Saturation,
35    /// The `Sharpness` variant.
36    Sharpness,
37    /// The `Gamma` variant.
38    Gamma,
39    /// The `BacklightCompensation` variant.
40    BacklightCompensation,
41    /// The `Gain` variant.
42    Gain,
43    /// The `Pan` variant.
44    Pan,
45    /// The `Tilt` variant.
46    Tilt,
47    /// The `Iris` variant.
48    Iris,
49}
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51/// Unit or representation used by a numeric control value.
52pub enum ControlUnit {
53    /// The `Boolean` variant.
54    Boolean,
55    /// The `Mode` variant.
56    Mode,
57    /// The `Native` variant.
58    Native,
59    /// The `HundredMicroseconds` variant.
60    HundredMicroseconds,
61    /// The `Log2Seconds` variant.
62    Log2Seconds,
63    /// The `MilliEv` variant.
64    MilliEv,
65    /// The `CompensationIndex` variant.
66    CompensationIndex,
67    /// The `Kelvin` variant.
68    Kelvin,
69    /// The `Percent` variant.
70    Percent,
71    /// The `Degrees` variant.
72    Degrees,
73    /// The `ArcSeconds` variant.
74    ArcSeconds,
75    /// The `Iso` variant.
76    Iso,
77}
78#[derive(Clone, Copy, Debug, PartialEq, Eq)]
79/// Common operating modes for automatic and manual controls.
80pub enum ControlMode {
81    /// The `Manual` variant.
82    Manual,
83    /// The `Automatic` variant.
84    Automatic,
85    /// The `Locked` variant.
86    Locked,
87    /// The `Single` variant.
88    Single,
89    /// The `Continuous` variant.
90    Continuous,
91}
92#[derive(Clone, Debug, PartialEq)]
93/// Numeric or mode value accepted by the control API.
94pub enum ControlValue {
95    /// The `Number` variant.
96    Number(f64),
97    /// The `Mode` variant.
98    Mode(ControlMode),
99}
100#[derive(Clone, Debug, PartialEq)]
101/// Indicates whether a returned value is measured, requested, or unavailable.
102pub enum ControlReadback {
103    /// Value confirmed by the camera backend.
104    Actual(ControlValue),
105    /// Requested value retained because the backend cannot read it back.
106    Requested(ControlValue),
107    /// The backend cannot report either an actual or requested value.
108    Unknown,
109}
110#[derive(Clone, Copy, Debug, PartialEq, Eq)]
111/// Validated white-balance temperature in kelvin.
112pub struct Kelvin(u32);
113impl Kelvin {
114    /// Creates a temperature in the supported 1,000–40,000 K range.
115    pub fn new(value: u32) -> CameraResult<Self> {
116        if !(1_000..=40_000).contains(&value) {
117            return Err(CameraError::invalid_config(
118                "White-balance temperature must be 1000..=40000 K".into(),
119            ));
120        }
121        Ok(Self(value))
122    }
123    /// Returns the temperature in kelvin.
124    pub const fn get(self) -> u32 {
125        self.0
126    }
127}
128#[derive(Clone, Copy, Debug, PartialEq, Eq)]
129/// Possible values for `Exposure`.
130pub enum Exposure {
131    /// The `Auto` variant.
132    Auto,
133    /// The `Manual` variant.
134    Manual(std::time::Duration),
135}
136#[derive(Clone, Copy, Debug, PartialEq, Eq)]
137/// Possible values for `WhiteBalance`.
138pub enum WhiteBalance {
139    /// The `Auto` variant.
140    Auto,
141    /// The `Temperature` variant.
142    Temperature(Kelvin),
143}
144#[derive(Clone, Copy, Debug, PartialEq)]
145/// Possible values for `Focus`.
146pub enum Focus {
147    /// The `Auto` variant.
148    Auto,
149    /// The `Position` variant.
150    Position(f64),
151}
152#[derive(Clone, Debug)]
153/// Numeric limits and optional default for a camera control.
154pub struct ControlRange {
155    /// The min value.
156    pub min: f64,
157    /// The max value.
158    pub max: f64,
159    /// The step value.
160    pub step: Option<f64>,
161    /// The default value.
162    pub default: Option<ControlValue>,
163}
164#[derive(Clone, Debug)]
165/// Capabilities and access rules for one camera control.
166pub struct ControlDescriptor {
167    /// The id value.
168    pub id: ControlId,
169    /// The unit value.
170    pub unit: ControlUnit,
171    /// The readable value.
172    pub readable: bool,
173    /// The writable value.
174    pub writable: Option<bool>,
175    /// The range value.
176    pub range: Option<ControlRange>,
177    /// The modes value.
178    pub modes: Vec<ControlMode>,
179    /// Some controls only apply while the associated automatic mode is disabled.
180    pub requires_manual: Option<ControlId>,
181}
182#[derive(Debug)]
183/// Result of applying one item from a batch of control changes.
184pub struct ControlOutcome {
185    /// The id value.
186    pub id: ControlId,
187    /// The result value.
188    pub result: CameraResult<()>,
189}
190fn mapping(backend: BackendType, id: ControlId) -> CameraResult<(Raw, ControlUnit)> {
191    use ControlId::*;
192    use ControlUnit as U;
193    let av = backend == BackendType::AVFoundation;
194    let c2 = backend == BackendType::Camera2;
195    let unsupported = || CameraError::control_not_supported(format!("{id:?} on {backend}"));
196    Ok(match id {
197        ExposureMode => (if av { Raw::Exposure } else { Raw::AutoExposure }, U::Mode),
198        ExposureTime if av || c2 => return Err(unsupported()),
199        ExposureTime => (
200            Raw::Exposure,
201            if backend == BackendType::MediaFoundation {
202                U::Log2Seconds
203            } else {
204                U::HundredMicroseconds
205            },
206        ),
207        ExposureCompensation if av => (Raw::Brightness, U::MilliEv),
208        ExposureCompensation if c2 => (Raw::Exposure, U::CompensationIndex),
209        ExposureCompensation => return Err(unsupported()),
210        FocusMode => (if av { Raw::Focus } else { Raw::AutoFocus }, U::Mode),
211        WhiteBalanceMode => (
212            if av {
213                Raw::WhiteBalance
214            } else {
215                Raw::AutoWhiteBalance
216            },
217            U::Mode,
218        ),
219        FocusPosition if av || c2 => return Err(unsupported()),
220        FocusPosition => (Raw::Focus, U::Native),
221        WhiteBalanceTemperature if av || c2 => return Err(unsupported()),
222        WhiteBalanceTemperature => (Raw::WhiteBalance, U::Kelvin),
223        Brightness if av || c2 => return Err(unsupported()),
224        Brightness => (Raw::Brightness, U::Native),
225        Contrast => (Raw::Contrast, U::Native),
226        Hue => (Raw::Hue, U::Native),
227        Saturation => (Raw::Saturation, U::Native),
228        Sharpness => (Raw::Sharpness, U::Native),
229        Gamma => (Raw::Gamma, U::Native),
230        BacklightCompensation => (Raw::BacklightCompensation, U::Native),
231        Gain => (Raw::Gain, if c2 { U::Iso } else { U::Native }),
232        Zoom => (Raw::Zoom, if av || c2 { U::Percent } else { U::Native }),
233        Pan => (Raw::Pan, U::Native),
234        Tilt => (Raw::Tilt, U::Native),
235        Iris => (Raw::Iris, U::Native),
236    })
237}
238const IDS: &[ControlId] = &[
239    ControlId::ExposureMode,
240    ControlId::ExposureTime,
241    ControlId::ExposureCompensation,
242    ControlId::FocusMode,
243    ControlId::FocusPosition,
244    ControlId::WhiteBalanceMode,
245    ControlId::WhiteBalanceTemperature,
246    ControlId::Zoom,
247    ControlId::Brightness,
248    ControlId::Contrast,
249    ControlId::Hue,
250    ControlId::Saturation,
251    ControlId::Sharpness,
252    ControlId::Gamma,
253    ControlId::BacklightCompensation,
254    ControlId::Gain,
255    ControlId::Pan,
256    ControlId::Tilt,
257    ControlId::Iris,
258];
259fn decode(backend: BackendType, id: ControlId, value: RawValue) -> CameraResult<ControlValue> {
260    let (_, unit) = mapping(backend, id)?;
261    if unit == ControlUnit::Mode {
262        let mode = if backend == BackendType::AVFoundation {
263            match value.as_i32() {
264                Some(0) => ControlMode::Locked,
265                Some(1) => ControlMode::Single,
266                Some(2) => ControlMode::Continuous,
267                _ => {
268                    return Err(CameraError::control_not_readable(
269                        "Unknown native mode".into(),
270                    ))
271                }
272            }
273        } else if value.as_bool().unwrap_or(false) {
274            ControlMode::Automatic
275        } else {
276            ControlMode::Manual
277        };
278        Ok(ControlValue::Mode(mode))
279    } else {
280        Ok(ControlValue::Number(match value {
281            RawValue::Float(v) => v as f64,
282            _ => value
283                .as_i32()
284                .ok_or_else(|| CameraError::control_not_readable("Native numeric value".into()))?
285                as f64,
286        }))
287    }
288}
289fn describe_range(
290    backend: BackendType,
291    id: ControlId,
292    raw: Raw,
293    range: crate::CameraControlRange,
294) -> ControlRange {
295    ControlRange {
296        min: range.min as f64,
297        max: range.max as f64,
298        step: (range.step > 0).then_some(range.step as f64),
299        default: if backend == BackendType::Camera2 {
300            None
301        } else {
302            decode(
303                backend,
304                id,
305                if raw.is_auto_control() {
306                    RawValue::Boolean(range.default != 0)
307                } else {
308                    RawValue::manual(range.default)
309                },
310            )
311            .ok()
312        },
313    }
314}
315fn descriptor(camera: &BackendCamera, id: ControlId) -> CameraResult<ControlDescriptor> {
316    let backend = camera.backend_type();
317    let (raw, unit) = mapping(backend, id)?;
318    if !camera.supports_control(raw) {
319        return Err(CameraError::control_not_supported(format!("{id:?}")));
320    }
321    let readable = backend != BackendType::Camera2 && camera.get_control(raw).is_ok();
322    let range = camera
323        .get_control_range(raw)
324        .ok()
325        .map(|r| describe_range(backend, id, raw, r));
326    #[allow(unused_mut)]
327    let mut modes = if unit == ControlUnit::Mode {
328        if backend == BackendType::AVFoundation {
329            vec![
330                ControlMode::Locked,
331                ControlMode::Single,
332                ControlMode::Continuous,
333            ]
334        } else {
335            vec![ControlMode::Manual, ControlMode::Automatic]
336        }
337    } else {
338        vec![]
339    };
340    #[allow(unused_mut)]
341    let mut writable = None;
342    #[allow(unreachable_patterns)]
343    match camera {
344        #[cfg(all(
345            any(feature = "native", feature = "backend-camera2"),
346            target_os = "android"
347        ))]
348        BackendCamera::Camera2(c) => {
349            if unit == ControlUnit::Mode {
350                modes = c
351                    .supported_modes(raw)?
352                    .into_iter()
353                    .filter_map(|value| camera2_mode(id, value))
354                    .collect();
355                modes.dedup();
356                writable = Some(!modes.is_empty());
357            } else {
358                writable = range.as_ref().map(|r| r.max > r.min);
359            }
360        }
361        #[cfg(all(
362            feature = "backend-uvc",
363            any(target_os = "linux", target_os = "macos", target_os = "android")
364        ))]
365        BackendCamera::Uvc(c) if id == ControlId::ExposureMode => {
366            modes = c.exposure_modes()?;
367        }
368        #[cfg(all(
369            any(feature = "native", feature = "backend-avfoundation"),
370            any(target_os = "macos", target_os = "ios")
371        ))]
372        BackendCamera::AVFoundation(c) => {
373            writable = Some(true);
374            if unit == ControlUnit::Mode {
375                modes = c
376                    .supported_modes(raw)?
377                    .into_iter()
378                    .filter_map(|v| match decode(backend, id, RawValue::manual(v)).ok()? {
379                        ControlValue::Mode(m) => Some(m),
380                        _ => None,
381                    })
382                    .collect();
383                writable = Some(!modes.is_empty());
384            }
385        }
386        #[cfg(camera_v4l2)]
387        BackendCamera::V4l2(c) => {
388            writable = Some(c.control_writable(raw)?);
389        }
390        _ => {}
391    }
392    let requires_manual = match id {
393        ControlId::ExposureTime => Some(ControlId::ExposureMode),
394        ControlId::FocusPosition => Some(ControlId::FocusMode),
395        ControlId::WhiteBalanceTemperature => Some(ControlId::WhiteBalanceMode),
396        _ => None,
397    };
398    Ok(ControlDescriptor {
399        id,
400        unit,
401        readable,
402        writable,
403        range,
404        modes,
405        requires_manual,
406    })
407}
408impl CaptureSession {
409    pub async fn controls(&self) -> CameraResult<Vec<ControlDescriptor>> {
410        if self.device().id.backend() == &crate::BackendId::SYNTHETIC {
411            return Ok(Vec::new());
412        }
413        self.with_native(|c| {
414            let mut controls = Vec::new();
415            for &id in IDS {
416                match descriptor(&c, id) {
417                    Ok(descriptor) => controls.push(descriptor),
418                    Err(error) if error.kind() == crate::CameraErrorKind::ControlNotSupported => {}
419                    Err(error) => return Err(error),
420                }
421            }
422            Ok(controls)
423        })
424        .await
425    }
426    pub async fn control(&self, id: ControlId) -> CameraResult<ControlReadback> {
427        let actual = self
428            .with_native(move |c| {
429                let (raw, _) = mapping(c.backend_type(), id)?;
430                decode(c.backend_type(), id, c.get_control(raw)?)
431            })
432            .await;
433        match actual {
434            Ok(v) => Ok(ControlReadback::Actual(v)),
435            Err(error) if error.kind() == crate::CameraErrorKind::ControlNotReadable => Ok(self
436                .requested_control(id)
437                .map_or(ControlReadback::Unknown, ControlReadback::Requested)),
438            Err(e) => Err(e),
439        }
440    }
441    pub async fn set_control(&self, id: ControlId, value: ControlValue) -> CameraResult<()> {
442        let requested = value.clone();
443        self.with_native(move |c| {
444            let backend = c.backend_type();
445            let (raw, unit) = mapping(backend, id)?;
446            let desc = descriptor(&c, id)?;
447            if desc.writable == Some(false) {
448                return Err(CameraError::control_not_supported(
449                    "Read-only control".into(),
450                ));
451            }
452            let raw_value = match value {
453                ControlValue::Mode(mode) if unit == ControlUnit::Mode => {
454                    if !desc.modes.contains(&mode) {
455                        return Err(CameraError::invalid_config("Invalid control mode".into()));
456                    }
457                    #[cfg(all(
458                        any(feature = "native", feature = "backend-camera2"),
459                        target_os = "android"
460                    ))]
461                    #[allow(irrefutable_let_patterns)]
462                    if let BackendCamera::Camera2(native) = &c {
463                        let value = native
464                            .supported_modes(raw)?
465                            .into_iter()
466                            .find(|&value| camera2_mode(id, value) == Some(mode))
467                            .ok_or_else(|| {
468                                CameraError::control_not_supported("Camera2 mode".into())
469                            })?;
470                        return c.set_control(raw, RawValue::manual(value));
471                    }
472                    if backend == BackendType::AVFoundation {
473                        RawValue::manual(match mode {
474                            ControlMode::Locked => 0,
475                            ControlMode::Single => 1,
476                            ControlMode::Continuous => 2,
477                            _ => unreachable!(),
478                        })
479                    } else {
480                        RawValue::Boolean(mode == ControlMode::Automatic)
481                    }
482                }
483                ControlValue::Number(v) if unit != ControlUnit::Mode => {
484                    if !v.is_finite()
485                        || v.fract() != 0.0
486                        || v < i32::MIN as f64
487                        || v > i32::MAX as f64
488                    {
489                        return Err(CameraError::invalid_config(
490                            "Native control expects a finite representable integer".into(),
491                        ));
492                    }
493                    if let Some(range) = desc.range {
494                        if v < range.min
495                            || v > range.max
496                            || range
497                                .step
498                                .is_some_and(|step| step > 0.0 && (v - range.min) % step != 0.0)
499                        {
500                            return Err(CameraError::invalid_config(
501                                "Control value outside native range/step".into(),
502                            ));
503                        }
504                    }
505                    RawValue::manual(v as i32)
506                }
507                _ => {
508                    return Err(CameraError::invalid_config(
509                        "Control value kind differs from descriptor".into(),
510                    ))
511                }
512            };
513            c.set_control(raw, raw_value)
514        })
515        .await?;
516        self.record_control(id, requested);
517        Ok(())
518    }
519    /// Apply every item and retain every failure. This operation is not atomic.
520    pub async fn set_controls(
521        &self,
522        values: impl IntoIterator<Item = (ControlId, ControlValue)>,
523    ) -> Vec<ControlOutcome> {
524        let mut outcomes = Vec::new();
525        for (id, value) in values {
526            outcomes.push(ControlOutcome {
527                id,
528                result: self.set_control(id, value).await,
529            });
530        }
531        outcomes
532    }
533    pub async fn reset_controls(&self) -> CameraResult<Vec<ControlOutcome>> {
534        let controls = self.controls().await?;
535        let mut outcomes = Vec::new();
536        for desc in controls {
537            let result = if let Some(value) = desc.range.and_then(|r| r.default) {
538                self.set_control(desc.id, value).await
539            } else {
540                Err(CameraError::control_not_supported(
541                    "Native default is unavailable".into(),
542                ))
543            };
544            outcomes.push(ControlOutcome {
545                id: desc.id,
546                result,
547            });
548        }
549        Ok(outcomes)
550    }
551    /// Set a representable exposure duration. Automatic exposure must be disabled separately.
552    pub async fn set_exposure_time(&self, duration: std::time::Duration) -> CameraResult<()> {
553        let unit = self
554            .controls()
555            .await?
556            .into_iter()
557            .find(|c| c.id == ControlId::ExposureTime)
558            .ok_or_else(|| CameraError::control_not_supported("Exposure duration".into()))?
559            .unit;
560        let value = match unit {
561            ControlUnit::HundredMicroseconds => duration.as_secs_f64() * 10_000.0,
562            ControlUnit::Log2Seconds => duration.as_secs_f64().log2(),
563            _ => {
564                return Err(CameraError::control_not_supported(
565                    "Exposure duration unit".into(),
566                ))
567            }
568        };
569        if !value.is_finite() || (value - value.round()).abs() > 1e-6 {
570            return Err(CameraError::invalid_config(
571                "Duration is not representable in the native control unit".into(),
572            ));
573        }
574        self.set_control(ControlId::ExposureTime, ControlValue::Number(value.round()))
575            .await
576    }
577
578    pub async fn set_exposure(&self, exposure: Exposure) -> CameraResult<()> {
579        match exposure {
580            Exposure::Auto => {
581                self.set_control(
582                    ControlId::ExposureMode,
583                    ControlValue::Mode(ControlMode::Automatic),
584                )
585                .await
586            }
587            Exposure::Manual(duration) => {
588                self.set_control(
589                    ControlId::ExposureMode,
590                    ControlValue::Mode(ControlMode::Manual),
591                )
592                .await?;
593                self.set_exposure_time(duration).await
594            }
595        }
596    }
597
598    pub async fn set_white_balance(&self, value: WhiteBalance) -> CameraResult<()> {
599        match value {
600            WhiteBalance::Auto => {
601                self.set_control(
602                    ControlId::WhiteBalanceMode,
603                    ControlValue::Mode(ControlMode::Automatic),
604                )
605                .await
606            }
607            WhiteBalance::Temperature(kelvin) => {
608                self.set_control(
609                    ControlId::WhiteBalanceMode,
610                    ControlValue::Mode(ControlMode::Manual),
611                )
612                .await?;
613                self.set_control(
614                    ControlId::WhiteBalanceTemperature,
615                    ControlValue::Number(f64::from(kelvin.get())),
616                )
617                .await
618            }
619        }
620    }
621
622    pub async fn set_focus(&self, value: Focus) -> CameraResult<()> {
623        match value {
624            Focus::Auto => {
625                self.set_control(
626                    ControlId::FocusMode,
627                    ControlValue::Mode(ControlMode::Automatic),
628                )
629                .await
630            }
631            Focus::Position(position) => {
632                self.set_control(
633                    ControlId::FocusMode,
634                    ControlValue::Mode(ControlMode::Manual),
635                )
636                .await?;
637                self.set_control(ControlId::FocusPosition, ControlValue::Number(position))
638                    .await
639            }
640        }
641    }
642}
643
644#[cfg(any(
645    test,
646    all(
647        any(feature = "native", feature = "backend-camera2"),
648        target_os = "android"
649    )
650))]
651fn camera2_mode(id: ControlId, value: i32) -> Option<ControlMode> {
652    match (id, value) {
653        (ControlId::FocusMode, 0) => Some(ControlMode::Manual),
654        (ControlId::FocusMode, 1) => Some(ControlMode::Single),
655        (ControlId::FocusMode, 3 | 4) => Some(ControlMode::Continuous),
656        (ControlId::ExposureMode | ControlId::WhiteBalanceMode, 0) => Some(ControlMode::Manual),
657        (ControlId::ExposureMode | ControlId::WhiteBalanceMode, 1) => Some(ControlMode::Automatic),
658        _ => None,
659    }
660}
661
662#[cfg(test)]
663mod tests {
664    use super::*;
665
666    #[test]
667    fn camera2_focus_modes_preserve_single_and_continuous_semantics() {
668        assert_eq!(
669            camera2_mode(ControlId::FocusMode, 1),
670            Some(ControlMode::Single)
671        );
672        assert_eq!(
673            camera2_mode(ControlId::FocusMode, 3),
674            Some(ControlMode::Continuous)
675        );
676        assert_eq!(
677            camera2_mode(ControlId::ExposureMode, 1),
678            Some(ControlMode::Automatic)
679        );
680        assert_eq!(camera2_mode(ControlId::WhiteBalanceMode, 8), None);
681    }
682
683    #[test]
684    fn camera2_limits_do_not_claim_a_device_default() {
685        let range = describe_range(
686            BackendType::Camera2,
687            ControlId::Gain,
688            Raw::Gain,
689            crate::CameraControlRange {
690                min: 100,
691                max: i32::MAX,
692                step: 0,
693                default: 0,
694                supports_auto: false,
695            },
696        );
697        assert_eq!(range.min, 100.0);
698        assert_eq!(range.max, i32::MAX as f64);
699        assert!(range.default.is_none());
700        assert!(range.step.is_none());
701    }
702}