|
Wwise SDK 2023.1.8
|
Wwise のオープンアーキテクチャは、次の3種類のプラグインをサポートしています：サウンドを生成するソースプラグイン、サウンドを向上させるエフェクトプラグイン、Wwise 内でのソース管理ソフトウェア使用を可能にするソース管理プラグイン。最初の2種のプラグインは、デフォルトプロパティ値を含めた一部のプラグイン設定を、コードの再コンパイルなしですばやく変更することができる XML プラグイン記述ファイルを使用します。Wwise プラグイン DLL は、複数のプラグインを含めることが可能ですが、各プラグインが関連 XML ファイルで記述されている必要があります。各 Wwise プラグインDLL の XML 記述ファイルは、XML ファイルの拡張子以外は DLL と同じ名前である必要があります。例えば、DLLが "MyPlugin.dll" という名前である場合、プラグイン記述ファイルは "MyPlugin.xml" という名前でなければなりません。
Wwiseがオープンアーキテクチャなので、Wwiseオブジェクトのカスタムプロパティを設定することもできます。プラグインの定義とほぼ同様に、WwiseのプロパティもXML記述を使って制御されています。詳細は、カスタムプロパティの定義 を参照してください。
Properties 要素
Properties セクションは、ご使用プラグインのプロパティとリファレンスを定義します。Property と Reference は、XMLで指定された順序でユーザーインターフェイスに表示されます。.
- これらのプロパティは、プラグインのユーザーインターフェースでユーザーが操作できる（スライダやチェックボックスなどの）コントロールおよびサウンドエンジンプラグインコードが計算に使用できる値に対応しています。
- リファレンスはWwiseオブジェクトへのリファレンスを含むフィールドに対応しています。例えば、リファレンスは、プロジェクトで定義されたGame Parameterオブジェクトを特定することができます。
Property は通常以下のように定義されます：
Referenceは通常以下のように定義されます：
Property と Reference の要素にはいくつかの属性を含めることができます。：
-
Name [Property, Reference](タイプ：文字列、必須)：これはWwiseプラグインでプロパティを識別するために使用される文字列IDです。以下のような場所で使用されます：- コントロールへのプロパティのバインド：コントロールをプロパティにバインドするために、プラグインのダイアログリソース (Prop=<Property Name>) で指定する必要のある名前です。
-
永続性：プロパティに関連するデータを永続化するために Wwise Project ファイルの
Property要素に表示される名前です。
注意: 既存プロパティの名前を変更しないでください。プラグインを使用しているプロジェクトが、ユーザーがこのプロパティに対して設定した値、ランダマイザや RTPC を失うことになります。 -
以下にある in_szPropertyName パラメータ:
-
AK::Wwise::Plugin::NotificationsPropertySet::NotifyPropertyChanged() -
AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp() -
AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues()
-
注釈: Property Nameは、UI に表示される名前ではありませんが、ユーザーが Project ファイル内で目にする可能性があるので有意味なものにする必要があります。UI に表示される名前は、DisplayName 属性によって指定されます。注釈: カスタムプロパティを設定する場合は、 Name属性の最初に"Custom:"をプレフィックスとして付ける必要があります。詳細は、カスタムプロパティの定義 を参照してください。 -
DisplayName [Property, Reference]（タイプ： 文字列、 デフォルト： 空）：Wwise内の色々な場所で表示される、Property の表示名を定義します。この属性は、AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp関数に優先します。 -
DisplayGroup [Property, Reference]（タイプ：文字列、 デフォルト：空）：ツリーでプロパティやレファレンスを整理するために使用される、スラッシュで区切られたパスを定義します。Ex: "Audio/HDR" -
IsVisible [Property, Reference]（タイプ：Bool型、 デフォルト：true、オプション）：デフォルト値は、true。これが存在しない場合、プロパティが一般的なエディタに表示されます。ユーザーにとって、プロパティとその値が重要でない場合や、ユーザーによる一般的なエディタ（例えば List View など）での表示や変更を避けたい場合には、IsVisibleをfalseに設定してください。 -
Type [Property]（必須）：プロパティタイプです。Possible values are:-
bool:Boolean -
int16:16-bit integer -
Uint16:16-bit unsigned integer -
int32:32-bit integer -
Uint32:32-bit unsigned integer -
int64:64-bit integer -
Uint64:64-bit unsigned integer -
Real32:Single-precision float (32-bit) -
Real64:Double-precision float (64-bit) -
string:UTF-8, null-terminated character string
Plug-ins write properties to SoundBanks using the
AK::Wwise::Plugin::DataWriterservice, which supports writing any of the types listed above. Strings are serialized as null-terminated UTF-8 c-strings. Bool values are serialized as 1-byte values, where 1 stands for true and 0 for false.
In the case of custom properties added to a Wwise project, the values supported in SoundBanks are restricted to:-
int32:32-bit integer -
Real32:Single-precision float (32-bit)
The bool type can still be used as custom properties, however values are interpreted as int32 where 1 stands for true and 0 for false. However, custom properties typed as Strings are not exported to SoundBanks because they cannot be represented numerically.
-
-
SupportLink [Property, Reference]( タイプ: Bool型、 デフォルト: false、オプション):Property、またはReferenceが、Link/Unlink機能をサポートするかどうかを定義します。 -
SupportStates [Property](type: boolean, default: true, optional): Defines if thePropertysupports State mapping to control its value. Note that State mapping is only supported if the property also definesSupportRTPCTypeas eitherAdditiveorBoolean. -
SupportRTPCType [Property](type: string, default: undefined, optional): If not specified, the property will not support RTPCs. If specified, possible values are:-
Additive:The value computed from the RTPC curve will be added to the base property value of the object and to other RTPCs on the same property. -
Multiplicative:The value computed from the RTPC curve will be multiplied by the base property value of the object and by other RTPCs on the same property. -
Exclusive:The value computed from the RTPC curve has exclusive control over the property's value, completely overriding the value set in the property's control within the dialog. (That control will be disabled to make it clear to the Wwise user that it does not have any effect on the property.) -
Boolean:Equivalent logical operations are applied to enable or disable boolean properties. This attribute also enables State mapping to affect the property's value when the RTPC type is eitherAdditiveorBoolean.
-
-
ForceRTPCCurveSegmentShape [Property](type: string, default: undefined, optional, used withSupportRTPCType): Restricts the possible segment shapes used in RTPC curves on this property. 指定しない場合、ユーザーは曲線内のセグメントの形状を自由に変更することができます。指定した場合、可能な値は次のとおりです：-
Constant:曲線内のすべてのセグメントは一定補間（隣接する2点間でY値は対の最も左にある値と同じ）を使用。プロパティがブール型または列挙型のような控えめな値を表す場合にこれを使用してください。
-
-
DataMeaning [Property](type: string, default: undefined, オプション): これが定義された場合、プロパティがデシベルなどの特別なタイプのデータを表すことを指定します。可能な値は以下のとおりです：
-
Decibels:このプロパティは、デシベルを表します。RTPC 曲線は、デフォルトではデシベルスケーリングを使用しますが、ユーザーはデシベルとリニアスケーリングの間で変更するオプションを持ちます。デシベルスケーリングは、ポイント間で値が補間される方法に影響を与えます。例えば、0 dB および -96.3 dB のそれぞれにポイントがある場合、この2点間で正確に評価されたリニア曲線セグメントは、リニアスケーリング使用時には -48.15 dB の値、デシベルスケーリング使用時には約 -6 dB ほどの値を生成します（振幅の半分に相当）。
-
Frequency:このプロパティは、Hz 単位の周波数を表します。周波数スケーリングは、ポイント間で値が補間される方法に影響を与えます。例えば、1000 Hzおよび4000 Hz（2オクターブ上）のそれぞれにポイントがある場合、この2点間で正確に評価されたリニア曲線セグメントは、リニアスケーリング使用時には2500 Hzの値、周波数スケーリング使用時には2000 Hz（1オクターブ上）の値を生成します。
-
| 注釈: プラグインによって生成されたサウンドまたはエフェクトが Wwise ユーザーによって設定され、これがゲーム中に変更されないようにするには、RTPC をサポートするよう設定しないでください。 |
DefaultValue 要素は、プロパティのデフォルト値を指定します。このデフォルト値は、新規インスタンス作成時の初期値、ユーザーが CTRL キーを押しながらプロパティのコントロールをクリックした時にプロパティがリセットされる値を示します。この値は、プロパティの（Property 要素の Type 属性で指定されている）タイプおよび範囲（下記）と一致する必要があります。
 | Tip: XMLファイルは、任意のテキストエディタまたはXMLエディタで編集可能です。このファイルは、メイン Wwise インストールフォルダ下の "plugins" フォルダ内にある、プラグインDLLのフォルダと同じフォルダにあります。カスタムプラグインを持っている Wwise ユーザーは、使用プラグインの XMLファイルを編集して、プラグインの再コンパイルなしでプラグインプロパティのデフォルト値を変更可能です。この変更を行うのに、デベロッパの専門知識は必要ありません。 |
AudioEnginePropertyID 要素は、Sound Engine でこのプロパティを識別します。これは、0～32767の範囲の正の整数である必要がありますが、例外としてwcustompropertiesファイルでは、範囲は0～150です。AudioEnginePropertyID 要素で設定した値は、AK::IAkEffectParam::SetParam() 内の AkFXParamID パラメータに対応するため、プロパティIDが AK::IAkEffectParam::SetParam() の実装とプラグイン記述ファイル間で同期していることを確認してください。
UserInterface
UserInterface 要素は、ユーザーインターフェースの動作と外観に関連する属性を定義します。次の属性はすべてオプションであり、UserInterface 要素に設定可能です：
-
DisplayName（タイプ： 文字列、 デフォルト： 空）：（非推奨）Wwise内の色々な場所で表示される、Property の表示名を定義します。この属性を、PropertyまたはReference要素で定義されるDisplayName属性に置換えます。 -
Decimals( タイプ: 整数、 デフォルト: 0)：小数点以下に表示する桁数を定義します。この値は、非負の整数でなければなりません。0に設定されている場合は、小数点以下の数字および小数点は表示されません。 -
Step( タイプ: フロート、 デフォルト: 1)：スライダを移動したときに数値が変化する量を定義します。この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。 -
Fine( タイプ: フロート、 デフォルト: 1)：SHIFT キーを押しながらスライダを移動したときに数値が変化する量を定義します。この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。 -
SliderType( タイプ: 整数、 デフォルト: 0)：スライダ範囲全体に渡る値のマッピングを定義します。- 0: リニア（デフォルト）
- 1: 擬似対数、-96.3dB から 0dB まで
- 2: 擬似対数、-96.3dB から 96.3dB まで
- 4: 擬似対数、20 Hz から 20000 Hz まで
- 5: 擬似対数、20 Hz から 12000 Hz まで
- 6: 擬似対数、-96.3dB から 12dB まで
- 11: 擬似対数、 0.02 Hz から 20000 Hz まで
- 12: 擬似対数、 0.02 Hz から 20 Hz まで
- 15: 擬似対数、 -24dB から 24dB まで
- 16: 擬似対数、-96.3dB から 24dB まで
-
Mid（タイプ：フロート、 デフォルト：0）：ニュートラルとみなされる [min,max] 範囲内の値を定義します。この値は、スライダコントロールの描画に影響を与えます。 -
UIMin（ タイプ： フロート、 デフォルト： 範囲の最小値）：スライダを使用して最初に設定される最小値を定義します。この値が、Min属性で指定された値より大きい場合、ユーザーは、この属性により指定された値より小さい値を入力して、より低い値に強制し、コントロールの範囲を拡大することが可能です。 -
UIMax（ タイプ： フロート、 デフォルト： 範囲の最大値）：スライダを使用して最初に設定される最大値を定義します。この値が、Max属性で指定された値より小さい場合、ユーザーは、この属性により指定された値より大きい値を入力して、より大きな値に強制し、コントロールの範囲を拡大することが可能です。 -
AutoUpdate（ タイプ： ブール、 デフォルト： false）：スライダを移動している間に値が更新されるかどうかを定義します。オーディオパフォーマンスの不具合のため、頻繁に値が更新されるときは、この属性を\ c falseに設定します。 -
LRMixDisplay（ タイプ： ブール、 デフォルト： false）：値が特殊な左右（Left-Right）バランス範囲スタイルで表示されるかどうかを定義します。設定値の範囲は-100 ～ +100とし、LeftとRightのバランスつまりミックスにマッピングされるもので、0がCenterとなります。 -
ControlClass(type: string, default: empty): List ViewやMulti Editorなどのビューで、このプロパティに使用するユーザーインターフェースコントロールを定義します。可能な値は以下のとおりです：- ColorPicker: カラーピッカー。
- ReadOnlyText: このプロパティ値は、ユーザーインターフェースでリードオンリーとします。
-
DropDown( タイプ: ストリング、 デフォルト: 空）：数値の列挙型（例えばEnumerationタイプ int16）と共に使うと、Enumerationの各数値の、メニューの表現方法を指定できます。可能な値は以下のとおりです：- Menu: ドロップダウンの代わりに、該当するenum値のショートカットメニューを表示します。メニューのパスを定義するのは、
Enumeration内の、ValueのDisplayNameです。例えば、DisplayName値が "/Bus Volume/Reset Bus Volume" であれば、メニューに Bus Volume が表示され、そのサブメニューにある Reset Bus Volumeをクリックすると、プロパティ値が14に設定されます。 - CurveIn：該当値が0～8であれば、次のファンクションの曲線（傾きが正）を表示します：Logarithmic (Base 3)、Sine、Logarithmic (Base 1.41)、Inverted S-Curve、Linear、S-Curve、Exponential (Base 1.41)、Reciprocal Sine、Exponential (Base 3)。
- CurveOut:：該当値が0～8であれば、次のファンクションの曲線（傾きが負）を表示します：Logarithmic (Base 3)、Sine、Logarithmic (Base 1.41)、Inverted S-Curve、Linear、S-Curve、Exponential (Base 1.41)、Reciprocal Sine、Exponential (Base 3)。
- Menu: ドロップダウンの代わりに、該当するenum値のショートカットメニューを表示します。メニューのパスを定義するのは、
| Tip: UIMin および UIMax 属性の目的は、プロパティ範囲が非常に大きい場合にコントロールのスライダの初期範囲をより使いやすくすることです。プロパティのいずれかが大きな理論的範囲を持っているが、一般的にユーザーはより制限された範囲を使用する場合には、Min/ real 範囲を、 UIMin/ |
制限
Wwise XML 記述で、 プロパティの制限事項 や、 リファレンスの制限事項 を指定できます。
プロパティの制限事項
プロパティは、必要に応じてデータ値に対する次の2つの制限のいずれかを有することができます。
Range 制限（Restrictions/ValueRestriction/Range セクション）では、数値プロパティの範囲を定義することができます。
Enumeration 制限（Restrictions/ValueRestriction/Enumeration セクション）では、可能な値のリストとそれぞれの値の表示名を定義することができます。
bool プロパティや string プロパティに、範囲は必要ありません。この範囲は、Y軸上のグラフ範囲を定義するために、RTPC Curve Editor など Wwise の様々な場所で使用されます。
このファイルの形式は、メイン Wwise インストールフォルダ下の "/Authoring/Data/Schemas" フォルダにある Plugin.xsd XML スキーマファイルにおいて正式に記述されています。
リファレンスの制限事項
リファレンスには、オプションで、リファレンスされるオブジェクトに対して以下の制限のリストを含めることができます。：
TypeEnumerationRestriction： リファレンスに有効なWwiseオブジェクト型のリストを定義します。
Type Nameは以下をサポートしています。： ActorMixer, RandomSequenceContainer, SwitchContainer, BlendContainer, Sound, Bus, Event, SwitchGroup, Switch, State, GameParameter, MidiParameter, SoundBank, Effect, MusicSegment, MusicTrack, MusicTrackSequence, MusicPlaylistContainer, MusicSwitchContainer, Trigger, Attenuation, DialogueEvent, MotionBus, MotionFX, Conversion, AuxBus, ModulatorLfo, ModulatorEnvelope.
CategoryEnumerationRestriction： リファレンスに有効なWwiseオブジェクトカテゴリのリストを定義します。
Category Nameは以下をサポートしています： Busses、AudioObjects、Events、Switches、States、SoundBanks、GameParameters、Effects、AudioDevices、Presets、SoundcasterSessions、MixingSessions、Queries、InteractiveMusic、Triggers、Attenuations、DynamicDialogue、Conversions、Modulators、ControlSurfaceSessions。
PlayableRestriction： オブジェクトを再生可能にする必要があるかどうかを定義します。
NotNullRestriction： オブジェクトがnullであってはならないかどうかを定義します。
依存関係
プロパティまたはreferencesはゼロまたは多くの依存関係を持つことができます。依存関係がプロパティを結びつけるので、他のプロパティの値に基づいて、あるプロパティを有効または無効にすることができます。
依存関係は現在次のコンテキストのみで使用されることに注意してください:
- Property Editor - All Properties タブ
- エフェクトのDefault User Interface (ただし、ソース以外)
- List View
- Multi Editor
- Query View
- Reference View
AK::Wwise::Plugin::AudioPlugin::GetDialog() でダイアログを提供して独自のユーザーインターフェイスを実装する場合、依存関係はエフェクトエディタで使用されていません。有効または無効のStateは、プラグインのユーザーインターフェイスに実装する必要があります。
次の例では、"GainBand1"から"OnOffBand1"への依存を追加しています。"GainBand1" プロパティは、"OnOffBand1"に "True"をセットすると有効になります。
Condition 要素は、Enumeration 要素または Range 要素のいずれかを含むことができます。PropertyDependency 要素で特定された Action 属性は「Enable (有効)」である必要があります。条件があった場合、プロパティが有効になることを指定します。
Enumeration 条件:
Range 条件:
また、 Context 属性を PropertyDependency で指定することで、 Condition の分析対象となるオブジェクトを変更できます。 Context 属性は、"Parent"または"Self"に設定でき、あえて設定しない場合はデフォルトで"Self"となります。
前記の例で PropertyDependency にコンテキストを追加すると、現在のオブジェクトの親の"OnOffBand1"を"True"に設定した場合は、"GainBand1"プロパティが有効になります。