Metodo IXAudio2::CreateMasteringVoice (xaudio2.h)

Articolo
03/09/2024

Crea e configura una voce mastering.

Sintassi

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

Parametri

[out] ppMasteringVoice

In caso di esito positivo, restituisce un puntatore al nuovo oggetto IXAudio2MasteringVoice .

[in] InputChannels

Numero di canali previsti dalla voce mastering nell'audio di input. InputChannels deve essere minore o uguale a XAUDIO2_MAX_AUDIO_CHANNELS.

È possibile impostare InputChannels su XAUDIO2_DEFAULT_CHANNELS, che fa sì che XAudio2 tenti di rilevare la configurazione della voce di sistema.

[in] InputSampleRate

Frequenza di campionamento dei dati audio di input della voce mastering. Questa tariffa deve essere un multiplo di XAUDIO2_QUANTUM_DENOMINATOR. InputSampleRate deve essere compreso tra XAUDIO2_MIN_SAMPLE_RATE e XAUDIO2_MAX_SAMPLE_RATE.

È possibile impostare InputSampleRate su XAUDIO2_DEFAULT_SAMPLERATE, con il valore predefinito determinato dalla piattaforma corrente.

Per impostazione predefinita, Windows XP è 44100.

Windows Vista e Windows 7 per impostazione predefinita sono l'impostazione specificata in Sound Pannello di controllo. Il valore predefinito per questa impostazione è 44100 (o 48000 se richiesto dal driver).

Flags

[in] Flags

Flag che specificano il comportamento della voce mastering. Può essere 0 o XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT.

[in] szDeviceId

Identificatore del dispositivo per ricevere l'audio di output. Se si specifica il valore predefinito NULL, XAudio2 seleziona il dispositivo audio predefinito globale. In Windows 10 o versione successiva, NULL acconsenterà anche al client virtualizzato WASAPI, a meno che non XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT venga passato in Flag.

[in, optional] pEffectChain

Puntatore a una struttura XAUDIO2_EFFECT_CHAIN che descrive una catena di effetti da utilizzare nella voce mastering o NULL per non utilizzare alcun effetto.

[in, optional] StreamCategory

Categoria del flusso audio da usare per questa voce mastering.

Valore restituito

Restituisce S_OK in caso di esito positivo; in caso contrario, un codice di errore. Restituisce ERROR_NOT_FOUND se non esiste alcun dispositivo audio predefinito e NULL viene passato come parametro szDeviceId.

Per le descrizioni dei codici di errore specifici di XAudio2, vedere Codici di errore XAudio2 .

Commenti

Le voci mastering ricevono l'output di una o più voci di origine o submix. Elaborano i dati e li inviano al dispositivo di output audio.

In genere, devi creare una voce mastering con una frequenza di campionamento di input che verrà usata dalla maggior parte del contenuto audio del titolo. La voce mastering esegue una conversione della frequenza di campionamento da questa frequenza di campionamento di input alla velocità di output effettiva del dispositivo.

Non è possibile creare voci di origine o submix finché non esiste una voce mastering. Non è possibile distruggere una voce mastering se esistono ancora voci di origine o submix.

Le voci mastering vengono sempre elaborate dopo tutte le voci di origine e submix. Ciò significa che non è necessario specificare un parametro ProcessingStage per controllare l'ordine di elaborazione.

XAudio2 consente l'esistenza di una sola voce mastering contemporaneamente. Se si tenta di creare più voci, viene restituito XAUDIO2_E_INVALID_CALL. Se è necessaria una voce mastering aggiuntiva, ad esempio per un dispositivo di output con un set di categorie audio diverso, sarà necessario creare un'istanza XAudio2 aggiuntiva.

Quando vengono create per la prima volta, le voci mastering si trovano nello stato di avvio.

Non è possibile chiamare CreateMasteringVoice dall'interno di un callback, ovvero IXAudio2EngineCallback o IXAudio2VoiceCallback. Se si chiama CreateMasteringVoice all'interno di un callback, viene restituito XAUDIO2_E_INVALID_CALL.

Il XAUDIO2_EFFECT_CHAIN passato come argomento pEffectChain e tutte le informazioni XAUDIO2_EFFECT_DESCRIPTOR contenute al suo interno non sono più necessarie al termine di CreateMasteringVoice e possono essere eliminate immediatamente dopo la chiamata a CreateMasteringVoice .

Si noti che DirectX SDK XAUDIO2 versione di CreateMasteringVoice ha preso un argomento DeviceIndex anziché uno szDeviceId e un argomento StreamCategory. Ciò riflette le modifiche necessarie per il modello di enumerazione dei dispositivi Windows standard.