裝置和資料類型
[與此頁面相關聯的功能 「波波音訊」是舊版功能。 WASAPI和音訊圖形已取代它。 WASAPI和音訊圖形已針對Windows 10和Windows 11進行優化。 Microsoft 強烈建議新程式碼盡可能使用 WASAPI 和 音訊圖形 ，而不是 波波音訊。 Microsoft 建議盡可能重寫使用舊版 API 的現有程式碼，以使用新的 API。]
本節說明如何使用電壓音訊裝置，並包含如何開啟、關閉及查詢其功能的相關資訊。 它也描述如何使用裝置控制碼和裝置識別碼來追蹤系統中的裝置。
開啟Waveform-Audio輸出裝置
使用 waveOutOpen 函式開啟用於播放的電壓音訊輸出裝置。 此函式會開啟與指定裝置識別碼相關聯的裝置，並藉由寫入指定記憶體位置的控制碼，傳回開啟裝置的控制碼。
某些多媒體電腦有多個電壓音訊輸出裝置。 除非您想要在系統中開啟特定的電壓音訊輸出裝置，否則當您開啟裝置時，應該使用裝置識別碼的 WAVE_MAPPER 旗標。 waveOutOpen函式會選擇系統中最能播放指定資料格式的裝置。
查詢音訊裝置
Windows 提供下列函式，以判斷系統中有多少特定類型的裝置可用。
| 函式 | 描述 |
|---|---|
| auxGetNumDevs | 擷取系統中存在的輔助輸出裝置數目。 |
| waveInGetNumDevs | 擷取系統中存在的波音訊輸入裝置數目。 |
| waveOutGetNumDevs | 擷取系統中存在的波音訊輸出裝置數目。 |
音訊裝置會以裝置識別碼來識別。 裝置識別碼會隱含地從系統中存在的裝置數目來決定。 裝置識別碼的範圍從零到一個小於存在的裝置數目。 例如，如果系統中有兩個電壓音訊輸出裝置，有效的裝置識別碼為 0 和 1。
在您判斷系統中存在多少特定類型的裝置之後，您可以使用下列其中一個函式來查詢每個裝置的功能。
| 函式 | 描述 |
|---|---|
| auxGetDevCaps | 擷取指定輔助輸出裝置的功能。 |
| waveInGetDevCaps | 擷取指定之電壓音訊輸入裝置的功能。 |
| waveOutGetDevCaps | 擷取指定之電壓音訊輸出裝置的功能。 |
每個函式都會填入結構，其中包含指定裝置功能的相關資訊。 下表列出對應至每個函式的結構。
| 函式 | 結構 |
|---|---|
| auxGetDevCaps | AUXCAPS |
| waveInGetDevCaps | WAVEINCAPS |
| waveOutGetDevCaps | WAVEOUTCAPS |
標準格式會列在WAVEOUTCAPS結構的dwFormats成員中。 電壓音訊裝置可以支援非標準格式。 若要判斷裝置是否支援特定格式 (標準或非標準) ，您可以使用 WAVE_FORMAT_QUERY 旗標呼叫 waveOutOpen 函式。 此旗標不會開啟裝置。 您可以在傳遞至waveOutOpen的pwfx參數所指向的WAVEATEX結構中指定有問題的格式。
電壓音訊輸出裝置會因支援的功能而有所不同。 WAVEOUTCAPS結構的dwSupport成員指出裝置是否支援音量和音調變更等功能。
裝置控制碼和裝置識別碼
每個開啟音訊裝置的函式都會指定裝置識別碼、記憶體位置的指標，以及每種裝置類型唯一的某些參數。 記憶體位置會填入裝置控制碼。 使用此裝置控制碼來識別呼叫其他音訊功能時開啟的音訊裝置。
音訊裝置的識別碼和控制碼之間的差異很細微，但很重要：
- 裝置識別碼會隱含地從系統中存在的裝置數目來決定。 此數位是使用auxGetNumDevs、waveInGetNumDevs 或 waveOutGetNumDevs函數取得。
- 使用 waveInOpen 或 waveOutOpen 函式開啟設備磁碟機時，會傳回裝置控制碼。
沒有可開啟或關閉輔助音訊裝置的函式。 輔助音訊裝置不需要開啟和關閉，例如電壓音訊裝置，因為沒有與其相關聯的連續資料傳輸。 所有輔助音訊功能都會使用裝置識別碼來識別裝置。
Waveform-Audio輸出資料類型
下列資料類型是針對電壓音訊輸出函式所定義。
| 類型 | 描述 |
|---|---|
| HWAVEOUT | 開啟的電壓輸出裝置的控制碼。 |
| 電壓X | 結構，指定特定電壓音訊輸入裝置所支援的資料格式。 此結構也用於電壓音訊輸入裝置。 |
| WAVEHDR | 結構，做為波狀音訊輸入資料區塊的標頭。 這個結構也用於電壓音訊輸入裝置。 |
| WAVEOUTCAPS | 結構，用來查詢特定電壓音訊輸出裝置的功能。 |
指定Waveform-Audio資料格式
當您呼叫 waveOutOpen 函式來開啟設備磁碟機進行播放，或查詢驅動程式是否支援特定資料格式時，請使用 pwfx 參數來指定包含所要求之波浪訊資料格式的 WAVEATEX 結構的指標。 WAVEATEX 取代 了WAVEAT 和 PCMWAVEFORMAT 結構。
對於分成兩個以上的通道或樣本大小不是 8 的倍數的音訊資料，您應該使用 WAVEFORMATEXTENSIBLE。 這個結構只會設定 CBSize 成員所指向的額外位元組 ， 以提供有關格式的額外資訊。 其可轉換成「波狀架構」XTENSIBLE。
您也可以使用兩種剪貼簿格式來表示音訊資料：CF_WAVE和CF_RIFF。 使用 CF_WAVE 格式來代表其中一種標準格式的資料，例如 11 kHz 或 22 kHz PCM。 使用CF_RIFF格式來表示無法以標準波音訊檔案表示的更複雜的資料格式。
寫入Waveform-Audio資料
成功開啟聲場音訊輸出設備磁碟機之後，您就可以開始播放音效。 Windows 提供 waveOutWrite 函式，可將資料區區塊轉送至電壓音訊輸出裝置。
使用 WAVEHDR 結構來指定您使用 waveOutWrite傳送的波浪音訊資料區塊。 這個結構包含鎖定資料區塊的指標、資料區塊的長度，以及某些旗標。 使用此資料區塊之前，必須先備妥此資料區塊;如需準備資料區塊的詳細資訊，請參閱 音訊資料區塊。
使用 waveOutWrite將資料區區塊轉送至輸出裝置之後，您必須等到設備磁碟機完成資料區塊後再釋放它。 如果您要傳送多個資料區塊，您必須監視資料區塊的完成時間，才能知道何時要傳送其他區塊。 如需資料區塊的詳細資訊，請參閱 音訊資料區塊。
PCM Waveform-Audio資料格式
WAVEHDR結構的lpData成員會指向電壓音訊資料樣本。 對於 8 位 PCM 資料，每個範例都會以單一未簽署的資料位元組表示。 對於 16 位 PCM 資料，每個樣本都會以 16 位帶正負號的值來表示。 下表摘要說明 PCM 電壓音訊資料的最大、最小值和中間點值。
| 資料格式 | 最大值 | 最小值 | 中間點值 |
|---|---|---|---|
| 8 位 PCM | 255 (0xFF) | 0 | 128 (0x80) |
| 16 位 PCM | 32，767 (0x7FFF) | –32，768 (0x8000) | 0 |
PCM 資料封裝
資料位元組的順序會依 8 位和 16 位格式以及單聲道和立體格式而有所不同。 下列清單描述不同 PCM 電壓音訊資料格式的資料封裝。
| PCM 電壓音訊格式 | 描述 |
|---|---|
| 8 位單聲道 | 每個範例都是對應至單一音訊通道的 1 個位元組。 範例 1 後面接著範例 2、3、4 等等。 |
| 8 位立體 | 每個範例都是 2 個位元組。 範例 1 後面接著範例 2、3、4 等等。 針對每個範例，第一個位元組是通道 0 (左通道) ，而第二個位元組則是通道 1 (右通道) 。 |
| 16 位 Mono | 每個範例都是 2 個位元組。 範例 1 後面接著範例 2、3、4 等等。 針對每個樣本，第一個位元組是通道 0 的低序位元組，而第二個位元組則是通道 0 的高階位元組。 |
| 16 位立體 | 每個範例都是 4 個位元組。 範例 1 後面接著範例 2、3、4 等等。 針對每個範例，第一個位元組是通道 0 (左通道的低序位元組) ;第二個位元組是通道 0 的高序位元組;第三個位元組是通道 1 的低序位元組 (右通道) ;而第四個位元組是通道 1 的高階位元組。 |
| 其他 | 每個樣本都包含在 4 個位元組的區塊中，但樣本可能不對齊位元組。 通道的相片順序是由遮罩所指定。 如需詳細資訊，請參閱 WAVEFORMATEXTENSIBLE。 |
關閉Waveform-Audio輸出裝置
在輸出音訊播放完成之後，請呼叫 waveOutClose 以關閉輸出裝置。 如果在播放波浪音訊檔案時呼叫 waveOutClose ，關閉作業會失敗，而且函式會傳回錯誤碼，指出裝置未關閉。 如果您不想在關閉裝置之前等候播放結束，請在關閉之前呼叫 waveOutReset 函式。 這會結束播放，並允許關閉裝置。 在關閉裝置之前，請務必使用 waveOutUnprepareHeader 函式清除所有資料區塊上的準備。