企业官网建设流程全解析

TiXL 程序化几何场 TorusSDF 完全指南：甜甜圈 SDF 的生成、渲染与空间变形

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3

本篇技术指南围绕 TiXL（实时动态图形开源创作工具）中的TorusSDF场生成节点展开，讲解如何用 4 个参数在 GPU 着色器图中生成程序化圆环（Donut）有符号距离场（SDF），并通过 RaymarchField 渲染、VisualizeFieldDistance 可视化，以及 BendField / TransformField / PolarRepeat 等空间算子进行变形。读完本文，你将掌握 TorusSDF 的距离函数数学原理、参数语义、默认值与取值范围，并能搭建一条从"场生成 → 场修改 → 光线步进渲染"的完整实战链路。

TorusSDF 是什么：在 TiXL 场渲染管线中的角色

TorusSDF 属于Lib.field.generate.sdf（有符号距离场生成）节点族，位于 .help/docs/operators/lib/field/generate/sdf/TorusSDF.md。它生成一个程序化圆环场（procedural torus field），即一个描述"空间中每一点到圆环表面的带符号距离"的标量场：

• 场内每一点输出带符号距离值：正值在圆环外部，负值在内部，0 为表面；
• 该场以T3.Core.DataTypes.ShaderGraphNode形式向下游节点输出，可被 RaymarchField 渲染为实体几何，也可被 VisualizeFieldDistance 以等高线平面方式可视化；
• 在 TiXL 中它还有一个广为人知的别名：Donut SDF（甜甜圈 SDF）。

从源码结构看，TorusSDF 继承了Instance<TorusSDF>并实现IGraphNodeOp（着色器图节点操作）与ITransformable（支持 3D Gizmo 变换）两个接口，核心实现见 Operators/Lib/Symbols/field/generate/sdf/TorusSDF.cs。作为生成类节点，它本身不绘制任何东西，而是向下游"喂"一个 SDF 描述，由渲染类节点消费——这是理解 TiXL 场管线的关键心智模型。

距离函数原理：一行 HLSL 的数学内核

TorusSDF 的全部几何语义浓缩在它注册到着色器图的全局函数fTorus中（见 TorusSDF.cs）：

float fTorus(float3 p, float radius, float thickness) { float2 q = float2(length(p.xy) - radius, p.z); return length(q) - thickness; }

逐行拆解其几何含义：

1. p.xy取采样点在圆环主轴平面（此处默认 z 为环面轴向）的投影，length(p.xy)得到该点到主轴的径向距离；
2. length(p.xy) - radius将该径向距离减去主半径radius，把坐标原点平移到"圆环骨架圆"上；
3. 与p.z（沿主轴的高度分量）组成二维向量q，再取length(q)，得到点到骨架圆的二维距离；
4. 最后减去thickness（环体粗细），得到带符号距离——这正是"圆环 = 骨架圆周围厚度为 thickness 的管子"这一几何直觉的解析表达。

在着色器装配阶段，GetPreShaderCode将该函数调用写入代码段（见 TorusSDF.cs）：

f{c}.w = fTorus(p{c}.{a} - {ShaderNode}Center.{a}, {ShaderNode}Radius, {ShaderNode}Thickness); f{c}.xyz = p.w < 0.5 ? p{c}.xyz : 1; // save local space

其中{a}由 Axis 参数决定（见下文），Center在调用前先从采样点中减去，完成对象中心平移；第二行将局部空间坐标存入f.xyz，供后续材质、法线或空间变换节点读取——这是 TiXL 场节点之间传递坐标信息的标准约定。

输入参数详解：语义、类型与默认值

TorusSDF 共暴露 4 个输入参数，与官方文档（TorusSDF.md）一致，其默认值可在符号定义文件 TorusSDF.t3 中确认：

Center（Vector3）

控制圆环在空间中的位置。在 TorusSDF.cs 中，它同时也是ITransformable.TranslationInput的实现（见 TorusSDF.cs）——这意味着你在编辑器视口中拖动 Gizmo 移动圆环时，写入的正是该输入。移动会同步反映到fTorus调用前的坐标相减，因此平移是精确的解析变换，不会引入步进伪影。

Radius 与 Thickness（Single）

两者共同决定圆环比例：Radius拉大外径、Thickness加粗管体。需要注意两者相对关系影响最终形态——当Thickness相对Radius过大时，圆环内孔会变小甚至闭合（变成近似实心球）。作为距离场，二者在概念上无硬性上限，但极端取值会改变表面曲率并影响光线步进的收敛质量，实际制作建议把两者保持在同一数量级（如 1.0 / 0.5、2.0 / 0.3）。

Axis（Int32）

圆环的朝向轴，对应源码中的私有枚举AxisTypes { X, Y, Z }（见 TorusSDF.cs）。该输入通过MappedType = typeof(AxisTypes)声明（见 TorusSDF.cs），在编辑器 UI 中表现为下拉枚举而非裸整数。

底层实现上，三个轴向对应三组坐标排列字符串（见 TorusSDF.cs）：

private readonly string[] _axisCodes0 = [ "yzx", // X 轴：主环在 yz 平面展开 "xzy", // Y 轴：主环在 xz 平面展开 "xyz", // Z 轴：主环在 xy 平面展开（默认） ];

以默认的 Z 轴（"xyz"）为例，距离计算式为fTorus(p.xyz, radius, thickness)，对应上文公式；选 Y 轴（"xzy"）时则变为fTorus(p.xzy, ...)，即把 y、z 分量交换后再套用同一公式，从而实现环面朝向切换。从代码实现看，切轴通过ShaderNode.FlagCodeChanged()触发着色器代码重编译（见 TorusSDF.cs），因此修改 Axis 后需要一次重新编译才生效——这与 BendField 文档中对 Axis 参数的提示逻辑一致。

输出：Result 节点

该输出在 TorusSDF.cs 中声明，节点构造时即与内部ShaderGraphNode绑定（见 TorusSDF.cs）。它是后续一切消费节点的入口：连入 RaymarchField 即渲染、连入 VisualizeFieldDistance 即可视化、连入各类空间修改算子即变形。

实战链路一：用 RaymarchField 渲染圆环

生成场之后，将其Result连入 RaymarchField 的SdfField（必需输入）即可得到可渲染实体。RaymarchField 会先写入正确的深度缓冲，因此输出可以与其他网格几何正确混合、遮挡（见 RaymarchField.md）。

对该节点中与圆环外观直接相关的参数，建议关注：

对纯圆环这种光滑凸形场，较小的MaxSteps即可收敛良好；若后续叠加 BendField、噪声等场，可适当增大MaxSteps、调小StepSize以保证步进不"穿透"表面。

实战链路二：用 VisualizeFieldDistance 剖析场结构

在调参阶段，可把同一份Result同时连入 VisualizeFieldDistance 的SdfField。该节点绘制一张带等高线的分析平面，平面可旋转、平移穿过你的场，用等高线密度直观展示距离场的梯度变化（见 VisualizeFieldDistance.md）。

它的输入包括Center（Vector3）、Rotation（Vector3）、Size（Vector2）以控制平面位置与范围，以及LineColor、Background（Vector4）控制显示配色，另有EnableZTest/EnableZWrite（Boolean）控制深度交互。官方文档特别指出，这一步对检查场的Lipschitz 连续性、排查 RaymarchSDF 的潜在问题非常有用——例如当你对圆环施加位移/噪声变形后，等高线间距出现明显"断裂"或骤变区域，往往预示着步进伪影会出现在那里。

实战链路三：用空间修改算子变形圆环

TorusSDF 生成的是连续标量场，天然可与其他场算子级联。官方文档明确推荐它与以下节点配合：

• BendField：沿指定轴弯曲/卷曲输入场，适用于"单位范围内的小体积源"（见 BendField.md），其Amount控制弯曲量、Axis选择弯曲轴、StepFactor调小可减少步进伪影。圆环这类自带解析公式的场叠加弯曲后形态尤为出彩（可弯成环形/波浪环）；
• TransformField：对场施加位移/旋转/缩放，实现比 Center 更灵活的坐标变换；
• PolarRepeat：极坐标重复算子，可将圆环沿圆周方向复制出多个，快速生成齿轮、链环等阵列造型。

组合方式均为"TorusSDF.Result → 空间算子.InputField → 空间算子.Result → RaymarchField.SdfField"的链式接线。注意每个修改算子都会改写距离场的 Lipschitz 常数，链条越长、变形越剧烈，越需要调大 RaymarchField 的MaxSteps并调小StepSize来维持画质。

相似节点与替代方案

在 Lib.field.generate.sdf 节点族 中，与 TorusSDF 可互为参考的节点包括：

• BoxSDF：圆角立方体场（BoxSDF.md）；
• ChainLinkSDF：链环场（ChainLinkSDF.md）；
• FractalSDF：MandelBox 分形场（FractalSDF.md）；
• CappedTorusSDF：带圆角封边的圆环场，适合需要"环面弧段"而非完整甜甜圈的造型；
• CylinderSDF、SphereSDF等基础体素场，可作为组装复杂体的积木。

如果你需要的不是程序化距离场，而是多边形网格版本的圆环（用于常规网格渲染管线、UV 贴图或与其他网格做布尔运算），请改用TorusMesh（见 TorusMesh.md）。二者的关键区别：TorusSDF 输出的是可被光线步进、可被场算子解析变形的连续场；TorusMesh 输出的是离散多边形网格。

一个最小可运行的接线示例

以默认参数快速在视口中看到"甜甜圈"：

1. 在符号库中创建TorusSDF（位于Lib.field.generate.sdf），默认配置即为主半径 1.0、管厚 0.5、中心原点的 Z 轴圆环；
2. 创建RaymarchField，将 TorusSDF 的Result连入其SdfField；
3. 运行项目，圆环即以光线步进方式渲染；如需旁路分析，再创建VisualizeFieldDistance并连接同一Result；
4. 调节Radius/Thickness观察外径与胖瘦变化，切换Axis观察朝向变化（切换后等待代码重编译）；
5. 在 TorusSDF 与 RaymarchField 之间插入BendField，调节Amount观察圆环弯曲，必要时增大MaxSteps、调小StepSize消除伪影。

小结与排查提示

• TorusSDF 是"零渲染成本"的纯描述性节点，实际开销取决于下游 RaymarchField 的步进参数与场景复杂度；
• 场变形（弯曲、重复、噪声）会破坏 Lipschitz 连续性，画质劣化时应优先调小 RaymarchField 的StepSize，其次增大MaxSteps；
• Axis改变会触发着色器重编译，若改动"没反应"，参照 BendField 的提示，可先改动其他任意参数强制刷新；
• 使用 VisualizeFieldDistance 的等高线平面快速定位距离场异常区域，是排查步进伪影位置的高效手段。

核心事实与源码依据均可在此仓库中复现：官方文档、C# 实现、符号默认值定义 以及 SDF 节点族索引。

【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3