イントロダクション
ゲームのインタラクティブミュージックを作成する時、音楽のビートに関する情報が必要です。サウンドエンジンから、ミュージック通知を使用してこの情報を要求することができます。ビートは、再生中の主要な音楽セグメントによって決定されます。セグメントには様々な拍子があるので、再生中の音楽によってビートが変化します。再生中の音楽がない場合は、通知は行われません。
ミュージックコールバックには、以下の2種類がある。
- ミュージック通知: 現在の音楽生成プロパティを呼び出された側に通知する。
- ミュージック プレイリスト セレクション: ミュージック プレイリスト セレクションの次のアイテムを、呼び出された側に強制することができます。
ミュージック通知の使い方
音楽に関するマーカー通知を受信したい場合は、アプリケーションを設計する時に注意しなければならない特殊事項があります：
- フォローしたいビートの音楽を含む再生イベントをポストする時、次のフラグを1つ以上追加することができます：
イベント終了時に通知を受信したい場合、フラグはビット単位の排他であるため、AK_EndOfEvent | AK_MusicSyncBeat を使用する必要があります。
- コールバック関数は、次の形式でなければなりません：
static void MusicCallback(
)
- コールバック関数が呼び出された時、まずどのタイプの通知が渡されたのか確認する必要があります。例えば、
AK_MusicSyncBar 通知を処理したいだけであれば、他のイベントタイプを受信した場合には返す必要があります。
- 通知の種類に基づいて、適切な情報構造型に
in_pCallbackInfo を型キャストすることができます。ミュージック通知の場合は、AkMusicSyncCallbackInfo です。
- 覚え書き
- 複数のミュージック通知を要求すると、これらは追加的に送信されます。つまり、
AK_MusicSyncBeat と AK_MusicSyncBar の両方に4/4拍子で登録すると、バーごとに4つのビート通知＋バー自体でバー通知1つを受け取ることになります。"0" 拍子も1ビートおよび1バーと数えられ、ほとんどのケースで、AK_MusicSyncEntry も同様です。よって、バー、ビート、エントリーポイントを登録した場合、音楽が開始すると3つのコールバックを連続して受け取ることになります。
-
テンポは次の式を用いて計算することができます：Tempo (in BPM) = 60.0 / fBeatDuration
-
拍子の上限値は、次の式を用いて計算できます：Upper value = fBarDuration / fBeatDuration。 これにより、1つのバー内にビートがいくつあるかを知ることができます。
-
AK_MusicSyncExit 通知は、再生中セグメントの終端に到達した場合にのみ送信されます。再生中のセグメントが終了する前にに別のセグメントに音楽がスイッチする場合、現行の AK_MusicSyncExit 通知は送信されません。
- 参照
- クイックスタートサンプル統合 - Event（イベント）
ミュージックコールバックの使い方
上記に示したコールバック関数で、ミュージック プレイリストの次のアイテムの選択を手作業での管理にも使用できます。これは次のフラグを追加することで実行できます。
この種類のイベントを受け取った場合、コールバック関数はパラメーター in_pCallbackInfo を、 AkMusicPlaylistCallbackInfo型へ型変換する必要があります。
アクティブなプレイリストノードは、数値 playlistID が示します。サウンドエンジンは、コールバック関数の呼び出しの前に、プレイリストノードの次のアイテムを選択します。このセレクションは、 uPlaylistSelection ならびに uPlaylistItemDone の数値に含まれています。もし、uPlaylistItemDone が 0 にセットさている場合には、 uPlaylistSelection がプレイリストノードで再生する次のアイテムを決定します。もし、 uPlaylistItemDone に 0 が設定されていない場合には、現在のプレイリストノードが終了します (親ノードがアクティブノードになりま)。uPlaylistSelection ならびに uPlaylistItemDone の両方の数値を、コールバック関数によって変更することができます。
通知の遅延
通知は、バッファがハードウェアに引き継がれた時に送信されます。つまり、通知の送信時とその再生時の間に一定の遅延が起こります。この遅延により、アプリケーションは、マーカーに関する情報を収集し、マーカーと関連付けられたサウンドが実際に再生される前にこれを処理する余裕を得ることができます。
この遅延はプラットフォーム依存であることにご注意ください。
コールバックスレッド
コールバックは、サウンドエンジンのメインスレッドから実行されます。つまり、アプリケーションは、必要な情報を通知から収集し、即時に返さなければなりません。なんらかの処理が必要な場合は、通知から関連情報がコピーされた後に別のスレッドで実行されなければなりません。
アプリケーションがスレッドを長く保持しすぎると、サウンドエンジンがアンダーラン状態に陥り、出力が再生を停止する可能性があります。
- 参照
- 統合の詳細 - Event（イベント）
@ AK_MusicSyncEntry
Enable notifications on Music Entry Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
@ AK_MusicSyncBar
Enable notifications on Music Bar. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
AkUInt32 uPlaylistSelection
Selection: set by sound engine, modified by callback function (if not in range 0 <= uPlaylistSelectio...
AkUInt64 AkGameObjectID
Game object ID
@ AK_MusicSyncAll
Use this flag if you want to receive all notifications concerning AK_MusicSync registration.
AkCallbackType
Type of callback. Used as a bitfield in methods AK::SoundEngine::PostEvent() and AK::SoundEngine::Dyn...
float AkReal32
32-bit floating point
AkCallbackType musicSyncType
Would be either AK_MusicSyncEntry, AK_MusicSyncBeat, AK_MusicSyncBar, AK_MusicSyncExit,...
AkUInt32 AkUniqueID
Unique 32-bit ID
AkPlayingID playingID
Playing ID of Event, returned by PostEvent()
@ AK_MusicSyncGrid
Enable notifications on Music Grid. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
void(* AkCallbackFunc)(AkCallbackType in_eType, AkCallbackInfo *in_pCallbackInfo)
AkUInt32 uPlaylistItemDone
Playlist node done: set by sound engine, modified by callback function (if set to anything but 0 then...
AkUniqueID playlistID
ID of playlist node
@ AK_MusicPlaylistSelect
Callback triggered when music playlist container must select the next item to play....
@ AK_MusicSyncExit
Enable notifications on Music Exit Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
@ AK_MusicSyncBeat
Enable notifications on Music Beat. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
uint32_t AkUInt32
Unsigned 32-bit integer
@ AK_MusicSyncPoint
Enable notifications on Music switch transition synchronization point. AkCallbackInfo can be cast to ...
AkUInt32 uNumPlaylistItems
Number of items in playlist node (may be segments or other playlists)
AKSOUNDENGINE_API AkPlayingID PostEvent(AkUniqueID in_eventID, AkGameObjectID in_gameObjectID, AkUInt32 in_uFlags=0, AkCallbackFunc in_pfnCallback=NULL, void *in_pCookie=NULL, AkUInt32 in_cExternals=0, AkExternalSourceInfo *in_pExternalSources=NULL, AkPlayingID in_PlayingID=AK_INVALID_PLAYING_ID)
AkUInt32 AkPlayingID
A unique identifier generated whenever a PostEvent is called (or when a Dynamic Sequence is created)....
@ AK_MusicSyncUserCue
Enable notifications on Music Custom Cue. AkCallbackInfo can be cast to AkMusicSyncCallbackInfo.
あなたのプロジェクトについて教えてください。ご不明な点はありませんか。
プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。
Wwiseからはじめよう