ACP の概要

このトピックでは、Audio Control Processor (ACP) の制御に使用されるフローグラフの説明と例を紹介します。

このセクションでは、ACP のプログラミングインターフェイスについて説明します。 acphal ライブラリ (acphal.lib) は、Scalable Hardware Audio Processing Engine (SHAPE) の API セットを定義します。また、Microsoft Game Development Kit (GDK) には、SHAPE で使用するオーディオデータを準備するのに役立つオーディオユーティリティとソースコードのコレクションも含まれています。ユーティリティヘッダーは、次の内容を定義します。

サポートされている各データ形式のコンテキスト構造体
これらのコンテキストの読み取りと書き込みに使用できる完全な関数セット

オーディオデータを SHAPE ブロック経由でルーティングするために、少なくとも 1 つのフローグラフをアプリで定義してください。ACP は SHAPE ブロックを管理し、効率性を確保します。ユーティリティファイルで宣言される構造体および列挙型を含む API セットの詳細については、AcpHal リファレンスを参照してください。 SHAPE アーキテクチャの詳細については、SHAPE の概要を参照してください。タイトルプロジェクトのソースファイルでは、個別のコンテキストヘッダーファイルではなく、ShapeContext.h ファイルをインクルードしてください。このトピックの内容:

フローグラフ
DMA ユーティリティ
EQ コンプレッサーユーティリティ
フィルターボリュームユーティリティ
PCM ユーティリティ
SRC ユーティリティ
XMA ユーティリティ
ターゲット値
スレッドセーフティ
PCM および XMA データに SRC を使用するためのガイドライン
タイトルの一時停止と再開

フローグラフ

SHAPE を使用するには、タイトルは通常、SHAPE フローグラフを作成します。代替方法の説明については、XMA ユーティリティセクションを参照してください。SHAPE フローグラフは、SHAPE ブロックごとのコマンドの配列と、個々のブロックの操作の順序およびそれらが処理するデータを記述する付随コンテキストデータです。ACP は、フローグラフ内のデータを使用して、SHAPE ブロック内の操作を適切にスケジュールします。タイトルは、フローグラフの構築と ACP への送信に責任を持ちます。フローグラフを構築するには、ShapeFlowGraph (フローグラフユーティリティメソッド) を使用してください。以下の図では、緑のブロックが SHAPE コンポーネントを表し、シアンのブロックがソース素材、ラベル付きの黄色い円がハードウェアミックスバッファーです。

3D サウンド
ソフトウェアオーディオエンジンのフロントエンド
オーディオのレンダリング
フローグラフの解析
フローグラフの更新
複数のフローグラフ

3D サウンド

図 1. 2 つの音声。それぞれが 2 つの出力の間でパンされ、共通の出力へのセンドがあります。 コードでは、このフローグラフは次のように表現できます。

        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. ソフトウェアエンジンの基本的なフロントエンド。このモデルを使用するすべての音声で、同じ構造を使用できる可能性があります。 コードでは、このフローグラフは次のように表現できます。

        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   );  

オーディオのレンダリング

オーディオをレンダリングするには

処理されるオーディオグラフを定義する、前述の例のようなフローグラフを作成します。
フローグラフが何をどのように処理するかを定義するコンテキスト構造体を作成します。
SubmitCommand メソッドを使用して、フローグラフを ACP に送信します。SubmitCommand に渡されるパラメーターに基づいて、フローグラフは 1 回処理された後に破棄されるか、オーディオフレームごとに処理されます。
タイトルは、ACP_COMMAND_UPDATE_*_CONTEXT コマンドを使用するか、フローグラフ処理と適切に同期して手動でコンテキストを更新することにより、オーディオフレームごとにコンテキストデータを更新する責任があります。
コンテキストを更新する際、SubmitCommand のフラグパラメーターによって、更新がすぐに行われるか、次のオーディオフレームで行われるかが決定される点に注意してください。

コンテキストの更新を手動で同期する方法の詳細については、ACP_COMMAND_LOAD_SHAPE_FLOWGRAPH コマンドを参照してください。一般に、ACP_COMMAND_TYPE_UPDATE_*_CONTEXT コマンドは、オーディオフレームあたり少数のコンテキストを更新する場合に使用します。これらのコマンドを使用して大量のコンテキストを更新するのは、コマンドの処理に加えて大量のコンテキストデータを ACP にコピーおよび送信する必要があるため、効率的ではありません。大量のコンテキストを更新したい場合、タイトルはコンテキストデータを変更してから非永続的なフローグラフを ACP に送信するか、ACP_COMMAND_TYPE_START_FLOWGRAPH コマンドと 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 つの戦略を使用できます。

非永続的なフローグラフを使用し、必要に応じて再構築し、オーディオフレームの先頭で送信します。タイトルは、同じフローグラフを必要なだけ再利用できます。フローグラフが変わらない場合、タイトルはそれを再構築する必要はありません。古いフローグラフが処理されている間に新しいフローグラフを構築することで、このアプローチをダブルバッファーとすることもできます。再構築されるとき、フローグラフをゼロから構築できるだけでなく、ミックスバッファー ID を適切に設定することで、そのセクションを保存してリンクすることもできます。
永続的なフローグラフを使用し、変更が必要な場合にのみ再構築および置換します。ここでもダブルバッファリングは機能します。ACP_COMMAND_LOAD_SHAPE_FLOWGRAPH の waitForStart パラメーターを使用しないことで、ACP を自由に実行できます。ACP はオーディオフレームが開始した直後、そのオーディオフレームにタグ付けされたコマンドが処理された直後にフローグラフの処理を開始します。あるいは、waitForStart パラメーターを設定して、ACP_COMMAND_TYPE_START_FLOWGRAPH コマンドが送信されるまでフローグラフが処理されないようにすることもできます。これはフローグラフの更新自体に直接影響しませんが、同期の若干の改善を可能にします。
フローグラフコマンドの 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 構造体を操作します。詳細については、ShapeDmaContext (DMA ユーティリティメソッド) を参照してください。

EQ コンプレッサーユーティリティ

EQCOMP ユーティリティは、ShapeEqCompContext.h ファイルにインクルードされています。これらのユーティリティは、SHAPE_EQCOMP_CONTEXT 構造体を操作します。詳細については、ShapeEqCompContext (EQCOMP ユーティリティメソッド) を参照してください。

フィルターボリュームユーティリティ

フィルターボリュームユーティリティは、ShapeFiltVolContext.h ファイルにインクルードされています。これらのユーティリティは、SHAPE_FILTVOL_CONTEXT 構造体を操作します。詳細については、ShapeFiltVolContext (FLTVOL ユーティリティメソッド) を参照してください。

PCM ユーティリティ

Pulse Code Modulation (PCM) ユーティリティは、ShapePCMContext.h ファイルにインクルードされています。これらのユーティリティは、SHAPE_PCM_CONTEXT 構造体を操作します。詳細については、ShapePcmContext (PCM ユーティリティメソッド) を参照してください。

SRC ユーティリティ

Sample Rate Convertor (SRC) ユーティリティは、ShapeSRCContext.h ファイルにインクルードされています。これらのユーティリティは、SHAPE_SRC_CONTEXT 構造体を操作します。詳細については、ShapeSrcContext (SRC ユーティリティメソッド) を参照してください。

XMA ユーティリティ

XMA ユーティリティは、ShapeXMAContext.h ファイルにインクルードされています。これらのユーティリティは、SHAPE_XMA_CONTEXT 構造体を操作します。詳細については、ShapeXmaContext (XMA ユーティリティメソッド) を参照してください。ハードウェアエミュレーションの XMA デコード機能は制限されています。詳細については、SHAPE_XMA_CONTEXT 構造体トピックを参照してください。タイトルは、フローグラフを使用せずに XMA データを使用できますが、次の表に示すように、データは 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 とほぼ同じように、次の操作順序で使用できます。

バッファー、オフセットなどの関連データでコンテキストを設定します。
コンテキストを有効にします。
コンテキストを更新します。コンテキストが無効になっている場合、タイトルは自由に内容を直接変更できます。コンテキストが有効になっている場合、タイトルはまず無効にするか、ACP_COMMAND_TYPE_UPDATE_XMA_CONTEXT コマンドを使用できます。後者では、ACP が無効化、待機、および更新を処理してくれるため、より効率的な場合があります。

一般に、タイトルは SHAPE の XMA コンポーネントのみを使用しないでください。わずかなメンテナンスだけで無料で高品質な SRC やその他の機能を提供してくれる「フロントエンド」フローグラフを作成するのは、ほとんど自明です。フローグラフは作成および管理が容易で、メイン CPU から SRC をオフロードして品質を向上させます。

ターゲット値

ユーティリティ関数で設定できるターゲット値は、オーディオフレーム終了時のパラメーターの最終値を表します。たとえば、SHAPE_FILTVOL_CONTEXT 構造体には、gain と gainTarget の値が含まれます。フレームが処理されている間、gain は次の方程式による線形補間を使用して計算されます。

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 インターフェイスのメソッドおよび ACPHAL メソッドはスレッドセーフです。ApuCreateHeap 呼び出しが行われる場合、ヒープはすべてのスレッドで使用されます。以下のユーティリティ関数はスレッドセーフではありません。ただし、それらのソースコードが提供されています。必要に応じて、スレッドセーフにできます。一般的な方法は、Critical Section Objects を使用することです。

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 の概要を参照してください。

リファレンス API ドキュメント

Acphal (API 内容)
- 構造体
Shapedmacontext (API 内容)
- 構造体
  - SHAPE_DMA_CONTEXT
Shapeeqcompcontext (API 内容)
- 構造体
  - SHAPE_EQCOMP_CONTEXT
Shapefiltvolcontext (API 内容)
- 構造体
  - SHAPE_FILTVOL_CONTEXT
Shapeflowgraph (API 内容)
Shapepcmcontext (API 内容)
- 構造体
  - SHAPE_PCM_CONTEXT
Shapesrccontext (API 内容)
- 構造体
  - SHAPE_SRC_CONTEXT
Shapexmacontext (API 内容)
- 構造体
  - SHAPE_XMA_CONTEXT
apu (API 内容)
- 関数
  - ApuCreateHeap

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

ACP の概要

ACP の概要

フローグラフ

3D サウンド

ソフトウェアオーディオエンジンのフロントエンド

オーディオのレンダリング

フローグラフの解析

フローグラフの更新

複数のフローグラフ

DMA ユーティリティ

EQ コンプレッサーユーティリティ

フィルターボリュームユーティリティ

PCM ユーティリティ

SRC ユーティリティ

XMA ユーティリティ

ターゲット値

スレッドセーフティ

PCM および XMA データに SRC を使用するためのガイドライン

タイトルの一時停止と再開

リファレンス API ドキュメント

​ACP の概要

​フローグラフ

​3D サウンド

​ソフトウェア オーディオ エンジンのフロント エンド

​オーディオのレンダリング

​フローグラフの解析

​フローグラフの更新

​複数のフローグラフ

​DMA ユーティリティ

​EQ コンプレッサー ユーティリティ

​フィルター ボリューム ユーティリティ

​PCM ユーティリティ

​SRC ユーティリティ

​XMA ユーティリティ

​ターゲット値

​スレッド セーフティ

​PCM および XMA データに SRC を使用するためのガイドライン

​タイトルの一時停止と再開

​リファレンス API ドキュメント

ACP の概要

フローグラフ

3D サウンド

ソフトウェアオーディオエンジンのフロントエンド

オーディオのレンダリング

フローグラフの解析

フローグラフの更新

複数のフローグラフ

DMA ユーティリティ

EQ コンプレッサーユーティリティ

フィルターボリュームユーティリティ

PCM ユーティリティ

SRC ユーティリティ

XMA ユーティリティ

ターゲット値

スレッドセーフティ

PCM および XMA データに SRC を使用するためのガイドライン

タイトルの一時停止と再開

リファレンス API ドキュメント