TiXL Lib.flow.context 上下文变量操作符完全指南在节点图中传递数据与渲染状态【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3TiXLt3是一套用于实时动态图形创作的节点式操作符系统Lib.flow.context是其中负责跨节点传递数据与渲染状态的核心命名空间。本指南以 Lib.flow.context 官方索引 为骨架逐一讲解其全部操作符的输入/输出参数、底层存储机制与典型用法并结合 EvaluationContext.cs 等源码揭示其工作原理。读完本指南你将掌握如何用 Set/Get 变量操作符在图中向前方节点传递状态如何配合Loop遍历生成以及如何利用GetPosition、SetRequestedResolutionCmd等操作符访问渲染上下文。一、Lib.flow.context 是什么Lib.flow.context是 TiXL 操作符库Operators/Lib/Symbols/flow/context/中的一个命名空间包含 20 个操作符按功能可分为三类类别操作符作用变量写入SetFloatVar、SetIntVar、SetBoolVar、SetStringVar、SetVec3Var、SetMatrixVar、SetObjectVar向求值上下文EvaluationContext写入一个命名变量变量读取GetFloatVar、GetIntVar、GetBoolVar、GetStringVar、GetVec3Var、GetMatrixVar、GetObjectVar从上下文中按名字取出变量未命中时返回 Fallback 默认值上下文查询/控制GetPosition、GetForegroundColor、SetRequestedResolutionCmd、ExecuteRawBufferUpdate读取/修改渲染上下文中的变换、颜色、分辨率等状态补充在源码目录 Operators/Lib/Symbols/flow/context/ 中还存在 README 索引未列出的 GetVec2Var.cs 与 SetVec2Var.cs机制与 Vec3 版本一致。需要说明的是这些 Markdown 参考页是由 TiXL 编辑器内的操作符描述自动生成的根据 操作符参考说明在编辑器主菜单执行Documentation → Export as WIKI即可重新生成整个参考树因此操作符描述 → 文档始终保持同步本指南中的参数表即来自这些自动生成页面。二、数据模型EvaluationContext 中的上下文变量字典Lib.flow.context的一切读写都围绕 EvaluationContext.cs 中的几个字典展开见#region context variables约 第 156 行字典键类型值类型对应的 Set/Get 操作符FloatVariablesstringfloatSetFloatVar / GetFloatVarIntVariablesstringintSetIntVar / GetIntVarBoolVariablesstringboolSetBoolVar / GetBoolVarStringVariablesstringstringSetStringVar / GetStringVarObjectVariablesstringobjectSetObjectVar / GetObjectVarVec3 / Matrix / Vec2 变量也存入此字典从源码可以看到EvaluationContext.Reset()会在每帧求值开始前清空这些字典FloatVariables.Clear()等见 EvaluationContext.cs 第 51 行这意味着上下文变量默认是每帧重建的谁在上游图中左侧写入下游右侧就能在同一帧内读到而跨帧持久化则需要依赖ClearAfterExecution等机制或循环结构。除变量字典外EvaluationContext还承载着渲染状态ForegroundColor、BackgroundColor、RequestedResolution以及三个变换矩阵ObjectToWorld、WorldToCamera、CameraToClipSpace第 121-125 行它们分别被GetForegroundColor、SetRequestedResolutionCmd和GetPosition使用。三、Set 系列操作符写入变量的完整语义3.1 SetFloatVarSetFloatVar.md 定义的参数为参数类型说明FloatValueSingle要写入的浮点值VariableNameString变量名供下游 GetFloatVar 引用SubGraphCommand可选子图用于在临时变量作用域内执行一段命令ClearAfterExecutionBoolean子图执行结束后是否清除该变量其实现 SetFloatVar.cs 揭示了两种关键行为无效名保护若VariableName为空则输出警告Cant set variable with invalid name {name}并直接返回第 20-24 行。压栈式临时变量当SubGraph有输入连接时先把新值写入context.FloatVariables[name]执行子图随后恢复之前的值若原本存在或按ClearAfterExecution决定是否移除若原本不存在见 第 26-45 行。这提供了类似编程语言中块作用域局部变量的语义非常适合在不污染全局命名空间的前提下临时覆盖变量。无子图时的持久写入当SubGraph未连接时直接context.FloatVariables[name] newValue变量会一直保留到上下文重置。3.2 SetIntVarSetIntVar.md 声明Sets or overwrites an int variable that can be retrieved by [GetIntVar] further down (left in) the graph——即写入后图中左侧更早执行的 GetIntVar就能读到该值。其参数包括参数类型说明SubGraphCommand可选子图压栈作用域VariableNameString变量名ValueInt32要写入的整数LogLevelInt32日志级别枚举见下文ClearAfterExecutionBoolean是否在子图结束后清除与 Float 版本相比SetIntVar 多了LogLevel参数。从 SetIntVar.cs 的私有枚举可见其取值第 82 行附近枚举值语义None不输出日志Warnings仅警告如无效变量名Changes在变量值被修改时输出Changing {name} from {previous} - {newValue}AllUpdates所有写入都输出Setting {name} to {newValue}3.3 SetBoolVar / SetStringVar / SetVec3Var / SetObjectVarSetBoolVar.md输入BoolValue(Boolean)、VariableName(String)、SubGraph(Command)输出Command。SetStringVar.md输入StringValue、VariableName、SubGraph、ClearAfterExecution。其文档描述中writes a string value to the contextsfloatvariable dictionary是自动生成时的笔误源码 SetStringVar.cs 实际操作的是context.StringVariables字典。SetVec3Var.md输入Vec3Value(Vector3)、VariableName、SubGraph输出Command。从 SetVec3Var.cs 看Vec3 值存入的是ObjectVariables字典泛型 object 承载。SetObjectVar.md输入ObjectValue(Object)、VariableName、SubGraph、ClearAfterExecution是存储任意对象的通用通道。3.4 SetMatrixVarSetMatrixVar.md 专门用于在渲染 pass 之间传递变换矩阵This is used internally by passing transform matrices between render passes for things like rendering shadow maps.常用于阴影贴图等需要跨 pass 传递变换矩阵的场景。其参数参数类型说明SubGraphCommand必填子图作用域VariableNameString变量名ValueVector4[]必填以 4 个 Vector4 行向量表示的 4×4 矩阵ClearAfterExecutionBoolean执行后是否清除矩阵以Vector4[]4 行的形式存储与 GetPosition 输出的ObjectToWorld形式一致因此可以把 GetPosition 读到的矩阵直接转存为变量。注意 SetMatrixVar.cs 中SubGraph必填其压栈/恢复逻辑与 Float 版本完全一致。四、Get 系列操作符读取变量与智能下拉4.1 通用读取语义所有 Get 操作符遵循同一模式以 GetFloatVar.cs 第 14-28 行为例从context.FloatVariables中按VariableName查找命中则输出字典中的值未命中则输出FallbackDefault或 FallbackValue / FallbackDefault默认值。因此 Get 操作符是惰性且安全的即使上游从未写入对应变量图中也不会报错只会输出默认值——这让可选的上下文状态变得容易表达。4.2 ICustomDropdownHolder自动补全变量名一个非常实用的源码细节是Get 系列操作符实现了ICustomDropdownHolder接口会在编辑器中为VariableName输入提供动态下拉列表。以 GetFloatVar.cs 为例Update()中会把当前上下文里所有 float 变量名缓存到_contextVariableNames第 17 行GetOptionsForInput()返回这些名字供下拉展示HandleResultForInput()在用户选择后将名字写回VariableName输入第 41-51 行。这意味着在编辑器里点击 GetFloatVar 的变量名输入就能看到上游 SetFloatVar 写入的全部可用变量无需手打变量名从根上避免了拼写不一致导致的查找失败。4.3 各类型 Get 操作符的参数速查操作符输入参数输出备注GetFloatVarVariableName(String)、FallbackDefault(Single)Result(Single)文档特别提示配合 Loop 时常使用变量名fGetIntVarVariableName(String)、FallbackValue(Int32)、LogUpdates(Int32)Result(Int32)LogUpdates 为 LogLevels 枚举未命中时按级别输出警告GetBoolVarVariableName(String)、FallbackDefault(Boolean)Result(Boolean)—GetStringVarVariableName(String)、FallbackDefault(String)Result(String)文档提示配合 Loop 时常用变量名sGetVec3VarVariableName(String)、FallbackDefault(Vector3)Result(Vector3)从 ObjectVariables 读取并做is Vector3类型校验GetMatrixVar无输入Result(Vector4[])用于跨 pass 读取变换矩阵如阴影贴图GetObjectVarVariableName(String)、FallbackDefault(Object)Result(Object)任意对象读取从 GetIntVar.cs 的LogUpdates实现可以看到它同样使用LogLevels枚举None / Warnings / Changes / AllUpdates在Warnings级别下若变量未命中且尚未抱怨过会输出一次警告_complainedOnce防止刷屏AllUpdates级别则每次求值都输出int {variableName} is {currentValue}非常适合调试循环中的迭代变量。五、与 Loop 的黄金组合f / i / s 约定Lib.flow.context最常见的实战场景是配合 Loop 使用——文档明确写道You can use [GetFloatVar] and [GetIntVar] to access the iterator variables.可以用 GetFloatVar / GetIntVar 读取循环迭代变量。看 Loop.cs 的实现第 14-41 行for (var i 0; i end; i) { context.FloatVariables[indexVariableName] i; context.IntVariables[indexVariableName] i; if (end 1) context.FloatVariables[progressVariableName] 0; else context.FloatVariables[progressVariableName] i / ((float)(end - 1)); // 使循环体内依赖这些变量的节点失效并重新求值 DirtyFlag.GlobalInvalidationTick; Command.InvalidateGraph(); Command.GetValue(context); }关键事实IndexVariable默认常命名为i同时被写入FloatVariables和IntVariables两个字典因此既可以用 GetIntVar 读取整数下标也可以用 GetFloatVar 读取同一名字获得浮点版下标ProgressVariable归一化进度0→1只写入FloatVariables这正是 GetFloatVar.md 强调dont forget to use f as the normalized progress variable的原因——f即 Loop 的 ProgressVariable 默认名从 GetFloatVar.t3 的序列化内容可以看到其VariableName输入的默认值就是f与 Loop 的默认约定无缝衔接当end 1时进度被特判为 0避免除零值得在编写依赖进度插值的逻辑时注意。Loop 文档还给出性能提示每次迭代都会产生一次 draw call循环次数不宜超过 1000。想要每个粒子一条轨迹式的效果时应尽量把循环体内的计算下沉到 GPUShader侧。在仓库的既有符号中可以看到这一组合的真实用法例如RenderWithMotionBlur.t3 同时包含Loop与GetFloatVar节点RepeatWithMotionBlur.t3 同样在循环体内通过 GetFloatVar 读取迭代进度VisualizeCamTrail.t3 等相机分析符号也依赖该变量族。六、上下文查询与控制类操作符5.1 GetPosition世界/相机/裁剪空间变换读取GetPosition.md 的用途是Gets the current position, rotation, and scale in the world so it can be applied to other transforms.读取当前物体在世界中的位置、旋转与缩放以便应用到其他变换上。其输出输出类型说明UpdateCommandCommand触发计算的命令输出PositionVector3变换后的位置ScaleVector3变换后的缩放ObjectToWorldVector4[]4 个 Vector4 行向量构成的矩阵从 GetPosition.cs 源码可以确认其内部使用context.ObjectToWorld * context.WorldToCamera * context.CameraToClipSpace矩阵链Space输入为枚举Space 值矩阵组合WorldSpacecontext.ObjectToWorldCameraSpacecontext.WorldToCamera * context.ObjectToWorldClipSpacecontext.CameraToClipSpace * context.WorldToCamera * context.ObjectToWorldPositionOffset作为局部偏移先变换到目标空间再作为输出位置Scale通过对单位向量做同一矩阵变换后取分量得到第 57-61 行。矩阵链的默认值在 EvaluationContext.cs 第 79-95 行初始化含透视矩阵PerspectiveFovRH与 LookAt 相机矩阵。5.2 GetForegroundColor读取主绘制色GetForegroundColor.md 输出当前上下文的前景色Vector4This can then be used to apply it to drawing operators, which can be affected by the primary drawing color.可应用到受主绘制色影响的绘制操作符上。实现非常直接——GetForegroundColor.cs 只是把context.ForegroundColor赋值给输出槽而该字段的注释表明它Can be set by [SetMaterial] [Group] and other ops由 SetMaterial、Group 等操作符设置因此它本质上是读取当前材质/分组上下文中的主题色。5.3 SetRequestedResolutionCmd临时覆盖目标分辨率SetRequestedResolutionCmd.md 用于在子图执行期间临时修改上下文请求的分辨率常用于 RenderTarget 等输出尺寸控制。参数参数类型说明TextureCommand作为命令传递的纹理输入ResolutionInt2基础分辨率宽、高StretchResolutionVector2逐轴拉伸系数ScaleResolutionSingle全局缩放系数从 SetRequestedResolutionCmd.cs 源码可见其计算公式newResolution Resolution.X * ScaleResolution * StretchResolution.X Y 轴同理并对结果 Clamp(1, 16384)它在修改前保存context.RequestedResolution执行完Texture命令后立即恢复原值第 12 行、第 30-31 行从而把分辨率覆盖限制在子图作用域内不会泄漏到整个渲染链。注意只有Resolution与StretchResolution各分量均大于 0 时才会应用新分辨率否则沿用原值。5.4 ExecuteRawBufferUpdate先执行更新命令再取缓冲ExecuteRawBufferUpdate.md 接受UpdateCommandsCommand必填与BufferBuffer输出SharpDX.Direct3D11.Buffer。其实现 ExecuteRawBufferUpdate.cs 只有两步UpdateCommands.GetValue(context)—— 强制执行上游的更新命令如 GPU 端的 Buffer 写入/拷贝Output.Value Buffer.GetValue(context)—— 取回更新后的 Buffer 引用。它保证了先更新、后取用的执行顺序适合需要把计算着色器结果同步给后续绘制操作的场景。七、实战模式小结综合文档与源码Lib.flow.context的典型使用模式可以归纳为四条循环内取迭代变量Loop(CountN, ProgressVariablef, IndexVariablei)→ 子图内GetFloatVar(f)获取 0→1 进度、GetIntVar(i)获取整数下标实现逐帧/逐实例的变化参考 RenderWithMotionBlur.t3跨分支传递状态上游SetFloatVar/SetIntVar写入命名变量下游任意位置的 Get 系列按名读取避免为传递单个数值而拉长连接线临时作用域覆盖给 Set 系列接上SubGraph实现仅在子图内生效的变量覆盖配合ClearAfterExecution控制清理时机防止变量泄漏到上下文重置之外渲染上下文协调GetPosition读取当前变换、GetForegroundColor读取主题色、SetRequestedResolutionCmd控制局部分辨率、SetMatrixVar/GetMatrixVar在渲染 pass 之间传递矩阵如阴影贴图。八、文档与源码的对应关系如果你想深入验证以上内容建议按以下路径在仓库中对照阅读自动生成的参考页.help/docs/operators/lib/flow/context/目录下的 20 个 Markdown 文件其中 README.md 为命名空间索引操作符实现源码Operators/Lib/Symbols/flow/context/ 下每个操作符对应的.cs文件上下文数据模型Core/Operator/EvaluationContext.cs变量字典在第 156 行附近矩阵与颜色字段在 121-147 行附近循环协同Operators/Lib/Symbols/flow/Loop.cs 与 Loop 参考页文档生成机制操作符参考说明在编辑器中通过 Documentation → Export as WIKI 重新生成。掌握Lib.flow.context本质上就掌握了 TiXL 节点图中数据如何在求值过程中流动的核心脉络——它是把多分支、多层级的操作符网络组织成有序、可复用逻辑的关键一环。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考