Material Maker 的 sdRoundedBox 节点:二维有符号距离场圆角矩形生成详解
Material Maker 的 sdRoundedBox 节点:二维有符号距离场圆角矩形生成详解
sdRoundedBox 是 Material Maker 内置的二维 SDF(Signed Distance Function,有符号距离函数)形状节点,它通过一段精巧的 GLSL 函数在片元着色器中计算"点到圆角矩形边界的带符号距离",从而生成可无缝接入布尔运算、形态变换与可视化管线的圆角矩形几何体。读完本文,你将掌握 sdRoundedBox 的 8 个参数(含默认值与取值范围)、其底层距离函数的数学原理,以及如何配合 sdShow 节点将距离场渲染为可用的灰度贴图。
sdRoundedBox 节点是什么
在 Material Maker 的"Easy SDF"体系中(详见 node_simple_sdf.rst),所有二维 SDF 节点都基于一组非常精简的基础形状,这些形状可以通过运算类节点(布尔、平滑布尔、圆化、形态学变换等)组合出复杂几何,最终由 sdShow 节点输出为灰度图像。
sdRoundedBox 就是这组基础形状中的一员,它专门用于描述"四角可独立控制圆角半径的矩形"。与普通矩形(sdBox)不同,它的四个角可以分别设置不同的圆角半径,且支持整体平移,因此在制作圆角面板、胶囊形按钮、圆角边框等素材时非常灵活。
从节点的官方定义文件可以看到,它的 longdesc 为 "A rounded box described as a signed distance function"(以有符号距离函数描述的圆角矩形),类型为 shader,节点名为 sdRoundedBox。
输入与输出
输入:sdRoundedBox 节点不接受任何输入端口。它完全由自身参数驱动,不依赖上游节点的数据流。
输出:节点输出一个类型为 sdf2d 的单端口信号,即二维有符号距离函数。根据 gen_sdf.gd 的引擎逻辑,SDF2D 场景中每个形状节点的输出字段为 sdf2d,其值代表"某点到形状边界的带符号距离":
- 距离值为负 → 点在形状内部;
- 距离值为正 → 点在形状外部;
- 距离值为零 → 点恰好位于边界上。
这种连续的标量场正是 SDF 体系能够实现平滑布尔、圆角、形态学腐蚀/膨胀等操作的基础。
参数详解
sdRoundedBox 共暴露 8 个浮点参数,完整定义见 sdroundedbox.mmg:
| 参数名 | 界面标签 | 默认值 | 取值范围 | 步长 | 说明 |
|---|---|---|---|---|---|
width |
Width | 0.4 | 0.0 ~ 1.0 | 0.01 | 圆角矩形的宽度 |
height |
Height | 0.25 | 0.0 ~ 1.0 | 0.01 | 圆角矩形的高度 |
top_left |
3: | 0.0 | 0.0 ~ 1.0 | 0.01 | 左上角圆角半径 |
top_right |
3: | 0.2 | 0.0 ~ 1.0 | 0.01 | 右上角圆角半径 |
bottom_left |
4: | 0.2 | 0.0 ~ 1.0 | 0.01 | 左下角圆角半径 |
bottom_right |
4: | 0.0 | 0.0 ~ 1.0 | 0.01 | 右下角圆角半径 |
center_x |
Center X | 0.0 | -0.5 ~ 0.5 | 0.01 | 中心在 X 轴上的位置 |
center_y |
Center Y | 0.0 | -0.5 ~ 0.5 | 0.01 | 中心在 Y 轴上的位置 |
几点需要特别注意:
- 四个圆角互相独立:
top_left、top_right、bottom_left、bottom_right分别控制四个角,你可以做出"左上、右下为直角,右上、左下为大圆角"这类不对称形状,这正是 sdRoundedBox 相比单一圆角矩形的核心价值。 - 圆角半径的上限保护:虽然每个半径参数都允许取到 1.0,但在最终生成表达式里半径会被
min($width, $height)钳制(详见下文),确保圆角不会互相穿透,避免出现病态几何。 - 中心的坐标空间:
center_x、center_y的取值被限制在 -0.5 ~ 0.5 之间,因为 SDF 计算发生在归一化的 UV 坐标系内(详见"坐标空间与平移"一节)。
底层实现:GLSL 距离函数源码解析
sdRoundedBox 的核心是一个写在节点 shader_model.global 字段里的 GLSL 函数(见 sdroundedbox.mmg):
float sdRoundedBox( in vec2 p, in vec2 b, in vec4 r )
{
r.xy = (p.x>0.0)?r.xy : r.zw;
r.x = (p.y>0.0)?r.x : r.y;
vec2 q = abs(p)-b+r.x;
return min(max(q.x,q.y),0.0) + length(max(q,0.0)) - r.x;
}
该函数是典型的 Inigo Quilez 风格 SDF 实现(Material Maker 文档 node_simple_sdf.rst 明确说明所有 SDF 节点基于 Inigo Quilez 公开的 2D 距离函数文章)。其推导思路如下:
- 按象限选取圆角半径:利用矩形在四个象限的对称性,先根据
p.x的正负从r.xy(右侧)与r.zw(左侧)中选出半边,再根据p.y的正负从两者中选出当前象限的半径r.x; - 构造角点附近的偏移量:
q = abs(p) - b + r.x,其中abs(p)把任意象限的点折叠到第一象限,b为半宽半高(注意传入的是vec2(width, height),函数内部直接当作半尺寸使用),+r.x把圆角弧线向内收缩,使距离测量以"圆角圆心"为基准; - 距离合成:
min(max(q.x,q.y),0.0)得到矩形内部区域的负距离(表示在边界内部),length(max(q,0.0))得到边界外的欧氏距离,两者相加再减去r.x,最终还原出到真实边界(含圆弧)的带符号距离。
节点的输出表达式(见 sdroundedbox.mmg)则负责把参数拼装进调用:
sdRoundedBox($uv-0.5-vec2($center_x, $center_y), vec2($width, $height), min(vec4($bottom_right, $top_right, $bottom_left, $top_left), min($width, $height)))
这里有两个值得注意的细节:
- 四个半径的打包顺序:
vec4($bottom_right, $top_right, $bottom_left, $top_left)严格对应函数体内r.xy(右/左)与r.x/r.y(上/下)的选取逻辑,任何顺序错乱都会导致圆角出现在错误的位置; - 半径钳制:整个
vec4与min($width, $height)做逐分量取小,保证任意圆角半径不会超过矩形的半宽或半高,从数学上杜绝了圆角交叉重叠的异常形状。
坐标空间与中心平移
Material Maker 的二维 SDF 形状节点工作在归一化 UV 空间。从 gen_sdf.gd 可以看到,SDF2D 场景生成距离函数时统一执行 uv = "$uv-vec2(0.5)",即先把 UV 从 [0,1] 区间平移到中心为原点的 [-0.5, 0.5] 区间。
sdRoundedBox 的输出表达式在此基础上又减去了 vec2($center_x, $center_y),因此:
center_x、center_y为 0 时,矩形中心与画布中心对齐;- 取值范围限定在 -0.5 ~ 0.5,正好把矩形中心限制在画布内部;
- 该平移发生在距离计算之前,属于对几何体的刚性变换,不影响圆角半径和尺寸的语义。
节点在库中的注册与加载机制
sdRoundedBox 并不是硬编码在引擎里的特殊节点,而是和其他所有 SDF 节点一样,以 .mmg(Material Maker Generator)JSON 文件的形式存放于 addons/material_maker/nodes/ 目录,其中就包括本文主角 sdroundedbox.mmg。
加载流程由 loader.gd 负责:get_predefined_generators_from_dir 会遍历该目录,读取每个 .mmg 文件并解析其中的 shader_model(含 global 代码段),注册进 predefined_generators 字典;之后无论是拖拽创建节点还是打开已有工程,都从这个注册表按 type 字段实例化。
同时,节点还注册在基础节点库中,其 tree_item 路径为 Simple/SDF/Shapes/sdRoundedBox,display_name 为 sdRoundedBox,并带有内置的 48x48 图标数据。这意味着你在 Material Maker 的节点库面板中,可以沿 Simple → SDF → Shapes 分支直接找到并拖出该节点。
实战:生成圆角矩形并输出为灰度图
由于 sdRoundedBox 的输出是距离场而不是图像,要"看到"结果,必须配合 sdShow(或 sdShow 2)节点。根据 sdShow 节点文档,它接收 sdf2d 输入,输出一张黑色背景、白色形状的灰度图像,其参数为渐变宽度(从白到黑的过渡范围)和输出基值。
推荐流程:
- 从节点库 Simple/SDF/Shapes 分支拖出
sdRoundedBox节点; - 调整参数,例如设置 Width = 0.4、Height = 0.25、Top Left = 0.0、Top Right = 0.2、Bottom Left = 0.2、Bottom Right = 0.0(这也是 sdroundedbox.mmg 与 base.json 中记录的默认参数组合,可直观看到"对角圆角"效果);
- 从 Simple/SDF/Operators 分支拖出
sdShow节点,将 sdRoundedBox 的输出端口连接到 sdShow 的输入端口; - 连接 2D 预览面板查看灰度结果,此时圆角矩形的边界会在渐变宽度内形成平滑的抗锯齿过渡;
- 如需让边界的过渡宽度在不同位置保持一致,可改用 sdShow 2 节点,它会修正被扭曲的距离值,生成更均匀的倒角宽度。
得到灰度图之后,你还可以继续把它接入形态学(morphology)、扭曲(warp)等变换节点,或作为遮罩与其他纹理混合,从而把几何距离场转变成可复用的材质元素。
小结
- sdRoundedBox 是一个无输入、单
sdf2d输出的基础形状节点,用 8 个参数(宽、高、四角独立半径、中心 X/Y)完整描述一个圆角矩形; - 其底层基于 Inigo Quilez 的经典圆角矩形距离函数,通过象限对称折叠与
min/max/length组合一次性求出带符号距离; - 四个圆角半径相互独立,且输出表达式用
min($width, $height)对半径做钳制,避免病态几何; - 节点以
.mmg文件注册,加载、实例化均由引擎的loader.gd统一管理,并可沿Simple/SDF/Shapes库路径直接拖放使用; - 要可视化或利用该距离场,需搭配 sdShow / sdShow 2 节点输出灰度图,再进入后续材质流程。

