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 |
| -或- | 電壓X | 18 |
| WAVE_FORMAT_IEEE_FLOAT (0x0003) [32 位] | PCMWAVEFORMAT | 18 |
| WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM] | ADPCMWAVEFORMAT | 50 |
| WAVE_FORMAT_EXTENSIBLE (0xFFFE) | 波地ATEXTENSIBLE | 40 |
XAudio2 支援下列 PCM 格式。
- 8 位 (無符號) 整數 PCM
- XAudio2) 的16位整數 PCM (最佳格式
- 24 或 32 位容器中的 20 位整數 PCM ()
- 24 位整數 PCM (在 24 或 32 位容器中)
- 32 位整數 PCM
- 32 位浮點數 PCM (16 位整數之後慣用的格式)
[in] Flags
指定來源語音行為的旗標。 旗標可以是 0 或下列一或多個組合：
| 值 | Description |
|---|---|
| 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 會針對具有相同格式的語音使用內部記憶體共用器。 這表示語音的記憶體配置會較不頻繁發生，因為建立並終結更多語音。 若要將 Just-In-Time 配置降到最低，標題可以建立預先所需的語音數目上限，然後視需要將其刪除。 然後，從 XAudio2 集區重複使用語音。 記憶體集區會系結至 XAudio2 引擎實例。 您可以藉由終結 XAudio2 物件並視需要重新建立 XAudio2 物件，以回收 XAudio2 引擎實例所使用的所有記憶體， (強制記憶體集區透過預先配置成長，必須視需要重新套用) 。
從回呼 (呼叫 CreateSourceVoice 是 IXAudio2EngineCallback 或 IXAudio2VoiceCallback) 無效。 如果您在回呼內呼叫 CreateSourceVoice ，它會傳回XAUDIO2_E_INVALID_CALL。
傳遞為 pEffectChain 自變數的XAUDIO2_EFFECT_CHAIN，在 CreateSourceVoice 順利完成之後就不再需要內含的任何XAUDIO2_EFFECT_DESCRIPTOR資訊，而且可能會在呼叫 CreateSourceVoice 之後立即刪除。
平臺需求
Windows 10 (XAudio2.9) ;Windows 8，Windows Phone 8 (XAudio 2.8) ;DirectX SDK (XAudio 2.7)規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | Windows |
| 標頭 | xaudio2.h |