Skip to main content

ferroui_media_camera_apple/
lib.rs

1//! AVFoundation camera capture, independent of video playback and QR.
2#![cfg(target_vendor = "apple")]
3#![deny(unsafe_code)]
4#[allow(unsafe_code)]
5mod native;
6use ferroui_media::frames::*;
7use ferroui_media_apple::poll_native as wait;
8#[cfg(feature = "controls")]
9pub use ferroui_media_apple::AppleTextureImporter;
10use ferroui_media_camera::*;
11use std::{cell::Cell, rc::Rc, task::Poll, time::Duration};
12fn duration(seconds: f64) -> Option<Duration> {
13    if seconds.is_finite() && seconds >= 0. {
14        Duration::try_from_secs_f64(seconds).ok()
15    } else {
16        None
17    }
18}
19fn invalid() -> CameraError {
20    CameraError::new(
21        CameraErrorKind::NativeFailure,
22        "Invalid native camera metadata",
23    )
24}
25fn number(value: &serde_json::Value, key: &str) -> Result<u32, CameraError> {
26    value[key]
27        .as_u64()
28        .and_then(|n| n.try_into().ok())
29        .ok_or_else(invalid)
30}
31fn frame_rate(value: &serde_json::Value) -> Result<f64, CameraError> {
32    value["fps"]
33        .as_f64()
34        .filter(|rate| rate.is_finite() && *rate > 0.)
35        .ok_or_else(invalid)
36}
37fn parse_device(value: &serde_json::Value) -> Result<CameraDevice, CameraError> {
38    let mut formats = Vec::new();
39    for f in value["formats"].as_array().ok_or_else(invalid)? {
40        formats.push(CameraFormat {
41            width: number(f, "width")?,
42            height: number(f, "height")?,
43            frames_per_second: frame_rate(f)?,
44        });
45    }
46    formats.sort_by(|a, b| {
47        (a.width, a.height)
48            .cmp(&(b.width, b.height))
49            .then_with(|| a.frames_per_second.total_cmp(&b.frames_per_second))
50    });
51    formats.dedup();
52    Ok(CameraDevice {
53        id: value["id"].as_str().ok_or_else(invalid)?.into(),
54        label: value["label"].as_str().map(String::from),
55        facing: match value["facing"].as_u64() {
56            Some(1) => CameraFacing::Front,
57            Some(2) => CameraFacing::Rear,
58            Some(3) => CameraFacing::External,
59            _ => CameraFacing::Unknown,
60        },
61        formats,
62    })
63}
64/// Native camera capture on an already admitted Metal compositor device.
65/// The application must declare NSCameraUsageDescription in its bundle. This
66/// provider never asks for microphone or photo-library access.
67pub struct AppleCameraProvider {
68    pub device: DeviceIdentity,
69    pub device_generation: u64,
70}
71impl CameraProvider for AppleCameraProvider {
72    fn devices(&self) -> CameraFuture<Vec<CameraDevice>> {
73        Box::pin(async {
74            native::devices()?
75                .as_array()
76                .ok_or_else(invalid)?
77                .iter()
78                .map(parse_device)
79                .collect()
80        })
81    }
82    fn permission(&self) -> CameraPermission {
83        native::permission()
84    }
85    fn start(
86        &self,
87        options: CameraStartOptions,
88        source: u64,
89        generation: u64,
90        budget: FrameBudget,
91    ) -> CameraFuture<Rc<dyn NativeCameraSession>> {
92        let device = self.device.clone();
93        let device_generation = self.device_generation;
94        let mut provisional = Some(native::Camera::new(&options.selection));
95        let mut camera = None;
96        wait(move || {
97            if let Some(initial) = provisional.take() {
98                match initial {
99                    Ok(c) => camera = Some(c),
100                    Err(e) => return Poll::Ready(Err(e)),
101                }
102            }
103            let c = camera.as_ref().unwrap();
104            match c.status() {
105                Ok(false) => Poll::Pending,
106                Err(error) => {
107                    camera.take();
108                    Poll::Ready(Err(error))
109                }
110                Ok(true) => {
111                    let settings = (|| {
112                        let s = c.settings()?;
113                        let format = CameraFormat {
114                            width: number(&s, "width")?,
115                            height: number(&s, "height")?,
116                            frames_per_second: frame_rate(&s)?,
117                        };
118                        if format.width > budget.limits().max_dimension
119                            || format.height > budget.limits().max_dimension
120                            || u64::from(format.width) * u64::from(format.height) * 4
121                                > budget.limits().bytes
122                        {
123                            return Err(CameraError::new(
124                                CameraErrorKind::Unsupported,
125                                "Negotiated camera format exceeds the frame budget",
126                            ));
127                        }
128                        Ok(CameraSettings {
129                            device: parse_device(&s["device"])?,
130                            format,
131                            native_still: s["native_still"].as_bool().unwrap_or(false),
132                            torch: false,
133                            zoom: None,
134                        })
135                    })();
136                    match settings {
137                        Err(e) => {
138                            camera.take();
139                            Poll::Ready(Err(e))
140                        }
141                        Ok(settings) => Poll::Ready(Ok(Rc::new(AppleCameraSession {
142                            camera: camera.take().unwrap(),
143                            settings,
144                            source,
145                            generation,
146                            device: device.clone(),
147                            device_generation,
148                            budget: budget.clone(),
149                            sequence: Cell::new(0),
150                        })
151                            as Rc<dyn NativeCameraSession>)),
152                    }
153                }
154            }
155        })
156    }
157}
158struct AppleCameraSession {
159    camera: native::Camera,
160    settings: CameraSettings,
161    source: u64,
162    generation: u64,
163    device: DeviceIdentity,
164    device_generation: u64,
165    budget: FrameBudget,
166    sequence: Cell<u64>,
167}
168impl NativeCameraSession for AppleCameraSession {
169    fn settings(&self) -> CameraSettings {
170        self.settings.clone()
171    }
172    fn take_frame(&self) -> Result<Option<FrameLease>, CameraError> {
173        self.camera.status()?;
174        if self.budget.quarantined_reads() > 0 {
175            return Err(CameraError::new(
176                CameraErrorKind::NativeFailure,
177                "GPU completion is indeterminate; camera storage remains quarantined",
178            ));
179        }
180        let Some((buffer, timestamp)) = self.camera.frame() else {
181            return Ok(None);
182        };
183        let (width, height, stride, bytes, color) = buffer.info();
184        if !matches!(color, 1 | 2) || buffer.surface().is_none() {
185            return Err(CameraError::new(
186                CameraErrorKind::Unsupported,
187                "Camera frame requires known SDR RGB color and IOSurface storage",
188            ));
189        }
190        let sequence = self
191            .sequence
192            .get()
193            .checked_add(1)
194            .expect("camera frame identity exhausted");
195        self.sequence.set(sequence);
196        let metadata = FrameMetadata {
197            identity: FrameIdentity {
198                source: self.source,
199                generation: self.generation,
200                sequence,
201            },
202            width,
203            height,
204            visible: FrameRegion {
205                x: 0,
206                y: 0,
207                width,
208                height,
209            },
210            format: FrameFormat::Bgra8,
211            color: if color == 1 {
212                FrameColor::Srgb
213            } else {
214                FrameColor::Rec709Full
215            },
216            alpha: FrameAlpha::Opaque,
217            rotation: FrameRotation::None,
218            mirrored: false,
219            top_left_origin: true,
220            timestamp: duration(timestamp).unwrap_or_default(),
221            device: Some(self.device.clone()),
222            device_generation: self.device_generation,
223            planes: vec![FramePlane {
224                offset: 0,
225                stride,
226                length: stride.checked_mul(height as u64).ok_or_else(invalid)?,
227            }],
228            retained_bytes: bytes,
229        };
230        match self.budget.lease(metadata, buffer) {
231            Ok(frame) => Ok(Some(frame)),
232            Err(FrameError::BudgetExceeded) => Ok(None),
233            Err(e) => Err(CameraError::new(
234                CameraErrorKind::Unsupported,
235                e.to_string(),
236            )),
237        }
238    }
239    fn supports_video_recording(&self) -> bool {
240        true
241    }
242    fn start_recording(&self) -> CameraFuture<Rc<dyn NativeCameraRecording>> {
243        let recording = self.camera.record().map(|native| {
244            Rc::new(AppleCameraRecording(Rc::new(native))) as Rc<dyn NativeCameraRecording>
245        });
246        Box::pin(async move { recording })
247    }
248    fn photo(&self) -> CameraFuture<CameraPhoto> {
249        if !self.settings.native_still {
250            return Box::pin(async {
251                Err(CameraError::new(
252                    CameraErrorKind::Unsupported,
253                    "Native JPEG capture is unavailable",
254                ))
255            });
256        }
257        let initial = self.camera.photo();
258        let counters = self.budget.counters();
259        let mut initial = Some(initial);
260        let mut request = None;
261        wait(move || {
262            if let Some(result) = initial.take() {
263                match result {
264                    Ok(photo) => request = Some(photo),
265                    Err(e) => return Poll::Ready(Err(e)),
266                }
267            }
268            let photo = request.as_ref().unwrap();
269            match photo.poll() {
270                None => Poll::Pending,
271                Some(Err(e)) => Poll::Ready(Err(e)),
272                Some(Ok(info)) => {
273                    // Only encoded still output is copied. Preview storage is
274                    // never mapped/read back by this capture provider.
275                    let result = (|| {
276                        counters
277                            .cpu_transfer(
278                                PixelTransferPurpose::Photo,
279                                info.length,
280                                PresentationRoute::SharedTexture,
281                            )
282                            .map_err(|_| invalid())?;
283                        let encoded = photo.copy(&info)?;
284                        let (rotation_degrees, mirrored) = match info.orientation {
285                            1 => (0, false),
286                            2 => (0, true),
287                            3 => (180, false),
288                            4 => (180, true),
289                            5 => (90, true),
290                            6 => (90, false),
291                            7 => (270, true),
292                            8 => (270, false),
293                            _ => return Err(invalid()),
294                        };
295                        Ok(CameraPhoto {
296                            encoded: encoded.into(),
297                            content_type: "image/jpeg".into(),
298                            width: info.width,
299                            height: info.height,
300                            timestamp: duration(info.timestamp).unwrap_or_default(),
301                            rotation_degrees,
302                            mirrored,
303                            origin: PhotoOrigin::NativeStill,
304                        })
305                    })();
306                    Poll::Ready(result)
307                }
308            }
309        })
310    }
311    fn set_control(&self, _: CameraControl) -> Result<(), CameraError> {
312        Err(CameraError::new(
313            CameraErrorKind::Unsupported,
314            "Native camera controls are not exposed by this profile",
315        ))
316    }
317    fn stop(&self) {
318        self.camera.stop();
319    }
320}
321
322struct AppleCameraRecording(Rc<native::Recording>);
323impl NativeCameraRecording for AppleCameraRecording {
324    fn finish(&self) -> CameraFuture<CameraVideo> {
325        self.0.finish();
326        let native = self.0.clone();
327        wait(move || native.poll())
328    }
329    fn cancel(&self) {
330        self.0.cancel();
331    }
332}