Win10 下 DirectShow 开发环境搭建与 Filter 注册排错

简介面向Windows 10平台多媒体开发者的DirectShow学习与开发包适合需要处理视频音频流、构建播放器或捕获程序的初中级开发者重点解决Win10下框架配置与COM接口调用等问题。压缩包为rar格式体积约1.29MB文件总数与类型明细上游暂未标注内容围绕DirectShow开发所需的头文件、库文件及配套工具资源展开。已有919人学习说明其在同类资料中具备一定参考度。资料覆盖DirectShow过滤器图与源、转换、渲染过滤器的基础知识并延伸到Win10安装配置、CoCreateInstance调用、典型播放、捕获、流媒体、编辑场景以及自定义过滤器、Filter Graph Manager管理、GraphEdit调试和HRESULT错误处理等要点。读者可据此梳理DirectShow开发脉络对照关键接口与调试思路减少在Win10环境搭建和排错上的摸索成本。1. DirectShow 在 Windows 10 上的安装现场为什么老工程一挪机器就编译不过前几天把一份跑了很多年的采集 demo 挪到一台全新的 Windows 10 机器上工程一个字符没改编译直接红了一片dxtrans.h找不到、strmbasd.lib链接不上好不容易编译过了运行时CoCreateInstance又甩回来一个0x80040154。DirectShow 在 Win10 上就是典型的「系统里有、开发环境里没有」——运行时组件跟着系统走头文件、BaseClasses 源码、注册工具却要自己一件件补齐。这篇按我刚在这台机器上重装一遍的顺序写装什么版本、目录怎么摆、库怎么链、filter 怎么注册、装坏了怎么退回去适合第一次在 Win10 上搭 DirectShow 采集或播放工程的人照着走。2. 装前清点Windows 10 SDK 与 DirectShow BaseClasses 的版本搭配2.1 三个组件的版本关系先把这张表对一遍DirectShow 本身不需要单独「安装」它是 Windows 10 自带的一套 COM 组件quartz.dll就躺在System32和SysWOW64里。真正要装的是开发期需要的那几样东西SDK 提供的头文件和导入库、BaseClasses 提供的基类源码、以及一个能编 C 的编译器。这三者的版本关系如果不先对齐后面每一步都会出问题。组件常见选择在 DirectShow 工程里的作用是否必装Visual Studio2019v142或 2022v143编译 .exe / .ax 工程管运行库必装Windows 10 SDK10.0.19041、10.0.22621 这类仍在维护的版本提供 dshow.h、strmif.h、uuids.h、strmiids.lib、quartz.lib必装DirectShow BaseClasses资源包里的 BaseClasses 源码目录提供 CBaseFilter、CBasePin 等基类编出 strmbase.lib写自定义 filter 时必装GraphStudioNext / GraphEdit任意可用版本手动连 graph验证 pin 能不能连上强烈建议依赖查看工具任意查 .ax 的动态库依赖、查注册表可选SDK 版本这块不用太纠结DirectShow 的头文件好多年没大改过10.0.19041 和 10.0.22621 编出来的结果没有区别。真正会出问题的是两件事一是 BaseClasses 的源码版本和你手上的 SDK 是否匹配太老的 BaseClasses 里会引用已经被移除的头文件二是 MSVC 运行库BaseClasses 用/MD编、你的工程用/MT链链接期就会报 LNK2038 运行库不匹配这个坑后面还会单独说。还有一点容易被忽略BaseClasses 不在 Windows SDK 的安装选项里。装 SDK 的时候勾不勾「Windows 桌面开发」都不会把streams.h和CBaseFilter送到你机器上它属于旧版示例代码得从资源包或者示例代码目录里单独拿。这也是很多人以为「SDK 装完就能写 filter」结果一头雾水的原因。2.2 目录规划头文件、库、源码分三处放我见过太多工程把dshow.h、streams.h直接拷进项目目录短时间能编译换台机器或者升级 SDK 就全乱。常见的做法是分三层放置工程里只写相对路径引用路径放什么谁维护D:\DS\sdk_include\从 BaseClasses 里挑出来的头文件副本streams.h、wxdebug.h 等一次性拷贝不随工程变D:\DS\baseclasses\完整的 BaseClasses 源码用于编 lib保持原样不改动D:\DS\build\lib\x64\、...\Win32\编出来的 strmbase.lib / strmbasd.lib编译产物可删可重建D:\DS\filters\自己写的 .ax 输出目录编译产物把产物目录和源码目录分开好处是清工程的时候直接删build不用去源码里翻哪些是编出来的、哪些是原本就有的。资源包拿到手之后我会先把 BaseClasses 整个目录复制到D:\DS\baseclasses保持只读任何修改都通过工程属性做不动源码——这一条是血泪经验改了源码下次换版本就再也对不上了。2.3 Visual Studio 安装时到底要勾哪几项打开 Visual Studio Installer「修改」当前实例在「单个组件」里确认这三项被勾上MSVC v142 或 v143 生成工具x86 与 x64 都要、Windows 10 SDK版本号记下来后面配属性要用、C 核心功能。三项缺任何一项后面msbuild都会在第一步就失败。装完之后验证一下别急着开工程。开一个普通命令提示符敲where msbuild能返回路径就说明工具链在 PATH 里再敲dir C:\Program Files (x86)\Windows Kits\10\Include能列出刚才那个 SDK 版本号目录说明 SDK 头文件到位了。这两条命令我每次装完都会跑一遍比起在 IDE 里报错之后再倒推五分钟能省后面两小时。3. 编译落地从 BaseClasses 到 strmbase.lib 的四步走3.1 第一步先编 BaseClasses不要先编自己的工程顺序反了会浪费很多时间。自己的工程一编译就报无法打开包括文件: streams.h这时候你会以为是包含路径写错了改半天路径其实根源是strmbase.lib根本还不存在。正确顺序是先让 BaseClasses 编过拿到 lib再回头配主工程。BaseClasses 目录里通常带一个baseclasses.vcxproj也有叫baseclasses.sln的直接命令行编最省事:: 进到 BaseClasses 源码目录再执行路径按自己机器改 cd /d D:\DS\baseclasses :: x64 Release产出 strmbase.lib msbuild baseclasses.vcxproj /p:ConfigurationRelease /p:Platformx64 /m /v:m :: x64 Debug产出 strmbasd.lib32 位工程把 Platform 换成 Win32 msbuild baseclasses.vcxproj /p:ConfigurationDebug /p:Platformx64 /m /v:m/p:Configuration和/p:Platform这两个参数决定了产物落到哪一层目录Release 出strmbase.lib、Debug 出strmbasd.lib名字带 d 的那个是 Debug 版两者不能混用——Debug 工程链了 Release 的 lib链接期不一定报错运行时才在堆上出问题这种属于最难查的一类。/m是并行编译/v:m把输出降到简洁级别报错信息依然完整适合在命令行里看。编完到x64\Release或Win32\Release下面确认一下 lib 大小正常是几百 KB 级别。如果产物是 0 字节或者压根没生成多半是 SDK 版本不匹配导致某些源文件被跳过回去看编译输出里的第一条 warning。3.2 第二步工程属性里的三处路径怎么填新建一个空的 C 控制台工程然后按顺序改三处不要用「编辑包含目录」那种一长串手填的方式容易漏分号。包含目录里加 BaseClasses 源码路径和刚才那个sdk_include库目录里加 lib 产物路径。真正的关键在「附加依赖项」这一项直接决定链接期会不会报一堆LNK2019。我一般直接改.vcxproj比在对话框里点要清楚ItemDefinitionGroup Condition$(Configuration)|$(Platform)Release|x64 Link !-- 顺序不重要但 strmbase 必须和当前配置的 Debug/Release 对上 -- AdditionalDependenciesstrmbase.lib;quartz.lib;strmiids.lib;ole32.lib;oleaut32.lib;uuid.lib;winmm.lib;%(AdditionalDependencies)/AdditionalDependencies AdditionalLibraryDirectoriesD:\DS\build\lib\x64\Release;%(AdditionalLibraryDirectories)/AdditionalLibraryDirectories /Link /ItemDefinitionGroup逐个说清楚这几个库是干什么的缺哪个会报什么错。strmbase.lib提供 CBaseFilter、CBasePin 这些基类实现写自定义 filter 缺它必报基类未定义quartz.lib提供 FilterGraph、CaptureGraphBuilder2 的 CLSID 和 IID缺它会报CLSID_FilterGraph无法解析strmiids.lib是各种接口 IID 的定义IID_IBaseFilter这类符号从这里来ole32.lib和oleaut32.lib是 COM 基础CoInitializeEx、CoCreateInstance全靠它们uuid.lib兜底一部分 GUID 定义winmm.lib在用到多媒体定时器的时候需要。一个常见的误用是把strmbasd.lib写死在工程里然后切 Release 配置编译链接器会提示找不到文件。正确做法是利用 VS 的配置宏让 Debug 链带 d 的那个或者干脆两套配置各写一份ItemDefinitionGroup。3.3 第三步最小骨架先把 graph 建起来再谈业务业务代码之前先写一个只做三件事的程序初始化 COM、创建 FilterGraph、创建 CaptureGraphBuilder2。这个骨架能跑通说明头文件、库、运行库三样全对了剩下的采集逻辑才有意义。#include windows.h #include dshow.h #include cstdio #pragma comment(lib, strmiids.lib) #pragma comment(lib, quartz.lib) int main() { // 采集和播放类程序统一用 STA跨线程回调里图状态才不会错乱 HRESULT hr CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED); if (hr RPC_E_CHANGED_MODE) { // 当前线程已被别处用 MTA 初始化过直接用不要重复初始化 printf(COM 已以 MTA 初始化沿用现有套间\n); } IGraphBuilder* pGraph nullptr; hr CoCreateInstance(CLSID_FilterGraph, nullptr, CLSCTX_INPROC_SERVER, IID_IGraphBuilder, (void**)pGraph); if (FAILED(hr)) { // 0x80040154 类未注册多半是位数不匹配或系统组件被裁掉 printf(FilterGraph 创建失败: 0x%08X\n, hr); return -1; } ICaptureGraphBuilder2* pBuild nullptr; hr CoCreateInstance(CLSID_CaptureGraphBuilder2, nullptr, CLSCTX_INPROC_SERVER, IID_ICaptureGraphBuilder2, (void**)pBuild); if (FAILED(hr)) { printf(CaptureGraphBuilder2 创建失败: 0x%08X\n, hr); pGraph-Release(); return -1; } pBuild-SetFiltergraph(pGraph); // 把 builder 绑到这张图上后面建链全靠它 printf(graph 创建成功\n); pBuild-Release(); pGraph-Release(); CoUninitialize(); return 0; }三个细节值得单独说。CoInitializeEx的第二个参数用COINIT_APARTMENTTHREADEDSTA因为 DirectShow 的回调和窗口消息绑得比较紧MTA 下有些 filter 会出现状态不同步如果返回RPC_E_CHANGED_MODE说明这个线程之前被别的库初始化成 MTA 了这时不要CoUninitialize也不要再初始化一次。CoCreateInstance的返回值一定要打出来0x80040154是类未注册、0x80070005是权限不足、0x8007007E是找不到模块三个错误码指向完全不同的方向。最后Release的顺序和创建顺序相反CoUninitialize必须在所有 COM 对象释放之后调这条违反了在调试版里会直接断言。4. 运行环境配置filter 注册、位数对齐与 qedit.h 兼容写法4.1 位数对齐32 位 filter 只能用 32 位 regsvr32 注册这一条是 Win10 上最容易出现的问题因为目录命名是反的。64 位系统里C:\Windows\System32放的是 64 位程序C:\Windows\SysWOW64放的是 32 位程序。你的 .ax 是 32 位就必须用SysWOW64下面那个regsvr32.exe去注册用错了注册会「成功」但程序里CoCreateInstance永远返回0x80040154。:: 注册 32 位自定义 filter必须以管理员身份运行且用 SysWOW64 下的 regsvr32 C:\Windows\SysWOW64\regsvr32.exe /s D:\DS\filters\Win32\Release\MyGrabber.ax :: 注册 64 位 filter用 System32 下的注意不要写成 SysWOW64 C:\Windows\System32\regsvr32.exe /s D:\DS\filters\x64\Release\MyGrabber.ax :: 卸载用 /u改代码重新编译前先卸一遍避免旧版本残留在注册表里 C:\Windows\SysWOW64\regsvr32.exe /u D:\DS\filters\Win32\Release\MyGrabber.ax/s是静默模式不弹框适合脚本化调试阶段建议去掉它让它把成功或失败的提示弹出来因为DllRegisterServer内部失败时静默模式什么都不显示。注册完不要急着跑程序先在注册表里确认InprocServer32指向的路径和你刚注册的文件是同一个机器上装过多个版本的时候这一步能省掉大量排查时间。如果regsvr32报「模块已加载但找不到入口点 DllRegisterServer」说明这个 .ax 没导出注册函数检查工程里是否定义了DllRegisterServer和对应的.def文件如果报「找不到指定模块」那是依赖的 DLL 缺失用依赖查看工具查一遍通常是某个运行库没装。4.2 qedit.h 与 SampleGrabber老代码在新 SDK 上怎么改抓帧的工程十个有九个用到ISampleGrabber而它的声明在qedit.h里。这个头文件在新版 SDK 上直接包含会报无法打开包括文件: dxtrans.h因为qedit.h内部引了 DirectX Media 的一部分类型而这块早就不随 SDK 发了。我一般用屏蔽接口定义的方式绕过去在包含qedit.h之前先把四个冲突的接口宏定义掉// 这四个宏告诉 qedit.h相关接口已经声明过不要再拉 dxtrans.h #define __IDxtCompositor_INTERFACE_DEFINED__ #define __IDxtAlphaSetter_INTERFACE_DEFINED__ #define __IDxtJpeg_INTERFACE_DEFINED__ #define __IDxtKey_INTERFACE_DEFINED__ #include qedit.h原理很简单qedit.h里那段引用是被#ifndef __IDxtCompositor_INTERFACE_DEFINED__这类条件包起来的手动定义之后预处理阶段直接跳过dxtrans.h就不会被拉进来。这四个宏必须写在#include qedit.h之前写到后面无效而且每个用到 SampleGrabber 的 .cpp 都要写建议抽成一个ds_compat.h统一包含。另一种做法是自己声明ISampleGrabber的虚表结构和 IID完全不依赖qedit.h。这种做法在跨版本编译时更稳代价是要手写几十行接口声明容易写错方法顺序。除非你要在多个 SDK 版本之间来回切否则不建议走这条路。还有个链接期的细节CLSID_SampleGrabber在quartz.lib里IID_ISampleGrabber有时候得自己定义一份报无法解析的外部符号 IID_ISampleGrabber就是这个原因。定义的时候 GUID 值要和系统里注册的完全一致差一个字节都创建不出来。4.3 设备枚举与 Win10 的两个权限开关代码编过了、filter 注册了接下来最常见的现象是枚举不到摄像头。先别怀疑代码Win10 有个隐私开关设置 → 隐私 → 相机里面「允许应用访问你的相机」和「允许桌面应用访问你的相机」两个都要打开。第二个默认可能是关的而 DirectShow 走的正是桌面应用这条通道。枚举设备的写法比较固定用系统设备枚举器按类别过滤// 枚举视频输入设备注意 S_FALSE 是「这一类一个都没有」不是失败 ICreateDevEnum* pDevEnum nullptr; CoCreateInstance(CLSID_SystemDeviceEnum, nullptr, CLSCTX_INPROC_SERVER, IID_ICreateDevEnum, (void**)pDevEnum); IEnumMoniker* pEnum nullptr; HRESULT hr pDevEnum-CreateClassEnumerator(CLSID_VideoInputDeviceCategory, pEnum, 0); if (hr ! S_OK) { // S_FALSE系统里没有任何视频输入设备先去看设备管理器 printf(没有找到视频输入设备\n); } IMoniker* pMoniker nullptr; while (pEnum pEnum-Next(1, pMoniker, nullptr) S_OK) { IPropertyBag* pBag nullptr; pMoniker-BindToStorage(nullptr, nullptr, IID_IPropertyBag, (void**)pBag); VARIANT var; VariantInit(var); // FriendlyName 就是设备管理器里显示的那个名字用它判断选的是哪一个 pBag-Read(LFriendlyName, var, nullptr); if (var.vt VT_BSTR) wprintf(L设备: %s\n, var.bstrVal); VariantClear(var); pBag-Release(); pMoniker-Release(); } if (pEnum) pEnum-Release(); pDevEnum-Release();CreateClassEnumerator返回S_FALSE是很多人会误判的地方它不是错误只是这一类设备数量为零。这时候往下查的方向是驱动和设备管理器而不是代码。另外注意Next返回S_OK才是拿到一个 moniker循环条件写成 S_OK而不是SUCCEEDED(...)否则最后一个元素会被多处理一次。5. 排查记录DirectShow 在 Win10 上翻车的五个坑5.1 编译期头文件和库的坑坑一无法打开包括文件: dxtrans.h。现象是编译到某个用 SampleGrabber 的文件就中断报错行指向qedit.h内部。原因是新版 Windows SDK 不再附带 DirectX Media 的那部分头文件而qedit.h默认会去引。解决办法就是上一节那四个宏写在#include qedit.h之前全工程统一放一个兼容头文件里不要每个文件各写一遍容易漏。坑二LNK2038: 检测到“RuntimeLibrary”的不匹配项。现象是链接期报错提示MD_DynamicRelease和MT_StaticRelease冲突。原因是 BaseClasses 编出来的 lib 用的是/MD而你自己的工程在「C/C → 代码生成 → 运行库」里选成了/MT。解决是把主工程的运行库改成和 BaseClasses 一致的多线程 DLL/MDDebug 配置对应/MDd。不要反过来去改 BaseClasses 的工程设置改了下次换版本又得重来。坑三LNK2019: 无法解析的外部符号 CLSID_FilterGraph。现象是编译通过、链接报一堆 GUID 未定义。原因是附加依赖项里少了quartz.lib或strmiids.lib。解决是按 3.2 节那张表把该加的库补齐注意 Debug 和 Release 两份配置都要加只改一份是最常见的疏忽。5.2 运行期注册与设备的坑坑四CoCreateInstance返回0x80040154类未注册。现象是自写 filter 在开发机上好好的换一台机器就创建不出来。原因有三种位数不匹配导致注册表里根本没有这条记录、regsvr32用错了目录32 位文件用 System32 的注册器、或者是注册成功了但注册表被 32/64 位重定向到了另一个分支。解决是先按 4.1 节的规则重注册一遍再用reg query确认InprocServer32的路径确实指向你编译出来的那个 .ax。坑五graph 建起来了但采集黑屏、帧数为零。现象是 pin 都连上了Run之后回调一次都不进。原因通常不是代码Win10 的相机隐私开关没开、摄像头被另一个程序独占、或者用了MEDIASUBTYPE_RGB24而设备只出YUY2。解决顺序是先开隐私开关再关掉所有可能占用摄像头的程序最后用 GraphStudioNext 手动连一遍同样的 graph看 pin 的媒体类型协商到了什么。手动连能出图、代码不能出图问题一定在你的参数设置上不在环境上。这五个坑覆盖了从编译到运行的大半场景剩下的基本是它们的变体。真正查不出来的时候我会用依赖查看工具看 .ax 的动态库依赖用 Process Monitor 看注册表读写落在哪个分支——这两样比反复改代码有效得多。6. 装完怎么验证三层验证法确认 graph 真的跑起来了装完不代表能用我习惯按三层往下验任何一层不过就停在那一层查不要跳。第一层验「组件在不在」。命令行敲两条:: 系统自带的 DirectShow 核心组件正常 Win10 两个目录都该有 dir C:\Windows\System32\quartz.dll dir C:\Windows\SysWOW64\quartz.dll :: 查自定义 filter 的注册信息InprocServer32 必须指向实际文件 reg query HKCR\CLSID\{你的Filter的CLSID}\InprocServer32 /ve两条都有输出且路径对得上第一层算过。reg query报「系统找不到指定的注册表项」说明 filter 没注册成功回 4.1 节。第二层验「graph 连不连得通」。打开 GraphStudioNextGraph → Insert Filter把采集设备和渲染器拉进来手动连 pin。连不上会直接标红并告诉你媒体类型协商失败在哪一步。这一层的价值在于把「代码问题」和「环境问题」彻底分开手动连得上、代码连不上就是参数写错了手动也连不上就是驱动或设备的问题。第三层验「跑起来有没有数据」。写个最小循环Run之后数回调次数跑三秒看帧数验证项观察点期望结果COM 初始化CoInitializeEx返回值S_OK或S_FALSE设备枚举CreateClassEnumerator返回值S_OK且至少一个设备Graph 构建SetFiltergraph与RenderStream返回值S_OK数据流三秒内回调次数大于零且大致等于帧率 × 3退出清理释放后无断言Debug 版无弹窗三秒回调次数为零但 graph 状态是 Running回头看坑五次数远低于帧率检查是不是在回调里做了耗时操作阻塞了数据流线程。从那以后我每次在新机器上装完 DirectShow都会先用 GraphStudioNext 手动连一遍 graph 再动业务代码这一步花五分钟能挡掉后面大半天对着黑屏猜原因的工夫。希望帮到你。本文还有配套的精品资源点击获取