IXAudio2 ::CreateMasteringVoice, méthode (xaudio2.h)

Article
03/04/2024

Crée et configure une voix de mastering.

Syntaxe

HRESULT CreateMasteringVoice(
  [out]          IXAudio2MasteringVoice     **ppMasteringVoice,
  [in]           UINT32                     InputChannels,
  [in]           UINT32                     InputSampleRate,
  [in]           UINT32                     Flags,
  [in]           LPCWSTR                    szDeviceId,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain,
  [in, optional] AUDIO_STREAM_CATEGORY      StreamCategory
);

Paramètres

[out] ppMasteringVoice

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

[in] InputChannels

Nombre de canaux attendus par la voix de mastering dans son audio d’entrée. InputChannels doit être inférieur ou égal à XAUDIO2_MAX_AUDIO_CHANNELS.

Vous pouvez définir InputChannels sur XAUDIO2_DEFAULT_CHANNELS, ce qui amène XAudio2 à essayer de détecter la configuration de l’orateur système.

[in] InputSampleRate

Taux d’échantillonnage des données audio d’entrée de la voix de mastering. Ce taux doit être un multiple de XAUDIO2_QUANTUM_DENOMINATOR. InputSampleRate doit se trouver entre XAUDIO2_MIN_SAMPLE_RATE et XAUDIO2_MAX_SAMPLE_RATE.

Vous pouvez définir InputSampleRate sur XAUDIO2_DEFAULT_SAMPLERATE, la valeur par défaut étant déterminée par la plateforme actuelle.

Windows XP est défini par défaut sur 44100.

Par défaut, Windows Vista et Windows 7 mettent en valeur le paramètre spécifié dans le Panneau de configuration audio. La valeur par défaut de ce paramètre est 44100 (ou 48 000 si nécessaire par le pilote).

Indicateurs

[in] Flags

Indicateurs qui spécifient le comportement de la voix de mastering. Il peut s’agir de 0 ou XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT.

[in] szDeviceId

Identificateur de l’appareil pour recevoir l’audio de sortie. Si vous spécifiez la valeur NULL par défaut, XAudio2 sélectionne le périphérique audio par défaut global. Sur Windows 10 ou une version ultérieure, NULL accepte également le client virtualisé WASAPI, sauf s’il XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT est passé dans indicateurs.

[in, optional] pEffectChain

Pointeur vers une structure de XAUDIO2_EFFECT_CHAIN qui décrit une chaîne d’effets à utiliser dans la voix de mastering, ou NULL pour n’utiliser aucun effet.

[in, optional] StreamCategory

Catégorie de flux audio à utiliser pour cette voix de mastering.

Valeur retournée

Retourne S_OK en cas de réussite ; sinon, un code d’erreur. Retourne ERROR_NOT_FOUND si aucun périphérique audio par défaut n’existe et que NULL est passé en tant que paramètre szDeviceId.

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

Remarques

Les voix de mastering reçoivent la sortie d’une ou plusieurs voix sources ou submix. Ils traitent les données et les envoient au périphérique de sortie audio.

En règle générale, vous devez créer une voix de mastering avec un taux d’échantillonnage d’entrée qui sera utilisé par la majorité du contenu audio du titre. La voix de mastering effectue une conversion du taux d’échantillonnage de ce taux d’échantillonnage d’entrée vers le taux de sortie réel de l’appareil.

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

Les voix de mastering sont toujours traitées après toutes les voix sources et de sous-mix. Cela signifie que vous n’avez pas besoin de spécifier un paramètre ProcessingStage pour contrôler l’ordre de traitement.

XAudio2 n’autorise qu’une seule voix de mastering à exister en même temps. Si vous tentez de créer plusieurs voix, XAUDIO2_E_INVALID_CALL est retourné. Si une voix de mastering supplémentaire est nécessaire, par exemple pour un appareil de sortie avec un autre ensemble de catégories audio, vous devez créer un instance XAudio2 supplémentaire.

Lors de la première création, les voix de mastering sont à l’état démarré.

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

Le XAUDIO2_EFFECT_CHAIN transmis en tant qu’argument pEffectChain et les informations XAUDIO2_EFFECT_DESCRIPTOR contenues dans ce dernier ne sont plus nécessaires une fois CreateMasteringVoice terminé, et peuvent être supprimés immédiatement après l’appel de CreateMasteringVoice .

Notez que le Kit de développement logiciel (SDK) DirectX XAUDIO2 version de CreateMasteringVoice a pris un argument DeviceIndex au lieu d’un argument szDeviceId et d’un argument StreamCategory. Cela reflète les modifications nécessaires pour le modèle d’énumération d’appareil Windows standard.