KSPROPERTY_SYNTH_VOICEPRIORITY

Article
06/09/2017

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.

Usage Summary Table

Get	Set	Target	Property descriptor type	Property value type
Yes	Yes	Pin	KSNODEPROPERTY + SYNTHVOICEPRIORITY_INSTANCE	DWORD

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.

Status Code	Meaning
STATUS_BUFFER_TOO_SMALL	The buffer was too small to complete the operation.
STATUS_UNSUCCESSFUL	The operation did not complete successfully.

Remarks

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

Requirements

Header

Dmusprop.h (include Dmusprop.h)

Partager via