キューシートのロード処理の詳細
AtomComponent を使って音声再生を行う場合、 Atom Cue アセットと Atom Cue Sheet アセットのロードが必要です。
Atom Cue アセットと Atom Cue Sheet アセットは、以下のクラスで実装されています。
  • SoundAtomCue クラス : Atom Cue アセット
  • SoundAtomCueSheet クラス : Atom Cue Sheet アセット

キューシートを参照するクラス

AtomComponent 、 SoundAtomCue 、 SoundAtomCueSheet は CRIWARE UE4 Plugin の主要なサウンド関連クラスです。 これらの参照関係を下図に示します。
criware_ue4_035_primary_atom_object_relation.jpg
上図を元に、 主要なサウンド関連オブジェクトの参照関係を以下のように説明します。
  • AtomComponent オブジェクトは SoundAtomCue オブジェクトを参照します
  • SoundAtomCue オブジェクトは SoundAtomCueSheet オブジェクトを参照します
  • SoundAtomCueSheet オブジェクトは Raw ACB Data を内包します。Raw ACB Data は ACB ファイルの内容のコピーです
  • CRI Core Runtime は C 言語で実装されたネイティブライブラリです。 正しくは CRI Atom ライブラリという名称です
  • CRI Core Runtime は Raw ACB Data をロードすることで、 ACB 内のキューを再生可能になります
下記の2つの処理は明確に異なる点に注意してください。
  • Atom Cue Sheet アセットのロード
  • Atom Cue Sheet アセット内の Raw ACB Data のロード

Atom Cue Sheet アセットのロード

UE4によるアセットの自動ロード

多くの場合、Atom Cue Sheet アセットは .uasset ファイルの形でアプリケーションにパッケージングされます。
Atom Cue Sheet アセットをハード参照するオブジェクトがレベル上に存在する場合、 この .uasset ファイルは UE4 によって自動的にストレージから読み出され、メモリへロードされます。
ハード参照やソフト参照といったアセットの参照に関する用語については、 Epic Games 社の Unreal Engine 4 ドキュメント を参照してください。

アプリケーションによるアセットの手動ロード

UE4 によるアセットのロードが既に完了している場合、下記の関数のいずれかを呼び出すことで、有効な USoundAtomCueSheet オブジェクトへのポインタを取得することができます。
  • USoundAtomCueSheet* USoundAtomCueSheet::LoadAcb(FName AcbName, bool bAddToLevel)
  • USoundAtomCueSheet* USoundAtomCueSheet::LoadAtomCueSheet(USoundAtomCueSheet* CueSheet, bool bAddToLevel)
UE4 によるアセットのロードが行われていない場合、 USoundAtomCueSheet::LoadAcb() 関数は指定した Atom Cue Sheet アセットファイル (.uasset) のパッケージを検索して、 メモリに読み出します。これはファイル I/O と大きなメモリコピーを伴う可能性があるため、パフォーマンスに悪影響が出る恐れがあります。
このケースを回避または検知するには、下記の方法があります。
  • 必要な Atom Cue Sheet アセットへのハード参照を作成する
  • 必要な Atom Cue Sheet アセットへのソフト参照を作成する
  • Atom Cue Sheetアセットの非同期ロード の機能を使用する
  • ログカテゴリ名 "LogCriWareRuntime" に関してのログ出力を Verbose レベルに設定する (.uasset からのロードを行う際にメッセージを出力します)

アセット内の Raw ACB Data のロード

アセットをロードするだけではキュー再生はできません。上図に示したように、 CRI Core Runtime が Raw ACB Data をロードする必要があります。
本節では Raw ACB Data のロードに関する仕様を説明します。
CRIWARE UE4 Plugin v1.27.11.00 より、CRI Core Runtime による Raw ACB Data のロード処理は、非同期に行われるよう変更されました。

暗黙的なロード

AtomComponent はキューの再生を指示されると、必要な Raw ACB Data を自動的にロードします。本節ではこれを "暗黙的なロード" と呼びます。
暗黙的なロードが実行される場合の AtomComponent は下記のように動作します。
  1. CRI Core Runtime が Raw ACB Data をロード済みかどうか確認されます
  2. ロード済みではない場合、 AtomComponent の内部で Raw ACB Data のロードが要求されます (暗黙的なロードの実行)
  3. 暗黙的なロードの実行中、 AtomComponent のステータスは EAtomComponentStatus::Prep を示します
  4. ロードが完了すると AtomComponent は CRI Core Runtime にキュー再生を要求します
  5. 実際にキューが再生されるまでにはタイムラグが存在します
  6. CRI Core Runtime によって再生が開始されると AtomComponent のステータスは EAtomComponentStatus::Playing へ遷移します

明示的なロード

下記の関数のいずれかを呼び出すことで、有効な USoundAtomCueSheet オブジェクトへのポインタを取得することができます。
  • USoundAtomCueSheet* USoundAtomCueSheet::LoadAcb(FName AcbName, bool bAddToLevel)
  • USoundAtomCueSheet* USoundAtomCueSheet::LoadAtomCueSheet(USoundAtomCueSheet* CueSheet, bool bAddToLevel)
上記関数呼び出し直後、返り値の USoundAtomCueSheet ポインタはまだ Raw ACB Data のロードを完了していません。
ロード完了を検知する手段として、 USoundAtomCueSheet は FOnLoadCompleted デリゲートを提供しています。
また、 USoundAtomCueSheet::IsLoaded() 関数を呼び出すことで確認することも可能です。