简介：面向DirectShow开发者的视频捕获示例工程，演示了视频采集与多种像素格式转换的典型用法，适合初学DirectShow或需要将格式转换功能集成到自有项目的开发者。压缩包为RAR格式，共20个文件，主体为6个头文件与4个C++源文件，配合工程解决方案sln、vcproj及资源文件rc/ico等，结构清晰可直接编译查看。其中cscc.lib封装了RGB24_to_YV12、YV12_to_RGB24、YVU9_to_YV12、YUY2_to_YV12、YV12_to_YUY2等常用转换函数，涵盖YUV与RGB系列互转，便于直接调用或扩展。包体仅55KB，轻量易部署，已有246人学习下载。这套示例为视频处理开发提供了可复用的转换工具和捕获流程参照，尤其适合在图像采集、视频编码前处理等场景下快速核对格式转换细节。
1. 直接上手 DirectShow 捕获：为什么这个老技术现在还值得用
做桌面端视频工具时，你迟早会撞上 DirectShow——哪怕你已经习惯了 OpenCV 的VideoCapture一把梭。某个开发者前阵子接了个项目，要给一台工控机接四路 USB 摄像头做实时采集，OpenCV 在 Windows 下枚举摄像头经常丢设备，帧率也压不住，换用 DirectShow 的Dshow Capture这套封装后，设备枚举、格式协商、帧回调全部可控，CPU 占用还降了三分之一。这个技术是 2000 年前后的产物，但 Windows 至今原声支持，摄像头、采集卡、虚拟设备都能统一接进来。适合谁？写桌面安防、医学影像、工业视觉、视频会议调试工具的人——只要你的目标平台是 Windows，且 camera 型号杂、需要精细控制，DirectShow 就不是过时方案，而是最稳的底牌。这份资源把 DirectShow 捕获流程做成了直接可跑的工程，省掉你从 MSDN 缝里抠接口的时间。
2. 设备枚举与源码结构：先看懂这份资源怎么组织
2.1 从 ICreateDevEnum 到 IMoniker：抓出系统里的每一路摄像头
DirectShow 的设备枚举对新手是个黑匣子：为什么我capGetDriverDescription只能拿到旧版 VFW 驱动的名字？因为 DirectShow 走的是 COM 接口ICreateDevEnum，它按类别枚举系统里的 Filter，视频输入设备属于CLSID_VideoInputDeviceCategory。这一步绕不过去，所有上层封装（包括 OpenCV 的MSMF后端）最终都归到这套枚举逻辑上。
在这份Dshow Capture资源里，枚举部分是一个独立类，核心代码大致长这样：
// EnumerateDevices.cpp HRESULT EnumerateVideoDevices(std::vector<DeviceInfo>& outDevices) { HRESULT hr = S_OK; ICreateDevEnum* pDevEnum = nullptr; IEnumMoniker* pEnumMon = nullptr; // 创建系统设备枚举器 hr = CoCreateInstance(CLSID_SystemDeviceEnum, NULL, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&pDevEnum)); if (FAILED(hr)) return hr; // 指定视频输入设备类别，拿到枚举器 hr = pDevEnum->CreateClassEnumerator( CLSID_VideoInputDeviceCategory, &pEnumMon, 0); if (hr == S_FALSE) { // 返回 S_FALSE 表示该类设备不存在，不是失败 pEnumMon = nullptr; return hr; } IMoniker* pMoniker = nullptr; while (pEnumMon->Next(1, &pMoniker, nullptr) == S_OK) { IPropertyBag* pPropBag = nullptr; hr = pMoniker->BindToStorage(0, 0, IID_PPV_ARGS(&pPropBag)); if (SUCCEEDED(hr)) { VARIANT varName; VariantInit(&varName); // 读设备的 FriendlyName，这就是你在设备管理器里看到的名称 hr = pPropBag->Read(L"FriendlyName", &varName, 0); if (SUCCEEDED(hr)) { DeviceInfo info; info.friendlyName = varName.bstrVal; outDevices.push_back(info); VariantClear(&varName); } pPropBag->Release(); } pMoniker->Release(); } pEnumMon->Release(); pDevEnum->Release(); return S_OK; }这段代码有两个细节值得记：第一，CreateClassEnumerator返回S_FALSE不代表失败，而是表示这台机器上压根没有视频设备，这时候直接返回空列表就行，别当成异常去弹错误框。第二，BindToStorage拿IPropertyBag读取的是设备属性包，除了FriendlyName，你还能读DevicePath，那是设备唯一标识，用来区分两个同型号摄像头特别有用——这个后面多路采集时会讲。
2.2 资源包目录结构与关键类说明
Dshow Capture不是单文件脚本，它是一套完整的 Visual Studio 工程。解压后顶层目录大概是这样的结构：
DshowCapture/ ├── src/ │ ├── DeviceEnumerator.cpp/.h // 设备枚举 │ ├── CaptureGraph.cpp/.h // Filter Graph 构建 │ ├── SampleGrabberCallback.cpp/.h // 帧回调 │ ├── MediaTypeHelper.cpp/.h // 格式协商 │ └── FrameConverter.cpp/.h // YUY2/RGB24 -> RGB32 ├── demo/ │ ├── ConsoleDemo/ // 命令行采集测试 │ └── OpenCVDemo/ // 集成 OpenCV 显示 ├── include/ // 对外头文件 ├── lib/ // 预编译静态库 └── docs/ └── usage.md // 使用说明与 API 清单在我实际跑过的工程里，最值得优先读的是CaptureGraph.cpp，它把IGraphBuilder、ICaptureGraphBuilder2、IMediaControl这几张核心接口的关系理顺了。收到这份资源后，第一步不是急着编译 Demo，而是按这个顺序读：先看DeviceEnumerator确认设备枚举逻辑，再看CaptureGraph理解管线搭建方式，最后看SampleGrabberCallback弄懂帧是怎么一条路走到你的回调函数里的。顺序对了，后面改参数你才知道去哪一层动刀。
3. 采集管线搭建：把摄像头画面拉进内存缓冲
3.1 Filter Graph 的三种构建方式与选型
DirectShow 的采集管线本质是一张 Filter Graph：源 Filter（摄像头）→ 中间 Filter（格式转换、Sample Grabber）→ 渲染 Filter（显示或写入文件）。构建这张图有三种常见姿势：
第一种是直接用IGraphBuilder::AddFilter手动把每个 Filter 加进去，然后找到 Pin 手动连接。这种姿势最啰嗦，但控制力最强，适合采集卡这种需要精确指定物理通道的场景。
第二种是ICaptureGraphBuilder2::RenderStream，它只需要你告诉它：源 Filter、需要连接的 Pin 类型（PIN_CATEGORY_PREVIEW或PIN_CATEGORY_CAPTURE）、以及中间 Filter，它会自动挑合适的 Pin 并把整条链路搭好。这是最容易上手的姿势，资源里的 ConsoleDemo 默认就用这个。
第三种是结合ICaptureGraphBuilder2::FindPin先查找指定 Pin，再做部分手动连接。这种方式适合你既要自动协商，又要在某个节点强制插入自定义 Filter 的场景。
我在自己的项目里通常选第二种起步，因为它能避开「Pin 类型不对导致连接失败」这种经典翻车点。选型原则很简单：纯摄像头采集用RenderStream足够；涉及采集卡多路输入或需要插第三方滤镜时，再升级到 FindPin 手动连。
3.2 用 Sample Grabber 拉流：回调里收帧
RenderStream的链路默认会把视频送到 VMR 或 EVR 渲染器去显示，但我们通常只需要拿到原始帧数据。解决办法是在源 Filter 和渲染器之间插入一个Sample Grabber，让它把每一帧截下来交给你的回调函数。这段代码是资源里最核心的部分：
// BuildGraph.cpp 片段 hr = CoCreateInstance(CLSID_SampleGrabber, NULL, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&m_pSampleGrabber)); if (FAILED(hr)) return hr; // 必须先把媒体类型设为 NULL，允许 SampleGrabber 自动协商 AM_MEDIA_TYPE mt; ZeroMemory(&mt, sizeof(mt)); mt.majortype = MEDIATYPE_Video; hr = m_pSampleGrabber->SetMediaType(&mt); // 注册回调 hr = m_pSampleGrabber->SetCallback(&m_callback, 0);这里有个隐藏约束：SetMediaType(&mt)时，如果你把subtype设置成具体格式，比如MEDIASUBTYPE_RGB24，那么 Sample Grabber 会强制要求上游输出的格式必须匹配，否则连接失败。所以没有明确要求时，只指定主类型MEDIATYPE_Video，其他字段留空，让 Filter Graph 自己去协商。回调接口ISampleGrabberCB有两个方法，实模式SampleCB传的是媒体样本指针，缓冲模式BufferCB传的是内存指针。资源默认用BufferCB，因为它直接给你数据缓冲，少一次拷贝，性能更好。
3.3 帧率与分辨率参数设置
很多人误以为 DirectShow 不需要设置采集分辨率，摄像头默认输出什么就是什么。实际上，对于 UVC 摄像头，你可以在IAMStreamConfig接口上设置VIDEO_STREAM_CONFIG_CAPS里的分辨率、帧率和颜色格式。下面是直接在 Capture Graph 上操作的代码：
// SetCaptureParams.cpp CComPtr<IAMStreamConfig> pStreamConfig; hr = m_pCaptureGraphBuilder->FindInterface( &PIN_CATEGORY_CAPTURE, &MEDIATYPE_Video, m_pSourceFilter, IID_IAMStreamConfig, (void**)&pStreamConfig); int iCount = 0, iSize = 0; pStreamConfig->GetNumberOfCapabilities(&iCount, &iSize); VIDEO_STREAM_CONFIG_CAPS caps; pStreamConfig->GetStreamCaps(0, &m_mediaType, (BYTE*)&caps); // 经典参数：分辨率、帧率、颜色格式 m_mediaType.formattype = FORMAT_VideoInfo; VIDEOINFOHEADER* vih = (VIDEOINFOHEADER*)m_mediaType.pbFormat; vih->bmiHeader.biWidth = 1920; vih->bmiHeader.biHeight = 1080; vih->bmiHeader.biBitCount = 24; // 设置帧率 30fps vih->AvgTimePerFrame = 333333; // 单位是 100ns hr = pStreamConfig->SetFormat(&m_mediaType);AvgTimePerFrame的单位是 100 纳秒，333333就是 1/30 秒，写成10000000 / fps更容易维护。GetStreamCaps返回的是设备支持的能力列表，索引从 0 开始。如果直接SetFormat一个设备不支持的格式，返回会是VFW_E_INVALIDMEDIATYPE。这就是为什么必须先把GetNumberOfCapabilities和GetStreamCaps打一遍，看清设备到底支持哪些组合，再去设你要的值。玄学的是，有些虚拟摄像头驱动会假装支持高分辨率，但SetFormat成功了，实际出来的帧还是低分辨率——后面避坑章会细说。
4. 参数协商与格式转换：别让摄像头给你乱出牌
4.1 枚举媒体类型：看清支持的分辨率和帧率
拿到IAMStreamConfig接口后，不要直接猜格式。一定要把它支持的AM_MEDIA_TYPE全部打出来，存成一个候选列表。这份资源里MediaTypeHelper.cpp有一个函数封装了这件事：
// MediaTypeHelper.cpp std::vector<AM_MEDIA_TYPE> GetSupportedMediaTypes( CComPtr<IAMStreamConfig>& pConfig) { std::vector<AM_MEDIA_TYPE> types; int iCount = 0, iSize = 0; HRESULT hr = pConfig->GetNumberOfCapabilities(&iCount, &iSize); if (FAILED(hr) || iCount <= 0) return types; for (int i = 0; i < iCount; i++) { AM_MEDIA_TYPE mt; BYTE* pCaps = new BYTE[iSize]; hr = pConfig->GetStreamCaps(i, &mt, pCaps); if (SUCCEEDED(hr)) { types.push_back(mt); // 注意：调用方需要 DeleteMediaType // pCaps 由 GetStreamCaps 内部填充，用完即弃 } delete[] pCaps; } return types; }这里有个内存坑：GetStreamCaps返回的AM_MEDIA_TYPE是 COM 分配的内存，你必须用DeleteMediaType(&mt)释放，否则每次调用泄漏一份。我见过最离谱的泄漏是在一个长期运行的服务里枚举能力列表，每分钟一次，两周后内存涨到三个 G。这个函数里故意用push_back做浅拷贝，注释提醒调用方释放，就是为了防止用户直接把本地变量丢给CoTaskMemFree那种张冠李戴的写法。
4.2 RGB24 / YUY2 / MJPG：颜色格式怎么选
枚举出来的列表里你会看到MEDIASUBTYPE_YUY2、MEDIASUBTYPE_UYVY、MEDIASUBTYPE_RGB24、MEDIASUBTYPE_MJPG等。选择原则要看你拿帧之后的用途。
如果只是显示或送到编码器，尽量保持设备的原生格式。大多数 USB 摄像头原生输出是 YUY2，这是一种 4:2:2 的 YUV 格式，每像素占 16 位。如果你直接要求 RGB24，驱动会内部转换，CPU 占用上升，而且有些廉价摄像头在 RGB24 下的最大分辨率会被砍半。MJPG 则是摄像头内部压缩成 JPEG 帧，帧率可以做得非常高（部分摄像头 1080p 能到 60fps），但你的程序要自己解压，解压的 CPU 开销不一定比 YUY2 低。
我的习惯是这样：做实时预览或做图像识别，都先问一下设备原生支持什么。如果设备原生给 YUY2，我就接 YUY2，到FrameConverter里再转 RGB24；如果设备只给 MJPG，我就接收 MJPG 再jpeg_decode。不要一上来就SetFormat(RGB24)把驱动硬件转换这条路堵死，尤其是多路采集的时候，转换杀手锏反而是 YUY2 转 RGB24 那个 SSE2 优化版本。
4.3 把抓到的帧转成 OpenCV Mat
SampleGrabber回调里拿到的是BYTE* pBuffer，长度取决于格式。在最常见的 YUY2 格式下，一帧大小是width * height * 2字节，每个像素由 Y 和交错的 UV 组成。要把这份数据变成 OpenCV 能用的Mat，不能直接cv::Mat(h, w, CV_8UC3, pBuffer)，因为那是 RGB 布局的。正确的做法是先转格式，资源里FrameConverter.cpp有一段手工转换逻辑：
// FrameConverter.cpp void YUY2ToRGB24(const BYTE* yuy2, int width, int height, BYTE* rgb) { for (int i = 0; i < width * height / 2; i++) { int y0 = yuy2[i * 4 + 0]; int u = yuy2[i * 4 + 1] - 128; int y1 = yuy2[i * 4 + 2]; int v = yuy2[i * 4 + 3] - 128; // 第一个像素 int r = (int)(y0 + 1.402f * v); int g = (int)(y0 - 0.344f * u - 0.714f * v); int b = (int)(y0 + 1.772f * u); // 溢出截断 r = r < 0 ? 0 : r > 255 ? 255 : r; g = g < 0 ? 0 : g > 255 ? 255 : g; b = b < 0 ? 0 : b > 255 ? 255 : b; rgb[i * 6 + 0] = (BYTE)b; rgb[i * 6 + 1] = (BYTE)g; rgb[i * 6 + 2] = (BYTE)r; // 第二个像素复用同一个 UV r = (int)(y1 + 1.402f * v); g = (int)(y1 - 0.344f * u - 0.714f * v); b = (int)(y1 + 1.772f * u); r = r < 0 ? 0 : r > 255 ? 255 : r; g = g < 0 ? 0 : g > 255 ? 255 : g; b = b < 0 ? 0 : b > 255 ? 255 : b; rgb[i * 6 + 3] = (BYTE)b; rgb[i * 6 + 4] = (BYTE)g; rgb[i * 6 + 5] = (BYTE)r; } }这种双像素共享 UV 的转换逻辑写起来不难，但要注意 OpenCV 默认通道是 BGR 排列，所以rgb[i*6+0]放 B、+2放 R，否则画面会蓝红互换。如果你对性能敏感，这段代码可以改成 SSE 指令一次处理四个像素；但在多路采集场景下，真正占 CPU 的往往不是这个转换，而是你后续的图像处理算法。另外提示一句：如果设备原生输出 RGB24，那直接cv::Mat(h, w, CV_8UC3, pBuffer)就能用，记得pBuffer的行对齐一般没问题，但有采集卡会做 4 字节对齐，这时你需要用cv::Mat(h, w, CV_8UC3, pBuffer, step)手动指定行宽。
5. 避坑与常见问题：DirectShow 调试三天踩出来的五个坑
5.1 坑一：枚举不到设备但系统里明明有摄像头
现象：CreateClassEnumerator(CLSID_VideoInputDeviceCategory, ...)返回S_OK，但Next一直返回S_FALSE，列表是空的。系统设置里摄像头能正常工作。
原因：最常见的有两种。第一种是 64 位和 32 位程序混用：如果系统装的是 64 位驱动，而你编译的是 32 位程序，某些摄像头驱动只注册在 64 位 COM 环境下，32 位进程枚举不到。第二种是访问权限，桌面应用如果以标准用户运行，而摄像头被系统服务（比如人脸识别登录）占用，枚举时会看到设备但打不开。
解决：先确认工程的Platform是 x64。如果是 32 位程序，强制改成 x64 重新编译。权限问题可以用管理员身份跑一次验证，但正规解法是不要在服务里直接采集摄像头，把采集放在用户会话的进程中。我这个坑就是在远程桌面会话里调试时踩的，本地登录能枚举到，远程登录后设备直接消失。
5.2 坑二：设置 1920x1080 失败，摄像头偷偷给你 640x480
现象：SetFormat返回成功，但回调里拿到的帧宽高不是你要的，只有 640x480，而且颜色格式也变了。
原因：很多摄像头驱动有「假协商」问题。在GetStreamCaps里它列出了 1920x1080 @ 30fps 的能力，但实际SetFormat时它并不真正切换传感器模式，只是把参数记在内部，输出仍然走默认的标清模式。更隐蔽的是，某些驱动在SetFormat后需要重新Run整个 Graph 才会让新格式生效，如果你只是改了格式但没有重启 Graph，它保持旧格式。
解决：每次修改格式后，先Stop()，再SetFormat，最后重新Run()。如果还不行，就把SetFormat的目标宽高换成列表里的下一个候选，一个一个试，找到驱动真正接受的那一个。我在一个国产摄像头项目里，驱动只认 800x600 和 1280x720，其他统统自动退回 640x480，没办法，只能把程序适配成 1280x720 流。
5.3 坑三：回调频率远超设定帧率，CPU 占用暴增
现象：明明SetFormat里设了AvgTimePerFrame = 333333（30fps），但回调每秒来 60 次甚至 90 次。
原因：Sample Grabber 的回调频率由上游 Filter 决定。对于 USB 摄像头，DirectShow 的源 Filter 内部如果开着预览 Pin，预览流会单独跑另一个帧率；而你接的 Sample Grabber 可能同时接收了 Preview 和 Capture 两路流量。更常见的情况是驱动没有遵守AvgTimePerFrame，它内部硬编码了最高帧率，尤其是 MJPG 模式。
解决：不要依赖回调频率来限帧。在回调里按时间戳或系统时钟做节流，超过设定间隔的帧直接丢弃。具体做法是在BufferCB里记录上一次处理的时间，if (now - lastTime < frameInterval) return S_OK;。另外，确认你的RenderStream只连了PIN_CATEGORY_CAPTURE，不要连 Preview Pin。还有一招是检查IAMStreamConfig::GetFrameRate的实际值，有些驱动支持SetFrameRate但效果很差。
5.4 坑四：颜色格式串场，画面发绿或变色
现象：画面整体偏绿、偏紫，或者红蓝互换，尤其是换了电脑或摄像头之后。
原因：DirectShow 的颜色格式协商经常出现「你以为你收到的是 RGB24，实际上收到的还是 YUY2」的情况。因为 Sample Grabber 的SetMediaType只设了主类型为MEDIATYPE_Video，具体 subtype 是 Graph 自己协商的。如果你在回调里盲目按 RGB24 处理，就会解析错位。
解决：在回调里先检查ISampleGrabber::GetConnectedMediaType，拿到当前实际连接的AM_MEDIA_TYPE，看subtype是MEDIASUBTYPE_YUY2还是MEDIASUBTYPE_RGB24。然后走对应的转换分支。这是这类资源落地时被问得最多的一个问题，很多人以为设置过就一定能拿到，实际上在 Source Filter 和 Sample Grabber 之间还可能被其他 Filter 插了一脚。
5.5 坑五：程序退出后摄像头灯还亮着
现象：进程已经 Kill 掉，但摄像头的指示灯还灭不了，USB 设备被占用，其他程序打不开。
原因：DirectShow Filter Graph 的释放顺序有问题。如果你只Release()了IGraphBuilder，但没有显式Stop()并断开所有 Filter，源 Filter 的流线程不会退出，内核驱动还处于 streaming 状态。更隐蔽的是，Sample Grabber 回调里如果持有帧缓冲的引用计数没释放，整个 Graph 的引用计数归不了零。
解决：退出时必须按这个顺序执行：先IMediaControl->Stop()，然后枚举 Graph 里所有 Filter 并调用IFilterGraph::RemoveFilter逐个移除，最后才Release各个接口。资源里CaptureGraph.cpp的DestroyGraph()函数已经按这个顺序写好了，不要自己去Release后就 sleep。我自己的血泪经验是：在OnExit里加一个WaitForSingleObject等待源 Filter 的内部线程退出信号，再用CoUninitialize收尾，从此再也没有设备占用问题。
6. 进阶：多路摄像头接入与视频录制
6.1 多路采集的关键：独立 Filter Graph 与线程亲和性
多路摄像头采集最容易翻车的地方是把所有摄像头塞进同一个 Filter Graph。DirectShow 的 Filter Graph 是一个调度单元，多路 Source Filter 共享一条时钟线，某一路出问题会把整个图拖死。正确做法是每个摄像头独立创建一套 Graph：独立的ICaptureGraphBuilder2、独立的IMediaControl、独立的 Sample Grabber 回调对象。这样一路摄像头断开只会影响它自己的 Graph，其他路照样跑。
线程安排上，我给每个 Graph 单独开一个线程跑Run()，回调里的BufferCB由该 Graph 的工作线程触发，所以你的处理逻辑如果比较重，记得把帧拷贝出来再丢到自己的处理线程池，不要在回调里做同步处理。某开发者之前看到回调里直接cv::imshow，结果 30fps 的流被拖到 12fps，回调阻塞时间太长了。
6.2 把捕获帧写成 AVI/MP4：绕不开的封装顺序
如果你要录制视频，不要试图在 Sample Grabber 回调里自己拼 AVI 文件。DirectShow 里有现成的AVI MuxFilter 和File WriterFilter，你只需把 Capture 链路连到 AVI Mux 上，然后再连 File Writer，让 Graph 自己负责帧封装和写入。资源里的 OpenCVDemo 展示的是文件录像的完整连线方式：
摄像头源 Filter -> AVI Mux Filter -> File Writer Filter -> Sample Grabber -> 你的回调这样同一路流既进了录像，也进了内存回调，两边独立消费。要注意的是，AVI 封装要求所有帧经过 AVI Mux 时保持固定帧率，否则文件时长会不对。编码器选择上，用MJPEG Compressor是压缩比和速度的平衡点，直接连 Uncompressed RGB 会让 AVI 文件大得离谱。
录制结束的时机也有讲究。你必须在Stop()之前先断开 AVI Mux 和 File Writer 的连接，否则文件尾部会缺索引块，播放器看到的是「文件已损坏」。这个细节在 MSDN 里藏在IFileSinkFilter的说明中，没人会主动告诉你。
6.3 一个我可以分享的习惯：验证摄像头参数是否生效
自从在上一个项目中因为格式假协商吃了亏，我现在拿到任何一台新摄像头，都会先跑一遍资源里那个ConsoleDemo / capstest命令行工具，让它把枚举到的设备、支持的所有媒体类型、最终协商的格式全部打印出来，再确认回调里拿到的实帧尺寸和颜色格式。这套验证流程走完，心里才有底，后面写业务代码才不会被摄像头驱动那些反直觉行为打断。
从那以后，我每次接新项目都强制自己先花十分钟做这个参数验证，而不是直接改业务代码。这一步省掉的后调式时间远比十分钟多。这套Dshow Capture资源里已经内置了这些工具，你拿到手后建议直接把capstest跑一遍，把每路摄像头的真实能力打在屏幕上再开工，希望帮到你。
本文还有配套的精品资源，点击获取
