IAcpHal::SubmitCommand
ACP にコマンドを送信します。構文
パラメーター
command型: ACP_COMMAND_TYPE コマンド。ACP_COMMAND_TYPE 列挙体を参照してください。 commandId
型: UINT64 コマンドに対する任意のオプション識別子。この ID は特定のメッセージとともに返されます。ポインターをコマンド ID として渡せるように UINT64 型になっています。 audioFrame
型: UINT32 オーディオ フレーム番号を指定した場合、そのオーディオ フレームの開始時にコマンドが処理されますが、既に経過している場合は次のオーディオ フレームで処理が開始されます。このパラメーターには 2 つの特別な値もあります。
ACP_SUBMIT_PROCESS_COMMAND_ASAPは、ACP に対して可能な限り速やかに (可能であれば現在のオーディオ フレームで) コマンドを処理するよう指示します。ACP_SUBMIT_PROCESS_COMMAND_NEXT_FRAMEは、ACP に対して次のオーディオ フレームの開始時にコマンドを処理するよう指示します。コマンドがコンテキストを更新するものである場合、フローグラフの処理が始まる前にこのコンテキストが更新されます。これによりフローグラフ処理の開始が遅延するため、ボイス数の多いグラフではボイスがドロップする可能性があります。
型: void* コマンドに関連付けられるオプションのデータ。ほとんどのコマンドではデータ構造体が必要です。 notification _In_opt_
型: APU_ADDRESS コマンドの完了時に非ゼロ値に設定される UINT32 要素の、オプションの物理アドレス。対応する仮想アドレスへのポインターは volatile として宣言する必要があります。これはコマンド完了メッセージに似ていますが、コマンドの完了を通知するためにメッセージは必要ありません。XAudio2 は ACP にコマンドを送信するとき、コマンドが完了したかを判定するチェックにこの通知ポインターを使用します。
戻り値
型: HRESULT メソッドが成功した場合は S_OK を返します。失敗した場合は、次のいずれかのコードを返します (一部のみ)。解説
これは、タイトルが 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 の呼び出しは処理をブロックしないことに注意してください。
タイトルが通知を使用する最も効率的な方法は次のとおりです。
- ApuCreateHeap を使用して、タイトルが必要とするすべてのコンテキストと、使用するすべての通知を保持するのに十分な非キャッシュ サイズを持つ APU ヒープを作成します。他の ACP メソッドの前にこのメソッドが呼び出されない場合、既定のヒープが割り当てられます。
- 必要な通知数と等しいサイズの、非キャッシュの UINT32 配列を割り当てます。つまり、オーディオ フレームごとに発行されるコンテキスト更新の合計数です。通知を 1 つずつ割り当てるのは非常に非効率であることに注意してください。