This article groups the Microsoft® DirectShow™ interfaces according to the objects that expose them. It explains which object implements each interface and who is likely to call the interface methods implemented on each type of object. The information is presented as a series of tables of COM interfaces relating to each object, and so provides a summary and quick reference for understanding the DirectShow interfaces.
Contents of this article:
Introducing the DirectShow COM Interfaces
The DirectShow COM interfaces comprise the schematic of an architecture for streaming time-stamped media. The filter graph, through which media flows, is composed of objects, such as filters, pins, media samples, allocators, and enumerators, that work together. COM interfaces are implemented on these objects and are called by other objects with which they interact. The filter is the only filter graph COM object that has a CLSID; all other objects in the filter graph support COM interfaces, and are created as needed by the filter. Filters and their supporting object must implement their COM interfaces and a class library is available for help in that task. The filter graph manager, on the other hand, has a CLSID and supports several fully implemented interfaces, as do plug-in distributors, which are aggregated by the filter graph manager. (Microsoft-provided plug-in distributors are referred to as the filter graph manager in this article.)
This section contains the following topics.
The DirectShow COM interfaces can be categorized as follows:
Filter Graph Manager Interfaces
Most filter graph manager interfaces fall in the category of control interfaces, also listed separately in this article; however, some are unique to the filter graph manager.
Interface | What calls methods | What methods do | Comments |
IFilterGraph | Not normally called directly. | Add, connect, and reconnect filters in a filter graph. | Use IGraphBuilder instead, since it inherits from this interface. |
IGraphBuilder | Application. | Create filter graphs dynamically from stream media type or recreate stored filter graph. | Inherits from IFilterGraph. Also uses a filter mapper object to look up filters in the registry. |
IGraphVersion | Application and plug-in distributors in the filter graph manager. | Return the current filter graph version. | Determine when a filter graph has had filters added, deleted, or reconnected. |
IEnumFilters | Application or possibly a filter that wants to know what other filters are in the graph. | Return filters, skip filters, or clone the enumerator. | Implemented in the filter graph manager. |
IEnumRegFilters | Filter mapper. | Return filters, skip items, or clone the enumerator. | Implemented by the filter graph manager. |
IMediaControl | Application. | Run, pause, and stop the filter graph, and return the state. | Has many of the same methods as the IMediaFilter interface, which is implemented on filters. |
IMediaEvent | Applications that need to retrieve events passed to the filter graph manager from filters. | Get events, get event handles, block until completion, and block or unblock default handling of events by the filter graph manager. | Implemented by the filter graph manager. |
IMediaEventSink | Filters that need to pass events to the application. | Receive event notifications from filters. | Implemented by the filter graph manager. |
IMediaPosition | Applications. | Get duration and position properties, and get and set start time, stop time, preroll time, and rate properties. | Implemented on the filter graph manager and also on filters. |
IMediaSeeking | Applications. | Set and retrieve current position and stop position in units other than time (such as sample or field). | Implemented on the filter graph manager and also on filters. |
IQueueCommand | Application wanting to send a deferred command. | Cue commands to run at stream time (offset from start) or presentation time. | Implemented by the filter graph manager and used by applications. Filters can implement this. |
IDeferredCommand | The application that sent a deferred command using IQueueCommand. | Return confidence information, postpone, or cancel a deferred command, and return HRESULT values from an invoked command. | Implemented by the filter graph manager and returned to any application that calls IQueueCommand methods. |
IAMCollection | An Automation client such as Microsoft® Visual Basic®. | Retrieve the number of items in the collection and retrieve an indexed item. | Implemented by the filter graph manager. Not used by C or C++ applications. |
IRegFilterInfo | An Automation client such as Visual Basic. | Return a filter name and add it to the filter graph. | Implemented by the filter graph manager. Not used by C or C++ applications. |
IFilterInfo | An Automation client such as Visual Basic. | Return name, vendor information, IBaseFilter interface, file name (for source filters), specified pin object, or collection of associated pin objects. | Implemented by the filter graph manager. Not used by C or C++ applications. |
IPinInfo | An Automation client such as Visual Basic. | Return pin information such as name, direction, connections, and collection of associated media type objects. Also includes methods to connect and disconnect pins. | Implemented by the filter graph manager. Not used by C or C++ applications. |
IMediaTypeInfo | An Automation client such as Visual Basic. | Return the major and minor media types. | Implemented by the filter graph manager. Not used by C or C++ applications. |
IFilterGraph2 | C or C++ applications. | Extended filter graph functionality. |
Filter and Pin Interfaces
Filters are composed of one filter object and one or more pin objects. Although only the IUnknown and IBaseFilter interfaces are strictly required on a filter, filters can support other filter and pin interfaces, as discussed in Filter Interfaces.
This topic contains the following subtopics.
Filter Interfaces
The following interfaces are exposed by filter objects in order to be integrated with the filter graph manager. The filter is the main COM object and has a class ID (CLSID) and name registered in the registry. Filters must provide access to their pins and otherwise communicate with the filter graph. They must also allow the filter graph manager to manage the data flow by accepting state change messages.
Interface | What calls methods | What methods do | Comments |
IUnknown | Filter graph manager. | Return a pointer to the interface, add and delete references to the interface. | Implemented by the CUnknown base class. |
IPersist | Filter graph manager. | Return the class identifier (CLSID) of the filter for saving the filter as part of a stored filter graph. | Implemented by the CBaseFilter base class. |
IMediaFilter | Nothing directly. | Put the filter in run, stop, or pause state, get and set the reference clock and retrieve the filter state. | Inherited by the IBaseFilter interface, which should be used instead of referencing this directly. |
IBaseFilter | Filter graph manager. | Same as IMediaFilter plus enumerate pins, retrieve filter and vendor information, and locate pins when rebuilding a persistent filter graph. | Inherits methods from the IMediaFilter interface. Implemented by the CBaseFilter class. |
IPersist | Filter graph manager when loading preconfigured filter graph files. | Has one method that is used to retrieve the class identifier of the filter. | Inherited by IBaseFilter along with IMediaFilter.
|
IAMovieSetup | Entry-point routines in Dllentry.cpp. | Two methods that register and unregister the object. | This is implemented by the base classes for most of what is required to make a filter self-registerable. Need to override one base member function to provide setup structures.
|
The following additional filter interfaces can be exposed by filters such as source filters, and by video and audio renderers. Source filters are notified by means of a quality control mechanism so that they can adjust the amount of data introduced to the stream according to the renderer's performance. Audio renderers are usually called upon to provide a reference clock, since audio hardware generates this. The video renderer filter supplied by Microsoft exposes interfaces to handle both the video window and the transferring of video frames into video buffers.
Interface | What calls methods | What methods do | Comments |
IAsyncReader | Downstream parser filter. | Perform synchronized reads, request data, request allocator, begin and end flushing and retrieve file's total length. | Implemented on the Asynchronous Reader Filter, which reads media types with a major type of MEDIATYPE_Stream.
|
IFileSourceFilter | Any application that needs to set the name of the file into which the file sink filter will write. | Set or retrieve the file name. | Implemented on any source filter that needs a file name from the user.
|
IFileSinkFilter | Any application that needs to set the name of the file from which the file source filter will read. | Set or retrieve the file name. | Implemented on a file writer filter, as used in a video capture filter graph.
|
IQualityControl | Filter graph manager, upstream filter, or pin. | Receive a quality message and receive the quality sink location. | Normally implemented on filters that can affect the quality when they receive the message. |
IReferenceClock | Filters that need to be synchronous with a reference clock. | Register for time notifications from the filter, convert real to reference time, and return the current time. | Implemented on a filter that can generate a reference clock, typically an audio renderer. Provides services similar to the timeBeginPeriod and timeSetEvent Win32® functions. |
IBasicAudio | Applications and Automation clients such as Visual Basic. | Get and set the properties of the audio renderer filter. | Can be implemented on an audio renderer filter.
Supports Automation. |
IBasicVideo | Applications and Automation clients such as Visual Basic. | Get and set the source video rectangle, and retrieve video size and palette values as well as the current image. | Normally implemented on a video renderer filter.
Supports Automation. |
IVideoWindow | Applications and Automation clients such as Visual Basic. | Control the window aspects of a video renderer. | Normally implemented on a video renderer filter. |
IDirectDrawVideo | C or C++ applications. | Set and retrieve DirectDraw® hardware and emulated capabilities and surface types. | Normally implemented on a video renderer filter. |
IFullScreenVideo | C or C++ applications. | Set and retrieve full-screen modes, message drain, icon caption and other information. | Normally implemented on a video renderer filter. |
IOverlay | Filters upstream from the renderer that want to be notified of window changes. | Set and retrieve palette and color key information; get window handle, clip list, window position; setup advise link with upstream filter. | Normally implemented on a video renderer filter. |
IQualProp | Property page objects. | Retrieve rendering quality properties of the video renderer such as the number of frames drawn, jitter, and so on. | Supports Automation.
|
IAMCrossbar | C or C++ applications. | Crossbar functionality. | |
IAMExtDevice | C or C++ applications. | Device control. | |
IAMExtTransport | C or C++ applications. | Device control. | |
IAMTimecodeDisplay | C or C++ applications. | Time codes. | |
IAMTimecodeGenerator | C or C++ applications. | Time codes. | |
IAMTimecodeReader | C or C++ applications. | Time codes. | |
IAMTVTuner | C or C++ applications. | TV Tuner. | |
ICreateDevEnum | C or C++ applications. | Enumeration of hardware devices. | |
IFileSinkFilter2 | C or C++ applications. | Options for file writer filters. | |
IMediaPropertyBag | C or C++ applications. | Copy right information. | |
IMediaSample2 | Filters. | Exposes sample properties. |
DirectShow provides filters that implement particular interfaces for you. Applications typically use those interfaces.
Interface | What calls methods | What methods do | Comments |
IAMDirectSound | DirectSound audio renderer. | Provides access to DirectSound buffers. | DirectSound audio renderer implements and uses this interface.
|
IAMLine21Decoder | Applications or video mixer filter. | Provide access to closed caption settings. | Line21 decoder implements this interface.
|
IAMVfwCaptureDialogs | Applications. | Provide access to dialog boxes exposed by Video for Windows capture drivers. | Video for Windows capture filter implements this interface.
|
IAMVfwCompressDialogs | Applications. | Provide access to dialog boxes exposed by Video for Windows compressors. | Video for Windows installable compression manager (ICM) filter implements this interface.
|
ICaptureGraphBuilder | Applications. | Simplify building capture filter graphs. | Capture graph builder object implements this interface.
|
IConfigAviMux | Applications. | Control how the AVI multiplexer filter writes files to disk. | AVI multiplexer filter implements this interface on its property page.
|
IConfigInterleaving | Applications. | Control how the AVI multiplexer filter writes files to disk and set interleaving configuration information | AVI multiplexer filter implements this interface on its property page.
|
IDvdControl | Applications. | Control playback and searching on DVD discs. | DVD navigator filter implements this interface.
|
IDvdGraphBuilder | Applications. | Simplifies building DVD filter graphs. | DVD graph builder object implements this interface.
|
IDvdInfo | Applications. | Query for DVD attributes and DVD player status. | DVD navigator filter implements this interface.
|
IVPConfig | Video port mixer filter. | Allow a video port (VP) mixer filter to communicate with a VP driver. | Ksproxy filter implements this interface.
|
IVPNotify | Applications. | Control properties of a filter that uses a video port. | Video port mixer filter implements this interface.
|
Pin Interfaces
Pin objects expose these interfaces. Pins do not normally have registered class identifiers and are usually created by the filter object on which they reside. They are exposed externally by the filter, which includes a method (IBaseFilter::EnumPins) to hand out pointers to the IPin interfaces of its pins, normally to the filter graph manager. The filter graph manager is responsible for connecting pins by calling an IPin method on one of the pins with a pointer to the other pin. Once pins are connected, each pin holds a pointer to the pin to which it is connected.
Interface | What calls methods | What methods do | Comments |
IUnknown | Filter graph manager, other pins, the owning filter. | Return a pointer to the interface, add and delete references to the interface. | Implemented on all pins by the CUnknown base class. |
IPin | Filter graph manager, other pins, the owning filter. | Connect and disconnect the pin, return information on external and internal pin connections, return preferred media types enumerator, negotiate preferred media types, receive flush and end-of-stream notifications. | Implemented on all pins by the CBasePin base class. |
IMemInputPin | Filter graph manager, output pin of a connected filter. | Return a preferred allocator, receive the allocator provided by output pin, receive media samples, and tell whether the pin will block on receive. | Normally only on input pins. Implemented by the CBaseInputPin base class. |
IMemAllocator | Owning filter and output pin of connected filter. | Allocate one or more buffers based on required size, retrieve a buffer for a media sample, commit memory when in use, and release it (decommit) when not in use. | Appears on allocator object normally created by IMemInputPin. Implemented by CMemAllocator class. |
IQualityControl | Downstream filter or pin on downstream filter. | Receive a quality message and receive the quality sink to send quality messages to. | Implemented on output pins by the CBaseOutputPin base class, where it is used to pass the message upstream. |
IMediaPosition | Filter graph manager or downstream filter. | Get duration and position properties, and get and set start time, stop time, preroll time, and rate properties. | Downstream filters call methods on output pins supporting this to pass a requested media position upstream. Implemented in CPosPassThru on pins. |
IMediaSeeking | Applications. | Set and retrieve current position and stop position in units other than time (such as sample or field). | Downstream filters call methods on output pins supporting this to pass a requested media position upstream. Implemented in CPosPassThru on pins. |
IAMAudioInputMixer | Applications. | Adjust audio input characteristics. | Input pin of an audio capture filter typically implements this interface.
|
IAMBufferNegotiation | Applications. | Set and retrieve buffer properties. | |
IAMDevMemoryAllocator | Applications. | Provide creation of third-party memory allocators. | |
IAMDevMemoryControl | Applications. | Control and identify on-board codec memory. | |
IAMDroppedFrames | Applications. | Provide information about the number of dropped frames, frame rate, and data rate. | Capture filters video output pin should implement this interface.
|
IAMStreamConfig | Applications or filters. | Provide types of formats an output pin can be connected with. | Output pins of capture and compression filter typically implement this interface.
|
IAMStreamControl | Applications. | Allow control of streams in a filter graph. | Implemented by any input or output pins.
|
IAMVideoCompression | Applications. | Control compression parameters that aren't part of the media type. | Output pin of a video capture or compression filter typically implements this interface.
|
IKsPropertySet | Applications or filters. | Expose device properties and allow an application or filter to change the properties. |
In addition, the Microsoft video renderer's input pin supports the IOverlay interface, which allows the connected upstream pin to effectively register its IOverlayNotify interface in order to receive notifications of video window changes. Replacement video renderers can also implement this if they are intended to connect to the same filters as the video renderer provided with DirectShow.
Media Sample and Enumerator Interfaces
Media sample and enumerator interfaces are temporary objects created to pass information or data between objects. They do not have class identifiers.
This topic contains the following subtopics.
Media Sample Interfaces
The media sample interface, IMediaSample, is created from the memory allocator, which uses the media sample object as its unit of exchange. It has no class identifier. It is the unit of media data that is passed from one filter to the next via the memory allocator shared by two connected pins.
Interface | What calls methods | What methods do | Comments |
IUnknown | Pin or filter. | Return pointer to the interface, add and delete references to the interface. | Implemented on media samples by the CUnknown base class. |
IMediaSample | Pins or filters that need to manipulate the media sample data or examine its properties. | Return a pointer to data, and get and set properties on the media sample such as buffer size, time stamp, data length, type, synchronization point, preroll, and end-of-stream properties. | Implemented on media samples by the CMediaSample base class. |
Enumerator Interfaces
Enumerators in DirectShow are based on the COM IEnumXXXX interfaces. They include the Next and Prev methods, which tell the enumerator what item or items to return; the Skip method, which skips one or more items; and the Clone method, which makes a copy of the enumerator. Enumerators are used to present lists of items such as filters in a filter graph, pins on a filter, or media types that are preferred by a pin.
Interface | What calls methods | What methods do | Comments |
IEnumPins | Filter graph manager. | Return pins, skip pins, or clone the enumerator. | Implemented by the CEnumPins class. |
IEnumMediaTypes | Filter graph manager or connected pin negotiating a media type. | Return media types, skip media types, or clone the enumerator. | Implemented by the CEnumMediaTypes class. |
IEnumFilters | Application or possibly a filter that wants to know what other filters are in the graph. | Return filters, skip filters, or clone the enumerator. | Implemented in the filter graph manager. |
IEnumRegFilters | Filter mapper. | Return filters, skip items, or clone the enumerator. | Implemented by the filter graph manager. |
Control Interfaces
Control interfaces allow the filter graph manager to coordinate the activities of the data stream with filters. Interfaces described previously in both the Filter Graph Manager Interfaces and Filter and Pin Interfaces sections are repeated here so that all control interfaces can be viewed together.
Interface | What calls methods | What methods do | Comments |
IMediaControl | Application. | Run, pause, and stop the filter graph, and return the state. | Implemented by the filter graph manager. |
IMediaPosition | Application, when exposed on the filter graph manager; filter graph manager or downstream filter, when exposed on a filter. | Get duration and position properties, and get and set start time, stop time, preroll time, and rate properties. | Implemented on the filter graph manager and also on filters. |
IMediaSeeking | Applications. | Set and retrieve current position and stop position in units other than time (such as sample or field). | Implemented on the filter graph manager and also on filters. |
IMediaFilter | Nothing directly. | Put the filter in run, stop, or pause state, get and set the reference clock and retrieve the filter state. | Inherited by IBaseFilter, which should be used instead of referencing this directly. |
IBaseFilter | Filter graph manager. | Same as IMediaFilter plus enumerate pins, retrieve filter and vendor information and locate pins when rebuilding a persistent filter graph. | Inherits methods from the IMediaFilter interface. Implemented by the CBaseFilter class. |
Because DirectShow objects are COM-based objects, it is a natural extension to use other COM interfaces published in the OLE specifications to perform functions such as listing property pages or accessing files. Following are some of the OLE interfaces that are commonly used in DirectShow filters.
Interfaces on a Typical Filter Graph
Perhaps the best way to put the DirectShow interfaces into perspective is to look at the interfaces exposed in a simple filter graph. The example chosen here is a filter graph that plays back audio data stored on a disk. It is composed of a source filter and an audio renderer filter (no transforms are done, so this is a very simple graph).
The basic source filter consists of an IBaseFilter interface, and one output pin that can be found by using the IBaseFilter::EnumPins method. The OLE IPersist interface might also be present on the filter (not shown here) to enable the filter to be stored as part of a persistent filter graph.
The output pin supports IPin and IMediaPosition, since the source filter is a seekable filter (that is, it can be told to move to a particular position in the media stream). The following illustration shows the interfaces on the source filter and its output pin.
Note that quality management is not implemented in this example, but could be by including the IQualityControl interface on the output pin as well.
The basic renderer filter consists of a COM driver supporting the IBaseFilter (and, again, IMediaFilter by inheritance) and IMediaPosition interfaces, as well as having one input pin through the EnumPins method of the IBaseFilter interface. The OLE IPersistFile interface might also be present on the filter (not shown here) in order load the file. The renderer can support additional interfaces, such as IReferenceClock (as a master for synchronization) or IBasicAudio, for an audio renderer as shown here.
The input pin supports the IPin and IMemInputPin interfaces. Methods of the IMediaPosition interface on the renderer filter can call the IMediaPosition interface methods of the output pin that is connected to the renderer's input pin.
A basic representation of the connection of a source filter to a renderer filter follows:
Once the pins are enumerated and connected, it is the implementation of the output and input pins that defines the interactions of the two pins.
Once the filters are connected, the control available to the user (filter graph manager) is indicated through the bold interfaces. This continues with the example of connecting an audio source to an audio renderer.
The following interfaces are those that would likely be used during a transport.
Special (custom) interfaces that the filters would support must be obtained directly from the filters. Usage of these interfaces implies that the user is aware of their identifiers.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.