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

Artigo
03/04/2024

Cria e configura uma voz de domínio.

Sintaxe

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

Parâmetros

[out] ppMasteringVoice

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

[in] InputChannels

Número de canais que a voz de domínio espera em seu áudio de entrada. InputChannels deve ser menor ou igual a XAUDIO2_MAX_AUDIO_CHANNELS.

Você pode definir InputChannels como XAUDIO2_DEFAULT_CHANNELS, o que faz com que xAudio2 tente detectar a configuração do alto-falante do sistema.

[in] InputSampleRate

Taxa de exemplo dos dados de áudio de entrada da voz de masterização. Essa taxa deve ser um múltiplo de XAUDIO2_QUANTUM_DENOMINATOR. InputSampleRate deve estar entre XAUDIO2_MIN_SAMPLE_RATE e XAUDIO2_MAX_SAMPLE_RATE.

Você pode definir InputSampleRate como XAUDIO2_DEFAULT_SAMPLERATE, com o padrão sendo determinado pela plataforma atual.

O Windows XP usa como padrão 44100.

O Windows Vista e o Windows 7 são padrão para a configuração especificada na Painel de Controle de Som. O padrão para essa configuração é 44100 (ou 48000, se necessário, pelo driver).

Flags

[in] Flags

Sinalizadores que especificam o comportamento da voz de domínio. Isso pode ser 0 ou XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT.

[in] szDeviceId

Identificador do dispositivo para receber o áudio de saída. Especificar o valor padrão de NULL faz com que XAudio2 selecione o dispositivo de áudio padrão global. No Windows 10 ou posterior, NULL também aceitará o cliente virtualizado WASAPI, a menos que XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT seja passado em Sinalizadores.

[in, optional] pEffectChain

Ponteiro para uma estrutura XAUDIO2_EFFECT_CHAIN que descreve uma cadeia de efeitos a ser usada na voz de masterização ou NULL para não usar efeitos.

[in, optional] StreamCategory

A categoria de fluxo de áudio a ser usada para essa voz de masterização.

Retornar valor

Retorna S_OK se tiver êxito; caso contrário, um código de erro. Retorna ERROR_NOT_FOUND se nenhum dispositivo de áudio padrão existir e NULL for passado como o parâmetro szDeviceId.

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

Comentários

As vozes de masterização recebem a saída de uma ou mais vozes de origem ou submix. Eles processam os dados e os enviam para o dispositivo de saída de áudio.

Normalmente, você deve criar uma voz de domínio com uma taxa de exemplo de entrada que será usada pela maioria do conteúdo de áudio do título. A voz de masterização executa uma conversão de taxa de exemplo dessa taxa de exemplo de entrada para a taxa de saída real do dispositivo.

Você não pode criar uma origem ou submixar vozes até que exista uma voz de domínio. Você não poderá destruir uma voz de domínio se ainda existirem vozes de origem ou submixagem.

As vozes de masterização são sempre processadas após todas as vozes de origem e submixagem. Isso significa que você não precisa especificar um parâmetro ProcessingStage para controlar a ordem de processamento.

O XAudio2 só permite que uma voz de domínio exista de uma só vez. Se você tentar criar mais de uma voz, XAUDIO2_E_INVALID_CALL será retornado. Se uma voz de masterização adicional for necessária, por exemplo, para um dispositivo de saída com um conjunto de categorias de áudio diferente, você precisará criar uma instância XAudio2 adicional.

Quando criadas pela primeira vez, as vozes de domínio estão no estado iniciado.

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

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

Observe que o SDK do DirectX XAUDIO2 versão de CreateMasteringVoice teve um argumento DeviceIndex em vez de um szDeviceId e um argumento StreamCategory. Isso reflete as alterações necessárias para o modelo de enumeração de dispositivo Windows padrão.