Skip to main content

ferroui_media_camera/
lib.rs

1//! Camera discovery, explicit acquisition, sessions and still capture.
2//! Depends on the shared media base, independently of video playback and QR.
3#![forbid(unsafe_code)]
4pub use ferroui_media as media;
5use ferroui_media::frames::{FrameBudget, FrameLease, FrameMailbox, PresentationPolicy};
6use std::{
7    cell::{Cell, RefCell},
8    future::Future,
9    pin::Pin,
10    rc::Rc,
11    sync::Arc,
12    time::Duration,
13};
14
15pub type CameraFuture<T> = Pin<Box<dyn Future<Output = Result<T, CameraError>>>>;
16#[derive(Clone, Copy, Debug, PartialEq, Eq)]
17pub enum CameraErrorKind {
18    InvalidRequest,
19    NoDevice,
20    NotDetermined,
21    Denied,
22    Restricted,
23    Busy,
24    Disconnected,
25    Unsupported,
26    Cancelled,
27    NativeFailure,
28    DeviceLost,
29}
30#[derive(Clone, Debug, PartialEq, Eq)]
31pub struct CameraError {
32    pub kind: CameraErrorKind,
33    pub message: String,
34}
35impl CameraError {
36    pub fn new(kind: CameraErrorKind, message: impl Into<String>) -> Self {
37        Self {
38            kind,
39            message: message.into(),
40        }
41    }
42}
43impl std::fmt::Display for CameraError {
44    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45        f.write_str(&self.message)
46    }
47}
48impl std::error::Error for CameraError {}
49#[derive(Clone, Copy, Debug, PartialEq, Eq)]
50pub enum CameraFacing {
51    Front,
52    Rear,
53    External,
54    Unknown,
55}
56#[derive(Clone, Copy, Debug, PartialEq, Eq)]
57pub enum CameraPermission {
58    NotDetermined,
59    Granted,
60    Denied,
61    Restricted,
62}
63#[derive(Clone, Copy, Debug, PartialEq)]
64pub struct CameraFormat {
65    pub width: u32,
66    pub height: u32,
67    /// Preserves negotiated fractional rates rather than rounding to integers.
68    pub frames_per_second: f64,
69}
70#[derive(Clone, Debug)]
71pub struct CameraDevice {
72    pub id: String,
73    pub label: Option<String>,
74    pub facing: CameraFacing,
75    pub formats: Vec<CameraFormat>,
76}
77#[derive(Clone, Debug, Default)]
78pub struct CameraSelection {
79    pub device_id: Option<String>,
80    pub preferred_facing: Option<CameraFacing>,
81    pub format: Option<CameraFormat>,
82    pub exact: bool,
83}
84#[derive(Clone, Debug)]
85pub struct CameraStartOptions {
86    pub selection: CameraSelection,
87    pub presentation: PresentationPolicy,
88    /// Retain an immutable sampling view for explicitly requested analysis.
89    /// Preview-only capture does not allocate analysis storage or read pixels.
90    pub enable_analysis: bool,
91}
92impl Default for CameraStartOptions {
93    fn default() -> Self {
94        Self {
95            selection: CameraSelection::default(),
96            presentation: PresentationPolicy::GpuPreferred,
97            enable_analysis: false,
98        }
99    }
100}
101#[derive(Clone, Debug)]
102pub struct CameraSettings {
103    pub device: CameraDevice,
104    pub format: CameraFormat,
105    pub native_still: bool,
106    pub torch: bool,
107    pub zoom: Option<(f64, f64)>,
108}
109#[derive(Clone, Copy, Debug, PartialEq, Eq)]
110pub enum PhotoOrigin {
111    NativeStill,
112    PreviewSnapshot,
113}
114#[derive(Clone, Debug)]
115pub struct CameraPhoto {
116    pub encoded: Arc<[u8]>,
117    pub content_type: String,
118    pub width: u32,
119    pub height: u32,
120    pub timestamp: Duration,
121    pub rotation_degrees: u16,
122    pub mirrored: bool,
123    pub origin: PhotoOrigin,
124}
125#[derive(Clone, Copy, Debug)]
126pub enum CameraControl {
127    Torch(bool),
128    Zoom(f64),
129    Focus(f64, f64),
130    Exposure(f64),
131}
132/// Independently owned encoded video. Preview frames never pass through this buffer.
133#[derive(Clone, Debug)]
134pub struct CameraVideo {
135    pub encoded: Arc<[u8]>,
136    pub content_type: String,
137    pub width: u32,
138    pub height: u32,
139    pub duration: Duration,
140}
141/// Native recording owns its encoder, output and completion. Cancel must be
142/// idempotent and discard output, including output arriving after cancellation.
143/// Implementations must bound encoded output and never request microphone access.
144pub trait NativeCameraRecording {
145    fn finish(&self) -> CameraFuture<CameraVideo>;
146    fn cancel(&self);
147}
148
149pub trait NativeCameraSession {
150    /// Optional narrow platform extension (for example an analysis stream).
151    /// Borrowing it never transfers ownership of the camera session.
152    fn platform_context(&self) -> Option<&dyn std::any::Any> {
153        None
154    }
155    fn settings(&self) -> CameraSettings;
156    fn take_frame(&self) -> Result<Option<FrameLease>, CameraError>;
157    fn photo(&self) -> CameraFuture<CameraPhoto>;
158    /// Silent video recording is optional and separately advertised. Preview or
159    /// still support alone must never enable a Record button.
160    fn supports_video_recording(&self) -> bool {
161        false
162    }
163    fn start_recording(&self) -> CameraFuture<Rc<dyn NativeCameraRecording>> {
164        Box::pin(async {
165            Err(CameraError::new(
166                CameraErrorKind::Unsupported,
167                "Video recording is unavailable from this camera provider",
168            ))
169        })
170    }
171    fn set_control(&self, control: CameraControl) -> Result<(), CameraError>;
172    fn stop(&self);
173}
174pub trait CameraProvider {
175    /// No acquisition or consent prompt. Labels/formats may remain unknown.
176    fn devices(&self) -> CameraFuture<Vec<CameraDevice>>;
177    fn permission(&self) -> CameraPermission;
178    /// Owns provisional resources until committed. Dropping the returned future
179    /// must retire those resources, including late permission results. Never
180    /// requests microphone access.
181    fn start(
182        &self,
183        options: CameraStartOptions,
184        source: u64,
185        generation: u64,
186        budget: FrameBudget,
187    ) -> CameraFuture<Rc<dyn NativeCameraSession>>;
188}
189struct PendingStart {
190    pending: RefCell<Option<CameraFuture<Rc<dyn NativeCameraSession>>>>,
191    cancelled: Cell<bool>,
192    waker: RefCell<Option<std::task::Waker>>,
193}
194impl PendingStart {
195    fn cancel(&self) {
196        self.cancelled.set(true);
197        let pending = self.pending.borrow_mut().take();
198        let waker = self.waker.borrow_mut().take();
199        drop(pending);
200        if let Some(waker) = waker {
201            waker.wake();
202        }
203    }
204}
205struct CaptureInner {
206    provider: RefCell<Rc<dyn CameraProvider>>,
207    source: u64,
208    generation: Cell<u64>,
209    budget: FrameBudget,
210    pending: RefCell<Option<std::rc::Weak<PendingStart>>>,
211}
212impl Drop for CaptureInner {
213    fn drop(&mut self) {
214        if let Some(pending) = self
215            .pending
216            .get_mut()
217            .take()
218            .and_then(|weak| weak.upgrade())
219        {
220            pending.cancel();
221        }
222    }
223}
224#[derive(Clone)]
225pub struct CameraCapture(Rc<CaptureInner>);
226impl CameraCapture {
227    pub fn new(provider: Rc<dyn CameraProvider>, budget: FrameBudget) -> Self {
228        Self(Rc::new(CaptureInner {
229            provider: RefCell::new(provider),
230            source: ferroui_media::allocate_source_id(),
231            generation: Cell::new(0),
232            budget,
233            pending: RefCell::new(None),
234        }))
235    }
236    /// Rebinds renderer resources while retaining the source identity and shared
237    /// budget. Active sessions are caller-owned and must be stopped separately.
238    pub fn rebind_provider(&self, provider: Rc<dyn CameraProvider>) {
239        self.cancel_pending_start();
240        *self.0.provider.borrow_mut() = provider;
241    }
242    pub fn devices(&self) -> CameraFuture<Vec<CameraDevice>> {
243        let provider = self.0.provider.borrow().clone();
244        provider.devices()
245    }
246    pub fn permission(&self) -> CameraPermission {
247        let provider = self.0.provider.borrow().clone();
248        provider.permission()
249    }
250    pub fn cancel_pending_start(&self) {
251        self.0.generation.set(
252            self.0
253                .generation
254                .get()
255                .checked_add(1)
256                .expect("camera generation exhausted"),
257        );
258        let pending = self
259            .0
260            .pending
261            .borrow_mut()
262            .take()
263            .and_then(|weak| weak.upgrade());
264        if let Some(pending) = pending {
265            pending.cancel();
266        }
267    }
268    pub fn start(&self, options: CameraStartOptions) -> CameraFuture<CameraSession> {
269        if options.selection.format.is_some_and(|format| {
270            format.width == 0
271                || format.height == 0
272                || !format.frames_per_second.is_finite()
273                || format.frames_per_second <= 0.
274        }) {
275            return Box::pin(async {
276                Err(CameraError::new(
277                    CameraErrorKind::InvalidRequest,
278                    "Camera dimensions and frame rate must be positive",
279                ))
280            });
281        }
282        self.cancel_pending_start();
283        let generation = self.0.generation.get();
284        let source = self.0.source;
285        let provider = self.0.provider.borrow().clone();
286        let pending = provider.start(options, source, generation, self.0.budget.clone());
287        let slot = Rc::new(PendingStart {
288            pending: RefCell::new(Some(pending)),
289            cancelled: Cell::new(false),
290            waker: RefCell::new(None),
291        });
292        *self.0.pending.borrow_mut() = Some(Rc::downgrade(&slot));
293        let weak = Rc::downgrade(&self.0);
294        let pending = std::future::poll_fn(move |cx| {
295            if slot.cancelled.get() {
296                return std::task::Poll::Ready(Err(CameraError::new(
297                    CameraErrorKind::Cancelled,
298                    "Camera start was cancelled",
299                )));
300            }
301            let Some(mut pending) = slot.pending.borrow_mut().take() else {
302                return std::task::Poll::Ready(Err(CameraError::new(
303                    CameraErrorKind::Cancelled,
304                    "Camera start was cancelled",
305                )));
306            };
307            *slot.waker.borrow_mut() = Some(cx.waker().clone());
308            let result = pending.as_mut().poll(cx);
309            if slot.cancelled.get() {
310                if let std::task::Poll::Ready(Ok(native)) = result {
311                    native.stop();
312                }
313                return std::task::Poll::Ready(Err(CameraError::new(
314                    CameraErrorKind::Cancelled,
315                    "Camera start was cancelled",
316                )));
317            }
318            match result {
319                std::task::Poll::Pending => {
320                    *slot.pending.borrow_mut() = Some(pending);
321                    std::task::Poll::Pending
322                }
323                std::task::Poll::Ready(result) => {
324                    slot.waker.borrow_mut().take();
325                    std::task::Poll::Ready(result)
326                }
327            }
328        });
329        Box::pin(async move {
330            let native = pending.await?;
331            if !weak
332                .upgrade()
333                .is_some_and(|c| c.generation.get() == generation)
334            {
335                native.stop();
336                return Err(CameraError::new(
337                    CameraErrorKind::Cancelled,
338                    "Camera start was abandoned",
339                ));
340            }
341            Ok(CameraSession(Rc::new(SessionInner {
342                native,
343                frames: Arc::new(FrameMailbox::new(source, generation)),
344                stopped: Cell::new(false),
345                recording_busy: Cell::new(false),
346                recording: RefCell::new(None),
347            })))
348        })
349    }
350}
351struct SessionInner {
352    native: Rc<dyn NativeCameraSession>,
353    frames: Arc<FrameMailbox>,
354    stopped: Cell<bool>,
355    recording_busy: Cell<bool>,
356    recording: RefCell<Option<std::rc::Weak<RecordingInner>>>,
357}
358impl Drop for SessionInner {
359    fn drop(&mut self) {
360        if !self.stopped.replace(true) {
361            self.frames.clear();
362            if let Some(recording) = self.recording.get_mut().take().and_then(|r| r.upgrade()) {
363                recording.cancel();
364            }
365            self.native.stop();
366        }
367    }
368}
369#[derive(Clone)]
370pub struct CameraSession(Rc<SessionInner>);
371#[derive(Clone)]
372pub struct WeakCameraSession(std::rc::Weak<SessionInner>);
373impl WeakCameraSession {
374    pub fn upgrade(&self) -> Option<CameraSession> {
375        self.0.upgrade().map(CameraSession)
376    }
377}
378impl CameraSession {
379    pub fn platform_context<T: std::any::Any>(&self) -> Option<&T> {
380        self.0.native.platform_context()?.downcast_ref()
381    }
382    pub fn downgrade(&self) -> WeakCameraSession {
383        WeakCameraSession(Rc::downgrade(&self.0))
384    }
385    pub fn is_stopped(&self) -> bool {
386        self.0.stopped.get()
387    }
388    pub fn settings(&self) -> CameraSettings {
389        self.0.native.settings()
390    }
391    pub fn frames(&self) -> Arc<FrameMailbox> {
392        self.0.frames.clone()
393    }
394    pub fn poll(&self) -> Result<(), CameraError> {
395        if self.0.stopped.get() {
396            return Ok(());
397        }
398        match self.0.native.take_frame() {
399            Ok(Some(frame)) => self
400                .0
401                .frames
402                .publish(frame)
403                .map_err(|e| CameraError::new(CameraErrorKind::NativeFailure, e.to_string())),
404            Ok(None) => Ok(()),
405            Err(error) => {
406                self.stop();
407                Err(error)
408            }
409        }
410    }
411    pub fn photo(&self) -> CameraFuture<CameraPhoto> {
412        if self.0.stopped.get() {
413            return Box::pin(async {
414                Err(CameraError::new(
415                    CameraErrorKind::Disconnected,
416                    "Camera is stopped",
417                ))
418            });
419        }
420        let pending = self.0.native.photo();
421        let session = Rc::downgrade(&self.0);
422        Box::pin(async move {
423            let result = pending.await;
424            if !session.upgrade().is_some_and(|s| !s.stopped.get()) {
425                return Err(CameraError::new(
426                    CameraErrorKind::Cancelled,
427                    "Camera stopped before photo capture completed",
428                ));
429            }
430            result
431        })
432    }
433    pub fn supports_video_recording(&self) -> bool {
434        !self.is_stopped() && self.0.native.supports_video_recording()
435    }
436    /// Begins one silent native recording. Dropping preparation cancels it;
437    /// stopping the camera invalidates both recording and its encoded result.
438    pub fn start_recording(&self) -> CameraFuture<CameraRecording> {
439        if self.is_stopped() {
440            return recording_error(CameraErrorKind::Disconnected, "Camera is stopped");
441        }
442        if !self.supports_video_recording() {
443            return recording_error(
444                CameraErrorKind::Unsupported,
445                "Video recording is unavailable from this camera provider",
446            );
447        }
448        if self.0.recording_busy.replace(true) {
449            return recording_error(CameraErrorKind::Busy, "A recording is already active");
450        }
451        let guard = RecordingSlot(Rc::downgrade(&self.0));
452        let pending = self.0.native.start_recording();
453        Box::pin(async move {
454            let native = pending.await?;
455            let Some(session) = guard.0.upgrade().filter(|s| !s.stopped.get()) else {
456                native.cancel();
457                return Err(CameraError::new(
458                    CameraErrorKind::Cancelled,
459                    "Camera stopped during recording preparation",
460                ));
461            };
462            let recording = Rc::new(RecordingInner {
463                native,
464                slot: guard,
465                state: Cell::new(RecordingState::Active),
466            });
467            *session.recording.borrow_mut() = Some(Rc::downgrade(&recording));
468            Ok(CameraRecording(recording))
469        })
470    }
471    pub fn set_control(&self, control: CameraControl) -> Result<(), CameraError> {
472        if self.0.stopped.get() {
473            return Err(CameraError::new(
474                CameraErrorKind::Disconnected,
475                "Camera is stopped",
476            ));
477        }
478        let valid = match control {
479            CameraControl::Torch(_) => true,
480            CameraControl::Zoom(zoom) => zoom.is_finite() && zoom > 0.,
481            CameraControl::Focus(x, y) => {
482                x.is_finite() && y.is_finite() && (0. ..=1.).contains(&x) && (0. ..=1.).contains(&y)
483            }
484            CameraControl::Exposure(exposure) => exposure.is_finite(),
485        };
486        if !valid {
487            return Err(CameraError::new(
488                CameraErrorKind::InvalidRequest,
489                "Camera control requires finite values in its normalized range",
490            ));
491        }
492        self.0.native.set_control(control)
493    }
494    pub fn stop(&self) {
495        if !self.0.stopped.replace(true) {
496            self.0.frames.clear();
497            let recording = self
498                .0
499                .recording
500                .borrow_mut()
501                .take()
502                .and_then(|r| r.upgrade());
503            if let Some(recording) = recording {
504                recording.cancel();
505            }
506            self.0.native.stop();
507        }
508    }
509}
510
511fn recording_error<T: 'static>(kind: CameraErrorKind, message: &'static str) -> CameraFuture<T> {
512    Box::pin(async move { Err(CameraError::new(kind, message)) })
513}
514struct RecordingSlot(std::rc::Weak<SessionInner>);
515impl Drop for RecordingSlot {
516    fn drop(&mut self) {
517        if let Some(session) = self.0.upgrade() {
518            session.recording_busy.set(false);
519        }
520    }
521}
522#[derive(Clone, Copy, PartialEq, Eq)]
523enum RecordingState {
524    Active,
525    Finishing,
526    Complete,
527    Cancelled,
528}
529struct RecordingInner {
530    native: Rc<dyn NativeCameraRecording>,
531    slot: RecordingSlot,
532    state: Cell<RecordingState>,
533}
534impl RecordingInner {
535    fn cancel(&self) {
536        if !matches!(
537            self.state.replace(RecordingState::Cancelled),
538            RecordingState::Complete | RecordingState::Cancelled
539        ) {
540            self.native.cancel();
541        }
542    }
543}
544impl Drop for RecordingInner {
545    fn drop(&mut self) {
546        if self.state.get() != RecordingState::Complete {
547            self.cancel();
548        }
549    }
550}
551/// Owned recording transaction. Drop discards unfinished output. No clone is
552/// exposed, and finish can be issued once. The capture session remains borrowed.
553pub struct CameraRecording(Rc<RecordingInner>);
554impl CameraRecording {
555    pub fn cancel(&self) {
556        self.0.cancel();
557    }
558    pub fn finish(self) -> CameraFuture<CameraVideo> {
559        if self.0.state.get() != RecordingState::Active {
560            return recording_error(
561                CameraErrorKind::InvalidRequest,
562                "Recording is no longer active",
563            );
564        }
565        self.0.state.set(RecordingState::Finishing);
566        let pending = self.0.native.finish();
567        Box::pin(async move {
568            let result = pending.await;
569            if self.0.state.get() == RecordingState::Cancelled
570                || !self.0.slot.0.upgrade().is_some_and(|s| !s.stopped.get())
571            {
572                return Err(CameraError::new(
573                    CameraErrorKind::Cancelled,
574                    "Camera recording was cancelled",
575                ));
576            }
577            let video = result?;
578            if video.encoded.is_empty()
579                || video.encoded.len() > 256 * 1024 * 1024
580                || video.width == 0
581                || video.height == 0
582                || video.duration.is_zero()
583            {
584                return Err(CameraError::new(
585                    CameraErrorKind::NativeFailure,
586                    "Recording output exceeds the encoded output contract",
587                ));
588            }
589            self.0.state.set(RecordingState::Complete);
590            Ok(video)
591        })
592    }
593}
594
595#[cfg(test)]
596mod tests;