跳轉到主要內容
在本主題中,我們將使用 Microsoft Game Development Kit (GDK) 隨附的其中一個範例,逐步說明如何在 XBOX Series X 裝置上使用 Opus 硬體加速解碼的預期程式碼流程。此範例名為 DecodeOne.cpp,涵蓋單一用戶端的單一串流解碼案例。

音訊硬體連線與啟動

解碼一開始會透過 XApuConnect 與硬體加速單元建立連線。呼叫端會使用 XApuConnectInputParameters 設定連線需求,以設定下列項目:
  1. 處理類型 (在此例中為 XApuProcessType::DecodeOpus)。
  2. 串流數目 (在此例中為 1)。
  3. 傳遞和擷取輸入與輸出資料所需的記憶體總量,在此例中,MaxInputBufferLength 為 1024 (必須等於或大於串流中最大的 Opus 封包)。此數字也必須是 16 的倍數,以及 7680。這是 48 K 下 20 毫秒的資料,即 MaxOutputBufferLength 為 960 × 2 × sizeof(float) = 7680。輸出也必須是 16 的倍數。
如果此呼叫成功,XApuConnectOutputParameters::baseData 參數會指向由作業系統配置的記憶體位置,其配置方式讓硬體加速單元可以直接存取,而無須額外封送處理或複製。呼叫端應使用此記憶體來傳遞輸入資料並擷取輸出資料。下列簡易記憶體管理員範例可用來設定 XApuConnectInputParameters,並將 XApuConnectOutputParameters::baseData 分割成兩個指標:一個用於輸入資料,另一個用於輸出資料。
以下是建立連線第一個步驟的程式碼範例。

啟用與停用串流

與裝置建立連線之後,呼叫端應傳送串流啟用命令以啟用單一解碼引擎。呼叫端必須指定串流索引與聲道數。僅允許單聲道或立體聲串流。 呼叫端應呼叫 XApuDequeueResult 以取得啟用結果。由於此範例中的 XApuConnectInputParameters::maxQueuedCommandsPerStream 設為 1,呼叫端必須等候每個結果後才能提交下一個命令。這包括 Activate、Process 與 Deactivate 命令 (如需詳細資料,請參閱 XApuCommandType)。 以下是啟用一個串流的程式碼。
收到啟用結果之後,呼叫端就可以開始提交 Opus 封包進行解碼。這應透過 XApuCommandType::Process 命令來完成。針對每個 Process 命令,呼叫端必須執行下列動作:
  1. 在輸入緩衝區中填入剛好一個 Opus 封包。
  2. 指定封包的長度。
  3. 提供輸出緩衝區的位置,音訊硬體加速單元會在該緩衝區中填入解碼後的資料。
  4. 指定輸出緩衝區的最大長度。
此外,呼叫端必須指定 streamIndex 與 frameCount 值。如果需要將所有解碼資料複製到輸出緩衝區,可以將 frameCount 值設為等於或大於封包中所編碼畫面數的任何值 (例如,對於 20 毫秒的封包,frameCount 可設定在 960 與 0xFFFFFFFF 之間)。
接下來,應呼叫 XApuDequeueResult 以取得封包的解碼輸出。成功擷取 XApuResult 之後,輸出資料會儲存在 result.outputData 中。處理完畢後,應以 XApuCommandType::Process 命令再次呼叫 XApuEnqueueCommand,提交下一個封包進行解碼。
串流中的所有封包都解碼完成後,應提交 XApuCommandType::Deactivate 命令。

終止

收到停用的結果之後,呼叫端必須呼叫 XApuDisconnect 以中斷與音訊硬體加速單元的連線,進而釋放所有已配置的資源。
最後修改於 2026年10月6日