E.E. 支持自定义节点

ihc5232022-01-14

从 v1.0.2 开始，EffectExporter可以通过封装一些 GLSL 代码来创建自定义节点

自定义节点

从 v1.0.2 开始，EffectExporter可以通过封装一些 GLSL 代码来创建自定义节点 CustomBlock。当有一些复杂的特效可能很难用现有的节点实现时，自定义节点将会非常有用且高效。
v1.0.3 将自定义节点声明改为 ts，支持语法提示。语法详见目录下 block.d.ts。

实现

以一个 OreoMultiply 自定义乘法节点的实现来讲解。该节点功能与内置的 Multiply 乘法节点功能相同，这里只是演示如何自定义节点。
```
   // 自定义节点示例
export const block: ICustomBlockOption = {
	name: "OreoMultiply",
	comments: "自定义乘法节点示例",
	document: "https://www.exporter.top/docs/#/zh-cn/block/custom",
	target: "Fragment",
	inParameters: [
		{
			name: "left",
			type: "AutoDetect",
		},
		{
			name: "right",
			type: "AutoDetect",
		}
	],
	outParameters: [
		{
			name: "output",
            type: "BasedOnInput",
            typeFromInput: "left"
		}
	],
	inLinkedConnectionTypes: [
        {
            input1: "left",
            input2: "right",
            looseCoupling: false
        }
    ],
	includes: [
        // "helperFunctions",
        "shaderToyDeclaration"
    ],
	entryFunctionName: "multiply_{TYPE_left}",
    code: `
        {TYPE_output} myHelper_{TYPE_left}({TYPE_left} l, {TYPE_right} r){ 
			return l * r; 
		}
        void multiply_{TYPE_left}({TYPE_left} l, {TYPE_right} r, out {TYPE_output} result) {
           result = myHelper_{TYPE_left}(l, r);
        }
    `
}
```
- export const block: ICustomBlockOption 固定写法，导出一个 ICustomBlockOption 对象。
- name 自定义节点名称
- comments 概述
- document 细节说明文档，主要用来讲解节点的实现原理。
- target 默认使用的着色器输出目标，可选值 Neutral, Vertex, Fragment, VertexAndFragment
- in/out parameters: 输入/输出插槽插槽说明，可选值 Float, Int, Vector2, Vector3, Vector4, Color3, Color4, Matrix, Object, AutoDetect, BasedOnInput
- inLinkedConnectionTypes 各输入插槽的类型是否强行关联。looseCoupling 表示是否弱耦合，值为 false 表示强行关联。
- includes 加载自定义的公共文件。文件内可定义共用变量、共用方法等；
- entryFunctionName 自定义节点导出的入口函数名称
- code 自定义节点导出的 GLSL 代码
1、由于自定义块允许任何类型的输入（Float、Vector3 等），输出类型设置为 BasedOnInput 表示关联 typeFromInput 指定的输入插槽的类型。
2、另外，我们希望左右输入的类型相同（一旦确定一个输入，另一个应该继承相同的类型），这就是为什么我们在文件中有一个 inLinkedConnectionTypes 属性。上述示例中，表示输入端的插槽 left 和 right 类型强行关联，当 left 插槽确定为 Float 类型时，right 插槽也会立即确定为 Float 类型
3、由于在我们创建 .json 文件时不知道这些类型，我们必须使用特殊语法 {TYPE_XXX} 在 GLSL 代码中引用它们，其中 XXX 是输入/输出插槽的名称；在运行时，这些语法将替换为正确的类型（float、vec2 等）。
4、请注意，这里使用 myHelper_{TYPE_left} 辅助函数只是为了演示您可以在代码中使用其他函数，您可以根据实际情况修改。
5、请注意，入口函数（在 entryFunctionName 属性中导出的那个函数）必须返回 void；输入参数的个数必须与 inParameters 数组定义的参数个数相同；输出参数必须放在最后，并且它必须以 out 参数接收结果返回（参见示例）。

导入

自定义节点由 .json 文件描述，该文件集成在插件 oreo-shader-effect-exporter\editor\blocks 目录下。用户可手动修改并增加自己的自定义节点，修改后点击 刷新 按钮即可自动重新载入。

使用

自定义节点与其他节点没有区别，因此只需将一个节点从节点列表中拖放到主区域即可

示例

目前参考 ShaderToy 特效实现了部分示例，可在在线示例列表中一键加载，实现细节请参考插件内文件 oreo-shader-effect-exporter\editor\blocks。部分示例效果展示如下：
火焰效果
水波纹荡漾效果

万花筒效果
导出到 CocosCreator 中运行效果如下