KSPROPSETID_Synth_Dls

Il KSPROPSETID_Synth_Dls set di proprietà contiene proprietà utilizzate per scaricare esempi e strumenti DLS in un sintetizzatore MIDI. Queste sono le proprietà di un nodo synth (KSNODETYPE_SYNTHESIZER) su un pin DirectMusic di un filtro DirectMusic (vedi FILTRI MIDI e DirectMusic).

Questa sezione descrive il comportamento di queste proprietà in relazione al modo in cui scaricano e scaricano "blocchi" di memoria contenente dati DLS. Il formato effettivo dello strumento scaricato e dei blocchi di dati wave viene specificato nella discussione dls di basso livello nella documentazione di Microsoft Windows SDK.

I download e gli scaricamenti di DLS possono verificarsi in qualsiasi momento durante l'esistenza del pin. A differenza degli eventi DirectMusic, non vengono contrassegnati come timestamp e devono essere elaborati il prima possibile.

In questa sezione il termine risorsa DLS o semplicemente risorsa si riferisce a un blocco dello strumento DLS o a un blocco d'onda DLS. Il sistema gestisce correttamente i conteggi dei riferimenti su tutte le risorse DLS:

• Quando un client scarica l'ultimo strumento che fa riferimento a un'onda, il sistema genera automaticamente una chiamata per scaricare l'onda.

• Al contrario, il sistema sfida la chiamata a scaricare un'onda fino a quando il client scarica l'ultimo strumento che fa riferimento all'onda.

Gli elementi delle proprietà in questo set vengono specificati da KSPROPERTY_SYNTH_DLS valori di enumerazione, come definito nel file di intestazione Dmusprop.h.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_DLS_APPEND specifica la quantità di spazio di archiviazione riservato che il client aggiunge ai dati DLS in ogni buffer scaricato nel sintetizzatore.

Recupero	Set	Destinazione	Tipo di descrittore di proprietà	Tipo valore proprietà
Sì	No	Aggiungi (Blocca)	KSNODEPROPERTY	ULONG

Il valore della proprietà (dati dell'operazione) è di tipo ULONG e specifica il numero di byte che il driver miniport deve riservare per il proprio utilizzo alla fine di ogni buffer di dati DLS scaricato. Il client alloca quindi ogni buffer di download per essere sufficientemente grande da contenere il numero di byte richiesto dopo la fine dei dati scaricati.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_DLS_APPEND restituisce STATUS_SUCCESS per indicare che è stata completata correttamente. In caso contrario, la richiesta restituisce un codice di stato di errore appropriato. La tabella seguente illustra alcuni dei possibili codici di errore.

Codice di stato	Significato
STATUS_UNSUCCESSFUL	L'operazione non è stata completata correttamente.

Questi byte aggiuntivi sono destinati ai driver che necessitano di spaziatura interna aggiuntiva per i requisiti di allineamento o per replicare l'inizio di un campione per semplificare l'interpolazione di campioni.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_DLS_COMPACT è una richiesta per il sintetizzatore per rendere disponibile il blocco più grande possibile di memoria di esempio disponibile.

Recupero	Set	Destinazione	Tipo di descrittore di proprietà	Tipo valore proprietà
No	Sì	Aggiungi (Blocca)	KSNODEPROPERTY	Nessuno

Nessun valore della proprietà (dati dell'operazione) è associato a questa proprietà.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_DLS_COMPACT restituisce STATUS_SUCCESS per indicare che è stata completata correttamente. In caso contrario, la richiesta restituisce un codice di stato di errore appropriato. La tabella seguente illustra alcuni dei possibili codici di errore.

Codice di stato	Significato
STATUS_UNSUCCESSFUL	L'operazione non è stata completata correttamente.

L'implementazione del gestore per questa proprietà non deve interrompere la riproduzione.

Per altre informazioni, vedere la descrizione del metodo IDirectMusicPort::Compact nella documentazione di Microsoft Windows SDK.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_DLS_DOWNLOAD viene usata per scaricare i dati DLS nel sintetizzatore.

Recupero	Set	Destinazione	Tipo di descrittore di proprietà	Tipo valore proprietà
Sì	No	Aggiungi (Blocca)	KSNODEPROPERTY + SYNTH_BUFFER	SYNTHDOWNLOAD

Il descrittore di proprietà (dati dell'istanza) è costituito da una struttura KSNODEPROPERTY immediatamente seguita da una struttura SYNTH_BUFFER, che specifica la posizione e le dimensioni del buffer di dati DLS da scaricare.

Il valore della proprietà (dati dell'operazione) è una struttura SYNTHDOWNLOAD. Il driver miniport restituisce le informazioni seguenti in questa struttura:

• Handle generato dal driver miniport per identificare in modo univoco i dati DLS scaricati. Questo client deve salvare questo handle e usarlo in un secondo momento per scaricare i dati (vedere KSPROPERTY_SYNTH_DLS_UNLOAD).

• Valore booleano che indica se il client può liberare il buffer contenente i dati DLS al termine della richiesta di proprietà. Se il driver miniport ha creato la propria copia dei dati DLS, il client può liberare il buffer. In caso contrario, se il driver miniport continua a usare il buffer di dati DLS originale del client, il client non deve liberare il buffer finché il driver miniport scarica i dati DLS.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_DLS_DOWNLOAD restituisce STATUS_SUCCESS per indicare che è stata completata correttamente. In caso contrario, la richiesta restituisce un codice di stato di errore appropriato. La tabella seguente illustra alcuni dei possibili codici di errore.

Codice di stato	Significato
STATUS_BUFFER_TOO_SMALL	Il buffer era troppo piccolo per completare l'operazione.
STATUS_UNSUCCESSFUL	L'operazione non è stata completata correttamente.
STATUS_NO_MEMORY	Nessuna memoria disponibile per completare questa richiesta.

Per altre informazioni, vedere la discussione sul metodo IDirectMusicPort::D ownloadInstrument nella documentazione di Microsoft Windows SDK.

Esempio

La richiesta di proprietà KSPROPERTY_SYNTH_DLS_DOWNLOAD specifica il percorso dei dati di download DLS con un indirizzo di memoria utente. Il driver miniport deve eseguire il probe e bloccare la memoria utente contenente i dati DLS prima di tentare di accedervi. Il codice di esempio seguente illustra come eseguire questa operazione:

  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;
  }

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_DLS_UNLOAD scarica una risorsa dati DLS scaricata in precedenza.

Recupero	Set	Destinazione	Tipo di descrittore di proprietà	Tipo valore proprietà
No	Sì	Aggiungi (Blocca)	KSNODEPROPERTY	HANDLE

Il valore della proprietà (dati dell'operazione) è di tipo HANDLE e contiene l'handle della risorsa dati DLS scaricata che deve essere liberata. Si tratta dell'handle generato dal driver miniport per identificare i dati DLS in una precedente richiesta di KSPROPERTY_SYNTH_DLS_DOWNLOADget-property.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_DLS_UNLOAD restituisce STATUS_SUCCESS per indicare che è stata completata correttamente. In caso contrario, la richiesta restituisce un codice di stato di errore appropriato. La tabella seguente illustra alcuni dei possibili codici di errore.

Codice di stato	Significato
STATUS_BUFFER_TOO_SMALL	Il buffer era troppo piccolo per completare l'operazione.
STATUS_UNSUCCESSFUL	L'operazione non è stata completata correttamente.
STATUS_PENDING	L'operazione verrà completata in un secondo momento.

Il driver miniport dovrebbe scaricare i dati DLS non appena non sono presenti note che usano i dati DLS. Se il sintetizzatore non è in grado di liberare la memoria associata alla risorsa dati DLS al momento della richiesta di proprietà set-KSPROPERTY_SYNTH_DLS_UNLOAD, può usare il completamento asincrono della proprietà per completare la richiesta in un secondo momento.

Se, dopo lo scaricamento della risorsa dati DLS, il sintetizzatore riceve un evento di nota che usa la risorsa, il driver miniport deve ignorare l'evento a meno che non sia stata scaricata una nuova risorsa dati DLS nel frattempo.

Per altre informazioni, vedere la discussione del metodo IDirectMusicPort::UnloadInstrument nella documentazione di Microsoft Windows SDK.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_DLS_WAVEFORMAT viene usata per eseguire una query sul sintetizzatore per il formato dell'onda di output.

Recupero	Set	Destinazione	Tipo di descrittore di proprietà	Tipo valore proprietà
Sì	No	Aggiungi (Blocca)	KSNODEPROPERTY	WAVEFORMATEX

Il valore della proprietà (dati dell'operazione) è di tipo WAVEFORMATEX e specifica il formato d'onda del flusso di output del sintetizzatore.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_DLS_WAVEFORMAT restituisce STATUS_SUCCESS per indicare che è stata completata correttamente. In caso contrario, la richiesta restituisce un codice di stato di errore appropriato. La tabella seguente illustra alcuni dei possibili codici di errore.

Codice di stato	Significato
STATUS_BUFFER_TOO_SMALL	Il buffer era troppo piccolo per completare l'operazione.

Un buffer di valori di proprietà di byte sizeof(WAVEFORMATEX) potrebbe non essere sufficientemente grande per tutti i formati di onda. Ad esempio, un formato multicanale richiede un buffer di byte sizeof(WAVEFORMATEXTENSIBLE). Se la richiesta di proprietà restituisce un codice di stato di STATUS_BUFFER_TOO_SMALL, il client può controllare le dimensioni del valore della proprietà restituite dal driver miniport, allocare un buffer più grande e quindi inviare una seconda richiesta.

Per altre informazioni, vedere la descrizione del metodo IDirectMusicPort::GetFormat nella documentazione di Microsoft Windows SDK.