バージョン
ゲームのインタラクティブミュージックを作成する時、音楽のビートに関する情報が必要です。サウンドエンジンから、ミュージック通知を使用してこの情報を要求することができます。ビートは、再生中の主要な音楽セグメントによって決定されます。セグメントには様々な拍子があるので、再生中の音楽によってビートが変化します。再生中の音楽がない場合は、通知は行われません。
ミュージックコールバックには、以下の2種類がある。
音楽に関するマーカー通知を受信したい場合は、アプリケーションを設計する時に注意しなければならない特殊事項があります：
AK_MusicSyncBeat = 0x0100, // Enable notifications on Music Beat. AK_MusicSyncBar = 0x0200, // Enable notifications on Music Bar. AK_MusicSyncEntry = 0x0400, // Enable notifications on Music Entry Point. AK_MusicSyncExit = 0x0800, // Enable notifications on Music Exit Point. AK_MusicSyncGrid = 0x1000, // Enable notifications on Music Grid. AK_MusicSyncUserCue = 0x2000, // Enable notifications on Music User Cue. AK_MusicSyncPoint = 0x4000, // Enable notifications on Music synchronisation point. AK_MusicSyncAll = 0xff00, // Use this flag if you want to receive all notifications concerning AK_MusicSync registration.
イベント終了時に通知を受信したい場合、フラグはビット単位の排他であるため、AK_EndOfEvent | AK_MusicSyncBeat を使用する必要があります。
AkPlayingID AK::SoundEngine::PostEvent( AkUniqueID in_eventID, // Unique ID of the event AkGameObjectID in_gameObjectID, // Associated game object ID AkUInt32 in_uFlags = 0, // Bitmask: see AkCallbackType AkCallbackFunc in_pfnCallback = NULL, // Callback function void * in_pCookie = NULL // Callback cookie that will be sent to the callback function // along with additional information );
static void MusicCallback( AkCallbackType in_eType, // Type of callback reason, in this case it could be AK_MusicSyncBeat AkCallbackInfo* in_pCallbackInfo // Pointer to callback information structure, in this case // AkMusicSyncCallbackInfo*. )
AK_MusicSyncBar 通知を処理したいだけであれば、他のイベントタイプを受信した場合には返す必要があります。in_pCallbackInfo を型キャストすることができます。ミュージック通知の場合は、AkMusicSyncCallbackInfo です。struct AkMusicSyncCallbackInfo : public AkCallbackInfo { AkPlayingID playingID; AkCallbackType musicSyncType; AkReal32 fBeatDuration; AkReal32 fBarDuration; AkReal32 fGridDuration; AkReal32 fGridOffset; };
AK_MusicSyncBeat と AK_MusicSyncBar の両方に4/4拍子で登録すると、バーごとに4つのビート通知＋バー自体でバー通知1つを受け取ることになります。"0" 拍子も1ビートおよび1バーと数えられ、ほとんどのケースで、AK_MusicSyncEntry も同様です。よって、バー、ビート、エントリーポイントを登録した場合、音楽が開始すると3つのコールバックを連続して受け取ることになります。AK_MusicSyncExit 通知は、再生中セグメントの終端に到達した場合にのみ送信されます。再生中のセグメントが終了する前にに別のセグメントに音楽がスイッチする場合、現行の AK_MusicSyncExit 通知は送信されません。上記に示したコールバック関数で、ミュージック プレイリストの次のアイテムの選択を手作業での管理にも使用できます。これは次のフラグを追加することで実行できます。
AK_MusicPlaylistSelect = 0x0040 // Callback triggered when music playlist container must select the next item to play.
この種類のイベントを受け取った場合、コールバック関数はパラメーター in_pCallbackInfo を、 AkMusicPlaylistCallbackInfo型へ型変換する必要があります。
struct AkMusicPlaylistCallbackInfo : public AkEventCallbackInfo { AkPlayingID playlistID; AkUInt32 uNumPlaylistItems; AkUInt32 uPlaylistSelection; AkUInt32 uPlaylistItemDone; };
アクティブなプレイリストノードは、数値 playlistID が示します。サウンドエンジンは、コールバック関数の呼び出しの前に、プレイリストノードの次のアイテムを選択します。このセレクションは、 uPlaylistSelection ならびに uPlaylistItemDone の数値に含まれています。もし、uPlaylistItemDone が 0 にセットさている場合には、 uPlaylistSelection がプレイリストノードで再生する次のアイテムを決定します。もし、 uPlaylistItemDone に 0 が設定されていない場合には、現在のプレイリストノードが終了します (親ノードがアクティブノードになりま)。uPlaylistSelection ならびに uPlaylistItemDone の両方の数値を、コールバック関数によって変更することができます。
通知は、バッファがハードウェアに引き継がれた時に送信されます。つまり、通知の送信時とその再生時の間に一定の遅延が起こります。この遅延により、アプリケーションは、マーカーに関する情報を収集し、マーカーと関連付けられたサウンドが実際に再生される前にこれを処理する余裕を得ることができます。
この遅延はプラットフォーム依存であることにご注意ください。
コールバックは、サウンドエンジンのメインスレッドから実行されます。つまり、アプリケーションは、必要な情報を通知から収集し、即時に返さなければなりません。なんらかの処理が必要な場合は、通知から関連情報がコピーされた後に別のスレッドで実行されなければなりません。
アプリケーションがスレッドを長く保持しすぎると、サウンドエンジンがアンダーラン状態に陥り、出力が再生を停止する可能性があります。