Material Maker 的 sdRoundedBox 节点:二维有符号距离场圆角矩形生成详解

原创2026-10-11 22:52:581,737 阅读
文章标签:桌面应用图像处理3D建模图形学

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 节点在文档中的示意图

sdRoundedBox 节点通过 sdShow 输出的示例灰度图像

输入与输出

输入: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 轴上的位置

几点需要特别注意:

  1. 四个圆角互相独立:top_left、top_right、bottom_left、bottom_right 分别控制四个角,你可以做出"左上、右下为直角,右上、左下为大圆角"这类不对称形状,这正是 sdRoundedBox 相比单一圆角矩形的核心价值。
  2. 圆角半径的上限保护:虽然每个半径参数都允许取到 1.0,但在最终生成表达式里半径会被 min($width, $height) 钳制(详见下文),确保圆角不会互相穿透,避免出现病态几何。
  3. 中心的坐标空间: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 距离函数文章)。其推导思路如下:

  1. 按象限选取圆角半径:利用矩形在四个象限的对称性,先根据 p.x 的正负从 r.xy(右侧)与 r.zw(左侧)中选出半边,再根据 p.y 的正负从两者中选出当前象限的半径 r.x;
  2. 构造角点附近的偏移量:q = abs(p) - b + r.x,其中 abs(p) 把任意象限的点折叠到第一象限,b 为半宽半高(注意传入的是 vec2(width, height),函数内部直接当作半尺寸使用),+r.x 把圆角弧线向内收缩,使距离测量以"圆角圆心"为基准;
  3. 距离合成: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 输入,输出一张黑色背景、白色形状的灰度图像,其参数为渐变宽度(从白到黑的过渡范围)和输出基值。

推荐流程:

  1. 从节点库 Simple/SDF/Shapes 分支拖出 sdRoundedBox 节点;
  2. 调整参数,例如设置 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 中记录的默认参数组合,可直观看到"对角圆角"效果);
  3. 从 Simple/SDF/Operators 分支拖出 sdShow 节点,将 sdRoundedBox 的输出端口连接到 sdShow 的输入端口;
  4. 连接 2D 预览面板查看灰度结果,此时圆角矩形的边界会在渐变宽度内形成平滑的抗锯齿过渡;
  5. 如需让边界的过渡宽度在不同位置保持一致,可改用 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 节点输出灰度图,再进入后续材质流程。
登录后查看全文
material-maker