Wwise SDK 2025.1.0

此页面将阐述如何访问和修改插件的模型。模型由以下元素两个构成：

Property Set 标准模型：完全由插件的 XML 定义描述，可通过 AK::Wwise::Plugin::RequestPropertySet 提供的组件访问。该模型仅限于特定类型的数据，但允许自动保存、加载、撤消和恢复更改并作为 GUI 控件的模型予以绑定。
自定义数据自定义模型：可选择添加到插件以表示较为复杂的数据，但需以显式方式实现 Property Set 自动完成的操作。该限制同样适用于需要手动更新的 GUI 控件。

Property Set

在获取 AK::Wwise::Plugin::RequestPropertySet 请求实例时，将把 Property Set 实例作为成员变量 m_propertySet 提供给插件。在 AK::Wwise::Plugin::AudioPlugin::GetBankParameters 等函数中，可访问 XML 中定义的属性值以将其写入到 SoundBank 中（详见生成声音包章节）。以显式方式提供常用类型的访问器，但不可使用与 XML 中所指定类型不匹配的访问器类型。

为方便起见，在通过 AK::Wwise::Plugin::AudioPlugin 获取插件类时，将自动请求 AK::Wwise::Plugin::RequestPropertySet 。在其他情况下，比如创建前端时，必须请求该接口。

class MySourcePlugin
:   public AK::Wwise::Plugin::AudioPlugin
{
public:
    bool GetBankParameters(
         const GUID& in_guidPlatform,
         AK::Wwise::Plugin::DataWriter& in_dataWriter) const override
    {
        bool result = true;
        // Access the property set
        int32_t value = m_propertySet.GetInt32(in_guidPlatform, "PropertyKey");
        // Write the value into the sound bank
        result &= in_dataWriter.WriteInt32(value);
        return result;
    }
};

备注: m_propertySet 变量的生命周期与插件实例的生命周期相同。请不要存储此实例并将其用于不同的插件实例。此外，也可在后端类和前端类中请求此服务。

属性值通知

音频设计师可以通过对话框中的控件直接更改属性值，也可以使用撤消/恢复命令来更改属性值。在用户更改属性值时，将针对插件调用 AK::Wwise::Plugin::Notifications::PropertySet::NotifyPropertyChanged() 。这样就可以基于这一更改来调节其他属性的值，比如自定义数据和属性范围依赖项。另外，若这时正在显示对话框，则可指定要在对话框中执行的操作（比如启用或禁用控件）。

备注: XML 允许依据规则描述依赖项。有关更多详细信息，请参阅插件 XML 相关性章节。

class MySourcePlugin
:   public AK::Wwise::Plugin::AudioPlugin
{
public:
    void NotifyPropertyChanged(
         const GUID& in_guidPlatform,
         const char* in_szPropertyName) override
    {
        if (strcmp(in_szPropertyName, "PropertyKey") == 0)
        {
            // Access the property set
            int32_t value = 0;
            if (m_propertySet.GetValueInt32(in_guidPlatform, in_szPropertyName, value))
            {
                // Do something with the value
            }
        }
        else if (strcmp(in_szPropertyName, "OtherPropertyKey") == 0)
        {
            // ...
        }
    }
};

Reference Set

A Reference Set instance is provided to the plug-in as a member variable m_referenceSet when deriving the AK::Wwise::Plugin::RequestReferenceset request interface. This allows for data about other objects in the Wwise project that the plug-in references to be accessed. In functions such as AK::Wwise::Plugin::AudioPlugin::GetBankParameters, referenced objects such as Game Parameters or Sidechain Mix sharesets can be resolved into Short IDs for use in the runtime with supported sound engine APIs. Some other functions for referenced objects are provided, such as the ability to access the GUID or name of an object, or to update a Reference to a new Object.

class MyEffectPlugin
:   public AK::Wwise::Plugin::AudioPlugin
,   public AK::Wwise::Plugin::RequestReferenceSet
{
public:
    bool GetBankParameters(
         const GUID& in_guidPlatform,
         AK::Wwise::Plugin::DataWriter& in_dataWriter) const override
    {
        bool result = true;
        // Access the unique shortId of a referenced object
        AkUniqueId value = m_referenceSet.GetReferenceShortId(in_guidPlatform, "TargetGameParameter");
        // Write the value into the sound bank
        result &= in_dataWriter.WriteUInt32(value);
        return result;
    }
};

备注: The lifetime of the m_referenceSet variable is the same as the lifetime of the plug-in instance. Do not store an address or reference to this instance across plug-in instances. 此外，也可在后端类和前端类中请求此服务。

Reference Set Notification

Wwise users can change object references through a control in the dialog, or by using the undo/redo commands. When a user changes a Reference, AK::Wwise::Plugin::Notifications::ReferenceSet::NotifyReferenceChanged() is called on your plug-in, which can update other plug-ins or UI states based on this change.

class MySourcePlugin
:   public AK::Wwise::Plugin::AudioPlugin
,   public AK::Wwise::Plugin::RequestReferenceSet
{
public:
    void NotifyReferenceChanged(
         const GUID& in_guidPlatform,
         const char* in_pszReferenceName) override
    {
        if (strcmp(in_pszReferenceName, "TargetGameParameter") == 0)
        {
            // Access the reference's GUID
            GUID refGuid = m_referenceset.GetReferenceGuid(in_guidPlatform, in_pszReferenceName);
            // Do something with the GUID
        }
    }
};

自定义数据

倘若插件使用曲线、坐标图等复杂数据，那么属性集可能无法充分表示这类数据。不过，我们可以借助自定义数据机制来处理这类复杂数据。自定义数据的要求如下：

以 XML 数据形式（如二进制文件路径、base64 内容等）实现加载和保存机制。
在所述数据发生更改时告知 Wwise 以便在声音引擎中重新加载。
实现序列化函数以便写入到 SoundBank 中并用作声音引擎插件的参数。

这些操作可通过实现特定的接口来完成：

AK::Wwise::Plugin::CustomData ：提供必要的接口以将自定义数据加载和保存到 Wwise 工程中。
AK::Wwise::Plugin::RequestHost ：提供函数以向设计工具发送通知 (AK::Wwise::Plugin::Host::NotifyInternalDataChanged())

备注: 插件可完全控制其自定义数据，因此不应针对此类数据在插件 XML 中作任何定义。

提供自定义数据

您可以通过实现 AK::Wwise::Plugin::CustomData::GetPluginData 来提供插件数据。为此，需要定义自定义参数 ID，并确保其与调用 AK::IAkPluginParam::SetParam 时用来在插件的声音引擎部分中读取此数据的参数 ID 保持一致。

初始化和保留自定义数据

自定义数据由插件实例保有，其须加载并保存到工程中以供持续使用。强烈建议在适宜情况下尽可能使用纯 XML 来表示复杂数据，以便在工程处于版本控制之下时便捷地实施合并。要想保存更为复杂的数据，可将其编组为 base64 内容，或者保存文件以将工程根目录的相对路径保留为 XML 元素。

AK::Wwise::Plugin::CustomData 可提供为方便持续使用数据而要实现的函数：

AK::Wwise::Plugin::CustomData::InitFromWorkunit() 接收 AK::Wwise::Plugin::XmlReader 以将自定义数据解组。
AK::Wwise::Plugin::CustomData::Save() 接收 AK::Wwise::Plugin::XmlWriter 以将自定义数据编组。

若插件实例的自定义数据成功保存到了工程的 Work Unit，则将在工程加载过程中（实例化不久之后）调用 InitFromWorkunit 。设计工具还可依据具体情形选用另外两个函数来初始化自定义数据插件。这两个函数相互排斥；在初始化时仅可调用其中一个函数。

AK::Wwise::Plugin::CustomData::InitToDefault() ：在设计工具初始化新的实例或没有保存的数据可用时。
AK::Wwise::Plugin::CustomData::InitFromInstance() ：在用户复制插件实例、插件实例被删除或执行恢复操作时。

备注: 插件代码负责处理数据的版本控制。为此，强烈建议在自定义数据中添加版本控制信息。请确保您的插件知道哪些版本的数据可以加载，哪些不可以，以避免崩溃和数据损坏。

自定义数据通知

您可以使用 AK::Wwise::Plugin::Host::NotifyInternalDataChanged() 函数，来告知 Wwise 某些数据发生了更改，需要保存该数据并将其传给声音引擎。为此，可指定 ParamID 来规定仅针对特定的数据子集发送通知。我们将此内部数据单元称为“复杂属性”。另外，还可使用 AK::IAkPluginParam::ALL_PLUGIN_DATA_ID 来指定所有发生更改的数据。

备注: 请不要将 NotifyInternalDataChanged 用于在 XML 中声明并由 Property Set 处理的属性。在使用来自于 AK::Wwise::Plugin::PropertySet 的设置函数时，会自动发送通知。

在用户修改自定义属性且插件调用 NotifyInternalDataChanged 时，Wwise 会调用其 AK::Wwise::Plugin::CustomData::GetPluginData 方法，来获取要传给插件的声音引擎部分的数据块。声音引擎插件将通过 AK::IAkPluginParam::SetParam 接收该数据块。在此过程中，将使用 NotifyInternalDataChanged 中指定的 ParamID。

备注: 若使用自定义属性，则须在 AK::IAkPluginParam::SetParam 和 AK::Wwise::Plugin::CustomData::GetPluginData 中处理 AK::IAkPluginParam::ALL_PLUGIN_DATA_ID 。该 ID 至少要在首次运行插件时使用一次。

属性显示名称和数值

您可以通过在 Property 标记中指定 DisplayName 属性，来分别为每项属性设定一个便于识别的名称（详见属性要素章节）。不过，如有在不同情境下具有不同含义的动态属性，则可实现 AK::Wwise::Plugin::PropertyDisplayNames 接口，并为属性和命名值指定显示名称。

用户界面中的好几个地方都会显示属性名称。其中包括 RTPC Manager、Multi Editor、撤消/重做命令的编辑菜单（属性发生更改后）等等。

AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp 中的 in_pszPropertyName 参数与插件 XML 定义文件 (Wwise 插件 XML 描述文件) 中指定的属性名称对应。该方法的实现示例如下：

bool MySourcePlugin::DisplayNameForProp(
    const char* in_pszPropertyName,
    char* out_pszDisplayName,
    uint32_t in_unCharCount) const
{
    if (strcmp(in_pszPropertyName, "Frequency") == 0)
    {
        strncpy(out_pszDisplayName, "Frequency (KHz)", in_unCharCount);
        return true;
    }
    return false;
}

若特定属性包含非数字值（比如用来表示 On/Off 或 Yes/No 的布尔值、曲线类型之类的枚举值）或某些数值具有特殊含义，则可在实现 AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() 时，为属性的部分或所有可能值指定所要显示的自定义文本。这些自定义文本将用在 RTPC 坐标图中，来标示 Y 轴上的坐标值。

备注: AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() 所构建的字符串在格式上与针对对话框中的 Combo Box 控件指定的 Options 属性相同（详见 Wwise 插件对话框参考文档章节）。该字符串包含多个数值/文本对（使用逗号隔开），每个对又包含相应的数字值和文本（使用冒号隔开）。例如：

布尔值属性："0:Off,1:On"
视为枚举的数值属性："0:Low Pass,1:High Pass,2:Band Pass"
具有特殊含义值的数值属性：“-100:Left,0:Center,100:Right”

对于bool 属性，值/文本组的值一侧使用0代表 false ，1代表 true 。

在以下代码示例中，名称从插件资源中获取的：

// 允许 Wwise 为该属性值获取用户可见的名称（例如 RTPC）。
bool MySourcePlugin::DisplayNamesForPropValues(
    const char * in_pszPropertyName,
    char * out_pszValuesName,
    uint32_t in_unCharCount
) const
{
    if (strcmp(in_pszPropertyName, szSmoothMode) == 0)
    {
        strncpy(out_pszValuesName, "0:LowRes,1:HiRes", in_unCharCount);
        return true;
    }
 
    return false;
}