> ## 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](/reference/audio/acphal/enums/acp_command_type)

コマンド。[ACP\_COMMAND\_TYPE](/reference/audio/acphal/enums/acp_command_type) 列挙体を参照してください。

*commandId*   \
型: UINT64

コマンドに対する任意のオプション識別子。この ID は特定のメッセージとともに返されます。ポインターをコマンド ID として渡せるように UINT64 型になっています。

*audioFrame*   \
型: UINT32

オーディオ フレーム番号を指定した場合、そのオーディオ フレームの開始時にコマンドが処理されますが、既に経過している場合は次のオーディオ フレームで処理が開始されます。このパラメーターには 2 つの特別な値もあります。

* `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       | 1 つ以上の引数が無効です。 |
| ACP\_E\_QUEUE\_FULL | コマンド キューが満杯です。 |

## 解説

これは、タイトルが Audio Control Processor (ACP)、Scalable Hardware Audio Processing Engine (SHAPE)、および XMA と通信するための唯一の API です。

この `SubmitCommand` メソッドを使用して送信されたデータの有効期間は可変です。入力として渡された構造体へのポインターは、API 呼び出し中にのみ参照されます。つまり、開発者はローカル変数を安全に使用できます。コマンドが別のデータ ブロックへのポインターを含む場合、そのデータはコピーされないため、ACP がコマンドを処理するまで存在し続ける必要があります。これは内部でコピーするデータ量を最小限に抑えるためです。追加のコマンド データの有効期間管理が懸念される場合、アプリケーションは *コマンド完了* メッセージを登録することで、追加データが参照されなくなった正確なタイミングでメッセージを受信できます。

タイトルが 1 つ以上のコマンドを `ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAME` フラグを設定して、または特定のオーディオ フレーム番号を指定して送信した場合、これらのコマンドはすべて、指定されたオーディオ フレームの開始時に、他の処理が実行される前に処理されます。

すべての ACP コマンドはメイン CPU 上では非同期であるため、`IAcpHal::SubmitCommand` の呼び出しは処理をブロックしないことに注意してください。

タイトルが通知を使用する最も効率的な方法は次のとおりです。

1. [ApuCreateHeap](/reference/audio/apu/functions/apucreateheap) を使用して、タイトルが必要とするすべてのコンテキストと、使用するすべての通知を保持するのに十分な非キャッシュ サイズを持つ APU ヒープを作成します。他の ACP メソッドの前にこのメソッドが呼び出されない場合、既定のヒープが割り当てられます。

2. 必要な通知数と等しいサイズの、非キャッシュの UINT32 配列を割り当てます。つまり、オーディオ フレームごとに発行されるコンテキスト更新の合計数です。通知を 1 つずつ割り当てるのは非常に非効率であることに注意してください。

## 要件

**ヘッダー:** acphal.h

**サポート対象プラットフォーム:** XBOX One ファミリー本体、XBOX Series 本体

## 関連項目

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


## Related topics

- [IAcpHal](/ja-jp/reference/audio/acphal/interfaces/IAcpHal/iacphal.md)
- [IAcpHal::Connect](/ja-jp/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_connect.md)
- [ACP_COMMAND_TYPE](/ja-jp/reference/audio/acphal/enums/acp_command_type.md)
- [ACP_COMMAND_UPDATE_CONTEXTS](/ja-jp/reference/audio/acphal/structs/acp_command_update_contexts.md)
- [ACP_COMMAND_UPDATE_ALL_CONTEXTS](/ja-jp/reference/audio/acphal/structs/acp_command_update_all_contexts.md)