KSPROPSETID_Synth_Dls

Le KSPROPSETID_Synth_Dls jeu de propriétés contient des propriétés utilisées pour télécharger des exemples et des instruments DLS sur un synthétiseur MIDI. Il s’agit des propriétés d’un nœud de synthèse (KSNODETYPE_SYNTHESIZER) sur une broche DirectMusic d’un filtre DirectMusic (voir Filtres MIDI et DirectMusic).

Cette section décrit le comportement de ces propriétés en ce qui concerne la façon dont elles téléchargent et déchargent des « blocs » de mémoire contenant des données DLS. Le format réel des blocs de données d’instrument et d’onde téléchargés est spécifié dans la discussion DLS de bas niveau dans la documentation Microsoft Windows SDK.

Les téléchargements et déchargements DLS peuvent se produire à tout moment pendant l’existence de l’épingle. Contrairement aux événements DirectMusic, ils ne sont pas horodatés et doivent être traités dès que possible.

Dans cette section, le terme ressource DLS, ou simplement ressource, fait référence à un segment d’instrument DLS ou à un bloc d’ondeS DLS. Le système gère correctement le nombre de références sur toutes les ressources DLS :

• Lorsqu’un client décharge le dernier instrument référençant une onde, le système génère automatiquement un appel pour décharger la vague.

• À l’inverse, le système reporte l’appel pour décharger une onde jusqu’à ce que le client décharge le dernier instrument référençant l’onde.

Les éléments de propriété dans ce jeu sont spécifiés par KSPROPERTY_SYNTH_DLS 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_DLS_APPEND spécifie la quantité d’espace de stockage réservé que le client ajoute aux données DLS dans chaque mémoire tampon qu’il télécharge sur le synthétiseur.

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

La valeur de propriété (données d’opération) est de type ULONG et spécifie le nombre d’octets que le pilote miniport doit réserver pour sa propre utilisation à la fin de chaque mémoire tampon de données DLS téléchargée. Le client alloue ensuite chaque mémoire tampon de téléchargement à une taille suffisante pour contenir le nombre d’octets demandé après la fin des données téléchargées.

Valeur de retour

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

Code d’état	Signification
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.

Ces octets supplémentaires sont destinés aux pilotes qui ont besoin d’un remplissage supplémentaire pour les exigences d’alignement ou pour répliquer le début d’un exemple afin de simplifier l’interpolation de l’échantillon.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_DLS_COMPACT est une demande pour que le synthétiseur rende disponible le plus grand nombre possible de mémoire d’exemple libre.

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

Aucune valeur de propriété (données d’opération) n’est associée à cette propriété.

Valeur de retour

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

Code d’état	Signification
STATUS_UNSUCCESSFUL	L’opération ne s’est pas terminée correctement.

L’implémentation du gestionnaire pour cette propriété ne doit pas interrompre la lecture.

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

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_DLS_DOWNLOAD est utilisée pour télécharger des données DLS sur le synthétiseur.

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

Le descripteur de propriété (instance données) se compose d’une structure KSNODEPROPERTY qui est immédiatement suivie d’une structure de SYNTH_BUFFER, qui spécifie l’emplacement et la taille de la mémoire tampon de données DLS en cours de téléchargement.

La valeur de propriété (données d’opération) est une structure SYNTHDOWNLOAD. Le pilote miniport renvoie les informations suivantes dans cette structure :

• Handle que le pilote miniport génère pour identifier de manière unique les données DLS téléchargées. Ce client doit enregistrer ce handle et l’utiliser ultérieurement pour décharger les données (voir KSPROPERTY_SYNTH_DLS_UNLOAD).

• Valeur booléenne qui indique si le client peut libérer la mémoire tampon contenant les données DLS une fois la demande de propriété terminée. Si le pilote miniport a créé sa propre copie des données DLS, le client peut libérer la mémoire tampon. Sinon, si le pilote miniport continue d’utiliser la mémoire tampon de données DLS d’origine du client, le client ne doit pas libérer la mémoire tampon tant que le pilote miniport n’a pas déchargé les données DLS.

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_DLS_DOWNLOAD retourne STATUS_SUCCESS pour indiquer qu’elle s’est terminée avec succès. Sinon, la requête 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_NO_MEMORY	Aucune mémoire n’est disponible pour effectuer cette demande.

Pour plus d’informations, consultez la présentation de la méthode IDirectMusicPort::D ownloadInstrument dans la documentation Microsoft Windows SDK.

Exemple

La demande de propriété KSPROPERTY_SYNTH_DLS_DOWNLOAD spécifie l’emplacement des données de téléchargement DLS avec une adresse mémoire utilisateur. Le pilote miniport doit sonder et verrouiller la mémoire utilisateur contenant les données DLS avant de tenter d’y accéder. L’exemple de code suivant montre comment procéder :

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

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_DLS_UNLOAD décharge une ressource de données DLS précédemment téléchargée.

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

La valeur de propriété (données d’opération) est de type HANDLE et contient le handle de la ressource de données DLS téléchargée qui doit être libérée. Il s’agit du handle que le pilote miniport a généré pour identifier les données DLS dans une demande get-property KSPROPERTY_SYNTH_DLS_DOWNLOADprécédente.

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_DLS_UNLOAD 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_PENDING	L’opération se terminera ultérieurement.

Le pilote miniport doit décharger les données DLS dès qu’aucune note n’utilise les données DLS. Si le synthétiseur n’est pas en mesure de libérer la mémoire associée à la ressource de données DLS au moment de l’KSPROPERTY_SYNTH_DLS_UNLOAD demande set-property, il peut utiliser la saisie semi-automatique asynchrone pour terminer la demande ultérieurement.

Si, après avoir déchargé la ressource de données DLS, le synthétiseur reçoit un événement de note qui utilise la ressource, le pilote miniport doit ignorer l’événement, sauf si une nouvelle ressource de données DLS a été téléchargée entre-temps.

Pour plus d’informations, consultez la discussion sur la méthode IDirectMusicPort::UnloadInstrument dans la documentation Microsoft Windows SDK.

Tableau récapitulatif de l’utilisation

La propriété KSPROPERTY_SYNTH_DLS_WAVEFORMAT est utilisée pour interroger le synthétiseur pour son format d’onde de sortie.

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

La valeur de propriété (données d’opération) est de type WAVEFORMATEX et spécifie le format d’onde du flux de sortie du synthétiseur.

Valeur de retour

Une demande de propriété KSPROPERTY_SYNTH_DLS_WAVEFORMAT 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.

Une mémoire tampon de valeur de propriété d’octets sizeof(WAVEFORMATEX) peut ne pas être assez grande pour tous les formats wave. Par exemple, un format multicanal nécessite une mémoire tampon de tailleof(WAVEFORMATEXTENSIBLE) octets. Si la demande de propriété retourne un code status de STATUS_BUFFER_TOO_SMALL, le client peut case activée la taille de la valeur de propriété que génère le pilote miniport, allouer une mémoire tampon plus importante, puis envoyer une deuxième demande.

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