|
Wwise SDK 2022.1.18
|
このチュートリアルに使うのは、Audiokinetic LauncherでSDKやVisual StudioプラットフォームをインストールしたあとにSDKサンプルに入っている、Integration Demoプロジェクトが適切です。なお、ご自分のプロジェクトや、WwiseサンプルにあるWwise Audio LabやWwise Adventure Gameなど、ほかのプロジェクトを使うことも可能です。
WAQLは様々な場所で使えますが、このチュートリアルではList Viewを使うことを推奨します。
 | Tip: A brief video tutorial on WAQL usage in the List View is available. See Finding Objects using WAQL. |
単純なフィルタのクエリ
List Viewのサーチフィールドに、以下を入力します:
$ where volume < 0
最初の文字の $ は、WwiseにWAQLクエリを書いていることを伝えるものです。これで、Wwiseが標準のテキストサーチとWAQLクエリを区別できます。そして $ のあとにくるものが全て、クエリ自体を定義するものとなります。
この例では、クエリを where キーワードで始めています。最初に where キーワードがあると、自動的にWAQLはプロジェクトの全オブジェクトを対象に、 where のあとに定義する条件文を使いオブジェクトにフィルタを適用します。キーワード where は、一致するオブジェクトだけをアウトプットするフィルタです。
まとめると:
$ where CONDITION
CONDITIONは、trueまたはfalseを返すブール式です。前の例では、ボリュームを数値と比較しています。ボリュームがゼロ未満であれば、クエリはtrueを返します。この条件で、プロジェクトの全オブジェクトを検証します。クエリの結果は、ボリュームがゼロ未満の全てのオブジェクトとなります。
追加の演習問題:
- ほかの演算子を試してください: <=, >, >=, =
- volume の代わりに pitch や lowpass を試してください
- and や or などを、括弧付きや括弧無しで使い、さらに複雑な式を定義してください
| Tip: WAQLのプロパティ名について知るには、 Wwiseオブジェクトリファレンス を参照してください。 |
文字列の条件
ここまで、数値的な条件しか使っていません。それでは、文字列の条件を使ってみます:
$ where name = "hello"
文字列の条件では、2つの文字列の内容を比較します。イコール演算子は、大文字小文字を区別しないで比較します。この条件では、テキストが同じであれば、大文字小文字に関係なくtrueと評価されます。特に具体的なものを探しているときなどに、便利です。
また、以下のように、文字列の一部を比較することもできます:
$ where name : "hello"
このクエリの比較演算子は、イコールでなくコロンです。コロンは、単語検索の演算子を定義します。サーチ対象の要素のなかに、特別な単語が見つかれば、trueを返します。この例では、nameに"hello"が含まれると、trueを返します。
追加の演習問題:
- サーチするテキストを、変えてください
- サーチのテキストに、"*lo"のように、ワイルドカードのアスタリスクを使ってください
- name の代わりに notes や outputbus を試してください
オブジェクトプロパティのチェイン
Wwiseオブジェクトには、以下の2種類のプロパティがあります:
- 値を返すプロパティ:
- Volume、Pitch、Lowpassなど: Wwiseではスライダーと紐づいていることが多く、数値を格納します。これらはオブジェクトタイプによって異なります。例えば、 Sound と Random Containers では、設定できるパラメータセットが違います。
- Name、notes、id、path: Wwiseオブジェクトシステムの主要要素であり、文字列値を格納することが多いです。どのWwiseオブジェクトにもあります。
別のWwiseオブジェクトを返すプロパティ（リファレンスとも呼ばれる）:
- OutputBus、Target、UserAuxSend0、Effect0: 別のオブジェクトにポイントし、オブジェクトタイプによって異なります。例えば Events と Sounds のプロパティは、同じではありません。
- Parent: 親オブジェクトへのポインター。
dot 演算子を使ってプロパティを組み合わせることができます。例：
$ where parent.name = "Music"
または
$ where parent.volume < 0
以下のように、複数のプロパティを組み合わせることもできます:
$ where outputbus.parent.name = "Master Audio Bus"
 | 注釈: プロパティを組み合わせるときは、値を返すプロパティが必ず最後のドットのあとにくるようにします。別のオブジェクトを返すプロパティは、シーケンス中のどこにでも入れられます。 |
追加の演習問題:
- outputbusのボリュームにフィルタをかけてください
- Effect0のpluginnameにフィルタをかけてください
違うソースを使う
ここまでは、フィルタの対象がプロジェクト全体のオブジェクトでした。一方、サーチの対象オブジェクトの範囲を狭めることもできます。
以下を入力します:
$ from type sound
このクエリで、プロジェクトの全てのサウンドオブジェクトがリストに表示されます。この from キーワードが、クエリを開始するソースを定義してくれます。サーチの範囲を絞るための非常に効率的な方法です。WAQLは、イテレーションを、指定したソースに限定することができます。
また、以下のように、複数のオブジェクトタイプを指定することもできます:
$ from type randomsequencecontainer, switchcontainer, blendcontainer
先ほどのクエリは、以下のように、 where キーワードを使ったフィルタサーチで書くこともできます:
$ where type = "randomsequencecontainer" or type = "switchcontainer" or type = "blendcontainer"
ただしフィルタ処理がイベント、バス、サウンドなど、全てのプロジェクトオブジェクトに対して実行されます。このため、実行時間が長くなります。
追加の演習問題:
- ほかのオブジェクトタイプでも試してください。 Wwiseオブジェクトリファレンス を参照してください。
FromとWhereを組み合わせる
以下のクエリを入力します:
$ from type sound where volume < 0
プロジェクトの全てのサウンドオブジェクトを対象にフィルタにかけ、そのうち、ボリュームがゼロ未満のサウンドのみを残します。
from キーワードは必ずWAQLクエリの最初にきますが、 where キーワードは from のあとに加えることができます。
追加の演習問題:
- from のあとの部分に、ほかのオブジェクトタイプを入れてください
- where のあとの部分に、ほかの条件を入れてください
- 複数の where 文をチェイン（chain）でつなげてください
From特定オブジェクト
WAQLでは、クエリソースをさらに絞ることができます。
List Viewで、以下を入力します:
$ from object "\Actor-Mixer Hierarchy"
このクエリは、オブジェクトパスを使い、1つのオブジェクトを返します。
さらにコンパクトにするために、WAQLでは以下のように'from object'の部分を省略できます:
$ "\Actor-Mixer Hierarchy"
これで、指定したオブジェクトが返されます。
複数のオブジェクトを並べることもできます:
$ "\Master-Mixer Hierarchy", "\Actor-Mixer Hierarchy"
追加の演習問題:
- SHIFTキーを押しながら、Project Explorerで1つのオブジェクトを右クリックします。ショートカットメニューで Copy Path(s) to clipboard を選択します。それを使いWAQLクエリを作成してください。
- SHIFTキーを押しながら、Project Explorerで複数のオブジェクトを右クリックします。ショートカットメニューで Copy WAQL query to clipboard を選択します。このクエリをList Viewに貼り付けます。
- SHIFTキーを押しながら、Project Explorerで1つのオブジェクトを右クリックします。ショートカットメニューで Copy GUID(s) to clipboard を選択します。guidをList Viewに貼り付け、ダブルクォーテーションで囲みます: $ "{1514A4D8-1DA6-412A-A17E-75CA0C2149F3}" 。
- バスやイベントには、タイプと名前を使います: $ "Bus:Master Audio Bus"。
オブジェクトを選択する
異なるソースのWAQLクエリをつくれるようになったので、さっそくオブジェクトを選択してみます。オブジェクトをselect（選択）すると、最初の一連のオブジェクトから、別のオブジェクトを取得できます。
List Viewで以下のクエリを入力します:
$ "\Actor-Mixer Hierarchy\Default Work Unit" select children
これは、Default Work Unitの中から、直下のchildren（子）を全て返します。
それでは、もっと別のオブジェクトも取得してみます:
$ "\Actor-Mixer Hierarchy\Default Work Unit" select descendants
こうすると、Default Work Unitの全てのdescendants（子孫）を取得します。子孫に、全ての子が再帰的に含まれます。
追加の演習問題:
- 親を選択してください
- 複数の要素をコンマで区切り、選択してください
- select 文を、最初の方のセクションの where クエリに追加してください
- where 文を、selectクエリの最後に追加してください
- outputbusを選択してください
イベントで試す
WAQLの基本概念が分かったところで、具体的な例を構築してみます。次の例では、あるイベントがリファレンスする全てのサウンドを列挙します。
最初に、プロジェクトの全てのEventを列挙します:
$ from type event
次にEventオブジェクトから、Eventアクション（直下のchildren）を取得します:
$ from type event select children
次に、各アクションのtarget（リファレンス名target）を取得します:
$ from type event select children select target
次に、そのtarget自体（キーワード this を使用）と、そのdescendantsを取得します:
$ from type event select children select target select this, descendants
最後に、soundオブジェクトだけを残すために、typeのフィルタを適用します:
$ from type event select children select target select this, descendants where type = "sound"
追加の演習問題:
- プロジェクトの全てのイベントから開始するのではなく、特定のイベントから開始してください。
- Playアクションだけが残るフィルタを適用してください（Stopなどほかのタイプを除外）。アクションのプロパティについては、 Action を参照してください。
逆向きにイベントを試す
それでは、soundオブジェクトから開始して、それを再生するイベントを全て並べてみます:
$ from type sound
次に、それらのsound自体と、そのancestors（祖先）を取得します。ここでancestorsも対象とするのは、イベントがそれらも参照できるからです。例えば、親のランダムコンテナが、イベントのターゲットとなることがあります。
$ from type sound select this, ancestors
次に、これまで取得されたものをreference to（参照先）とする、全てのオブジェクトを取得します:
$ from type sound select this, ancestors select referencesTo
これは基本的にfind all references（Referenceビューに似ている）を行っているのですが、これを参照するものは、SoundBankやSoundCasterセッションなど、ほかのオブジェクトもあるかもしれないので、イベントactionだけが残るようなフィルタが必要です:
$ from type sound select this, ancestors select referencesTo where type = "action"
最後に、個々のactionの親、つまりイベントを、取得します:
$ from type sound select this, ancestors select referencesTo where type = "action" select parent
追加の演習問題:
- プロジェクトの全てのサウンドから開始するのではなく、特定のサウンドから開始してください。
- プロジェクトの全てのサウンドから開始するのではなく、特定のWork Unitの下の、全てのオブジェクトから開始してください。
- Playアクションだけを残し、Stopなどほかのアクションタイプを除くフィルタを適用してください。
まとめ
このチュートリアルの内容をまとめます。
WAQLクエリの仕組みについて:
- クエリは、Wwiseオブジェクトのシーケンスを返します。
- クエリを from 文、 where 文、 select 文で定義されたセクションに分解することができます。
- クエリの各セクションが、次のセクションの元となります。
- クエリには、必ず開始点となるソースがあります。クエリのソースは、 from 文で定義します。
- from 文を省略すると、プロジェクトの全オブジェクトが、ソースとなります。
- where 文で元となったシーケンス（つまり前セクション）のオブジェクトにフィルタが適用されるので、その条件と一致するものだけが残ります。
- select 文で、元となったシーケンス（つまり前セクション）から、新しいオブジェクトを取得できます。
- where 文と select 文は、どのシーケンスにも追加できます。
Wwiseオブジェクトについて:
- Wwiseオブジェクトにはプロパティがあり、それは where 文や select 文で使えます。
- プロパティとは、数値、ブーリアン、文字列、またはプロジェクトのほかのオブジェクトへのリファレンスです。
- 一部のプロパティは、どのオブジェクトにもあります（つまり、コアプロパティ）。
- 1つまたは複数のオブジェクトタイプに固有のプロパティも、あります。
- プロパティをdot演算子で組み合わせることができます。
次は何？WAQLでできることは、これ以外にも多数あります:
- さらにWAQLについて知るには、 用語集 and 重要なキーワードと概念 を参照してください。
- WAQLでできることを全て知るには、 Wwise Authoring Query Language (WAQL) リファレンス を参照してください。
- Wwiseオブジェクトと、そのプロパティについて知るには、 Wwiseオブジェクトリファレンス を参照してください。
- WAAPIでWAQLを使う方法については、 ak.wwise.core.object.get を参照してください。