IXAudio2::CreateMasteringVoice-Methode (xaudio2.h)

Artikel
08/28/2023

Erstellt und konfiguriert eine Masterstimme.

Syntax

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

Parameter

[out] ppMasteringVoice

Bei erfolgreicher Ausführung wird ein Zeiger auf das neue IXAudio2MasteringVoice-Objekt zurückgegeben.

[in] InputChannels

Anzahl der Kanäle, die die Masterstimme in ihrem Eingabeaudio erwartet. InputChannels müssen kleiner oder gleich XAUDIO2_MAX_AUDIO_CHANNELS sein.

Sie können InputChannels auf XAUDIO2_DEFAULT_CHANNELS festlegen, was dazu führt, dass XAudio2 versucht, die Systemlautsprecherkonfiguration zu erkennen.

[in] InputSampleRate

Abtastrate der Eingabe-Audiodaten der Masterstimme. Diese Rate muss ein Vielfaches von XAUDIO2_QUANTUM_DENOMINATOR sein. InputSampleRate muss zwischen XAUDIO2_MIN_SAMPLE_RATE und XAUDIO2_MAX_SAMPLE_RATE.

Sie können InputSampleRate auf XAUDIO2_DEFAULT_SAMPLERATE festlegen, wobei der Standardwert von der aktuellen Plattform bestimmt wird.

Windows XP ist standardmäßig 44100.

Windows Vista und Windows 7 verwenden standardmäßig die Einstellung, die im Sound Systemsteuerung angegeben ist. Der Standardwert für diese Einstellung ist 44100 (oder 48000, falls vom Treiber erforderlich).

Flags

[in] Flags

Flags, die das Verhalten der Masterstimme angeben. Dies kann 0 oder XAUDIO2_NO_VIRTUAL_AUDIO_CLIENTsein.

[in] szDeviceId

Bezeichner des Geräts, das die Ausgabeaudio empfangen soll. Wenn Sie den Standardwert NULL angeben, wählt XAudio2 das globale Standardaudiogerät aus. Ab Windows 10 wird NULL auch für den virtualisierten WASAPI-Client aktiviert, es sei dennXAUDIO2_NO_VIRTUAL_AUDIO_CLIENT, es wird in Flags übergeben.

[in, optional] pEffectChain

Zeiger auf eine XAUDIO2_EFFECT_CHAIN Struktur, die eine Effektkette beschreibt, die in der Masterstimme verwendet werden soll, oder NULL, um keine Effekte zu verwenden.

[in, optional] StreamCategory

Die Audiostreamkategorie, die für diese Masterstimme verwendet werden soll.

Rückgabewert

Gibt bei erfolgreicher Ausführung S_OK zurück. andernfalls ein Fehlercode. Gibt ERROR_NOT_FOUND zurück, wenn kein Standardaudiogerät vorhanden ist und NULL als szDeviceId-Parameter übergeben wird.

Beschreibungen von XAudio2-spezifischen Fehlercodes finden Sie unter XAudio2-Fehlercodes.

Hinweise

Master-Stimmen erhalten die Ausgabe einer oder mehrerer Quell- oder Submixstimmstimden. Sie verarbeiten die Daten und senden sie an das Audioausgabegerät.

In der Regel sollten Sie eine Masterstimme mit einer Eingabe-Samplerate erstellen, die von der Mehrheit der Audioinhalte des Titels verwendet wird. Die Masterstimme führt eine Konvertierung der Abtastrate von dieser Eingabe-Abtastrate in die tatsächliche Geräteausgaberate durch.

Sie können keine Quell- oder Submixstimme erstellen, bis eine Masterstimme vorhanden ist. Sie können eine Masterstimme nicht zerstören, wenn noch Quell- oder Submixstimme vorhanden sind.

Mastering-Stimmen werden immer nach allen Quell- und Submixstimmstimden verarbeitet. Dies bedeutet, dass Sie keinen ProcessingStage-Parameter angeben müssen, um die Verarbeitungsreihenfolge zu steuern.

Mit XAudio2 kann nur eine Masterstimme gleichzeitig vorhanden sein. Wenn Sie versuchen, mehr als eine Stimme zu erstellen, wird XAUDIO2_E_INVALID_CALL zurückgegeben. Wenn eine zusätzliche Masterstimme benötigt wird, z. B. für ein Ausgabegerät mit einer anderen Audiokategorie, müssen Sie eine zusätzliche XAudio2-instance erstellen.

Beim ersten Erstellen befinden sich mastering voices im Startzustand.

Es ist ungültig, CreateMasteringVoice innerhalb eines Rückrufs (also IXAudio2EngineCallback oder IXAudio2VoiceCallback) aufzurufen. Wenn Sie CreateMasteringVoice innerhalb eines Rückrufs aufrufen, wird XAUDIO2_E_INVALID_CALL zurückgegeben.

Die XAUDIO2_EFFECT_CHAIN , die als pEffectChain-Argument übergeben wird, und alle darin enthaltenen XAUDIO2_EFFECT_DESCRIPTOR Informationen werden nach dem erfolgreichen Abschluss von CreateMasteringVoice nicht mehr benötigt und können sofort nach dem Aufruf von CreateMasteringVoice gelöscht werden.

Beachten Sie, dass das DirectX SDK XAUDIO2 Version von CreateMasteringVoice ein DeviceIndex-Argument anstelle einer szDeviceId und eines StreamCategory-Arguments verwendet hat. Dies spiegelt die Änderungen wider, die für das Windows-Standardgeräteaufzählungsmodell erforderlich sind.