Plug-in Distributors

This article describes the plug-in distributor architecture and provides some rules assumed by the default Microsoft® DirectShow™ control distributors.

Contents of this article:

Plug-in Distributors and Extensibility

The filter graph manager exports control interfaces; it also distributes the actions of interface methods to the appropriate filters. For example, the IMediaControl::Run method on the filter graph manager is called by an application to run the filter graph; this command is distributed to the IMediaFilter::Run method of each filter method by the filter graph manager. This distribution allows applications to have a single point of control to perform the basic operations.

To allow the filter graph manager to be extensible, a mechanism known as a plug-in distributor (PID) is used. This is a Component Object Model (COM) object that exposes a particular control interface and implements it by calling the enumerator of the filter graph manager, finding which filters expose the control interface and communicating directly with those filters. PIDs are supplied for the standard control interfaces; independent software vendors (ISVs) can replace these supplied PIDs and also add others.

When the filter graph manager is asked for an interface that it does not recognize, it searches the registry for a PID. This is an unnamed value under the following key.

HKEY_CLASSES_ROOT\Interface\<IID>\Distributor

This value provides the class identifier (CLSID) of an object that can distribute the interface identifier (IID). The filter graph manager then instantiates that object as an aggregated object, specifying the IUnknown implementation of the filter graph manager as the outer IUnknown, and asking for the IID. The object will then be able to use its outer IUnknown pointer to obtain an IFilterGraph interface. With this interface, it can enumerate the filters to implement its control interface methods and properties; it will also be able to use the IMediaControl implementation of the filter graph manager for correctly ordered and synchronized state changes (run, pause, stop, and so on).

Control Distributors

A control distributor is a PID that is used to control the data flow in the filter graph; for example, starting or stopping playback of a media stream. The standard control distributors supplied with DirectShow directly implement their distribution. These distributors make the following assumptions.

Applications that connect filters directly without informing the filter graph manager will get unexpected results if they also use the distributors of the filter graph manager. For example, a deadlock might occur if an application calls a filter's IBaseFilter::Run method directly, because the filter graph manager contains a distributor that implements IMediaControl::Run and passes calls on to each filter's IBaseFilter::Run method.
Properties that can be aggregated directly can be read and written to through the control interface, even when exposed by multiple filters. For example, duration can be reported as the longest of all individual durations, with all streams treated as running in parallel.
Where a property is exposed by several different filters, applications will either use the filter graph manager to set and get the property or will communicate with the individual filters, but will not mix the two methods. An application that communicates with two audio renderers to reset the volume and then queries the IBasicAudio implementation of the filter graph manager for the volume, will get undefined results. (In practice, it will probably retrieve the Volume property of the first audio renderer with no attempt to combine this with the other stream.) If the application sets the property through the interface of the filter graph manager, the same value will be set to all the individual filters that expose it.
The filter graph manager will expose the IMediaControl interface (through a non-replaceable distributor) as the main application method for starting and stopping graphs. This is a slightly higher-level, more simplified interface than IMediaFilter and is suitable for OLE Automation (OA) clients and applications. The IMediaFilter implementation on the filter graph manager should not be called by applications. IMediaControl is implemented by calling the IMediaFilter interface implemented by the filter graph manager and by individual filters. Individual filters expose IMediaFilter through the IBaseFilter interface, which inherits it.

PIDs must keep track of the filters in the filter graph. This is done by implementing the IDistributorNotify interface on the distributor. IDistributorNotify has the same Run, Pause, and Stop methods as IMediaFilter, all of which are called before the calling the filter. It also has a IDistributorNotify::NotifyGraphChange method, which notifies the distributor when any filters are added or removed from the filter graph, or connections change.