> ## 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. # ACP の概要 > XBOX One コンソール上で SHAPE オーディオ フローグラフを管理する Audio Control Processor (ACP) と acphal ライブラリのプログラミング ガイドです。 このトピックでは、Audio Control Processor (ACP) の制御に使用されるフローグラフの説明と例を紹介します。 ## ACP の概要 このセクションでは、ACP のプログラミング インターフェイスについて説明します。 `acphal` ライブラリ (*acphal.lib*) は、Scalable Hardware Audio Processing Engine (SHAPE) の API セットを定義します。また、Microsoft Game Development Kit (GDK) には、SHAPE で使用するオーディオ データを準備するのに役立つオーディオ ユーティリティとソース コードのコレクションも含まれています。ユーティリティ ヘッダーは、次の内容を定義します。 * サポートされている各データ形式のコンテキスト構造体 * これらのコンテキストの読み取りと書き込みに使用できる完全な関数セット オーディオ データを SHAPE ブロック*経由で*ルーティングするために、少なくとも 1 つのフローグラフをアプリで定義してください。ACP は SHAPE ブロックを管理し、効率性を確保します。 ユーティリティ ファイルで宣言される構造体および列挙型を含む API セットの詳細については、[AcpHal](/reference/audio/acphal/acphal_members) リファレンスを参照してください。 SHAPE アーキテクチャの詳細については、[SHAPE の概要](/build/console-features/audio/overviews/shape-overview)を参照してください。 タイトル プロジェクトのソース ファイルでは、個別のコンテキスト ヘッダー ファイルではなく、*ShapeContext.h* ファイルをインクルードしてください。 このトピックの内容: * [フローグラフ](#ID4EVB) * [DMA ユーティリティ](#ID4EZH) * [EQ コンプレッサー ユーティリティ](#ID4EIAAC) * [フィルター ボリューム ユーティリティ](#ID4EWAAC) * [PCM ユーティリティ](#ID4EEBAC) * [SRC ユーティリティ](#ID4ESBAC) * [XMA ユーティリティ](#ID4EACAC) * [ターゲット値](#ID4EXEAC) * [スレッド セーフティ](#ID4E3NAC) * [PCM および XMA データに SRC を使用するためのガイドライン](#ID4EUPAC) * [タイトルの一時停止と再開](#ID4E5BAE) ### フローグラフ SHAPE を使用するには、タイトルは通常、SHAPE フローグラフを作成します。代替方法の説明については、[XMA ユーティリティ](#ID4EACAC)セクションを参照してください。SHAPE フローグラフは、SHAPE ブロックごとのコマンドの配列と、個々のブロックの操作の順序およびそれらが処理するデータを記述する付随コンテキスト データです。ACP は、フローグラフ内のデータを使用して、SHAPE ブロック内の操作を適切にスケジュールします。 タイトルは、フローグラフの構築と ACP への送信に責任を持ちます。フローグラフを構築するには、[ShapeFlowGraph (フローグラフ ユーティリティ メソッド)](/reference/audio/shapeflowgraph/shapeflowgraph_members) を使用してください。 以下の図では、緑のブロックが SHAPE コンポーネントを表し、シアンのブロックがソース素材、ラベル付きの黄色い円がハードウェア ミックス バッファーです。 * [3D サウンド](#ID4EHC) * [ソフトウェア オーディオ エンジンのフロント エンド](#ID4ETC) * [オーディオのレンダリング](#ID4E6C) * [フローグラフの解析](#ID4EHF) * [フローグラフの更新](#ID4EHG) * [複数のフローグラフ](#ID4ELH) #### 3D サウンド **図 1. 2 つの音声。それぞれが 2 つの出力の間でパンされ、共通の出力へのセンドがあります。** 2 つの音声のフローグラフ コードでは、このフローグラフは次のように表現できます。 ```cpp theme={null} typedef enum mixBuffers { noBuffer = 0, mixBuffer_1 = 1, mixBuffer_2 = 2, mixBuffer_3 = 3, mixBuffer_4 = 4, mixBuffer_5 = 5, mixBuffer_6 = 6, mixBuffer_7 = 7, mixBuffer_8 = 8, mixBuffer_9 = 9, mixBuffer_10 = 10, mixBuffer_11 = 11 }; typedef enum DMAcontexts { DMAcontext_0 = 0, DMAcontext_1 = 1, DMAcontext_2 = 2, DMAcontext_3 = 3, DMAcontext_4 = 4, }; typedef enum FLTVOLcontexts { FLTVOLcontext_0 = 0, FLTVOLcontext_1 = 1, FLTVOLcontext_2 = 2, FLTVOLcontext_3 = 3, FLTVOLcontext_4 = 4, FLTVOLcontext_5 = 5, FLTVOLcontext_6 = 6, FLTVOLcontext_7 = 7, }; typedef enum EQcontexts { EQcontext_0 = 0, EQcontext_1 = 1, }; typedef enum SRCcontexts { SRCcontext_0 = 0, SRCcontext_1 = 1, }; typedef enum XMAcontexts { XMAcontext_0 = 0, XMAcontext_1 = 1, }; // // Command structure to be initialized. // #define nSHAPE_3Dpan_commands 28 // SHAPE_FLOWGRAPH_COMMAND cmd[nSHAPE_3Dpan_commands]; // // Shared mix buffer. // // SetShapeAllocMixBufferCommand parameters: // command, virtualID, numIn, numOut, attenuation SetShapeAllocMixBufferCommand(&cmd[0], mixBuffer_1, 2, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); // // Mix buffers for voice A. // // SetShapeAllocMixBufferCommand parameters: // command, virtualID, numIn, numOut, attenuation SetShapeAllocMixBufferCommand(&cmd[1], mixBuffer_2, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[2], mixBuffer_3, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[3], mixBuffer_4, 1, 3, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[4], mixBuffer_5, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[5], mixBuffer_6, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); // // Voice A. // // SetShapeSrcXmaCommand parameters: // command, contextID, XMAContextID, leftorMonoMixBuffer, rightMixBuffer SetShapeSrcXmaCommand( &cmd[6], SRCcontext_0, XMAcontext_0, mixBuffer_2, noBuffer); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[7], FLTVOLcontext_0, mixBuffer_2, mixBuffer_3 ); // SetShapeEqCompCommand parameters: // command, contextID, inputMixBuffer, sidechainMixBuffer, outputMixBuffer SetShapeEqCompCommand( &cmd[8], EQcontext0, mixBuffer_3, noBuffer, mixBuffer_4); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[9], FLTVOLcontext_1, mixBuffer_4, mixBuffer_5 ); SetShapeFiltVolCommand(&cmd[10], FLTVOLcontext_2, mixBuffer_4, mixBuffer_6 ); SetShapeFiltVolCommand(&cmd[11], FLTVOLcontext_3, mixBuffer_4, mixBuffer_1 ); // // Mix buffers for voice B. // // SetShapeAllocMixBufferCommand parameters: // command, virtualID, numIn, nmmOut, attenuation SetShapeAllocMixBufferCommand(&cmd[12], mixBuffer_7, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[13], mixBuffer_8, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[14], mixBuffer_9, 1, 3, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[15], mixBuffer_10, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[16], mixBuffer_11, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); // // Voice B. // // SetShapeSrcXmaCommand parameters: // command, contextID, XMAContextID, leftorMonoMixBuffer, rightMixBuffer SetShapeSrcXmaCommand( &cmd[17], SRCcontext_1, XMAcontext_1, mixBuffer_7, noBuffer); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[18], FLTVOLcontext_4, mixBuffer_7, mixBuffer_8 ); // SetShapeEqCompCommand parameters: // command, contextID, inputMixBuffer, sidechainMixBuffer, outputMixBuffer SetShapeEqCompCommand( &cmd[19], EQcontext1, mixBuffer_8, noBuffer, mixBuffer_9); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[20], FLTVOLcontext_5, mixBuffer_9, mixBuffer_10 ); SetShapeFiltVolCommand(&cmd[21], FLTVOLcontext_6, mixBuffer_9, mixBuffer_11 ); SetShapeFiltVolCommand(&cmd[22], FLTVOLcontext_7, mixBuffer_9, mixBuffer_1 ); // // DMA all outputs. // // SetShapeDmaCommand parameters: // command, contextID, mixBuffer, write SetShapeDmaCommand( &cmd[23], DMAcontext_0, mixBuffer_1, true); SetShapeDmaCommand( &cmd[24], DMAcontext_1, mixBuffer_5, true); SetShapeDmaCommand( &cmd[25], DMAcontext_2, mixBuffer_6, true); SetShapeDmaCommand( &cmd[26], DMAcontext_3, mixBuffer_10, true); SetShapeDmaCommand( &cmd[27], DMAcontext_4, mixBuffer_11, true); ``` #### ソフトウェア オーディオ エンジンのフロント エンド **図 2. ソフトウェア エンジンの基本的なフロント エンド。このモデルを使用するすべての音声で、同じ構造を使用できる可能性があります。** ソフトウェア オーディオ エンジンの基本的なフロント エンド コードでは、このフローグラフは次のように表現できます。 ```cpp theme={null} typedef enum mixBuffers { noBuffer = 0, mixBuffer_1 = 1, mixBuffer_2 = 2, mixBuffer_3 = 3 }; typedef enum DMAcontexts { DMAcontext_0 = 0, }; typedef enum FLTVOLcontexts { FLTVOLcontext_0 = 0, }; typedef enum EQcontexts { EQcontext_0 = 0, }; typedef enum SRCcontexts { SRCcontext_0 = 0, }; typedef enum XMAcontexts { XMAcontext_0 = 0, }; // // Command structure to be initialized. // #define nSHAPE_frontend_commands 7 // SHAPE_FLOWGRAPH_COMMAND cmd[nSHAPE_frontend_commands]; // // Mix buffer allocation for the voice. // // SetShapeAllocMixBufferCommand parameters: // command, virtualID, numIn, numOut, attenuation SetShapeAllocMixBufferCommand(&cmd[0], mixBuffer_1, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[1], mixBuffer_2, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); SetShapeAllocMixBufferCommand(&cmd[2], mixBuffer_3, 1, 1, SHAPE_MIXBUFFER_ATTENUATION_0_DB); // // SHAPE blocks. // // SetShapeSrcXmaCommand parameters: // command, contextID, XMAContextID, leftorMonoMixBuffer, rightMixBuffer SetShapeSrcXmaCommand( &cmd[3], SRCcontext_0, XMAcontext_0, mixBuffer_1, noBuffer); // SetShapeEqCompCommand parameters: // command, contextID, inputMixBuffer, sidechainMixBuffer, outputMixBuffer SetShapeEqCompCommand( &cmd[4], EQcontext_0, mixBuffer_1, noBuffer, mixBuffer_2); // SetShapeFiltVolCommand parameters: // command, contextID, inputMixBuffer, outputMixBuffer SetShapeFiltVolCommand(&cmd[5], FLTVOLcontext_0, mixBuffer_2, mixBuffer_3 ); // SetShapeDmaCommand parameters: // command, contextID, mixBuffer, write SetShapeDmaCommand( &cmd[6], DMAcontext_0, mixBuffer_3, true ); ``` #### オーディオのレンダリング オーディオをレンダリングするには 1. 処理されるオーディオ グラフを定義する、前述の例のようなフローグラフを作成します。 2. フローグラフが何をどのように処理するかを定義するコンテキスト構造体を作成します。 3. [SubmitCommand](/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand) メソッドを使用して、フローグラフを ACP に送信します。`SubmitCommand` に渡されるパラメーターに基づいて、フローグラフは 1 回処理された後に破棄されるか、オーディオ フレームごとに処理されます。 4. タイトルは、`ACP_COMMAND_UPDATE_*_CONTEXT` コマンドを使用するか、フローグラフ処理と適切に同期して手動でコンテキストを更新することにより、オーディオ フレームごとにコンテキスト データを更新する責任があります。 * [ACP\_COMMAND\_UPDATE\_DMA\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_dma_context) * [ACP\_COMMAND\_UPDATE\_EQCOMP\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_eqcomp_context) * [ACP\_COMMAND\_UPDATE\_FILTVOL\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_filtvol_context) * [ACP\_COMMAND\_UPDATE\_PCM\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_pcm_context) * [ACP\_COMMAND\_UPDATE\_SRC\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_src_context) * [ACP\_COMMAND\_UPDATE\_XMA\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_xma_context) コンテキストを更新する際、[SubmitCommand](/reference/audio/acphal/interfaces/IAcpHal/methods/iacphal_submitcommand) のフラグ パラメーターによって、更新がすぐに行われるか、次のオーディオ フレームで行われるかが決定される点に注意してください。 コンテキストの更新を手動で同期する方法の詳細については、[ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/reference/audio/acphal/structs/acp_command_load_shape_flowgraph) コマンドを参照してください。一般に、`ACP_COMMAND_TYPE_UPDATE_*_CONTEXT` コマンドは、オーディオ フレームあたり少数のコンテキストを更新する場合に使用します。これらのコマンドを使用して大量のコンテキストを更新するのは、コマンドの処理に加えて大量のコンテキスト データを ACP にコピーおよび送信する必要があるため、効率的ではありません。大量のコンテキストを更新したい場合、タイトルはコンテキスト データを変更してから非永続的なフローグラフを ACP に送信するか、`ACP_COMMAND_TYPE_START_FLOWGRAPH` コマンドと [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/reference/audio/acphal/structs/acp_command_load_shape_flowgraph) コマンドの `waitForStart` パラメーターを上手く活用して、コンテキストが更新されるまで処理を保留する必要があります。フローグラフの処理が完了すると、コンテキストは再度更新可能な状態になります。 コンテキストを更新する第 3 の代替方法は、ダブル バッファリング プロセスを使用することです。タイトルは、フローグラフが処理されている間にコンテキストの 2 番目のコピーを更新し、オーディオ フレームの開始時にコンテキストをスワップできます。 #### フローグラフの解析 ACP は、オーディオ フレームの終了時に永続的なフローグラフの解析を終了します。ACP のオーディオ フレームは 2.667 ms の制限があります。タイトルにオーディオ フレームの 75% を処理に必要とするフローグラフがあるものの、タイトルがオーディオ フレームの 30% が経過するまで処理を開始させない場合、解析されなかったフローグラフの部分は削除されます。フローグラフ自体は変更されません。これが発生すると、タイトルがメッセージを受信するように登録されている場合、ACP は `ACP_MESSAGE_TYPE_FLOWGRAPH_TERMINATED` メッセージを送信します。内部の SHAPE キューに挿入されなかったコマンドを特定するには、タイトルはフローグラフ コマンドの `queued` フラグを検査します。 非永続的なフローグラフは、送信タイミングに関係なく、通常は完了まで処理されます。例外の 1 つは、ソース データが利用できないことや `disabled` フラグの不適切な使用による、1 つ以上のコマンドのブロックです。タイトルは、ACP オーディオ フレーム内のどの時点でも非永続的なフローグラフを送信でき、(いくつかの境界条件を除いて) 完了することが確実です。利点は、タイトルが ACP オーディオ フレーム間隔の 2.667 ms 内でフローグラフを引き続きサービスしている限り、オーディオ クロックと完全に同期している必要はないことです。リスクは、フローグラフを一貫して送信しない場合や、フローグラフが 2.667 ms を超える必要がある場合に、タイトルがオーディオ ドロップアウトを発生させる可能性があることです。 フローグラフのライフタイムの概要を以下に示します。 * 永続的なフローグラフは、新しいフローグラフや null フローグラフ (実質的に削除されます) を送信して置き換えられるまで、ACP 上でアクティブな状態を維持します。 * クライアントが ACP に対して開始コマンドを待つように指示しない限り、ACP はオーディオ フレームの先頭で永続的なフローグラフの処理を開始します。 * ACP は、完全に処理されていなくても、オーディオ フレームの終了直前に永続的なフローグラフの処理を停止します。 * 非永続的なフローグラフは、完了するまでのみアクティブで、その後は削除されます。 * 非永続的なフローグラフは、オーディオ フレーム間でもアクティブな状態を維持します。完了後にのみ削除されます。 コマンドの処理は、フローグラフの解析には縛られません。ACP は常に新しいコマンドをスキャンし、フローグラフを解析したり他の作業を行ったりしている間、可能な限り高速に処理します。 #### フローグラフの更新 フローグラフを更新するためのオプションは、前述のコンテキストを更新するオプションと似ています。基本的なルールは同じで、処理中のフローグラフは更新しないでください。 フローグラフを更新するには、次の 3 つの戦略を使用できます。 1. 非永続的なフローグラフを使用し、必要に応じて再構築し、オーディオ フレームの先頭で送信します。タイトルは、同じフローグラフを必要なだけ再利用できます。フローグラフが変わらない場合、タイトルはそれを再構築する必要はありません。古いフローグラフが処理されている間に新しいフローグラフを構築することで、このアプローチをダブル バッファーとすることもできます。再構築されるとき、フローグラフをゼロから構築できるだけでなく、ミックス バッファー ID を適切に設定することで、そのセクションを保存してリンクすることもできます。 2. 永続的なフローグラフを使用し、変更が必要な場合にのみ再構築および置換します。ここでもダブル バッファリングは機能します。[ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/reference/audio/acphal/structs/acp_command_load_shape_flowgraph) の `waitForStart` パラメーターを使用しないことで、ACP を自由に実行できます。ACP はオーディオ フレームが開始した直後、そのオーディオ フレームにタグ付けされたコマンドが処理された直後にフローグラフの処理を開始します。あるいは、`waitForStart` パラメーターを設定して、`ACP_COMMAND_TYPE_START_FLOWGRAPH` コマンドが送信されるまでフローグラフが処理されないようにすることもできます。これはフローグラフの更新自体に直接影響しませんが、同期の若干の改善を可能にします。 3. フローグラフ コマンドの `disabled` フラグを使用して、フローグラフの一部を無効にします。たとえば、マスター フローグラフを構築し、実行ごとに必要なセクションのみ有効にできます。ACP に新しいフローグラフを反映するには、これをオプション 1 または 2 と組み合わせる必要があります。ACP は現時点で孤立したブロックを探すためにフローグラフをトラバースしない点に注意してください。タイトルはフローグラフを介して完全なパスを無効にする必要があります (最初のノードだけではありません)。これが行われない場合、SHAPE コマンドが一時的にハードウェアを停止させます。これらの停止は、処理できず小さなコストで削除される単一ブロックなど、単純なものである可能性があります。また、音声全体を停止させるほど深刻なものである可能性もあります。 音声数が多いタイトルや、オーディオ フレームあたり多くの更新を行うタイトルには、ダブル バッファリング テクニックを使用してください。 タイトルが `ACP_MESSAGE_TYPE_FLOWGRAPH_COMPLETED` を使用して更新を管理している場合、ACP がメッセージ キューにメッセージを追加してからタイトルが `PopMessage` を呼び出すまでの間、ACP は長期間アイドル状態のままになる可能性があります。このアプローチで更新を管理しないでください - ACP をアクティブに保ってください。 #### 複数のフローグラフ タイトルは、複合的な要件がハードウェア機能を超えない限り、オーディオ フレームごとに複数のフローグラフを処理できます。利点は、タイトルがミドルウェアとカスタムの両方の複数のオーディオ エンジンを実行したり、解析をより管理しやすいチャンクに分割したりできることです。欠点は、このモードでは SHAPE ハードウェアが効率的に実行されないことです。SHAPE の最大スループットを実現するには、各 SHAPE ブロックを 100% ビジーに保つ必要がありますが、複数のフローグラフが処理されているときには不可能です。 ACP クライアントあたり読み込めるフローグラフは 1 つだけです。クライアントが新しいフローグラフを送信すると、既存のものと置き換わります。複数のフローグラフのサポートが必要なタイトルは、各フローグラフ タイプごとに個別のクライアント (各クライアントに独自のコマンドおよびメッセージ キューを持つ) を持つか、新しいフローグラフを送信する前にフローグラフの完了を待つ必要があります。 複数のフローグラフのサポートは、単一クライアントではなく、複数のクライアントで使用されるように設計されています。これにより、ミドルウェア エンジンがフローグラフを送信し、タイトルが追加のカスタム処理のために別のフローグラフを送信できます。タイトルが必要とする ACP クライアントごとに、`IACPHAL` インターフェイスのインスタンスを作成してください。 すべての ACP および SHAPE リソースはすべてのクライアント間で共有されるため (特にコンテキスト配列)、クライアントはそれらのリソースの割り当てと共有を調整する必要があります。 ### DMA ユーティリティ Direct Memory Access (DMA) ユーティリティは、*ShapeDMAContext.h* ファイルにインクルードされています。以下のユーティリティは、[SHAPE\_DMA\_CONTEXT](/reference/audio/shapedmacontext/structs/shape_dma_context) 構造体を操作します。詳細については、[ShapeDmaContext (DMA ユーティリティ メソッド)](/reference/audio/shapedmacontext/shapedmacontext_members) を参照してください。 ### EQ コンプレッサー ユーティリティ EQCOMP ユーティリティは、*ShapeEqCompContext.h* ファイルにインクルードされています。これらのユーティリティは、[SHAPE\_EQCOMP\_CONTEXT](/reference/audio/shapeeqcompcontext/structs/shape_eqcomp_context) 構造体を操作します。 詳細については、[ShapeEqCompContext (EQCOMP ユーティリティ メソッド)](/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members) を参照してください。 ### フィルター ボリューム ユーティリティ フィルター ボリューム ユーティリティは、*ShapeFiltVolContext.h* ファイルにインクルードされています。これらのユーティリティは、[SHAPE\_FILTVOL\_CONTEXT](/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context) 構造体を操作します。 詳細については、[ShapeFiltVolContext (FLTVOL ユーティリティ メソッド)](/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members) を参照してください。 ### PCM ユーティリティ Pulse Code Modulation (PCM) ユーティリティは、*ShapePCMContext.h* ファイルにインクルードされています。これらのユーティリティは、[SHAPE\_PCM\_CONTEXT](/reference/audio/shapepcmcontext/structs/shape_pcm_context) 構造体を操作します。 詳細については、[ShapePcmContext (PCM ユーティリティ メソッド)](/reference/audio/shapepcmcontext/shapepcmcontext_members) を参照してください。 ### SRC ユーティリティ Sample Rate Convertor (SRC) ユーティリティは、*ShapeSRCContext.h* ファイルにインクルードされています。これらのユーティリティは、[SHAPE\_SRC\_CONTEXT](/reference/audio/shapesrccontext/structs/shape_src_context) 構造体を操作します。 詳細については、[ShapeSrcContext (SRC ユーティリティ メソッド)](/reference/audio/shapesrccontext/shapesrccontext_members) を参照してください。 ### XMA ユーティリティ XMA ユーティリティは、*ShapeXMAContext.h* ファイルにインクルードされています。これらのユーティリティは、[SHAPE\_XMA\_CONTEXT](/reference/audio/shapexmacontext/structs/shape_xma_context) 構造体を操作します。 詳細については、[ShapeXmaContext (XMA ユーティリティ メソッド)](/reference/audio/shapexmacontext/shapexmacontext_members) を参照してください。 ハードウェア エミュレーションの XMA デコード機能は制限されています。詳細については、[SHAPE\_XMA\_CONTEXT](/reference/audio/shapexmacontext/structs/shape_xma_context) 構造体トピックを参照してください。 タイトルは、フローグラフを使用せずに XMA データを使用できますが、次の表に示すように、データは [ACP\_COMMAND\_TYPE](/reference/audio/acphal/enums/acp_command_type) コマンドを使用して ACP を経由する必要があります。 | コマンド | 説明 | | --------------------------------------- | -------------------------------------------------------------- | | `ACP_COMMAND_TYPE_ENABLE_XMA_CONTEXT` | 単一の XMA コンテキストを有効にし、ACP がコンテキストで指定されたバッファーのデコードを開始します。 | | `ACP_COMMAND_TYPE_ENABLE_XMA_CONTEXTS` | XMA コンテキストのブロックを有効にし、ACP がコンテキストで定義されたバッファーのデコードを開始します。 | | `ACP_COMMAND_TYPE_DISABLE_XMA_CONTEXT` | 単一の XMA コンテキストを無効にし、ACP がコンテキストで指定されたバッファーのデコードを停止します。 | | `ACP_COMMAND_TYPE_DISABLE_XMA_CONTEXTS` | XMA コンテキストのブロックを無効にし、ACP がコンテキストで定義されたバッファーのデコードを停止します。 | | `ACP_COMMAND_TYPE_UPDATE_XMA_CONTEXT` | XMA コンテキストの 1 つ以上のフィールドを更新します。これは、ACP 上で同期的に、または非同期に行うことができます。 | これらのコマンドを使用することで、タイトルは XBOX One ACP HAL を XBOX 360 XMA HAL とほぼ同じように、次の操作順序で使用できます。 1. バッファー、オフセットなどの関連データでコンテキストを設定します。 2. コンテキストを有効にします。 3. コンテキストを更新します。コンテキストが無効になっている場合、タイトルは自由に内容を直接変更できます。コンテキストが有効になっている場合、タイトルはまず無効にするか、`ACP_COMMAND_TYPE_UPDATE_XMA_CONTEXT` コマンドを使用できます。後者では、ACP が無効化、待機、および更新を処理してくれるため、より効率的な場合があります。 一般に、タイトルは SHAPE の XMA コンポーネントのみを使用しないでください。わずかなメンテナンスだけで無料で高品質な SRC やその他の機能を提供してくれる「フロント エンド」フローグラフを作成するのは、ほとんど自明です。フローグラフは作成および管理が容易で、メイン CPU から SRC をオフロードして品質を向上させます。 ### ターゲット値 ユーティリティ関数で設定できるターゲット値は、オーディオ フレーム終了時のパラメーターの最終値を表します。たとえば、[SHAPE\_FILTVOL\_CONTEXT](/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context) 構造体には、`gain` と `gainTarget` の値が含まれます。フレームが処理されている間、`gain` は次の方程式による線形補間を使用して計算されます。 ```cpp theme={null} gain = ((gainTarget - gain) / 127) * i + gain ``` ここで i は 0 から 127 まで変化します。 フレームの終了時に、`gain` は `gainTarget` と等しくなります。 ACP のターゲット パラメーターは、次の表に示すように設定できます。 | コンポーネント | ターゲット | 説明 | | ------- | ------------------------- | ------------------------- | | EQCOMP | `eqAB0Target` | EQ A b0 係数ターゲット | | EQCOMP | `eqAB1Target_L` | EQ A b1 係数ターゲット、下位 8 ビット | | EQCOMP | `eqAB1Target_H` | EQ A b1 係数ターゲット、上位 16 ビット | | EQCOMP | `eqAB2Target_L` | EQ A b2 係数ターゲット、下位 16 ビット | | EQCOMP | `eqAB2Target_H` | EQ A b2 係数ターゲット、上位 8 ビット | | EQCOMP | `eqAA1Target` | EQ A a1 係数ターゲット | | EQCOMP | `eqAA2Target` | EQ A a2 係数ターゲット | | EQCOMP | `eqBB0Target_L` | EQ B b0 係数ターゲット、下位 8 ビット | | EQCOMP | `eqBB0Target_H` | EQ B b0 係数ターゲット、上位 16 ビット | | EQCOMP | `eqBB1Target_L` | EQ B b1 係数ターゲット、下位 16 ビット | | EQCOMP | `eqBB1Target_H` | EQ B b1 係数ターゲット、上位 8 ビット | | EQCOMP | `eqBB2Target` | EQ B b2 係数ターゲット | | EQCOMP | `eqBA1Target` | EQ B a1 係数ターゲット | | EQCOMP | `eqBA2Target_L` | EQ B a2 係数ターゲット、下位 8 ビット | | EQCOMP | `eqBA2Target_H` | EQ B a2 係数ターゲット、上位 16 ビット | | EQCOMP | `eqCB0Target_L` | EQ C b0 係数ターゲット、下位 16 ビット | | EQCOMP | `eqCB0Target_H` | EQ C b0 係数ターゲット、上位 8 ビット | | EQCOMP | `eqCB1Target` | EQ C b1 係数ターゲット | | EQCOMP | `eqCB2Target` | EQ C b2 係数ターゲット | | EQCOMP | `eqCA1Target_L` | EQ C a1 係数ターゲット、下位 8 ビット | | EQCOMP | `eqCA1Target_H` | EQ C a1 係数ターゲット、上位 16 ビット | | EQCOMP | `eqCA2Target_L` | EQ C a2 係数ターゲット、下位 16 ビット | | EQCOMP | `eqCA2Target_H` | EQ C a2 係数ターゲット、上位 8 ビット | | EQCOMP | `compGainTarget` | 出力ゲインのユーザー設定可能ターゲット | | FILTVOL | `gainTarget` | ボリューム ターゲット レベル | | FILTVOL | `qRecipTarget` | ターゲット 1/Q 値 | | FILTVOL | `fcTarget` | ターゲット周波数値 | | SRC | `samplingIncrementTarget` | サンプリング増分の終了値 | ### スレッド セーフティ [IACPHAL インターフェイスのメソッド](/reference/audio/acphal/interfaces/IAcpHal/iacphal)および [ACPHAL メソッド](/reference/audio/acphal/acphal_members)はスレッドセーフです。[ApuCreateHeap](/reference/audio/apu/functions/apucreateheap) 呼び出しが行われる場合、ヒープはすべてのスレッドで使用されます。 以下のユーティリティ関数はスレッドセーフでは*ありません*。ただし、それらのソース コードが提供されています。必要に応じて、スレッドセーフにできます。一般的な方法は、[Critical Section Objects](https://msdn.microsoft.com/library/windows/desktop/ms682530\(v=vs.85\).aspx) を使用することです。 * [ShapeFlowGraph (フローグラフ)](/reference/audio/shapeflowgraph/shapeflowgraph_members) * [ShapeDmaContext (DMA)](/reference/audio/shapedmacontext/shapedmacontext_members) * [ShapeEqCompContext (EQCOMP)](/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members) * [ShapeFiltVolContext (FLTVOL)](/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members) * [ShapePcmContext (PCM)](/reference/audio/shapepcmcontext/shapepcmcontext_members) * [ShapeSrcContext (SRC)](/reference/audio/shapesrccontext/shapesrccontext_members) * [ShapeXmaContext (XMA)](/reference/audio/shapexmacontext/shapexmacontext_members) ### PCM および XMA データに SRC を使用するためのガイドライン 次の表は、SRC ブロックを PCM および XMA データで使用するためのガイドラインを示しています。 | ターゲット | 実装 | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 非ループ リニア PCM | SRC の `SHAPE_SRC_COMMAND_TYPE_START` を使用して音声を開始します。音声を最後まで再生させます。オプションで、`SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` を使用して終了前に停止することもできます。 | | 無限ループ リニア PCM | PCM コンテキストのループ カウント (`loopCount`) を `SHAPE_PCM_INFINITE_LOOP_COUNT` に設定します。SRC の `SHAPE_SRC_COMMAND_TYPE_START` を使用して音声を開始します。ループの終わりで停止したいときに `SHAPE_SRC_COMMAND_TYPE_STOP_END` を発行するまで音声を再生させ、音声を再生し切ります。オプションで、`SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` を発行することで即座に停止することもできます。 | | 有限ループ リニア PCM | PCM コンテキストのループ カウント (`loopCount`) を \[0, 254] に設定します。SRC の `SHAPE_SRC_COMMAND_TYPE_START` を使用して音声を開始します。音声を最後まで再生させます。オプションで、`SHAPE_SRC_COMMAND_TYPE_STOP_END` を使用してループの終わりで停止し、音声を再生し切ることもできます。オプションで、`SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` を発行することで即座に停止することもできます。 | | 循環 PCM | SRC の `SHAPE_SRC_COMMAND_TYPE_START` を使用して音声を開始します。停止したいときまで、データのストリーミングと PCM コンテキストの書き込みポインターの更新を続けます。`SHAPE_SRC_COMMAND_TYPE_STOP_END` を発行して、現在の PCM 書き込みポインター (`loopStartWritePointer`) まで SRC を再生させます。オプションで、`SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` を発行することで即座に停止することもできます。 | | ストリーミング (HW ループなし) XMA | SRC の `SHAPE_SRC_COMMAND_TYPE_START` を使用して音声を開始します。最後の XMA 入力バッファーが消費されたら、`SHAPE_SRC_COMMAND_TYPE_STOP_END` を発行してデコード バッファーの終わりまで再生します (以下の注記を参照)。オプションで、`SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` を発行することで即座に停止することもできます。 | | 無限 HW ループ XMA | XMA コンテキストのループ カウント (`numLoops`) を `SHAPE_XMA_INFINITE_LOOP_COUNT` に設定します。SRC の `SHAPE_SRC_COMMAND_TYPE_START` を使用して音声を開始します。ループの終わりで停止したいときに XMA ループ カウントをゼロに設定し、`SHAPE_SRC_COMMAND_TYPE_STOP_END` を発行し、音声を再生し切ります。オプションで、`SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` を発行することで即座に停止することもできます。 | | 有限 HW ループ XMA | XMA コンテキストのループ カウント (`numLoops`) を \[0, 254] に設定します。SRC の `SHAPE_SRC_COMMAND_TYPE_START` を使用して音声を開始します。ループ カウントを監視して、ループの終わりで停止したいときまで音声を再生させます。ゼロになったら、`SHAPE_SRC_COMMAND_TYPE_STOP_END` を発行し、音声を再生し切ります。オプションで、次のループの終わりで停止する場合はループ カウントをゼロに設定します。最後の XMA 入力バッファーが消費されたら、SRC コマンドを `SHAPE_SRC_COMMAND_TYPE_STOP_END` に設定し、音声を再生し切ります (以下の注記を参照)。即座に停止するには、`SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` を発行します。 | これらのシナリオのいずれかが完了すると、SRC コマンドは `SHAPE_SRC_COMMAND_TYPE_STOP_IMMEDIATE` になります。 XMA 入力バッファーの有効ビットを、SHAPE フローグラフの処理に使用するのと同じ頻度で確認してください。この確認をストリーミング ロジック (はるかに長い間隔で行われます) の一部として行うと、SRC に最後で停止するよう指示する前に XMA 出力バッファーが空になる可能性があります。これによりフローグラフが停止する可能性があります。 ### タイトルの一時停止と再開 タイトルは、たとえばユーザーが Constrained モードにしたときなど、一時停止と再開ができる必要があります。`IAcpHal` を使用して SHAPE ハードウェアに直接コーディングする場合の一時停止と再開では、タイトルは単にコマンドの送信を停止するようにしてください。既に送信されたコマンドは正常に完了し、メッセージ キューを埋める可能性があります。 タイトルが永続的なフローグラフを使用している場合は、処理を停止するために null フローグラフを読み込む必要があります。これは、`XAudio2` を使用してコーディングする場合の一時停止および再開プロセスとは異なります。詳細については、[XAudio2 の概要](/build/console-features/audio/overviews/xaudio2-overview)を参照してください。 ## リファレンス API ドキュメント * [Acphal (API 内容)](/reference/audio/acphal/acphal_members) * 構造体 * [ACP\_COMMAND\_UPDATE\_DMA\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_dma_context) * [ACP\_COMMAND\_UPDATE\_EQCOMP\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_eqcomp_context) * [ACP\_COMMAND\_UPDATE\_FILTVOL\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_filtvol_context) * [ACP\_COMMAND\_UPDATE\_PCM\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_pcm_context) * [ACP\_COMMAND\_UPDATE\_SRC\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_src_context) * [ACP\_COMMAND\_UPDATE\_XMA\_CONTEXT](/reference/audio/acphal/structs/acp_command_update_xma_context) * [ACP\_COMMAND\_LOAD\_SHAPE\_FLOWGRAPH](/reference/audio/acphal/structs/acp_command_load_shape_flowgraph) * [Shapedmacontext (API 内容)](/reference/audio/shapedmacontext/shapedmacontext_members) * 構造体 * [SHAPE\_DMA\_CONTEXT](/reference/audio/shapedmacontext/structs/shape_dma_context) * [Shapeeqcompcontext (API 内容)](/reference/audio/shapeeqcompcontext/shapeeqcompcontext_members) * 構造体 * [SHAPE\_EQCOMP\_CONTEXT](/reference/audio/shapeeqcompcontext/structs/shape_eqcomp_context) * [Shapefiltvolcontext (API 内容)](/reference/audio/shapefiltvolcontext/shapefiltvolcontext_members) * 構造体 * [SHAPE\_FILTVOL\_CONTEXT](/reference/audio/shapefiltvolcontext/structs/shape_filtvol_context) * [Shapeflowgraph (API 内容)](/reference/audio/shapeflowgraph/shapeflowgraph_members) * [Shapepcmcontext (API 内容)](/reference/audio/shapepcmcontext/shapepcmcontext_members) * 構造体 * [SHAPE\_PCM\_CONTEXT](/reference/audio/shapepcmcontext/structs/shape_pcm_context) * [Shapesrccontext (API 内容)](/reference/audio/shapesrccontext/shapesrccontext_members) * 構造体 * [SHAPE\_SRC\_CONTEXT](/reference/audio/shapesrccontext/structs/shape_src_context) * [Shapexmacontext (API 内容)](/reference/audio/shapexmacontext/shapexmacontext_members) * 構造体 * [SHAPE\_XMA\_CONTEXT](/reference/audio/shapexmacontext/structs/shape_xma_context) * [apu (API 内容)](/reference/audio/apu/apu_members) * 関数 * [ApuCreateHeap](/reference/audio/apu/functions/apucreateheap) ## Related topics - [SHAPE の概要](/ja-jp/build/console-features/audio/overviews/shape-overview.md) - [ACP_COMMAND_TYPE](/ja-jp/reference/audio/acphal/enums/acp_command_type.md) - [ACP_COMMAND_UPDATE_DMA_CONTEXT](/ja-jp/reference/audio/acphal/structs/acp_command_update_dma_context.md) - [ACP_COMMAND_UPDATE_EQCOMP_CONTEXT](/ja-jp/reference/audio/acphal/structs/acp_command_update_eqcomp_context.md) - [ACP_COMMAND_UPDATE_FILTVOL_CONTEXT](/ja-jp/reference/audio/acphal/structs/acp_command_update_filtvol_context.md)