mediadecode-webcodecs 0.2.0

//! Refcounted byte buffer for WebCodecs decoder output.
//!
//! `mediadecode::decoder::VideoStreamDecoder::Buffer` requires
//! `AsRef<[u8]>`. WebCodecs' native `VideoFrame` exposes pixels
//! only via the asynchronous `copyTo()` method, which returns one
//! contiguous `BufferSource` plus a `PlaneLayout` array describing
//! the offset and stride of each plane.
//!
//! `WebCodecsBuffer` represents a *view* into that contiguous
//! allocation. Planes share a single `Arc<Vec<u8>>`; each plane's
//! buffer carries an offset + length so its `AsRef<[u8]>` returns
//! only the bytes belonging to that plane. Cloning a buffer is an
//! `Arc::clone` plus copying two `usize` words — no per-plane
//! memcpy.

use std::sync::Arc;

/// Refcounted view over a slice of an `Arc<Vec<u8>>`.
/// Multiple buffers can share the same underlying allocation
/// without per-plane memcpy.
///
/// Wraps `Arc<Vec<u8>>` rather than `Arc<[u8]>` so the
/// allocation pipeline stays fallible end-to-end: the data
/// `Vec` itself is allocated via `Vec::try_reserve_exact`
/// upstream (see `copy_video_frame`), and `Arc::new` here
/// only allocates the small refcount header (~32 bytes).
/// Codex round 21 flagged that the prior `Arc::from(Vec)`
/// path performed a *second* `size`-byte allocation when
/// promoting the Vec to `Arc<[u8]>`; for cap-near frames
/// (~256 MiB) that allocation could panic on OOM and abort
/// the wasm tab. With `Arc<Vec<u8>>` the second allocation
/// is bounded to the refcount header — a size that almost
/// never fails to allocate, and even on failure the tab
/// has already exhausted memory in ways the adapter can't
/// recover from.
#[derive(Debug, Clone, Default)]
pub struct WebCodecsBuffer {
  inner: Option<Arc<Vec<u8>>>,
  start: usize,
  len: usize,
}

impl WebCodecsBuffer {
  /// Empty placeholder buffer (zero-length view, no allocation).
  /// Used to fill unused plane slots in
  /// [`mediadecode::frame::VideoFrame`]'s fixed-size plane array.
  pub const fn empty() -> Self {
    Self {
      inner: None,
      start: 0,
      len: 0,
    }
  }

  /// Wrap an owned byte buffer as a single-view buffer
  /// covering the whole allocation. Calls `Arc::new(bytes)`,
  /// which moves the `Vec` into the Arc (no data memcpy)
  /// and allocates only a small refcount header.
  ///
  /// `Arc::new` is panic-on-OOM. Codex round 22 [rejected]
  /// flagged this as a residual infallible allocation. The
  /// header is `sizeof(ArcInner<Vec<u8>>) ≈ 40 bytes`
  /// (two `usize` refcount fields + a `Vec<u8>` triple); a
  /// system that just fallibly allocated 256 MiB for the
  /// data Vec but cannot allocate 40 more bytes for the
  /// refcount is in a state where any error path would
  /// also fail. `Arc::try_new` (which would surface this
  /// allocation as a `Result`) is unstable in stable Rust,
  /// and the alternatives (vendoring a custom refcount
  /// type or skipping refcounting and per-plane-copying)
  /// trade real complexity / overhead for an unobservable
  /// hardening gain. Holding.
  pub fn from_bytes(bytes: Vec<u8>) -> Self {
    let len = bytes.len();
    Self {
      inner: Some(Arc::new(bytes)),
      start: 0,
      len,
    }
  }

  /// Build a per-plane view over an existing shared
  /// allocation. `start..start + len` must lie within
  /// `arc.len()` — the bound is checked in *every* build
  /// (codex round 12 flagged that the previous
  /// `debug_assert`-only check left release builds with a
  /// safe-code footgun). Visibility is `pub(crate)` so
  /// external API callers can't construct an out-of-range
  /// view at all; internal callers (`copy_video_frame`)
  /// compute bounds from `PlaneLayout.offset` /
  /// `total_size` arithmetic that's already explicitly
  /// validated.
  pub(crate) fn from_arc_range(arc: Arc<Vec<u8>>, start: usize, len: usize) -> Self {
    let end = start
      .checked_add(len)
      .expect("plane range start + len overflows usize");
    assert!(
      end <= arc.len(),
      "plane range out of bounds: start={start} len={len} arc.len={}",
      arc.len(),
    );
    Self {
      inner: Some(arc),
      start,
      len,
    }
  }

  /// Length of this view.
  pub const fn len(&self) -> usize {
    self.len
  }

  /// `true` if this is the empty placeholder.
  pub const fn is_empty(&self) -> bool {
    self.len == 0
  }
}

impl AsRef<[u8]> for WebCodecsBuffer {
  fn as_ref(&self) -> &[u8] {
    match &self.inner {
      Some(arc) => &arc[self.start..self.start + self.len],
      None => &[],
    }
  }
}