IXAudio2::CreateSourceVoice-Methode (xaudio2.h)

Artikel
08/28/2023

Erstellt und konfiguriert eine Quellstimme.

Syntax

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

Parameter

[out] ppSourceVoice

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

[in] pSourceFormat

Zeiger auf eine der Strukturen in der folgenden Tabelle. Diese Struktur enthält das erwartete Format für alle Audiopuffer, die an die Quellstimme übermittelt werden. XAudio2 unterstützt PCM- und ADPCM-Sprachtypen.

Formattag	Wellenformatstruktur	Größe (in Bytes)
WAVE_FORMAT_PCM (0x0001)	PCMWAVEFORMAT	16
Oder	WAVEFORMATEX	18
WAVE_FORMAT_IEEE_FLOAT (0x0003) [32-Bit]	PCMWAVEFORMAT	18
WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM]	ADPCMWAVEFORMAT	50
WAVE_FORMAT_EXTENSIBLE (0xFFFE)	WAVEFORMATEXTENSIBLE	40

XAudio2 unterstützt die folgenden PCM-Formate.

8-Bit-Ganzzahl -PCM (ohne Vorzeichen)
16-Bit-Ganzzahl PCM (optimales Format für XAudio2)
20-Bit-Ganzzahl-PCM (entweder in 24- oder 32-Bit-Containern)
24-Bit-Ganzzahl-PCM (entweder in 24- oder 32-Bit-Containern)
32-Bit-Ganzzahl-PCM
32-Bit-Float-PCM (bevorzugtes Format nach 16-Bit-Ganzzahl)

Die Anzahl der Kanäle in einer Quellstimme muss kleiner oder gleich XAUDIO2_MAX_AUDIO_CHANNELS sein. Die Abtastrate einer Quellstimme muss zwischen XAUDIO2_MIN_SAMPLE_RATE und XAUDIO2_MAX_SAMPLE_RATE betragen.

Hinweis PCM-Datenformate wie PCMWAVEFORMAT und ADPCMWAVEFORMAT , die mehr Informationen benötigen als von WAVEFORMATEX bereitgestellt, verfügen über eine WAVEFORMATEX-Struktur als erstes Element in ihren Formatstrukturen. Wenn Sie eine Quellstimme mit einem dieser Formate erstellen, wandeln Sie die Struktur des Formats in eine WAVEFORMATEX-Struktur um, und verwenden Sie sie als Wert für pSourceFormat.

[in] Flags

Flags, die das Verhalten der Quellstimme angeben. Ein Flag kann 0 oder eine Kombination aus einem oder mehreren der folgenden Elemente sein:

Wert	BESCHREIBUNG
XAUDIO2_VOICE_NOPITCH	Für die Stimme ist keine Tonhöhensteuerung verfügbar.
XAUDIO2_VOICE_NOSRC	Für die Stimme ist keine Abtastratekonvertierung verfügbar. Die Ausgaben der Stimme müssen dieselbe Abtastrate aufweisen. Hinweis Das XAUDIO2_VOICE_NOSRC-Flag bewirkt, dass sich die Stimme so verhält, als ob auch das XAUDIO2_VOICE_NOPITCH-Flag angegeben wäre.
XAUDIO2_VOICE_USEFILTER	Der Filtereffekt sollte für diese Stimme verfügbar sein.

Hinweis Das XAUDIO2_VOICE_MUSIC-Flag wird unter Windows nicht unterstützt.

[in] MaxFrequencyRatio

Das höchste zulässige Frequenzverhältnis, das für diese Stimme festgelegt werden kann. Der Wert für dieses Argument muss zwischen XAUDIO2_MIN_FREQ_RATIO und XAUDIO2_MAX_FREQ_RATIO. Nachfolgende Aufrufe von IXAudio2SourceVoice::SetFrequencyRatio werden zwischen XAUDIO2_MIN_FREQ_RATIO und MaxFrequencyRatio eingespannt. Der Maximalwert für dieses Argument wird als XAUDIO2_MAX_FREQ_RATIO definiert, wodurch die Tonhöhe um bis zu 10 Oktaven erhöht werden kann.

Wenn MaxFrequencyRatio kleiner als 1,0 ist, verwendet die Stimme dieses Verhältnis unmittelbar nach der Erstellung (anstelle des Standardwerts 1,0).

Xbox 360
Für XMA-Stimmen gibt es eine weitere Einschränkung für das MaxFrequencyRatio-Argument und die Abtastrate der Stimme. Das Produkt dieser beiden Zahlen darf XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO für Stimmen mit einem Kanal oder XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL für Stimmen mit einer anderen Anzahl von Kanälen nicht überschreiten. Wenn der für MaxFrequencyRatio angegebene Wert für das angegebene Format zu hoch ist, schlägt der Aufruf von CreateSourceVoice fehl und erzeugt eine Debugmeldung.

Xbox 360

Für XMA-Stimmen gibt es eine weitere Einschränkung für das MaxFrequencyRatio-Argument und die Abtastrate der Stimme. Das Produkt dieser beiden Zahlen darf XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO für Stimmen mit einem Kanal oder XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL für Stimmen mit einer anderen Anzahl von Kanälen nicht überschreiten. Wenn der für MaxFrequencyRatio angegebene Wert für das angegebene Format zu hoch ist, schlägt der Aufruf von CreateSourceVoice fehl und erzeugt eine Debugmeldung.

Hinweis Sie können den geringstmöglichen MaxFrequencyRatio-Wert verwenden, um die Arbeitsspeicherauslastung von XAudio2 zu reduzieren.

[in, optional] pCallback

Zeiger auf die vom Client bereitgestellte Rückrufschnittstelle IXAudio2VoiceCallback.

[in, out] pSendList

Zeiger auf eine Liste von XAUDIO2_VOICE_SENDS Strukturen, die den Satz von Zielstimme für die Quellstimme beschreiben. Wenn pSendList NULL ist, wird für die Sendeliste standardmäßig eine einzelne Ausgabe an die erste erstellte Masterstimme ausgegeben.

[in, optional] pEffectChain

Zeiger auf eine Liste von XAUDIO2_EFFECT_CHAIN Strukturen, die eine Effektkette beschreiben, die in der Quellstimme verwendet werden soll.

Rückgabewert

Gibt bei erfolgreicher Ausführung S_OK zurück. andernfalls ein Fehlercode.

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

Hinweise

Quellstimmdaten lesen Audiodaten vom Client. Sie verarbeiten die Daten und senden sie an das XAudio2-Verarbeitungsdiagramm.

Eine Quellstimme enthält eine Konvertierung mit variabler Abtastrate, um Daten von der Quellformat-Abtastrate in die Ausgaberate zu konvertieren, die für die Sprachsendeliste erforderlich ist. Wenn Sie eine NULL-Sendeliste verwenden, ist die Ziel-Abtastrate die Eingabe-Abtastrate der Masterstimme. Wenn Sie eine einzelne Stimme in pSendList angeben, ist die Eingabe-Abtastrate dieser Stimme die Zielrate. Wenn Sie mehrere Stimmen in pSendList angeben, müssen alle Ausgabestimme der Quellstimme mit derselben Eingabe-Abtastrate ausgeführt werden.

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

Quellstimmungen werden immer vor allen Submix- oder Masterstimmstimden verarbeitet. Dies bedeutet, dass Sie keinen ProcessingStage-Parameter benötigen, um die Verarbeitungsreihenfolge zu steuern.

Bei der ersten Erstellung befinden sich Quellstimmdaten im Status "Beendet".

XAudio2 verwendet einen internen Speicherpooler für Stimmen im gleichen Format. Dies bedeutet, dass die Speicherbelegung für Stimmen seltener auftritt, wenn mehr Stimmen erstellt und dann zerstört werden. Um Just-in-Time-Zuordnungen zu minimieren, kann ein Titel die erwartete maximale Anzahl von Stimmen erstellen, die im Voraus benötigt werden, und diese dann nach Bedarf löschen. Stimmen werden dann aus dem XAudio2-Pool wiederverwendet. Der Speicherpool ist an eine XAudio2-Engine instance gebunden. Sie können den gesamten Von einem instance der XAudio2-Engine verwendeten Arbeitsspeicher wieder freigeben, indem Sie das XAudio2-Objekt zerstören und es bei Bedarf neu erstellen (erzwingen, dass der Arbeitsspeicherpool über eine Vorbelegung vergrößert werden muss, muss bei Bedarf erneut angewendet werden).

Es ist ungültig, CreateSourceVoice innerhalb eines Rückrufs (d. a. IXAudio2EngineCallback oder IXAudio2VoiceCallback) aufzurufen. Wenn Sie CreateSourceVoice 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 CreateSourceVoice nicht mehr benötigt und können unmittelbar nach dem Aufruf von CreateSourceVoice gelöscht werden.