[DirectShow] 010 - Overview of Graph Building

To create a filter graph, begin by creating an instance of the Filter Graph Manager:

要创建 filter graph ，就先创建一个 Filter Graph Manager 的实例：

IGraphBuilder* pIGB;

HRESULT hr = CoCreateInstance(CLSID_FilterGraph,

    NULL, CLSCTX_INPROC_SERVER, IID_IGraphBuilder,

    (void **)&pIGB);

The Filter Graph Manager supports the following graph-building methods:

IFilterGraph::ConnectDirect tries to make a direct connection between two pins. If the pins cannot connect, the method fails.

IGraphBuilder::Connect connects two pins. If possible, it makes a direct connection. Otherwise, it uses intermediate filters to complete the connection.

IGraphBuilder::Render starts from an output pin and builds the rest of the graph. This methods adds filters as needed, working downstream, until it reaches a renderer filter.

IGraphBuilder::RenderFile builds a complete file-playback graph.

IFilterGraph::AddFilter adds a filter to the graph. It does not connect the filter. You must create the filter before calling this method, either by calling CoCreateInstance or by using the Filter Mapper or System Device Enumerator.

IFilterGraph::ConnectDirect 尝试在两个 pin 之间建立连接，如果不能连接，函数返回失败。

IGraphBuilder::Connect 连接两个 pin 。如果可能，将建立直接连接，否则，使用中间 filter 完成连接。

IGraphBuilder::Render 开始输出 pin ，生成 graph 的其他部分。如果需要，这个方法添加 filter ，直到能触及 renderer filter 。

IGraphBuilder::RenderFile 生成一个完整的文件回放 graph 。

IFilterGraph::AddFilter 添加一个 filter 到 graph ，它不连接 filter 。在调用这个函数之前，必须创建 filter ，不管是调用 CoCreateInstance 创建还是使用 Filter mapper 或者使用 System Device Enumerator 。

These methods provide three basic approaches to building the graph:

The Filter Graph Manager builds the entire graph.

The Filter Graph Manager builds part of the graph.

The application builds the entire graph.

这些函数提供三个基本的生成 graph 的方法：

Filter Graph Manager 生成整个 graph ；

Filter Graph Manager 生成部分 graph ；

应用程序生成整个 graph 。

If you simply want to play a file that is authored in a recognized format, such as AVI, MPEG, WAV, or MP3, use the RenderFile method.

The RenderFile method starts by looking in the registry for a source filter that can parse the file. It uses the protocol (such as "http://" in the URL), the file extension, or pre-defined byte patterns in the file to determine the source filter. For details, see Registering a Custom File Type .

To build the rest of the graph, the Filter Graph Manager uses an iterative process wherein it takes the media types that a filter supports on its output pins, and searches the registry for filters that will accept that media type as input. It uses several criteria to narrow the search and prioritize filters:

The filter category identifies the general functionality of the filter.

The media type describes what kind of data the filter can accept as input or deliver as output.

The merit determines the order in which filters are tried. If two filters in the same filter category both support the same input types, the Filter Graph Manager selects the one with the highest merit value. Some filters are purposely given a low merit value because they are designed for specialized purposes and should only be added to the graph by the application.

The Filter Graph Manager uses the Filter Mapper object to search the registry.

As each filter is added, the Filter Graph Manager tries to connect it to  the previous filter's output pin. The filters negotiate to determine whether they can connect, and if so, what media type to use for the connection. If the new filter cannot connect, the Filter Graph Manager discards it and tries another filter. This process continues until every stream is rendered.

如果简单播放一个标准格式的文件，那么使用 RenderFile 方法。

RenderFile 函数首先在注册表中找到一个能解析文件的 source filter ，通过协议，文件扩展名或者文件头决定 source filter 。详细的信息参见 Registering a Custom File Type 。

为了生成 graph 的剩余部分， Filter Graph Manager 使用一个迭代过程， Filter Graph Manager 携带了媒体类型，这个媒体类型是 filter 输出 pin 上所支持的媒体类型，并在注册表中搜索以此媒体类型作为输入的 filter 。

filter 种类定义 filter 的一般功能。

媒体类型描述 filter 接收哪种数据作为输入或传递给输出。

性能决定 filter 被尝试的顺序。如果两个 filter 在同一个种类中且支持相同的输入类型， Filter Graph Manager 将选择性能值最高的。

Filter Graph Manager 使用 Filter Mapper 对象查询注册表。

每添加一个 filter ， Filter Graph Manager 都会尝试把它和之前的 filter 输出 pin 进行连接。 filter 协商决定他们是否连接。如果新加入的 filter 不能连接， Filter Graph Manager 丢掉它，然后尝试其他的 filter 。这个过程一直持续，知道每一个流都演示。

To do something beyond simply playing a file, your application must perform at least some of the graph building work. For example, a video capture application must select a capture source filter and add it to the graph. If you are writing data to an AVI file, you must add the AVI Mux and File Writer filters to the graph. However, it is often possible to let the Filter Graph Manager complete the graph. For example, you can render a pin for preview by calling the Render method.

要在播放一个简单的文件之前做一些事情，应用程序必须至少执行生成 graph 工作。例如，视频采集应用程序必须选择视频采集源然后把源添加到 graph 中。如果正在写数据到 AVI 文件，就必须添加 AVI Mux 和 File Writer filter 到 graph 。

In some scenarios, your application may need to build the graph by adding and connecting each filter. In this case, you probably know specifically which filters should be added to the graph. With this approach, the application adds each filter by calling AddFilter, enumerates the pins on the filters, and connects them by calling either Connect or ConnectDirect.

有的程序中，应用程序需要添加和连接每一个 filter 来生成 graph 。在这种情况下，你大概知道哪些特殊的 filter 会被加到 graph 中。应用程序通过调用 AddFilter 添加每一个 filter ，枚举 filter 上的 pin ，调用 Connect 或者 ConnectDirect 来连接这些 pin 。