| Microsoft DirectX 8.1 (C++) |
All Microsoft® DirectShow® filters are user mode software components. For a kernel mode hardware device such as a capture card, TV Tuner, hardware decoder, or sound card to join a DirectShow filter graph, the device must be represented as a user mode filter in the filter graph. This function is performed for various types of devices by specialized "wrapper filters" provided with DirectShow. These filters include the Audio Capture filter, the VFW Capture filter, the TV Tuner filter, the Analog Video Crossbar filter, and the TV Audio filter. In addition to these wrapper filters, DirectShow also provides the KsProxy filter, which can represent any type of Windows Driver Model® (WDM) streaming device and which can be extended by independent hardware vendors (IHVs) to support custom functionality. This is done by means of a Ksproxy plug-in, which is a COM object that is aggregated by KsProxy.
The wrapper filters work by supporting COM interfaces that represent the expected capabilities of the device. The application uses these interfaces to pass information to and from the filter, the filter translates the interface calls into information the device driver can understand, and then the filter passes that information to and from the driver in kernel mode. (KsProxy works in a similar manner, although the interfaces it exposes to the filter graph vary depending on the device it is representing.) For filters such as the VfW Capture Filter and Audio Capture filter, the interfaces are non-extensible. The TV Tuner filter and Analog Video Crossbar and TV Audio filters, although not based on KsProxy, support the IKSPropertySet interface, which is a generic way of handling custom property sets through a single interface.
For application developers, the principle of wrapping hardware devices as user mode filters means that applications control devices in the same way they control any other DirectShow filter. No special programming is required on the part of the application; all the details involved in communicating with the kernel mode device are encapsulated within the filter itself.
To support earlier Video for Windows (VfW) capture cards, DirectShow provides the VFW Capture Filter. When a VfW card is present on the target system, it can be discovered using the DirectShow System Device Enumerator. The Enumerator is also used to add the VfW Capture Filter to the graph and associate it with the card that was found. The rest of the filter graph can then be constructed in the usual ways. See Enumerating Devices and Filters for more details.
Newer sound cards have input jacks for microphones and other types of devices. These cards also typically have on-board mixing capabilities for controlling the volume, treble, and bass of each individual input. In DirectShow, the sound card's inputs and mixer are wrapped in the Audio Capture filter. Each sound card in the local system can be discovered with the System Device Enumerator as described in Enumerating Devices and Filters. To view the sound cards in your system, open open the GraphEdit utility program that installs with the SDK and select from the Audio Capture Sources category. Each filter represented here is a separate instance of the Audio Capture filter.
Newer hardware decoders and capture cards conform to the Windows Driver Model (WDM) specification. These devices have greater functionality compared to VfW devices and are portable between Windows NT/Windows 2000 and Windows 98/Me. WDM video capture cards are capable of supporting features not available under VfW, including capture format enumeration, programmatic control of video parameters (such as hue/brightness), programmatic input selection, TV Tuner support, and VBI support.
To support WDM streaming devices, DirectShow provides a filter called KsProxy (ksproxy.ax). KsProxy has been called the "Swiss Army Knife filter" because it does so many different things. It has also been called the "chameleon filter" because the number of pins and interfaces supported on the filter as a whole and on individual pins depends on the capabilities of the underlying kernel mode driver. It never appears in a filter graph by the name "KsProxy." It always takes the "friendly" name of the device that it finds in the registry. (This name is originally specified in the driver's .inf file.) If you have a WDM device on your system, you can open the GraphEdit utility program, click Graph, select Insert Filters, and scroll down to the WDM Streaming devices nodes. Even if you have only one WDM card on your system, that card might contain more than one device. Each device is represented as a separate filter, and each of these filters is actually KsProxy.
When an application uses the System Device Enumerator to programmatically find a WDM device moniker on the target system; for example, a TV Tuning card, KsProxy (using a "friendly name" provided by the driver) is instantiated in the subsequent call to the BindToObject method. Because KsProxy can represent all kinds of WDM audio or video devices and does not know in advance what kind of device it will be representing, it must query the driver to see which property sets are supported. Property sets are collections of data structures used by WDM Stream Class drivers as well as some user mode filters such as MPEG-2 software decoders. KsProxy then configures itself dynamically to expose the appropriate interfaces to the filter graph and the application. When applications and other filters call into these interfaces, KsProxy translates the method parameters into property sets and sends these to the driver. IHVs can extend KsProxy by supplying plug-ins, which are vendor-specific interfaces that expose the special capabilities of a device. All these details are hidden from applications; the application controls and receives events from the WDM device, by way of KsProxy, in the same way as any other DirectShow user mode filter.
WDM devices support the kernel streaming model by which data can be streamed entirely in kernel mode without ever having to transition to user mode. Passing between kernel mode and user mode is a computationally expensive operation; kernel streaming provides the benefit of high bitrates without burdening the host CPU. WDM-based filters can use kernel streaming to pass multimedia data directly from one hardware device to another (either on the same card or on a different card) without ever copying the data into the system's main memory.
From an application's point of view, it appears as if the multimedia data in the graph is moving from one user mode filter to the next. In reality, the data might never pass into user mode at all, but is streamed directly from one kernel mode device to another until it is rendered on the video graphics card. Of course, in some scenarios, such as capture to a file, the data must actually pass from kernel mode to user mode at some point in the filter graph, but transfer to user mode access does not necessarily require that the data be copied to a new location in memory. Applications can take explicit control when building capture graphs to make sure the data follows a desired path, either from one hardware device to another, or from a hardware device to a user mode filter. See the sections on Video Capture for more information.
Application developers generally do not need to be concerned with the details of kernel streaming, except as background information. See the Microsoft DDK for more detailed documentation on WDM, kernel streaming, KsProxy, and related topics.