Edit

Support for DirectMusic Properties

  • Article

A DirectMusic-synthesis miniport driver specifies its hardware capabilities in the form of an array of property items. Each property item is a PCPROPERTY_ITEM structure that contains the following:

  • A property set GUID that defines a particular hardware feature that is defined by DirectMusic.

  • A pointer to a property-handler method that is implemented within the driver.

  • A set of flags that specify whether the handler can get the property, set the property, and indicate basic support for the property.

Property Set GUIDs

The following property-set GUIDs are defined by DirectMusic:

  • GUID_DMUS_PROP_DLS1

  • GUID_DMUS_PROP_DLS2

  • GUID_DMUS_PROP_Effects

  • GUID_DMUS_PROP_GM_Hardware

  • GUID_DMUS_PROP_GS_Capable

  • GUID_DMUS_PROP_GS_Hardware

  • GUID_DMUS_PROP_INSTRUMENT2

  • GUID_DMUS_PROP_LegacyCaps

  • GUID_DMUS_PROP_MemorySize

  • GUID_DMUS_PROP_SampleMemorySize

  • GUID_DMUS_PROP_SamplePlaybackRate

  • GUID_DMUS_PROP_SetSynthSink

  • GUID_DMUS_PROP_SynthSink_DSOUND

  • GUID_DMUS_PROP_SynthSink_WAVE

  • GUID_DMUS_PROP_Volume

  • GUID_DMUS_PROP_WavesReverb

  • GUID_DMUS_PROP_WriteLatency

  • GUID_DMUS_PROP_WritePeriod

  • GUID_DMUS_PROP_XG_Capable

  • GUID_DMUS_PROP_XG_Hardware

For definitions of the preceding property set GUIDs, see the description of the KSPROPERTY structure in the DirectX 8.0 Programmer's Reference in the Microsoft Windows SDK. The property set for each of the preceding GUIDs consists of a single element that is identified by an index of zero.

IKsControl Interface

The IKsControl interface is used to get, set, or query for basic support of properties, events, and methods. This interface is part of the WDM kernel streaming (KS) architecture, but is also used by DirectMusic to expose properties of DirectMusic ports. To retrieve this interface, call the IDirectMusicPort::QueryInterface method (described in the Windows SDK documentation) with the riid parameter set to IID_IKsControl.

The IKsControl interface has three methods: KsProperty, KsEvent, and KsMethod. At present, only KsProperty is supported by DirectMusic.

The IKsControl::KsProperty method gets or sets the value of a property. The manner in which a property item request is routed to a particular DirectMusic port depends on how the port is implemented:

  • No properties are supported by ports that represent DirectMusic emulation on top of the Microsoft Win32 handle-based multimedia calls (the midiOut and midiIn APIs). Use the GUID_DMUS_PROP_LegacyCaps property set GUID to query a port for whether it is implemented with Win32 multimedia calls.

  • Property item requests to a port that represents a pluggable software synthesizer are handled entirely in user mode. The topology of this type of port is a synthesizer (represented by an IDirectMusicSynth interface) that is connected to a sink node (an IDirectMusicSynthSink interface). The property request is given first to the synthesizer node, and then to the sink node if it is not recognized by the synthesizer.