KSPROPSETID_Synth

Il KSPROPSETID_Synth set di proprietà contiene proprietà globali alla configurazione di un nodo synth (KSNODETYPE_SYNTHESIZER).

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

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_CAPS viene usata dal sistema per determinare le funzionalità di un sintetizzatore.

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

Il valore della proprietà (dati dell'operazione) è una struttura di tipo SYNTHCAPS e specifica le funzionalità del sintetizzatore. Queste funzionalità includono:

• Quantità di memoria di esempio disponibile

• Numero massimo di gruppi di canali

• Numero massimo di voci

• Numero massimo di canali audio

• Effetti di rendering

Per altre informazioni, vedere SYNTHCAPS.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_CAPS restituisce STATUS_SUCCESS per indicare che è stata completata correttamente. In caso contrario, la richiesta restituisce un codice di stato di errore appropriato.

Per altre informazioni sulle funzionalità del sintetizzatore, vedere il metodo IDirectMusicPort::GetCaps e la struttura DMUS_PORTCAPS nella documentazione di Microsoft Windows SDK.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_CHANNELGROUPS viene usata dal sistema per impostare o ottenere il numero di gruppi di canali attivi nell'istanza del pin. I gruppi di canali sono numerati, a partire da zero, in ogni istanza del pin.

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

Il valore della proprietà (dati operazione) è di tipo ULONG e specifica il numero di gruppi di canali supportati dal pin. Se un pin supporta n gruppi di canali, i gruppi di canali nel pin vengono numerati da 0 a n-1.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_CAPS 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 mostra 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.

Per altre informazioni sui gruppi di canali, vedere le descrizioni dei metodi IDirectMusicPort::GetNumChannelGroups e IDirectMusicPort::SetNumChannelGroups nella documentazione di Microsoft Windows SDK.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_LATENCYCLOCK viene usata per eseguire query sul driver miniport per l'ora di latenza corrente del flusso, che è sempre maggiore dell'ora dell'orologio master.

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

Il valore della proprietà (dati dell'operazione) è di tipo ULONGlong e rappresenta il tempo di latenza corrente del sintetizzatore. Questa ora viene specificata rispetto all'orologio master e espressa in unità da 100 nanosecondi.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_LATENCYCLOCK 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 mostra 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_INVALID_DEVICE_REQUEST	L'operazione non è valida per questo dispositivo.

I clock di latenza vengono in genere usati per sincronizzare i flussi di output audio tra più dispositivi.

Una richiesta di KSPROPERTY_SYNTH_LATENCYCLOCK get-property deve restituire un'ora di latenza uguale all'ora dell'orologio master corrente, oltre alla latenza minima garantita del filtro audio passato dal flusso. Un programma applicazione che pianifica la riproduzione dei dati audio in precedenza rispetto all'ora di latenza corrente rischia di avere i dati riprodotti in ritardo.

Per altre informazioni sugli orologi di latenza, vedere quanto segue:

• Discussione della proprietà KSPROPERTY_SYNTH_LATENCYCLOCK in Clock di latenza.

• Le descrizioni dei metodi IDirectMusicPort::GetLatencyClock e IReferenceClock::GetTime nella documentazione di Microsoft Windows SDK.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_PORTPARAMETERS viene usata per ottenere i parametri di configurazione per una porta DirectMusic, ovvero un termine DirectMusic per un dispositivo che invia o riceve dati musicali. Nella terminologia KS la porta DirectMusic non corrisponde a un driver di porta DMus. Corrisponde a un pin di rendering o acquisizione su un filtro DirectMusic.

Recupero	Set	Destinazione	Tipo di descrittore delle proprietà	Tipo di valore della proprietà
Sì	No	Aggiungi (Blocca)	KSNODEPROPERTY + SYNTH_PORTPARAMS	SYNTH_PORTPARAMS

Il descrittore di proprietà (dati dell'istanza) è costituito da una struttura KSNODEPROPERTY immediatamente seguita da una struttura SYNTH_PORTPARAMS. Prima di inviare la richiesta di proprietà, il client specifica i valori dei parametri richiesti scrivendoli nella struttura SYNTH_PORTPARAMS.

Anche il valore della proprietà (dati dell'operazione) è di tipo SYNTH_PORTPARAMS. Il driver miniport carica questa struttura con i valori dei parametri effettivamente usati per configurare la porta.

Valore restituito

Se il driver miniport riesce a configurare la porta DirectMusic esattamente come specificato dal chiamante, restituisce il codice STATUS_SUCCESS. In caso contrario, restituisce un codice di errore appropriato. La tabella seguente indica alcuni dei possibili codici di stato di errore.

Codice di stato	Significato
STATUS_NOT_ALL_ASSIGNED	L'operazione è riuscita, ma il driver miniport doveva modificare uno o più valori dei parametri contrassegnati dal chiamante come valido nel valore della proprietà.
STATUS_UNSUCCESSFUL	L'operazione non è stata completata correttamente.

Questo è il più complicato degli elementi della proprietà DirectMusic da gestire. Anche se questa proprietà supporta solo la richiesta get, la richiesta get imposta anche i parametri della porta. La porta passa una struttura SYNTH_PORTPARAMS come descrittore di proprietà per la richiesta di proprietà. Un buffer property-value accompagna la richiesta di proprietà, ma poiché si tratta di una richiesta get, il buffer viene usato solo per recuperare informazioni dal driver miniport.

Il driver miniport deve prima copiare la struttura SYNTH_PORTPARAMS dal descrittore di proprietà nel buffer property-value. Successivamente, verificare se è in grado di supportare tutti i valori dei parametri richiesti dal chiamante (contrassegnato come valido). Se il driver miniport non è in grado di supportare uno o più valori dei parametri richiesti, deve sovrascrivere (nella struttura SYNTH_PORTPARAMS nel buffer dei valori della proprietà) i valori richiesti per questi parametri specifici con i valori che può supportare.

Se il driver miniport non apporta modifiche al SYNTH_PORTPARAMS del chiamante, il chiamante dovrebbe recuperare un valore di proprietà che corrisponde esattamente ai parametri nel descrittore di proprietà che il chiamante ha originariamente inviato al driver miniport.

Per convenzione, il driver compila anche i valori per i parametri che non hanno bit corrispondenti impostati nel membro dwValidParams di SYNTH_PORTPARAMS. In questo modo il chiamante può visualizzare i valori predefiniti usati dal driver miniport per questi parametri. Il driver miniport restituisce i valori effettivi dei parametri usati per compilare il dispositivo con interfaccia wave.

Il gestore KSPROPERTY_SYNTH_PORTPARAMETERS del driver miniport deve essere preparato per gestire correttamente le richieste di modifiche alla frequenza di campionamento.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_RUNNINGSTATS viene usata per eseguire una query sul driver miniport per le statistiche delle prestazioni del sintetizzatore.

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

Il valore della proprietà (dati dell'operazione) è una struttura di tipo SYNTH_STATS. Il gestore delle proprietà del driver miniport scrive le statistiche seguenti in questa struttura:

• Numero medio di voci in riproduzione

• Utilizzo CPU

• Numero di note perse

• Quantità di memoria libera

• Livello di volume di picco

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_RUNNINGSTATS 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_INVALID_DEVICE_REQUEST	L'operazione non è valida per il dispositivo.

Le statistiche sulle prestazioni del sintetizzatore vengono aggiornate continuamente mentre il dispositivo rimane nello stato KSSTATE_RUN. Ogni volta che il dispositivo entra in questo stato, reimposta le statistiche, che azzera valori cumulativi, ad esempio il volume di picco e il numero di note perse.

Per altre informazioni, vedere la descrizione del metodo IDirectMusicPort::GetRunningStats e la struttura DMUS_SYNTHSTATS nella documentazione di Microsoft Windows SDK.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_VOICEPRIORITY specifica quale priorità deve avere una particolare voce in un sintetizzatore MIDI quando il driver miniport deve urtare le voci dalla cache vocale.

Recupero	Set	Destinazione	Tipo di descrittore di proprietà	Tipo valore proprietà
Sì	Sì	Aggiungi (Blocca)	KSNODEPROPERTY + SYNTHVOICEPRIORITY_INSTANCE	DWORD

Il descrittore di proprietà (dati dell'istanza) è costituito da una struttura KSNODEPROPERTY immediatamente seguita da una struttura SYNTHVOICEPRIORITY_INSTANCE, che specifica il gruppo di canali della voce (set di 16 canali MIDI) e il numero di canale (all'interno del gruppo).

Il valore della proprietà (dati dell'operazione) è un DWORD che specifica la priorità. Il client usa una KSPROPERTY_SYNTH_VOICEPRIORITY richiesta di proprietà set per inviare la nuova priorità della voce al driver miniport e usa una richiesta di KSPROPERTY_SYNTH_VOICEPRIORITY get-property per recuperare la priorità corrente della voce dal driver miniport.

Priorità vocali

Le priorità del gruppo di canale seguenti sono definite nel file di intestazione Dmusprop.h:

  DAUD_CRITICAL_VOICE_PRIORITY
  DAUD_HIGH_VOICE_PRIORITY
  DAUD_STANDARD_VOICE_PRIORITY
  DAUD_LOW_VOICE_PRIORITY
  DAUD_PERSIST_VOICE_PRIORITY

L'elenco precedente viene ordinato con la priorità più alta nella parte superiore dell'elenco e il più basso nella parte inferiore. Queste priorità sono ORed con gli offset di priorità del canale per arrivare alla priorità vocale per ogni canale all'interno di un gruppo di canali. Le priorità risultanti vengono passate nelle richieste get- e set-property.

I valori di priorità del gruppo di canali precedenti sono di grandi dimensioni rispetto agli offset di priorità del canale. Il risultato è che la modifica della priorità del gruppo di canali aumenta o riduce la priorità dell'intero gruppo di canali rispetto ad altri gruppi di canali senza modificare le priorità relative dei canali all'interno del gruppo di canali.

Priorità predefinite

Quando viene creato un driver miniport sintetizzatore, assegna una priorità predefinita a ognuna delle voci. Le impostazioni predefinite sono definite come segue:

• Per impostazione predefinita, le priorità sono uguali tra i gruppi di canali. Ciò significa, ad esempio, che channel 5 nel gruppo di canali 1 ha la stessa priorità di channel 5 nel gruppo di canali 2.

• In conformità alle specifiche DLS Level-1, canale 10 (canale percussioni MIDI) ha la priorità più alta, seguita da 1 a 9 e 11 a 16.

Il file di intestazione Dmusprop.h definisce gli offset di priorità seguenti:

  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

L'elenco precedente di offset viene ordinato con la priorità più alta nella parte superiore dell'elenco. Il file di intestazione Dmusprop.h definisce anche le priorità predefinite dei canali in ogni gruppo di canali in modo bit per bit ORing ognuno di questi offset con DAUD_STANDARD_VOICE_PRIORITY. Ad esempio, la definizione seguente dà la priorità predefinita per il canale 1 in ogni gruppo di canali:

  #define DAUD_CHAN1_DEF_VOICE_PRIORITY \
    (DAUD_STANDARD_VOICE_PRIORITY | DAUD_CHAN1_VOICE_PRIORITY_OFFSET)

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_VOICEPRIORITY 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.

Per altre informazioni sulle priorità vocali, vedere le descrizioni dei metodi IDirectMusicPort::GetChannelPriority e IDirectMusicPort::SetChannelPriority nella documentazione di Microsoft Windows SDK.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_VOLUME ottiene o imposta il livello di volume di un dispositivo sintetizzatore.

Recupero	Set	Destinazione	Tipo di descrittore di proprietà	Tipo valore proprietà
Sì	Sì	Aggiungi (Blocca)	KSPROPERTY	LONG

Il valore della proprietà (dati dell'operazione) è di tipo LONG e specifica il livello di volume del dispositivo sintetizzatore. L'impostazione del volume viene specificata in unità di 1/100simi di decibel. Il driver miniport deve modificare il volume o segnalarne il volume, a seconda che la richiesta venga recuperata o impostata.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_VOLUME 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.

Tabella riepilogo utilizzo

La proprietà KSPROPERTY_SYNTH_VOLUMEBOOST specifica la quantità in base alla quale viene incrementato il volume di un dispositivo sintetizzatore.

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

Il valore della proprietà (dati dell'operazione) è di tipo LONG e specifica in base a quanto aumentare il segnale audio dopo la fase di combinazione. Si tratta della quantità di volume da aggiungere all'output finale del sintetizzatore dopo che tutte le articolazioni vocali e la combinazione sono state completate. La quantità di aumento del volume viene specificata in 1/100simi di decibel. Questo valore può essere positivo o negativo.

Valore restituito

Una richiesta di proprietà KSPROPERTY_SYNTH_VOLUMEBOOST 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.

Nessun altro boost deve essere aggiunto all'output. Il sintetizzatore deve seguire rigide convenzioni DLS Level-1 per l'articolazione.

Questa proprietà viene usata per equalizzare il volume del sintetizzatore con altri output audio nel sistema e gli importi di boost devono quindi essere interpretati in modo coerente in tutti i dispositivi.