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

Artículo
03/13/2024

Crea y configura una voz de maestro.

Sintaxis

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

Si se ejecuta correctamente, devuelve un puntero al nuevo objeto IXAudio2MasteringVoice .

[in] InputChannels

Número de canales que espera la voz de maestro en su audio de entrada. InputChannels debe ser menor o igual que XAUDIO2_MAX_AUDIO_CHANNELS.

Puede establecer InputChannels en XAUDIO2_DEFAULT_CHANNELS, lo que hace que XAudio2 intente detectar la configuración del altavoz del sistema.

[in] InputSampleRate

Frecuencia de muestreo de los datos de audio de entrada de la voz de masterización. Esta tasa debe ser un múltiplo de XAUDIO2_QUANTUM_DENOMINATOR. InputSampleRate debe estar entre XAUDIO2_MIN_SAMPLE_RATE y XAUDIO2_MAX_SAMPLE_RATE.

Puede establecer InputSampleRate en XAUDIO2_DEFAULT_SAMPLERATE, con el valor predeterminado determinado por la plataforma actual.

Windows XP tiene como valor predeterminado 44100.

Windows Vista y Windows 7 se establecen de forma predeterminada en la configuración especificada en el Panel de control sonido. El valor predeterminado para esta configuración es 44100 (o 48000 si es necesario para el controlador).

Marcas

[in] Flags

Marcas que especifican el comportamiento de la voz de maestro. Puede ser 0 o XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT.

[in] szDeviceId

Identificador del dispositivo para recibir el audio de salida. Especificar el valor predeterminado de NULL hace que XAudio2 seleccione el dispositivo de audio predeterminado global. En Windows 10 o posterior, NULL también participará en el cliente virtualizado WASAPI a menos que XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT se pase en Marcas.

[in, optional] pEffectChain

Puntero a una estructura de XAUDIO2_EFFECT_CHAIN que describe una cadena de efectos que se va a usar en la voz de maestro o NULL para no usar efectos.

[in, optional] StreamCategory

Categoría de secuencia de audio que se va a usar para esta voz de maestro.

Valor devuelto

Devuelve S_OK si se ejecuta correctamente; de lo contrario, un código de error. Devuelve ERROR_NOT_FOUND si no existe ningún dispositivo de audio predeterminado y se pasa NULL como parámetro szDeviceId.

Consulte Códigos de error XAudio2 para obtener descripciones de códigos de error específicos de XAudio2.

Comentarios

Las voces de maestro reciben la salida de una o varias voces de origen o submezcla. Procesan los datos y los envían al dispositivo de salida de audio.

Normalmente, debe crear una voz de maestro con una frecuencia de muestreo de entrada que usará la mayoría del contenido de audio del título. La voz de maestro realiza una conversión de frecuencia de muestreo de esta frecuencia de muestreo de entrada a la velocidad de salida del dispositivo real.

No se pueden crear voces de origen o submezcla hasta que exista una voz de maestro. No puede destruir una voz de maestro si todavía existen voces de origen o submezcla.

Las voces de maestro siempre se procesan después de todas las voces de origen y submezcla. Esto significa que no necesita especificar un parámetro ProcessingStage para controlar el orden de procesamiento.

XAudio2 solo permite que exista una voz de maestro a la vez. Si intenta crear más de una voz, se devuelve XAUDIO2_E_INVALID_CALL. Si se necesita una voz de procesamiento adicional, por ejemplo, para un dispositivo de salida con un conjunto de categorías de audio diferente, deberá crear una instancia de XAudio2 adicional.

Cuando se crea por primera vez, las voces de maestro están en estado iniciado.

No es válido llamar a CreateMasteringVoice desde una devolución de llamada (es decir, IXAudio2EngineCallback o IXAudio2VoiceCallback). Si llama a CreateMasteringVoice dentro de una devolución de llamada, devuelve XAUDIO2_E_INVALID_CALL.

El XAUDIO2_EFFECT_CHAIN que se pasa como argumento pEffectChain y cualquier información de XAUDIO2_EFFECT_DESCRIPTOR contenida en él ya no es necesaria después de que CreateMasteringVoice se complete correctamente y se pueda eliminar inmediatamente después de llamar a CreateMasteringVoice .

Tenga en cuenta que el SDK de DirectX XAUDIO2 versión de CreateMasteringVoice tomó un argumento DeviceIndex en lugar de un szDeviceId y un argumento StreamCategory. Esto refleja los cambios necesarios para el modelo de enumeración de dispositivos Windows estándar.