FMOD Studio User Manual 2.02

20. 插件引用

FMOD Studio Suite 支持加载使用 FMOD Studio 插件 SDK 创建的 DSP 插件。请参阅 FMOD Studio 插件 SDK 文档 了解有关为 FMOD 创作 DSP 插件的更多信息。

20.1 加载插件

插件库可从以下位置自动加载:

更改用户插件目录将导致所有插件被重新加载。对于加载失败的插件，警告会添加到日志中。这可以从控制台窗口的日志记录选项卡中查看。

20.2 使用插件

一旦加载了 DSP 插件，就可以在项目中使用。具有零输入通道的插件，通常称为生成器，可作为插件发声器添加。

添加插件发声器

可将处理输入信号的插件添加为插件效果。

添加插件效果

默认情况下，FMOD Studio 中插件的外观基于FMOD_DSP_DESCRIPTION和附加的FMOD_DSP_PARAMETER_DESC。这包括插件的名称、可用属性和操作台布局。

可使用插件脚本 API更改插件的外观。

20.3 插件脚本 API

可通过添加位于插件库旁边的 javascript 文件来扩充 FMOD_DSP_DESCRIPTION，自定义插件的外观。此文件必须以.plugin.js扩展名结尾。然后 javascript 文件可使用插件脚本 API。插件脚本 API 可用于为使用studio.plugins.registerPluginDescription()函数的一个或多个插件注册插件描述。例如: 

studio.plugins.registerPluginDescription("Acme_Explosion", {
    companyName: "Acme",
    productName:  "Explosion Generator",
    deckUi:  {
        // deck widget layout
    },
});

通过注册插件描述，可相应地定制插件的外观。

自定义插件用户界面示例

重新加载插件库时，或选择“脚本 > 重新加载”时，会重新加载插件脚本文件。

建议在部署插件库后不要更改 FMOD_DSP_DESCRIPTION.name 和 FMOD_DSP_PARAMETER_DESC.name 字段，因为 FMOD Studio 使用这些名称作为相应 DSP 的标识符。

20.3.1 API 函数

studio.plugins.registerPluginDescription（标识符，插件描述）

注册插件说明。identifier 必须匹配 FMOD_DSP_DESCRIPTION.name。

pluginDescription 参数是一个具有如下所述属性的对象。pluginDescription 的所有属性都是可选项。

pluginDescription.companyName

与插件作者相对应的 string 。在右键菜单中，具有相同公司名称的插件被编组在同一个菜单中。

pluginDescription.productName

与插件名称对应的 string 。

pluginDescription.parameters

将每个 FMOD_DSP_PARAMETER_DESC.name 映射到描述 Object 的 Object 。每个 DSP 参数描述 Object 包含以下可选属性:

例如: 

parameters: {
    "gain": {
        // FMOD_DSP_PARAMETER_DESC.name 是 "gain"
        displayName:  "Volume"
    },
    "freq": {
        // FMOD_DSP_PARAMETER_DESC.name 是“freq”
        displayName:  "Frequency"
    },
    "outputMode": {
        // FMOD_DSP_PARAMETER_DESC.name 是“outputMode”
        displayName:  "Output",
        enumeration: ["Mono", "Stereo", "Surround"], // 单声道 = 0, 立体声 = 1, 环绕声 = 2
    },
    "pattern": {
        // FMOD_DSP_PARAMETER_DESC.name 是“pattern”
        displayName:  "Pattern",
        enumeration: ["Rain", "Hail", "Shine"], // 雨 = 0, 冰雹 = 1, 光 = 2
    },
},

pluginDescription.defaultConfigurations

包含描述插件参数默认配置的对象的 Array。这些可以从操作台中插件的右键菜单访问。

defaultConfigurations: [
    {
        name: "Quiet",
        parameterValues: {
            "gain":  -20,
        },
    },
    {
        name: "Bright",
        parameterValues: {
            "gain": 0,
            "freq": 5000,
        },
    },
],

pluginDescription.deckUi

当显示在操作台中时，描述插件用户界面的 Object。例如: 

deckUi: {
    deckWidgetType: studio.ui.deckWidgetType.Layout,
    layout: studio.ui.layoutType.VBoxLayout,
    spacing: 6,
    items: [
        { deckWidgetType: studio.ui.deckWidgetType.Pixmap, filePath: __dirname + "/company_logo.png", },
        { deckWidgetType: studio.ui.deckWidgetType.Button, binding: "invert", },
        { deckWidgetType: studio.ui.deckWidgetType.Dial, color: "#e31a1c", binding:  "freq", },
        { deckWidgetType: studio.ui.deckWidgetType.Dropdown, binding: "mode", buttonWidth:  44, },
    ],
},

操作台面板的布局基于操作台小部件描述对象，其包含以下属性:

适用于deckWidgetType.Layout:

适用于 layoutType.HBoxLayout 或 layoutType.VBoxLayout 中的项目:

适用于 layoutType.GridLayout 中的项目:

适用于deckWidgetType.Label:

适用于deckWidgetType.Pixmap:

适用于deckWidgetType.Dial:

适用于deckWidgetType.Fader:

适用于deckWidgetType.MinMaxFader:

-minimumBinding: 要绑定到范围最小值的 DSP 属性名称。这必须匹配FMOD_DSP_PARAMETER_DESC.name。必要属性。
- maximumBinding: 要绑定到范围最大值的 DSP 属性名称。这必须匹配FMOD_DSP_PARAMETER_DESC.name。必要属性。
- text: 在推子上方的标签中显示的文本。

适用于deckWidgetType.NumberBox:

适用于deckWidgetType.Dropdown:

适用于deckWidgetType.Button:

适用于deckWidgetType.ButtonGroup:

适用于deckWidgetType.DataDrop:

适用于deckWidgetType.DistanceRolloffGraph: 

    rolloffTypes: {
        -1:  studio.project.distanceRolloffType.Custom,
        0:  studio.project.distanceRolloffType.Linear,
        1:  studio.project.distanceRolloffType.LinearSquared,
    },

适用于deckWidgetType.PolarDirectivityGraph:

-directivityBinding: 要绑定到表示极坐标方向性的 DSP 属性名称。这必须匹配FMOD_DSP_PARAMETER_DESC.name。分配的属性应在 0 到 1 的范围内。必要属性。
- sharpnessBinding: 要绑定到表示极坐标锐度的 DSP 属性名称。这必须匹配FMOD_DSP_PARAMETER_DESC.name。分配的属性应具有从 1 开始的范围。必要属性。

studio.ui.deckWidgetType

对应于pluginDescription.deckUi小部件可用的不同操作台小部件类型的枚举。对于可绑定控件（例如表盘、推子），应选择具有适当FMOD_DSP_PARAMETER_TYPE的属性。可能的值是:

studio.ui.dataDropMode

与可用于deckWidgetType.DataDrop小部件不同类型输入法相对应的枚举。可能的值是:

20.4 更新插件

使用自定义 DSP 插件时，有时可能会从 FMOD Designer 项目迁移，迁移到 FMOD Studio 的较新版本，或者 DSP 的描述得到更新，这可能导致 DSP 需要在 FMOD Studio 项目中修复。

当检测到问题时，效果插件模块或插件发声器会褪色并带有黄色虚线轮廓。

检测到效果插件问题

FMOD Studio 支持在插件描述更改或删除插件 DLL 时修复或删除 DSP 插件实例。这可以通过单击相应插件实例的操作台小部件来完成。可以针对每个实例或整个项目修复或删除插件。

修复插件

FMOD Studio User Manual 2.02.24 (2024-07-26). © 2024 Firelight Technologies Pty Ltd.