Microsoft DirectX 8.1 (C++)

Intelligent Connect

Intelligent Connect is the mechanism that the Filter Graph Manager uses to build filter graphs. It consists of several related methods, including IGraphBuilder::RenderFile, IGraphBuilder::Render, and IGraphBuilder::Connect. These methods all use similar algorithms to select filters and add them to the filter graph. This section describes those algorithms.

For application programming, you rarely need to know the details of Intelligent Connect. Read this section if you are having trouble building a certain filter graph and want to troubleshoot the problem, or if you are writing your own filter and want to make it available for automatic graph building.

The RenderFile Method

The RenderFile method builds a default playback graph from a file name. It starts by locating the correct source filter. To do so, it looks in the registry and matches against the file extension or against predetermined check bytes, which are bytes at particular offsets in the file that match certain patterns. For details, see Registering a Custom File Type. Assuming the RenderFile method locates a source filter, it creates an instance of the filter, adds it to the graph, and calls the filter’s IFileSourceFilter::Load method with the file name. (The IGraphBuilder::AddSourceFilter method also performs these same steps.

Next, RenderFile tries to build the rest of the graph, starting from the output pin(s) on the source filter and working downstream. At each step, the method searches for a filter that can connect to the previous filter. The stream can branch if a connecting filter has multiple output pins. The search stops when every stream has a renderer. If the RenderFile method gets stuck, it might back up and try again, using a different set of filters. At each step, the Filter Graph Manager tries to locate filters that can connect to a given output pin. The process is recursive, because the new filter might have output pins as well.

The process works as follows:

  1. If the output pin supports the IStreamBuilder interface, the Filter Graph Manager delegates the entire process to the pin's IStreamBuilder::Render method. By exposing this interface, the pin assumes responsibility for building its section of the graph, down to the renderer. However, very few pins support this interface.
  2. The Filter Graph Manager tries any filters that are cached in memory. Throughout the Intelligent Connect process, the Filter Graph Manager may cache filters from earlier steps in the process. (Also, see Dynamic Graph Building.)
  3. If the filter graph contains any filters with unconnected input pins, the Filter Graph Manager tries them next. You can force the Filter Graph Manager to try a particular filter by calling IFilterGraph::AddFilter before calling RenderFile.
  4. Finally, the Filter Graph Manager searches the registry, using the IFilterMapper2::EnumMatchingFilters method. It tries to match the output pin's preferred media types against media types listed in the registry.

Each filter is registered with a merit, which is a numerical value indicating how preferable that filter is, relative to other filters. The EnumMatchingFilters method returns filters in order of merit, with a minimum merit of MERIT_DO_NOT_USE + 1. It ignores filters with a merit of MERIT_DO_NOT_USE or less. For more information, see Merit.

Filters are also grouped into categories, defined by GUID. Categories themselves have merit, and the EnumMatchingFilters method ignores any category with a merit of MERIT_DO_NOT_USE or less, even if the filters in that category have higher merit values. For more information, see Filter Categories.

To summarize, the RenderFile method tries filters in the following order:

  1. Use IStreamBuilder.
  2. Try cached filters.
  3. Try filters in the graph.
  4. Look up filters in the registry.

The Render Method

The IGraphBuilder::Render method builds a subsection of a graph. It starts from an output pin of a filter and works downstream, adding new filters as needed. It uses the same algorithm as the RenderFile method. The starting filter must already be in the graph; call AddFilter if need be.

The Connect Method

The IGraphBuilder::Connect method connects two filters, output pin to input pin. The method adds intermediate filters if needed, using a variation of Intelligent Connect to find the intermediate filters:

  1. Try a direct connection between the filters, with no intermediate filters.
  2. Try cached filters.
  3. Try filters in the graph.
  4. Look up filters in the registry.

You can try each of these methods in GraphEdit. If you choose Render Media File from the File menu, it is equivalent to calling RenderFile. If you right click an output pin and choose Render, it is equivalent to calling Render. If you drag the mouse from an output pin to an input pin, it is equivalent to calling Connect.