Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

14.7 KB
Raw Blame
// SPDX-License-Identifier: GPL-3.0-or-later
//! `nectarlink_vcam`: Windows 11 Media Foundation virtual camera media source
//! COM DLL and shared-memory frame transport (`docs/protocol/webcam.md`).

#![allow(linker_messages)]

#[cfg(windows)]
use std::sync::atomic::Ordering;

#[cfg(windows)]
use windows::{
    Win32::{
        Foundation::{CLASS_E_CLASSNOTAVAILABLE, E_INVALIDARG, E_POINTER, S_FALSE, S_OK},
        Media::MediaFoundation::{MF_VERSION, MFSTARTUP_NOSOCKET, MFStartup},
        System::Com::IClassFactory,
    },
    core::{GUID, HRESULT, IUnknown, Interface},
};

#[cfg(windows)]
pub mod gpu;
pub mod shm;
#[cfg(windows)]
pub mod source;

pub use shm::{
    DEFAULT_MAPPING_NAME, LOCAL_MAPPING_NAME, MAX_FRAME_BYTES, MAX_HEIGHT, MAX_WIDTH, SharedFrameMapping,
    bgrx_to_nv12, fit_bgrx_aspect, render_placeholder_bgrx,
};
#[cfg(windows)]
pub use source::{SAMPLE_DURATION_100NS, VcamClassFactory, VcamMediaSource, VcamMediaStream};

/// CLSID of the NectarLink Virtual Camera Media Foundation media source:
/// `{8E6C3B74-5D4A-4B9E-9A12-7C8F1E2D3A40}`.
#[cfg(windows)]
pub const CLSID_NECTARLINK_VCAM: GUID = GUID::from_u128(0x8e6c3b74_5d4a_4b9e_9a12_7c8f1e2d3a40);

/// Standard COM DLL entry point returning an `IClassFactory` for
/// [`CLSID_NECTARLINK_VCAM`].
///
/// # Safety
/// `rclsid`, `riid`, and `ppv` must be valid pointers as specified by COM.
#[cfg(windows)]
#[unsafe(no_mangle)]
#[allow(unsafe_code)]
pub unsafe extern "system" fn DllGetClassObject(
    rclsid: *const GUID,
    riid: *const GUID,
    ppv: *mut *mut std::ffi::c_void,
) -> HRESULT {
    if ppv.is_null() {
        return E_POINTER;
    }
    unsafe { *ppv = std::ptr::null_mut() };
    if rclsid.is_null() || riid.is_null() {
        return E_INVALIDARG;
    }
    let clsid = unsafe { *rclsid };
    if clsid != CLSID_NECTARLINK_VCAM {
        return CLASS_E_CLASSNOTAVAILABLE;
    }
    let _ = unsafe { MFStartup(MF_VERSION, MFSTARTUP_NOSOCKET) };
    let factory: IClassFactory = VcamClassFactory::new().into();
    let unk: IUnknown = match factory.cast() {
        Ok(u) => u,
        Err(e) => return e.code(),
    };
    unsafe { unk.query(riid, ppv) }
}

/// Standard COM DLL unload check.
#[cfg(windows)]
#[unsafe(no_mangle)]
#[allow(unsafe_code)]
pub extern "system" fn DllCanUnloadNow() -> HRESULT {
    if source::ACTIVE_OBJECTS.load(Ordering::Relaxed) == 0 { S_OK } else { S_FALSE }
}

#[cfg(test)]
#[allow(unsafe_code)]
mod tests {
    use super::*;
    #[cfg(windows)]
    use windows::Win32::{
        Media::{
            KernelStreaming::PINNAME_VIDEO_CAPTURE,
            MediaFoundation::{
                IMF2DBuffer, IMFMediaSource, IMFMediaStream, IMFMediaStream2, IMFSample,
                IMFSampleAllocatorControl, IMFVideoSampleAllocator, MEMediaSample, MENewStream,
                MESourceStarted, MESourceStopped, MEStreamStarted, MEStreamStopped, MEUpdatedStream,
                MF_DEVICESTREAM_ATTRIBUTE_FRAMESOURCE_TYPES, MF_DEVICESTREAM_FRAMESERVER_SHARED,
                MF_DEVICESTREAM_STREAM_CATEGORY, MF_DEVICESTREAM_STREAM_ID, MF_E_INVALID_STATE_TRANSITION,
                MF_EVENT_FLAG_NO_WAIT, MF_MT_FRAME_SIZE, MF_MT_SUBTYPE, MF_STREAM_STATE_RUNNING,
                MF_STREAM_STATE_STOPPED, MFCreateVideoSampleAllocatorEx, MFFrameSourceTypes_Color,
                MFVideoFormat_NV12, MFVideoFormat_RGB32,
            },
        },
        System::Com::StructuredStorage::PROPVARIANT,
    };

    #[cfg(windows)]
    fn sample_bytes(sample: &IMFSample) -> Vec<u8> {
        unsafe {
            let buffer: IMF2DBuffer = sample.GetBufferByIndex(0).unwrap().cast().unwrap();
            let mut bytes = vec![0; buffer.GetContiguousLength().unwrap() as usize];
            buffer.ContiguousCopyTo(&mut bytes).unwrap();
            bytes
        }
    }

    #[cfg(windows)]
    #[test]
    fn dll_get_class_object_activates_media_source_in_process() {
        unsafe {
            let mut raw = std::ptr::null_mut();
            let hr = DllGetClassObject(&CLSID_NECTARLINK_VCAM, &IClassFactory::IID, &mut raw);
            assert_eq!(hr, S_OK);
            assert!(!raw.is_null());
            let factory: IClassFactory = IClassFactory::from_raw(raw);
            let activate: windows::Win32::Media::MediaFoundation::IMFActivate =
                factory.CreateInstance(None).unwrap();
            let source: windows::Win32::Media::MediaFoundation::IMFMediaSourceEx =
                activate.ActivateObject().unwrap();
            let attrs = source.GetSourceAttributes().unwrap();
            assert_eq!(
                attrs.GetUINT32(&MF_DEVICESTREAM_ATTRIBUTE_FRAMESOURCE_TYPES).unwrap(),
                MFFrameSourceTypes_Color.0 as u32
            );
            source.Shutdown().unwrap();
        }
    }

    #[cfg(windows)]
    #[test]
    fn media_source_delivers_placeholder_and_live_shared_memory_samples() {
        unsafe {
            let _ = MFStartup(MF_VERSION, MFSTARTUP_NOSOCKET);
            let map_name = format!("Local\\NectarlinkVcamSrcTest_{}", std::process::id());
            let writer = SharedFrameMapping::open_or_create(&map_name).unwrap();
            writer.set_idle("Pixel 8");

            let source_ex = VcamMediaSource::new_with_mapping(&map_name).unwrap();
            let source: IMFMediaSource = source_ex.cast().unwrap();

            // Verify source & stream attributes required by Windows Camera Frame Server.
            let src_attrs = source_ex.GetSourceAttributes().unwrap();
            assert_eq!(
                src_attrs.GetUINT32(&MF_DEVICESTREAM_ATTRIBUTE_FRAMESOURCE_TYPES).unwrap(),
                MFFrameSourceTypes_Color.0 as u32
            );
            let stm_attrs = source_ex.GetStreamAttributes(0).unwrap();
            assert_eq!(stm_attrs.GetGUID(&MF_DEVICESTREAM_STREAM_CATEGORY).unwrap(), PINNAME_VIDEO_CAPTURE);
            assert_eq!(stm_attrs.GetUINT32(&MF_DEVICESTREAM_STREAM_ID).unwrap(), 0);
            assert_eq!(stm_attrs.GetUINT32(&MF_DEVICESTREAM_FRAMESERVER_SHARED).unwrap(), 1);

            // Presentation descriptor & media types (RGB32/NV12 @ 720p & 1080p).
            let pd = source.CreatePresentationDescriptor().unwrap();
            assert_eq!(pd.GetStreamDescriptorCount().unwrap(), 1);
            let mut selected = windows::core::BOOL(0);
            let mut sd_opt = None;
            pd.GetStreamDescriptorByIndex(0, &mut selected, &mut sd_opt).unwrap();
            assert!(selected.as_bool());
            let sd = sd_opt.unwrap();
            let handler = sd.GetMediaTypeHandler().unwrap();
            assert_eq!(handler.GetMediaTypeCount().unwrap(), 4);

            // Frame Server supplies the allocator before starting the source.
            // Exercise real 2D buffers rather than only flat test buffers.
            handler.SetCurrentMediaType(&handler.GetMediaTypeByIndex(1).unwrap()).unwrap();
            let mut raw_allocator = std::ptr::null_mut();
            MFCreateVideoSampleAllocatorEx(&IMFVideoSampleAllocator::IID, &mut raw_allocator).unwrap();
            let allocator = IMFVideoSampleAllocator::from_raw(raw_allocator);
            let allocator_control: IMFSampleAllocatorControl = source.cast().unwrap();
            allocator_control.SetDefaultAllocator(0, &allocator).unwrap();

            // Start the media source.
            let start_pos = PROPVARIANT::default();
            source.Start(&pd, &GUID::zeroed(), &start_pos).unwrap();

            // Pop MENewStream and MESourceStarted from the source event queue.
            let ev_new_stream = source.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap();
            assert_eq!(ev_new_stream.GetType().unwrap(), MENewStream.0 as u32);
            let val = ev_new_stream.GetValue().unwrap();
            let stream_unk: IUnknown = val.Anonymous.Anonymous.Anonymous.punkVal.as_ref().unwrap().clone();
            let stream: IMFMediaStream = stream_unk.cast().unwrap();
            let stream2: IMFMediaStream2 = stream.cast().unwrap();
            assert_eq!(stream2.GetStreamState().unwrap(), MF_STREAM_STATE_RUNNING);

            let ev_src_started = source.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap();
            assert_eq!(ev_src_started.GetType().unwrap(), MESourceStarted.0 as u32);

            let ev_stm_started = stream.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap();
            assert_eq!(ev_stm_started.GetType().unwrap(), MEStreamStarted.0 as u32);

            // 1. RequestSample while inactive -> placeholder 1280x720 RGB32 sample.
            stream.RequestSample(None).unwrap();
            let ev_sample0 = stream.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap();
            assert_eq!(ev_sample0.GetType().unwrap(), MEMediaSample.0 as u32);
            let s0_val = ev_sample0.GetValue().unwrap();
            let sample0: IMFSample =
                s0_val.Anonymous.Anonymous.Anonymous.punkVal.as_ref().unwrap().cast().unwrap();
            let sample_time0 = sample0.GetSampleTime().unwrap();
            assert!(sample_time0 > 0);
            assert_eq!(sample0.GetSampleDuration().unwrap(), SAMPLE_DURATION_100NS);
            let bytes0 = sample_bytes(&sample0);
            assert_eq!(bytes0.len(), 1280 * 720 * 4);
            // Placeholder contains amber/white text pixels over the dark background.
            assert!(bytes0.as_chunks::<4>().0.iter().any(|px| px[2] > 200));

            // 2. Write a live 1280x720 BGRX frame to shared memory and request a sample.
            let mut live_frame = vec![0u8; 1280 * 720 * 4];
            for px in live_frame.as_chunks_mut::<4>().0 {
                px[0] = 0x22;
                px[1] = 0x88;
                px[2] = 0xEE;
                px[3] = 0xFF;
            }
            writer.write_frame("Pixel 8", 1280, 720, 12_345, &live_frame, false);

            stream.RequestSample(None).unwrap();
            let ev_sample1 = stream.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap();
            assert_eq!(ev_sample1.GetType().unwrap(), MEMediaSample.0 as u32);
            let s1_val = ev_sample1.GetValue().unwrap();
            let sample1: IMFSample =
                s1_val.Anonymous.Anonymous.Anonymous.punkVal.as_ref().unwrap().cast().unwrap();
            let sample_time1 = sample1.GetSampleTime().unwrap();
            assert!(sample_time1 >= sample_time0 + SAMPLE_DURATION_100NS);
            let bytes1 = sample_bytes(&sample1);
            assert_eq!(bytes1.len(), 1280 * 720 * 4);
            assert_eq!(&bytes1[..4], &[0x22, 0x88, 0xEE, 0xFF]);
            assert_eq!(&bytes1[bytes1.len() - 4..], &[0x22, 0x88, 0xEE, 0xFF]);

            // 3. Switch stream media type to NV12 @ 1280x720 and request a sample.
            let mt_nv12 = handler.GetMediaTypeByIndex(0).unwrap();
            assert_eq!(mt_nv12.GetGUID(&MF_MT_SUBTYPE).unwrap(), MFVideoFormat_NV12);
            handler.SetCurrentMediaType(&mt_nv12).unwrap();
            allocator.UninitializeSampleAllocator().unwrap();
            allocator.InitializeSampleAllocator(10, &mt_nv12).unwrap();
            stream.RequestSample(None).unwrap();
            let ev_sample2 = stream.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap();
            let s2_val = ev_sample2.GetValue().unwrap();
            let sample2: IMFSample =
                s2_val.Anonymous.Anonymous.Anonymous.punkVal.as_ref().unwrap().cast().unwrap();
            let sample_time2 = sample2.GetSampleTime().unwrap();
            assert!(sample_time2 >= sample_time1 + SAMPLE_DURATION_100NS);
            assert_eq!(sample_bytes(&sample2).len(), 1280 * 720 * 3 / 2);

            // 4. Switch stream media type to RGB32 @ 1920x1080 and request a sample.
            let mt_1080 = handler.GetMediaTypeByIndex(3).unwrap();
            assert_eq!(mt_1080.GetGUID(&MF_MT_SUBTYPE).unwrap(), MFVideoFormat_RGB32);
            assert_eq!(mt_1080.GetUINT64(&MF_MT_FRAME_SIZE).unwrap(), (1920u64 << 32) | 1080u64);
            handler.SetCurrentMediaType(&mt_1080).unwrap();
            allocator.UninitializeSampleAllocator().unwrap();
            allocator.InitializeSampleAllocator(10, &mt_1080).unwrap();
            stream.RequestSample(None).unwrap();
            let ev_sample3 = stream.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap();
            let s3_val = ev_sample3.GetValue().unwrap();
            let sample3: IMFSample =
                s3_val.Anonymous.Anonymous.Anonymous.punkVal.as_ref().unwrap().cast().unwrap();
            let sample_time3 = sample3.GetSampleTime().unwrap();
            assert!(sample_time3 >= sample_time2 + SAMPLE_DURATION_100NS);
            assert_eq!(sample_bytes(&sample3).len(), 1920 * 1080 * 4);

            // A live source rejects pause; restart, stop and shutdown still work.
            assert_eq!(source.Pause().unwrap_err().code(), MF_E_INVALID_STATE_TRANSITION);
            assert_eq!(stream2.GetStreamState().unwrap(), MF_STREAM_STATE_RUNNING);

            allocator.UninitializeSampleAllocator().unwrap();
            source.Start(&pd, &GUID::zeroed(), &start_pos).unwrap();
            assert_eq!(
                source.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap().GetType().unwrap(),
                MEUpdatedStream.0 as u32
            );
            assert_eq!(
                source.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap().GetType().unwrap(),
                MESourceStarted.0 as u32
            );
            assert_eq!(
                stream.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap().GetType().unwrap(),
                MEStreamStarted.0 as u32
            );

            source.Stop().unwrap();
            assert_eq!(stream2.GetStreamState().unwrap(), MF_STREAM_STATE_STOPPED);
            assert_eq!(
                source.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap().GetType().unwrap(),
                MESourceStopped.0 as u32
            );
            assert_eq!(
                stream.GetEvent(MF_EVENT_FLAG_NO_WAIT).unwrap().GetType().unwrap(),
                MEStreamStopped.0 as u32
            );

            source.Shutdown().unwrap();
        }
    }

    #[test]
    fn shared_memory_mirror_and_aspect_fit_round_trip() {
        let map_name = format!("Local\\NectarlinkVcamShmTest_{}", std::process::id());
        let writer = SharedFrameMapping::open_or_create(&map_name).unwrap();
        let reader = SharedFrameMapping::open_or_create(&map_name).unwrap();

        // 4x2 frame where left half is blue and right half is red.
        let mut src = vec![0u8; 4 * 2 * 4];
        for y in 0..2 {
            for x in 0..4 {
                let off = (y * 4 + x) * 4;
                if x < 2 {
                    src[off..off + 4].copy_from_slice(&[255, 0, 0, 255]);
                } else {
                    src[off..off + 4].copy_from_slice(&[0, 0, 255, 255]);
                }
            }
        }
        writer.write_frame("Pixel 8", 4, 2, 999, &src, true);

        let mut dst = vec![0u8; 4 * 2 * 4];
        let ts = reader.read_bgrx(4, 2, &mut dst);
        assert_eq!(ts, (true, 999));
        // Because mirror=true, left half is now red and right half is blue.
        assert_eq!(&dst[0..4], &[0, 0, 255, 255]);
        assert_eq!(&dst[8..12], &[255, 0, 0, 255]);
    }
}