Método IXAudio2::CreateSourceVoice (xaudio2.h)

Artigo
08/28/2023

Cria e configura uma voz de origem.

Sintaxe

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

Parâmetros

[out] ppSourceVoice

Se tiver êxito, retornará um ponteiro para o novo objeto IXAudio2SourceVoice .

[in] pSourceFormat

Ponteiro para uma das estruturas na tabela abaixo. Essa estrutura contém o formato esperado para todos os buffers de áudio enviados à voz de origem. O XAudio2 dá suporte a tipos de voz PCM e ADPCM.

Marca de formato	Estrutura de formato de onda	Tamanho (em bytes)
WAVE_FORMAT_PCM (0x0001)	PCMWAVEFORMAT	16
-ou-	WAVEFORMATEX	18
WAVE_FORMAT_IEEE_FLOAT (0x0003) [32 bits]	PCMWAVEFORMAT	18
WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM]	ADPCMWAVEFORMAT	50
WAVE_FORMAT_EXTENSIBLE (0xFFFE)	WAVEFORMATEXTENSIBLE	40

O XAudio2 dá suporte aos seguintes formatos de PCM.

PCM inteiro de 8 bits (sem sinal)
PCM inteiro de 16 bits (formato ideal para XAudio2)
PCM inteiro de 20 bits (em contêineres de 24 ou 32 bits)
PCM inteiro de 24 bits (em contêineres de 24 ou 32 bits)
PCM inteiro de 32 bits
PCM float de 32 bits (formato preferencial após inteiro de 16 bits)

O número de canais em uma voz de origem deve ser menor ou igual a XAUDIO2_MAX_AUDIO_CHANNELS. A taxa de exemplo de uma voz de origem deve estar entre XAUDIO2_MIN_SAMPLE_RATE e XAUDIO2_MAX_SAMPLE_RATE.

Nota Formatos de dados PCM como PCMWAVEFORMAT e ADPCMWAVEFORMAT que exigem mais informações do que o fornecido por WAVEFORMATEX têm uma estrutura WAVEFORMATEX como o primeiro membro em suas estruturas de formato. Ao criar uma voz de origem com um desses formatos, converta a estrutura do formato como uma estrutura WAVEFORMATEX e use-a como o valor para pSourceFormat.

[in] Flags

Sinalizadores que especificam o comportamento da voz de origem. Um sinalizador pode ser 0 ou uma combinação de um ou mais dos seguintes:

Valor	Descrição
XAUDIO2_VOICE_NOPITCH	Nenhum controle de tom está disponível na voz.
XAUDIO2_VOICE_NOSRC	Nenhuma conversão de taxa de exemplo está disponível na voz. As saídas da voz devem ter a mesma taxa de exemplo. Nota O sinalizador XAUDIO2_VOICE_NOSRC faz com que a voz se comporte como se o sinalizador XAUDIO2_VOICE_NOPITCH também fosse especificado.
XAUDIO2_VOICE_USEFILTER	O efeito de filtro deve estar disponível nessa voz.

Nota Não há suporte para o sinalizador XAUDIO2_VOICE_MUSIC no Windows.

[in] MaxFrequencyRatio

Maior taxa de frequência permitida que pode ser definida nessa voz. O valor desse argumento deve estar entre XAUDIO2_MIN_FREQ_RATIO e XAUDIO2_MAX_FREQ_RATIO. As chamadas subsequentes para IXAudio2SourceVoice::SetFrequencyRatio são fixadas entre XAUDIO2_MIN_FREQ_RATIO e MaxFrequencyRatio. O valor máximo para esse argumento é definido como XAUDIO2_MAX_FREQ_RATIO, o que permite que o pitch seja gerado em até 10 oitavas.

Se MaxFrequencyRatio for menor que 1,0, a voz usará essa taxa imediatamente após ser criada (em vez do padrão de 1,0).

Xbox 360
Para vozes XMA, há mais uma restrição no argumento MaxFrequencyRatio e na taxa de exemplo da voz. O produto desses dois números não pode exceder XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO para vozes de um canal ou XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL para vozes com qualquer outro número de canais. Se o valor especificado para MaxFrequencyRatio for muito alto para o formato especificado, a chamada para CreateSourceVoice falhará e produzirá uma mensagem de depuração.

Xbox 360

Para vozes XMA, há mais uma restrição no argumento MaxFrequencyRatio e na taxa de exemplo da voz. O produto desses dois números não pode exceder XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO para vozes de um canal ou XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL para vozes com qualquer outro número de canais. Se o valor especificado para MaxFrequencyRatio for muito alto para o formato especificado, a chamada para CreateSourceVoice falhará e produzirá uma mensagem de depuração.

Nota Você pode usar o menor valor possível de MaxFrequencyRatio para reduzir o uso de memória do XAudio2.

[in, optional] pCallback

Ponteiro para uma interface de retorno de chamada fornecida pelo cliente, IXAudio2VoiceCallback.

[in, out] pSendList

Ponteiro para uma lista de estruturas de XAUDIO2_VOICE_SENDS que descrevem o conjunto de vozes de destino para a voz de origem. Se pSendList for NULL, a lista de envio usará como padrão uma única saída para a primeira voz de masterização criada.

[in, optional] pEffectChain

Ponteiro para uma lista de estruturas de XAUDIO2_EFFECT_CHAIN que descrevem uma cadeia de efeitos a ser usada na voz de origem.

Retornar valor

Retorna S_OK se tiver êxito; caso contrário, um código de erro.

Consulte Códigos de Erro XAudio2 para obter descrições de códigos de erro específicos do XAudio2.

Comentários

As vozes de origem leem dados de áudio do cliente. Eles processam os dados e os enviam para o grafo de processamento XAudio2.

Uma voz de origem inclui uma conversão de taxa de exemplo de taxa variável para converter dados da taxa de exemplo de formato de origem para a taxa de saída necessária para a lista de envio de voz. Se você usar uma lista de envio NULL, a taxa de exemplo de destino será a taxa de exemplo de entrada da voz de domínio. Se você fornecer uma única voz em pSendList, a taxa de exemplo de entrada dessa voz será a taxa de destino. Se você fornecer várias vozes no pSendList, todas as vozes de saída da voz de origem deverão estar em execução na mesma taxa de exemplo de entrada.

Não é possível criar vozes de origem ou submixar até que exista uma voz de domínio e você não poderá destruir uma voz de mestre se ainda existirem vozes de origem ou submixagem.

As vozes de origem são sempre processadas antes de qualquer submixar ou dominar vozes. Isso significa que você não precisa de um parâmetro ProcessingStage para controlar a ordem de processamento.

Quando criadas pela primeira vez, as vozes de origem estão no estado interrompido.

O XAudio2 usa um pooler de memória interno para vozes com o mesmo formato. Isso significa que a alocação de memória para vozes ocorrerá com menos frequência à medida que mais vozes forem criadas e destruídas. Para minimizar as alocações just-in-time, um título pode criar o número máximo previsto de vozes necessárias antecipadamente e excluí-las conforme necessário. Em seguida, as vozes serão reutilizados do pool XAudio2. O pool de memória está vinculado a uma instância do mecanismo XAudio2. Você pode recuperar toda a memória usada por uma instância do mecanismo XAudio2 destruindo o objeto XAudio2 e recriando-o conforme necessário (forçar o pool de memória a crescer via pré-localização teria que ser reaplicado conforme necessário).

É inválido chamar CreateSourceVoice de dentro de um retorno de chamada (ou seja, IXAudio2EngineCallback ou IXAudio2VoiceCallback). Se você chamar CreateSourceVoice em um retorno de chamada, ele retornará XAUDIO2_E_INVALID_CALL.

As XAUDIO2_EFFECT_CHAIN que são passadas como o argumento pEffectChain e todas as informações de XAUDIO2_EFFECT_DESCRIPTOR contidas nela não são mais necessárias após a conclusão do CreateSourceVoice com êxito e podem ser excluídas imediatamente após CreateSourceVoice ser chamado.