SYNTHCAPS structure (dmusprop.h)

Article
09/01/2022

The SYNTHCAPS structure specifies the capabilities of a synthesizer.

Syntax

typedef struct _SYNTHCAPS {
  GUID  Guid;
  DWORD Flags;
  DWORD MemorySize;
  DWORD MaxChannelGroups;
  DWORD MaxVoices;
  DWORD MaxAudioChannels;
  DWORD EffectFlags;
  WCHAR Description[128];
} SYNTHCAPS, *PSYNTHCAPS;

Members

Guid

Specifies the class ID for the synthesizer's miniport driver interface.

Flags

Specifies the general capabilities of the driver. This member is a bitfield whose value is either zero or the bitwise OR of one or more of the following flag bits:

SYNTH_PC_DLS

The driver supports downloadable sample collections (DLS Level 1).

SYNTH_PC_EXTERNAL

The synth represents a connection to external hardware.

SYNTH_PC_SOFTWARESYNTH

The driver implements a software synthesizer.

SYNTH_PC_MEMORYSIZEFIXED

The memory size given in the MemorySize member is valid and represents the maximum amount of sample memory in bytes. This flag is typically set when the sample memory is not system memory.

SYNTH_PC_GMINHARDWARE

The synth supports the General MIDI sound set in hardware.

SYNTH_PC_GSINHARDWARE

The synth supports the Roland GS sound set in hardware.

SYNTH_PC_REVERB

The synth supports reverb.

SYNTH_PC_DLS2

The driver supports downloadable sample collections (DLS Level 2).

SYNTH_PC_SYSTEMMEMORY

The synth can use system memory.

MemorySize

Specifies the amount of sample memory on the device (in bytes). This field should contain the value SYNTH_PC_SYSTEMMEMORY if the device uses system memory for sample memory with no limitation on the amount of memory allocated.

MaxChannelGroups

Specifies the maximum number of channel groups this driver supports. Each channel group represents a set of 16 MIDI channels and has associated with it all the state that a MIDI hardware device would keep, which includes DLS, GM, GS, XG, or other mode information. DLS downloads, however, are per-driver and can be used by any of the channel groups. This prevents wasting memory by downloading several copies of the same DLS sample, one per channel group.

MaxVoices

Specifies the maximum number of voices that the rendering device supports. If the property handler is unable to provide a valid number for this member, it should set the member to (ULONG)-1.

MaxAudioChannels

Specifies the maximum number of audio channels that the rendering device supports. If the property handler is unable to provide a valid number for this member, it should set the member to (ULONG)-1.

EffectFlags

Specifies the effects that the rendering device is capable of producing. This member is a bitfield whose value is either zero or the bitwise OR of the following flag bits:

SYNTH_EFFECT_REVERB

Rendering device can produce reverb effect.

SYNTH_EFFECT_CHORUS

Rendering device can produce chorus effect.

SYNTH_EFFECT_DELAY

Rendering device can produce delay effect.

If the device supports none of these capabilities, set this member to SYNTH_EFFECT_NONE (zero).

Description[128]

Contains a text description of the device. This member is a WCHAR array containing a null-terminated string (for example, "Microsoft MPU-401").

Remarks

The KSPROPERTY_SYNTH_CAPS get-property request uses the SYNTHCAPS structure to retrieve the capabilities of a synthesizer device from a DMus miniport driver.

SYNTH_CAPS is similar to the DMUS_PORTCAPS structure, which is described in the Microsoft Windows SDK documentation.

In the DMusUART sample driver in the Windows Driver Kit (WDK), the KSPROPERTY_SYNTH_CAPS property handler sets the members of the SYNTHCAPS structure to the following values:

  SYNTHCAPS *caps = (SYNTHCAPS*)pRequest->Value;
  ...
  caps->Flags              = SYNTH_PC_EXTERNAL;
  caps->MemorySize         = 0;         
  caps->MaxChannelGroups   = 1;
  caps->MaxVoices          = 0xFFFFFFFF;  // (ULONG)-1
  caps->MaxAudioChannels   = 0xFFFFFFFF;  // (ULONG)-1
  caps->EffectFlags        = 0;

In this example, the 0xFFFFFFFF values indicate that the handler has no way of knowing the actual MaxVoices and MaxAudioChannels limits because they are completely dependent on whatever external synthesizer happens to be connected to the UART. Elsewhere in the code, but not shown in the preceding example, the DMusUART property handler sets the Guid member of the SYNTHCAPS structure to either CLSID_MiniportDriverDMusUART or CLSID_MiniportDriverDMusUARTCapture. The one the Guid member is it is set to depends on whether the target node (of type KSNODETYPE_SYNTHESIZER) for the property request lies on a data path that handles rendering data or capture data. Both class IDs are defined in header file Dmusicks.h.

Requirements

Requirement	Value
Header	dmusprop.h (include Dmusprop.h)