|
|
|
MIDI and DirectMusic filters represent devices that synthesize, output, or capture MIDI music data. Applications typically access the capabilities of these devices either through the DirectMusic API or through the Windows Multimedia midiOutXxx and midiInXxx functions. For more information about these interfaces, see the Windows SDK documentation.
A MIDI or DirectMusic synthesizer filter receives as input a MIDI stream consisting of time-stamped MIDI events. The filter outputs either of the following:
A MIDI or DirectMusic output filter receives as input a MIDI stream consisting of time-stamped MIDI events. The filter outputs raw MIDI messages to an external MIDI sound module.
A MIDI or DirectMusic capture filter takes as input a series of raw MIDI messages from a MIDI keyboard or other external MIDI device. The filter outputs a MIDI stream consisting of time-stamped MIDI events.
A single MIDI or DirectMusic filter can perform a combination of the three functions above — synthesis, output, and capture — depending on the capabilities of the device that the filter represents. For example, a pure MPU-401 device performs output and capture but not synthesis.
A MIDI filter is implemented as a port/miniport driver pair. A MIDI filter factory creates a MIDI filter as follows:
The code example in Subdevice Creation illustrates this process. The port and miniport drivers communicate with each other through their IPortMidi and IMiniportMidi interfaces.
To support MIDI output and synthesizer devices, the MIDI port driver contains a software sequencer that outputs raw MIDI messages to the miniport driver with a timer resolution of one millisecond.
A DirectMusic filter provides a superset of the functionality of a MIDI filter. The superset includes these additional capabilities:
With channel groups, the number of notes that can be played simultaneously is no longer limited to the 16 channels of the original MIDI specification. It is limited only by the number of voices available in the synthesizer.
A DirectMusic filter is implemented as a port/miniport driver pair. A DirectMusic filter factory creates a DirectMusic filter as follows:
The code example in Subdevice Creation illustrates this process. The port and miniport drivers communicate with each other through their IPortDMus and IMiniportDMus interfaces.
To support DirectMusic synthesizer devices, the DMus port driver contains a low-resolution (one millisecond) software sequencer that can output time-stamped MIDI events to the hardware sequencer’s buffer in advance of when they are scheduled to be played. To support DirectMusic output devices, the port driver's software sequencer can also be configured to output raw MIDI messages at the times they are to be played.
When enumerating MIDI input or output devices through the Windows Multimedia midiInXxx or midiOutXxx functions, an application can see only WDM devices whose miniport drivers expose MIDI pins. These are pins that support MIDI streams (see MIDI Stream Data Range). When enumerating devices through DirectMusic, however, an application can see WDM devices with both DirectMusic (see DirectMusic Stream Data Range) and MIDI pins.
When implementing a custom miniport driver, a hardware vendor typically writes either a MIDI miniport driver or a DMus miniport driver, but not both. A DMus miniport driver can expose both MIDI and DirectMusic pins, which eliminates the need to write a separate MIDI miniport driver.
In Windows 98/Me, DirectMusic sometimes enumerates the same MPU-401 device twice. The reason is that some hardware vendors expose their MPU-401 devices both as legacy, pre-WDM MIDI devices and as WDM devices. For the legacy device, DirectMusic enumerates an MPU-401 device that represents the direct path from DMusic.dll to IHVAudio.dll. For the WDM device, DirectMusic enumerates the same MPU-401 device through a circuitous path consisting of the following sequence of components:
The MIDI synthesizer that shows up in the multimedia control panel (mmsys.cpl) will have the same name as the WDM device.
Several system-supplied MIDI and DirectMusic miniport drivers are built into the PortCls system driver:
Adapter drivers can access the system-supplied miniport drivers by calling the PcNewMiniport function. The FMSynth and DMusUART miniport drivers are also included as sample audio drivers in the Windows DDK. By modifying the source code in these samples, hardware vendors can extend the drivers to manage their devices' proprietary features.
DMusUART is an example of a DirectMusic miniport driver that exposes both MIDI and DirectMusic pins, but does not support either DLS downloads or hardware sequencing. The miniport driver's DirectMusic rendering pin has a synth node (KSNODETYPE_SYNTHESIZER) that supports several KSPROPSETID_Synth properties. The miniport driver includes itself in categories KSCATEGORY_RENDER and KSCATEGORY_CAPTURE, but not in KSCATEGORY_SYNTHESIZER (because it does not contain an internal synthesizer). For details, see the DMusUART sample audio driver in the Windows DDK.
Note that in Windows XP and later, the MIDI and DirectMusic port drivers use the same internal software implementation. This means that the CLSID_PortMidi and CLSID_PortDMus GUIDs are equivalent when calling PcNewPort. Applications written for previous versions of Windows should see no change in behavior resulting from consolidation of the MIDI and DirectMusic port drivers.