企业官网建设流程全解析

• 音视频
• 图形学
• 桌面应用

导读

Add 是 TiXL 实时动态图形（realtime motion graphics）编辑器中Lib.numbers.float.basic（浮点数基础运算）算子库最常用的两个浮点值相加算子。本文以官方算子文档为主体，结合仓库内该算子的 C# 源码与符号定义文件，完整解析其输入输出契约、底层求值逻辑、默认值与 UI 配置，并给出在节点图与表达式中的典型接线方式；同时对比多输入场景下的 Sum 算子，帮助你在构建参数化动画、偏移量与数据驱动控制时做出正确选择。读完本文，你将能够熟练使用 Add 算子并理解其与 Sum、Sub、Multiply 等基础浮点算子的协作模式。

一、算子定位：在浮点基础运算家族中的角色

Add 属于 TiXL 算子库Lib.numbers.float.basic分类，该分类下共有 9 个基础浮点运算算子，分类索引 中逐一列出：

官方文档指出："Adds two float values and outputs the result as a float"。它是节点图中最基础、最常用的数学运算之一：凡是需要把两个浮点信号叠加的场景——例如把"基础数值"与"动态偏移量"相加、把两条控制曲线求和、或把时间参数与相位偏移组合——都可以用 Add 完成。该分类下的索引文件末尾注明"Auto-generated from the operator library."，即算子文档由库自动生成，反映的是算子符号的真实契约。

二、输入输出契约：从文档到源码的双重印证

2.1 输入参数（Input Parameters）

文档给出的输入参数表如下：

两个输入的类型均为浮点（float，.NET 中对应System.Single）。其中Input1被标记为 "Single Relevant"，表示在 UI 中它属于高相关度（Relevant）输入；从符号 UI 配置 Add.t3ui 可以看到：

• Input1（Guide3550929-8905-4cdf-bc85-c31e97da4baa）设置"Relevancy": "Relevant"，即默认展开显示为高相关度输入；
• Input2（Guid993d59bb-1fc0-4857-a36d-629b0e7aa0d2）未标记 Relevant，属于常规输入，需要时可在参数面板中展开。

两者的 UI 数值范围（Min/Max）均配置为-100.0 ~ 100.0，其中Input2还额外带有"Scale": 0.01的滑杆缩放，适用于精细微调。

2.2 输出（Outputs）

文档给出的输出表如下：

输出类型为System.Single（即 C# 中的float），与两个输入的类型一致，因此 Add 可以无缝串接其他浮点算子。

2.3 源码级印证

算子源码位于 Add.cs，完整呈现了上述契约：

namespace Lib.numbers.@float.basic; [Guid("c160f925-0a66-4505-a569-cadd878dbb6f")] internal sealed class Add : Instance<Add> { [Output(Guid = "{5CE9C625-F890-4620-9747-C98EAB4B9447}")] public readonly Slot<float> Result = new(); public Add() { Result.UpdateAction += Update; } private void Update(EvaluationContext context) { Result.Value = Input1.GetValue(context) + Input2.GetValue(context); } [Input(Guid = "{E3550929-8905-4CDF-BC85-C31E97DA4BAA}")] public readonly InputSlot<float> Input1 = new(); [Input(Guid = "{993D59BB-1FC0-4857-A36D-629B0E7AA0D2}")] public readonly InputSlot<float> Input2 = new(); }

值得注意的源码细节：

1. 求值逻辑只有一行：Result.Value = Input1.GetValue(context) + Input2.GetValue(context);，即输出始终等于两个输入当前值的直接和。
2. 输出类型：Slot<float>对应文档中的System.Single，[Output]特性中的 Guid{5CE9C625-...}与符号 UI 文件中的输出 Ui 一一对应。
3. 输入槽位：InputSlot<float>是 TiXL 的标准浮点输入槽，其取值逻辑见 Core 的 InputSlot.cs：当输入没有连接外部信号且未做动画时，InputUpdate直接使用默认值；当存在连接或动画时，GetValue(context)返回上游求值结果。这意味着 Add 既可以接收来自其他算子的动态信号，也可以直接使用面板上的常量数值。
4. 源码中还保留了被注释掉的Input3/Input4扩展痕迹，说明该算子的设计定位就是"两数相加"，需要更多输入时官方推荐改用 Sum 算子（见下文）。

2.4 符号定义与默认值

算子的默认状态保存在符号定义文件 Add.t3（FormatVersion 3）中：

{ "FormatVersion": 3, "Id": "c160f925-0a66-4505-a569-cadd878dbb6f"/*Add*/, "Inputs": [ { "Id": "993d59bb-1fc0-4857-a36d-629b0e7aa0d2"/*Input2*/, "DefaultValue": 0.0 }, { "Id": "e3550929-8905-4cdf-bc85-c31e97da4baa"/*Input1*/, "DefaultValue": 0.0 } ], "Children": [], "Connections": [] }

两个输入的默认值均为0.0，因此在未接线、未改参数时，Add 的 Result 输出恒为0.0（0.0 + 0.0）。任何一端输入改变，输出立即随之变化。

三、典型实战用法

3.1 静态常量相加

直接在参数面板中给Input1与Input2输入数值，例如1.5与2.5，Result 输出4.0。这是 Add 最直观的用法，适合做常量运算或把多个偏移量合并成单一数值再馈入下游算子。

3.2 动态信号叠加（最常用）

把上游算子的动态输出接入 Add 的任一输入，即可实现信号叠加。典型场景包括：

• 基础值 + 动态偏移：把一个固定数值（如位置基准）与一个随时间变化的偏移（如正弦振荡、Noise 输出）相加，产生"基准 + 扰动"的复合控制信号；
• 曲线求和：把两条浮点曲线（例如通过 Curve 算子或动画曲线得到的信号）相加，得到叠加后的新曲线；
• 时间参数偏移：把时间（Time）与相位偏移相加，驱动动画错峰播放。

Add 的输出System.Single可以直接接入 Transform、Color、参数化材质等任何接受浮点输入的算子，实现数据驱动。

3.3 数值范围平移

利用"加常量"可以平移数值范围：若某个信号取值在-0.5 ~ 0.5，通过 Add 加上0.5即可平移到0.0 ~ 1.0，便于后续接入百分比类参数或映射算子。

四、与 Sum 算子及兄弟算子的协作

文档特别提示："If more values are to be added, there is also Sum"。当需要相加的浮点数量超过两个（或数量不固定）时，应改用 Sum 算子：

• Sum 支持多输入：其源码 Sum.cs 使用MultiInputSlot<float> InputValues，可任意连接多个浮点信号，循环累加全部已连接输入：

Result.Value = 0; var connectedCount = 0; foreach (var input in InputValues.GetCollectedTypedInputs()) { Result.Value += input.GetValue(context); connectedCount++; } if (connectedCount == 0) { Result.Value = InputValues.GetValue(context); }

即：有一个或多个输入连接时输出它们的总和；没有任何连接时回退到 InputValues 自身的值。

• 选择建议：固定两个输入用 Add（输入更清晰、默认值显式可见）；两个以上或数量可变的输入用 Sum。此外，同分类下的 Sub（减法）、Multiply（乘法）可与 Add 组合成(a + b) * c这类复合表达式，覆盖大部分数值处理需求。

五、类型与实现原理小结

Add 的求值采用 TiXL 的依赖驱动（dirty-flag）机制：Result.UpdateAction注册到输出槽上，仅当上游输入变化（dirty）时才会重新执行Input1 + Input2，避免每帧无谓的重复计算；而输入槽的默认值回退逻辑在 Core/Operator/Slots/InputSlot.cs 中实现（Input.IsDefault ? TypedDefaultValue.Value : TypedInputValue.Value）。这意味着把 Add 放入高帧率渲染管线中，其计算开销几乎可以忽略。

六、快速查阅指引

• 官方算子文档：Add.md（本文主体来源）
• 算子源码：Add.cs
• 符号定义：Add.t3
• 界面配置：Add.t3ui
• 同分类算子：见 Lib.numbers.float.basic 索引；多输入求和请参考 Sum.md

掌握 Add 之后，配合 Multiply、Sub、Modulo 等基础算子，即可在 TiXL 中搭建从简单数值运算到复杂参数化动画的完整信号链。

• 音视频
• 图形学
• 桌面应用