滤镜蓝图

1. 基本概述

滤镜节点在引擎端渲染侧是一个有向图节点序列，分为前处理流程序列图、后处理流程序列图。引擎在渲染时对每个滤镜节点进行了依赖分析，得到每个滤镜节点的输入渲染目标和输出渲染目标，并利用这些输入输出目标，结合给定的材质Pass中的Shader，进行图元绘制和渲染。

2. 滤镜节点

节点间可以存在多个依赖，一个滤镜节点可接受最多7个输入InputTextureSampler_n和7个输出OutputRenderTarget_n，其中n取值为[0,6]。每个输出声明对应一个在Pass里创建的RenderTarget。如OpenGLES为例，RenderTarget通过附加纹理的帧缓冲对象渲染生成。节点间的输入输出决定滤镜节点间的依赖关系。 在实际业务中，往往需要动态生成这个渲染依赖图。为此，我们在高阶对象系统中引入滤镜节点树，节点树中的节点由节点注入器生成和注入，节点注入器可存在于独立的Actor、蓝图节点中，以此实现节点对象的灵活拆卸、组装、高复用性、几乎无额外性能损耗的要求。更多原理细节，可访问引擎图像处理框架和引擎滤镜节点链体系。

滤镜节点类型可按如下划分：

• 滤镜系统固定节点
  • 原始纹理采样输入节点 XEPFilterOriginInputSamplerNode， 当该节点连接到滤镜节点的输入槽时，表示该输入槽接受一个原始纹理采样输入。
  • 滤镜结束节点 XEPFilterFinalOutputNode，该节点为最终滤镜纹理输出。
  • 滤镜处理过程类型设置节点 XEPFilterRenderProcessNode, 允许将该滤镜节点流程设置为前处理/后处理过程。
• 滤镜节点容器
  • 自定义绘制节点 XEPFilterNode， 包含一个XEFilter模板和编译时生成的XEFilterInstance实例
  • 缓存帧节点 XEPFilterCacheNode, 为自定义绘制节点的扩展，但只是负责生成帧缓存，无需材质
• 修改器节点，在运行时可动态改变滤镜所用的数据
  • 美颜修改器， 一个便捷的美颜参数修改专用节点，会管理和收集可用美颜参数
  • 人脸实体修改器，捕获CV算法模型中的人脸实体数据，包含表情、头转向角度、人脸关键点、人脸形变的顶点数据等
  • 人脸形变修改器，为人脸实体修改器的扩展修改器，专门负责从人脸形变顶点数据中生成引擎可用的顶点描述和数据，支持大眼、瘦脸和瘦脸类型设置
  • 人脸Mask纹理修改器， 实时从CV算法数据生成一张人脸/人体的Mask单通道纹理，作扣图纹理使用
  • Pass参数修改器，支持运行时动态修改Pass输出目标的尺寸（相对/绝对）
• 数据适配器节点，对修改器数据的适配和进一步处理
  • 美颜参数适配器，获取/设置美颜修改器中的参数，为连接节点作数据适配
  • 人脸实体数据适配器，获取/设置人脸实体修改器中的数据，为连接节点作数据适配
  • 滤镜材质参数适配器，获取/设置材质参数，为连接节点作数据适配
• 变量节点
  • 包含4种基础数据类型。数据节点以XEPVariableNode为基类。包含一个XEVariant变量。节点可声明为常量，也可声明为变量。有具体意义的常量定义，会持续在节点库中进行补充。
    • 布尔型(xbool)
    • 浮点型(xfloat32, XVECTOR2, XVECTOR3, XVECTOR4, XETransform, XCOLORBASE)
    • 字符串(XString)
    • 整型(xin32)
  • 脚本逻辑输入节点，XEPVariableScriptNode。可以挂载一个Lua脚本，并影响连接的节点。

3. 滤镜节点引脚

节点两侧都有引脚。左侧的引脚是输入引脚，右侧的引脚是输出引脚。滤镜蓝图中的节点引脚使用的都是数据引脚，在混合蓝图中，既有数据引脚，又有执行引脚，在此不多介绍。

数据引脚用于将数据导入节点或者从节点输出数据。数据引脚在界面上显示为圆形，引脚旁边标注的为对应引脚名称。引脚在未连接到任何对象时，引脚名称会显示为暗灰色，连接到对象后则显示为白色。鼠标浮动到引脚上时，会有该引脚的Tooltip提示信息。

基础类型转换，数据引脚一般只能与同类型的相连接，但也支持一些可自动转换的不同的基础类型相连接，比如Int与Float、Bool与Int等也可以连接。如果不存在转换，则连接线为单一色，而存在自动转换时，连接线会出现渐变色。

4. 滤镜节点连接

节点之间通过引脚之间的连线从而连接起来。滤镜蓝图中，引脚之间的连线一方面表示了数据流向，另一方面表示了节点之间的依赖关系。目前仅支持一个输入（输出）引脚与一个输出（输入）引脚相连接，后续可能根据需求扩展。

连接：在蓝图编辑器中，使用鼠标从一个（输入/输出）引脚拖动到另一个（输出/输入）引脚，如果两个引脚数据类型一致，即可连接成功。拖动过程中，连接线为虚线，连接成功后变为彩色实线。

断开：在蓝图编辑器中，断开连接有两种方法。可以从输入引脚直接拖动连接线到空白处，松开鼠标即可断开连接；还可以点击连接线，选中后，按住Delete键（Windows端）或者Commond+Delete键（Mac端）删除。

5. 滤镜蓝图编辑器使用

我们对蓝图各项编辑工作可使用蓝图编辑器来完成。

蓝图编辑器界面总共分为五个部分：蓝图面板tab、加载的蓝图子页签、工具栏、节点属性面板和蓝图节点编辑面板。

5.0.1. 蓝图面板tab

拖动“蓝图”tab（可拖动区域仅限于文字部分），可随意移动蓝图面板在整个编辑器中的位置，移动到其他面板上时，会出现如下位置标识，松开鼠标即可把蓝图面板嵌入到对应区域。

5.0.2. 蓝图子页签

蓝图编辑器可打开多个蓝图文件，文件名以蓝图子页签的形式展示（文件名不带后缀）。

5.0.3. 工具栏

• 文件：文件菜单中有一系列蓝图文件相关的操作。
  • 创建滤镜蓝图：点击，弹出文件命名对话框，确定后，即可创建一个空的滤镜蓝图文件.
  • 创建混合蓝图：点击，弹出文件命名对话框，确定后，即可创建一个空的混合蓝图文件.
  • 保存：保存当前蓝图到文件中，默认保存到"Resources\blueprint\"文件夹中，Resources与工程路径同级；蓝图编辑器保存会生成两个文件，xx.edg(界面文件)和xx.rtg(引擎资产).
  • 另存为：蓝图文件另存为.
  • 加载：打开一个已有的蓝图文件，支持edg/rtg格式。
  • 清空：当只存在一个蓝图子页签时，可清空当前蓝图。

• 编辑：编辑菜单中汇集了一系列蓝图编辑的操作。

  • 撤销/重做：针对蓝图编辑器每一步编辑操作的撤销/重做。备注：因为与主编辑器快捷键冲突，蓝图编辑器中不支持Ctrl+Z/Y快捷键。
  • 基础滤镜链：添加一组基础滤镜节点，包括：原始纹理采样输入节点、默认滤镜节点、滤镜结束节点和滤镜处理过程类型设置节点，并连接好输入输出关系。
  • 运行蓝图：编译并运行当前蓝图，该操作与停止蓝图操作互斥。
  • 停止蓝图：停止运行当前蓝图，该操作与运行蓝图操作互斥。
  • 截图：把当前蓝图内所有节点渲染到一张png图片上，并保存到Resources\blueprint文件夹下。
  • 属性面板：显示/隐藏属性面板。

• 基础按钮：以下基础按钮同文件或编辑菜单中对应项。

• 其他：

5.0.4. 节点属性面板

节点属性面板，用于展示和编辑当前选中的节点/引脚/图的基本属性。

5.0.5. 蓝图节点编辑面板

• 缩放系数：它仅显示当前蓝图编辑器中的缩放比例。
• 蓝图类型标签：它显示您正在编辑的蓝图的类型。当您编辑滤镜蓝图（FILTER BLUEPRINT）、混合蓝图（MIX BLUEPRINT）,它会发生变化。
• 编辑控制操作
  • 平移蓝图：左键单击+拖动
  • 缩放蓝图：鼠标滚轮
  • 弹出上下文菜单：右键单击
  • 选择节点/连接线：左键单击
  • 删除节点/连接线：选中后，Delete(Mac: Commond+Delete)
  • 多选：Ctrl+左键单击
  • 框选：Shift+左键单击+拖动
  • 拖动节点：左键单击+拖动
  • 引脚连接：单击+拖动
• 添加节点：蓝图编辑区，右键单击空白处，弹出添加节点菜单，列出了多种类型节点。
  • OneKeyAdd：添加基础滤镜链，同工具栏。
  • BaseData：基础数据输出节点，包括Int/Bool/Float/Float2/Float3/String/Image等类型节点。
  • BitwiseOperation：移位运算节点（>>, <<，|, &, ^），生成并输出一个xuint32。
  • Compare：逻辑比较运算节点( >, <, ==, >=, <=, !=)。
  • Filters：滤镜节点，包括CommonFilter(滤镜自定义绘制节点)和CacheFilter(滤镜缓存帧节点).
  • LogicOperation：逻辑节点（&&、||、！）。
  • Loop: 循环节点，包括While循环节点和For循环节点。
  • Math: 基础数学节点，包括加、减、乘、除、Max、Min、取模、Leap插值、sin、cos基础三角函数等。
  • ModifierDataAdapter: 数据适配器节点，包括FilterParamGetter(滤镜材质参数适配器节点)、FilterFaceEntityGetter(人脸实体数据适配器节点)、FilterBeautiFxGetter(美颜参数适配器节点)。
  • Modifiers: 修改器节点，包括ScriptModifier(脚本修改器节点)、FilterFaceEntityModifier(人脸实体修改器)、FilterFaceWarpModifier(人脸形变修改器)、FilterPassModifiter(Pass参数修改器节点)、FilterBeautiFxModifier(美颜修改器)、FilterMaskEntityModifier(人脸Mask纹理修改器)。
  • Reoute: 路由节点(暂不可用)，用于可视化地改善图中的数据流。
  • SubGraphs: 子图节点，已存在的子图节点会在这里列出来。
  • TypeConvert: 基本类型转换节点，包括(int->bool、bool->int、int->float、float->int...)等。

• 子图：我们可以把已完成的一个完整的滤镜效果（包括各个节点和连接线），打包成一个子图节点，这样界面更简洁，并且这个滤镜效果作为一个子图节点可重复使用。
  • 打包成子图方式：选中要打包的各个节点及连接线，右键=》打包为子图，即可。
  • 子图展示：打包之后，变成一个节点，可双击进入子图显示。
  • 使用：打包后的子图文件，在节点添加菜单中的SubGraphs中列出，点击对应添加即可重复使用。

6. 滤镜蓝图开发最佳实践

此部分主要用于介绍如何使用滤镜蓝图编辑器编辑一个完整的滤镜效果。

6.1. 基本制作流程

6.1.1. 创建基础滤镜链

打开蓝图编辑器，创建一个完整的基础滤镜链，有两种快捷方式：

• 通过蓝图编辑器工具栏的快捷创建按钮创建：

  

• 在蓝图编辑窗口空白处右键，在弹出的右键菜单中，选择OneKeyAdd项创建：

  

通过快捷方式创建的四个节点分别是Origin Input、Common Filter、Final Output和Filter RenderProcess，想要将滤镜效果正常表现出来，这四个节点缺一不可。每个节点的作用如下：

• Origin Input：节点类型为XEPFilterOriginInputSamplerNode，代表原始输入图像（视频帧）。
• Common Filter：节点类型为XEPFilterNode，代表一个滤镜节点，通过指定材质文件（.mt格式）加载滤镜效果。
• Final Output：节点类型为XEPFilterFinalOutputNode，代表滤镜结束，用于将滤镜纹理输出。
• Filter RenderProcess：节点类型为XEPFilterRenderProcessNode，用于控制滤镜节点生效的时机（前处理/后处理）。

6.1.2. 指定材质文件

选中滤镜节点（Common Filter），在属性面板中指定工程目录下已存在的材质文件，材质文件后缀名为.mt。

指定材质文件后，滤镜蓝图节点会创建材质实例，将shader中的处理效果展示在场景窗口。

点击属性面板的Open按钮，会自动在Visual Studio Code中打开材质文件（打开过程可能较慢，请耐心等待）。

6.1.3. 创建材质文件

通过滤镜节点属性面板的【创建材质文件】按钮可创建默认的mt文件，同时会创建mt文件关联的两个着色器文件（vertex着色器和pixel着色器）。

材质文件创建完成之后，滤镜蓝图节点会自定加载材质文件。由于自动创建的着色器文件没有特殊的逻辑算法，因此预览场景没有任何不同。

点击蓝图节点属性面板Pass选项卡内的【Open】按钮，会在Visual Studio Code中显示对应着色器文件的内容。

关于材质文件内各参数的含义、着色器文件的制作等相关内容，请参考XImageEffect_design.md。

6.1.4. 预览滤镜效果

指定或创建材质文件后，一个简单的滤镜蓝图即制作完成，完整的蓝图节点图如下：

滤镜蓝图制作完成后，首先在主编辑器工具栏中选择一个预览视频，然后点击蓝图编辑器的执行按钮来预览最终效果。

效果图如下（素材工程）：

此滤镜效果是根据当前时间动态变化当前帧的透明度和大小，具体算法可参考素材工程下的douyin_linghunchuqiao_ps.glsl文件，路径为.\resources\BlueprintDemo1\Resources\materials\douyin_linghunchuqiao。

6.2. 制作复杂的滤镜效果

上述部分介绍了创建一个滤镜效果的流程，对于非常复杂的效果与上述流程基本一致，只不过需要增加多个滤镜蓝图节点实现。

如下图所示的滤镜效果由lookup和闪白两个效果组成（先执行lookup滤镜节点，再执行闪白效果滤镜节点）：

其最终的滤镜蓝图为：