企业官网建设流程全解析

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

导读

SampleCurve 是 TiXL（t3）开源实时动态图形软件中位于Lib.numbers.curve命名空间下的一个算符（Operator），它的核心价值是在节点图（Graph）内直接开辟一个内嵌的曲线编辑器窗口，让你像编辑时间线动画曲线一样编辑一条可复用的曲线，并实时将其采样为浮点数值供其他算符驱动。阅读本文后，你将掌握 SampleCurve 的输入输出语义、完整的鼠标编辑操作、与 AnimValue 组合实现自动动画曲线的实战技巧，以及其底层GetSampledValue采样与插值机制的源码级原理。

一、SampleCurve 是什么

根据 SampleCurve 官方文档 的定义，SampleCurve 会在节点图的『graph』中创建一个窗口，窗口内是一个仅包含单条曲线的曲线编辑器。这条曲线可以在『Parameters』视图中编辑，编辑方式与标准时间线中的动画曲线完全一致。它是Lib.numbers.curve运算符库中的一员，同库还包含 CurvesToTexture（将曲线写入纹理），完整目录见 Lib.numbers.curve 索引。

从源码看，SampleCurve 是Instance<SampleCurve>的派生类，定义于 Operators/Lib/Symbols/numbers/curve/SampleCurve.cs，并配套有节点定义文件 SampleCurve.t3 与 UI 绑定文件 SampleCurve.t3ui。其 Graph 内嵌编辑器的绘制逻辑由 Editor/Gui/OpUis/UIs/SampleCurveUi.cs 实现。

二、输入参数与输出

2.1 输入参数

2.2 输出

在源码 SampleCurve.cs 中可以看到两个输入槽的声明：InputSlot<Curve> Curve与InputSlot<float> U，分别对应 GUID108CB829-5F9E-4A45-BC6B-7CF40A0A0F89和2c24d4fe-6c96-4502-bf76-dac756a16215；两个输出Slot<float> Result与Slot<Curve> CurveOutput同样以固定 GUID 注册。这些 GUID 在 SampleCurve.t3ui 中被[BindInput]/[BindOutput]特性一一对应绑定，从而将节点图 UI 与运行时算符实例连接起来。

三、曲线编辑器的完整鼠标操作

官方文档列出了曲线编辑器内的全部鼠标操作，现结合编辑器 UI 实现逐条说明：

• 左键单击：选中曲线上的点（关键帧）。
• 左键拖拽：移动选中点及其 Bezier 控制点，实时调整曲线形状与切线。
• 左键 + Alt：在曲线上创建新点（新增关键帧）。
• 右键单击：弹出选项菜单，包含额外的插值方式（Constant / Linear / Bezier / Spline）等设置。
• 右键拖拽：在曲线编辑器内部平移视图（Pan）。
• 点击左上角图标：将曲线在更大的窗口中打开，方便精细编辑。

其中「左上角图标」对应 SampleCurveUi.cs 中调用的CurveEditPopup.DrawPopupIndicator(...)——当窗口高度足够时（大于ImGui.GetFrameHeight() * UiScaleFactor * 2）会显示弹出指示图标，点击后进入放大版曲线编辑弹窗。

3.1 一个容易被忽略的 UI 细节：防滑拖拽手柄

官方文档特别提示：在节点图中选择、移动这个算符有时会比较困难。原因在于该算符的主体几乎全被曲线编辑器占据，鼠标落在曲线上会优先触发曲线编辑交互。为此，SampleCurveUi.cs 在编辑器左侧绘制了一个WidgetElements.DrawOperatorDragHandle(...)拖拽手柄（官方文档戏称其带『防滑涂层』），这一小块区域是专门用来选中与移动整个算符的。同时，编辑器默认只在按住Ctrl时才允许鼠标编辑曲线（见preventEditingUnlessCtrlPressed逻辑），这也进一步减少了误触。

四、实战技巧：用 AnimValue 驱动 U 输入

官方文档给出的 ProTip 是 SampleCurve 最常用的高级玩法：

ProTip：如果 [AnimValue] 的result输出连接到 SampleCurve 的 U 输入，你就得到了一条易于编辑的、自动动画的曲线，并且附带大量可选项。

原理拆解：

1. AnimValue 是 TiXL 中与 BPM 同步的动画值生成器（位于Lib.numbers.anim.animators.AnimValue），内置 Saws、Sine、Noise 等多种动画样式，按住 Ctrl 拖拽可调整形状。它可以在运行期间持续输出随时间变化的浮点值。
2. 将 AnimValue 的result接到 SampleCurve 的U输入后，SampleCurve 会以该动态值为采样横坐标，沿你手工绘制的曲线取到对应的纵坐标值，再从Result输出。
3. 于是，曲线的形状变成了一个可自由塑形的『响应函数』：AnimValue 负责产生周期性或随机性的输入，曲线负责把它映射成你想要的输出波形。例如把 AnimValue 设为循环锯齿波、曲线设为缓入缓出形状，即可得到平滑往复的动画值。

在 SampleCurveUi.cs 中，编辑器还会在 U 当前值对应的横坐标位置绘制一条垂直的采样指示线（DrawSamplePointIndicator），让你直观看到此刻曲线被采样到了哪里。这套『动画值 + 曲线重映射』的组合也被大量使用在 TiXL 内置示例与官方教程中（参见 Introduction.md 对 AnimValue 结合采样操作的介绍）。

五、源码级原理：Result 是怎么算出来的

5.1 算符的更新流程

SampleCurve.cs 的Update方法实现了完整的采样管线：

Result.UpdateAction += Update; CurveOutput.UpdateAction += Update;

两个输出槽共用同一个更新回调。每次求值时：

1. 若Curve输入为空则直接返回；
2. 读取U与Curve的值；
3. 将曲线原样透传给CurveOutput；
4. 调用c.GetSampledValue(u)得到采样结果，写入Result；
5. 清除两个输出槽的脏标记（DirtyFlag），完成本次求值。

5.2 Curve.GetSampledValue 的插值决策

真正执行数学计算的是 Core/DataTypes/Curve.cs 中的Curve.GetSampledValue(double u)，其算法要点如下：

• 对u做 4 位小数精度取整（TimePrecision = 4），避免浮点抖动；
• 当u小于首个关键帧时间或大于末个关键帧时间时，调用PreCurveMapper/PostCurveMapper进行越界映射（即曲线的 Pre/Post 越界策略，如 Constant 钳制、循环等），映射会同时返回新的mappedU和一个offset偏移量；
• 在区间内部，根据相邻两个关键帧（VDefinition）的插值类型，在四种插值器中择一计算：
  • Constant（OutInterpolation == Constant）→ConstInterpolator.Interpolate
  • Linear（两侧均为Linear）→LinearInterpolator.Interpolate
  • Bezier（BezierInterpolator.SegmentNeedsBezier判定为真）→BezierInterpolator.Interpolate
  • 其余情况 →SplineInterpolator.Interpolate

5.3 默认曲线：开箱即用的线性斜坡

SampleCurve.t3 中记录了该算符的默认 Curve 输入值：包含两个关键帧——Time=0, Value=0与Time=1, Value≈1，两者的InInterpolation/OutInterpolation均为Linear，PreCurve/PostCurve越界策略均为Constant。也就是说，新拖入的 SampleCurve 默认就是一条从 0 到 1 的线性斜坡，U 输入 0 时 Result 输出 0，U 输入 1 时 Result 输出 1，越界时钳制在端点值——非常适合直接作为归一化控制信号使用。

六、编辑曲线时发生了什么：UI 与数据同步

在 Parameters 视图中编辑曲线时，SampleCurveUi.cs 的工作流程如下：

1. 判断Curve输入是否连接了外部数据：若没有连接（Input.IsDefault），则编辑操作会先clone一份曲线副本（cloneIfModified），保证不污染默认值；
2. 通过CurveInputEditing.DrawCanvasForCurve(...)绘制可交互的曲线画布，接收鼠标拖拽、Alt+左键加点等编辑输入；
3. 当检测到修改标记（InputEditStateFlags.Modified）时，将编辑后的曲线写回输入槽（SetTypedInputValue），并分别对Result与CurveOutput调用DirtyFlag.Invalidate()/ForceInvalidate()，强制下游在下一帧重新求值。

这套机制保证了你每拖一下贝塞尔手柄，Result 与 CurveOutput 都会在下一次求值时立即反映最新曲线，实现所见即所得的实时预览。

七、典型使用链路小结

将以上内容串起来，SampleCurve 最典型的三种用法是：

1. 静态重映射：U 接入固定值（如 0.5），Result 输出曲线在中点的值，用于在两张纹理/两种颜色之间插值；
2. 动态动画：U 接入 AnimValue 等 BPM 同步动画值，Result 输出循环动画数值，驱动位置、缩放、透明度等任何接受浮点输入的参数；
3. 曲线透传：将 CurveOutput 连接到其他接受T3.Core.DataTypes.Curve数据的算符（例如 CurvesToTexture 将曲线写入纹理），实现曲线的渲染与复用。

由于 SampleCurve 的输入输出类型明确（float与Curve），它也是学习 TiXL 自定义算符输入输出约定（InputSlot<T>/Slot<T>与固定 GUID 注册机制）的极佳入门样例——完整定义可对照 SampleCurve.cs 与 Curve.cs 阅读。

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