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 文件BoolValueBoolean要写入上下文的布尔值falseVariableNameString布尔变量在上下文中的键名供 GetBoolVar 等按名读取空字符串SubGraphCommand可选子图命令若连接则变量的新值仅在子图求值期间临时生效详见下文临时作用域null未连接输出参数名称类型ResultT3.Core.DataTypes.Command三、核心实现变量如何写入上下文SetBoolVar 的求值逻辑位于 SetBoolVar.cs其核心过程如下读取VariableName与BoolValue两个输入的当前值若变量名为空或为 null则调用Log.Warning输出警告Cant set variable with invalid name并直接返回不会写入任何数据若SubGraph没有连线则直接把context.BoolVariables[name] newValue写入上下文字典若SubGraph有连线则执行临时写入 → 求值子图 → 恢复旧值的三步操作见下一节。底层存储是EvaluationContext上的布尔变量字典定义于 EvaluationContext.cspublic Dictionarystring, 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动态收集变量名作为下拉选项方便你直接选择已写入的变量名减少拼写错误。六、编辑器中的自定义 UISetBoolVar 在节点图中有一个专门的自定义绘制实现 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），仅供参考
