プラグインプロパティやカスタムプロパティのXML記述

Wwise のオープンアーキテクチャは、次の3種類のプラグインをサポートしています：サウンドを生成するソースプラグイン、サウンドを向上させるエフェクトプラグイン、Wwise 内でのソース管理ソフトウェア使用を可能にするソース管理プラグイン。最初の2種のプラグインは、デフォルトプロパティ値を含めた一部のプラグイン設定を、コードの再コンパイルなしですばやく変更することができる XML プラグイン記述ファイルを使用します。Wwise プラグイン DLL は、複数のプラグインを含めることが可能ですが、各プラグインが関連 XML ファイルで記述されている必要があります。各 Wwise プラグインDLL の XML 記述ファイルは、XML ファイルの拡張子以外は DLL と同じ名前である必要があります。例えば、DLLが "MyPlugin.dll" という名前である場合、プラグイン記述ファイルは "MyPlugin.xml" という名前でなければなりません。

Wwiseがオープンアーキテクチャなので、Wwiseオブジェクトのカスタムプロパティを設定することもできます。プラグインの定義とほぼ同様に、WwiseのプロパティもXML記述を使って制御されています。詳細は、カスタムプロパティの定義を参照してください。

Properties 要素

        <Properties>
            ...
        </Properties>

Properties セクションは、ご使用プラグインのプロパティとリファレンスを定義します。Property と Reference は、XMLで指定された順序でユーザーインターフェイスに表示されます。.

これらのプロパティは、プラグインのユーザーインターフェースでユーザーが操作できる（スライダやチェックボックスなどの）コントロールおよびサウンドエンジンプラグインコードが計算に使用できる値に対応しています。
リファレンスはWwiseオブジェクトへのリファレンスを含むフィールドに対応しています。例えば、リファレンスは、プロジェクトで定義されたGame Parameterオブジェクトを特定することができます。

Property は通常以下のように定義されます：

<Property Name="GainBand1" Type="Real32" SupportRTPCType="Exclusive" DataMeaning="Decibels" DisplayName="Band 1 Gain">
    <UserInterface Step="0.5" Fine="0.1" Decimals="1" />
    <DefaultValue>0</DefaultValue>
    <AudioEnginePropertyID>1</AudioEnginePropertyID>
    <Restrictions>
        <ValueRestriction>
            <Range Type="Real32">
                <Min>-24</Min>
                <Max>24</Max>
            </Range>
        </ValueRestriction>
    </Restrictions>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable">
            <Condition>
                <Enumeration Type="bool">
                    <Value>1</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>

Referenceは通常以下のように定義されます：

<Reference Name="OutputGameParameter" DisplayName="Output Game Parameter">
    <Restrictions>
        <TypeEnumerationRestriction>
            <Type Name="GameParameter" />
        </TypeEnumerationRestriction>
    </Restrictions>
</Reference>

Property と Reference の要素にはいくつかの属性を含めることができます。：

Name [Property, Reference] (タイプ：文字列、必須)：これはWwiseプラグインでプロパティを識別するために使用される文字列IDです。以下のような場所で使用されます：

コントロールへのプロパティのバインド：コントロールをプロパティにバインドするために、プラグインのダイアログリソース (Prop=<Property Name>) で指定する必要のある名前です。

永続性：プロパティに関連するデータを永続化するために Wwise Project ファイルの Property 要素に表示される名前です。

Caution: 既存プロパティの名前を変更しないでください。プラグインを使用しているプロジェクトが、ユーザーがこのプロパティに対して設定した値、ランダマイザや RTPC を失うことになります。

in_szPropertyName parameter in:

Note: Property Name は、UI に表示される名前ではありませんが、ユーザーが Project ファイル内で目にする可能性があるので有意味なものにする必要があります。UI に表示される名前は、DisplayName 属性によって指定されます。

Note: カスタムプロパティを設定する場合は、Name 属性の最初に"Custom:"をプレフィックスとして付ける必要があります。詳細は、カスタムプロパティの定義を参照してください。

DisplayName [Property, Reference] （タイプ：文字列、 デフォルト：空）：Wwise内の色々な場所で表示される、Property の表示名を定義します。この属性は、AK::Wwise::IAudioPlugin::DisplayNameForProp 関数に優先します。
DisplayGroup [Property, Reference]（タイプ：文字列、 デフォルト：空）：ツリーでプロパティやレファレンスを整理するために使用される、スラッシュで区切られたパスを定義します。Ex: "Audio/HDR"
IsVisible [Property, Reference] （タイプ：Bool型、 デフォルト：true、オプション）：デフォルト値は、 true 。これが存在しない場合、プロパティが一般的なエディタに表示されます。ユーザーにとって、プロパティとその値が重要でない場合や、ユーザーによる一般的なエディタ（例えば List View など）での表示や変更を避けたい場合には、IsVisible を false に設定してください。
Type [Property] （必須）：プロパティタイプです。次のような値が可能です：
- bool: Bool型
- int16: 16ビット整数
- int32: 32ビット整数
- Real32: 単精度浮動小数点（32ビット）
- Real64: 倍精度浮動小数点（64ビット）
- string: ワイド文字列
SupportLink [Property, Reference] (タイプ: Bool型、デフォルト: false、オプション): Property、またはReferenceが、Link/Unlink機能をサポートするかどうかを定義します。なお、 SupportLink がサポートされるのはSourceプラグイン用だけで、Effectプラグイン用は対象外です。
SupportRTPCType [Property] (type:string, default:undefined, オプション）：この値がない場合、プロパティは RTPC をサポートしません。ある場合には、これを、Exclusive に設定する必要があります。Exclusive は、RTPC 曲線から計算された値がプロパティ値に対して排他的に制御し、ダイアログ内のプロパティのコントロールに設定されている値を完全にオーバーライドすることを意味します（このコントロールは無効にされ、もはやプロパティに対して影響を持たないことが Wwise ユーザーに知らされます）。
ForceRTPCCurveSegmentShape [Property]（type: string, default: undefined, オプション、SupportRTPCTypeと一緒に使用される）: このプロパティ上の RTPC 曲線で使用可能なセグメントの形状を制限します。指定しない場合、ユーザーは曲線内のセグメントの形状を自由に変更することができます。指定した場合、可能な値は次のとおりです：
- 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オクターブ上）の値を生成します。

Note: プラグインによって生成されたサウンドまたはエフェクトが 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）バランス範囲スタイルで表示されるかどうかを定義します。0 が Center の時、値の範囲は -100 から +100 の間で、Left から Right バランス／ミックスにマッピングされている必要があります。

Tip: UIMin および UIMax 属性の目的は、プロパティ範囲が非常に大きい場合にコントロールのスライダの初期範囲をより使いやすくすることです。プロパティのいずれかが大きな理論的範囲を持っているが、一般的にユーザーはより制限された範囲を使用する場合には、Min/Max 属性を使用して real 範囲を、 UIMin/UIMax 属性を使用して、スライダの初期範囲を設定してください。

制限

Wwise XML 記述で、プロパティの制限事項や、リファレンスの制限事項を指定できます。

プロパティの制限事項

プロパティは、必要に応じてデータ値に対する次の2つの制限のいずれかを有することができます。

Range 制限（Restrictions/ValueRestriction/Range セクション）では、数値プロパティの範囲を定義することができます。

<Restrictions>
    <ValueRestriction>
        <Range Type="Real64">
            <Min>0</Min>
            <Max>100</Max>
        </Range>
    </ValueRestriction>
</Restrictions>

Enumeration 制限（Restrictions/ValueRestriction/Enumeration セクション）では、可能な値のリストとそれぞれの値の表示名を定義することができます。

<Restrictions>
    <ValueRestriction>
        <Enumeration Type="int32">
            <Value DisplayName="Low Pass">0</Value>
            <Value DisplayName="High Pass">1</Value>
            <Value DisplayName="Band Pass">2</Value>
            <Value DisplayName="Notch">3</Value>
            <Value DisplayName="Low Shelf">4</Value>
            <Value DisplayName="High Shelf">5</Value>
            <Value DisplayName="Peaking">6</Value>
        </Enumeration>
    </ValueRestriction>
</Restrictions>

bool プロパティや string プロパティに、範囲は必要ありません。この範囲は、Y軸上のグラフ範囲を定義するために、RTPC Curve Editor など Wwise の様々な場所で使用されます。

このファイルの形式は、メイン Wwise インストールフォルダ下の "/Authoring/Data/Schemas" フォルダにある Plugin.xsd XML スキーマファイルにおいて正式に記述されています。

リファレンスの制限事項

リファレンスには、オプションで、リファレンスされるオブジェクトに対して以下の制限のリストを含めることができます。：

TypeEnumerationRestriction：リファレンスに有効なWwiseオブジェクト型のリストを定義します。

<Restrictions>
    <TypeEnumerationRestriction>
        <Type Name="GameParameter" />
        ...
    </TypeEnumerationRestriction>
</Restrictions>

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オブジェクトカテゴリのリストを定義します。

<Restrictions>
    <CategoryEnumerationRestriction>
        <Category Name="AudioObjects" />
        ...
    </CategoryEnumerationRestriction>
</Restrictions>

Category Nameは以下をサポートしています： Busses、AudioObjects、Events、Switches、States、SoundBanks、GameParameters、Effects、AudioDevices、Presets、SoundcasterSessions、MixingSessions、Queries、InteractiveMusic、Triggers、Attenuations、DynamicDialogue、Conversions、Modulators、ControlSurfaceSessions。

PlayableRestriction：オブジェクトを再生可能にする必要があるかどうかを定義します。

<Restrictions>
    <PlayableRestriction />
</Restrictions>

NotNullRestriction：オブジェクトがnullであってはならないかどうかを定義します。

<Restrictions>
    <NotNullRestriction />
</Restrictions>

依存関係

プロパティまたはreferencesはゼロまたは多くの依存関係を持つことができます。依存関係がプロパティを結びつけるので、他のプロパティの値に基づいて、あるプロパティを有効または無効にすることができます。

依存関係は現在次のコンテキストのみで使用されることに注意してください:

Property Editor - All Properties タブ
エフェクトのDefault User Interface (ただし、ソース以外)
List View
Multi Editor
Query View
Reference View

AK::Wwise::IAudioPlugin::GetDialog() でダイアログを提供して独自のユーザーインターフェイスを実装する場合、依存関係はエフェクトエディタで使用されていません。有効または無効のステートは、プラグインのユーザーインターフェイスに実装する必要があります。

次の例では、"GainBand1"から"OnOffBand1"への依存を追加しています。"GainBand1" プロパティは、"OnOffBand1"に "True"をセットすると有効になります。

<Property Name="GainBand1" ...>
    <...>
    <Dependencies>
        <PropertyDependency Name="OnOffBand1" Action="Enable">
            <Condition>
                <Enumeration Type="bool">
                    <Value>True</Value>
                </Enumeration>
            </Condition>
        </PropertyDependency>
    </Dependencies>
</Property>

Condition 要素は、Enumeration 要素または Range 要素のいずれかを含むことができます。PropertyDependency 要素で特定された Action 属性は「Enable (有効)」である必要があります。条件があった場合、プロパティが有効になることを指定します。

Enumeration 条件:

<Enumeration Type="int32">
    <Value>0</Value>
    <Value>1</Value>
</Enumeration>

Range 条件:

<Range Type="Real32">
    <Min>-24</Min>
    <Max>24</Max>
</Range>

このページはお役に立ちましたか？

サポートは必要ですか？

ご質問や問題、ご不明点はございますか？お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう

Wwise SDK 2017.2.10