1use 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)]
9pub enum ControlId {
11 ExposureMode,
13 ExposureTime,
15 ExposureCompensation,
17 FocusMode,
19 FocusPosition,
21 WhiteBalanceMode,
23 WhiteBalanceTemperature,
25 Zoom,
27 Brightness,
29 Contrast,
31 Hue,
33 Saturation,
35 Sharpness,
37 Gamma,
39 BacklightCompensation,
41 Gain,
43 Pan,
45 Tilt,
47 Iris,
49}
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub enum ControlUnit {
53 Boolean,
55 Mode,
57 Native,
59 HundredMicroseconds,
61 Log2Seconds,
63 MilliEv,
65 CompensationIndex,
67 Kelvin,
69 Percent,
71 Degrees,
73 ArcSeconds,
75 Iso,
77}
78#[derive(Clone, Copy, Debug, PartialEq, Eq)]
79pub enum ControlMode {
81 Manual,
83 Automatic,
85 Locked,
87 Single,
89 Continuous,
91}
92#[derive(Clone, Debug, PartialEq)]
93pub enum ControlValue {
95 Number(f64),
97 Mode(ControlMode),
99}
100#[derive(Clone, Debug, PartialEq)]
101pub enum ControlReadback {
103 Actual(ControlValue),
105 Requested(ControlValue),
107 Unknown,
109}
110#[derive(Clone, Copy, Debug, PartialEq, Eq)]
111pub struct Kelvin(u32);
113impl Kelvin {
114 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 pub const fn get(self) -> u32 {
125 self.0
126 }
127}
128#[derive(Clone, Copy, Debug, PartialEq, Eq)]
129pub enum Exposure {
131 Auto,
133 Manual(std::time::Duration),
135}
136#[derive(Clone, Copy, Debug, PartialEq, Eq)]
137pub enum WhiteBalance {
139 Auto,
141 Temperature(Kelvin),
143}
144#[derive(Clone, Copy, Debug, PartialEq)]
145pub enum Focus {
147 Auto,
149 Position(f64),
151}
152#[derive(Clone, Debug)]
153pub struct ControlRange {
155 pub min: f64,
157 pub max: f64,
159 pub step: Option<f64>,
161 pub default: Option<ControlValue>,
163}
164#[derive(Clone, Debug)]
165pub struct ControlDescriptor {
167 pub id: ControlId,
169 pub unit: ControlUnit,
171 pub readable: bool,
173 pub writable: Option<bool>,
175 pub range: Option<ControlRange>,
177 pub modes: Vec<ControlMode>,
179 pub requires_manual: Option<ControlId>,
181}
182#[derive(Debug)]
183pub struct ControlOutcome {
185 pub id: ControlId,
187 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 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 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}