KSPROPSETID_Synth_Dls

Der KSPROPSETID_Synth_Dls Eigenschaftensatz enthält Eigenschaften, die zum Herunterladen von DLS-Beispielen und Instrumenten auf einen MIDI-Synthesizer verwendet werden. Dies sind die Eigenschaften eines Synth-Knotens (KSNODETYPE_SYNTHESIZER) auf einem DirectMusic-Pin eines DirectMusic-Filters (siehe MIDI- und DirectMusic-Filter).

In diesem Abschnitt wird das Verhalten dieser Eigenschaften in Bezug auf das Herunterladen und Entladen von Speicherblöcken beschrieben, die DLS-Daten enthalten. Das tatsächliche Format der heruntergeladenen Instrument- und Wellendatenblöcke wird in der DlS-Diskussion auf niedriger Ebene in der Microsoft Windows SDK-Dokumentation angegeben.

DLS-Downloads und -Entladungen können jederzeit während der Existenz des Pins erfolgen. Im Gegensatz zu DirectMusic-Ereignissen sind sie nicht zeitstempelt und sollten so schnell wie möglich verarbeitet werden.

In diesem Abschnitt bezieht sich der Begriff DLS-Ressource oder nur Ressource auf einen DLS-Instrumentblock oder einen DLS-Wellenblock. Das System verwaltet die Verweisanzahl für alle DLS-Ressourcen ordnungsgemäß:

• Wenn ein Client das letzte Instrument entlädt, das auf eine Welle verweist, generiert das System automatisch einen Aufruf zum Entladen der Welle.

• Umgekehrt verschiebt das System den Aufruf zum Entladen einer Welle, bis der Client das letzte Instrument entlädt, das auf die Welle verweist.

Eigenschaftenelemente in diesem Satz werden durch KSPROPERTY_SYNTH_DLS Enumerationswerte angegeben, die in der Headerdatei Dmusprop.h definiert sind.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_DLS_APPEND-Eigenschaft gibt die Menge des reservierten Speicherplatzes an, den der Client an die DLS-Daten in jedem Puffer anhängt, den er in den Synthesizer lädt.

Herunterladen	Set	Ziel	Eigenschaftsdeskriptortyp	Eigenschaftswerttyp
Ja	Nein	Pin	KSNODEPROPERTY	ULONG

Der Eigenschaftswert (Vorgangsdaten) ist vom Typ ULONG und gibt die Anzahl der Bytes an, die der Miniporttreiber für die eigene Verwendung am Ende jedes heruntergeladenen DLS-Datenpuffers reservieren muss. Der Client weist dann jedem Downloadpuffer so zu, dass er groß genug ist, um die angeforderte Anzahl von Bytes nach dem Ende der heruntergeladenen Daten zu enthalten.

Rückgabewert

Eine KSPROPERTY_SYNTH_DLS_APPEND-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_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.

Diese zusätzlichen Bytes sind für Treiber vorgesehen, die eine zusätzliche Auffüllung für Ausrichtungsanforderungen benötigen oder um den Start eines Beispiels zu replizieren, um die Beispielinterpolation zu vereinfachen.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_DLS_COMPACT-Eigenschaft ist eine Anforderung an den Synthesizer, den größtmöglichen Teil des freien Beispielspeichers zur Verfügung zu stellen.

Herunterladen	Set	Ziel	Eigenschaftsdeskriptortyp	Eigenschaftswerttyp
Nein	Ja	Pin	KSNODEPROPERTY	Keine

Dieser Eigenschaft sind kein Eigenschaftswert (Vorgangsdaten) zugeordnet.

Rückgabewert

Eine KSPROPERTY_SYNTH_DLS_COMPACT-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_UNSUCCESSFUL	Der Vorgang wurde nicht erfolgreich abgeschlossen.

Die Implementierung des Handlers für diese Eigenschaft sollte die Wiedergabe nicht unterbrechen.

Weitere Informationen finden Sie in der Beschreibung der IDirectMusicPort::Compact-Methode in der Microsoft Windows SDK-Dokumentation.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_DLS_DOWNLOAD-Eigenschaft wird verwendet, um DLS-Daten auf den Synthesizer herunterzuladen.

Herunterladen	Set	Ziel	Eigenschaftsdeskriptortyp	Eigenschaftswerttyp
Ja	Nein	Pin	KSNODEPROPERTY + SYNTH_BUFFER	SYNTHDOWNLOAD

Der Eigenschaftsdeskriptor (instance Daten) besteht aus einer KSNODEPROPERTY-Struktur, die unmittelbar von einer SYNTH_BUFFER-Struktur gefolgt wird, die den Speicherort und die Größe des heruntergeladenen DLS-Datenpuffers angibt.

Der Eigenschaftswert (Vorgangsdaten) ist eine SYNTHDOWNLOAD-Struktur. Der Miniporttreiber gibt die folgenden Informationen in dieser Struktur zurück:

• Ein Handle, das der Miniporttreiber generiert, um die heruntergeladenen DLS-Daten eindeutig zu identifizieren. Dieser Client sollte dieses Handle speichern und später zum Entladen der Daten verwenden (siehe KSPROPERTY_SYNTH_DLS_UNLOAD).

• Ein boolescher Wert, der angibt, ob der Client den Puffer mit den DLS-Daten nach Abschluss der Eigenschaftenanforderung freigeben kann. Wenn der Miniporttreiber eine eigene Kopie der DLS-Daten erstellt hat, kann der Client den Puffer freigeben. Andernfalls sollte der Client, wenn der Miniporttreiber weiterhin den ursprünglichen DLS-Datenpuffer des Clients verwendet, den Puffer erst dann freigeben, wenn der Miniporttreiber die DLS-Daten entladen hat.

Rückgabewert

Eine KSPROPERTY_SYNTH_DLS_DOWNLOAD-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_NO_MEMORY	Für diese Anforderung steht kein Arbeitsspeicher zur Verfügung.

Weitere Informationen finden Sie in der Microsoft Windows SDK-Dokumentation zur IDirectMusicPort::D ownloadInstrument-Methode.

Beispiel

Die KSPROPERTY_SYNTH_DLS_DOWNLOAD-Eigenschaftsanforderung gibt den Speicherort der DLS-Downloaddaten mit einer Benutzerspeicheradresse an. Der Miniporttreiber sollte den Benutzerspeicher mit den DLS-Daten testen und sperren, bevor er versucht, darauf zuzugreifen. Der folgende Beispielcode veranschaulicht dies:

  NTSTATUS Status = STATUS_UNSUCCESSFUL;
  PSYNTH_BUFFER pDlsBuffer = (PSYNTH_BUFFER)pRequest->Instance;
  PMDL pMdl = IoAllocateMdl(pDlsBuffer->BufferAddress, pDlsBuffer->BufferSize,
                            FALSE, FALSE, NULL);
  if (pMdl)
  {
      __try
      {
          MmProbeAndLockPages(pMdl, KernelMode, IoReadAccess);
          PVOID pvUserData = MmGetSystemAddressForMdlSafe(pMdl, NormalPagePriority);
 
         // do something with the data here
      }
      __except (EXCEPTION_EXECUTE_HANDLER)
      {
          Status = GetExceptionCode();
      }
 
      MmUnlockPages(pMdl);
      IoFreeMdl(pMdl);
  }
  else
  {
      Status = STATUS_NO_MEMORY;
  }

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_DLS_UNLOAD-Eigenschaft entladen eine DLS-Datenressource, die zuvor heruntergeladen wurde.

Herunterladen	Set	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Nein	Ja	Pin	KSNODEPROPERTY	HANDLE

Der Eigenschaftswert (Vorgangsdaten) ist vom Typ HANDLE und enthält das Handle der heruntergeladenen DLS-Datenressource, die freigegeben werden soll. Dies ist das Handle, das der Miniporttreiber generiert hat, um die DLS-Daten in einer vorherigen KSPROPERTY_SYNTH_DLS_DOWNLOADget-property-Anforderung zu identifizieren.

Rückgabewert

Eine KSPROPERTY_SYNTH_DLS_UNLOAD-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_PENDING	Der Vorgang wird zu einem späteren Zeitpunkt abgeschlossen.

Der Miniporttreiber sollte die DLS-Daten entladen, sobald keine Notizen wiedergegeben werden, die die DLS-Daten verwenden. Wenn der Synthesizer den der DLS-Datenressource zugeordneten Arbeitsspeicher zum Zeitpunkt der KSPROPERTY_SYNTH_DLS_UNLOAD Set-Property-Anforderung nicht freigeben kann, kann er die asynchrone Eigenschaftenvervollständigung verwenden, um die Anforderung zu einem späteren Zeitpunkt abzuschließen.

Wenn der Synthesizer nach dem Entladen der DLS-Datenressource ein Hinweisereignis empfängt, das die Ressource verwendet, sollte der Miniporttreiber das Ereignis ignorieren, es sei denn, in der Zwischenzeit wurde eine neue DLS-Datenressource heruntergeladen.

Weitere Informationen finden Sie in der Microsoft Windows SDK-Dokumentation zur IDirectMusicPort::UnloadInstrument-Methode.

Nutzungszusammenfassungstabelle

Die KSPROPERTY_SYNTH_DLS_WAVEFORMAT-Eigenschaft wird verwendet, um den Synthesizer nach seinem Ausgabewellenformat abzufragen.

Herunterladen	Set	Ziel	Eigenschaftendeskriptortyp	Eigenschaftswerttyp
Ja	Nein	Pin	KSNODEPROPERTY	WAVEFORMATEX

Der Eigenschaftswert (Vorgangsdaten) ist vom Typ WAVEFORMATEX und gibt das Wellenformat des Ausgabestreams des Synthesizers an.

Rückgabewert

Eine KSPROPERTY_SYNTH_DLS_WAVEFORMAT-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.

Ein Eigenschaft-Wert-Puffer von sizeof(WAVEFORMATEX)-Bytes ist möglicherweise nicht groß genug für alle Wellenformate. Beispielsweise erfordert ein Mehrkanalformat einen Puffer aus sizeof(WAVEFORMATEXTENSIBLE)-Bytes. Wenn die Eigenschaftenanforderung einen status Code von STATUS_BUFFER_TOO_SMALL zurückgibt, kann der Client die Vom Miniporttreiber ausgegebene Eigenschaftswertgröße überprüfen, einen größeren Puffer zuordnen und dann eine zweite Anforderung übermitteln.

Weitere Informationen finden Sie in der Beschreibung der IDirectMusicPort::GetFormat-Methode in der Microsoft Windows SDK-Dokumentation.