IxAudio2 ::CreateSourceVoice, méthode (xaudio2.h)

Article
08/28/2023

Crée et configure une voix source.

Syntaxe

HRESULT CreateSourceVoice(
  [out]          IXAudio2SourceVoice        **ppSourceVoice,
  [in]           const WAVEFORMATEX         *pSourceFormat,
  [in]           UINT32                     Flags,
  [in]           float                      MaxFrequencyRatio,
  [in, optional] IXAudio2VoiceCallback      *pCallback,
  [in, out]      const XAUDIO2_VOICE_SENDS  *pSendList,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain
);

Paramètres

[out] ppSourceVoice

En cas de réussite, retourne un pointeur vers le nouvel objet IXAudio2SourceVoice .

[in] pSourceFormat

Pointeur vers une des structures du tableau ci-dessous. Cette structure contient le format attendu pour toutes les mémoires tampons audio envoyées à la voix source. XAudio2 prend en charge les types de voix PCM et ADPCM.

Balise de format	Structure de format d’onde	Taille (en octets)
WAVE_FORMAT_PCM (0x0001)	PCMWAVEFORMAT	16
-ou-	WAVEFORMATEX	18
WAVE_FORMAT_IEEE_FLOAT (0x0003) [32 bits]	PCMWAVEFORMAT	18
WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM]	ADPCMWAVEFORMAT	50
WAVE_FORMAT_EXTENSIBLE (0xFFFE)	WAVEFORMATEXTENSIBLE	40

XAudio2 prend en charge les formats PCM suivants.

PCM entier 8 bits (non signé)
PCM entier 16 bits (format optimal pour XAudio2)
PCM entier 20 bits (dans des conteneurs 24 ou 32 bits)
PCM entier 24 bits (dans des conteneurs 24 ou 32 bits)
PCM entier 32 bits
PCM float 32 bits (format préféré après un entier 16 bits)

Le nombre de canaux dans une voix source doit être inférieur ou égal à XAUDIO2_MAX_AUDIO_CHANNELS. Le taux d’échantillonnage d’une voix source doit être compris entre XAUDIO2_MIN_SAMPLE_RATE et XAUDIO2_MAX_SAMPLE_RATE.

Note Les formats de données PCM tels que PCMWAVEFORMAT et ADPCMWAVEFORMAT qui nécessitent plus d’informations que ceux fournis par WAVEFORMATEX ont une structure WAVEFORMATEX comme premier membre de leurs structures de format. Lorsque vous créez une voix source avec l’un de ces formats, castez la structure du format en tant que structure WAVEFORMATEX et utilisez-la comme valeur pour pSourceFormat.

[in] Flags

Indicateurs qui spécifient le comportement de la voix source. Un indicateur peut être égal à 0 ou à une combinaison d’un ou plusieurs des éléments suivants :

Valeur	Description
XAUDIO2_VOICE_NOPITCH	Aucun contrôle de tonalité n’est disponible sur la voix.
XAUDIO2_VOICE_NOSRC	Aucune conversion de taux d’échantillonnage n’est disponible sur la voix. Les sorties de la voix doivent avoir le même taux d’échantillonnage. Note L’indicateur XAUDIO2_VOICE_NOSRC fait que la voix se comporte comme si l’indicateur de XAUDIO2_VOICE_NOPITCH était également spécifié.
XAUDIO2_VOICE_USEFILTER	L’effet de filtre doit être disponible sur cette voix.

Note L’indicateur XAUDIO2_VOICE_MUSIC n’est pas pris en charge sur Windows.

[in] MaxFrequencyRatio

Taux de fréquence le plus élevé autorisé pouvant être défini sur cette voix. La valeur de cet argument doit être comprise entre XAUDIO2_MIN_FREQ_RATIO et XAUDIO2_MAX_FREQ_RATIO. Les appels suivants à IXAudio2SourceVoice ::SetFrequencyRatio sont limités entre XAUDIO2_MIN_FREQ_RATIO et MaxFrequencyRatio. La valeur maximale de cet argument est définie comme XAUDIO2_MAX_FREQ_RATIO, ce qui permet d’élever la hauteur jusqu’à 10 octaves.

Si MaxFrequencyRatio est inférieur à 1,0, la voix utilise ce ratio immédiatement après sa création (plutôt que la valeur par défaut de 1,0).

Xbox 360
Pour les voix XMA, il existe une autre restriction sur l’argument MaxFrequencyRatio et le taux d’échantillonnage de la voix. Le produit de ces deux nombres ne peut pas dépasser XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO pour les voix à canal unique ou XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL pour les voix avec un autre nombre de canaux. Si la valeur spécifiée pour MaxFrequencyRatio est trop élevée pour le format spécifié, l’appel à CreateSourceVoice échoue et génère un message de débogage.

Xbox 360

Pour les voix XMA, il existe une autre restriction sur l’argument MaxFrequencyRatio et le taux d’échantillonnage de la voix. Le produit de ces deux nombres ne peut pas dépasser XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO pour les voix à canal unique ou XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL pour les voix avec un autre nombre de canaux. Si la valeur spécifiée pour MaxFrequencyRatio est trop élevée pour le format spécifié, l’appel à CreateSourceVoice échoue et génère un message de débogage.

Note Vous pouvez utiliser la valeur MaxFrequencyRatio la plus faible possible pour réduire l’utilisation de la mémoire de XAudio2.

[in, optional] pCallback

Pointeur vers une interface de rappel fournie par le client, IXAudio2VoiceCallback.

[in, out] pSendList

Pointeur vers une liste de structures XAUDIO2_VOICE_SENDS qui décrivent l’ensemble des voix de destination pour la voix source. Si pSendList a la valeur NULL, la liste d’envoi affiche par défaut une seule sortie pour la première voix de mastering créée.

[in, optional] pEffectChain

Pointeur vers une liste de structures XAUDIO2_EFFECT_CHAIN qui décrivent une chaîne d’effets à utiliser dans la voix source.

Valeur retournée

Retourne S_OK en cas de réussite ; sinon, un code d’erreur.

Consultez Codes d’erreur XAudio2 pour obtenir une description des codes d’erreur spécifiques à XAudio2.

Remarques

Les voix sources lisent les données audio du client. Ils traitent les données et les envoient au graphe de traitement XAudio2.

Une voix source inclut une conversion de taux d’échantillonnage à taux variable pour convertir des données du taux d’échantillonnage du format source vers le taux de sortie requis pour la liste d’envois vocaux. Si vous utilisez une liste d’envoi NULL, le taux d’échantillonnage cible sera le taux d’échantillonnage d’entrée de la voix de mastering. Si vous fournissez une seule voix dans pSendList, le taux d’échantillonnage d’entrée de cette voix est le taux cible. Si vous fournissez plusieurs voix dans pSendList, toutes les voix de sortie de la voix source doivent s’exécuter au même taux d’échantillonnage d’entrée.

Vous ne pouvez pas créer de voix source ou de sous-mixage tant qu’une voix de mastering n’existe pas, et vous ne pouvez pas détruire une voix de mastering si des voix sources ou sous-mix existent encore.

Les voix sources sont toujours traitées avant toute voix de sous-mixage ou de mastering. Cela signifie que vous n’avez pas besoin d’un paramètre ProcessingStage pour contrôler l’ordre de traitement.

Lors de la première création, les voix sources sont à l’état arrêté.

XAudio2 utilise un pooleur de mémoire interne pour les voix avec le même format. Cela signifie que l’allocation de mémoire pour les voix se produit moins fréquemment à mesure que davantage de voix sont créées, puis détruites. Pour réduire les allocations juste-à-temps, un titre peut créer le nombre maximal prévu de voix nécessaires à l’avance, puis les supprimer si nécessaire. Les voix seront ensuite réutilisées à partir du pool XAudio2. Le pool de mémoires est lié à un moteur XAudio2 instance. Vous pouvez récupérer toute la mémoire utilisée par un instance du moteur XAudio2 en détruisant l’objet XAudio2 et en le recréant si nécessaire (forcer le pool de mémoires à croître via la préallocation devrait être réappliqué si nécessaire).

Il n’est pas valide d’appeler CreateSourceVoice à partir d’un rappel (autrement dit, IXAudio2EngineCallback ou IXAudio2VoiceCallback). Si vous appelez CreateSourceVoice dans un rappel, il retourne XAUDIO2_E_INVALID_CALL.

Le XAUDIO2_EFFECT_CHAIN passé en tant qu’argument pEffectChain et les informations XAUDIO2_EFFECT_DESCRIPTOR qu’il contient ne sont plus nécessaires une fois createSourceVoice terminé, et peuvent être supprimés immédiatement après l’appel de CreateSourceVoice .