Cap 开源项目中的 DirectShow 相机采集封装cap-camera-directshow 的架构、API 与实战解析【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap导读Cap 是一个开源 Loom 替代品用于录制并分享高质量的屏幕与摄像头画面。在 Windows 平台上为了让老式摄像头与旧驱动依然可用Cap 在crates/camera-directshow中提供了对 Windows DirectShow API 的 Rust 安全封装cap-camera-directshow它通过 COM 滤镜图Filter Graph完成设备枚举、格式协商与同步帧回调采集并在上层与 Media Foundation 采集路径互为补充。阅读本文后你将掌握该 crate 的核心 API 设计、start_capturing的完整调用链、自定义 Sink 滤镜的工作原理以及如何在 Cap 的camera-windows层中将其作为媒体采集回退方案使用。一、为什么 Cap 需要 DirectShow定位与背景DirectShow 是 Windows 上历史悠久的媒体框架其基于 COM 的滤镜图架构至今仍是许多老式摄像头设备尤其是采集卡、虚拟摄像头以及缺少 Media Foundation 驱动的硬件唯一可靠的采集途径。Cap 在 crates/camera-directshow/README.md 中明确描述了该 crate 的目标为“旧式摄像头采集”提供符合人体工学的 Rust 封装Ergonomic Rust wrapper在 COM 接口之上提供安全抽象同时保持与不支持 Media Foundation 的旧设备/旧驱动的兼容性在消费 DirectShow 的方式上对标 ChromiumAims to mirror how Chromium consumes DirectShow即采用“枚举 → 协商格式 → 建立滤镜图 → 通过自定义 Sink 滤镜回调取帧”的经典路线。从 crates/camera-windows/src/lib.rs 的集成代码可以看到它的实际定位get_devices()会同时枚举 Media Foundation 与 DirectShow 设备并以name_and_model()为键将同一台设备的 MF/DS 两个实例“配对”把 DS 设备挂到 MF 设备的dshow_fallback字段上——当 MF 设备激活失败或报不出格式时采集流程会回退到 DirectShow这正是该 crate 在项目中的核心价值场景详见第七节。二、架构总览把 COM 滤镜图模型桥接到 Rust 所有权体系cap-camera-directshow的架构核心见 crates/camera-directshow/src/lib.rs由四层构成COM 初始化层通过initialize_directshow()完成CoInitialize为后续 COM 调用建立公寓环境设备枚举层VideoInputDeviceIterator借助系统设备枚举器ICreateDevEnumCLSID_VideoInputDeviceCategory与 COM Moniker 遍历视频采集设备格式协商层通过采集引脚上的IAMStreamConfig枚举AM_MEDIA_TYPE能力分辨率、像素格式、帧率同步采集层自定义SinkFilter/SinkInputPin作为滤镜图的接收端在IMemInputPin::Receive中以回调方式同步交付每一帧IMediaSample。这种“滤镜图 自定义 Sink 回调”的组合配合 RAII 管理 COM 对象生命周期让调用方可以在完全不接触裸 COM 的情况下完成一次实时视频采集。延迟绑定Deferred Binding枚举绝不打开设备源码中有一处值得注意的设计见 src/lib.rs 中VideoInputDevice的定义与注释#[derive(Clone)] pub struct VideoInputDevice { moniker: IMoniker, prop_bag: IPropertyBag, bound: OnceLockBoundFilter, }VideoInputDevice内部用OnceLockBoundFilter缓存“已绑定的滤镜”。注释明确说明绑定采集滤镜会通过 KS 驱动打开设备这会消耗一个线程和数十个内核句柄且这些句柄在释放时不会立即回收对应仓库记录 CapSoftware/Cap#2132。因此纯枚举获取name()/id()/model_id()永远不会触发绑定只读取IPropertyBag中的属性只有真正需要media_types()或start_capturing()时才通过BindToObject绑定滤镜绑定结果以OnceLock缓存多次调用不重复打开设备。这保证了上层轮询设备列表时不会产生资源泄漏。三、核心 API 详解3.1 设备管理API作用initialize_directshow()初始化 DirectShow COM 子系统内部调用CoInitializeVideoInputDeviceIterator::new()通过系统设备枚举器枚举可用摄像头VideoInputDevice::name()读取设备显示名称优先读Description属性回退到FriendlyNameVideoInputDevice::id()读取DevicePath属性回退到设备名VideoInputDevice::model_id()从 DevicePath 中解析vid_xxxx/pid_xxxx生成vid:pid形式的型号标识VideoInputDevice::media_types()返回支持格式的迭代器会触发延迟绑定设备枚举在源码中的实现见 src/lib.rs 的VideoInputDeviceIterator::newlet create_device_enum: ICreateDevEnum CoCreateInstance( CLSID_SystemDeviceEnum, None::windows_core::IUnknown, CLSCTX_INPROC_SERVER, )?; let mut enum_moniker None; create_device_enum.CreateClassEnumerator( CLSID_VideoInputDeviceCategory, mut enum_moniker, 0, )?;其中有一个关键细节CreateClassEnumerator在无设备时可能返回S_FALSE被当作成功处理所以枚举器可能为None迭代器会自然结束而非报错——这是处理“无摄像头”场景的健壮做法。model_id()的解析逻辑见 src/lib.rs 的get_device_model_id在设备路径中定位vid_与pid_标记取其后 4 位十六进制拼接为vendor:product这是上层判断设备类别如是否是虚拟摄像头的重要依据。3.2 格式处理AMMediaType对AM_MEDIA_TYPE的安全包装。new()通过copy_media_type用CoTaskMemAlloc深拷贝pbFormatDrop时用CoTaskMemFree释放杜绝内存泄漏支持Clone与Deref可无缝传入采集 API。AM_MEDIA_TYPEExt::subtype_str()把格式 GUID 映射为可读字符串内置支持以下格式见 src/lib.rs 的subtype_str实现GUID 常量返回字符串MEDIASUBTYPE_I420i420MEDIASUBTYPE_IYUViyuvMEDIASUBTYPE_RGB24rgb24MEDIASUBTYPE_RGB32rgb32MEDIASUBTYPE_YUY2yuy2MEDIASUBTYPE_MJPGmjpgMEDIASUBTYPE_UYVYuyvyMEDIASUBTYPE_ARGB32argb32MEDIASUBTYPE_NV12nv12MEDIASUBTYPE_YV12yv12AM_MEDIA_TYPEVideoExt::video_info()将pbFormat强转为KS_VIDEOINFOHEADER从而读取bmiHeader.biWidth、biHeight、AvgTimePerFrame等视频尺寸与帧率信息。示例代码正是用它获取分辨率与默认帧率。3.3 采集管线API作用VideoInputDevice::start_capturing(format, callback)以指定格式开始同步采集返回CaptureHandleCaptureHandle::stop_capturing()停止采集会话并断开滤镜图SinkCallback帧处理回调接收CallbackData回调数据结构见 src/lib.rspub struct CallbackDataa { pub sample: a IMediaSample, // 当前帧样本 pub media_type: a AMMediaType, // 当前媒体类型 pub timestamp: Duration, // 采样时间戳微秒 pub perf_counter: i64, // QueryPerformanceCounter 高精度计数器 } pub type SinkCallback Boxdyn FnMut(CallbackData);perf_counter由QueryPerformanceCounter在每次Receive时采样可供上层做精确的时间同步与性能统计。3.4 滤镜图扩展 traitIBaseFilterExt::get_pin()按“方向 引脚类别 主类型”三条件查找引脚。direction为PINDIR_OUTPUT/PINDIR_INPUTcategory或major_type传GUID::zeroed()表示不约束该项。内部用EnumPins遍历并用matches_category/matches_major_type过滤。IPinExt::matches_category()通过IKsPropertySet::Get读取AMPROPSETID_Pin/AMPROPERTY_PIN_CATEGORY判断引脚类别如采集引脚PIN_CATEGORY_CAPTURE。IPinExt::matches_major_type()通过ConnectionMediaType读取已连接媒体类型的主类型。IAMStreamConfigExt::media_types()先调GetNumberOfCapabilities获取能力数量再逐个GetStreamCaps(i, ...)拉取AM_MEDIA_TYPE与VIDEO_STREAM_CONFIG_CAPS返回迭代器可配合IAMVideoControlExt::time_per_frame_list()读取每种分辨率下的帧率列表。四、采集流水线深潜start_capturing 的完整调用链start_capturing(format, callback)见 src/lib.rs内部依次完成以下步骤绑定设备通过bound()获取缓存的滤镜与采集引脚失败映射为StartCapturingError::BindDevice设置格式在IAMStreamConfig上调用SetFormat(format)把AMMediaType写入设备创建 Sink 滤镜SinkFilter::new(format.clone(), callback)并取出唯一的输入引脚input_sink_pin取不到则返回NoInputPin实例化滤镜图CoCreateInstance(CLSID_FilterGraph)与CLSID_CaptureGraphBuilder2并将IGraphBuilder强转为IMediaControl构图SetFiltergraph绑定构图器AddFilter依次加入设备滤镜与 Sink 滤镜FindInterface(PIN_CATEGORY_CAPTURE, MEDIATYPE_Video, ...)重新取得IAMStreamConfig连接graph_builder.Connect(bound.output_pin, input_sink_pin)把设备采集引脚接到 Sink 输入引脚运行media_control.Run()启动滤镜图返回持有media_control、graph_builder及两端引脚的CaptureHandle。整个流程中任何一步失败都会映射为对应的StartCapturingError变体见第五节保证错误可定位、可传播。Sink 滤镜如何工作SinkFilter实现了IBaseFilter、IMediaFilter与IPersist其状态机State_Stopped/State_Paused/State_Running与JoinFilterGraph钩子记录宿主图都通过RefCell安全维护。真正的帧处理发生在SinkInputPin::ReceiveIMemInputPin_Impl记录QueryPerformanceCounter高精度时间若样本携带新的媒体类型GetMediaType成功则更新current_media_type校验数据长度大于 0否则返回S_FALSE跳过校验GetPointer可取到缓冲区用GetTime读取起止时间换算为微秒级timestampstart_time / 10组装CallbackData并调用回调。SinkInputPin同时实现了IPin与IMemInputPin覆盖Connect、ReceiveConnection、Disconnect、ConnectionMediaType、QueryAccept、EnumMediaTypes返回期望格式以及分配器相关接口能够完整参与滤镜图的连接协商。停止采集对标 ChromiumCaptureHandle::stop_capturing()见 src/lib.rs先IMediaControl::Stop()再主动Disconnect设备输出引脚与 Sink 输入引脚。源码注释明确指出该流程对标 Chromium 的VideoCaptureDeviceWin::StopAndDeallocate确保滤镜图状态机回到停止态、资源可回收。五、错误处理模型StartCapturingError是一个基于thiserror的枚举见 src/lib.rs完整覆盖采集启动各阶段变体含义BindDevice(windows_core::Error)绑定设备滤镜失败延迟绑定阶段NoInputPinSink 滤镜输入引脚创建失败CreateGraph(windows_core::Error)滤镜图 / 采集图构建器实例化失败ConfigureGraph(windows_core::Error)滤镜连接与配置失败构图、AddFilter、Connect 等Run(windows_core::Error)IMediaControl::Run执行失败Other(windows_core::Error)其他通用 DirectShow COM 错误如SetFormat失败由于 crate 的Drop实现AMMediaType自动释放pbFormat与CaptureHandle持有的 COM 引用都会在离开作用域时自动清理错误传播过程中不会出现 COM 资源泄漏。这种“RAII 强类型错误”的组合既满足了实时视频采集所需的回调架构又保持了 Rust 的内存安全承诺。六、开箱即用的命令行示例仓库在 crates/camera-directshow/examples/cli.rs 提供了一个完整的交互式示例演示了从枚举到采样的全流程初始化 COMCoInitialize(None)并初始化tracing_subscriber用VideoInputDeviceIterator::new()收集所有设备通过inquire::Select交互选择取设备输出引脚并cast::IAMVideoControl()为后续帧率查询做准备用media_types()枚举格式过滤出MEDIATYPE_VideoFORMAT_VideoInfo的格式读取biWidth/biHeight帧率获取优先走IAMVideoControl::time_per_frame_list对指定分辨率的GetFrameRateList将time_per_frame换算为10_000_000.0 / t100ns 单位换算为 fps并保留两位小数若列表为空则回退用KS_VIDEOINFOHEADER::AvgTimePerFrame计算交互选择格式后调用start_capturing回调中打印每帧的data_length与timestamp持续 10 秒。该示例展示的核心模式——先用IAMVideoControl精确获取帧率列表、失败再回退到AvgTimePerFrame——可以直接复用到真实产品中。需要注意的是示例与整个 crate 一样仅支持 Windows非 Windows 平台会直接panic!。七、与 camera-windows 的集成作为 Media Foundation 的回退路径cap-camera-directshow在上层被 crates/camera-windows/src/lib.rs 消费形成“MF 优先、DS 兜底”的双通道策略枚举get_devices()同时调用initialize_directshow()与initialize_mediafoundation()分别枚举 DS 设备与 MF 设备对每个 DS 设备若能在 MF 列表中按name_and_model()名称 model_id找到尚未挂接回退的“孪生”MF 设备则把 DS 实例挂到其dshow_fallback否则 DS 设备单独入列src/lib.rs 的get_devices实现格式ds_formats(device)遍历media_types()通过VideoFormat::new_ds转成统一的VideoFormatMF 设备的格式列表会在激活失败时回退到dshow_fallback的格式采集start_capturing按设备类型分发——MediaFoundation MF format走 MF 采集DirectShow或MediaFoundation { dshow_fallback: Some(..) } DirectShow format走 DS 采集。DS 回调中通过KS_VIDEOINFOHEADER读取biWidth/biHeight并结合directshow_frame_is_bottom_up判断是否需要翻转对 RGB24/RGB32/BGR24/ARGB/RGB565 这类传统自下而上bottom-up的像素格式biHeight 0即表示图像方向需要处理src/lib.rs 的directshow_frame_is_bottom_up。这种设计正是 README 中“兼容不支持 Media Foundation 的旧设备”这一目标的落地实现一台同时被 MF 与 DS 注册的设备MF 路径不可用时无需用户干预即可平滑切换。八、构建与使用注意事项从 crates/camera-directshow/Cargo.toml 可以看出该 crate 的使用前提平台限制源码开头为#![cfg(windows)]windows与windows-core依赖位于[target.cfg(windows).dependencies]因此只能在 Windows 目标上编译使用依赖特性启用windowscrate 的Win32_System_Com、Win32_Media_DirectShow、Win32_Media_MediaFoundation、Win32_System_Com_StructuredStorage、Win32_System_Ole、Win32_System_Variant、Win32_System_Performance、Win32_Media_KernelStreaming特性Win32_Media_KernelStreaming提供KS_VIDEOINFOHEADERWin32_System_Performance提供QueryPerformanceCounter工作区集成依赖workspace-hack、tracing、thiserror遵循工作区统一的 lints 与 profile 配置示例的inquire与tracing-subscriber仅作为 dev-dependenciescrate 元信息包名为cap-camera-directshow版本0.1.0edition 2024MIT 协议它是 Cap 工作区见根目录 Cargo.toml 的 workspace members中crates/*的一员。在仓库中运行示例的方式Windows 环境cargo run -p cap-camera-directshow --example cli结语cap-camera-directshow用不到 1200 行的 Rust 代码把 DirectShow 的 COM 滤镜图体系封装成了一套类型安全、资源安全且贴近产品需求的 API延迟绑定避免枚举泄漏、AMMediaType以 RAII 管理原生内存、StartCapturingError精确刻画启动失败点、自定义SinkFilter支撑同步回调取帧。在 Cap 的 Windows 相机链路中它与 Media Foundation 路径互为镜像共同保证了从现代网络摄像头到老式采集卡的广泛兼容性。对于希望在 Rust 中消费 DirectShow 的开发者这是一个值得直接参考的完整范本。【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cap 开源项目中的 DirectShow 相机采集封装cap-camera-directshow 的架构、API 与实战解析【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap导读Cap 是一个开源 Loom 替代品用于录制并分享高质量的屏幕与摄像头画面。在 Windows 平台上为了让老式摄像头与旧驱动依然可用Cap 在crates/camera-directshow中提供了对 Windows DirectShow API 的 Rust 安全封装cap-camera-directshow它通过 COM 滤镜图Filter Graph完成设备枚举、格式协商与同步帧回调采集并在上层与 Media Foundation 采集路径互为补充。阅读本文后你将掌握该 crate 的核心 API 设计、start_capturing的完整调用链、自定义 Sink 滤镜的工作原理以及如何在 Cap 的camera-windows层中将其作为媒体采集回退方案使用。一、为什么 Cap 需要 DirectShow定位与背景DirectShow 是 Windows 上历史悠久的媒体框架其基于 COM 的滤镜图架构至今仍是许多老式摄像头设备尤其是采集卡、虚拟摄像头以及缺少 Media Foundation 驱动的硬件唯一可靠的采集途径。Cap 在 crates/camera-directshow/README.md 中明确描述了该 crate 的目标为“旧式摄像头采集”提供符合人体工学的 Rust 封装Ergonomic Rust wrapper在 COM 接口之上提供安全抽象同时保持与不支持 Media Foundation 的旧设备/旧驱动的兼容性在消费 DirectShow 的方式上对标 ChromiumAims to mirror how Chromium consumes DirectShow即采用“枚举 → 协商格式 → 建立滤镜图 → 通过自定义 Sink 滤镜回调取帧”的经典路线。从 crates/camera-windows/src/lib.rs 的集成代码可以看到它的实际定位get_devices()会同时枚举 Media Foundation 与 DirectShow 设备并以name_and_model()为键将同一台设备的 MF/DS 两个实例“配对”把 DS 设备挂到 MF 设备的dshow_fallback字段上——当 MF 设备激活失败或报不出格式时采集流程会回退到 DirectShow这正是该 crate 在项目中的核心价值场景详见第七节。二、架构总览把 COM 滤镜图模型桥接到 Rust 所有权体系cap-camera-directshow的架构核心见 crates/camera-directshow/src/lib.rs由四层构成COM 初始化层通过initialize_directshow()完成CoInitialize为后续 COM 调用建立公寓环境设备枚举层VideoInputDeviceIterator借助系统设备枚举器ICreateDevEnumCLSID_VideoInputDeviceCategory与 COM Moniker 遍历视频采集设备格式协商层通过采集引脚上的IAMStreamConfig枚举AM_MEDIA_TYPE能力分辨率、像素格式、帧率同步采集层自定义SinkFilter/SinkInputPin作为滤镜图的接收端在IMemInputPin::Receive中以回调方式同步交付每一帧IMediaSample。这种“滤镜图 自定义 Sink 回调”的组合配合 RAII 管理 COM 对象生命周期让调用方可以在完全不接触裸 COM 的情况下完成一次实时视频采集。延迟绑定Deferred Binding枚举绝不打开设备源码中有一处值得注意的设计见 src/lib.rs 中VideoInputDevice的定义与注释#[derive(Clone)] pub struct VideoInputDevice { moniker: IMoniker, prop_bag: IPropertyBag, bound: OnceLockBoundFilter, }VideoInputDevice内部用OnceLockBoundFilter缓存“已绑定的滤镜”。注释明确说明绑定采集滤镜会通过 KS 驱动打开设备这会消耗一个线程和数十个内核句柄且这些句柄在释放时不会立即回收对应仓库记录 CapSoftware/Cap#2132。因此纯枚举获取name()/id()/model_id()永远不会触发绑定只读取IPropertyBag中的属性只有真正需要media_types()或start_capturing()时才通过BindToObject绑定滤镜绑定结果以OnceLock缓存多次调用不重复打开设备。这保证了上层轮询设备列表时不会产生资源泄漏。三、核心 API 详解3.1 设备管理API作用initialize_directshow()初始化 DirectShow COM 子系统内部调用CoInitializeVideoInputDeviceIterator::new()通过系统设备枚举器枚举可用摄像头VideoInputDevice::name()读取设备显示名称优先读Description属性回退到FriendlyNameVideoInputDevice::id()读取DevicePath属性回退到设备名VideoInputDevice::model_id()从 DevicePath 中解析vid_xxxx/pid_xxxx生成vid:pid形式的型号标识VideoInputDevice::media_types()返回支持格式的迭代器会触发延迟绑定设备枚举在源码中的实现见 src/lib.rs 的VideoInputDeviceIterator::newlet create_device_enum: ICreateDevEnum CoCreateInstance( CLSID_SystemDeviceEnum, None::windows_core::IUnknown, CLSCTX_INPROC_SERVER, )?; let mut enum_moniker None; create_device_enum.CreateClassEnumerator( CLSID_VideoInputDeviceCategory, mut enum_moniker, 0, )?;其中有一个关键细节CreateClassEnumerator在无设备时可能返回S_FALSE被当作成功处理所以枚举器可能为None迭代器会自然结束而非报错——这是处理“无摄像头”场景的健壮做法。model_id()的解析逻辑见 src/lib.rs 的get_device_model_id在设备路径中定位vid_与pid_标记取其后 4 位十六进制拼接为vendor:product这是上层判断设备类别如是否是虚拟摄像头的重要依据。3.2 格式处理AMMediaType对AM_MEDIA_TYPE的安全包装。new()通过copy_media_type用CoTaskMemAlloc深拷贝pbFormatDrop时用CoTaskMemFree释放杜绝内存泄漏支持Clone与Deref可无缝传入采集 API。AM_MEDIA_TYPEExt::subtype_str()把格式 GUID 映射为可读字符串内置支持以下格式见 src/lib.rs 的subtype_str实现GUID 常量返回字符串MEDIASUBTYPE_I420i420MEDIASUBTYPE_IYUViyuvMEDIASUBTYPE_RGB24rgb24MEDIASUBTYPE_RGB32rgb32MEDIASUBTYPE_YUY2yuy2MEDIASUBTYPE_MJPGmjpgMEDIASUBTYPE_UYVYuyvyMEDIASUBTYPE_ARGB32argb32MEDIASUBTYPE_NV12nv12MEDIASUBTYPE_YV12yv12AM_MEDIA_TYPEVideoExt::video_info()将pbFormat强转为KS_VIDEOINFOHEADER从而读取bmiHeader.biWidth、biHeight、AvgTimePerFrame等视频尺寸与帧率信息。示例代码正是用它获取分辨率与默认帧率。3.3 采集管线API作用VideoInputDevice::start_capturing(format, callback)以指定格式开始同步采集返回CaptureHandleCaptureHandle::stop_capturing()停止采集会话并断开滤镜图SinkCallback帧处理回调接收CallbackData回调数据结构见 src/lib.rspub struct CallbackDataa { pub sample: a IMediaSample, // 当前帧样本 pub media_type: a AMMediaType, // 当前媒体类型 pub timestamp: Duration, // 采样时间戳微秒 pub perf_counter: i64, // QueryPerformanceCounter 高精度计数器 } pub type SinkCallback Boxdyn FnMut(CallbackData);perf_counter由QueryPerformanceCounter在每次Receive时采样可供上层做精确的时间同步与性能统计。3.4 滤镜图扩展 traitIBaseFilterExt::get_pin()按“方向 引脚类别 主类型”三条件查找引脚。direction为PINDIR_OUTPUT/PINDIR_INPUTcategory或major_type传GUID::zeroed()表示不约束该项。内部用EnumPins遍历并用matches_category/matches_major_type过滤。IPinExt::matches_category()通过IKsPropertySet::Get读取AMPROPSETID_Pin/AMPROPERTY_PIN_CATEGORY判断引脚类别如采集引脚PIN_CATEGORY_CAPTURE。IPinExt::matches_major_type()通过ConnectionMediaType读取已连接媒体类型的主类型。IAMStreamConfigExt::media_types()先调GetNumberOfCapabilities获取能力数量再逐个GetStreamCaps(i, ...)拉取AM_MEDIA_TYPE与VIDEO_STREAM_CONFIG_CAPS返回迭代器可配合IAMVideoControlExt::time_per_frame_list()读取每种分辨率下的帧率列表。四、采集流水线深潜start_capturing 的完整调用链start_capturing(format, callback)见 src/lib.rs内部依次完成以下步骤绑定设备通过bound()获取缓存的滤镜与采集引脚失败映射为StartCapturingError::BindDevice设置格式在IAMStreamConfig上调用SetFormat(format)把AMMediaType写入设备创建 Sink 滤镜SinkFilter::new(format.clone(), callback)并取出唯一的输入引脚input_sink_pin取不到则返回NoInputPin实例化滤镜图CoCreateInstance(CLSID_FilterGraph)与CLSID_CaptureGraphBuilder2并将IGraphBuilder强转为IMediaControl构图SetFiltergraph绑定构图器AddFilter依次加入设备滤镜与 Sink 滤镜FindInterface(PIN_CATEGORY_CAPTURE, MEDIATYPE_Video, ...)重新取得IAMStreamConfig连接graph_builder.Connect(bound.output_pin, input_sink_pin)把设备采集引脚接到 Sink 输入引脚运行media_control.Run()启动滤镜图返回持有media_control、graph_builder及两端引脚的CaptureHandle。整个流程中任何一步失败都会映射为对应的StartCapturingError变体见第五节保证错误可定位、可传播。Sink 滤镜如何工作SinkFilter实现了IBaseFilter、IMediaFilter与IPersist其状态机State_Stopped/State_Paused/State_Running与JoinFilterGraph钩子记录宿主图都通过RefCell安全维护。真正的帧处理发生在SinkInputPin::ReceiveIMemInputPin_Impl记录QueryPerformanceCounter高精度时间若样本携带新的媒体类型GetMediaType成功则更新current_media_type校验数据长度大于 0否则返回S_FALSE跳过校验GetPointer可取到缓冲区用GetTime读取起止时间换算为微秒级timestampstart_time / 10组装CallbackData并调用回调。SinkInputPin同时实现了IPin与IMemInputPin覆盖Connect、ReceiveConnection、Disconnect、ConnectionMediaType、QueryAccept、EnumMediaTypes返回期望格式以及分配器相关接口能够完整参与滤镜图的连接协商。停止采集对标 ChromiumCaptureHandle::stop_capturing()见 src/lib.rs先IMediaControl::Stop()再主动Disconnect设备输出引脚与 Sink 输入引脚。源码注释明确指出该流程对标 Chromium 的VideoCaptureDeviceWin::StopAndDeallocate确保滤镜图状态机回到停止态、资源可回收。五、错误处理模型StartCapturingError是一个基于thiserror的枚举见 src/lib.rs完整覆盖采集启动各阶段变体含义BindDevice(windows_core::Error)绑定设备滤镜失败延迟绑定阶段NoInputPinSink 滤镜输入引脚创建失败CreateGraph(windows_core::Error)滤镜图 / 采集图构建器实例化失败ConfigureGraph(windows_core::Error)滤镜连接与配置失败构图、AddFilter、Connect 等Run(windows_core::Error)IMediaControl::Run执行失败Other(windows_core::Error)其他通用 DirectShow COM 错误如SetFormat失败由于 crate 的Drop实现AMMediaType自动释放pbFormat与CaptureHandle持有的 COM 引用都会在离开作用域时自动清理错误传播过程中不会出现 COM 资源泄漏。这种“RAII 强类型错误”的组合既满足了实时视频采集所需的回调架构又保持了 Rust 的内存安全承诺。六、开箱即用的命令行示例仓库在 crates/camera-directshow/examples/cli.rs 提供了一个完整的交互式示例演示了从枚举到采样的全流程初始化 COMCoInitialize(None)并初始化tracing_subscriber用VideoInputDeviceIterator::new()收集所有设备通过inquire::Select交互选择取设备输出引脚并cast::IAMVideoControl()为后续帧率查询做准备用media_types()枚举格式过滤出MEDIATYPE_VideoFORMAT_VideoInfo的格式读取biWidth/biHeight帧率获取优先走IAMVideoControl::time_per_frame_list对指定分辨率的GetFrameRateList将time_per_frame换算为10_000_000.0 / t100ns 单位换算为 fps并保留两位小数若列表为空则回退用KS_VIDEOINFOHEADER::AvgTimePerFrame计算交互选择格式后调用start_capturing回调中打印每帧的data_length与timestamp持续 10 秒。该示例展示的核心模式——先用IAMVideoControl精确获取帧率列表、失败再回退到AvgTimePerFrame——可以直接复用到真实产品中。需要注意的是示例与整个 crate 一样仅支持 Windows非 Windows 平台会直接panic!。七、与 camera-windows 的集成作为 Media Foundation 的回退路径cap-camera-directshow在上层被 crates/camera-windows/src/lib.rs 消费形成“MF 优先、DS 兜底”的双通道策略枚举get_devices()同时调用initialize_directshow()与initialize_mediafoundation()分别枚举 DS 设备与 MF 设备对每个 DS 设备若能在 MF 列表中按name_and_model()名称 model_id找到尚未挂接回退的“孪生”MF 设备则把 DS 实例挂到其dshow_fallback否则 DS 设备单独入列src/lib.rs 的get_devices实现格式ds_formats(device)遍历media_types()通过VideoFormat::new_ds转成统一的VideoFormatMF 设备的格式列表会在激活失败时回退到dshow_fallback的格式采集start_capturing按设备类型分发——MediaFoundation MF format走 MF 采集DirectShow或MediaFoundation { dshow_fallback: Some(..) } DirectShow format走 DS 采集。DS 回调中通过KS_VIDEOINFOHEADER读取biWidth/biHeight并结合directshow_frame_is_bottom_up判断是否需要翻转对 RGB24/RGB32/BGR24/ARGB/RGB565 这类传统自下而上bottom-up的像素格式biHeight 0即表示图像方向需要处理src/lib.rs 的directshow_frame_is_bottom_up。这种设计正是 README 中“兼容不支持 Media Foundation 的旧设备”这一目标的落地实现一台同时被 MF 与 DS 注册的设备MF 路径不可用时无需用户干预即可平滑切换。八、构建与使用注意事项从 crates/camera-directshow/Cargo.toml 可以看出该 crate 的使用前提平台限制源码开头为#![cfg(windows)]windows与windows-core依赖位于[target.cfg(windows).dependencies]因此只能在 Windows 目标上编译使用依赖特性启用windowscrate 的Win32_System_Com、Win32_Media_DirectShow、Win32_Media_MediaFoundation、Win32_System_Com_StructuredStorage、Win32_System_Ole、Win32_System_Variant、Win32_System_Performance、Win32_Media_KernelStreaming特性Win32_Media_KernelStreaming提供KS_VIDEOINFOHEADERWin32_System_Performance提供QueryPerformanceCounter工作区集成依赖workspace-hack、tracing、thiserror遵循工作区统一的 lints 与 profile 配置示例的inquire与tracing-subscriber仅作为 dev-dependenciescrate 元信息包名为cap-camera-directshow版本0.1.0edition 2024MIT 协议它是 Cap 工作区见根目录 Cargo.toml 的 workspace members中crates/*的一员。在仓库中运行示例的方式Windows 环境cargo run -p cap-camera-directshow --example cli结语cap-camera-directshow用不到 1200 行的 Rust 代码把 DirectShow 的 COM 滤镜图体系封装成了一套类型安全、资源安全且贴近产品需求的 API延迟绑定避免枚举泄漏、AMMediaType以 RAII 管理原生内存、StartCapturingError精确刻画启动失败点、自定义SinkFilter支撑同步回调取帧。在 Cap 的 Windows 相机链路中它与 Media Foundation 路径互为镜像共同保证了从现代网络摄像头到老式采集卡的广泛兼容性。对于希望在 Rust 中消费 DirectShow 的开发者这是一个值得直接参考的完整范本。【免费下载链接】CapOpen source Loom alternative. Beautiful, shareable screen recordings.项目地址: https://gitcode.com/GitHub_Trending/cap1/Cap创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
