Metodo IXAudio2::CreateSourceVoice (xaudio2.h)

Articolo
08/28/2023

Crea e configura una voce di origine.

Sintassi

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

Parametri

[out] ppSourceVoice

Se ha esito positivo, restituisce un puntatore al nuovo oggetto IXAudio2SourceVoice .

[in] pSourceFormat

Puntatore a una delle strutture nella tabella seguente. Questa struttura contiene il formato previsto per tutti i buffer audio inviati alla voce di origine. XAudio2 supporta tipi di voce PCM e ADPCM.

Tag di formato	Struttura del formato wave	Dimensioni (in byte)
WAVE_FORMAT_PCM (0x0001)	PCMWAVEFORMAT	16
-oppure-	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 supporta i formati PCM seguenti.

PCM intero a 8 bit (senza segno)
PCM intero a 16 bit (formato ottimale per XAudio2)
PCM intero a 20 bit (in contenitori a 24 o 32 bit)
PCM intero a 24 bit (in contenitori a 24 o 32 bit)
PCM intero a 32 bit
PCM float a 32 bit (formato preferito dopo intero a 16 bit)

Il numero di canali in una voce di origine deve essere minore o uguale a XAUDIO2_MAX_AUDIO_CHANNELS. La frequenza di esempio di una voce di origine deve essere compresa tra XAUDIO2_MIN_SAMPLE_RATE e XAUDIO2_MAX_SAMPLE_RATE.

Nota Formati di dati PCM, ad esempio PCMWAVEFORMAT e ADPCMWAVEFORMAT, che richiedono più informazioni rispetto a quelle fornite da WAVEFORMATEX hanno una struttura WAVEFORMATEX come primo membro nelle strutture di formato. Quando si crea una voce di origine con uno di questi formati, eseguire il cast della struttura del formato come struttura WAVEFORMATEX e usarla come valore per pSourceFormat.

[in] Flags

Flag che specificano il comportamento della voce di origine. Un flag può essere 0 o una combinazione di uno o più dei seguenti:

Valore	Descrizione
XAUDIO2_VOICE_NOPITCH	Nessun controllo di passo è disponibile sulla voce.
XAUDIO2_VOICE_NOSRC	Nessuna conversione della frequenza di esempio è disponibile nella voce. Gli output della voce devono avere la stessa frequenza di esempio. Nota Il flag XAUDIO2_VOICE_NOSRC causa il comportamento della voce come se il flag XAUDIO2_VOICE_NOPITCH sia specificato anche.
XAUDIO2_VOICE_USEFILTER	L'effetto filtro deve essere disponibile in questa voce.

Nota Il flag XAUDIO2_VOICE_MUSIC non è supportato in Windows.

[in] MaxFrequencyRatio

Rapporto di frequenza consentito massimo che può essere impostato su questa voce. Il valore per questo argomento deve essere compreso tra XAUDIO2_MIN_FREQ_RATIO e XAUDIO2_MAX_FREQ_RATIO. Le chiamate successive a IXAudio2SourceVoice::SetFrequencyRatio vengono bloccate tra XAUDIO2_MIN_FREQ_RATIO e MaxFrequencyRatio. Il valore massimo per questo argomento è definito come XAUDIO2_MAX_FREQ_RATIO, che consente di elevare il passo fino a 10 ottafi.

Se MaxFrequencyRatio è minore di 1,0, la voce userà tale rapporto immediatamente dopo la creazione (anziché l'impostazione predefinita di 1,0).

Xbox 360
Per le voci XMA, esiste una restrizione maggiore sull'argomento MaxFrequencyRatio e sulla frequenza di esempio della voce. Il prodotto di questi due numeri non può superare XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO per voci a un canale o XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL per voci con qualsiasi altro numero di canali. Se il valore specificato per MaxFrequencyRatio è troppo elevato per il formato specificato, la chiamata a CreateSourceVoice ha esito negativo e genera un messaggio di debug.

Xbox 360

Per le voci XMA, esiste una restrizione maggiore sull'argomento MaxFrequencyRatio e sulla frequenza di esempio della voce. Il prodotto di questi due numeri non può superare XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO per voci a un canale o XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL per voci con qualsiasi altro numero di canali. Se il valore specificato per MaxFrequencyRatio è troppo elevato per il formato specificato, la chiamata a CreateSourceVoice ha esito negativo e genera un messaggio di debug.

Nota È possibile usare il valore MassimoFrequencyRatio possibile per ridurre l'utilizzo della memoria di XAudio2.

[in, optional] pCallback

Puntatore a un'interfaccia di callback fornita dal client, IXAudio2VoiceCallback.

[in, out] pSendList

Puntatore a un elenco di strutture XAUDIO2_VOICE_SENDS che descrivono il set di voci di destinazione per la voce di origine. Se pSendList è NULL, l'elenco di invio viene predefinito in un singolo output alla prima voce mastering creata.

[in, optional] pEffectChain

Puntatore a un elenco di strutture XAUDIO2_EFFECT_CHAIN che descrivono una catena di effetti da usare nella voce di origine.

Valore restituito

Restituisce S_OK se ha esito positivo; in caso contrario, un codice di errore.

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

Commenti

Le voci di origine leggeno i dati audio dal client. Elaborano i dati e li inviano al grafico di elaborazione XAudio2.

Una voce di origine include una conversione della frequenza di esempio a frequenza variabile per convertire i dati dalla frequenza di esempio del formato di origine alla frequenza di output necessaria per l'elenco di invio vocale. Se si usa un elenco di invio NULL, la frequenza di esempio di destinazione sarà la frequenza di esempio di input della voce mastering. Se si specifica una singola voce in pSendList, la frequenza di esempio di input della voce è la frequenza di destinazione. Se si forniscono più voci in pSendList, tutte le voci di output della voce di origine devono essere eseguite con la stessa frequenza di esempio di input.

Non è possibile creare voci di origine o submix fino a quando non esiste una voce mastering e non è possibile distruggere una voce mastering se esistono ancora voci di origine o submix.

Le voci di origine vengono sempre elaborate prima di qualsiasi sottomix o mastering voce. Ciò significa che non è necessario un parametro ProcessingStage per controllare l'ordine di elaborazione.

Quando viene creata la prima volta, le voci di origine si trovano nello stato arrestato.

XAudio2 usa un pooler di memoria interno per le voci con lo stesso formato. Ciò significa che l'allocazione della memoria per le voci si verificherà meno frequentemente quando vengono create più voci e quindi eliminate. Per ridurre al minimo le allocazioni just-in-time, un titolo può creare il numero massimo previsto di voci necessarie in anticipo e quindi eliminarle in base alle esigenze. Le voci verranno quindi riutilizzate dal pool XAudio2. Il pool di memoria è associato a un'istanza del motore XAudio2. È possibile recuperare tutta la memoria usata da un'istanza del motore XAudio2 distruggendo l'oggetto XAudio2 e ricreandolo in base alle esigenze (forzando il pool di memoria a crescere tramite preallocation dovrebbe essere riapplicato in base alle esigenze).

Non è valido chiamare CreateSourceVoice da un callback, ovvero IXAudio2EngineCallback o IXAudio2VoiceCallback. Se si chiama CreateSourceVoice all'interno di un callback, restituisce XAUDIO2_E_INVALID_CALL.

Il XAUDIO2_EFFECT_CHAIN passato come argomento pEffectChain e tutte le informazioni XAUDIO2_EFFECT_DESCRIPTOR contenute all'interno non sono più necessarie dopo il completamento di CreateSourceVoice e possono essere eliminate immediatamente dopo la chiamata a CreateSourceVoice .