Specifying the Topology

After a hardware vendor decides which miniport drivers to write for the wave and MIDI devices, the next step is to represent the kernel streaming (KS) topology of these devices. The KS topology consists of a set of data structures that describe the data paths that audio or MIDI streams follow as they flow through each device. Through this topology, the driver exposes the control nodes (for example, volume control) that lie along each path. Typically, an application uses the Windows multimedia mixerXxx functions to explore the topology by enumerating the sequence of nodes along each path. For example, after discovering a volume-level control node, an application can set the volume level on that node. For more information about Windows multimedia, see the Microsoft Windows SDK documentation. For more information about the representation of KS topologies by the mixerXxx functions, see Kernel Streaming Topology to Audio Mixer API Translation.

PortCls provides six port drivers: WavePci, WaveCyclic, WaveRT, MIDI, DMus, and Topology. (WaveRT has been available since Windows Vista and is the recommended approach.) The Topology port driver controls the portion of the audio adapter circuitry that mixes together the rendering streams from the wave and MIDI devices. It also controls the selection of capture streams from input jacks. In spite of its somewhat misleading name, the Topology port driver does not embody all of an audio adapter's topology, although typically it does contain a large portion of it. The other port drivers contribute the remaining portions of the adapter's topology.

Each port driver is paired with a corresponding miniport driver to form a KS filter that represents a particular device (wave, MIDI, or mixer) on the audio adapter, as shown in the following table.

Filter Type	Description
WaveXxx filter	Represents a wave device that converts a wave output stream to an analog audio signal or that converts an analog audio signal to a wave input stream.
MIDI or DMus filter	Represents a MIDI device that plays or captures a MIDI stream.
Topology filter	Represents the adapter's mixer circuitry.

The miniport driver implements the filter's device-specific functions, including the definition of the portion of the adapter topology that the device encompasses. The port driver takes care of the generic filter operations, including communication with the operating system, for each type of filter.

Each filter has one or more KS pins that serve as pathways for streams of audio data to enter and leave the filter. Typically, the pins on the Topology filter are tied to the pins on the wave, MIDI, and DMus filters through hardwired connections in the adapter circuitry. These filters and their interconnections together form a KS filter graph that embodies the adapter's topology.

The following figure shows the topology of an example audio adapter.

In the preceding figure, the topology at the top level consists of the connections among the MIDI, WaveXxx, and topology filters. In addition, each filter has its own internal topology, which consists of the data paths through the filter and the control nodes that lie along each path. The nodes are labeled as shown in the following table.

Label	Description	KS Node-Type GUID
Synth	Synthesizer node	KSNODETYPE_SYNTHESIZER
DAC	Digital-to-audio converter node	KSNODETYPE_DAC
ADC	Analog-to-digital converter node	KSNODETYPE_ADC
Volume	Volume-level control node	KSNODETYPE_VOLUME
Mute	Mute control node	KSNODETYPE_MUTE
Sum	Summation node	KSNODETYPE_SUM
MUX	Multiplexer node	KSNODETYPE_MUX

In the preceding figure, the pins on the left side of the audio adapter represent the logical connections (not physical connections) through which data streams enter the adapter from the system bus or enter the system bus from the adapter. These pins are logically connected to source and sink pins on other filters (not shown) that are external to the adapter. Typically, these filters are software modules that, together with the adapter topology, form a larger filter graph whose topology can be explored by applications using the mixerXxx functions. For example, the pin labeled "PCM Wave Out" in the preceding figure is logically connected to the user-mode audio engine in Windows. These logical connections are maintained by DMA transfers over the system bus.

In contrast, the pins on the left edge of the topology filter are physically connected to pins on the MIDI and WaveXxx filters. These connections are hardwired and cannot be changed by software.

The bridge pins on the right side of the audio adapter represent audio jacks on the system chassis. These pins are referred to as bridge pins because they bridge the boundary between the KS filter graph and the external world.

Filters, pins, and nodes typically have properties that are accessible to clients (kernel-mode components or user-mode applications) of the audio driver. A client can send a KS property request to a filter, pin, or node either to query for the current value of a property or to change the property value. For example, a volume-level control node has a KSPROPERTY_AUDIO_VOLUMELEVEL property, which a client can change through a KS property request. A summation node is an example of a node type that typically has no properties.

For simplicity, the WaveXxx filter in the preceding figure provides only a single pin for accepting a PCM wave output stream from the system bus. In contrast, some wave devices provide multiple pins for PCM wave output and contain hardware for internally mixing the streams that enter the pins. These devices provide hardware acceleration for applications that use DirectSound by accepting PCM streams that play from the applications' sound buffers. For DirectSound to use these pins, they must provide additional nodes for two-dimensional (2-D) and three-dimensional (3-D) processing, as described in DirectSound Hardware Acceleration in WDM Audio.

This type of hardware acceleration is supported in Windows Server 2003, Windows XP, Windows 2000, and Windows Me/98, but it is not supported in Windows Vista. Windows Vista makes no use of the hardware acceleration pins on older wave devices.

In the preceding figure, the physical connections between the MIDI, WaveXxx, and topology filters all transport analog audio signals. However, a different topology device might achieve a similar effect by accepting digital output streams from the MIDI and wave devices, digitally mixing them, and converting the digital mix to an analog output signal.

The "Non-PCM Wave Out" pin at the lower-left corner of the preceding figure accepts a non-PCM output stream in an S/PDIF pass-through format, such as AC-3-over-S/PDIF or WMA Pro-over-S/PDIF. Using one of these formats, the device simply transmits the compressed data over the S/PDIF link without decoding the data. For this reason, the data path to the "S/PDIF Out" pin on the lower-right corner of the preceding figure contains no volume or mute nodes. For more information about non-PCM audio formats and S/PDIF pass-through transmission, see Supporting Non-PCM Wave Formats and S/PDIF Pass-Through Transmission of Non-PCM Streams.

The miniport driver presents its topology to the port driver in the form of a PCFILTER_DESCRIPTOR structure. This structure describes all of the filter's pins and nodes, and it specifies how the pins and nodes connect to each other.

Instead of designing a monolithic topology filter, as shown in the preceding figure, the mixer circuitry in the audio adapter can be partitioned into several topology filters. For example, in the preceding figure, the data paths that drive the speakers might be implemented as one topology filter, and the data paths that capture audio data from input devices can be implemented as a separate topology filter. When the data paths in a particular topology filter are not in use, that portion of the adapter can be powered down without disabling the entire adapter. For more information, see Dynamic Audio Subdevices.