Index
|
|
|
|
|
| |||
| |||
Summary of DirectShow COM Interfaces
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.
- Filter Graph Manager Interfaces
- Filter and Pin Interfaces
- Media Sample and Enumerator Interfaces
- Control Interfaces
The DirectShow COM interfaces can be categorized as follows:
- Filter graph manager interfaces, which are fully implemented and used by applications to create, connect, and control filter graphs and by filters within the filter graph to post event notifications and to force reconnections when needed.
- Filter and pin interfaces, which must be implemented by the filter. They comprise the methods exposed by filters for communicating with the filter graph manager, connecting with other filters, passing data downstream (from source filter to renderer filter) and passing quality control and media positioning information upstream (from renderer to source).
- Enumerator and media sample interfaces, which are interfaces on objects created temporarily for passing information.
- Control interfaces, which are exposed by filters and the filter graph manager to enable the starting, stopping, and positioning of media in the stream. The control interfaces on the filters must be implemented when writing a filter, whereas they are already implemented on the filter graph manager.
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 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. IDeferredCommand The application that sent a deferred command using IQueueCommand. Retrieve 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. IEnumFilters Application or possibly a filter that needs to know what other filters are in the graph. Retrieve filters, skip filters, or clone the enumerator. Implemented in the filter graph manager. IEnumRegFilters Filter mapper. Retrieve filters, skip items, or clone the enumerator. Implemented by the filter graph manager. IFilterGraph Not usually called directly. Add, connect, and reconnect filters in a filter graph. Use IGraphBuilder instead, because it inherits from this interface. IFilterGraph2 C or C++ applications. Extend filter graph functionality. IFilterInfo An Automation client such as Visual Basic. Retrieve 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. IGraphBuilder Application. Create filter graphs dynamically from stream media type or re-create 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. Retrieve the current filter graph version and determine when a filter graph has had filters added, deleted, or reconnected. IMediaControl Application. Run, pause, and stop the filter graph, and retrieve 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. IMediaTypeInfo An Automation client such as Visual Basic. Retrieve the major and minor media types. Implemented by the filter graph manager. Not used by C or C++ applications. IPinInfo An Automation client such as Visual Basic. Retrieve 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. IQueueCommand Application needing 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. IRegFilterInfo An Automation client such as Visual Basic. Retrieve a filter name and add it to the filter graph. Implemented by the filter graph manager. Not used by C or C++ applications. ISeekingPassThru Applications. Instantiate and initialize a CRendererPosPassThru object. You can use this object to keep track of reference times and stream times. Implemented on video renderer filters that need to keep track of reference time and stream time. 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 IAMovieSetup Entry-point routines in Dllentry.cpp. 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. 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. 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. IPersist Filter graph manager when loading preconfigured filter graph files. Retrieve the filter's class identifier. Inherited by IBaseFilter along with IMediaFilter. IUnknown Filter graph manager. Retrieve a pointer to the interface, add and delete references to the interface. Implemented by the CUnknown base class. 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 IAMCrossbar C or C++ applications. Route messages from an analog or digital audio or video source to a video capture filter. Exposed on analog video crossbar filters. IAMExtDevice C or C++ applications. Control external devices. IAMExtTransport C or C++ applications. Control specific behaviors of an external VCR. IAMTimecodeDisplay C or C++ applications. Define behavior of an external SMPTE/MIDI timecode display device. IAMTimecodeGenerator C or C++ applications. Specify how an external SMPTE/MIDI timecode generator should supply data to the filter graph, and the formats in which timecode should be supplied. IAMTimecodeReader C or C++ applications. Specify the timecode format that an external device should read and how it is embedded in the media. IAMTVTuner C or C++ applications. Enables applications to set TV transmission types. IAMVideoProcAmp C or C++ applications. Control video quality settings. Exposed on WDM video capture filters. IAsyncReader Downstream parser filter. Perform synchronized reads, request data, request allocator, begin and end flushing, and retrieve file's total length. Implemented on the Async Sample (Asynchronous Reader Filter), which reads media types with a major type of MEDIATYPE_Stream. 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, palette values, and the current image. Usually implemented on a video renderer filter. Supports Automation. ICreateDevEnum C or C++ applications. Enumerate hardware devices. IDirectDrawVideo C or C++ applications. Set and retrieve DirectDraw® hardware and emulated capabilities and surface types. Usually implemented on a video renderer filter. 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. IFileSinkFilter2 C or C++ applications. Set or retrieve the file name, optionally overwriting an existing file. 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. IFullScreenVideo C or C++ applications. Set and retrieve full-screen modes, message drain, icon caption, and other information. Usually implemented on a video renderer filter. IMediaPropertyBag C or C++ applications. Expose copyright information on filters. IMediaSample2 Filters. Expose sample properties. IOverlay Filters upstream from the renderer that need to be notified of window changes. Set and retrieve palette and color key information; get window handle, clip list, window position; set up advise link with upstream filter. Usually implemented on a video renderer filter. 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. 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. IReferenceClock Filters that need to be synchronous with a reference clock. Register for time notifications from the filter, convert real to reference time, and retrieve 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. IVideoWindow Applications and Automation clients such as Visual Basic. Control the window aspects of a video renderer. Usually implemented on a video renderer filter. DirectShow provides filters that implement particular interfaces for you. Applications typically use those interfaces, but filters do so as well.
Interface What calls methods What methods do Comments IAMDirectSound DirectSound audio renderer. Set and retrieve the window that will handle the sound playback. 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. IAMStreamSelect Applications. Control which logical streams are played and retrieve information about them. The MPEG splitter 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. IAMAudioCutListElement Applications and filters. Provide support for a cutlist element for an audio file stream in a WAV or AVI file. The CLSID_AudioFileClip object 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. IAMCutListElement Filters. Describe a base object, which represents an element in a cutlist. DirectShow provides the CLSID_VideoFileClip and CLSID_AudioFileClip objects, which can create an object that implements it for you. ICutListGraphBuilder Applications. Enable you to easily implement one or more cutlist filter graphs. IDvdControl Applications. Control playback and searching on DVD discs. DVD navigator filter implements this interface. IDvdGraphBuilder Applications. Simplify 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. IFileClip Applications. Provide a simple way for an application to create one or more cuts from a single media file, or to create blank cuts. IAMFileCutListElement Filters. Provide support for a cutlist element for a file stream. DirectShow provides the CLSID_VideoFileClip and CLSID_AudioFileClip objects that implement it for you. IStandardCutList Applications. Provide a simple way for an application to feed a cutlist into a cutlist provider (filter). IAMVideoCutListElement Filters. Provide support for a cutlist element from an AVI video file stream. DirectShow provides the CLSID_VideoFileClip object that implements it for you. IVPBaseConfig Video port mixer filter. Enable a video port (VP) mixer filter to communicate with a VP driver. Ksproxy filter implements this interface. IVPBaseNotify Applications. Control properties of a filter that uses a video port. Video port mixer filter implements this interface. IVPConfig Video port mixer filter. Enable a video port (VP) mixer filter to communicate with a VP driver. Ksproxy filter implements this interface. IVPNotify, IVPNotify2 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 usually 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, usually 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 IAMAudioInputMixer Applications. Adjust audio input characteristics. Input pin of an audio capture filter typically implements this interface. IAMBufferNegotiation Applications. Set and retrieve buffer properties. The IAMBufferNegotiation interface informs a pin what kind of buffer specifications it should use when connected. IAMDevMemoryAllocator Applications. Provide creation of third-party memory allocators. Makes use of on-board memory manager objects. IAMDevMemoryControl Applications. Control and identify on-board codec memory. This interface is supported by a device memory control object. IAMDroppedFrames Applications. Provide information about the number of dropped frames, frame rate, and data rate. Capture filter's video output pin should implement this interface. IAMStreamConfig Applications or filters. Provide types of formats an output pin can connect with. Output pins of capture and compression filters typically implement this interface. IAMStreamControl Applications. Enable 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. Sets and retrieves device properties. Expose device properties and enable an application or filter to change the properties. 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. 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 usually created by IMemInputPin. Implemented by the CMemAllocator class. IMemInputPin Filter graph manager, output pin of a connected filter. Retrieve a preferred allocator, receive the allocator provided by output pin, receive media samples, and tell whether the pin will block on receive. Usually only on input pins. Implemented by the CBaseInputPin base class. IPin Filter graph manager, other pins, the owning filter. Connect and disconnect the pin, retrieve information on external and internal pin connections, retrieve preferred media types enumerator, negotiate preferred media types, receive flush and end-of-stream notifications. Implemented on all pins by the CBasePin base 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. IUnknown Filter graph manager, other pins, the owning filter. Retrieve a pointer to the interface, add and delete references to the interface. Implemented on all pins by the CUnknown base class. 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 IMediaSample Pins or filters that need to manipulate the media sample data or examine its properties. Retrieve 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. IUnknown Pin or filter. Retrieve pointer to the interface, add and delete references to the interface. Implemented on media samples by the CUnknown 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 IEnumFilters Application or possibly a filter that needs to know what other filters are in the graph. Retrieve filters, skip filters, or clone the enumerator. Implemented in the filter graph manager. IEnumMediaTypes Filter graph manager or connected pin negotiating a media type. Retrieve media types, skip media types, or clone the enumerator. Implemented by the CEnumMediaTypes class. IEnumPins Filter graph manager. Retrieve pins, skip pins, or clone the enumerator. Implemented by the CEnumPins class. IEnumRegFilters Filter mapper. Retrieve 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 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. IMediaControl Application. Run, pause, and stop the filter graph, and retrieve the state. Implemented by the filter graph manager. 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. 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 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 on filters. Because DirectShow objects are COM-based objects, it is a natural extension to use other COM interfaces published in the COM specifications to perform functions such as listing property pages or accessing files. Following are some of the COM 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 COM 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 COM 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.
- IMediaPosition supports the ability to seek to a position and change the rate.
- IBasicAudio supports the ability to set the volume.
- IBaseFilter supports such methods as Run and Pause (methods on the filter graph manager's IMediaControl interface).
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.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.