t3（TiXL）DefineGradient 操作符完全指南：从四色控制点到可动画渐变

t3TiXLDefineGradient 操作符完全指南从四色控制点到可动画渐变【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3本文以 t3TiXL开源实时动态图形软件Lib 库中numbers/color分类下的 DefineGradient 操作符为对象完整讲解其输入参数、位置过滤规则、五种插值模式、底层Gradient数据结构及与下游操作符GradientsToTexture、SampleGradient 等的组合用法。读完本文你将能直接用 DefineGradient 搭建可动画的渐变并在 BuildGradient、SampleGradient 之间做出正确的选型。一、DefineGradient 是什么DefineGradient 是 t3 的 Lib 操作符库中用于从一组颜色和位置定义渐变的节点属于 Lib.numbers.color 家族。它的典型用途是快速搭建固定 4 个控制点的颜色渐变将位置参数如 Color1Pos、Color2Pos与动画曲线或音频驱动相连实现渐变动画把输出渐变交给 SampleGradient、GradientsToTexture 等下游操作符采样成颜色或纹理。该节点由项目自带符号 DefineGradient.t3 及对应实现 DefineGradient.cs 承载内部逻辑并不复杂读取 4 组「颜色 位置」输入过滤掉范围外的位置写入一个T3.Core.DataTypes.Gradient结构并输出。二、输入参数与默认值原文档给出了完整的输入参数表结合 DefineGradient.t3 中的DefaultValue与 DefineGradient.t3ui 中的 UI 范围约束可以得到下表名称类型说明默认值UI 约束Color1Vector4第 1 个控制点颜色RGBA各分量 0–1近黑约 0,0,0,1Min 0.0 / Max 1.0Color1PosSingle第 1 个控制点位置0.0Min -0.001 / Max 1.0ClampMin/ClampMaxScale 0.001Color2Vector4第 2 个控制点颜色白色1,1,1,1Min 0.0 / Max 1.0Color2PosSingle第 2 个控制点位置1.0同上位置约束Color3Vector4第 3 个控制点颜色品红透明1,0,1,0Min 0.0 / Max 1.0Color3PosSingle第 3 个控制点位置-1.0同上位置约束Color4Vector4第 4 个控制点颜色品红透明1,0,1,0Min 0.0 / Max 1.0Color4PosSingle第 4 个控制点位置-1.0同上位置约束InterpolationInt32控制点之间的插值模式0Linear下拉枚举几个值得注意的默认值设计Color1Pos0、Color2Pos1开箱即用就是一条「黑→白」的完整渐变Color3Pos、Color4Pos 默认为 -1.0位置落在 0…1 之外会被忽略相当于默认只启用了前两个控制点。需要更多颜色时把对应 Pos 拖回 [0,1] 区间即可Color3/Color4 默认是透明度为 0 的品红即便误启用了位置也不会立刻破坏画面品红常用于 t3 中的「空值/占位」提示色。UI 层的Scale0.001 与 0.01决定拖动位置滑杆的精细程度位置输入在编辑器中被钳制在 -0.001…1.0 之间其中-1 这类负值是「停用该控制点」的惯用手法。三、位置过滤与回退逻辑0…1 之外被忽略的底层实现原文档明确写道Positions outside the range of 0 ... 1 will be ignored.在 DefineGradient.cs 的Update方法中可以看到完整实现private void Update(EvaluationContext context) { _gradient.Steps.Clear(); foreach (var slots in _slots) { var pos slots.PositionSlot.GetValue(context); if (pos 0) continue; _gradient.Steps.Add(new Gradient.Step { NormalizedPosition pos, Color slots.ColorSlot.GetValue(context), Id slots.PositionSlot.Id }); } if (_gradient.Steps.Count 0) { _gradient.Steps.Add(new Gradient.Step { NormalizedPosition 0, Color Color1.GetValue(context), Id Color1Pos.Id }); } _gradient.SortHandles(); _gradient.Interpolation (Gradient.Interpolations)Interpolation.GetValue(context); OutGradient.Value _gradient; }由此可以确认三个实现细节过滤条件实际是pos 0即跳过等价于文档所述范围过滤的工程实现。也就是说位置输入为负数时该控制点不参与构建回退保护若 4 个位置全部被忽略Steps 为空节点会自动用 Color1 在位置 0 处兜底保证输出永远是「非空」的渐变避免下游节点拿到空结构_gradient.SortHandles()会对 Step 按NormalizedPosition升序排序见 Gradient.cs因此即使你输入的位置乱序如 Color2Pos0.2、Color1Pos0.8输出也是按位置有序的合法渐变。4 对输入的组织方式实现中用了一个Pair内部类把颜色槽与位置槽绑定private class Pair { public InputSlotfloat PositionSlot; public InputSlotVector4 ColorSlot; }构造时以new() {PositionSlot Color1Pos, ColorSlot Color1}等 4 组依次注册Update中遍历该列表统一处理。这也解释了为什么每个颜色输入都严格对应一个同编号的位置输入——两者必须成对使用。四、Interpolation五种插值模式详解Interpolation 输入Int32通过MappedType typeof(Gradient.Interpolations)映射为枚举见 DefineGradient.cs。枚举定义在 Gradient.cspublic enum Interpolations { Linear, Hold, Smooth, OkLab, Spline, }值模式行为说明0Linear两控制点之间使用Vector4.Lerp线性过渡RGBA 各通道独立线性变化1Hold保持上一控制点颜色直到下一控制点形成阶梯式色块2Smooth对归一化位置先施加MathUtils.SmootherStep(0, 1, fraction)过渡两端平滑缓入缓出3OkLab使用 OkLab 色彩空间插值OkLab.Mix过渡更符合人眼感知并对结果做了非负截断4Spline使用 Catmull-Rom 样条在 RGBA 四个通道上分别插值可产生过冲/曲线过渡对应的采样逻辑集中在 Gradient.cs 的Sample(float t)t首先被Clamp(0, 1)限制到渐变有效区间Hold直接返回previousStep.ColorLinear/Smooth走Vector4.LerpSmooth 先经SmootherStep改写 fractionOkLab走感知均匀色彩空间插值Spline则委托给SampleSpline——内部按 Step 的 hash 缓存 4 条CubicSpline分别对应 R/G/B/A仅当渐变内容变化GetHashCode()改变时才重建样条避免每帧重复计算见 Gradient.cs。注意Spline 模式对 RGB 通道做了MathF.Max(..., 0)下限截断、对 Alpha 通道做了 0–1 钳制防止样条过冲产生负色或非法透明度。实践建议颜色过渡要求自然、无偏色时优先 OkLab需要「闪变」效果用 Hold需要柔和过门用 Smooth追求曲线型色彩运动用 Spline其余常规场景用 Linear 即可。Interpolation 本身也是可动画输入可以在演出中途切换插值风格。五、输出 OutGradient 与底层数据结构唯一输出OutGradient的类型是T3.Core.DataTypes.Gradient对应输出槽定义见 DefineGradient.cs。Gradient类Gradient.cs的核心成员ListStep Steps控制点列表每个Step由NormalizedPosition0–1 归一化位置、ColorVector4与IdGuid用于序列化与编辑跟踪构成Interpolations Interpolation当前插值模式Sample(float t)在任意归一化位置取样颜色Write/Read支持把渐变序列化为 JSONStep 的 Id、NormalizedPosition、Color 的 R/G/B/A 字段因此渐变可以作为项目文件持久化保存SortHandles()、TypedClone()排序与深拷贝辅助。与 GradientEditor 的配合Gradient实现了IEditableInputType因此它可以直接出现在节点参数面板的渐变编辑器里。t3 编辑器中的 GradientEditor.cs 负责可视化编辑 Steps——左键点击添加采样点、向下拖拽删除采样点右键可切换插值模式SampleGradient 文档也描述了这套交互见 SampleGradient.md。这意味着你既可以完全用节点参数「手写」DefineGradient 的 4 组颜色/位置也可以把它输出的渐变交给其他带渐变编辑器的节点继续精修。六、典型组合把渐变用起来DefineGradient 输出的Gradient自身不直接产生图像需要下游节点消费SampleGradientSampleGradient.md通过SamplePos在渐变上取样输出单一ColorVector4适合做「沿渐变取色」——例如用位置参数做动画让某个物体的颜色随时间在渐变上游走GradientsToTextureGradientsToTexture.cs把渐变按Resolution采样成一维/二维纹理支持 Horizontal/Vertical 方向供 Shader 或其他纹理操作符使用。其实现遍历每个采样点调用gradient?.Sample(t)并写入R32G32B32A32_Float格式纹理采样分辨率被钳制在 1–16384 之间BlendGradients见 color 目录 README对两个渐变做混合常与多个 DefineGradient 配合实现渐变间的平滑过渡。一个典型的「渐变动画」链路是DefineGradient ── OutGradient ── SampleGradient ── Color驱动物体/粒子颜色 ↑ 把 Color1Pos/Color2Pos 接到动画曲线或 BPM 驱动值位置参数接到随时间变化的信号例如 BpmProvider 提供的节拍相位或任意动画曲线即可让渐变控制点来回移动形成流动的色彩。七、何时改用 BuildGradient原文档明确提示Consider using BuildGradient for a more flexible solution.两者的取舍如下维度DefineGradientBuildGradientBuildGradient.cs控制点数量固定 4 个Color1–4任意数量由Colors/Positions列表决定输入形态标量槽逐一接线列表输入ListVector4Listfloat可接其他节点生成的数据空位置列表回退到 Color10自动按索引均分生成 0–1 归一化位置适用场景少量控制点、手工接线、快速原型动态生成/数据驱动的渐变如从表格、音频分析结果构造如果渐变控制点数量在演出中会动态变化或需要程序化生成例如从 DataSet 读取色表请用 BuildGradient如果只是固定 2–4 个颜色的静态/动画渐变DefineGradient 更直接、接线更少。八、小结DefineGradient 用 4 组「颜色 位置」定义渐变位置在 0…1 之外实现上为负值的控制点会被忽略全部忽略时自动回退到 Color10默认只启用 Color1Pos0 与 Color2Pos1 两个控制点形成黑→白渐变Color3/Color4 需自行把位置拖回有效区间启用Interpolation 提供 Linear/Hold/Smooth/OkLab/Spline 五种模式对应Gradient.Sample()中的不同插值路径其中 OkLab 感知更自然、Spline 支持曲线过冲输出T3.Core.DataTypes.Gradient可被 SampleGradient 采样成颜色、被 GradientsToTexture 转成纹理、被 BlendGradients 混合并支持 JSON 持久化控制点数量需要动态变化或数据驱动时改用 BuildGradient 是更灵活的选择。相关文件索引操作符文档 DefineGradient.md、实现 DefineGradient.cs、符号默认值 DefineGradient.t3、UI 配置 DefineGradient.t3ui、数据结构 Gradient.cs、对比参考 BuildGradient.cs 与 GradientsToTexture.cs。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考