简介面向Qt开发者的DirectShow封装示例解决在Windows平台上通过Qt接口快速调用摄像头和音频设备的问题。包内共7个文件包含3个cpp源文件、2个h头文件、1个pro工程文件和1个ui界面文件整体仅7KB结构紧凑适合作为轻量级参考工程。已有879人浏览学习。通过该示例开发者可以了解如何枚举摄像头与音频设备列表、读取摄像头参数如曝光、白平衡以及获取支持的分辨率同时掌握将DirectShow API封装进Qt类的基本思路。对于需要集成视频聊天、在线教育或监控功能的项目它能帮助避开底层DirectShow的复杂编程模型快速搭建可运行的采集模块并为进一步调试和多设备兼容性测试提供起点。1. 为什么兜兜转转最后又打开了DirectShow这套老框架我手里一直存着一个名叫 directshow.zip 的压缩包说实话这东西跟了我快十年了。每次换电脑别的资料可以丢这个包一定会被我挪到新硬盘里。原因很简单在 Windows 平台上做视频采集、摄像头预览、画面抓取这类活儿DirectShow 虽然老但你绕不开它。哪怕现在微软主推 Media Foundation很多工业相机、USB 摄像头、视频采集卡厂商提供的 SDK 底层依然是 DirectShow 的封装或者说至少兼容 DirectShow 的调用方式。直接说结论凡是跟把外部视频信号拉进 Windows 程序相关的需求——USB 摄像头预览、采集卡画面显示、RTSP 流拉取、视频文件转码DirectShow 都是一条非常稳定、有大量现成代码可抄的路径。它从 1996 年随 DirectX 5 出现到现在快三十年网上积累的坑和解决方案非常全几乎所有你能遇到的报错都能搜到答案。相比之下Media Foundation 虽然新但官方示例少、API 变化大、各家硬件厂商对它的兼容性也参差不齐真到了现场调试阶段反而更费劲。那 directshow.zip 里装的是什么其实就是一套能直接编译运行的 DirectShow 工程代码包含设备枚举、预览、单帧抓取、录像、参数调节这些最常用的模块。这篇文章我就以这个压缩包为主线把 DirectShow 开发里最核心、最常踩坑的部分掰开揉碎讲一遍。适合谁看如果你正准备在 Windows 下做摄像头相关的小工具、设备测试程序、实验室采集软件或者你接手了一套老代码但看不懂 Filter Graph 在干嘛这篇文章能帮你省下大量翻文档和逛社区的时间。2. 打开压缩包前先把 Filter Graph 这套模型搞明白2.1 Filter、Pin、Media Sample这套东西到底是怎么工作的DirectShow 的核心思想其实非常像水管工干活你要把一桶水从水源送到水龙头中间可以接各种管子——粗管子、细管子、带过滤网的管子、带阀门的管子。在 DirectShow 里这些管子叫 Filter管子之间的接口叫 Pin流动的水叫 Media Sample。举个例子摄像头预览这个最简单的功能你的 Graph 里至少有三个 FilterSource Filter负责从摄像头读取数据、Renderer Filter负责把数据显示到窗口上以及一个隐形的 Graph Manager负责帮你把各个 Filter 按顺序连起来。数据从 Source 的 Output Pin 流出来经过连接状态的协商流入 Renderer 的 Input Pin画面就出来了。中间想加画面处理就再插一个 Transform Filter。想录制就在分支上挂一个文件写入的 Filter。这套模型的优点是把音视频处理拆成了积木。工厂要做夜视增强只需要写一个处理 Filter 替换掉原来的 Pass-through Filter其他部分不用动。缺点也明显Filter 之间的连接需要双方对媒体类型协商一致协商失败你就啥也干不了而协商失败的报错往往是含糊的 VFW_E_CANNOT_CONNECT没有具体原因得自己一边打印一边猜。我见过无数新人卡在为什么我的 Graph 连接不上这个问题上多半不是代码写错而是对媒体类型协商没有概念。实际上连接的本质是 Output Pin 和 Input Pin 互相对话Output Pin 说我能输出 YUY2、NV12、MJPG 三种格式分辨率最高 1920x1080Input Pin 说我只能接收 RGB24其他我不认识。这样的对话必然失败。所以写 DirectShow 程序第一步永远是搞清楚你的设备到底输出什么格式而不是直觉上以为摄像头一定会给你 RGB24。2.2 一个最小的 Graph 搭建代码和它背后的关键点下面这段代码是 directshow.zip 里最基础的一段作用是创建 Graph、添加两个 Filter、手动连接、然后跑起来。它绕过了很多教程里用的 Grabber 框架让你看清楚 Graph 最朴素的形态#include dshow.h #include windows.h #pragma comment(lib, strmiids.lib) #pragma comment(lib, ole32.lib) #pragma comment(lib, oleaut32.lib) IGraphBuilder* pGraph NULL; IMediaControl* pControl NULL; IMediaEvent* pEvent NULL; HRESULT BuildPreviewGraph(HWND hwnd) { HRESULT hr CoInitializeEx(NULL, COINIT_MULTITHREADED); if (FAILED(hr)) return hr; // 1. 创建 Filter Graph Manager hr CoCreateInstance(CLSID_FilterGraph, NULL, CLSCTX_INPROC_SERVER, IID_IGraphBuilder, (void**)pGraph); if (FAILED(hr)) return hr; // 2. 查询控制与事件接口 pGraph-QueryInterface(IID_IMediaControl, (void**)pControl); pGraph-QueryInterface(IID_IMediaEvent, (void**)pEvent); // 3. 创建 Source Filter这里用系统枚举器动态查找省略具体设备名 IBaseFilter* pSrcFilter NULL; hr CoCreateInstance(CLSID_VideoInputDeviceCategory, NULL, CLSCTX_INPROC_SERVER, IID_IBaseFilter, (void**)pSrcFilter); // 实际项目中这个 CLSID 应该用设备枚举器拿到而不是指定类别 // 后面第 3 节会给出完整枚举代码 // 4. 创建视频渲染 Filter IBaseFilter* pRenderer NULL; hr CoCreateInstance(CLSID_VideoRendererDefault, NULL, CLSCTX_INPROC_SERVER, IID_IBaseFilter, (void**)pRenderer); // 5. 加入 Graph pGraph-AddFilter(pSrcFilter, LSource); pGraph-AddFilter(pRenderer, LRenderer); // 6. 尝试连接注意成功的前提是两边媒体类型能协商上 hr pGraph-Connect(pSrcFilter-QueryPin(LOutput), pRenderer-QueryPin(LInput)); if (FAILED(hr)) { // 真正商业项目中这里要打印更多诊断信息 return hr; } // 7. 运行 pControl-Run(); return S_OK; }这段代码能跑通但真正的工程里我不会建议你手工 Connect。更可靠的做法是调用IGraphBuilder::RenderPin让系统自动寻找合适的中间 Filter 完成整条链路。例如摄像头输出 YUY2 而渲染器要 RGB24中间需要一个 Color Converter Filter你手动连就永远连不通系统自动连却能完美工作。很多初学者总觉得自动连接不够可控但其实恰恰相反DirectShow 的 Filter Mapper 用了多年迭代的匹配逻辑比你手动猜要聪明得多。3. 设备枚举和配置directshow.zip 里最值得复用的代码片段3.1 枚举摄像头这段代码值得放在所有工程开头现在打开 directshow.zip你会发现里面最实用的一小段代码就是系统设备枚举。在 Windows 开发中枚举摄像头这事儿从来没简单过——你不能保证用户只有一个摄像头也不能保证插上去的设备名是中文还是英文更不能保证设备拔掉重插后同一个 USB 口是否还能用同一个 CLSID。标准的做法是用ICreateDevEnum遍历CLSID_VideoInputDeviceCategory类别下的所有设备取出每个设备的 Moniker再通过 Moniker 拿到它的友好名称和绑定后的 IBaseFilter。代码大概是#include dshow.h HRESULT EnumVideoDevices(std::vectorstd::wstring names, std::vectorCLSID clsidList) { HRESULT hr S_OK; ICreateDevEnum* pDevEnum NULL; IEnumMoniker* pEnumMoniker NULL; hr CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER, IID_ICreateDevEnum, (void**)pDevEnum); if (FAILED(hr)) return hr; hr pDevEnum-CreateClassEnumerator(CLSID_VideoInputDeviceCategory, pEnumMoniker, 0); if (hr S_FALSE) // 注意没有设备时返回 S_FALSE不是失败 { pDevEnum-Release(); return E_FAIL; } IMoniker* pMoniker NULL; while (pEnumMoniker-Next(1, pMoniker, NULL) S_OK) { IPropertyBag* pBag NULL; pMoniker-BindToStorage(0, 0, IID_IPropertyBag, (void**)pBag); if (pBag) { VARIANT varName; VariantInit(varName); VARIANT varPath; VariantInit(varPath); pBag-Read(LFriendlyName, varName, 0); pBag-Read(LDevicePath, varPath, 0); names.push_back(varName.bstrVal ? varName.bstrVal : L未知设备); // 用 Moniker 绑定出实际 Filter IBaseFilter* pFilter NULL; pMoniker-BindToObject(0, 0, IID_IBaseFilter, (void**)pFilter); if (pFilter) { CLSID clsid; pFilter-GetClassID(clsid); clsidList.push_back(clsid); pFilter-Release(); } VariantClear(varName); VariantClear(varPath); pBag-Release(); } pMoniker-Release(); } pEnumMoniker-Release(); pDevEnum-Release(); return S_OK; }这里有两个特别容易被忽略的细节。第一CreateClassEnumerator在没有设备时返回的是S_FALSE而不是S_OK很多人的代码只判断FAILED(hr)结果就是没设备时程序直接继续往下走然后莫名崩溃。第二DevicePath这个属性一定不要只用来做名字展示它才是区分同一型号多个摄像头的关键键两个一模一样品牌的 USB 摄像头友好名称都是USB Camera但 DevicePath 里的 USB 端口序号不同通过它才能稳定选择你想要的那一路。3.2 设置分辨率和帧率用 IAMStreamConfig 才能说到点子上摄像头枚举完接着就要设置采集参数。很多新人对这个环节也误解很大——以为 DirectShow 设置分辨率是调用什么 SetResolution 方法其实通篇没有这个方法。你要做的是拿到 Source Filter 的 Output Pin 上的IAMStreamConfig接口然后遍历支持的媒体类型选一个匹配的调用SetFormat。IAMStreamConfig* pConfig NULL; // pPin 是从 pSrcFilter 上拿到的 Output Pin hr pPin-QueryInterface(IID_IAMStreamConfig, (void**)pConfig); if (SUCCEEDED(hr)) { AM_MEDIA_TYPE* pmt NULL; if (SUCCEEDED(pConfig-GetFormat(pmt))) { VIDEOINFOHEADER* pVih (VIDEOINFOHEADER*)pmt-pbFormat; pVih-bmiHeader.biWidth 1280; pVih-bmiHeader.biHeight 720; pVih-AvgTimePerFrame 333333; // 1/30 秒, 单位 100ns pConfig-SetFormat(pmt); DeleteMediaType(pmt); } }SetFormat 的改动不保证一定生效这个坑后面详说。但有一个原则修改参数前先把GetFormat拿到当前的 AM_MEDIA_TYPE在这个基础上改字段而不是自己从头构造一个空结构体。为什么因为 AM_MEDIA_TYPE 里有一些不显眼但关键的字段比如subtype、bFixedSizeSamples、lSampleSize这些信息是设备驱动期望的一致状态你凭空造一个容易造成字段不匹配驱动直接拒绝。关于直接用户最关心的分辨率我的建议是不要盲目追求最大。很多工业相机的最大分辨率下帧率会掉一半而且色彩压缩算法MJPG vs YUY2在分辨率增大后性能差距非常明显。实际项目中我一般会枚举出设备支持的所有格式打印到日志里再从中选一个平衡点。枚举代码同样走 IAMStreamConfig调用GetNumberOfCapabilitiesGetStreamCaps每个显卡的驱动驱动支持格式不同这步省不了。4. 实测中踩过的几个硬坑directshow.zip 里没写但我必须告诉你4.1 颜色空间协商YUY2、MJPG、NV12 怎么选很多人不理解为什么摄像头明明支持 1080p代码设置后画面却卡成幻灯片。我在真实项目中排查过好几次最终都是颜色空间的锅。USB 摄像头在 1080p 下的输出格式通常有两种YUY2无压缩和 MJPGMotion JPEG 压缩。YUY2 每像素占 2 字节1920x108030fps 的理论数据量约 1920*1080*2*30 ≈ 124MB/sUSB 2.0 的带宽是 480Mbps约 60MB/s根本跑不动摄像头就会自动降帧率到 15fps 甚至 10fpsMJPG 经过压缩后通常只有几 MB/s轻松跑满 30fps。但 MJPG 的问题在于Surface 数据到应用层之前是 JPEG 压缩态你要做像素级的图像处理就得先解压成原始帧。DirectShow 的 MJPEG Decompressor Filter 可以自动完成这个解压但会占用不少 CPU。所以正确思路是如果只是预览显示选 MJPG 完全没问题如果要做 OpenCV 实时处理或算法分析优先选 YUY2且分辨率不要盲目上 4K除非你确认设备走的是 USB 3.0 通道。实际开发中我通常这样决策先枚举出所有格式列个表看一眼。如果设备在 1080p 下只给 MJPG 和 NV12而我的算法需要 YUY2我会在采集端选 NV12避免 JPEG 解压开销再用 CPU/GPU 的转换库转成 YUY2。NV12 是视频压缩里最常见的中间格式转起来比 MJPG 快得多。4.2 线程回调与 UI 假死的爱恨情仇如果你用 Sample Grabber 做逐帧回调一定要记住回调函数跑在 DirectShow 的工作线程上不是 UI 线程。这几乎是所有 DirectShow 程序都死过的坑。我在 directshow.zip 里写了一个典型的错误示范然后注释掉了在回调里直接给窗口发消息或者在回调里操作 MFC/ QT 控件。这种写法你测试时不一定崩但用户一拖动窗口、一点关闭按钮程序大概率就假死或者闪退。原因简单回调线程持续占用 CPU 处理视频帧UI 线程如果等回调线程完成某些操作就会形成互相等待的死锁。正确做法是回调函数里只做轻量数据拷贝把帧指针和大小塞进一个自写循环队列然后通过 PostMessage 通知 UI 线程去取数据。UI 线程在空闲时才从队列中取出最新帧并绘制。注意是取最新帧不是逐帧绘制——视频帧率 30fps 而 UI 刷新率不一定跟得上队列里堆几帧后一定要丢老帧否则内存和界面都会越来越卡。4.3 设备拔出再插入Graph 不会自动恢复实际交付软件时最令人崩溃的就是用户拔了一下摄像头程序就再也找不到设备了。DirectShow 的 Graph 在你拔掉设备后并不会自动销毁或重建它只会报一个 EC_DEVICE_LOST 事件而且部分老驱动连这个事件都不发。我在 directshow.zip 里放的方案是定时用ICreateDevEnum重新枚举设备列表对比 CLSID 和 DevicePath 是否有变化。一旦发现设备消失就停止 Graph、释放所有 Filter再次发现设备插入时重新构建整个 Graph。这套逻辑写起来虽然啰嗦却是工业设备软件必不可少的部分。关于这个坑还有一个扩展场景设备被占用。有时候你不是主动插拔而是另一个进程打开了同一个摄像头那你的 Graph 在运行时就会收到 EC_DEVICE_LOST 或者等待超时。处理方式是一样的——彻底重建同时弹窗提示用户关闭其他占用摄像头的程序。4.4 64 位下的注册表重定向和 DLL 匹配如果你的软件是 64 位编译但摄像头厂商提供的驱动 DLL 是 32 位专用这问题比你想的更常见。很多老型号的采集卡和工业相机厂商驱动只给了 32 位版本DirectShow 的 Filter 注册信息在 64 位系统上会被重定向到 WOW6432Node 下64 位程序根本枚举不到。排查这类问题时最容易陷入的误区是反复检查你的枚举代码。其实方向应该反过来——先看这个设备驱动是否真正支持 64 位。用regedit查看HKEY_CLASSES_ROOT\WOW6432Node\CLSID是否能找到该设备的 CLSID如果没有基本可以断定你的 64 位程序死活枚举不到设备就算强行用 CoCreateInstance 也只会返回 REGDB_E_CLASSNOTREG。对策有两条路要么给项目启用 32 位编译与驱动环境保持一致要么中间加一层独立 32 位采集服务进程通过进程间通信把视频帧传给 64 位主程序。后者架构复杂但某些军方和工控项目里跑了一两年也没出过问题。4.5 帧率设置不生效为什么摄像头就是不听话前面提到我用AvgTimePerFrame设置帧率但很多摄像头根本不理会这个值。这背后的原因是USB 摄像头通常是通过 USB Video Class (UVC) 协议工作帧率的协商更多依赖驱动和固件SetFormat里的 AvgTimePerFrame 只是请求驱动可以选择接受或忽略。我之前做过一个双路摄像头同步采集项目两个摄像头在 Windows 下用 DirectShow 各跑各的无论我怎么设 AvgTimePerFrame两路画面在 Windows 时间戳上永远差 40~80ms后来不用了因为 UVC 驱动自己控制帧率。要真正实现帧率控制通常得用厂商提供的私有 SDK或者通过IAMVideoProcAmp/IAMCameraControl接口里的属性进行调节但这两个接口本身也不保证每个属性可用。所以我的经验是先运行一个枚举工具把设备配合的帧率范围打印出来再对照你的需求选一个最接近的。如果设备本身只有 30fps 一种选择你硬设 15fps 多半没用得在应用层做抽帧。5. 从 directshow.zip 继续扩展能做出哪些实用项目5.1 录像功能用 File Writer Filter 还是 Sample Grabber 自己写录像在 DirectShow 里有两套实现路线。第一套是用系统自带的 ASF Writer / AVI Mux File Writer Filter把编码好的数据直接写进容器。优点是代码量极小缺点是你对编码格式几乎无法控制——系统选什么编码器、怎么设置码率都得另外通过 IConfigAsfWriter 等接口设置出错时排查难度大。第二套是接 Sample Grabber在每一帧回调里用第三方编码库比如 FFmpeg把原始帧编码后写入磁盘。这套方案灵活度高得多也更容易控制。我在 directshow.zip 里用的是后者原因是很多视频处理项目后续要接入算法检测或叠加信息逐帧处理后顺手写文件更顺手。代价是回调线程需要处理编码耗时如果编码帧率跟不上采集帧率队列会堆积最终延迟变大。解决办法是让回调线程只入队另开一个专门编码写盘的线程去消费队列把采集和编码彻底解耦。5.2 给画面叠加文字VMR9 是最稳的老路子DirectShow 里叠加 OSD 信息常见的两种做法是用 VMR9 的 Alpha Blending 接口或者用 VMR9 的 Mixer 模式把多路视频混合。我在实践中强烈推荐 VMR9因为它的视频混合机制设计得非常好可以在不额外增加 Filter 的情况下通过IVMRMixerBitmap9接口把一张带透明通道的位图叠加到视频流上。但请记住一个前提VMR9 在机器没有硬件加速时会退回软件混合1080p 下 CPU 占用会飙升。如果你是在老式工控机上做视频叠加最好把视频降低到 720p否则界面流畅度会很难看。AVI 文件叠加画面也一样等分复用。5.3 从 VMR9 到 EVR 的迁移和兼容微软自己对 VMR9 的态度是弃用但可用Windows 7 之后推荐的是 EVREnhanced Video Renderer。EVR 的接口模型比 VMR9 复杂一些但性能和兼容性确实更好尤其是在多显示器和硬件加速的现代显卡上。如果你还在维护老项目建议先保留 VMR9 作为默认渲染器然后做一个配置项允许切换 EVR。代码层面VMR9 和 EVR 都实现了 IBaseFilter因此 Graph 搭建方式一致你需要额外做的就是处理 EVR 的媒体类型协商差异以及 EVR 上获取图像统计信息的方式不一样。这么做的价值是给未来的迁移铺路不至于某一台新笔记本的显卡不支持 VMR9 的某个加速特性时你的软件突然黑屏。6. 最后分享几个长期积累的小技巧directshow.zip 这套东西用久了有几个小经验我觉得比任何 API 文档都值钱。第一永远在 Graph 运行前保存一份完整的IGraphBuilder的日志。DirectShow 有一个IGraphBuilder::SetLogFile或者通过IObjectWithSite设置日志文件的接口当你的 Filter 连接失败时日志文件里往往带着比 HRESULT 更具体的诊断信息。我在现场排查问题时几乎全靠这份日志而不是靠断点逐步跑。第二做一个简单的视频源测试工具把它打进 directshow.zip 里。这个工具不需要界面多华丽只需要能枚举出设备、列出所有支持格式、显示当前格式、允许手动切换分辨率并预览。任何一个摄像头拿到手先用这个工具测一遍我心里就有底了。很多同学拿到新设备直接写代码结果调试半天发现是设备驱动的问题而不是你代码的问题这很冤枉。第三在 Filter 连接之前尽量用IFilterMapper2查找可用的中间 Filter。真实项目中你几乎永远需要在 Source 和 Renderer 之间加编码器或转换器与其自己在代码里硬编码 CLSID不如让系统帮你找。配合日志机制这样你就能看清整个管线里到底有哪些 Filter 参与定位问题就不靠猜了。DirectShow 确实老学习曲线也比较陡但它的稳定性、资料厚度和硬件兼容性是许多后来者比不上的。希望这篇文章能让你在拿到 directshow.zip 这类代码包时少走几步弯路也欢迎用过这套框架的同行在评论区聊聊你踩过的那些更偏门的坑。本文还有配套的精品资源点击获取