IXAudio2：：CreateSourceVoice 方法 (xaudio2.h)

  • 项目

创建并配置源语音。

语法

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

参数

[out] ppSourceVoice

如果成功，则返回指向新 IXAudio2SourceVoice 对象的指针。

[in] pSourceFormat

指向下表中某个结构的指针。 此结构包含提交到源语音的所有音频缓冲区的预期格式。 XAudio2 支持 PCM 和 ADPCM 语音类型。

格式标记 波形格式结构 大小（以字节为单位）
WAVE_FORMAT_PCM (0x0001) PCMWAVEFORMAT 16
-或- WAVEFORMATEX 18
WAVE_FORMAT_IEEE_FLOAT (0x0003) [32 位] PCMWAVEFORMAT 18
WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM] ADPCMWAVEFORMAT 50
WAVE_FORMAT_EXTENSIBLE (0xFFFE) WAVEFORMATEXTENSIBLE 40
 

XAudio2 支持以下 PCM 格式。

  • 8 位 (无符号) 整数 PCM
  • 16 位整数 PCM (XAudio2) 的最佳格式
  • 24 位或 32 位容器中的 20 位整数 PCM ()
  • 24 位或 32 位容器中的 24 位整数 PCM ()
  • 32 位整数 PCM
  • 32 位浮点 PCM (16 位整数后的首选格式)
源语音中的通道数必须小于或等于XAUDIO2_MAX_AUDIO_CHANNELS。 源语音的采样率必须介于 XAUDIO2_MIN_SAMPLE_RATE 和 XAUDIO2_MAX_SAMPLE_RATE 之间。
注意 PCM 数据格式（如 PCMWAVEFORMAT 和 ADPCMWAVEFORMAT ）需要比 WAVEFORMATEX 提供的信息更多的信息，其格式结构中的第一个成员为 WAVEFORMATEX 结构。 使用其中一种格式创建源语音时，请将格式的结构转换为 WAVEFORMATEX 结构，并将其用作 pSourceFormat 的值。
 

[in] Flags

指定源语音行为的标志。 标志可以是 0，也可以是以下一个或多个标志的组合：

值 说明
XAUDIO2_VOICE_NOPITCH 语音上没有可用的音调控件。 
XAUDIO2_VOICE_NOSRC 语音上没有可用的采样率转换。 语音的输出必须具有相同的采样率。
注意 XAUDIO2_VOICE_NOSRC标志使语音的行为就像还指定了XAUDIO2_VOICE_NOPITCH标志一样。
 
XAUDIO2_VOICE_USEFILTER 此语音应提供筛选器效果。 
 
注意 Windows 不支持XAUDIO2_VOICE_MUSIC标志。
 

[in] MaxFrequencyRatio

可对此语音设置的最高允许频率比。 此参数的值必须介于 XAUDIO2_MIN_FREQ_RATIO 和 XAUDIO2_MAX_FREQ_RATIO 之间。 后续对 IXAudio2SourceVoice：：SetFrequencyRatio 的调用将固定在 XAUDIO2_MIN_FREQ_RATIO 和 MaxFrequencyRatio 之间。 此参数的最大值定义为 XAUDIO2_MAX_FREQ_RATIO，它允许将音调提升最多 10 个八度。

如果 MaxFrequencyRatio 小于 1.0，则语音将在创建 (后立即使用该比率，而不是默认值 1.0) 。

Xbox 360
对于 XMA 语音， MaxFrequencyRatio 参数和语音的采样率还有一个限制。 对于单声道语音，这两个数字的乘积不能超过 XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO，对于具有任何其他声道数的语音，不能超过XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL。 如果为 MaxFrequencyRatio 指定的值对于指定格式而言过高，则对 CreateSourceVoice 的调用会失败并生成调试消息。
 
注意 可以使用尽可能低的 MaxFrequencyRatio 值来减少 XAudio2 的内存使用量。
 

[in, optional] pCallback

指向客户端提供的回调接口 IXAudio2VoiceCallback 的指针。

[in, out] pSendList

指向描述源语音的目标语音集的 XAUDIO2_VOICE_SENDS 结构列表的指针。 如果 pSendList 为 NULL，则发送列表默认为创建的第一个主语音的单个输出。

[in, optional] pEffectChain

指向 XAUDIO2_EFFECT_CHAIN 结构列表的指针，这些结构描述要用于源语音的效果链。

返回值

如果成功，则返回S_OK;否则为错误代码。

有关 特定于 XAudio2 的错误代码 的说明，请参阅 XAudio2 错误代码。

注解

源语音从客户端读取音频数据。 它们处理数据并将其发送到 XAudio2 处理图。

源语音包括可变速率采样率转换，用于将数据从源格式采样率转换为语音发送列表所需的输出速率。 如果使用 NULL 发送列表，则目标采样率将是主语音的输入采样率。 如果在 pSendList 中提供单个语音，则该语音的输入采样率为目标速率。 如果在 pSendList 中提供多个语音，则源语音的所有输出语音都必须以相同的输入采样率运行。

在主语音存在之前，无法创建任何源或子混合语音，并且如果仍然存在任何源或子混合语音，则不能销毁主语音。

源语音始终在任何子混合或主语音之前进行处理。 这意味着无需 ProcessingStage 参数即可控制处理顺序。

首次创建时，源语音处于停止状态。

XAudio2 对具有相同格式的语音使用内部内存池。 这意味着，随着创建和销毁更多语音，语音的内存分配频率会降低。 若要最大程度地减少实时分配，游戏可以预先创建预期的最大语音数，然后根据需要将其删除。 然后，将从 XAudio2 池中重复使用语音。 内存池绑定到 XAudio2 引擎实例。 可以通过销毁 XAudio2 对象并根据需要重新创建 XAudio2 对象来回收 XAudio2 引擎实例使用的所有内存， (必须根据需要重新应用通过预分配来强制内存池增长) 。

从回调 (（即 IXAudio2EngineCallback 或 IXAudio2VoiceCallback) ）调用 CreateSourceVoice 无效。 如果在回调中调用 CreateSourceVoice ，它将返回XAUDIO2_E_INVALID_CALL。

在 CreateSourceVoice 成功完成后，不再需要作为 pEffectChain 参数传入的XAUDIO2_EFFECT_CHAIN以及其中包含的任何XAUDIO2_EFFECT_DESCRIPTOR信息，并且可以在调用 CreateSourceVoice 后立即删除。

平台要求

Windows 10 (XAudio2.9) ;Windows 8，Windows Phone 8 (XAudio 2.8) ;DirectX SDK (XAudio 2.7)

要求

要求 值
目标平台 Windows
标头 xaudio2.h

另请参阅

如何：构建基本的音频处理图

IXAudio2

XAPO 概述

XAudio2 采样率转换