KSPROPSETID_Synth

The KSPROPSETID_Synth property set contains properties that are global to the configuration of a synth node (KSNODETYPE_SYNTHESIZER).

Property items in this set are specified by KSPROPERTY_SYNTH enumeration values, as defined in header file Dmusprop.h.

Usage Summary Table

The KSPROPERTY_SYNTH_CAPS property is used by the system to determine the capabilities of a synthesizer.

The property value (operation data) is a structure of type SYNTHCAPS and specifies the synthesizer's capabilities. These capabilities include:

• Amount of sample memory available

• Maximum number of channel groups

• Maximum number of voices

• Maximum number of audio channels

• Rendering effects

For more information, see SYNTHCAPS.

Return Value

A KSPROPERTY_SYNTH_CAPS property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code.

For more information about synthesizer capabilities, see the IDirectMusicPort::GetCaps method and the DMUS_PORTCAPS structure in the Microsoft Windows SDK documentation.

Usage Summary Table

The KSPROPERTY_SYNTH_CHANNELGROUPS property is used by the system to set or get the number of active channel groups on the pin instance. Channel groups are numbered, beginning with zero, on each pin instance.

The property value (operation data) is of type ULONG and specifies how many channel groups the pin supports. If a pin supports n channel groups, the channel groups on the pin are numbered from 0 to n-1.

Return Value

A KSPROPERTY_SYNTH_CAPS property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code. The following table shows some of the possible failure codes.

For more information about channel groups, see the descriptions of the IDirectMusicPort::GetNumChannelGroups and IDirectMusicPort::SetNumChannelGroups methods in the Microsoft Windows SDK documentation.

Usage Summary Table

The KSPROPERTY_SYNTH_LATENCYCLOCK property is used to query the miniport driver for the stream's current latency-clock time, which is always greater than the master-clock time.

The property value (operation data) is of type ULONGLONG and represents the synthesizer's current latency time. This time is specified relative to the master clock and expressed in 100-nanosecond units.

Return Value

A KSPROPERTY_SYNTH_LATENCYCLOCK property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code. The following table shows some of the possible failure codes.

Latency clocks are typically used to synchronize audio output streams among multiple devices.

A KSPROPERTY_SYNTH_LATENCYCLOCK get-property request should return a latency-clock time that equals the current master-clock time, plus the minimum guaranteed latency of the audio filter that the stream passes through. An application program that schedules audio data to be played earlier than the current latency-clock time risks having the data played late.

For more information about latency clocks, see the following:

• The discussion of the KSPROPERTY_SYNTH_LATENCYCLOCK property in Latency Clocks.

• The descriptions of the IDirectMusicPort::GetLatencyClock and IReferenceClock::GetTime methods in the Microsoft Windows SDK documentation.

Usage Summary Table

The KSPROPERTY_SYNTH_PORTPARAMETERS property is used to get the configuration parameters for a DirectMusic port, which is a DirectMusic term for a device that sends or receives music data. (In KS terminology, DirectMusic port does not correspond to a DMus port driver. It corresponds to a render or capture pin on a DirectMusic filter.)

The property descriptor (instance data) consists of a KSNODEPROPERTY structure that is immediately followed by a SYNTH_PORTPARAMS structure. Before sending the property request, the client specifies its requested parameter values by writing them into the SYNTH_PORTPARAMS structure.

The property value (operation data) is also of type SYNTH_PORTPARAMS. The miniport driver loads this structure with the parameter values that it actually uses to configure the port.

Return Value

If the miniport driver succeeds in configuring the DirectMusic port exactly as specified by the caller, it returns the STATUS_SUCCESS code. Otherwise, it returns an appropriate error code. The following table indicates some of the possible error status codes.

This is the most complicated of the DirectMusic property items to handle. Although this property supports only the get request, the get request also sets the port parameters. The port passes a SYNTH_PORTPARAMS structure as the property descriptor for the property request. A property-value buffer accompanies the property request, but because this is a get request, the buffer is only used to retrieve information from the miniport driver.

The miniport driver should first copy the SYNTH_PORTPARAMS structure from the property descriptor to the property-value buffer. Next, it should check to see if it is capable of supporting all the parameter values that the caller has requested (marked as valid). If the miniport driver is unable to support one or more of the requested parameter values, it should overwrite (in the SYNTH_PORTPARAMS structure in the property-value buffer) the requested values for these particular parameters with the values that it can support.

If the miniport driver makes no changes to the caller's SYNTH_PORTPARAMS, the caller should get back a property value that exactly matches the parameters in the property descriptor that the caller originally sent down to the miniport driver.

By convention, the driver also fills in values for parameters that do not have corresponding bits set in the dwValidParams member of SYNTH_PORTPARAMS. This allows the caller to see what default values the miniport driver used for these parameters. The miniport driver outputs the actual parameter values that it used to build the wave-interface device.

The miniport driver's KSPROPERTY_SYNTH_PORTPARAMETERS handler should be prepared to correctly handle requests for sample-rate changes.

Usage Summary Table

The KSPROPERTY_SYNTH_RUNNINGSTATS property is used to query the miniport driver for the synthesizer's performance statistics.

The property value (operation data) is a structure of type SYNTH_STATS. The miniport driver's property handler writes the following statistics into this structure:

• The average number of voices playing

• CPU usage

• Number of notes lost

• Amount of free memory

• Peak volume level

Return Value

A KSPROPERTY_SYNTH_RUNNINGSTATS property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code. The following table shows some of the possible error codes.

The synthesizer's performance statistics are continuously updated while the device remains in the KSSTATE_RUN state. Each time the device enters this state, it resets the statistics, which zeros cumulative values such as the peak volume and number of notes lost.

For additional information, see the description of the IDirectMusicPort::GetRunningStats method and the DMUS_SYNTHSTATS structure in the Microsoft Windows SDK documentation.

Usage Summary Table

The KSPROPERTY_SYNTH_VOICEPRIORITY property specifies what priority a particular voice in a MIDI synthesizer should have when the miniport driver needs to bump voices from its voice cache.

The property descriptor (instance data) consists of a KSNODEPROPERTY structure that is immediately followed by a SYNTHVOICEPRIORITY_INSTANCE structure, which specifies the voice's channel group (set of 16 MIDI channels) and channel number (within the group).

The property value (operation data) is a DWORD that specifies the priority. The client uses a KSPROPERTY_SYNTH_VOICEPRIORITY set-property request to send the voice's new priority to the miniport driver, and it uses a KSPROPERTY_SYNTH_VOICEPRIORITY get-property request to retrieve the voice's current priority from the miniport driver.

Voice Priorities

The following channel-group priorities are defined in header file Dmusprop.h:

  DAUD_CRITICAL_VOICE_PRIORITY
  DAUD_HIGH_VOICE_PRIORITY
  DAUD_STANDARD_VOICE_PRIORITY
  DAUD_LOW_VOICE_PRIORITY
  DAUD_PERSIST_VOICE_PRIORITY

The preceding list is ordered with the highest priority at the top of the list and the lowest at the bottom. These priorities are ORed with the channel priority offsets to arrive at the voice priority for each channel within a channel group. The resulting priorities are passed in the get- and set-property requests.

The preceding channel-group priority values are large compared to the channel priority offsets. The result is that changing the channel-group priority raises or lowers the priority of the entire channel group relative to other channel groups without altering the relative priorities of the channels within the channel group.

Default Priorities

When a synthesizer miniport driver is created, it assigns a default priority to each of its voices. The defaults are defined as follows:

• By default, priorities are equal across channel groups. This means, for example, that channel 5 on channel group 1 has the same priority as channel 5 on channel group 2.

• In accordance with DLS Level-1 specifications, channel 10 (the MIDI percussion channel) has the highest priority, followed by 1 through 9 and 11 through 16.

Header file Dmusprop.h defines the following priority offsets:

  DAUD_CHAN10_VOICE_PRIORITY_OFFSET
  DAUD_CHAN1_VOICE_PRIORITY_OFFSET
  DAUD_CHAN2_VOICE_PRIORITY_OFFSET
  DAUD_CHAN3_VOICE_PRIORITY_OFFSET
  DAUD_CHAN4_VOICE_PRIORITY_OFFSET
  DAUD_CHAN5_VOICE_PRIORITY_OFFSET
  DAUD_CHAN6_VOICE_PRIORITY_OFFSET
  DAUD_CHAN7_VOICE_PRIORITY_OFFSET
  DAUD_CHAN8_VOICE_PRIORITY_OFFSET
  DAUD_CHAN9_VOICE_PRIORITY_OFFSET
  DAUD_CHAN11_VOICE_PRIORITY_OFFSET
  DAUD_CHAN12_VOICE_PRIORITY_OFFSET
  DAUD_CHAN13_VOICE_PRIORITY_OFFSET
  DAUD_CHAN14_VOICE_PRIORITY_OFFSET
  DAUD_CHAN15_VOICE_PRIORITY_OFFSET
  DAUD_CHAN16_VOICE_PRIORITY_OFFSET

The preceding list of offsets is ordered with the highest priority at the top of the list. Header file Dmusprop.h also defines the default priorities of the channels in each channel group by bitwise ORing each of these offsets with DAUD_STANDARD_VOICE_PRIORITY. For example, the following definition gives the default priority for channel 1 in each channel group:

  #define DAUD_CHAN1_DEF_VOICE_PRIORITY \
    (DAUD_STANDARD_VOICE_PRIORITY | DAUD_CHAN1_VOICE_PRIORITY_OFFSET)

Return Value

A KSPROPERTY_SYNTH_VOICEPRIORITY property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code. The following table shows some of the possible error codes.

For more information about voice priorities, see the descriptions of the IDirectMusicPort::GetChannelPriority and IDirectMusicPort::SetChannelPriority methods in the Microsoft Windows SDK documentation.

Usage Summary Table

The KSPROPERTY_SYNTH_VOLUME property gets or sets the volume level of a synthesizer device.

The property value (operation data) is of type LONG and specifies the volume level of the synthesizer device. The volume setting is specified in units of 1/100ths of a decibel. The miniport driver should either change its volume or report its volume, depending on whether the request is to get or set the property.

Return Value

A KSPROPERTY_SYNTH_VOLUME property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code. The following table shows some of the possible error codes.

Usage Summary Table

The KSPROPERTY_SYNTH_VOLUMEBOOST property specifies the amount by which a synthesizer device's volume is boosted.

The property value (operation data) is of type LONG and specifies by how much to boost the audio signal after the mix stage. This is the amount of volume to add to the final output of the synthesizer after all voice articulation and mixing have been completed. The volume boost amount is specified in 1/100ths of a decibel. This value can be positive or negative.

Return Value

A KSPROPERTY_SYNTH_VOLUMEBOOST property request returns STATUS_SUCCESS to indicate that it has completed successfully. Otherwise, the request returns an appropriate error status code. The following table shows some of the possible error codes.

No other boost should be added to the output. The synthesizer should follow strict DLS Level-1 conventions for articulation.

This property is used to equalize the volume of the synthesizer with other audio output in the system, and boost amounts should therefore be interpreted in a consistent manner across all devices.