イントロダクション

SDK API は、MIDI イベントをサウンドエンジンにポストする関数を提供します。ポストされる可能性のあるThe types of MIDI イベントの種類は以下の通りです:

• ノートオンイベント。
• ノートオフイベント。
• そしてコンティニュアス コントローラ (continuous controller: CC) イベント。

MIDI イベントがサウンドを生成するには、ターゲットとなるシンセサイザーが必要です。このシンセサイザーは、プロジェクトのアクターミキサー階層でWwiseユーザーが作成したWwiseオブジェクトのコレクションです。 ノートオンイベントは、通常ターゲットのアクターミキサーオブジェクト、またはその子孫の1つを再生します。再生されると、アクターミキサーオブジェクトは次の事柄で停止します:

• ループに設定されていなければ、そのソースの最後に達した時、
• または、対応するセットオフイベント (同じ音ならびにチャンネル) が同じターゲットに送られる。

ゲームへのMIDI Event統合

AK::SoundEngine::PostMIDIOnEvent の "PostMIDIOnEvent" 関数は、MIDIイベントをサウンドエンジンのキューに入れます。この関数は引数として次を受け取ります:

• MIDIイベント。
• Event ID。
• Game Object ID。
• Playing ID。

サウンドエンジンは、ポストされたMIDIイベントをシーケンスにグループ化します。 各シーケンスは次によって特定します:

• ゲームオブジェクト ID; 関数のパラメータ、
• Playing ID; 関数のパラメータ、
• Wwiseオブジェクト ID; イベント IDに対応するイベントの、各プレイアクションのターゲットオブジェクトから取得。 Eventに関する詳細は、 Event（イベント）の統合 を参照してください。

従って、同じMIDIイベント(複数可) を複数のターゲットに同時にポストすることも可能です。例えば、次のような例を考えてみましょう:

• EV1イベントには、Wwise オブジェクト W0 および W1両方のプレイアクションがあります。
• EV2イベントには、Wwise オブジェクト W0のプレイアクションがあります。

MIDIイベントのME1をGame Object GOでEV1にポストすると、サウンドエンジンはMIDIイベントのME1を、MIDIシーケンスのW0-GO-PID1とW1-GO-PID1に追加しますが、このPID1は、PostMIDIOnEventで返されたPlaying IDです。 MIDIイベントME2をイベントEV2にポストすると、サウンドエンジンはMIDIイベントME2をMIDIシーケンスW0-GO-PID2に追加します。

AK::SoundEngine::PostMIDIOnEvent の呼び出しは、MIDIイベントをMIDIシーケンスに追加します。 しかしながら、AK::SoundEngine::RenderAudio() 関数が呼び出されるまではイベントの処理が実行されません。AK::SoundEngine::RenderAudioへの各呼び出しは、メッセージキューを処理し、 オーディオフレームをいくつでも生成できますが、直近RenderAudioからどれくらいの時間が経過しているかに依存します。RenderAudioが生成する各フレームについては、サウンドエンジンはフレーム一つ毎にすべてのMIDIシーケンスを前に進めます。

MIDIイベントのタイミング

MIDIイベントが実行される瞬間は、以下の要素によって決まります:

• キューに入った瞬間（PostMIDIOnEvent経由）
• イベントのメンバーのAkMIDIPost::uOffset
• PostMIDIOnEventの呼び出しに提供された引数in_bAbsoluteOffsets

in_bAbsoluteOffsetsがfalseであれば、MIDIイベントが実行されるのは、サウンドエンジンのメッセージキューからPostMIDIOnEventメッセージを読み取ったタイミングから、サンプル数uOffsetだけ経過したときです（ MIDIシーケンスの更新 参照）。 in_bAbsoluteOffsetsがtrueであれば、MIDIイベントが実行されるのは、絶対時間でサンプル数uOffsetです。現在の絶対時間は、 AK::SoundEngine::GetSampleTick を呼び出して取得します。

注釈: サンプルの長さは、 AK::SoundEngine::GetAudioSettings を呼び出してサウンドエンジンのオーディオ設定から判断できます。

MIDIイベントのシーケンス - Playing ID

PostMIDIOnEventを呼び出すと、ポストしたすべてのMIDIイベントがMIDIシーケンスにまとめられます。前述の通り、MIDIシーケンスは以下で識別します:

• Playing ID
• Game Object ID
• Event ID。 シーケンスのPlaying IDを作成するには、in_playingIDを AK_INVALID_PLAYING_ID に設定してPostMIDIOnEventを呼び出します。Playing IDは、あとでMIDIイベントをシーケンスに追加するためにPostMIDIOnEventを呼び出すときに使います。シーケンスは、以下の通りです:
• 最初にPostMIDIOnEventを呼び出すと、MIDIシーケンスが作成されます。関数の引数のin_playingIDを、 AK_INVALID_PLAYING_ID に設定します。関数が、Playing ID PIDを返します。
• このシーケンスにイベントを追加するために、続いてPostMIDIOnEventを呼び出します。関数の引数の in_playingID を、PIDに設定します。

PostMIDIOnEventによって返されるPlaying IDで、意図するシーケンスにイベントがポストされたかどうかが分かります。返されたPlaying IDが、

• in_playingIDと合致すれば、イベントが意図するシーケンスに追加されました。
• in_playingIDと合致しなければ、イベントは、新たに作成したシーケンスに追加されました。
• AK_INVALID_PLAYING_IDであれば、エラーが発生したため、イベントは、どのシーケンスにも追加されませんでした。

指定したシーケンスとは別のシーケンスが新たに作成されるのは、以下の場合です:

• シーケンス（Playing ID）が存在しない場合
• シーケンスが、別のGame ObjectまたはEventを使い作成された場合
• すべてのMIDIイベントが実行され、すべての再生中のサウンドが終了したため、シーケンスがすでに存在しない場合

MIDIシーケンスの更新

各MIDIシーケンスを、サウンドエンジンがアプリケーションが意図する的確なタイミングで再生することは重要です。MIDIシーケンスをサウンドエンジンにポストする方法は二つあります。

全体のMIDIシーケンスが既知であり、MIDIシーケンスのタイミングに変更がないとわかっている場合、MIDIシーケンス全体をAK::SoundEngine::PostMIDIOnEventを一度呼び出すだけでポストすることができます。

しかしそうでない場合には、MIDIシーケンスを各フレームで更新する必要があります。AK::SoundEngine::PostMIDIOnEvent 関数は、アプリケーションのどの時点でも、どこでも呼び出すことはできます。 しかし、メインのオーディオスレッド以外で呼び出すと、同期に問題が発生します。AK::SoundEngine::PostMIDIOnEvent の呼び出しは、イベントのみをサウンドエンジンのメッセージキューでポストします。このメッセージキューは、AK::SoundEngine::RenderAudioの呼び出し中に処理され、そのような呼び出しは幾つかの処理されたオーディオフレームへと続きます。 適切な同期を行うには、アプリケーションが次のようにグローバルコールバック関数を登録することを推奨します:

• AK::SoundEngine::RegisterGlobalCallback( &MyCallbackFunction, AkGlobalCallbackLocation_PreProcessMessageQueueForRender );

登録された関数は、各オーディオフレームでサウンドエンジンに呼び出されます。アプリケーションんはコールバック関数を使用して、サウンドエンジンが処理するオーディオフレームの最新状態を追跡します。 従って、MIDIイベントをコールバック関数にポストすると、確実に適切な同期が行われます。

MIDIシーケンスの停止

AK::SoundEngine::StopMIDIOnEvent "StopMIDIOnEvent" 関数を呼び出して、MIDIシーケンスを停止します。 この関数がパラメータとして受け入れるのは、Playing ID、Event ID、そしてGame Object IDです。 これらのパラメータは、どれも無効の値を設定すれば、ワイルドカードとして機能します。従って、すべての引数の設定が無効であれば、すべてのMIDIシーケンスが停止されます。

この関数の呼び出しは、MIDIシーケンス(複数可)をクリアして、いずれのサウンドの再生を停止します。

MIDIの統合の例は、クイックスタートサンプル統合 - MIDI を参照してください。