> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IAcpHal::SubmitCommand

> IAcpHal::SubmitCommand

# IAcpHal::SubmitCommand

將命令提交至 ACP。

## 語法

```cpp theme={null}
HRESULT SubmitCommand(  
         ACP_COMMAND_TYPE command,  
         UINT64 commandId,  
         UINT32 audioFrame,  
         const void* data= nullptr,  
         APU_ADDRESS notification= 0  
)  
```

### 參數

*command*   \
類型：[ACP\_COMMAND\_TYPE](/zh-TW/reference/audio/acphal/enums/acp_command_type)

命令。請參閱 [ACP\_COMMAND\_TYPE](/zh-TW/reference/audio/acphal/enums/acp_command_type) 列舉。

*commandId*   \
類型：UINT64

選用的任意命令識別碼。此 ID 會隨特定訊息一起傳回。它是 UINT64，以便支援將指標當作命令 ID 傳遞。

*audioFrame*   \
類型：UINT32

如果指定了音訊框架編號，命令會在該音訊框架開始時處理，除非該框架已過去，在此情況下會從下一個音訊框架開始處理。此參數也有兩個特殊值：

* `ACP_SUBMIT_PROCESS_COMMAND_ASAP` 會指示 ACP 儘快處理命令，可能的話會在目前的音訊框架處理。
* `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` 會指示 ACP 在下一個音訊框架開始時處理命令。如果命令是要更新內容，則會在流程圖處理開始之前更新此內容。這確實會延遲流程圖處理的開始，可能導致語音數量多的圖形捨棄語音。

*data*   \_In\_opt\_\
類型：void\*

與命令相關聯的選用資料。大部分命令都需要資料結構。

*notification*   \_In\_opt\_\
類型：APU\_ADDRESS

UINT32 元素的選用實體位址，命令完成時會將其設定為非零值。指向虛擬位址的對應指標應宣告為 **volatile**。這類似於命令完成訊息，不同之處在於不需要訊息即可發出命令完成的訊號。當 XAudio2 將命令提交至 ACP 時，會在檢查命令是否完成時使用此通知指標。

### 傳回值

類型：HRESULT

如果方法成功，會傳回 S\_OK。如果方法失敗，會傳回下列其中一個代碼 (部分清單)：

| 傳回碼 | 描述 |
| - | - |
| E\_INVALIDARG | 一或多個引數無效。 |
| ACP\_E\_QUEUE\_FULL | 命令佇列已滿。 |

## 備註

這是唯一能讓遊戲與音訊控制處理器 (ACP)、可擴充硬體音訊處理引擎 (SHAPE) 和 XMA 通訊的 API。

使用此 `SubmitCommand` 方法提交之資料的存留期是可變的。作為輸入傳遞之結構的指標只會在 API 呼叫期間被參考；這表示開發人員可以安全地使用區域變數。如果命令包含指向另一個資料區塊的指標，則該資料不會被複製，且必須保持存在，直到 ACP 處理完命令為止。這樣做是為了將內部需複製的資料量降至最低。如果需要考量其他命令資料的存留期管理，應用程式可以註冊*命令完成*訊息，以便在命令中的其他資料不再被參考時準確收到訊息。

如果遊戲提交一或多個設定了 `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` 旗標或指定了特定音訊框架編號的命令，則所有這些命令都會在指定音訊框架開始時、執行任何其他處理之前進行處理。

請注意，由於所有 ACP 命令在主要 CPU 上都是非同步的，因此呼叫 `IAcpHal::SubmitCommand` 不會封鎖處理。

以下是遊戲使用通知最有效率的方法：

1. 使用 [ApuCreateHeap](/zh-TW/reference/audio/apu/functions/apucreateheap) 建立 APU 堆積，其中非快取大小要大到足以容納遊戲所需的所有內容及其將使用的所有通知。如果在任何其他 ACP 或方法之前未呼叫此方法，則會配置預設堆積。

2. 配置一個非快取的 UINT32 陣列，其大小等於所需的通知數目：也就是每個音訊框架將發出的內容更新總數。請注意，一次配置一個通知非常沒有效率。

## 需求

**標頭：** acphal.h

**支援的平台：** XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[ACP\_COMMAND\_TYPE](/zh-TW/reference/audio/acphal/enums/acp_command_type)
[AcpHal](/zh-TW/reference/audio/acphal/acphal_members)


## Related topics

- [IAcpHal::SubmitCommand](/es/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand.md)
- [IAcpHal](/reference/audio/acphal/interfaces/IAcpHal/iacphal.md)