DirectShow 常用函数总结

本文准备总结一些 Direct Show 常用的API接口函数，方便以后查询回忆。如果这里没有你想了解的函数，你可以自行搜索MSDN + 函数名去 MSDN 查找你想要了解的函数，也可以查看百度百科相关。（持续更新中）

CoInitialize

在当前线程上初始化 COM 库。

Syntax

HRESULT CoInitialize(LPVOID pvReserved);

Parameters

pvReserved：此参数是保留参数，必须为 NULL。

返回值

返回一个 HRESULT 值。可能的值包括：

S_OK：COM 库在此线程上成功初始化。
S_FALSE：COM 库已经在此线程上初始化过了。

备注

新应用程序应调用 CoInitializeEx 而不是 CoInitialize。CoInitializeEx 提供相同功能的同时还提供了参数明确指定线程的并发模型。CoInitialize 调用 CoInitializeEx 并将并发模型指定为单线程单元。

参考自：MSDN CoInitialize function

CoUninitialize

关闭当前线程上的 COM 库，卸载该线程加载的所有 DLL，释放该线程维护的所有其他资源，并强制关闭该线程上的所有 RPC 连接。

Syntax

void CoUninitialize();

Parameters

此函数没有参数。

返回值

此函数不返回值。

备注

线程每次成功调用 CoInitialize 或 CoInitializeEx 函数后，都必须调用相对应的 CoUninitialize 函数将 COM 库再关闭。

参考：MSDN CoUninitialize function

CoCreateInstance

用指定的类标识符创建一个未初始化的 COM 对象。

Syntax

HRESULT CoCreateInstance(

  REFCLSID  rclsid,

  LPUNKNOWN pUnkOuter,

  DWORD     dwClsContext,

  REFIID    riid,

  LPVOID    *ppv

);

Parameters

rclsid：创建的 COM 对象的类标识符（CLSID）。
pUnkOuter：指向接口 IUnknown 的指针，大多数情况下都设置为 NULL。
dwClsContext：运行新创建对象的代码的上下文。该值取自枚举 CLSCTX。
riid：创建的 COM 对象的接口标识符（IID）。
ppv：用来接收指向 COM 对象接口地址的指针变量。

返回值

返回一个 HRESULT 值。具体的值可去 MSDN 对应页面查看。

备注

如果要在本地系统上仅创建一个对象，请调用 CoCreateInstance。要在远程系统上创建单个对象，请调用 CoCreateInstanceEx 函数。要基于单个 CLSID 创建多个对象，请调用 CoGetClassObject 函数。

参考：MSDN CoCreateInstance、百度百科 CoCreateInstance

IUnknown::QueryInterface

通过此方法来查询 COM 对象是否支持某个特定的接口。

Syntax

HRESULT QueryInterface(REFIID riid, void** ppvObject);

Parameters

riid：指明需要查询的接口的标识符（IID）。
ppvObject：指向 COM 对象中 riid 参数标识的接口指针的地址。

返回值

如果支持该接口，则此方法返回 S_OK，否则返回 E_NOINTERFACE。

备注

因为 IGraphBuilder 是从 IFilterGraph 这个类继承过来的，拥有 IFilterGraph 提供的所有方法。而 IFilterGraph 接口从 IUnknown 这个接口继承过来的，所以 IGraphBuilder 可以执行IGraphBuilder::QueryInterface。

参考：MSDN IUnknown::QueryInterface method

IGraphBuilder::RenderFile

构建一个渲染特定文件的 filter graph。

Syntax

HRESULT RenderFile(LPCWSTR lpcwstrFile, LPCWSTR lpcwstrPlayList);

Parameters

lpcwstrFile：指定包含媒体文件名的宽字符字符串。
lpcwstrPlayList：保留参数，必须为 NULL。

返回值

返回一个 HRESULT 值。具体的值可去 MSDN 对应页面查看。

备注

如果 lpwstrFile 参数指定了媒体文件，则该方法将会构建一个 filter graph 来播放。

参考：MSDN IGraphBuilder::RenderFile

IMediaControl::Run

运行 filter graph 中的所有 filter。当 graph 运行时，数据在 graph 中移动并被渲染。

Syntax

HRESULT Run();

Parameters

此函数没有参数。

返回值

返回一个 HRESULT 值。具体的值可去 MSDN 对应页面查看。

备注

如果 filter graph 已停止，则此方法将在运行之前暂停该 graph。如果该 graph 已经在运行，则该方法返回 S_OK，但无效。

成功调用，一般 graph 将一直运行，直到应用程序调用 IMediaControl :: Pause 或 IMediaControl :: Stop 方法为止。当回放到达 stream 的末尾时，graph 将继续运行，但是 filter 不再流化任何数据。此时，应用程序可以暂停或停止 graph。

参考：MSDN IMediaControl::Run

IMediaEvent::WaitForCompletion

等待 filter graph 渲染所有可用数据。filter graph 必须正在运行，否则该方法将失败。

Syntax

HRESULT WaitForCompletion(long msTimeout, long *pEvCode);

Parameters

msTimeout：超时时间，以毫秒为单位。传递 0 立即返回。传递值 INFINITE 无限期阻塞。

pEvCode：指向接收事件代码的变量的指针。

返回值

返回一个 HRESULT 值。可能的值包括：

S_OK：成功。
E_ABORT：超时时间已到。
VFW_E_WRONG_STATE：filter graph 未运行。

备注

该方法将一直阻塞，直到超时到期或发生以下事件之一：

参考：MSDN IMediaEvent::WaitForCompletion

ICaptureGraphBuilder2::SetFiltergraph

为 capture graph builder 指定要使用的 filter graph。

Syntax

HRESULT SetFiltergraph(IGraphBuilder* pfg);

Parameters

pfg：指向 filter graph 的 IGraphBuilder 接口指针。

返回值

返回一个 HRESULT 值。具体的值可去 MSDN 对应页面查看。

备注

如果不调用此方法，则 capture graph builder 会在需要时自动创建一个 filter graph。如果 capture graph builder 已经具有 filter graph，则此方法返回 E_UNEXPECTED。

参考：MSDN ICaptureGraphBuilder2::SetFiltergraph

ICreateDevEnum::CreateClassEnumerator

创建指定 device category 的 enumerator（枚举）。

Syntax

HRESULT CreateClassEnumerator（

  REFCLSID  clsidDeviceClass ，

  IEnumMoniker   ppEnumMoniker ，

  DWORD  dwFlags

）;

Parameters

clsidDeviceClass：[in]指定 device category 的类标识符（CLSID）。
ppEnumMoniker：[out]接收 IEnumMoniker 接口指针的地址。
dwFlags：[in]0 个或多个标志的按位组合。如果为 0，则该方法枚举类别中的每个 filter。更多标志请查看：ICreateDevEnum::CreateClassEnumerator

返回值

返回一个 HRESULT 值。具体的值可去 MSDN 对应页面查看。

备注

参考：MSDN ICreateDevEnum::CreateClassEnumerator

IMoniker::BindToObject

绑定到指定对象。绑定过程包括查找对象，必要时将其置于运行状态，并为调用者提供指向所标识对象上指定接口的指针。

Syntax

HRESULT BindToObject(

  IBindCtx *pbc,

  IMoniker *pmkToLeft,

  REFIID   riidResult,

  void     ppvResult

);

Parameters

pbc：指向绑定上下文对象上的 IBindCtx 接口的指针，此绑定操作中使用该指针。
pmkToLeft：此参数主要由 moniker 实现者使用，以启用复合名称的各个组件之间的协作。Moniker 客户端应使用 NULL。
riidResult：用于与 moniker 标识的对象进行通信的接口 IID。
ppvResult：接收 riid中 请求的接口指针的地址。成功返回后，ppvResult 包含指向 moniker 标识的对象的请求接口指针。

返回值

返回一个 HRESULT 值。具体的值可去 MSDN 对应页面查看。

备注

BindToObject 实现了别名的主要功能，该功能是查找由别名标识的对象，并返回指向其接口之一的指针。

参考：MSDN IMoniker::BindToObject method

IFilterGraph::AddFilter

此方法将 filter 添加到 filter graph 并使用 pName 参数对其进行命名。

Syntax

HRESULT AddFilter(IBaseFilter* pFilter, LPCWSTR pName);

Parameters

pFilte：[in]要加入到 filter graph 中的 filter。
pName：[in] 加入 filter 的名称。

返回值

返回一个 HRESULT 值。具体的值可去 MSDN 对应页面查看。

备注

BindToObject 实现了别名的主要功能，该功能是查找由别名标识的对象，并返回指向其接口之一的指针。

参考：MSDN IMoniker::BindToObject method

IUnknown::AddRef

增加指向 COM 对象的接口指针的引用计数。复制接口指针时，应调用此方法。

Syntax

ULONG AddRef();

Parameters

此函数没有参数。

返回值

该方法返回新的引用计数。此值仅用于测试目的。

备注

COM 对象使用每个接口的引用计数机制来确保该对象不会超出对其的引用。您可以使用AddRef 来稳定接口指针的副本。当克隆指针的寿命必须超过原始指针的寿命时，也可以调用它。必须通过调用 IUnknown::Release 释放克隆的指针。

参考：MSDN IUnknown::AddRef

ICaptureGraphBuilder2::RenderStream

此方法可以将 source filter 上的 output pin 连接到 sink filter，也可以通过中间 filter 连接。

Syntax

HRESULT RenderStream(

  const GUID*  pCategory,

  const GUID*  pType,

  IUnknown*    pSource,

  IBaseFilter* pIntermediate,

  IBaseFilter* pSink

);

Parameters

pCategory：[in]指向 AMPROPERTY_PIN_CATEGORY 属性集中的 pin 类别的指针（请参见 Pin属性集）。使用 NULL 可以匹配任何类别。以下列表显示了典型类别。
- PIN_CATEGORY_CAPTURE
- PIN_CATEGORY_PREVIEW
- PIN_CATEGORY_CC
pType：[in]指向主要类型 GUID 的指针，该 GUID 指定输出 pin 的媒体类型；或 NULL 以使用任何 pin，而与媒体类型无关。有关可能值的列表，请参考 Media Types and Sub Types。
pSource：[in]指定一个指向连接的起始 filter 或输出 pin 的指针。
pIntermediate：[in]指向中间 filter （例如压缩 filter）的 IBaseFilter 接口的指针。可以为 NULL。
pSink：[in]指向 sink filter（例如 renderer 或 mux filter）的 IBaseFilter 接口的指针。如果值为 NULL，则该方法使用默认的 renderer（渲染器）。

返回值

返回一个 HRESULT 值。具体的值可去 MSDN 对应页面查看。

备注

该方法通过将两个或多个 filter 连接在一起形成一个流：

PSource 参数指定链的开始，或者一个 filter 或输出 pin。
pIntermediate 参数指定的中间 filter，典型地是压缩 filter。此参数可以为 NULL。
pSink 参数指定链的端部的 filter。通常，此 filter 是用于预览的 renderer，或者是用于文件捕获的多路复用器。

参考：MSDN ICaptureGraphBuilder2::RenderStream

[扩展] 常用 CLSID

CLSID_FilterGraph：在共享工作线程上创建 Filter Graph Manager。

CLSID_CaptureGraphBuilder2：用于创建 capture graph builder。