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 |
| -或- | 波形 | 18 |
| WAVE_FORMAT_IEEE_FLOAT (0x0003) [32 位] | PCMWAVEFORMAT | 18 |
| WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM] | ADPCMWAVEFORMAT | 50 |
| WAVE_FORMAT_EXTENSIBLE (0xFFFE) | 波形值 | 40 |
XAudio2 支持以下 PCM 格式。
- 8 位 (无符号) 整数 PCM
- XAudio2) 的 16 位整数 PCM (最佳格式
- 24 或 32 位容器中的 20 位整数 PCM ()
- 24 位整数 PCM (24 位或 32 位容器)
- 32 位整数 PCM
- 32 位浮点 PCM (16 位整数后的首选格式)
[in] Flags
指定源语音行为的标志。 标志可以是 0，也可以是以下一个或多个标志的组合：
| Value | 说明 |
|---|---|
| XAUDIO2_VOICE_NOPITCH | 语音上没有音调控件。 |
| XAUDIO2_VOICE_NOSRC | 语音上没有可用的采样率转换。
语音的输出必须具有相同的采样率。 注意 XAUDIO2_VOICE_NOSRC标志会导致语音的行为方式与同时指定XAUDIO2_VOICE_NOPITCH标志一样。
|
| XAUDIO2_VOICE_USEFILTER | 筛选器效果应在此语音上可用。 |
[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 的调用将失败并生成调试消息。 |
[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 对象，并根据需要重新创建内存池， (强制通过预分配增长，必须根据需要重新应用) 。
从回调 (（即 IXAudio2EngineCallback 或 IXAudio2VoiceCallback) ）调用 CreateSourceVoice 无效。 如果在回调中调用 CreateSourceVoice ，它将返回XAUDIO2_E_INVALID_CALL。
作为 pEffectChain 参数传入的 XAUDIO2_EFFECT_CHAIN 及其中包含的任何 XAUDIO2_EFFECT_DESCRIPTOR 信息在 CreateSourceVoice 成功完成后不再需要，并在调用 CreateSourceVoice 后立即删除。
平台要求
Windows 10 (XAudio2.9) ;Windows 8，Windows Phone 8 (XAudio 2.8) ;DirectX SDK (XAudio 2.7)要求
| 目标平台 | Windows |
| 标头 | xaudio2.h |