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

Artículo
08/28/2023

Crea y configura una voz de origen.

Sintaxis

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

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

[in] pSourceFormat

Puntero a una de las estructuras de la tabla siguiente. Esta estructura contiene el formato esperado para todos los búferes de audio enviados a la voz de origen. XAudio2 admite tipos de voz PCM y ADPCM.

Etiqueta de formato	Estructura de formato de onda	Tamaño (en bytes)
WAVE_FORMAT_PCM (0x0001)	PCMWAVEFORMAT	16
O bien	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

XAudio2 admite los siguientes formatos PCM.

PCM entero de 8 bits (sin signo)
PCM entero de 16 bits (formato óptimo para XAudio2)
PCM entero de 20 bits (ya sea en contenedores de 24 o 32 bits)
PCM entero de 24 bits (ya sea en contenedores de 24 o 32 bits)
PCM entero de 32 bits
PCM flotante de 32 bits (formato preferido después del entero de 16 bits)

El número de canales de una voz de origen debe ser menor o igual que XAUDIO2_MAX_AUDIO_CHANNELS. La frecuencia de muestreo de una voz de origen debe estar entre XAUDIO2_MIN_SAMPLE_RATE y XAUDIO2_MAX_SAMPLE_RATE.

Nota Los formatos de datos PCM como PCMWAVEFORMAT y ADPCMWAVEFORMAT que requieren más información de la proporcionada por WAVEFORMATEX tienen una estructura WAVEFORMATEX como primer miembro en sus estructuras de formato. Al crear una voz de origen con uno de esos formatos, convierta la estructura del formato como una estructura WAVEFORMATEX y úsela como el valor de pSourceFormat.

[in] Flags

Marcas que especifican el comportamiento de la voz de origen. Una marca puede ser 0 o una combinación de uno o varios de los siguientes elementos:

Valor	Descripción
XAUDIO2_VOICE_NOPITCH	No hay ningún control de tono disponible en la voz.
XAUDIO2_VOICE_NOSRC	No hay ninguna conversión de frecuencia de muestreo disponible en la voz. Las salidas de voz deben tener la misma frecuencia de muestreo. Nota La marca XAUDIO2_VOICE_NOSRC hace que la voz se comporte como si también se especificara la marca XAUDIO2_VOICE_NOPITCH.
XAUDIO2_VOICE_USEFILTER	El efecto de filtro debe estar disponible en esta voz.

Nota La marca XAUDIO2_VOICE_MUSIC no se admite en Windows.

[in] MaxFrequencyRatio

Mayor proporción de frecuencia permitida que se puede establecer en esta voz. El valor de este argumento debe estar entre XAUDIO2_MIN_FREQ_RATIO y XAUDIO2_MAX_FREQ_RATIO. Las llamadas posteriores a IXAudio2SourceVoice::SetFrequencyRatio se fijan entre XAUDIO2_MIN_FREQ_RATIO y MaxFrequencyRatio. El valor máximo de este argumento se define como XAUDIO2_MAX_FREQ_RATIO, lo que permite elevar el tono hasta 10 octavas.

Si MaxFrequencyRatio es menor que 1,0, la voz usará esa relación inmediatamente después de crearse (en lugar del valor predeterminado de 1,0).

Xbox 360
En el caso de las voces XMA, hay una restricción más en el argumento MaxFrequencyRatio y la frecuencia de muestreo de la voz. El producto de estos dos números no puede superar XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO para las voces de un canal o XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL para las voces con cualquier otro número de canales. Si el valor especificado para MaxFrequencyRatio es demasiado alto para el formato especificado, se produce un error en la llamada a CreateSourceVoice y se genera un mensaje de depuración.

Xbox 360

En el caso de las voces XMA, hay una restricción más en el argumento MaxFrequencyRatio y la frecuencia de muestreo de la voz. El producto de estos dos números no puede superar XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO para las voces de un canal o XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL para las voces con cualquier otro número de canales. Si el valor especificado para MaxFrequencyRatio es demasiado alto para el formato especificado, se produce un error en la llamada a CreateSourceVoice y se genera un mensaje de depuración.

Nota Puede usar el valor maxFrequencyRatio más bajo posible para reducir el uso de memoria de XAudio2.

[in, optional] pCallback

Puntero a una interfaz de devolución de llamada proporcionada por el cliente, IXAudio2VoiceCallback.

[in, out] pSendList

Puntero a una lista de estructuras de XAUDIO2_VOICE_SENDS que describen el conjunto de voces de destino para la voz de origen. Si pSendList es NULL, el valor predeterminado de la lista de envío es una única salida a la primera voz de maestro creada.

[in, optional] pEffectChain

Puntero a una lista de XAUDIO2_EFFECT_CHAIN estructuras que describen una cadena de efectos que se va a usar en la voz de origen.

Valor devuelto

Devuelve S_OK si se ejecuta correctamente; de lo contrario, un código de error.

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

Comentarios

Las voces de origen leen datos de audio del cliente. Procesan los datos y los envían al gráfico de procesamiento XAudio2.

Una voz de origen incluye una conversión de frecuencia de muestreo de frecuencia variable para convertir datos de la frecuencia de muestreo de formato de origen a la velocidad de salida necesaria para la lista de envío de voz. Si usa una lista de envío NULL, la frecuencia de muestreo de destino será la frecuencia de muestreo de entrada de voz de mastering. Si proporciona una sola voz en pSendList, la frecuencia de muestreo de entrada de esa voz es la tasa de destino. Si proporciona varias voces en pSendList, todas las voces de salida de la voz de origen deben ejecutarse con la misma frecuencia de muestreo de entrada.

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

Las voces de origen siempre se procesan antes de cualquier submezcla o voces de maestro. Esto significa que no necesita un parámetro ProcessingStage para controlar el orden de procesamiento.

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

XAudio2 usa un agrupador de memoria interno para las voces con el mismo formato. Esto significa que la asignación de memoria para las voces se producirá con menos frecuencia a medida que se creen más voces y, a continuación, se destruya. Para minimizar las asignaciones Just-In-Time, un título puede crear el número máximo previsto de voces necesarias por adelantado y, a continuación, eliminarlas según sea necesario. Después, las voces se reutilizarán del grupo XAudio2. El grupo de memoria está asociado a una instancia del motor XAudio2. Puede reclamar toda la memoria usada por una instancia del motor XAudio2 destruyendo el objeto XAudio2 y volviendo a crearla según sea necesario (forzar el crecimiento del grupo de memoria a través de la asignación previa tendría que volver a aplicarse según sea necesario).

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

El XAUDIO2_EFFECT_CHAIN que se pasa como el argumento pEffectChain y cualquier información XAUDIO2_EFFECT_DESCRIPTOR contenida en ella ya no se necesita después de que CreateSourceVoice se complete correctamente y se pueda eliminar inmediatamente después de llamar a CreateSourceVoice .