TiXL 网格 UV 变换实战：深入解析 TransformMeshUVs 算子的平移、旋转、缩放与顶点选择机制-开发者社区

音视频
图形学
桌面应用

【免费下载链接】t3

TiXL is an open source software to create realtime motion graphics.

项目地址：https://gitcode.com/GitHub_Trending/t3/t3

TransformMeshUVs 是 TiXL（tooll3）开源实时动态图形软件中Lib.mesh.modify模块提供的一个网格 UV 处理算子，它直接操作网格已存在的 UV 坐标，实现对纹理映射的平移、旋转、非均匀缩放与整体缩放，并可选择只影响部分顶点。本文以官方算子文档为主体骨架，结合仓库中该算子的 C# 实例定义、组合图（.t3）默认配置与底层 HLSL 计算着色器实现，完整讲解其输入参数、输出类型、运行原理与在真实项目中的搭配用法，帮助你在实时可视化、投影映射与材质调试中精准控制纹理贴图。

算子定位：Lib.mesh.modify 家族中的 UV 编辑器

TransformMeshUVs 属于 Lib.mesh.modify 系列算子，该系列负责对网格几何与属性进行"就地修改"式处理，包括顶点混合（BlendMeshVertices）、法线重算（RecomputeNormals）、变形（DeformMesh）等。与同目录下的其他算子不同，TransformMeshUVs 不改变网格的顶点位置，而是只改写每个顶点的 UV（纹理坐标）数据，从源头改变后续着色阶段的纹理采样结果。

在官方文档中，它的定位非常明确：

核心功能：Manipulates the existing UV coordinates of a mesh to change the mapping of textures.（操作网格已有的 UV 坐标，从而改变纹理的映射方式）
可见性：变换结果通过 DrawMesh 一类的网格绘制算子最终呈现在画布上（Becomes visible with DrawMesh）。
与兄弟算子的分工：
- 若要从零覆盖UV，用平面映射方式重投影，应使用 MeshProjectUV（Overwrites the existing UV coordinates with planar mapping）；
- 若要基于其他数据源（如渲染后的内容）重新生成 UV 并用于后续采样，可参考 ReprojectToUV（Render 库中的重投影算子）。

三者可组成一条典型流水线：先用 MeshProjectUV 生成一套 UV，再用 TransformMeshUVs 对这套 UV 做动画化调整，最后交给 DrawMesh 显示。

输入参数详解

官方文档定义了 8 个输入参数，下表完整列出（保留原文档字段与说明，并补充仓库源码确认的类型与行为）：

名称（相关性 & 类型）	说明
InputMesh（MeshBuffers，必填）	输入网格缓冲，内含顶点位置、法线、UV 等属性。在 TransformMeshUVs.cs 中以`InputSlot<MeshBuffers>`声明
Translate（Vector3）	线性平移 UV 坐标，即沿 U / V 方向整体移动纹理
Rotate（Vector3）	旋转 UV 坐标，围绕 Pivot 定义的旋转中心旋转纹理
Stretch（Vector3）	按轴非均匀缩放 UV 坐标（U、V 两个轴方向分别缩放）
Uniformscale（Single/float）	对 UV 坐标做整体均匀缩放
UseVertexSelection（Boolean）	决定是否只影响被选中的顶点（与 SelectVertices 类算子配合使用）
Pivot（Vector3）	旋转或缩放时的操作中心点，默认位于 UV 空间的中心 (0.5, 0.5)
TexCoord2（Boolean）	是否将变换应用到第二套 UV 坐标（TexCoord2）而非主 UV

参数默认值（来自组合图定义）

从算子实例的定义文件 TransformMeshUVs.t3 中可以确认每个参数的默认值：

参数	默认值
Translate	(0, 0, 0)
Rotate	(0, 0, 0)
Stretch	(1, 1, 1)
Uniformscale	1.0
Pivot	(0.5, 0.5, 0.5)
UseVertexSelection	true
TexCoord2	false
InputMesh	null（需外部连接）

这些默认值意味着：算子开箱即用时不会改变 UV（平移为 0、缩放为 1、旋转为 0），只有在你显式驱动这些参数（例如用曲线或时间驱动 Translate / Rotate / Uniformscale）时纹理才会产生动画。

输出说明

官方文档定义的唯一输出如下：

名称	类型
Result	T3.Core.DataTypes.MeshBuffers

在源码中，输出以[Output(Guid = "1030db1a-...")] public readonly Slot<MeshBuffers> Result声明（见 TransformMeshUVs.cs），可直接接入 DrawMesh 等下游算子。注意：由于修改的是 UV 而非顶点位置，网格形状完全不变，只有贴图采样发生改变，因此非常适合做不改变几何的纹理动画。

运行原理：从算子图到 GPU 计算着色器

C# 侧的定义

该算子在 C# 层是一个轻量级Instance<TransformMeshUVs>容器（见 TransformMeshUVs.cs），本身不包含逐顶点运算逻辑，而是通过组合图（graph）把输入参数连接到内部的变换矩阵计算、缓冲组装与计算着色器执行等子节点上。从 TransformMeshUVs.t3 的子节点列表可以看出其内部结构：

TransformMatrix：把 Translate、Rotate、Stretch、Uniformscale、Pivot 组合成 4×4 变换矩阵；
ComputeShader：加载着色器资源Lib:shaders/3d/mesh/mesh-TransformUVs.hlsl（见 TransformMeshUVs.t3）；
ComputeShaderStage：以线程组 (64, 1, 1) 派发计算任务；
GetBufferComponents / GetSRVProperties / _AssembleMeshBuffers / ExecuteBufferUpdate：负责读取输入 MeshBuffers 的缓冲区视图、执行更新并把结果重新组装为 MeshBuffers；
BoolToFloat：把两个布尔输入（UseVertexSelection、TexCoord2）转换为着色器可读的 float 标志。

也就是说，TiXL 把"算子"实现为可组合的节点子图，C# 实例只负责声明输入输出槽位（每个槽位带独立 GUID），实际计算完全交给 HLSL 计算着色器在 GPU 上并行完成。

HLSL 着色器核心逻辑

核心计算位于 mesh-TransformUVs.hlsl。其常量缓冲区和执行流程如下：

cbuffer Params : register(b0) { float4x4 TransformMatrix; // 由 Translate/Rotate/Stretch/Uniformscale/Pivot 组合而成 float UseVertexSelection; // 0 或 1 float ToTexCoord2; // 0 或 1 }

逐线程（每线程处理一个顶点）的核心逻辑：

float s = UseVertexSelection > 0.5 ? SourceVerts[i.x].Selected : 1; // 顶点选择因子 float3 pos = float3(SourceVerts[i.x].TexCoord, 0); // 读取主 UV float3 pos2 = float3(SourceVerts[i.x].TexCoord2, 0); // 读取第二套 UV ResultVerts[i.x] = SourceVerts[i.x]; if((bool)ToTexCoord2 == true){ ResultVerts[i.x].TexCoord2 = lerp(pos2, mul(float4(pos2,1), TransformMatrix).xyz, s).xy; } else{ ResultVerts[i.x].TexCoord = lerp(pos, mul(float4(pos,1), TransformMatrix).xyz, s).xy; }

几个值得注意的实现细节：

选择因子的软过渡：当UseVertexSelection开启时，每个顶点的Selected属性（由 SelectVertices 等算子写入）被当作插值系数s，在"原始 UV"与"变换后 UV"之间做lerp。因此Selected并非简单的 0/1 硬开关——若选择值在 0～1 之间连续渐变，UV 变换也会呈现渐变过渡效果。
UV 以齐次坐标参与变换：UV 被扩展为(u, v, 0, 1)后乘以 4×4 的TransformMatrix，再取结果的 xy 写回，从而统一支持平移、旋转、缩放等仿射变换。
两套 UV 通道可选：TexCoord2为真时改写TexCoord2通道，为假时改写主TexCoord通道；未选中的通道保持原值。
GPU 并行：每个线程独立处理一个顶点，GetDimensions保证越界线程直接返回，线程组规模 64 与算子图内CalcDispatchCount节点计算出的调度数量匹配。

与之对照，MeshProjectUV.hlsl 的实现是直接把顶点对象空间位置经变换矩阵投影为 UV（mul(float4(posInObject.xyz,1), Transform).xy + float2(1,1)），并同样支持TexCoord2通道切换——这正是"覆盖 UV（project）"与"修改已有 UV（transform）"两种语义的底层区别。

典型使用流程

1. 基础连接

[网格来源] --> InputMesh (TransformMeshUVs) [纹理/参数控制] --> Translate / Rotate / Stretch / Uniformscale / Pivot TransformMeshUVs.Result --> DrawMesh

将任意网格缓冲（例如程序化生成或导入的模型）接入InputMesh，把算子输出接到 DrawMesh，再对变换参数做动画即可看到纹理在模型表面移动、旋转或缩放。

2. 仅影响部分顶点

先用 SelectVertices（或 SelectVerticesWithSDF）给网格顶点写入选择值，然后保持UseVertexSelection = true（默认值）。此时只有被选择的顶点区域参与 UV 变换，可用于制作"局部贴图滑动/拉伸"效果，例如只让某个面片的贴图滚动。

3. 纹理滚动与缩放动画

纹理无限滚动：让Translate的 X 或 Y 分量随时间线性增长（注意 UV 是周期性的，平移量等于整数倍时会回到相同采样位置）；
纹理放大/缩小：调节Uniformscale（整体）或Stretch（分轴），配合Pivot = (0.5, 0.5)使缩放围绕 UV 中心进行，避免纹理向角落漂移；
纹理旋转：驱动Rotate的 Z 分量，围绕Pivot旋转纹理。

4. 与投影类算子的搭配

若输入网格本身没有可用 UV，可先用 MeshProjectUV 生成平面映射 UV，再接 TransformMeshUVs 做后续动画；若希望把渲染画面重投影到网格表面再采样，可参考 ReprojectToUV 与示例工程ReprojectToUvExample（见 ReprojectToUvExample.t3）的组合方式。

注意事项

InputMesh为必填输入且类型必须是MeshBuffers，未连接时算子无输出；
UseVertexSelection依赖网格顶点携带选择数据；若输入网格未经过任何选择算子，Selected属性可能为默认值，建议在使用局部变换前先用 SelectVertices 明确写入选择范围；
变换作用于 UV 空间（0～1 范围之外的 UV 同样合法，会按纹理的采样/平铺设置显示），因此平移大数值可能让纹理超出单次平铺范围；
该算子不改变顶点位置与法线，不会影响光照几何，只影响纹理采样坐标；
如需重算因其他变形算子改变的法线，可再接 RecomputeNormals。