着色器图（实验性）¶

备注

Shader Graph Editor 是一项实验性功能，在 Kanzi Studio 的未来版本中可能会更改或被移除。要启用该功能，请参阅启用着色器图编辑器。

Shader Graph Editor 是一个基于节点的可视化工具，用于在 Kanzi Studio 中构建 GLSL 片段着色器。您无需手动编写着色器代码，而是创建一个由相互连接的节点组成的图来定义着色器逻辑。生成着色器时，Kanzi Studio 会将该图编译为 GLSL 片段着色器，并据此创建 Material Type。对于基于物理的图，Kanzi Studio 还会创建使用该 Material Type 的 Material。

启用着色器图编辑器¶

要启用 Shader Graph Editor：

在 Kanzi Studio 中选择 Edit > User Preferences。
选择 Experimental 选项卡。
在 Web-based editors 部分中，启用 Shader graph editor。

材质类型 (Material Types)¶

每个着色器图针对一种材质类型。材质类型决定 Material Output 节点公开哪些输入端口，以及 Kanzi Studio 生成何种 GLSL 片段着色器。

在编辑器左上角的 Material 下拉菜单中设置材质类型。

材质类型	描述 (Description)
PBR	基于物理的材质。Material Output 节点提供 Base Color、Metallic、Roughness、Normal、Emissive 和 AO （环境光遮蔽）输入。生成着色器时，Kanzi Studio 会创建一个 Material Type 以及使用它的 Material。
Fullscreen	全屏效果材质。Material Output 节点只公开一个 Color 输入。将此材质类型用于后期处理效果和类似的全屏渲染通道。

切换材质类型时，Kanzi Studio 会重新配置 Material Output 节点，并断开新端口集中已不存在的所有输入的连接。

在编辑器中导航¶

动作	快捷键
选择	左键点击节点或连接
平移	点击并拖动画布背景
缩放	鼠标滚轮
多选	`Shift` + 鼠标左键点击，或在画布上点击并拖动出选框
全部选中	`Ctrl` `A`
删除 (Delete)	选择节点或连接，然后按 `Delete` 或 `Backspace`
复制 (Copy)	`Ctrl` `C`
粘贴 (Paste)	`Ctrl` `V`
复制	`Ctrl` `D`
撤销 (Undo)	`Ctrl` `Z`
重做 (Redo)	`Ctrl` `Y`
将所选内容编组	`Ctrl` `G`
取消编组	`Ctrl` `Shift` `G`
自动布局	`Ctrl` `Shift` `A`
添加节点	右键点击画布，然后从 Add Node 菜单中选择节点。菜单打开时，菜单顶部的搜索框会自动获得焦点，因此您可以直接开始输入进行过滤

节点类型¶

Shader Graph Editor 提供分布在 7 个目录类别中的 45 个节点。Add Node 菜单按类别对节点进行分组，并包含一个可同时过滤所有类别的搜索框。数学节点是多态的，它们会调整自身的输入和输出类型以匹配所连接的端口。

除目录类别外，您还可以从 Utilities 子菜单添加 Note 节点，以及从所选内容创建 Group 节点。

常数¶

常数节点保存字面值，您可以直接在节点上编辑这些值。

节点 (Node)	描述 (Description)	输出
Scalar	常数浮点值。	result (float)
Int	常数整数值。	result (int)
Vec2	常数二维向量。	result (vec2), x (float), y (float)
Vec3	常数三维向量。	result (vec3), x (float), y (float), z (float)
Vec4	常数四维向量。	result (vec4), x (float), y (float), z (float), w (float)
Color3	RGB 颜色常数。点击节点上的色块可打开颜色选择器。	result (vec3)
Color4	RGBA 颜色常数。点击节点上的色块可打开颜色选择器。	result (vec4)

您可以将任何常数节点提升为参数，使其值成为可在 Kanzi Studio Properties 面板中编辑的 Uniform。请参阅参数。

内置¶

内置节点提供引擎在 rendering 期间生成的值。

节点 (Node)	描述 (Description)	输入	输出
UV	UV 纹理坐标。	—	uv (vec2), u (float), v (float)
Time	经过的时间和每帧增量。	—	Seconds (float), Delta (float)
TilingOffset	对 UV 坐标应用平铺和偏移。	uv (vec2), tiling (vec2), offset (vec2)	result (vec2)
Combine4	将四个 float 组合为一个 vec4。	r (float), g (float), b (float), a (float)	result (vec4)
RGB	将三个 float 组合为一个 vec3。	r (float), g (float), b (float)	result (vec3)

数学¶

节点 (Node)	描述 (Description)
Sin	正弦函数。
Cos	余弦函数。
Abs	绝对值。
Exp	自然指数运算（`e^x`）。
Negate	取负（一元减号）。
Normalize	向量归一化。
Length	向量长度。始终输出 float。
Dot	点积。始终输出 float。
Cross	两个 vec3 值的叉积。
Distance	两个 vec3 值之间的距离。始终输出 float。
Reflect	将入射 vec3 向量沿 vec3 法线进行反射。
Add	加法。
Subtract	减法。
Multiply	乘法。
Divide	除法。
Max	逐分量最大值。
Min	逐分量最小值。
Mix	线性插值（`mix`）。
Lerp	线性插值（`lerp`）。
Power	幂运算。
Clamp	将值限制在最小值和最大值之间。

材质 (Material)¶

材质节点提供逐片段的表面和视图数据，这些数据由引擎根据渲染的几何体填充。材质节点没有输入。

节点 (Node)	描述 (Description)	输出
Normal	世界空间中的表面法线。	normal (vec3), x (float), y (float), z (float)
Tangent	世界空间中的表面切线。	tangent (vec3), x (float), y (float), z (float)
Bitangent	根据法线和切线计算副切线。可以连接任意 vec3 源，不必使用 Normal 和 Tangent 节点。	bitangent (vec3)
WorldPos	当前片段在世界空间中的位置。	pos (vec3), posX (float), posY (float), posZ (float)
CameraPos	活动摄像机在世界空间中的位置。	pos (vec3), posX (float), posY (float), posZ (float)
ViewDir	世界空间中从片段指向摄像机的归一化视线方向。	viewDir (vec3)

纹理 (Texture)¶

纹理节点从 Kanzi Studio Library 中采样纹理资源。Texture 资源选择器列出工程中的所有纹理。

节点 (Node)	描述 (Description)
Texture	采样纹理。在节点上选择 Texture 资源，或者不设置以使用占位纹理。属性：Wrap （repeat、clamp、mirror）、Filter （linear、nearest）。输入：uv (vec2)。输出：rgba (vec4)、r、g、b、a (float)。
NormalMap	采样法线贴图并将结果变换到世界空间。输入：uv (vec2)、textureIndex (int)、strength (float)、worldNormal (vec3)。输出：result (vec3)。
UnpackNormal	将已采样的法线贴图颜色转换为世界空间法线向量。输入：normalSample (vec4)、strength (float)、worldNormal (vec3)。输出：result (vec3)。

自定义¶

使用 Custom 类别可以在图中嵌入手写的 GLSL。

节点 (Node)	描述 (Description)
GLSL Code	在编辑器中编写小型 GLSL 函数。在节点上设置 Function name，并在内嵌代码编辑器中编写函数体。节点会解析函数签名并据此生成端口：每个 `in` 参数成为一个输入端口，每个 `out` 参数成为一个输出端口，`inout` 参数同时成为输入和输出端口，非 `void` 返回类型会添加一个名为 `return` 的输出端口。支持的端口类型有 `float`、`vec2`、`vec3`、`vec4`、`int`、`bool` 和 `sampler2D`。当函数体包含多个函数时，编辑器使用名为 `main` 的函数作为入口点。

节点 (Node)

描述 (Description)

GLSL Code

在编辑器中编写小型 GLSL 函数。在节点上设置 Function name，并在内嵌代码编辑器中编写函数体。节点会解析函数签名并据此生成端口：每个 in 参数成为一个输入端口，每个 out 参数成为一个输出端口，inout 参数同时成为输入和输出端口，非 void 返回类型会添加一个名为 return 的输出端口。支持的端口类型有 float、vec2、vec3、vec4、int、bool 和 sampler2D。当函数体包含多个函数时，编辑器使用名为 main 的函数作为入口点。

例如，以下 GLSL Code 节点函数体会生成三个输入端口（uv、tile、softness）和两个输出端口（bright 和 return）：

// Soft checker mask. `tile` controls cell size; `softness` blurs cell edges.
// `bright` is 1.0 on bright cells, 0.0 on dark cells.
// The return value is the antialiased mask.

float Checker(vec2 uv, float tile, float softness, out float bright) {
    vec2 cell = floor(uv * tile);
    bright = mod(cell.x + cell.y, 2.0);
    vec2 f = fract(uv * tile);
    float edge = min(min(f.x, 1.0 - f.x), min(f.y, 1.0 - f.y));
    return smoothstep(0.0, softness, edge) * bright;
}

output¶

每个图必须有且仅有一个 Material Output 或 Output 节点，并与所有其他参与计算的节点相连。

节点 (Node)	描述 (Description)
Material Output	以材质类型为目标的图所必需的输出节点。输入端口随 Material 下拉菜单而变化： PBR：Base Color (vec4)、Metallic (float)、Roughness (float)、Normal (vec3)、Emissive (vec3)、AO (float)。 Fullscreen：Color (vec4)。
Output	用于不以材质类型为目标的图的通用颜色输出节点。

节点 (Node)

描述 (Description)

Material Output

以材质类型为目标的图所必需的输出节点。输入端口随 Material 下拉菜单而变化：

PBR：Base Color (vec4)、Metallic (float)、Roughness (float)、Normal (vec3)、Emissive (vec3)、AO (float)。
Fullscreen：Color (vec4)。

Output

用于不以材质类型为目标的图的通用颜色输出节点。

实用工具节点¶

实用工具节点不生成着色器代码。使用它们来组织图。

节点 (Node)	描述 (Description)
Group	可调整大小的容器，用于容纳其他节点。要从选中的两个或更多节点创建组，请按 `Ctrl` `G`，或在选择工具栏中点击 Group，或在右键上下文菜单中选择 Create Group。双击组页眉可重命名组。点击页眉上的 + / - 按钮可折叠或展开组，点击 N 按钮可附加备注，在右键菜单的 Color 行中可选择页眉颜色。
Note	自由浮动的注释。在 Add Node 菜单的 Utilities 下添加 Note。双击注释可编辑其文本。

使用着色器图¶

添加节点¶

右键点击画布打开 Add Node 菜单。可以浏览各类别子菜单，也可以直接输入以在所有类别中搜索。

要在特定位置添加节点，请先在画布上右键点击该位置，然后从菜单中选择。

连接节点¶

从一个节点的输出端口拖动到另一个节点的输入端口。每个输入端口只接受一个连接。为已连接的输入创建新连接会替换现有连接。

断开节点连接¶

选择连接并按 Delete 或 Backspace。要一次断开节点上的所有连接，请右键点击该节点并选择 Break Links。

编辑属性¶

常数节点直接在节点上显示可编辑的值字段。Color3 和 Color4 节点显示一个色块，点击可打开颜色选择器。Texture 节点显示资源选择器和所选纹理的缩略图。GLSL Code 节点会打开内嵌的 GLSL 编辑器。

选择上游和下游节点¶

要沿连接图扩展当前选择，请右键点击节点、连线或选择，然后选择 Select Upstream 或 Select Downstream。Select Upstream 会添加所有向当前选择提供输入的节点；Select Downstream 会添加所有接收当前选择输出的节点。

复制、粘贴和复制节点¶

要将选定的节点和连接复制到剪贴板，请按 Ctrl C，或者右键点击所选内容并选择 Copy。

要在视口中心粘贴剪贴板内容，请按 Ctrl V。在同一位置重复粘贴时，每次后续粘贴都会依次错开，以免新节点相互堆叠。

要在画布上的特定位置粘贴，请右键点击该位置并选择 Paste。

要在原位重复所选内容，请按 Ctrl D，或者右键点击所选内容并选择 Duplicate。

UV 和 Material Output 等内置节点在每个图中最多只能存在一个，并且无法复制或重复。

撤销和重做¶

编辑器会记录对图的每一次修改：添加和移除节点、编辑属性、连接和断开端口、分组、参数提升等。按 Ctrl Z 撤销，按 Ctrl Y 重做。在 GLSL Code 编辑器中，Ctrl Z 和 Ctrl Y 会先逐步回退本地代码编辑，然后才进入图的历史记录。

自动布局¶

要自动重新排列图，请按 Ctrl Shift A。编辑器会按数据流从左到右布局节点。

对节点分组¶

选择两个或更多节点，然后按 Ctrl G，在选择工具栏中点击 Group，或者右键点击并选择 Create Group。编辑器会将所选内容包装在一个可调整大小的 Group 容器中。

要重命名组，请双击其页眉。要折叠或展开组，请点击页眉上的 + / - 按钮，或者右键点击组并选择 Collapse Group 或 Expand Group。要附加注释，请点击 N 按钮。要更改组的颜色，请右键点击组并从 Color 行中选择一个色块。

要拆散组并保留其子节点，请选择该组并按 Ctrl Shift G，或者右键点击组并选择 Ungroup。

上下文菜单参考¶

右键上下文菜单中显示的内容取决于您右键点击的对象：

目标 (Target)	操作
空画布	Add Node 菜单（剪贴板不为空时还包含 Paste 快捷项）。
单个节点	Copy、Duplicate、Select Upstream、Select Downstream、Break Links、Promote to Parameter / Unpromote from Parameter （适用于可提升的常数）、Delete。组节点还提供 Collapse Group / Expand Group、Fit to Content、Ungroup 和 Color 行。
连接	Select Upstream、Select Downstream、Delete。
多选	Copy、Duplicate、Select Upstream、Select Downstream、Create Group （至少选定两个非实用工具节点时）、Delete。

有关 Promote to Parameter 的详细信息，请参阅参数。

生成着色器¶

点击编辑器右上角的 Generate Shader 以验证图并编译 GLSL 片段着色器。要在每次更改后自动重新生成，请启用 Generate Shader 按钮旁边的 Auto 开关。编辑器会对重新生成进行防抖处理，使一连串的编辑只触发一次编译。

着色器编译成功后，会出现绿色的 Shader compiled successfully 通知，并且 Kanzi Studio 会存储结果：

对于材质类型为 PBR 或 Fullscreen 的图，Kanzi Studio 会创建或更新使用所生成片段着色器的 Material Type。对于 PBR 图，Kanzi Studio 还会创建使用该 Material Type 的 Material。
提升的参数会显示为 Material Type 和 Material 上的属性。请参阅参数。