TiXL SetBoolVar 算子详解：通过上下文变量在节点图间传递布尔状态
【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3
导读
SetBoolVar 是 TiXL 中Lib.flow.context（流程 / 上下文变量）算子族的一员，它把布尔值写入 EvaluationContext 的布尔变量字典，供图中"更靠左（更早求值）"的算子通过 GetBoolVar 读取，从而在不使用连线的情况下实现跨分支、跨子图的数据传递。本文以 .help/docs/operators/lib/flow/context/SetBoolVar.md 为基础，结合算子源码、上下文实现与编辑器 UI 代码，完整讲解它的输入输出、临时作用域语义、与 GetBoolVar 的配对用法，以及它在 TiXL 实际项目中的典型应用方式。
一、算子定位：Lib.flow.context 上下文变量族
在 TiXL 的算子库中，Lib.flow.context 目录集中了一组"读写求值上下文变量"的算子，与 SetBoolVar 同族的还包括：
- 写入类：SetBoolVar、SetFloatVar、SetIntVar、SetStringVar、SetVec3Var、SetMatrixVar、SetObjectVar 等；
- 读取类：GetBoolVar、GetFloatVar、GetIntVar、GetStringVar、GetVec3Var、GetMatrixVar、GetObjectVar、GetPosition、GetForegroundColor 等；
- 以及 ExecuteRawBufferUpdate、SetRequestedResolutionCmd 等与上下文相关的命令算子。
这些算子的共同特点是：通过共享的 EvaluationContext 传递数据，而不是通过算子输出到输入的连线。它们常用于一个算子需要把状态"告诉"图中另一个位置（尤其是结构上相距较远、连线困难的分支）的场景。
二、输入输出参数
依据关联文档中的参数表，结合 SetBoolVar.t3 中保存的默认值，SetBoolVar 的参数定义如下：
输入参数
| 名称 | 类型 | 说明 | 默认值（来自 .t3 文件） |
|---|---|---|---|
| BoolValue | Boolean | 要写入上下文的布尔值 | false |
| VariableName | String | 布尔变量在上下文中的键名，供 GetBoolVar 等按名读取 | ""（空字符串） |
| SubGraph | Command | 可选子图命令；若连接，则变量的新值仅在子图求值期间临时生效（详见下文"临时作用域"） | null（未连接） |
输出参数
| 名称 | 类型 |
|---|---|
| Result | T3.Core.DataTypes.Command |
三、核心实现：变量如何写入上下文
SetBoolVar 的求值逻辑位于 SetBoolVar.cs，其核心过程如下：
- 读取
VariableName与BoolValue两个输入的当前值； - 若变量名为空或为 null，则调用
Log.Warning输出警告Can't set variable with invalid name并直接返回，不会写入任何数据； - 若
SubGraph没有连线，则直接把context.BoolVariables[name] = newValue写入上下文字典； - 若
SubGraph有连线，则执行"临时写入 → 求值子图 → 恢复旧值"的三步操作（见下一节）。
底层存储是EvaluationContext上的布尔变量字典，定义于 EvaluationContext.cs：
public Dictionary<string, bool> BoolVariables { get; } = new();该字典在每个求值帧开始时会被清空（见 EvaluationContext.cs 中的BoolVariables.Clear()），因此上下文变量本质上是每帧重建、瞬时有效的状态，适合作为单帧内的数据传递通道，而不是跨帧持久化的存储。
四、临时作用域：SubGraph 输入的两种语义
这是 SetBoolVar 最具特色的行为。从源码可以清楚看到两种模式：
模式一：无 SubGraph —— 永久（本帧内）写入
// SubGraph 无连线时 context.BoolVariables[name] = newValue;变量直接写入上下文，图中后续（更靠左、更早求值）的 GetBoolVar 在同一帧内可以读取到该值。
模式二：有 SubGraph —— 临时写入并自动还原
// SubGraph 有连线时 var hadPreviousValue = context.BoolVariables.TryGetValue(name, out var previous); context.BoolVariables[name] = newValue; // 1. 临时写入新值 SubGraph.GetValue(context); // 2. 求值子图 if (hadPreviousValue) { context.BoolVariables[name] = previous; // 3. 恢复旧值 }具体行为是：
- 把新值写入变量；
- 求值 SubGraph 连接的命令算子；
- 若该变量原本存在旧值，则在子图求值结束后恢复旧值；若原本不存在，则保持不变（不会清理为不存在，但该值也会随帧末清空而不影响下一帧）。
这种"临时遮蔽（scoped shadowing）"语义非常适合局部覆盖场景：在子图范围内让 GetBoolVar 读到临时值，子图执行完毕后又回到原值，从而不会污染外部逻辑。
五、与 GetBoolVar 配对使用
写入之后，读取工作由 GetBoolVar.cs 完成：
var variableName = VariableName.GetValue(context); if (variableName != null && context.BoolVariables.TryGetValue(variableName, out var value)) { Result.Value = value; } else { Result.Value = FallbackDefault.GetValue(context); // 变量不存在时使用回退默认值 }要点：
- 按名读取：GetBoolVar 通过
VariableName在context.BoolVariables字典中查找；因此 SetBoolVar 与 GetBoolVar 的变量名字符串必须完全一致（注意大小写）。 - 回退默认值：若变量不存在，GetBoolVar 输出其
FallbackDefault输入的值，避免出现未定义状态。 - 方向约定：上下文变量只能在"同一帧内、求值顺序更靠后写入、更靠前读取"的方向上流动（README 中对 SetIntVar 的描述明确写着"可被图中更靠左（left in）的 GetIntVar 检索"，布尔变量同理）。这是与直接连线最大的区别，使用时需要注意求值方向。
此外，GetBoolVar 实现了ICustomDropdownHolder接口，在编辑器中会从context.BoolVariables.Keys动态收集变量名作为下拉选项，方便你直接选择已写入的变量名，减少拼写错误。
六、编辑器中的自定义 UI
SetBoolVar 在节点图中有一个专门的自定义绘制实现 SetBoolVarUi.cs：
- 节点标题显示为算子名称，未命名时显示
Set bool: <变量名>（见 SetBoolVarUi.cs），让读者在图上即可看出它操作的是哪个变量； - 节点主体会显示当前 BoolValue 的具体布尔值（
True/False，见 SetBoolVarUi.cs）； - 当鼠标悬停在节点上时，会调用
OpUi.DrawVariableReferences绘制与该变量名关联的引用连线提示，帮助你在图上快速定位配对的 GetBoolVar（见 SetBoolVarUi.cs）。
七、典型使用场景与注意事项
典型场景
- 跨分支状态同步：在并行分支中设置一个布尔开关，供图中其他位置的逻辑（如条件触发、模式切换）读取，避免拉长连线；
- 局部行为覆盖：利用 SubGraph 临时作用域，在某个子图范围内临时改变变量值，执行完毕后自动恢复，实现"上下文无关"的局部配置；
- 条件与标志位传递：与 GetBoolVar 的 FallbackDefault 配合，构造"未设置时取默认值"的安全读取逻辑。
注意事项
- 变量名不能为空，否则算子只会记录警告而不会写入；
- 变量名大小写敏感，写入端与读取端必须完全一致；
- 上下文变量每帧清空，不能当作跨帧持久化存储使用；
- 读取方向受求值顺序约束（更靠左的算子才能读到），跨帧或跨求值顺序的读取请改用其他机制；
- 同名变量重复写入会直接覆盖（字典赋值语义），后写入者生效。
八、小结
SetBoolVar 是一个实现简单但语义巧妙的上下文算子：通过EvaluationContext.BoolVariables字典完成布尔状态的跨节点传递，借助 SubGraph 输入获得"临时写入、自动还原"的局部作用域能力，并与 GetBoolVar（含动态变量名下拉与 FallbackDefault 回退）形成完整的读写闭环。理解它的临时作用域语义与求值方向约束，是正确使用 TiXL 上下文变量族的关键。
【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
