Wwise SDK 2018.1.11

イントロダクション

ゲームのインタラクティブミュージックを作成する時、音楽のビートに関する情報が必要です。サウンドエンジンから、ミュージック通知を使用してこの情報を要求することができます。ビートは、再生中の主要な音楽セグメントによって決定されます。セグメントには様々な拍子があるので、再生中の音楽によってビートが変化します。再生中の音楽がない場合は、通知は行われません。

ミュージックコールバックには、以下の2種類がある。

ミュージック通知: 現在の音楽生成プロパティを呼び出された側に通知する。
ミュージックプレイリストセレクション: ミュージックプレイリストセレクションの次のアイテムを、呼び出された側に強制することができます。

ミュージック通知の使い方

音楽に関するマーカー通知を受信したい場合は、アプリケーションを設計する時に注意しなければならない特殊事項があります：

フォローしたいビートの音楽を含む再生イベントをポストする時、次のフラグを1つ以上追加することができます：

AK_MusicSyncBeat                = 0x0100,   // Enable notifications on Music Beat.

AK_MusicSyncBar                 = 0x0200,   // Music Bar の通知を有効にします。

AK_MusicSyncEntry               = 0x0400,   // Music Entry Point の通知を有効にします。

AK_MusicSyncExit                = 0x0800,   // Music Exit Point の通知を有効にします。

AK_MusicSyncGrid                = 0x1000,   // Music Grid の通知を有効にします。

AK_MusicSyncUserCue             = 0x2000,   // Music User Cue の通知を有効にします。

AK_MusicSyncPoint               = 0x4000,   // Music 同期ポイントの通知を有効にします。

AK_MusicSyncAll                 = 0xff00,   // AK_MusicSync登録に関するすべての通知を受信する場合は、このフラグを使用します。

イベント終了時に通知を受信したい場合、フラグはビット単位の排他であるため、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 です。

/// Callback information structure corresponding to Ak_MusicSync

struct AkMusicSyncCallbackInfo : public AkCallbackInfo
{
    AkPlayingID playingID;          ///< Playing ID of Event, returned by PostEvent()

    AkCallbackType musicSyncType;   ///< Would be either AK_MusicSyncEntry, AK_MusicSyncBeat, AK_MusicSyncBar, AK_MusicSyncExit, AK_MusicSyncGrid, AK_MusicSyncPoint or AK_MusicSyncUserCue.

    AkReal32 fBeatDuration;         ///< Beat Duration in seconds.

    AkReal32 fBarDuration;          ///< Bar Duration in seconds.

    AkReal32 fGridDuration;         ///< Grid duration in seconds.

    AkReal32 fGridOffset;           ///< Grid offset in seconds.

};

覚え書き: 複数のミュージック通知を要求すると、これらは追加的に送信されます。つまり、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 通知は送信されません。

参照: クイックスタートサンプル統合 - イベント

ミュージックコールバックの使い方

上記に示したコールバック関数で、ミュージックプレイリストの次のアイテムの選択を手作業での管理にも使用できます。これは次のフラグを追加することで実行できます。

AK_MusicPlaylistSelect = 0x0040 // Callback triggered when music playlist container must select the next item to play.

この種類のイベントを受け取った場合、コールバック関数はパラメーター in_pCallbackInfo を、 AkMusicPlaylistCallbackInfo型へ型変換する必要があります。

/// Callback information structure corresponding to Ak_MusicPlaylistSelect

struct AkMusicPlaylistCallbackInfo : public AkEventCallbackInfo
{
    AkPlayingID playlistID;         ///< ID of active node in music playlist container

    AkUInt32 uNumPlaylistItems;     ///< Number of items in playlist node (may be segments or other playlists)

    AkUInt32 uPlaylistSelection;    ///< Selection: set by sound engine, modified by callback function (if not in range 0 <= uPlaylistSelection < uNumPlaylistItems then ignored)

    AkUInt32 uPlaylistItemDone;     ///< Playlist node done: set by sound engine, modified by callback function (if set to anything but 0 then the current playlist item is done, and uPlaylistSelection is ignored)

};

アクティブなプレイリストノードは、数値 playlistID が示します。サウンドエンジンは、コールバック関数の呼び出しの前に、プレイリストノードの次のアイテムを選択します。このセレクションは、 uPlaylistSelection ならびに uPlaylistItemDone の数値に含まれています。もし、uPlaylistItemDone が 0 にセットさている場合には、 uPlaylistSelection がプレイリストノードで再生する次のアイテムを決定します。もし、 uPlaylistItemDone に 0 が設定されていない場合には、現在のプレイリストノードが終了します (親ノードがアクティブノードになりま)。uPlaylistSelection ならびに uPlaylistItemDone の両方の数値を、コールバック関数によって変更することができます。

通知の遅延

通知は、バッファがハードウェアに引き継がれた時に送信されます。つまり、通知の送信時とその再生時の間に一定の遅延が起こります。この遅延により、アプリケーションは、マーカーに関する情報を収集し、マーカーと関連付けられたサウンドが実際に再生される前にこれを処理する余裕を得ることができます。

この遅延はプラットフォーム依存であることにご注意ください。

コールバックスレッド

コールバックは、サウンドエンジンのメインスレッドから実行されます。つまり、アプリケーションは、必要な情報を通知から収集し、即時に返さなければなりません。なんらかの処理が必要な場合は、通知から関連情報がコピーされた後に別のスレッドで実行されなければなりません。

アプリケーションがスレッドを長く保持しすぎると、サウンドエンジンがアンダーラン状態に陥り、出力が再生を停止する可能性があります。

参照: 統合の詳細 - イベント