Skip to main content

camera/
frame.rs

1//! Immutable frames, bounded storage, and independent cancellation-safe readers.
2use crate::format::*;
3use crate::{pixels::Pixels, CameraError, CameraResult, StreamStats, SubscriptionOptions};
4use parking_lot::Mutex;
5use std::{
6    collections::VecDeque,
7    sync::{
8        atomic::{AtomicBool, AtomicU64, Ordering},
9        Arc, Weak,
10    },
11    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
12};
13use tokio::sync::watch;
14static NEXT_SESSION: AtomicU64 = AtomicU64::new(1);
15const MAX_FRAME_BYTES: usize = 128 * 1024 * 1024;
16pub(crate) const FRAME_ERROR_RECOVERY_THRESHOLD: u64 = 8;
17
18#[derive(Clone, Copy, Debug, PartialEq, Eq)]
19pub(crate) enum RecoveryTrigger {
20    SourceStopped,
21    SourceStalled,
22    FrameErrors { consecutive: u64 },
23}
24#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
25/// Values for `FrameKey`.
26pub struct FrameKey {
27    /// The session value.
28    pub session: u64,
29    /// The sequence value.
30    pub sequence: u64,
31}
32#[derive(Clone, Debug)]
33enum Storage {
34    Rgb(Arc<Pixels<u8>>),
35    Bytes(Arc<Vec<u8>>),
36}
37impl Storage {
38    fn bytes(&self) -> &[u8] {
39        match self {
40            Self::Rgb(p) => p.as_slice().expect("packed RGB"),
41            Self::Bytes(p) => p,
42        }
43    }
44    fn bytes_mut(&mut self) -> &mut [u8] {
45        match self {
46            Self::Rgb(p) => Arc::get_mut(p)
47                .expect("leased RGB")
48                .as_slice_mut()
49                .expect("packed RGB"),
50            Self::Bytes(p) => Arc::get_mut(p).expect("leased bytes"),
51        }
52    }
53    fn unique(&mut self) -> bool {
54        fn detach<T: Default>(p: &mut Arc<T>) -> bool {
55            if Arc::get_mut(p).is_some() {
56                return true;
57            }
58            if Arc::strong_count(p) != 1 {
59                return false;
60            }
61            let old = std::mem::replace(p, Arc::new(T::default()));
62            match Arc::try_unwrap(old) {
63                Ok(data) => {
64                    *p = Arc::new(data);
65                    true
66                }
67                Err(shared) => {
68                    *p = shared;
69                    false
70                }
71            }
72        }
73        match self {
74            Self::Rgb(p) => {
75                if Arc::get_mut(p).is_some() {
76                    return true;
77                }
78                if Arc::strong_count(p) != 1 {
79                    return false;
80                }
81                let old = std::mem::replace(p, Arc::new(Pixels::zeros((0, 0, 3))));
82                match Arc::try_unwrap(old) {
83                    Ok(data) => {
84                        *p = Arc::new(data);
85                        true
86                    }
87                    Err(shared) => {
88                        *p = shared;
89                        false
90                    }
91                }
92            }
93            Self::Bytes(p) => detach(p),
94        }
95    }
96    fn retained(&self) -> bool {
97        match self {
98            Self::Rgb(p) => Arc::strong_count(p) > 1,
99            Self::Bytes(p) => Arc::strong_count(p) > 1,
100        }
101    }
102}
103/// Cheaply shared immutable frame. RGB/native bytes never change while retained.
104#[derive(Debug)]
105pub struct CapturedFrame {
106    /// The key value.
107    pub key: FrameKey,
108    storage: Storage,
109    layout: FrameLayout,
110    /// Host monotonic processing-entry time, not the sensor exposure time.
111    pub captured_at: Instant,
112    /// The timestamp ns value.
113    pub timestamp_ns: u64,
114    /// The source timestamp ns value.
115    pub source_timestamp_ns: Option<i64>,
116    source_clock: ClockDomain,
117    /// The source sequence value.
118    pub source_sequence: Option<u64>,
119}
120/// Convenient result type for `Frame`.
121pub type Frame = Arc<CapturedFrame>;
122impl CapturedFrame {
123    /// Performs the `age` operation.
124    pub fn age(&self) -> Duration {
125        self.captured_at.elapsed()
126    }
127    /// Performs the `layout` operation.
128    pub fn layout(&self) -> &FrameLayout {
129        &self.layout
130    }
131    /// Performs the `bytes` operation.
132    pub fn bytes(&self) -> &[u8] {
133        self.storage.bytes()
134    }
135    /// Performs the `plane` operation.
136    pub fn plane(&self, index: usize) -> Option<&[u8]> {
137        let p = self.layout.planes.get(index)?;
138        self.bytes().get(p.offset..p.offset + p.length)
139    }
140    /// Performs the `rgb_view` operation.
141    pub fn rgb_view(&self) -> CameraResult<RgbView<'_>> {
142        if self.layout.format != PixelFormat::Rgb8 || self.layout.planes.len() != 1 {
143            return Err(CameraError::unsupported_format(
144                "Frame layout is not packed RGB8".into(),
145            ));
146        }
147        let plane = self.layout.planes[0];
148        if plane.pixel_stride != 3 {
149            return Err(CameraError::invalid_frame(
150                "RGB8 pixel stride must be three bytes".into(),
151            ));
152        }
153        let bytes = self
154            .bytes()
155            .get(plane.offset..plane.offset + plane.length)
156            .ok_or_else(|| CameraError::invalid_frame("RGB plane is outside the frame".into()))?;
157        Ok(RgbView {
158            bytes,
159            width: self.layout.width as usize,
160            height: self.layout.height as usize,
161            row_stride: plane.row_stride,
162        })
163    }
164    /// Performs the `source_timestamp` operation.
165    pub fn source_timestamp(&self) -> Option<SourceTimestamp> {
166        self.source_timestamp_ns.map(|nanoseconds| SourceTimestamp {
167            nanoseconds,
168            clock: self.source_clock,
169        })
170    }
171    /// Performs the `copy_to` operation.
172    pub fn copy_to(&self, out: &mut [u8]) -> CameraResult<()> {
173        if out.len() != self.bytes().len() {
174            return Err(CameraError::invalid_frame(
175                "Destination length differs from frame".into(),
176            ));
177        }
178        out.copy_from_slice(self.bytes());
179        Ok(())
180    }
181    /// Performs the `to_owned_bytes` operation.
182    pub fn to_owned_bytes(&self) -> Vec<u8> {
183        self.bytes().to_vec()
184    }
185    #[allow(dead_code)]
186    pub(crate) fn rgb_pixels(&self) -> CameraResult<&Arc<Pixels<u8>>> {
187        match &self.storage {
188            Storage::Rgb(p) => Ok(p),
189            _ => Err(CameraError::unsupported_format(
190                "Frame is native; request RGB or convert explicitly".into(),
191            )),
192        }
193    }
194    #[cfg(feature = "ndarray")]
195    /// Performs the `ndarray_view` operation.
196    pub fn ndarray_view(&self) -> CameraResult<ndarray::ArrayView3<'_, u8>> {
197        use ndarray::ShapeBuilder;
198        let view = self.rgb_view()?;
199        ndarray::ArrayView3::from_shape(
200            (view.height, view.width, 3).strides((view.row_stride, 3, 1)),
201            view.bytes,
202        )
203        .map_err(|error| CameraError::invalid_frame(error.to_string()))
204    }
205}
206
207#[derive(Clone, Copy, Debug)]
208/// Values for `RgbView`.
209pub struct RgbView<'a> {
210    bytes: &'a [u8],
211    width: usize,
212    height: usize,
213    row_stride: usize,
214}
215
216impl<'a> RgbView<'a> {
217    /// Performs the `width` operation.
218    pub fn width(&self) -> usize {
219        self.width
220    }
221
222    /// Performs the `height` operation.
223    pub fn height(&self) -> usize {
224        self.height
225    }
226
227    /// Performs the `row_stride` operation.
228    pub fn row_stride(&self) -> usize {
229        self.row_stride
230    }
231
232    /// Performs the `row` operation.
233    pub fn row(&self, index: usize) -> Option<&'a [u8]> {
234        if index >= self.height {
235            return None;
236        }
237        let start = index.checked_mul(self.row_stride)?;
238        self.bytes
239            .get(start..start.checked_add(self.width.checked_mul(3)?)?)
240    }
241
242    /// Performs the `bytes` operation.
243    pub fn bytes(&self) -> &'a [u8] {
244        self.bytes
245    }
246}
247#[derive(Clone, Default, Debug)]
248/// Values for `FrameMetrics`.
249pub struct FrameMetrics {
250    /// Number of frames received from the backend.
251    pub received: u64,
252    /// Number of frames published to consumers.
253    pub published: u64,
254    /// Frames dropped because the bounded pool was exhausted.
255    pub pool_drops: u64,
256    /// Number of frame conversion failures.
257    pub conversion_errors: u64,
258    /// Failed conversions since the latest successfully published frame.
259    pub consecutive_conversion_errors: u64,
260    /// Largest failed-conversion burst observed in the current session.
261    pub max_consecutive_conversion_errors: u64,
262    /// The allocated buffers value.
263    pub allocated_buffers: usize,
264    /// The allocated bytes value.
265    pub allocated_bytes: usize,
266    /// The retained buffers value.
267    pub retained_buffers: usize,
268    /// The conversion total ns value.
269    pub conversion_total_ns: u64,
270    /// The conversion max ns value.
271    pub conversion_max_ns: u64,
272    /// Quantiles of at most the latest 256 published-frame conversion durations.
273    pub conversion_p50_ns: u64,
274    /// The conversion p95 ns value.
275    pub conversion_p95_ns: u64,
276}
277#[derive(Clone, Default)]
278struct Snapshot {
279    session: u64,
280    active: bool,
281    recovering: bool,
282    reconnect_enabled: bool,
283    latest: Option<Frame>,
284}
285struct Publication {
286    session: u64,
287    layout: FrameLayout,
288    timestamp: Option<SourceTimestamp>,
289    source_sequence: Option<u64>,
290    captured_at: Instant,
291    elapsed: u64,
292}
293struct Slot {
294    data: Option<Storage>,
295    bytes: usize,
296}
297struct Pool {
298    slots: Vec<Slot>,
299    budget: MemoryBudget,
300    metrics: FrameMetrics,
301    started: Option<Instant>,
302    stopped: Option<Instant>,
303    last_source_activity: Option<Instant>,
304    recent: VecDeque<Instant>,
305    conversion_samples: VecDeque<u64>,
306    last_error_report: Option<Instant>,
307    suppressed_error_reports: u64,
308}
309struct Subscriber {
310    queue: Mutex<VecDeque<Frame>>,
311    delivery: DeliveryPolicy,
312    dropped: AtomicU64,
313    max_rate: Option<FrameRate>,
314    last_enqueued: Mutex<Option<Instant>>,
315    owner: std::sync::OnceLock<Arc<AtomicBool>>,
316}
317/// Internal publisher. Public applications receive FrameReceiver instead.
318#[derive(Clone)]
319pub struct FrameHub {
320    state: watch::Sender<Snapshot>,
321    pool: Arc<Mutex<Pool>>,
322    subscribers: Arc<Mutex<Vec<Weak<Subscriber>>>>,
323    native_output: Arc<AtomicBool>,
324    events: Arc<Mutex<Option<tokio::sync::broadcast::Sender<crate::SessionEvent>>>>,
325    recovery_wake: watch::Sender<u64>,
326}
327impl Default for FrameHub {
328    fn default() -> Self {
329        Self::new(6)
330    }
331}
332impl FrameHub {
333    /// Creates a frame hub with a bounded reusable-buffer pool.
334    pub fn new(capacity: usize) -> Self {
335        let (state, _) = watch::channel(Snapshot::default());
336        let (recovery_wake, _) = watch::channel(0);
337        Self {
338            state,
339            pool: Arc::new(Mutex::new(Pool {
340                slots: vec![],
341                budget: MemoryBudget {
342                    buffers: capacity.max(2),
343                    ..Default::default()
344                },
345                metrics: FrameMetrics::default(),
346                started: None,
347                stopped: None,
348                last_source_activity: None,
349                recent: VecDeque::new(),
350                conversion_samples: VecDeque::with_capacity(256),
351                last_error_report: None,
352                suppressed_error_reports: 0,
353            })),
354            subscribers: Arc::new(Mutex::new(vec![])),
355            native_output: Arc::new(AtomicBool::new(false)),
356            events: Arc::new(Mutex::new(None)),
357            recovery_wake,
358        }
359    }
360    pub(crate) fn configure(&self, r: &StreamRequest) -> CameraResult<()> {
361        if self.is_streaming() {
362            return Err(CameraError::invalid_state(
363                "Stop before configuring buffers".into(),
364            ));
365        }
366        let mut pool = self.pool.lock();
367        if pool.slots.iter().any(|s| s.data.is_none() && s.bytes > 0) {
368            return Err(CameraError::invalid_state(
369                "Frame conversion is still finishing".into(),
370            ));
371        }
372        pool.slots
373            .retain_mut(|s| s.data.as_mut().is_none_or(|d| !d.unique()));
374        if pool.slots.len() > r.memory.buffers
375            || pool.slots.iter().map(|s| s.bytes).sum::<usize>() > r.memory.bytes
376        {
377            return Err(CameraError::invalid_config(
378                "Retained frames exceed the new budget".into(),
379            ));
380        }
381        pool.budget = r.memory;
382        self.native_output
383            .store(r.output == OutputFormat::Native, Ordering::Release);
384        Ok(())
385    }
386    /// Starts a new stream generation and returns its session identifier.
387    pub fn start(&self) -> u64 {
388        let mut pool = self.pool.lock();
389        pool.metrics = FrameMetrics::default();
390        pool.started = Some(Instant::now());
391        pool.stopped = None;
392        pool.last_source_activity = Some(Instant::now());
393        pool.recent.clear();
394        pool.conversion_samples.clear();
395        pool.last_error_report = None;
396        pool.suppressed_error_reports = 0;
397        let session = NEXT_SESSION.fetch_add(1, Ordering::Relaxed);
398        self.clear_queues();
399        let current = self.state.borrow();
400        let recovering = current.recovering;
401        let reconnect_enabled = current.reconnect_enabled;
402        drop(current);
403        self.state.send_replace(Snapshot {
404            session,
405            active: true,
406            recovering,
407            reconnect_enabled,
408            latest: None,
409        });
410        session
411    }
412    pub(crate) fn set_event_sender(
413        &self,
414        sender: tokio::sync::broadcast::Sender<crate::SessionEvent>,
415    ) {
416        *self.events.lock() = Some(sender);
417    }
418
419    fn report_resource_pressure(&self, dropped_frames: u64) {
420        if let Some(sender) = self.events.lock().as_ref() {
421            let _ = sender.send(crate::SessionEvent::ResourcePressure { dropped_frames });
422        }
423    }
424    fn clear_queues(&self) {
425        self.subscribers.lock().retain(|s| {
426            if let Some(s) = s.upgrade() {
427                s.queue.lock().clear();
428                true
429            } else {
430                false
431            }
432        });
433    }
434    pub(crate) fn begin_recovery(&self) {
435        self.state.send_modify(|s| s.recovering = true);
436    }
437    pub(crate) fn end_recovery(&self) {
438        self.state.send_modify(|s| s.recovering = false);
439    }
440    pub(crate) fn enable_recovery(&self) {
441        self.state.send_modify(|s| s.reconnect_enabled = true);
442    }
443    pub(crate) fn disable_recovery(&self) {
444        self.state.send_modify(|s| {
445            s.reconnect_enabled = false;
446            s.recovering = false;
447        });
448    }
449    /// Marks the current stream generation as stopped and wakes subscribers.
450    pub fn stop(&self) {
451        self.pool.lock().stopped = Some(Instant::now());
452        self.clear_queues();
453        self.state.send_modify(|s| {
454            s.active = false;
455            s.latest = None;
456        });
457        self.wake_recovery();
458    }
459    /// Returns the current stream session identifier.
460    pub fn session(&self) -> u64 {
461        self.state.borrow().session
462    }
463    /// Returns whether the frame hub currently accepts published frames.
464    pub fn is_streaming(&self) -> bool {
465        self.state.borrow().active
466    }
467    /// Returns the latest published frame, if one exists.
468    pub fn latest(&self) -> Option<Frame> {
469        self.state.borrow().latest.clone()
470    }
471    #[cfg(test)]
472    pub(crate) fn source_activity_is_stale(&self, timeout: Duration) -> bool {
473        self.pool
474            .lock()
475            .last_source_activity
476            .is_none_or(|activity| activity.elapsed() > timeout)
477    }
478    fn wake_recovery(&self) {
479        self.recovery_wake
480            .send_modify(|generation| *generation = generation.wrapping_add(1));
481    }
482    pub(crate) fn recovery_trigger(&self, stall_timeout: Duration) -> Option<RecoveryTrigger> {
483        if !self.state.borrow().active {
484            return Some(RecoveryTrigger::SourceStopped);
485        }
486        let pool = self.pool.lock();
487        if pool.metrics.consecutive_conversion_errors >= FRAME_ERROR_RECOVERY_THRESHOLD {
488            return Some(RecoveryTrigger::FrameErrors {
489                consecutive: pool.metrics.consecutive_conversion_errors,
490            });
491        }
492        pool.last_source_activity
493            .is_none_or(|activity| activity.elapsed() >= stall_timeout)
494            .then_some(RecoveryTrigger::SourceStalled)
495    }
496    fn source_stall_remaining(&self, timeout: Duration) -> Duration {
497        self.pool
498            .lock()
499            .last_source_activity
500            .map_or(Duration::ZERO, |activity| {
501                timeout.saturating_sub(activity.elapsed())
502            })
503    }
504    pub(crate) async fn wait_for_recovery_trigger(
505        &self,
506        stall_timeout: Duration,
507    ) -> RecoveryTrigger {
508        let mut wake = self.recovery_wake.subscribe();
509        loop {
510            if let Some(trigger) = self.recovery_trigger(stall_timeout) {
511                return trigger;
512            }
513            let remaining = self.source_stall_remaining(stall_timeout);
514            tokio::select! {
515                result = wake.changed() => {
516                    if result.is_err() {
517                        return RecoveryTrigger::SourceStopped;
518                    }
519                }
520                _ = tokio::time::sleep(remaining) => {}
521            }
522        }
523    }
524    fn record_conversion_error(&self, session: u64, source_activity: bool) {
525        {
526            let state = self.state.borrow();
527            if !state.active || state.session != session {
528                return;
529            }
530        }
531        let notify = {
532            let mut pool = self.pool.lock();
533            if source_activity {
534                pool.metrics.received += 1;
535                pool.last_source_activity = Some(Instant::now());
536            }
537            pool.metrics.conversion_errors += 1;
538            pool.metrics.consecutive_conversion_errors += 1;
539            pool.metrics.max_consecutive_conversion_errors = pool
540                .metrics
541                .max_consecutive_conversion_errors
542                .max(pool.metrics.consecutive_conversion_errors);
543            pool.metrics.consecutive_conversion_errors == FRAME_ERROR_RECOVERY_THRESHOLD
544        };
545        if notify {
546            self.wake_recovery();
547        }
548    }
549    #[allow(dead_code)]
550    pub(crate) fn record_input_error(&self, session: u64) {
551        self.record_conversion_error(session, true);
552    }
553    #[allow(dead_code)]
554    pub(crate) fn log_frame_error(&self, backend: &str, error: &CameraError) {
555        let now = Instant::now();
556        let report = {
557            let mut pool = self.pool.lock();
558            if pool.last_error_report.is_some_and(|previous| {
559                now.saturating_duration_since(previous) < Duration::from_secs(1)
560            }) {
561                pool.suppressed_error_reports += 1;
562                None
563            } else {
564                let suppressed = std::mem::take(&mut pool.suppressed_error_reports);
565                pool.last_error_report = Some(now);
566                Some(suppressed)
567            }
568        };
569        if let Some(suppressed) = report {
570            if suppressed == 0 {
571                log::warn!("{backend} frame rejected: {error}");
572            } else {
573                log::warn!(
574                    "{backend} frame rejected: {error} ({suppressed} similar errors suppressed)"
575                );
576            }
577        }
578    }
579    pub(crate) fn wants_native(&self) -> bool {
580        self.native_output.load(Ordering::Acquire)
581    }
582    #[allow(dead_code)]
583    pub(crate) fn record_input_drop(&self, session: u64) {
584        if self.session() == session {
585            let mut pool = self.pool.lock();
586            pool.last_source_activity = Some(Instant::now());
587            pool.metrics.received += 1;
588            pool.metrics.pool_drops += 1;
589            let dropped = pool.metrics.pool_drops;
590            drop(pool);
591            self.report_resource_pressure(dropped);
592        }
593    }
594    #[doc(hidden)]
595    pub fn subscribe_with(&self, options: SubscriptionOptions) -> CameraResult<FrameReceiver> {
596        let budget = self.pool.lock().budget;
597        options.validate(budget)?;
598        let subscriber = Arc::new(Subscriber {
599            queue: Mutex::new(VecDeque::new()),
600            delivery: options.delivery,
601            dropped: AtomicU64::new(0),
602            max_rate: options.max_rate,
603            last_enqueued: Mutex::new(None),
604            owner: std::sync::OnceLock::new(),
605        });
606        let state = self.state.subscribe();
607        {
608            let snapshot = state.borrow();
609            let mut subs = self.subscribers.lock();
610            if let Some(f) = snapshot.latest.clone() {
611                *subscriber.last_enqueued.lock() = Some(f.captured_at);
612                subscriber.queue.lock().push_back(f);
613            }
614            subs.push(Arc::downgrade(&subscriber));
615        }
616        Ok(FrameReceiver {
617            state,
618            subscriber,
619            last: None,
620        })
621    }
622    /// Waits for a frame newer than `after` until the timeout expires.
623    pub async fn wait_after(
624        &self,
625        after: Option<FrameKey>,
626        timeout: Duration,
627    ) -> CameraResult<Frame> {
628        let mut rx = self.subscribe_with(SubscriptionOptions::latest())?;
629        rx.last = after.or_else(|| rx.state.borrow().latest.as_ref().map(|frame| frame.key));
630        rx.next_timeout(timeout).await
631    }
632
633    pub(crate) async fn wait_first_in(
634        &self,
635        session: u64,
636        timeout: Duration,
637    ) -> CameraResult<Frame> {
638        if self.session() != session {
639            return Err(CameraError::stream_stopped());
640        }
641        let mut rx = self.subscribe_with(SubscriptionOptions::latest())?;
642        let frame = rx.next_timeout(timeout).await?;
643        if frame.key.session != session {
644            return Err(CameraError::stream_stopped());
645        }
646        Ok(frame)
647    }
648    /// Publishes an RGB frame filled by `convert` into a pooled buffer.
649    pub fn publish_rgb(
650        &self,
651        session: u64,
652        width: u32,
653        height: u32,
654        source_timestamp_ns: Option<i64>,
655        convert: impl FnOnce(&mut [u8]) -> CameraResult<()>,
656    ) -> CameraResult<bool> {
657        self.publish(
658            session,
659            FrameLayout::rgb(width, height),
660            source_timestamp_ns.map(|nanoseconds| SourceTimestamp {
661                nanoseconds,
662                clock: ClockDomain::Unknown,
663            }),
664            None,
665            true,
666            convert,
667        )
668    }
669    #[allow(dead_code)]
670    pub(crate) fn publish_rgb_metadata(
671        &self,
672        session: u64,
673        width: u32,
674        height: u32,
675        timestamp: Option<SourceTimestamp>,
676        sequence: Option<u64>,
677        convert: impl FnOnce(&mut [u8]) -> CameraResult<()>,
678    ) -> CameraResult<bool> {
679        self.publish(
680            session,
681            FrameLayout::rgb(width, height),
682            timestamp,
683            sequence,
684            true,
685            convert,
686        )
687    }
688    pub(crate) fn publish_native_into(
689        &self,
690        session: u64,
691        layout: FrameLayout,
692        timestamp: Option<SourceTimestamp>,
693        convert: impl FnOnce(&mut [u8]) -> CameraResult<()>,
694    ) -> CameraResult<bool> {
695        let length = layout
696            .planes
697            .iter()
698            .try_fold(0, |n: usize, p| {
699                p.offset.checked_add(p.length).map(|end| n.max(end))
700            })
701            .ok_or_else(|| CameraError::invalid_frame("Native plane extent overflow".into()))?;
702        layout.validate(length)?;
703        self.publish(session, layout, timestamp, None, false, convert)
704    }
705    #[cfg_attr(not(feature = "custom-backend"), allow(dead_code))]
706    pub(crate) fn publish_native(
707        &self,
708        session: u64,
709        layout: FrameLayout,
710        timestamp: Option<SourceTimestamp>,
711        sequence: Option<u64>,
712        parts: &[&[u8]],
713    ) -> CameraResult<bool> {
714        let len = parts
715            .iter()
716            .try_fold(0usize, |n, p| n.checked_add(p.len()))
717            .ok_or_else(|| CameraError::invalid_frame("Native size overflow".into()))?;
718        layout.validate(len)?;
719        let end = layout
720            .planes
721            .iter()
722            .map(|p| p.offset + p.length)
723            .max()
724            .unwrap_or(0);
725        if end != len {
726            return Err(CameraError::invalid_frame(
727                "Native payload contains undescribed trailing data".into(),
728            ));
729        }
730        self.publish(session, layout, timestamp, sequence, false, |out| {
731            let mut offset = 0;
732            for p in parts {
733                out[offset..offset + p.len()].copy_from_slice(p);
734                offset += p.len();
735            }
736            Ok(())
737        })
738    }
739
740    #[cfg_attr(not(feature = "custom-backend"), allow(dead_code))]
741    pub(crate) fn writable_native(
742        &self,
743        session: u64,
744        layout: FrameLayout,
745    ) -> CameraResult<NativeWriteLease> {
746        let length = Self::frame_length(&layout, false)?;
747        layout.validate(length)?;
748        let lease = self
749            .reserve(session, &layout, false)?
750            .ok_or(CameraError::buffer_exhausted())?;
751        Ok(NativeWriteLease {
752            lease: Some(lease),
753            session,
754            layout,
755            timestamp: None,
756            captured_at: Instant::now(),
757        })
758    }
759
760    fn frame_length(layout: &FrameLayout, rgb: bool) -> CameraResult<usize> {
761        let length = if rgb {
762            (layout.width as usize)
763                .checked_mul(layout.height as usize)
764                .and_then(|n| n.checked_mul(3))
765        } else {
766            layout
767                .planes
768                .iter()
769                .filter_map(|plane| plane.offset.checked_add(plane.length))
770                .max()
771        };
772        length
773            .filter(|&length| length > 0 && length <= MAX_FRAME_BYTES)
774            .ok_or_else(|| CameraError::invalid_frame("Frame exceeds size limit".into()))
775    }
776
777    fn reserve(
778        &self,
779        session: u64,
780        layout: &FrameLayout,
781        rgb: bool,
782    ) -> CameraResult<Option<Lease>> {
783        {
784            let state = self.state.borrow();
785            if !state.active || state.session != session {
786                return Ok(None);
787            }
788        }
789        let length = Self::frame_length(layout, rgb)?;
790        let mut pool = self.pool.lock();
791        {
792            let state = self.state.borrow();
793            if !state.active || state.session != session {
794                return Ok(None);
795            }
796        }
797        pool.metrics.received += 1;
798        pool.last_source_activity = Some(Instant::now());
799        let index = pool
800            .slots
801            .iter_mut()
802            .position(|slot| slot.data.as_mut().is_some_and(Storage::unique));
803        let index = match index {
804            Some(index) => index,
805            None if pool.slots.len() < pool.budget.buffers => {
806                pool.slots.push(Slot {
807                    data: None,
808                    bytes: 0,
809                });
810                pool.slots.len() - 1
811            }
812            _ => {
813                pool.metrics.pool_drops += 1;
814                let dropped = pool.metrics.pool_drops;
815                drop(pool);
816                self.report_resource_pressure(dropped);
817                return Ok(None);
818            }
819        };
820        let used: usize = pool.slots.iter().map(|slot| slot.bytes).sum();
821        if length
822            > pool
823                .budget
824                .bytes
825                .saturating_sub(used - pool.slots[index].bytes)
826        {
827            if pool.slots[index].bytes == 0 {
828                pool.slots.pop();
829            }
830            pool.metrics.pool_drops += 1;
831            let dropped = pool.metrics.pool_drops;
832            drop(pool);
833            self.report_resource_pressure(dropped);
834            return Ok(None);
835        }
836        let available = pool
837            .budget
838            .bytes
839            .saturating_sub(used - pool.slots[index].bytes);
840        let existing = pool.slots[index].data.take();
841        let storage = match existing {
842            Some(Storage::Rgb(pixels))
843                if rgb && pixels.dim() == (layout.height as usize, layout.width as usize, 3) =>
844            {
845                Storage::Rgb(pixels)
846            }
847            Some(Storage::Bytes(mut bytes)) if !rgb => {
848                let buffer = Arc::get_mut(&mut bytes).expect("exclusive native slot");
849                if length > buffer.capacity() {
850                    bytes = Arc::new(vec![0; length]);
851                } else {
852                    buffer.resize(length, 0);
853                }
854                Storage::Bytes(bytes)
855            }
856            _ if rgb => Storage::Rgb(Arc::new(Pixels::zeros((
857                layout.height as usize,
858                layout.width as usize,
859                3,
860            )))),
861            _ => Storage::Bytes(Arc::new(vec![0; length])),
862        };
863        let allocated = match &storage {
864            Storage::Bytes(bytes) => bytes.capacity(),
865            Storage::Rgb(_) => length,
866        };
867        if allocated > available {
868            pool.slots[index].data = Some(Storage::Bytes(Arc::new(Vec::new())));
869            pool.slots[index].bytes = 0;
870            pool.metrics.pool_drops += 1;
871            let dropped = pool.metrics.pool_drops;
872            drop(pool);
873            self.report_resource_pressure(dropped);
874            return Ok(None);
875        }
876        pool.slots[index].bytes = allocated;
877        drop(pool);
878        Ok(Some(Lease {
879            hub: self.clone(),
880            index,
881            data: Some(storage),
882        }))
883    }
884
885    fn publish(
886        &self,
887        session: u64,
888        layout: FrameLayout,
889        timestamp: Option<SourceTimestamp>,
890        source_sequence: Option<u64>,
891        rgb: bool,
892        convert: impl FnOnce(&mut [u8]) -> CameraResult<()>,
893    ) -> CameraResult<bool> {
894        let now = Instant::now();
895        let Some(mut lease) = self.reserve(session, &layout, rgb)? else {
896            return Ok(false);
897        };
898        let begin = Instant::now();
899        let result = convert(lease.data.as_mut().unwrap().bytes_mut());
900        let elapsed = begin.elapsed().as_nanos().min(u64::MAX as u128) as u64;
901        if let Err(error) = result {
902            self.record_conversion_error(session, false);
903            return Err(error);
904        }
905        self.finish_publish(
906            Publication {
907                session,
908                layout,
909                timestamp,
910                source_sequence,
911                captured_at: now,
912                elapsed,
913            },
914            &lease,
915        )
916    }
917
918    fn finish_publish(&self, publication: Publication, lease: &Lease) -> CameraResult<bool> {
919        let Publication {
920            session,
921            layout,
922            timestamp,
923            source_sequence,
924            captured_at: now,
925            elapsed,
926        } = publication;
927        let timestamp_ns = SystemTime::now()
928            .duration_since(UNIX_EPOCH)
929            .unwrap_or_default()
930            .as_nanos()
931            .min(u64::MAX as u128) as u64;
932        let mut published = false;
933        self.state.send_if_modified(|state| {
934            if !state.active || state.session != session {
935                return false;
936            }
937            let sequence = state.latest.as_ref().map_or(1, |f| f.key.sequence + 1);
938            let frame = Arc::new(CapturedFrame {
939                key: FrameKey { session, sequence },
940                storage: lease.data.as_ref().unwrap().clone(),
941                layout,
942                captured_at: now,
943                timestamp_ns,
944                source_timestamp_ns: timestamp.map(|t| t.nanoseconds),
945                source_clock: timestamp.map_or(ClockDomain::Unknown, |t| t.clock),
946                source_sequence,
947            });
948            self.subscribers.lock().retain(|subscriber| {
949                let Some(subscriber) = subscriber.upgrade() else {
950                    return false;
951                };
952                let mut queue = subscriber.queue.lock();
953                if subscriber
954                    .owner
955                    .get()
956                    .is_some_and(|f| f.load(Ordering::Acquire))
957                {
958                    queue.clear();
959                    return false;
960                }
961                if let Some(rate) = subscriber.max_rate {
962                    let mut last = subscriber.last_enqueued.lock();
963                    if last.is_some_and(|previous| {
964                        frame.captured_at.saturating_duration_since(previous) < rate.interval()
965                    }) {
966                        subscriber.dropped.fetch_add(1, Ordering::Relaxed);
967                        return true;
968                    }
969                    *last = Some(frame.captured_at);
970                }
971                match subscriber.delivery {
972                    DeliveryPolicy::Latest => {
973                        subscriber
974                            .dropped
975                            .fetch_add(queue.len() as u64, Ordering::Relaxed);
976                        queue.clear();
977                        queue.push_back(frame.clone());
978                    }
979                    DeliveryPolicy::Buffered { capacity, overflow } => {
980                        if queue.len() >= capacity {
981                            subscriber.dropped.fetch_add(1, Ordering::Relaxed);
982                            if overflow == OverflowPolicy::DropNewest {
983                                return true;
984                            }
985                            queue.pop_front();
986                        }
987                        queue.push_back(frame.clone());
988                    }
989                }
990                true
991            });
992            state.latest = Some(frame);
993            published = true;
994            true
995        });
996        if published {
997            let mut pool = self.pool.lock();
998            if self.session() != session {
999                return Ok(true);
1000            }
1001            pool.metrics.published += 1;
1002            pool.metrics.consecutive_conversion_errors = 0;
1003            pool.metrics.conversion_total_ns =
1004                pool.metrics.conversion_total_ns.saturating_add(elapsed);
1005            pool.metrics.conversion_max_ns = pool.metrics.conversion_max_ns.max(elapsed);
1006            if pool.conversion_samples.len() == 256 {
1007                pool.conversion_samples.pop_front();
1008            }
1009            pool.conversion_samples.push_back(elapsed);
1010            pool.recent.push_back(now);
1011            while pool
1012                .recent
1013                .front()
1014                .is_some_and(|t| now.saturating_duration_since(*t) > Duration::from_secs(1))
1015            {
1016                pool.recent.pop_front();
1017            }
1018        }
1019        Ok(published)
1020    }
1021    /// Returns a snapshot of allocation, delivery, and conversion metrics.
1022    pub fn metrics(&self) -> FrameMetrics {
1023        let (mut samples, allocated_buffers, allocated_bytes, retained_buffers, metrics) = {
1024            let p = self.pool.lock();
1025            (
1026                p.conversion_samples.iter().copied().collect::<Vec<_>>(),
1027                p.slots.len(),
1028                p.slots.iter().map(|s| s.bytes).sum(),
1029                p.slots
1030                    .iter()
1031                    .filter(|s| s.data.as_ref().is_none_or(Storage::retained))
1032                    .count(),
1033                p.metrics.clone(),
1034            )
1035        };
1036        samples.sort_unstable();
1037        let quantile = |percent: usize| {
1038            samples
1039                .get((samples.len() * percent).div_ceil(100).saturating_sub(1))
1040                .copied()
1041                .unwrap_or(0)
1042        };
1043        FrameMetrics {
1044            conversion_p50_ns: quantile(50),
1045            conversion_p95_ns: quantile(95),
1046            allocated_buffers,
1047            allocated_bytes,
1048            retained_buffers,
1049            ..metrics
1050        }
1051    }
1052    /// Returns a snapshot of stream throughput and buffer statistics.
1053    pub fn stats(&self) -> StreamStats {
1054        let p = self.pool.lock();
1055        StreamStats {
1056            total_frames: p.metrics.received,
1057            dropped_frames: p.metrics.pool_drops + p.metrics.conversion_errors,
1058            current_fps: if self.is_streaming() {
1059                p.recent
1060                    .iter()
1061                    .filter(|t| t.elapsed() < Duration::from_secs(1))
1062                    .count() as f64
1063            } else {
1064                0.0
1065            },
1066            buffer_size: p.budget.buffers,
1067            buffered_frames: usize::from(self.latest().is_some()),
1068            uptime_seconds: p.started.map_or(0, |t| {
1069                p.stopped
1070                    .unwrap_or_else(Instant::now)
1071                    .saturating_duration_since(t)
1072                    .as_secs()
1073            }),
1074        }
1075    }
1076}
1077#[cfg_attr(not(feature = "custom-backend"), allow(dead_code))]
1078pub(crate) struct NativeWriteLease {
1079    lease: Option<Lease>,
1080    session: u64,
1081    layout: FrameLayout,
1082    timestamp: Option<SourceTimestamp>,
1083    captured_at: Instant,
1084}
1085
1086#[cfg_attr(not(feature = "custom-backend"), allow(dead_code))]
1087impl NativeWriteLease {
1088    pub(crate) fn bytes_mut(&mut self) -> &mut [u8] {
1089        self.lease
1090            .as_mut()
1091            .expect("lease is present until commit")
1092            .data
1093            .as_mut()
1094            .expect("reserved storage is present")
1095            .bytes_mut()
1096    }
1097
1098    pub(crate) fn set_timestamp(&mut self, timestamp: SourceTimestamp) {
1099        self.timestamp = Some(timestamp);
1100    }
1101
1102    pub(crate) fn commit(mut self) -> CameraResult<bool> {
1103        let lease = self.lease.take().expect("lease is present until commit");
1104        let hub = lease.hub.clone();
1105        hub.finish_publish(
1106            Publication {
1107                session: self.session,
1108                layout: self.layout,
1109                timestamp: self.timestamp,
1110                source_sequence: None,
1111                captured_at: self.captured_at,
1112                elapsed: 0,
1113            },
1114            &lease,
1115        )
1116    }
1117}
1118
1119struct Lease {
1120    hub: FrameHub,
1121    index: usize,
1122    data: Option<Storage>,
1123}
1124impl Drop for Lease {
1125    fn drop(&mut self) {
1126        self.hub.pool.lock().slots[self.index].data = self.data.take();
1127    }
1128}
1129/// Each receiver owns its cursor/queue. Dropping next() before it resolves does
1130/// not consume a frame. Stop wakes all receivers with StreamStopped.
1131pub struct FrameReceiver {
1132    state: watch::Receiver<Snapshot>,
1133    subscriber: Arc<Subscriber>,
1134    last: Option<FrameKey>,
1135}
1136impl std::fmt::Debug for FrameReceiver {
1137    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1138        f.debug_struct("FrameReceiver")
1139            .field("last", &self.last)
1140            .field("dropped", &self.dropped_frames())
1141            .finish()
1142    }
1143}
1144impl FrameReceiver {
1145    pub(crate) fn with_stop_flag(self, flag: Arc<AtomicBool>) -> Self {
1146        if flag.load(Ordering::Acquire) {
1147            self.subscriber.queue.lock().clear();
1148        }
1149        let _ = self.subscriber.owner.set(flag);
1150        self
1151    }
1152    /// Performs the `last_key` operation.
1153    pub fn last_key(&self) -> Option<FrameKey> {
1154        self.last
1155    }
1156    /// Performs the `queued_frames` operation.
1157    pub fn queued_frames(&self) -> usize {
1158        self.subscriber.queue.lock().len()
1159    }
1160    /// Performs the `dropped_frames` operation.
1161    pub fn dropped_frames(&self) -> u64 {
1162        self.subscriber.dropped.load(Ordering::Relaxed)
1163    }
1164    /// Performs the `next` operation.
1165    pub async fn next(&mut self) -> CameraResult<Frame> {
1166        loop {
1167            {
1168                let state = self.state.borrow_and_update();
1169                if self
1170                    .subscriber
1171                    .owner
1172                    .get()
1173                    .is_some_and(|f| f.load(Ordering::Acquire))
1174                    || (!state.active && !state.recovering && !state.reconnect_enabled)
1175                {
1176                    return Err(CameraError::stream_stopped());
1177                }
1178                let mut q = self.subscriber.queue.lock();
1179                while let Some(f) = q.pop_front() {
1180                    if Some(f.key) != self.last && f.key.session == state.session {
1181                        self.last = Some(f.key);
1182                        return Ok(f);
1183                    }
1184                }
1185            }
1186            self.state
1187                .changed()
1188                .await
1189                .map_err(|_| CameraError::stream_stopped())?;
1190        }
1191    }
1192    /// Performs the `next_timeout` operation.
1193    pub async fn next_timeout(&mut self, timeout: Duration) -> CameraResult<Frame> {
1194        tokio::time::timeout(timeout, self.next())
1195            .await
1196            .map_err(|_| CameraError::timeout(crate::OperationStage::FrameWait))?
1197    }
1198}