//! The v4l2loopback virtual webcam (PLAN.md, pipeline step 5 — the
//! Linux sink).
//!
//! Rendered virtual-camera frames are converted to YUYV and written to
//! a [v4l2loopback](https://github.com/v4l2loopback/v4l2loopback)
//! device, which conferencing tools (Teams, Slack, Chrome) then pick
//! up as an ordinary webcam.
//!
//! The device half is Linux-only; everything else — the RGBA→YUYV
//! conversion, the latest-frame handoff, the error handling — is
//! cross-platform and unit-tested. Creating an actual `/dev/video*`
//! device needs the v4l2loopback kernel module, which this container
//! cannot load; the device paths are exercised on a real machine.
//!
//! Typical setup (the `exclusive_caps` mode is what makes
//! Chrome-based consumers see the device):
//!
//! ```text
//! sudo apt install v4l2loopback-dkms
//! sudo modprobe v4l2loopback video_nr=10 card_label="kinect-view" exclusive_caps=1
//! kinect-view --loopback-path /dev/video10
//! ```

use std::path::Path;
use std::sync::Arc;
use std::sync::Mutex;
use std::sync::atomic::{AtomicBool, Ordering};
use std::thread::JoinHandle;

#[cfg(target_os = "linux")]
use anyhow::Context;
use anyhow::{Result, ensure};

use render::RenderedImage;

/// One pending frame handed to the writer thread.
struct PendingFrame {
    rgba: Arc<[u8]>,
    width: u32,
    height: u32,
}

/// Where converted frames go: the v4l2loopback device, or a test
/// collector.
pub trait LoopbackWriter: Send + 'static {
    /// Write one YUYV frame — exactly `width * height * 2` bytes.
    fn write_frame(&mut self, yuyv: &[u8], width: u32, height: u32) -> Result<()>;
}

/// The loopback sink: receives rendered frames, converts them, and
/// writes them out — on the caller's thread ([`LoopbackSink::with_writer`])
/// or on a dedicated writer thread with latest-frame semantics
/// ([`LoopbackSink::open`], so a slow device never stalls the UI).
pub struct LoopbackSink {
    mode: Mode,
}

enum Mode {
    /// Writes on the calling thread (tests, tools).
    Inline(Box<dyn LoopbackWriter>),
    /// The caller stores the latest frame; a writer thread converts and
    /// writes it.
    Threaded {
        latest: Arc<Mutex<Option<PendingFrame>>>,
        error: Arc<Mutex<Option<String>>>,
        shutdown: Arc<AtomicBool>,
        worker: Option<JoinHandle<()>>,
    },
}

impl LoopbackSink {
    /// Open the v4l2loopback output device at `path` and negotiate a
    /// YUYV format at `width x height`.
    ///
    /// The device must report video-output capability (with
    /// `exclusive_caps=1`, that is the *unattached* state — once this
    /// sink produces, the device announces capture capability for the
    /// conferencing tool). Fails clearly on Linux when the device is
    /// absent, not a V4L2 output device, or refuses the format — and
    /// on every non-Linux platform.
    pub fn open(path: impl AsRef<Path>, width: u32, height: u32) -> Result<Self> {
        let writer = open_device_writer(path.as_ref(), width, height)?;
        Ok(Self::threaded(writer))
    }

    /// A sink writing to an arbitrary [`LoopbackWriter`] on the calling
    /// thread — primarily for tests.
    pub fn with_writer(writer: Box<dyn LoopbackWriter>) -> Self {
        Self {
            mode: Mode::Inline(writer),
        }
    }

    /// Is the sink still active? (A writer failure disables it.)
    pub fn is_active(&self) -> bool {
        match &self.mode {
            Mode::Inline(_) => true,
            Mode::Threaded { error, .. } => error.lock().unwrap().is_none(),
        }
    }

    /// Push one rendered frame. Cheap: with a real device this only
    /// stores the latest frame; conversion and writing happen on the
    /// writer thread.
    pub fn push(&mut self, image: &RenderedImage) -> Result<()> {
        match &mut self.mode {
            Mode::Inline(writer) => {
                let yuyv = rgba_to_yuyv(&image.rgba, image.width, image.height)?;
                writer.write_frame(&yuyv, image.width, image.height)
            }
            Mode::Threaded { latest, error, .. } => {
                if let Some(error) = error.lock().unwrap().take() {
                    anyhow::bail!("loopback writer failed: {error}");
                }
                let frame = PendingFrame {
                    rgba: Arc::from(image.rgba.as_slice()),
                    width: image.width,
                    height: image.height,
                };
                *latest.lock().unwrap() = Some(frame);
                Ok(())
            }
        }
    }

    /// Build the threaded sink and start its writer loop.
    fn threaded(writer: Box<dyn LoopbackWriter>) -> Self {
        let latest = Arc::new(Mutex::new(None::<PendingFrame>));
        let error = Arc::new(Mutex::new(None::<String>));
        let shutdown = Arc::new(AtomicBool::new(false));

        let worker = {
            let latest = latest.clone();
            let error = error.clone();
            let shutdown = shutdown.clone();
            std::thread::spawn(move || {
                let mut writer = writer;
                loop {
                    if shutdown.load(Ordering::Relaxed) {
                        break;
                    }
                    let frame = latest.lock().unwrap().take();
                    let Some(frame) = frame else {
                        std::thread::sleep(std::time::Duration::from_millis(5));
                        continue;
                    };
                    let result = (|| -> Result<()> {
                        let yuyv = rgba_to_yuyv(&frame.rgba, frame.width, frame.height)?;
                        writer.write_frame(&yuyv, frame.width, frame.height)
                    })();
                    if let Err(e) = result {
                        *error.lock().unwrap() = Some(format!("{e:#}"));
                        break;
                    }
                }
            })
        };

        Self {
            mode: Mode::Threaded {
                latest,
                error,
                shutdown,
                worker: Some(worker),
            },
        }
    }
}

impl Drop for LoopbackSink {
    fn drop(&mut self) {
        if let Mode::Threaded {
            shutdown, worker, ..
        } = &mut self.mode
        {
            shutdown.store(true, Ordering::Relaxed);
            if let Some(worker) = worker.take() {
                let _ = worker.join();
            }
        }
    }
}

/// Convert an RGBA8 frame to YUYV (packed YUV 4:2:2): full-range
/// BT.601, the convention virtual-webcam consumers expect. Alpha is
/// ignored — rendered frames are already composited over the
/// background.
///
/// Layout: `[Y0, U, Y1, V]` per horizontal pixel pair, the chroma
/// averaged over the pair.
pub fn rgba_to_yuyv(rgba: &[u8], width: u32, height: u32) -> Result<Vec<u8>> {
    ensure!(
        width.is_multiple_of(2),
        "YUYV needs an even width, got {width}"
    );
    let pixel_count = width as usize * height as usize;
    ensure!(
        rgba.len() == pixel_count * 4,
        "expected {pixel_count} RGBA pixels, got {}",
        rgba.len() / 4
    );

    let mut yuyv = vec![0_u8; pixel_count * 2];
    for pair in 0..(width as usize * height as usize) / 2 {
        // The pixel pair this YUYV quartet covers.
        let px = pair * 2;
        let i = px * 4;
        let (r0, g0, b0) = (rgba[i] as f32, rgba[i + 1] as f32, rgba[i + 2] as f32);
        let (r1, g1, b1) = (rgba[i + 4] as f32, rgba[i + 5] as f32, rgba[i + 6] as f32);

        // BT.601 full range. Chroma is linear in RGB, so averaging the
        // pair's RGB is exactly averaging the pair's chroma.
        let y0 = clamp_u8(0.299 * r0 + 0.587 * g0 + 0.114 * b0 + 0.5);
        let y1 = clamp_u8(0.299 * r1 + 0.587 * g1 + 0.114 * b1 + 0.5);
        let (ra, ga, ba) = ((r0 + r1) * 0.5, (g0 + g1) * 0.5, (b0 + b1) * 0.5);
        let u = clamp_u8(-0.168_736 * ra - 0.331_264 * ga + 0.5 * ba + 128.5);
        let v = clamp_u8(0.5 * ra - 0.418_688 * ga - 0.081_312 * ba + 128.5);

        let o = pair * 4;
        yuyv[o] = y0;
        yuyv[o + 1] = u;
        yuyv[o + 2] = y1;
        yuyv[o + 3] = v;
    }
    Ok(yuyv)
}

fn clamp_u8(x: f32) -> u8 {
    x.clamp(0.0, 255.0) as u8
}

/// Open the v4l2loopback device writer. Linux only — elsewhere the
/// sink does not exist and the configuration is rejected up front.
#[cfg(target_os = "linux")]
fn open_device_writer(path: &Path, width: u32, height: u32) -> Result<Box<dyn LoopbackWriter>> {
    use std::fs::OpenOptions;

    use v4l2r::ioctl::{Capabilities, s_fmt};
    use v4l2r::{Format, PixelFormat, PlaneLayout, QueueType};

    let mut file = OpenOptions::new()
        .write(true)
        .open(path)
        .with_context(|| format!("opening {}", path.display()))?;

    // It must be an output device.
    let capability = query_capabilities(&mut file, path)?;
    if !capability
        .device_caps()
        .contains(Capabilities::VIDEO_OUTPUT)
    {
        anyhow::bail!(
            "{} does not accept video output. With exclusive_caps=1, pass the \
             v4l2loopback device *before* a producer attaches (it announces \
             output capability only until then)",
            path.display()
        );
    }

    // Negotiate YUYV at the render size.
    let frame_bytes = width as usize * height as usize * 2;
    let format = Format {
        width,
        height,
        pixelformat: PixelFormat::from_fourcc(b"YUYV"),
        plane_fmt: vec![PlaneLayout {
            bytesperline: width * 2,
            sizeimage: (frame_bytes) as u32,
        }],
    };
    let negotiated: Format = s_fmt(&mut file, (QueueType::VideoOutput, &format))
        .with_context(|| format!("negotiating the output format on {}", path.display()))?;
    if negotiated.width != width
        || negotiated.height != height
        || negotiated.pixelformat != format.pixelformat
    {
        anyhow::bail!(
            "{} refused the format: asked for YUYV {width}x{height}, got {:?} {}x{} \
             (the device was probably created with fixed dimensions — reload \
             the module or set them accordingly)",
            path.display(),
            negotiated.pixelformat.to_fourcc(),
            negotiated.width,
            negotiated.height
        );
    }

    Ok(Box::new(DeviceWriter {
        file,
        width,
        height,
        frame_bytes,
    }))
}

#[cfg(target_os = "linux")]
fn query_capabilities(file: &mut std::fs::File, path: &Path) -> Result<v4l2r::ioctl::Capability> {
    use v4l2r::ioctl::{QueryCapError, querycap};

    match querycap(file) {
        Ok(capability) => Ok(capability),
        Err(QueryCapError::IoctlError(e)) => {
            anyhow::bail!("{} is not a V4L2 device ({e})", path.display())
        }
    }
}

#[cfg(not(target_os = "linux"))]
fn open_device_writer(_path: &Path, _width: u32, _height: u32) -> Result<Box<dyn LoopbackWriter>> {
    anyhow::bail!("the v4l2loopback sink is Linux-only")
}

/// The Linux device writer: frames go out with plain `write()`, one
/// YUYV frame per call.
#[cfg(target_os = "linux")]
struct DeviceWriter {
    file: std::fs::File,
    width: u32,
    height: u32,
    frame_bytes: usize,
}

#[cfg(target_os = "linux")]
impl LoopbackWriter for DeviceWriter {
    fn write_frame(&mut self, yuyv: &[u8], width: u32, height: u32) -> Result<()> {
        use std::io::Write;
        ensure!(
            width == self.width && height == self.height,
            "frame size changed: wrote {}x{}, now {width}x{height}",
            self.width,
            self.height
        );
        ensure!(
            yuyv.len() == self.frame_bytes,
            "expected a {}-byte frame, got {}",
            self.frame_bytes,
            yuyv.len()
        );
        self.file
            .write_all(yuyv)
            .context("writing the frame (was the device removed?)")
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A writer that records everything it receives.
    struct Collector {
        frames: CollectedFrames,
    }

    /// What the collector writer received: `(yuyv, width, height)` per
    /// frame.
    type CollectedFrames = Arc<Mutex<Vec<(Vec<u8>, u32, u32)>>>;

    impl LoopbackWriter for Collector {
        fn write_frame(&mut self, yuyv: &[u8], width: u32, height: u32) -> Result<()> {
            self.frames
                .lock()
                .unwrap()
                .push((yuyv.to_vec(), width, height));
            Ok(())
        }
    }

    /// A writer that always fails.
    struct Failing;

    impl LoopbackWriter for Failing {
        fn write_frame(&mut self, _: &[u8], _: u32, _: u32) -> Result<()> {
            anyhow::bail!("writer exploded")
        }
    }

    fn image(width: u32, height: u32, rgba: &[u8]) -> RenderedImage {
        RenderedImage {
            width,
            height,
            rgba: rgba.to_vec(),
        }
    }

    #[test]
    fn yuyv_known_colours() {
        // BT.601 full range: Y' = 0.299R + 0.587G + 0.114B. Chroma
        // belongs to a pixel *pair*: computed from their average RGB.

        // A 2x1 image: red | white.
        let rgba = [255, 0, 0, 255, 255, 255, 255, 255];
        let out = rgba_to_yuyv(&rgba, 2, 1).expect("converts");
        assert_eq!(out.len(), 4);
        // Luma per pixel: red ≈ 76, white = 255.
        assert_eq!(out[0], 76);
        assert_eq!(out[2], 255);
        // Chroma of the red|white pair: averaged RGB (255, 127.5, 127.5)
        // → U ≈ 107, V ≈ 192.
        assert_eq!(out[1], 106);
        assert_eq!(out[3], 192);

        // Black is neutral: Y 0, U/V 128.
        let out = rgba_to_yuyv(&[0, 0, 0, 255, 0, 0, 0, 255], 2, 1).expect("converts");
        assert_eq!(out, vec![0, 128, 0, 128]);

        // Odd width is rejected.
        assert!(rgba_to_yuyv(&[0, 0, 0, 255], 1, 1).is_err());
        // Wrong buffer length is rejected.
        assert!(rgba_to_yuyv(&[0; 7], 2, 1).is_err());
    }

    #[test]
    fn inline_sink_pushes_converted_frames() {
        let frames = Arc::new(Mutex::new(Vec::new()));
        let mut sink = LoopbackSink::with_writer(Box::new(Collector {
            frames: frames.clone(),
        }));

        // A 2x2 red frame.
        let rgba = [255, 0, 0, 255].repeat(4);
        sink.push(&image(2, 2, &rgba)).expect("push");
        sink.push(&image(2, 2, &rgba)).expect("push");

        let frames = frames.lock().unwrap();
        assert_eq!(frames.len(), 2, "every pushed frame is written");
        for (yuyv, w, h) in frames.iter() {
            assert_eq!((*w, *h), (2, 2));
            assert_eq!(yuyv.len(), 2 * 2 * 2);
            // All red: each pixel pair is one YUYV quartet
            // [Y0, U, Y1, V] = [76, 85, 76, 255]; two rows.
            assert_eq!(yuyv, &[76, 85, 76, 255, 76, 85, 76, 255]);
        }
    }

    #[test]
    fn writer_errors_disable_the_sink() {
        let mut sink = LoopbackSink::with_writer(Box::new(Failing));
        let rgba = [0, 0, 0, 255].repeat(4);
        assert!(sink.push(&image(2, 2, &rgba)).is_err());
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn device_open_failures_are_clear() {
        // A nonexistent path.
        let err = match LoopbackSink::open("/nonexistent/video", 640, 480) {
            Ok(_) => panic!("opened a nonexistent device?"),
            Err(e) => e,
        };
        assert!(err.to_string().contains("opening"), "got: {err:#}");

        // A file that is not a V4L2 device.
        let err = match LoopbackSink::open("/dev/null", 640, 480) {
            Ok(_) => panic!("/dev/null is not a video device"),
            Err(e) => e,
        };
        assert!(
            err.to_string().contains("not a V4L2 device"),
            "got: {err:#}"
        );
    }

    #[cfg(not(target_os = "linux"))]
    #[test]
    fn device_open_fails_off_linux() {
        let err = match LoopbackSink::open("/dev/video0", 640, 480) {
            Ok(_) => panic!("opened a loopback device off Linux?"),
            Err(e) => e,
        };
        assert!(err.to_string().contains("Linux-only"));
    }
}