KSPROPSETID_Synth

Le KSPROPSETID_Synth jeu de propriétés contient des propriétés qui sont globales à la configuration d’un nœud de synthèse (KSNODETYPE_SYNTHESIZER).

Les éléments de propriété de cet ensemble sont spécifiés par KSPROPERTY_SYNTH valeurs d’énumération, telles que définies dans le fichier d’en-tête Dmusprop.h.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_CAPS est utilisée par le système pour déterminer les fonctionnalités d’un synthétiseur.

Obtenir	Définissez	Cible	Type de descripteur de propriété	Type de valeur de propriété
Oui	Non	Épingle	KSNODEPROPERTY	SYNTHCAPS

La valeur de propriété (données d’opération) est une structure de type SYNTHCAPS et spécifie les fonctionnalités du synthétiseur. Ces fonctionnalités sont les suivantes :

• Quantité de mémoire d’exemple disponible

• Nombre maximal de groupes de canaux

• Nombre maximal de voix

• Nombre maximal de canaux audio

• Effets de rendu

Pour plus d’informations, consultez SYNTHCAPS.

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_CAPS retourne STATUS_SUCCESS pour indiquer qu’elle s’est terminée avec succès. Sinon, la demande retourne une erreur appropriée status code.

Pour plus d’informations sur les fonctionnalités du synthétiseur, consultez la méthode IDirectMusicPort::GetCaps et la structure DMUS_PORTCAPS dans la documentation Microsoft Windows SDK.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_CHANNELGROUPS est utilisée par le système pour définir ou obtenir le nombre de groupes de canaux actifs sur le instance de broche. Les groupes de canaux sont numérotés, en commençant par zéro, sur chaque broche instance.

Obtenir	Définissez	Cible	Type de descripteur de propriété	Type de valeur de propriété
Oui	Oui	Épingle	KSNODEPROPERTY	ULONG

La valeur de propriété (données d’opération) est de type ULONG et spécifie le nombre de groupes de canaux pris en charge par la broche. Si une broche prend en charge n groupes de canaux, les groupes de canaux sur la broche sont numérotés de 0 à n-1.

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_CAPS retourne STATUS_SUCCESS pour indiquer qu’elle s’est terminée avec succès. Sinon, la demande retourne une erreur appropriée status code. Le tableau suivant présente certains des codes d’échec possibles.

Code d’état	Signification
STATUS_BUFFER_TOO_SMALL	La mémoire tampon était trop petite pour terminer l’opération.
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.

Pour plus d’informations sur les groupes de canaux, consultez les descriptions des méthodes IDirectMusicPort::GetNumChannelGroups et IDirectMusicPort::SetNumChannelGroups dans la documentation Microsoft Windows SDK.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_LATENCYCLOCK permet d’interroger le pilote miniport pour connaître l’heure d’horloge de latence actuelle du flux, qui est toujours supérieure à l’heure de l’horloge master.

Obtenir	Définissez	Cible	Type de descripteur de propriété	Type de valeur de propriété
Oui	Non	Épingle	KSNODEPROPERTY	ULONGLONG

La valeur de propriété (données d’opération) est de type ULONGLONG et représente le temps de latence actuel du synthétiseur. Cette durée est spécifiée par rapport à l’horloge master et exprimée en unités de 100 nanosecondes.

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_LATENCYCLOCK retourne STATUS_SUCCESS pour indiquer qu’elle s’est terminée avec succès. Sinon, la demande retourne une erreur appropriée status code. Le tableau suivant présente certains des codes d’échec possibles.

Code d’état	Signification
STATUS_BUFFER_TOO_SMALL	La mémoire tampon était trop petite pour terminer l’opération.
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.
STATUS_INVALID_DEVICE_REQUEST	L’opération n’est pas valide pour cet appareil.

Les horloges de latence sont généralement utilisées pour synchroniser les flux de sortie audio entre plusieurs appareils.

Une requête get-property KSPROPERTY_SYNTH_LATENCYCLOCK doit renvoyer une heure de latence qui est égale à l’heure actuelle de l’horloge master, plus la latence minimale garantie du filtre audio par lequel le flux passe. Un programme d’application qui planifie la lecture des données audio avant le temps d’horloge de latence actuel risque d’avoir les données lues en retard.

Pour plus d’informations sur les horloges de latence, consultez les informations suivantes :

• Discussion de la propriété KSPROPERTY_SYNTH_LATENCYCLOCK dans Horloges de latence.

• Descriptions des méthodes IDirectMusicPort::GetLatencyClock et IReferenceClock::GetTime dans la documentation Microsoft Windows SDK.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_PORTPARAMETERS est utilisée pour obtenir les paramètres de configuration d’un port DirectMusic, qui est un terme DirectMusic pour un appareil qui envoie ou reçoit des données musicales. (Dans la terminologie KS, le port DirectMusic ne correspond pas à un pilote de port DMus. Il correspond à une broche de rendu ou de capture sur un filtre DirectMusic.)

Obtenir	Définissez	Cible	Type de descripteur de propriété	Type de valeur de propriété
Oui	Non	Épingle	KSNODEPROPERTY + SYNTH_PORTPARAMS	SYNTH_PORTPARAMS

Le descripteur de propriété (instance données) se compose d’une structure KSNODEPROPERTY qui est immédiatement suivie d’une structure SYNTH_PORTPARAMS. Avant d’envoyer la demande de propriété, le client spécifie ses valeurs de paramètres demandées en les écrivant dans la structure SYNTH_PORTPARAMS.

La valeur de propriété (données d’opération) est également de type SYNTH_PORTPARAMS. Le pilote miniport charge cette structure avec les valeurs de paramètre qu’il utilise réellement pour configurer le port.

Valeur de retour

Si le pilote miniport réussit à configurer le port DirectMusic exactement comme spécifié par l’appelant, il retourne le code STATUS_SUCCESS. Sinon, il retourne un code d’erreur approprié. Le tableau suivant indique certains des codes d’erreur possibles status.

Code d’état	Signification
STATUS_NOT_ALL_ASSIGNED	L’opération a réussi, mais le pilote miniport a dû modifier une ou plusieurs des valeurs de paramètre que l’appelant a marquées comme valides dans la valeur de la propriété.
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.

Il s’agit de la plus compliquée des éléments de propriété DirectMusic à gérer. Bien que cette propriété ne prenne en charge que la demande get, la demande get définit également les paramètres de port. Le port transmet une structure de SYNTH_PORTPARAMS comme descripteur de propriété pour la demande de propriété. Une mémoire tampon de valeur de propriété accompagne la demande de propriété, mais comme il s’agit d’une demande d’obtention, la mémoire tampon est utilisée uniquement pour récupérer des informations à partir du pilote miniport.

Le pilote miniport doit d’abord copier la structure SYNTH_PORTPARAMS du descripteur de propriété vers la mémoire tampon de valeur de propriété. Ensuite, il doit case activée pour voir s’il est capable de prendre en charge toutes les valeurs de paramètre demandées par l’appelant (marquées comme valides). Si le pilote miniport ne peut pas prendre en charge une ou plusieurs des valeurs de paramètre demandées, il doit remplacer (dans la structure SYNTH_PORTPARAMS de la mémoire tampon de valeur de propriété) les valeurs demandées pour ces paramètres particuliers par les valeurs qu’il peut prendre en charge.

Si le pilote miniport n’apporte aucune modification au SYNTH_PORTPARAMS de l’appelant, l’appelant doit récupérer une valeur de propriété qui correspond exactement aux paramètres du descripteur de propriété que l’appelant a initialement envoyé au pilote miniport.

Par convention, le pilote remplit également les valeurs pour les paramètres qui n’ont pas de bits correspondants définis dans le membre dwValidParams de SYNTH_PORTPARAMS. Cela permet à l’appelant de voir quelles valeurs par défaut le pilote miniport a utilisées pour ces paramètres. Le pilote miniport génère les valeurs de paramètres réelles qu’il a utilisées pour générer l’appareil d’interface wave.

Le gestionnaire de KSPROPERTY_SYNTH_PORTPARAMETERS du pilote miniport doit être prêt à gérer correctement les demandes de modification du taux d’échantillonnage.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_RUNNINGSTATS est utilisée pour interroger le pilote miniport pour obtenir les statistiques de performances du synthétiseur.

Obtenir	Définissez	Cible	Type de descripteur de propriété	Type de valeur de propriété
Oui	Non	Épingle	KSNODEPROPERTY	SYNTH_STATS

La valeur de propriété (données d’opération) est une structure de type SYNTH_STATS. Le gestionnaire de propriétés du pilote miniport écrit les statistiques suivantes dans cette structure :

• Nombre moyen de voix en cours de lecture

• Utilisation de l’UC

• Nombre de notes perdues

• Quantité de mémoire libre

• Niveau de volume maximal

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_RUNNINGSTATS retourne STATUS_SUCCESS pour indiquer qu’elle s’est terminée avec succès. Sinon, la demande retourne une erreur appropriée status code. Le tableau suivant présente certains des codes d’erreur possibles.

Code d’état	Signification
STATUS_BUFFER_TOO_SMALL	La mémoire tampon était trop petite pour terminer l’opération.
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.
STATUS_INVALID_DEVICE_REQUEST	L’opération n’est pas valide pour cet appareil.

Les statistiques de performances du synthétiseur sont mises à jour en permanence tant que l’appareil reste à l’état KSSTATE_RUN. Chaque fois que l’appareil entre dans cet état, il réinitialise les statistiques, qui zéro les valeurs cumulatives telles que le volume de pointe et le nombre de notes perdues.

Pour plus d’informations, consultez la description de la méthode IDirectMusicPort::GetRunningStats et la structure DMUS_SYNTHSTATS dans la documentation Microsoft Windows SDK.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_VOICEPRIORITY spécifie la priorité d’une voix particulière dans un synthétiseur MIDI lorsque le pilote miniport doit faire passer les voix de son cache vocal.

Obtenir	Définissez	Cible	Type de descripteur de propriété	Type de valeur de propriété
Oui	Oui	Épingle	KSNODEPROPERTY + SYNTHVOICEPRIORITY_INSTANCE	DWORD

Le descripteur de propriété (instance données) se compose d’une structure KSNODEPROPERTY qui est immédiatement suivie d’une structure de SYNTHVOICEPRIORITY_INSTANCE, qui spécifie le groupe de canaux de la voix (ensemble de 16 canaux MIDI) et le numéro de canal (au sein du groupe).

La valeur de propriété (données d’opération) est un DWORD qui spécifie la priorité. Le client utilise une KSPROPERTY_SYNTH_VOICEPRIORITY demande set-property pour envoyer la nouvelle priorité de la voix au pilote miniport, et il utilise une KSPROPERTY_SYNTH_VOICEPRIORITY demande get-property pour récupérer la priorité actuelle de la voix à partir du pilote miniport.

Priorités vocales

Les priorités de groupe de canaux suivantes sont définies dans le fichier d’en-tête Dmusprop.h :

  DAUD_CRITICAL_VOICE_PRIORITY
  DAUD_HIGH_VOICE_PRIORITY
  DAUD_STANDARD_VOICE_PRIORITY
  DAUD_LOW_VOICE_PRIORITY
  DAUD_PERSIST_VOICE_PRIORITY

La liste précédente est triée avec la priorité la plus élevée en haut de la liste et la plus basse en bas. Ces priorités sont ORed avec les décalages de priorité de canal pour atteindre la priorité vocale pour chaque canal au sein d’un groupe de canaux. Les priorités obtenues sont transmises dans les demandes get- et set-property.

Les valeurs de priorité du groupe de canaux précédents sont importantes par rapport aux décalages de priorité du canal. Le résultat est que la modification de la priorité du groupe de canaux augmente ou diminue la priorité de l’ensemble du groupe de canaux par rapport aux autres groupes de canaux sans modifier les priorités relatives des canaux au sein du groupe de canaux.

Priorités par défaut

Lorsqu’un pilote miniport de synthétiseur est créé, il attribue une priorité par défaut à chacune de ses voix. Les valeurs par défaut sont définies comme suit :

• Par défaut, les priorités sont égales entre les groupes de canaux. Cela signifie, par exemple, que le canal 5 sur le groupe de canaux 1 a la même priorité que le canal 5 sur le groupe de canaux 2.

• Conformément aux spécifications de niveau 1 de DLS, le canal 10 (canal de percussion MIDI) a la priorité la plus élevée, suivi de 1 à 9 et de 11 à 16.

Le fichier d’en-tête Dmusprop.h définit les décalages de priorité suivants :

  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

La liste précédente des décalages est triée avec la priorité la plus élevée en haut de la liste. Le fichier d’en-tête Dmusprop.h définit également les priorités par défaut des canaux de chaque groupe de canaux en ORing au niveau du bit chacun de ces décalages avec DAUD_STANDARD_VOICE_PRIORITY. Par exemple, la définition suivante donne la priorité par défaut pour le canal 1 dans chaque groupe de canaux :

  #define DAUD_CHAN1_DEF_VOICE_PRIORITY \
    (DAUD_STANDARD_VOICE_PRIORITY | DAUD_CHAN1_VOICE_PRIORITY_OFFSET)

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_VOICEPRIORITY retourne STATUS_SUCCESS pour indiquer qu’elle s’est terminée avec succès. Sinon, la demande retourne une erreur appropriée status code. Le tableau suivant présente certains des codes d’erreur possibles.

Code d’état	Signification
STATUS_BUFFER_TOO_SMALL	La mémoire tampon était trop petite pour terminer l’opération.
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.

Pour plus d’informations sur les priorités vocales, consultez les descriptions des méthodes IDirectMusicPort::GetChannelPriority et IDirectMusicPort::SetChannelPriority dans la documentation Microsoft Windows SDK.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_VOLUME obtient ou définit le niveau de volume d’un appareil de synthétiseur.

Obtenir	Définissez	Cible	Type de descripteur de propriété	Type de valeur de propriété
Oui	Oui	Épingle	KSPROPERTY	LONG

La valeur de propriété (données d’opération) est de type LONG et spécifie le niveau de volume du périphérique de synthétiseur. Le paramètre de volume est spécifié en unités de 1/100e d’un décibel. Le pilote miniport doit modifier son volume ou signaler son volume, selon que la demande consiste à obtenir ou à définir la propriété.

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_VOLUME retourne STATUS_SUCCESS pour indiquer qu’elle s’est terminée avec succès. Sinon, la demande retourne une erreur appropriée status code. Le tableau suivant présente certains des codes d’erreur possibles.

Code d’état	Signification
STATUS_BUFFER_TOO_SMALL	La mémoire tampon était trop petite pour terminer l’opération.
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_VOLUMEBOOST spécifie la quantité d’augmentation du volume d’un appareil de synthétiseur.

Obtenir	Définissez	Cible	Type de descripteur de propriété	Type de valeur de propriété
Oui	Oui	Épingle	KSNODEPROPERTY	LONG

La valeur de propriété (données d’opération) est de type LONG et spécifie par la quantité à augmenter le signal audio après l’étape de mixage. Il s’agit de la quantité de volume à ajouter à la sortie finale du synthétiseur une fois que l’articulation et le mixage de la voix ont été terminés. La quantité d’augmentation de volume est spécifiée dans 1/100èmes d’un décibel. Cette valeur peut être positive ou négative.

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_VOLUMEBOOST retourne STATUS_SUCCESS pour indiquer qu’elle s’est terminée avec succès. Sinon, la demande retourne une erreur appropriée status code. Le tableau suivant présente certains des codes d’erreur possibles.

Code d’état	Signification
STATUS_BUFFER_TOO_SMALL	La mémoire tampon était trop petite pour terminer l’opération.
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.

Aucun autre boost ne doit être ajouté à la sortie. Le synthétiseur doit suivre des conventions strictes de niveau 1 DLS pour l’articulation.

Cette propriété est utilisée pour égaliser le volume du synthétiseur avec d’autres sorties audio dans le système, et les quantités de boost doivent donc être interprétées de manière cohérente sur tous les appareils.