KSPROPSETID_Synth

Der KSPROPSETID_Synth Eigenschaftensatz enthält Eigenschaften, die global für die Konfiguration eines Syntheseknotens (KSNODETYPE_SYNTHESIZER) sind.

Eigenschaftenelemente in diesem Satz werden durch KSPROPERTY_SYNTH Enumerationswerte angegeben, wie in der Headerdatei Dmusprop.h definiert.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_CAPS-Eigenschaft wird vom System verwendet, um die Funktionen eines Synthesizers zu bestimmen.

Herunterladen	Set	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Ja	Nein	Pin	KSNODEPROPERTY	SYNTHCAPS

Der Eigenschaftswert (Vorgangsdaten) ist eine Struktur vom Typ SYNTHCAPS und gibt die Funktionen des Synthesizers an. Diese Funktionen umfassen:

• Menge des verfügbaren Beispielarbeitsspeichers

• Maximale Anzahl von Kanalgruppen

• Maximale Anzahl von Stimmen

• Maximale Anzahl von Audiokanälen

• Rendereffekte

Weitere Informationen finden Sie unter SYNTHCAPS.

Rückgabewert

Eine KSPROPERTY_SYNTH_CAPS-Eigenschaftsanforderung gibt STATUS_SUCCESS zurück, um anzugeben, dass sie erfolgreich abgeschlossen wurde. Andernfalls gibt die Anforderung einen geeigneten Fehler status Code zurück.

Weitere Informationen zu Synthesizerfunktionen finden Sie in der IDirectMusicPort::GetCaps-Methode und in der DMUS_PORTCAPS-Struktur in der Microsoft Windows SDK-Dokumentation.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_CHANNELGROUPS-Eigenschaft wird vom System verwendet, um die Anzahl der aktiven Kanalgruppen auf dem Pin-instance festzulegen oder abzurufen. Kanalgruppen werden beginnend mit 0 (null) an jedem Pin instance nummeriert.

Herunterladen	Set	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Ja	Ja	Pin	KSNODEPROPERTY	ULONG

Der Eigenschaftswert (Vorgangsdaten) ist vom Typ ULONG und gibt an, wie viele Kanalgruppen der Pin unterstützt. Wenn eine Pin n Kanalgruppen unterstützt, werden die Kanalgruppen auf der Pin von 0 bis n-1 nummeriert.

Rückgabewert

Eine KSPROPERTY_SYNTH_CAPS-Eigenschaftsanforderung gibt STATUS_SUCCESS zurück, um anzugeben, dass sie erfolgreich abgeschlossen wurde. Andernfalls gibt die Anforderung einen geeigneten Fehler status Code zurück. In der folgenden Tabelle sind einige der möglichen Fehlercodes aufgeführt.

Statuscode	Bedeutung
STATUS_BUFFER_TOO_SMALL	Der Puffer war zu klein, um den Vorgang abzuschließen.
STATUS_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.

Weitere Informationen zu Kanalgruppen finden Sie in den Beschreibungen der Methoden IDirectMusicPort::GetNumChannelGroups und IDirectMusicPort::SetNumChannelGroups in der Microsoft Windows SDK-Dokumentation.

Nutzungszusammenfassungstabelle

Die eigenschaft KSPROPERTY_SYNTH_LATENCYCLOCK wird verwendet, um den Miniporttreiber nach der aktuellen Latenzzeit des Datenstroms abzufragen, die immer größer als die master-Clock-Zeit ist.

Herunterladen	Set	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Ja	Nein	Pin	KSNODEPROPERTY	ULONGLONG

Der Eigenschaftswert (Vorgangsdaten) ist vom Typ ULONGLONG und stellt die aktuelle Latenzzeit des Synthesizers dar. Diese Zeit wird relativ zur master Uhr angegeben und in 100 Nanosekundeneinheiten ausgedrückt.

Rückgabewert

Eine KSPROPERTY_SYNTH_LATENCYCLOCK-Eigenschaftsanforderung gibt STATUS_SUCCESS zurück, um anzugeben, dass sie erfolgreich abgeschlossen wurde. Andernfalls gibt die Anforderung einen geeigneten Fehler status Code zurück. In der folgenden Tabelle sind einige der möglichen Fehlercodes aufgeführt.

Statuscode	Bedeutung
STATUS_BUFFER_TOO_SMALL	Der Puffer war zu klein, um den Vorgang abzuschließen.
STATUS_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.
STATUS_INVALID_DEVICE_REQUEST	Der Vorgang ist für dieses Gerät ungültig.

Latenzuhren werden in der Regel verwendet, um Audioausgabestreams zwischen mehreren Geräten zu synchronisieren.

Eine KSPROPERTY_SYNTH_LATENCYCLOCK Get-Property-Anforderung sollte eine Latenzzeit zurückgeben, die der aktuellen master-Uhr-Zeit entspricht, sowie die minimale garantierte Latenz des Audiofilters, den der Stream durchläuft. Bei einem Anwendungsprogramm, das die Wiedergabe von Audiodaten vor der aktuellen Latenzzeit plant, besteht das Risiko, dass die Daten verspätet wiedergegeben werden.

Weitere Informationen zu Latenzuhren finden Sie in den folgenden Artikeln:

• Die Erläuterung der KSPROPERTY_SYNTH_LATENCYCLOCK-Eigenschaft in Latenzuhren.

• Die Beschreibungen der Methoden IDirectMusicPort::GetLatencyClock und IReferenceClock::GetTime in der Microsoft Windows SDK-Dokumentation.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_PORTPARAMETERS-Eigenschaft wird verwendet, um die Konfigurationsparameter für einen DirectMusic-Port abzurufen. Dabei handelt es sich um einen DirectMusic-Ausdruck für ein Gerät, das Musikdaten sendet oder empfängt. (In der KS-Terminologie entspricht der DirectMusic-Port nicht einem DMus-Porttreiber. Es entspricht einem Render- oder Aufnahmepin in einem DirectMusic-Filter.)

Herunterladen	Set	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Ja	Nein	Pin	KSNODEPROPERTY + SYNTH_PORTPARAMS	SYNTH_PORTPARAMS

Der Eigenschaftsdeskriptor (instance Daten) besteht aus einer KSNODEPROPERTY-Struktur, die unmittelbar von einer SYNTH_PORTPARAMS-Struktur folgt. Vor dem Senden der Eigenschaftsanforderung gibt der Client die angeforderten Parameterwerte an, indem er sie in die SYNTH_PORTPARAMS-Struktur schreibt.

Der Eigenschaftswert (Vorgangsdaten) ist ebenfalls vom Typ SYNTH_PORTPARAMS. Der Miniporttreiber lädt diese Struktur mit den Parameterwerten, die er tatsächlich zum Konfigurieren des Ports verwendet.

Rückgabewert

Wenn es dem Miniporttreiber gelingt, den DirectMusic-Port genau wie vom Aufrufer angegeben zu konfigurieren, gibt er den STATUS_SUCCESS Code zurück. Andernfalls wird ein entsprechender Fehlercode zurückgegeben. In der folgenden Tabelle sind einige der möglichen Fehler status Codes aufgeführt.

Statuscode	Bedeutung
STATUS_NOT_ALL_ASSIGNED	Der Vorgang war erfolgreich, aber der Miniporttreiber musste mindestens einen der Parameterwerte ändern, die der Aufrufer im Eigenschaftswert als gültig markiert hat.
STATUS_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.

Dies ist das komplizierteste der DirectMusic-Eigenschaftselemente, die verarbeitet werden müssen. Obwohl diese Eigenschaft nur die Get-Anforderung unterstützt, legt die get-Anforderung auch die Portparameter fest. Der Port übergibt eine SYNTH_PORTPARAMS-Struktur als Eigenschaftsdeskriptor für die Eigenschaftsanforderung. Ein Eigenschaft-Wert-Puffer begleitet die Eigenschaftsanforderung, aber da es sich um eine Get-Anforderung handelt, wird der Puffer nur zum Abrufen von Informationen aus dem Miniporttreiber verwendet.

Der Miniporttreiber sollte zuerst die SYNTH_PORTPARAMS Struktur aus dem Eigenschaftendeskriptor in den Eigenschaftswertpuffer kopieren. Als Nächstes sollte überprüft werden, ob es in der Lage ist, alle Parameterwerte zu unterstützen, die der Aufrufer angefordert hat (als gültig markiert). Wenn der Miniporttreiber einen oder mehrere der angeforderten Parameterwerte nicht unterstützen kann, sollten (in der SYNTH_PORTPARAMS-Struktur im Eigenschaftswertpuffer) die angeforderten Werte für diese speziellen Parameter mit den unterstützten Werten überschrieben werden.

Wenn der Miniporttreiber keine Änderungen am SYNTH_PORTPARAMS des Aufrufers vornimmt, sollte der Aufrufer einen Eigenschaftswert zurück erhalten, der genau den Parametern in der Eigenschaftsbeschreibung entspricht, die der Aufrufer ursprünglich an den Miniporttreiber gesendet hat.

Gemäß der Konvention füllt der Treiber auch Werte für Parameter ein, für die keine entsprechenden Bits im dwValidParams-Member von SYNTH_PORTPARAMS festgelegt sind. Dadurch kann der Aufrufer sehen, welche Standardwerte der Miniporttreiber für diese Parameter verwendet hat. Der Miniporttreiber gibt die tatsächlichen Parameterwerte aus, die er zum Erstellen des Wave-Interface-Geräts verwendet hat.

Der KSPROPERTY_SYNTH_PORTPARAMETERS-Handler des Miniporttreibers sollte so vorbereitet sein, dass Anforderungen für Änderungen der Stichprobenrate ordnungsgemäß verarbeitet werden.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_RUNNINGSTATS-Eigenschaft wird verwendet, um den Miniporttreiber für die Leistungsstatistiken des Synthesizers abzufragen.

Herunterladen	Set	Ziel	Eigenschaftsdeskriptortyp	Eigenschaftswerttyp
Ja	Nein	Pin	KSNODEPROPERTY	SYNTH_STATS

Der Eigenschaftswert (Vorgangsdaten) ist eine Struktur vom Typ SYNTH_STATS. Der Eigenschaftenhandler des Miniporttreibers schreibt die folgenden Statistiken in diese Struktur:

• Die durchschnittliche Anzahl der wiedergegebenen Stimmen

• CPU-Auslastung

• Anzahl der verlorenen Notizen

• Menge des freien Arbeitsspeichers

• Spitzenlautstärke

Rückgabewert

Eine KSPROPERTY_SYNTH_RUNNINGSTATS-Eigenschaftsanforderung gibt STATUS_SUCCESS zurück, um anzugeben, dass sie erfolgreich abgeschlossen wurde. Andernfalls gibt die Anforderung einen entsprechenden Fehler status Code zurück. In der folgenden Tabelle sind einige der möglichen Fehlercodes aufgeführt.

Statuscode	Bedeutung
STATUS_BUFFER_TOO_SMALL	Der Puffer war zu klein, um den Vorgang abzuschließen.
STATUS_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.
STATUS_INVALID_DEVICE_REQUEST	Der Vorgang ist für dieses Gerät ungültig.

Die Leistungsstatistiken des Synthesizers werden kontinuierlich aktualisiert, während das Gerät im KSSTATE_RUN Zustand verbleibt. Jedes Mal, wenn das Gerät in diesen Zustand wechselt, wird die Statistik zurückgesetzt, wodurch kumulierte Werte wie die Spitzenmenge und die Anzahl der verlorenen Notizen auf Null 00 zurückgesetzt werden.

Weitere Informationen finden Sie in der Beschreibung der IDirectMusicPort::GetRunningStats-Methode und der DMUS_SYNTHSTATS-Struktur in der Microsoft Windows SDK-Dokumentation.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_VOICEPRIORITY-Eigenschaft gibt an, welche Priorität eine bestimmte Stimme in einem MIDI-Synthesizer haben soll, wenn der Miniporttreiber Stimmen aus seinem Sprachcache stoßen muss.

Herunterladen	Set	Ziel	Eigenschaftsdeskriptortyp	Eigenschaftswerttyp
Ja	Ja	Pin	KSNODEPROPERTY + SYNTHVOICEPRIORITY_INSTANCE	DWORD

Der Eigenschaftsdeskriptor (instance Daten) besteht aus einer KSNODEPROPERTY-Struktur, die unmittelbar von einer SYNTHVOICEPRIORITY_INSTANCE-Struktur gefolgt wird, die die Kanalgruppe der Stimme (Satz von 16 MIDI-Kanälen) und die Kanalnummer (innerhalb der Gruppe) angibt.

Der Eigenschaftswert (Vorgangsdaten) ist ein DWORD, das die Priorität angibt. Der Client verwendet eine KSPROPERTY_SYNTH_VOICEPRIORITY Set-Eigenschaftsanforderung, um die neue Priorität der Stimme an den Miniporttreiber zu senden, und er verwendet eine KSPROPERTY_SYNTH_VOICEPRIORITY get-Eigenschaftsanforderung, um die aktuelle Priorität der Stimme aus dem Miniporttreiber abzurufen.

Sprachprioritäten

Die folgenden Kanalgruppenprioritäten werden in der Headerdatei Dmusprop.h definiert:

  DAUD_CRITICAL_VOICE_PRIORITY
  DAUD_HIGH_VOICE_PRIORITY
  DAUD_STANDARD_VOICE_PRIORITY
  DAUD_LOW_VOICE_PRIORITY
  DAUD_PERSIST_VOICE_PRIORITY

Die vorherige Liste wird mit der höchsten Priorität oben in der Liste und der niedrigsten am unteren Rand sortiert. Diese Prioritäten werden mit den Kanalprioritätsoffsets festgelegt, um die Sprachpriorität für jeden Kanal innerhalb einer Kanalgruppe zu erreichen. Die resultierenden Prioritäten werden in den Anforderungen der get- und set-Eigenschaft übergeben.

Die vorherigen Werte der Kanalgruppenpriorität sind im Vergleich zu den Kanalprioritätsoffsets groß. Das Ergebnis ist, dass das Ändern der Kanalgruppenpriorität die Priorität der gesamten Kanalgruppe im Verhältnis zu anderen Kanalgruppen erhöht oder verringert, ohne die relativen Prioritäten der Kanäle innerhalb der Kanalgruppe zu ändern.

Standardprioritäten

Wenn ein Synthesizer-Miniporttreiber erstellt wird, weist er jeder stimme eine Standardpriorität zu. Die Standardwerte sind wie folgt definiert:

• Standardmäßig sind die Prioritäten für alle Kanalgruppen gleich. Dies bedeutet beispielsweise, dass Kanal 5 in Kanalgruppe 1 die gleiche Priorität wie Kanal 5 in Kanalgruppe 2 hat.

• Gemäß DLS Level-1-Spezifikationen hat Kanal 10 (der MIDI-Schlagzeugkanal) die höchste Priorität, gefolgt von 1 bis 9 und 11 bis 16.

Die Headerdatei Dmusprop.h definiert die folgenden Prioritätsoffsets:

  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

Die vorherige Liste der Offsets wird mit der höchsten Priorität am Anfang der Liste sortiert. Die Headerdatei Dmusprop.h definiert auch die Standardprioritäten der Kanäle in jeder Kanalgruppe durch bitweises ORingen jeder dieser Offsets mit DAUD_STANDARD_VOICE_PRIORITY. Die folgende Definition gibt beispielsweise die Standardpriorität für Kanal 1 in jeder Kanalgruppe an:

  #define DAUD_CHAN1_DEF_VOICE_PRIORITY \
    (DAUD_STANDARD_VOICE_PRIORITY | DAUD_CHAN1_VOICE_PRIORITY_OFFSET)

Rückgabewert

Eine KSPROPERTY_SYNTH_VOICEPRIORITY-Eigenschaftsanforderung gibt STATUS_SUCCESS zurück, um anzugeben, dass sie erfolgreich abgeschlossen wurde. Andernfalls gibt die Anforderung einen entsprechenden Fehler status Code zurück. In der folgenden Tabelle sind einige der möglichen Fehlercodes aufgeführt.

Statuscode	Bedeutung
STATUS_BUFFER_TOO_SMALL	Der Puffer war zu klein, um den Vorgang abzuschließen.
STATUS_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.

Weitere Informationen zu Sprachprioritäten finden Sie in den Beschreibungen der Methoden IDirectMusicPort::GetChannelPriority und IDirectMusicPort::SetChannelPriority in der Microsoft Windows SDK-Dokumentation.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_VOLUME-Eigenschaft ruft die Lautstärke eines Synthesizergeräts ab oder legt sie fest.

Herunterladen	Set	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Ja	Ja	Pin	KSPROPERTY	LONG

Der Eigenschaftswert (Vorgangsdaten) ist vom Typ LONG und gibt die Lautstärke des Synthesizergeräts an. Die Lautstärkeeinstellung wird in Einheiten von 1/100Stel einer Dezibel angegeben. Der Miniporttreiber sollte entweder sein Volume ändern oder sein Volume melden, je nachdem, ob die Anforderung die Eigenschaft abrufen oder festlegen soll.

Rückgabewert

Eine KSPROPERTY_SYNTH_VOLUME-Eigenschaftsanforderung gibt STATUS_SUCCESS zurück, um anzugeben, dass sie erfolgreich abgeschlossen wurde. Andernfalls gibt die Anforderung einen geeigneten Fehler status Code zurück. In der folgenden Tabelle sind einige der möglichen Fehlercodes aufgeführt.

Statuscode	Bedeutung
STATUS_BUFFER_TOO_SMALL	Der Puffer war zu klein, um den Vorgang abzuschließen.
STATUS_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_VOLUMEBOOST-Eigenschaft gibt die Menge an, um die die Lautstärke eines Synthesizergeräts erhöht wird.

Herunterladen	Set	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Ja	Ja	Pin	KSNODEPROPERTY	LONG

Der Eigenschaftswert (Vorgangsdaten) ist vom Typ LONG und gibt an, um wie viel das Audiosignal nach der Mixphase erhöht werden soll. Dies ist die Menge an Lautstärke, die der enden Ausgabe des Synthesizers hinzugefügt werden soll, nachdem alle Stimmartikulation und -mischung abgeschlossen sind. Der Volumenerhöhungsbetrag wird in 1/100Stel einer Dezibel angegeben. Dieser Wert kann positiv oder negativ sein.

Rückgabewert

Eine KSPROPERTY_SYNTH_VOLUMEBOOST-Eigenschaftsanforderung gibt STATUS_SUCCESS zurück, um anzugeben, dass sie erfolgreich abgeschlossen wurde. Andernfalls gibt die Anforderung einen geeigneten Fehler status Code zurück. In der folgenden Tabelle sind einige der möglichen Fehlercodes aufgeführt.

Statuscode	Bedeutung
STATUS_BUFFER_TOO_SMALL	Der Puffer war zu klein, um den Vorgang abzuschließen.
STATUS_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.

Der Ausgabe sollte keine weitere Verstärkung hinzugefügt werden. Der Synthesizer sollte strengen DLS Level-1-Konventionen für die Artikulation folgen.

Diese Eigenschaft wird verwendet, um die Lautstärke des Synthesizers mit anderen Audioausgaben im System zu ausgleichen, und boost-Mengen sollten daher auf allen Geräten konsistent interpretiert werden.