Media Foundation 初始化需先调用CoInitializeEx(nullptr, COINIT_MULTITHREADED)，再调用MFStartup(MF_VERSION)；设备枚举须设置MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP属性；帧数据访问前必须Lock缓冲区；OnReadSample中不可直接操作UI，应PostMessage到主线程处理。
Media Foundation 初始化失败：CoInitializeEx 和 MFStartup 必须配对调用
直接调用 MFStartup 而不先初始化 COM，会导致返回 MF_E_PLATFORM_NOT_INITIALIZED。Windows 要求 Media Foundation 建立在多线程 COM 模型上，且必须显式指定 COINIT_MULTITHREADED。
-
CoInitializeEx(nullptr, COINIT_MULTITHREADED)是前提，不能省略或用CoInitialize -
MFStartup(MF_VERSION)必须在CoInitializeEx成功后调用，版本号建议用MF_VERSION（即 0x00010000） - 对应地，退出前要按顺序调用
MFShutdown()和CoUninitialize()，否则后续重复初始化可能失败
找不到可用视频采集设备：EnumDeviceSources 返回空列表
常见原因是未正确设置 MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE 属性，或设备本身被其他进程（如 Zoom、OBS、系统相机 App）独占占用。
- 枚举前需创建属性集合：
MFCreateAttributes(&pAttributes, 1)，再调用pAttributes->SetGUID(MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE, MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP) - 调用
MFEnumDeviceSources(pAttributes, &ppDevices, &cDevices)后，务必检查cDevices是否 > 0；为零时不要跳过错误处理 - 若设备被占用，
ActivateObject()会返回MF_E_DEVICE_IN_USE，此时需提示用户关闭其他摄像头程序
捕获帧数据为空：IMFSample 中没有有效 IMFMediaBuffer
即使回调触发，IMFSample::GetBufferByIndex(0, &pBuffer) 可能返回 nullptr 或缓冲区长度为 0，本质是未正确锁定缓冲区或格式不匹配。
- 必须调用
pBuffer->Lock(&pData, &cbMaxLength, &cbCurrentLength)才能访问原始像素数据，仅获取指针不等于数据就绪 - 默认捕获格式常为
MFVideoFormat_RGB32或MFVideoFormat_NV12，需通过IMFSourceReader::GetCurrentMediaType()确认实际格式，避免按错 stride 解析 - RGB32 的每行字节长（stride）未必等于
width * 4，应取MF_MT_DEFAULT_STRIDE属性值，否则图像会出现横向错位或绿条
回调线程中访问 UI 控件崩溃：IMFSourceReaderCallback 不在主线程执行
Media Foundation 默认在内部线程池中调用 OnReadSample，直接操作 Win32 窗口句柄（如 SendMessage）或 MFC/Qt 控件会引发 GDI 冲突或断言失败。
立即学习“C++免费学习笔记（深入）”；
- 不要在
OnReadSample中直接调用InvalidateRect或更新CStatic图片控件 - 推荐方案：用
PostMessage向主线程窗口发送自定义消息（如WM_USER + 100），附带IMFSample*指针（需 AddRef）并在主线程中 Release - 更稳妥做法是将帧数据 memcpy 到预分配的线程安全缓冲区（如
std::atomic+std::array），再由定时器或空闲循环读取渲染
HRESULT OnReadSample(HRESULT hrStatus, DWORD dwStreamIndex, DWORD dwStreamFlags,
LONGLONG llTimestamp, IMFSample* pSample) override {
if (SUCCEEDED(hrStatus) && pSample && !(dwStreamFlags & MF_SOURCE_READER_FLAG_ENDOFSTREAM)) {
IMFMediaBuffer* pBuffer = nullptr;
BYTE* pData = nullptr;
DWORD cbMaxLength = 0, cbCurrentLength = 0;
if (SUCCEEDED(pSample->ConvertToContiguousBuffer(&pBuffer)) &&
SUCCEEDED(pBuffer->Lock(&pData, &cbMaxLength, &cbCurrentLength))) {
// ✅ 此处可安全 memcpy 数据
// ⚠️ 不要在此处 CreateDIBSection / SetDIBitsToDevice
PostMessage(hWndMain, WM_USER_FRAME_READY, 0, (LPARAM)pSample);
pSample->AddRef(); // 主线程负责 Release
}
if (pBuffer) pBuffer->Unlock();
SafeRelease(&pBuffer);
}
return S_OK;}
MF 的设备发现和帧流转依赖多个 COM 对象生命周期管理，漏掉任意一个 Release() 或提前释放 IMFSourceReader，都可能导致下一次捕获卡在等待状态。真正稳定运行的关键不在“怎么拿到帧”，而在“谁在什么时候释放了什么”。
