1#![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 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 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#[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}
141pub trait NativeCameraRecording {
145 fn finish(&self) -> CameraFuture<CameraVideo>;
146 fn cancel(&self);
147}
148
149pub trait NativeCameraSession {
150 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 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 fn devices(&self) -> CameraFuture<Vec<CameraDevice>>;
177 fn permission(&self) -> CameraPermission;
178 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 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 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}
551pub 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;