Material Maker sdIsoscelesTriangle 节点全解析:等腰三角形有向距离场的参数、GLSL 实现与组合用法
Material Maker sdIsoscelesTriangle 节点全解析:等腰三角形有向距离场的参数、GLSL 实现与组合用法
本篇技术指南围绕 Material Maker(基于 Godot 引擎的程序化材质与 3D 绘制工具)中 Simple/SDF/Shapes 类别下的 sdIsoscelesTriangle 节点展开,完整讲解它的节点定位、输入输出约定、四个几何参数的取值范围与控件语义,并深入其节点定义文件剖析底层 sd_isosceles_triangle GLSL 函数的有向距离场(Signed Distance Field,SDF)实现原理。读完本文,你将能够在材质图(graph)中准确摆放并参数化一个等腰三角形 SDF 形状,理解它与 sdTriangle、sdEquilateralTriangle 的区别,并掌握将其与 sdShow、布尔/圆角/重复等 SDF 运算符组合成复杂图案的实战流程。
节点定位:Simple/SDF/Shapes 家族中的等腰三角形
Material Maker 的二维 SDF 节点体系(文档见 node_simple_sdf.rst)允许用"少量基础形状 + 运算符组合"的方式定义复杂几何:基础形状节点各自输出一段有向距离函数,再通过 sdBoolean、sdMorph、sdRepeat 等运算符组合,最后经 sdShow / sdShow 2 节点转换为灰度图像输出。
sdIsoscelesTriangle 正是这批基础形状节点之一,其作用是"为等腰三角形生成一张有向距离图像"(原文档核心描述)。它在节点库中被注册为 Simple/SDF/Shapes/sdIsoscelesTriangle,对应的节点定义文件位于 sdisoscelestriangle.mmg,并在 base.json 的库条目中登记了默认实例参数。与家族中的其他三角形节点相比,它的定位非常明确:
- sdTriangle(任意三角形):通过三个顶点共六个坐标参数定义任意形状的三角形,自由度最高;
- sdEquilateralTriangle(等边三角形):只用一个半径类参数,约束三边相等;
- sdIsoscelesTriangle(等腰三角形):仅用 Width(宽)与 Height(高)两个尺寸参数即可描述"两边相等、底边居中"的对称三角形,是三者中参数语义最直观、最适合作为几何原语的形态。
输入与输出约定
sdIsoscelesTriangle 是一个"生成型"(source)节点,不接受任何输入(原文档明确说明 "does not accept any input"),这与依赖上游形状输入的 sdRoundedShape、sdAnnularShape 等算子型节点完全不同——它直接向材质图"贡献"一个形状。
其唯一输出为 Output,类型是 sdf2d(二维有向距离场)。在 sdisoscelestriangle.mmg 中,该输出被声明为:
{
"longdesc": "The isosceles triangle as a signed distance function",
"sdf2d": "sd_isosceles_triangle($uv - 0.5 + vec2(0.0, $height) - vec2($cx, $cy), vec2($width, $height * 2.0))",
"shortdesc": "Output",
"type": "sdf2d"
}
需要特别说明的是:sdf2d 类型的值在图像层面并不可直接预览——负值代表形状内部、正值代表外部、零值代表边界(等值面)。因此若想在材质图中"看到"这个三角形,必须把输出接入 sdShow(或抗边角畸变更一致的 sdShow 2)节点。根据 node_simple_sdf_operators_sdshow.rst 的说明,sdShow 会把输入的有向距离函数转换为"背景为黑、形状为白"的灰度图像,并可调节过渡带的渐变宽度(gradient width)与输出的基础值(base value),文档中所有 SDF 形状节点的示例图均是通过 sdShow 生成的。
参数详解:Width、Height 与 Center X/Y
sdIsoscelesTriangle 的全部几何都由四个参数决定。下表完整继承自 sdisoscelestriangle.mmg 的参数定义,并补充了控件、取值范围与默认值:
| 参数 | 参数名 | 控件 | 默认值 | 取值范围 | 步进 | 语义 |
|---|---|---|---|---|---|---|
| Width(宽) | width |
Rect1.x |
0.5 | 0 ~ 1 | 0.01 | 等腰三角形的底边宽度 |
| Height(高) | height |
Rect1.y |
0.5 | 0 ~ 1 | 0.01 | 等腰三角形的高度(从底边到顶点) |
| Center X | cx |
P1.x |
0 | -0.5 ~ 0.5 | 0.01 | 三角形中心在 X 轴上的位置 |
| Center Y | cy |
P1.y |
0 | -0.5 ~ 0.5 | 0.01 | 三角形中心在 Y 轴上的位置 |
使用要点:
Rect1.x/Rect1.y控件在材质图编辑器中显示为矩形的宽高调节手柄,P1.x/P1.y则是一个可拖拽的点(point),用于直观地平移三角形。Width 与 Height 的范围被限制在 0~1(相对于 UV 空间),Center 的平移范围限制在 ±0.5,这保证三角形始终位于可预览的 UV 区域内。- 库中默认实例(见 base.json)采用的初始值是
width = 0.4、height = 0.2、cx = 0.0、cy = 0.2,即一个底边略宽、位置略偏上的等腰三角形——用户从节点库拖入该节点时看到的就是这个形状。 - 若希望生成"倒置"或镜像三角形,可以结合 Simple/SDF/Transforms 类别下的
sdScale(负缩放)或sdRotate节点对输出做变换,而不必修改节点本身。
底层原理:sd_isosceles_triangle 的 GLSL 逐行拆解
sdIsoscelesTriangle 并非魔法,它最终会被编译进一段真实可运行的 GLSL 着色器代码。节点的 shader_model.global 中定义了核心距离函数(sdisoscelestriangle.mmg):
float sd_isosceles_triangle(vec2 uv, vec2 size)
{
uv.x = abs(uv.x);
uv.y += size.y; size.y *= 2.0;
vec2 a = uv - size*clamp(dot(uv,size)/dot(size,size), 0.0, 1.0);
vec2 b = uv - size*vec2(clamp(uv.x/size.x, 0.0, 1.0), 1.0);
float s = -sign(size.y);
vec2 d = min(vec2(dot(a,a), s*(uv.x*size.y-uv.y*size.x)),
vec2(dot(b,b), s*(uv.y-size.y)));
return -sqrt(d.x)*sign(d.y);
}
这段函数是 Inigo Quilez 经典二维 SDF 库中 sdIsoscelesTriangle 的适配版本——node_simple_sdf.rst 明确说明,Material Maker 的全部 SDF 节点均基于其公开代码改编。逐步理解它,就能掌握"有向距离"这一概念在三角形上的具体形态:
- 对称折叠(
uv.x = abs(uv.x)):等腰三角形关于 Y 轴左右对称,因此把采样点的 x 坐标取绝对值,将左半平面折叠到右半平面,后续只需对"半个三角形"求距离,计算量减半。 - 垂直居中(
uv.y += size.y; size.y *= 2.0):先将采样点沿 Y 轴平移一个size.y,再把高度加倍,使三角形的顶点/中心对齐到坐标系原点附近——这正是节点输出表达式里vec2(0.0, $height)平移量与vec2($width, $height * 2.0)尺寸传入量的来源。 - 两条边的候选距离(a 与 b):向量
a是采样点到"斜边所在直线"的投影差(通过dot(uv,size)/dot(size,size)做 clamp 到 [0,1] 的投影),b则是采样点到"底边所在直线"的投影差。两者分别捕捉三角形两条几何边界的距离。 - 取最近距离(
d = min(...)):把a、b的平方长度与带符号的叉积/边距组合成两个二维候选量,取最小值——即点到三角形轮廓的最近距离,其中符号位(s = -sign(size.y))用于区分点在三角形内还是外。 - 还原带符号距离(
return -sqrt(d.x)*sign(d.y)):对最近距离开平方后乘以内外符号,得到标准的有向距离值:内部为负、外部为正。
结合输出表达式(上文 JSON 中的 sdf2d 字段)可以推断出完整的坐标链路:$uv 先减去 0.5 将 UV 原点移到画布中心,再依次叠加 (0, height) 的垂直居中偏移和 (-cx, -cy) 的中心平移,最后以 vec2(width, height*2.0) 作为尺寸传入距离函数。也就是说,Width/Height 直接控制底边与高度,cx/cy 控制整个三角形在 UV 空间中的位置,边界清晰、互不耦合。
在最终生成着色器时,gen_sdf.gd 会递归调用 SDF Builder 的 scene_to_shader_model,把每个形状节点的 includes、parameters、code 与 outputs 拼接进统一的 SDF 计算代码,而 loader.gd 则负责把 .mmg 中声明的 global 函数解析为可供引用的 GLSL 前缀代码。因此用户在材质图中"连接节点"的操作,最终等价于在着色器中完成一次函数调用与变量绑定。
在 SDF Builder 中的复用:IsocelesTriangle 形状选项
除了作为独立图节点使用,sd_isosceles_triangle 函数还是 Material Maker 内置 SDF Builder(二维形状构建器)的可选形状之一。在 box.gd 中可以看到,构建器的 shape 枚举同时暴露了 Box、Rhombus、IsocelesTriangle(源码中的原始拼写)、Tunnel、Ellipse 等选项:
@export_enum("Box", "Rhombus", "IsocelesTriangle", "Tunnel", "Ellipse") var shape : int
...
const FUNCTIONS : Array = [ "sd_box", "sdRhombus", "sd_isosceles_triangle", "sdTunnel", "sd_ellipse", "sdStairs" ]
当选择 IsocelesTriangle 时,构建器通过 get_includes() 引入 rotate 与 sdisoscelestriangle 两个函数,并用 shape_code 生成 sd_isosceles_triangle(uv, vec2(size_x, size_y)) 的调用代码。这意味着你在 SDF Builder 中拖入的每个基础形状,本质上都会被展开为与独立节点完全一致的 GLSL 距离函数。形状的通用变换(位移、旋转、缩放)则由 union.gd 的 scene_to_shader_model 统一包裹:先减去 position,再按 angle 旋转、按 scale 缩放,最后把结果乘回 scale,保证形状与变换参数的一致性和可预览性。
实战:从灰度预览到组合图案
由于 sdIsoscelesTriangle 输出的是 sdf2d,一个最小可运行的材质图流程是:
- 生成:从节点库拖入
Simple/SDF/Shapes/sdIsoscelesTriangle,按需设置 Width、Height、Center X/Y; - 可视化:将其 Output 连接到
Simple/SDF/Operators/sdShow,用"渐变宽度"控制形状边缘的柔和程度(数值越大边缘越宽越柔),得到黑白灰度图; - 组合:在此基础上继续接入
sdBoolean(并/交/差)、sdRoundedShape(圆角)、sdAnnularShape(环形)、sdMorph(形状渐变)或sdRepeat/sdCircleRepeat(平铺与环形阵列)等运算符,即可用单个等腰三角形快速派生出箭头、山脊、锯齿、徽章等程序化图案; - 变换:通过
Simple/SDF/Transforms下的sdTranslate、sdRotate、sdScale调整三角形的位置、朝向与大小,实现精确排布。
图下为该节点的示例输出(同样由 sdShow 渲染,参数取自节点默认实例),直观展示了等腰三角形 SDF 经灰度化后的形态:
相关文件速查
- 节点定义(参数 + GLSL 函数):addons/material_maker/nodes/sdisoscelestriangle.mmg
- 节点库注册(默认实例参数、图标、树目录):material_maker/library/base.json
- 二维 SDF 节点体系总览:material_maker/doc/node_simple_sdf.rst
- sdShow 灰度输出节点:material_maker/doc/node_simple_sdf_operators_sdshow.rst
- SDF Builder 形状复用实现:addons/material_maker/sdf_builder/sdf2d/shapes/box.gd
- SDF 构建与着色器拼接:addons/material_maker/sdf_builder/sdf2d/boolean/union.gd、addons/material_maker/engine/nodes/gen_sdf.gd
- 节点文档示例图:node_simple_sdf_shapes_sdisoscelestriangle.png、node_sdisoscelestriangle_sample.png

