很多做Blender插件开发或者对Blender内部机制感兴趣的朋友，都会在某个阶段产生这样的疑惑：按下G键之后，鼠标在3D视图里滑动，物体跟着动，这个过程到底是哪个函数在驱动？网上能看到的大多数资料，讲到算子注册、模态操作符的基本模板就停了，真正深入到源码层面的分析非常少。我之前写了几篇关于G键源码实现的拆解，分别聊了算子的注册、数据结构的初始化、以及变换模式的入口流程。这一篇，我们把视角集中在transform_modal这个核心函数上——它是整个G键移动交互的主循环核心，也是Blender所有变换工具在交互阶段的中枢。
这篇文章适合三类人：一类是想在Blender源码基础上做二次开发、写自定义变换工具的开发者；一类是已经在用Python脚本写模态操作符、想理解C层背后机制的高级用户；还有一类就是纯粹好奇"G键为什么这么流畅"的源码爱好者。我会尽量把事件怎么进入、状态怎么流转、坐标怎么更新这条链路讲清楚，同时结合我自己读源码和调试时的经验，告诉你哪些地方值得反复推敲，哪些地方看了一眼就得跳过去。
1. G键按下之后：事件如何一路走进transform_modal
很多人第一次在源码里搜transform_modal的时候会有一个困惑：明明按下G键，为什么第一步进的不是这个函数？这里要先理清Blender模态操作符的完整调用链条。
按下G键后，事件首先被窗口管理器的按键映射捕获，通过算子映射表匹配到TRANSFORM_OT_translate这个操作符。操作符的exec和invoke两个回调里，真正干活的是invoke。transform_invoke做的事很多，包括分配TransInfo结构体、初始化视图上下文、设置纹理空间、处理自动吸附的初始化，但最关键的一步是调用WM_event_add_modal_handler把操作符挂进模态事件队列。这一步做完，操作符就从"一次性调用"变成"持续接收事件"的状态，从此每个鼠标移动、每个按键事件都会优先派发到transform_modal。
这里就有个很重要的认知：transform_modal不是G键按下去那一瞬间触发的，而是被事件系统反复调用的。只要操作还处于模态状态，每一次鼠标移动、每一次键盘输入，都会重新进入这个函数。所以它的返回值也很讲究——OPERATOR_RUNNING_MODAL表示"我还想继续接收事件"，OPERATOR_FINISHED表示"确认退出"，OPERATOR_CANCELLED表示"取消退出"。这三态逻辑贯穿着整个函数的主干逻辑。
在真正看transform_modal的代码之前，先得了解它的入参。bContext提供当前场景、视图层、3D视图等信息，操作符指针带着自定义数据，也就是op->customdata，它会通过op->customdata转成TransInfo *t。这个t是整个变换操作的"总控制台"，里面装着当前是移动还是旋转还是缩放、鼠标在哪个像素坐标、变换结果进度、约束轴状态、吸附状态、数值输入状态，等等。几乎所有子函数都绕着t转，读不懂TransInfo，transform_modal就基本没法往下看。
我自己在读这块代码时的一个体会是：不要一上来就通读transform_modal整个函数。它有几百行，分支极多，直接从头读到尾很容易迷路。正确的做法是先看它的大结构，把"确认、取消、±1键数值输入、鼠标移动、模式切换"这些事件分支的框架搭出来，然后再逐个分支深入。下面几节我把各个分支展开来讲，你对照源码看的时候会轻松很多。
2. transform_modal的主循环：从模态事件到位置更新的核心链路
把transform_modal的函数体展开，你会发现它其实是一个巨大的switch加若干if分支的组合。作为一个模态回调，它首先要做的一件事是判断当前事件类型是否属于这个操作应该处理的范畴——很多事件其他操作符也在监听，不能因为一个操作符进入模态，全局所有输入都被它吞掉。所以函数开头会有一段针对事件类型的筛选逻辑。
真正核心的处理链路由两大块组成：输入处理阶段和应用阶段。输入处理阶段把鼠标移动、按键、数字键这些原始输入翻译成"变换意图"；应用阶段根据变换意图，调用对应的数学函数算出新的坐标或旋转量，最后写入到物体或骨骼的数据里。我在阅读代码时，习惯把第一阶段称为"意图收集"，第二阶段称为"结果落地"。
意图收集阶段中，主导的函数是transform_input_update。它会根据当前的变换模式，把鼠标在屏幕上的位移映射成对应的变换参数。比如移动模式下，位移直接映射成模型空间或世界空间的偏移量；旋转模式下，位移被解释为角度变化。这个映射过程不仅仅是"鼠标在哪物体就到哪"，中间还夹着很多影响因素：视图方向、透视投影矩阵、鼠标初始位置、数值输入的增量。
结果落地阶段中，核心函数是applyTransform。这个函数名字看起来是"应用变换"，但实际上它做的事非常底层——遍历当前选中的所有元素（物体、顶点、骨骼、控制点等），把变换矩阵作用上去，然后写回对应的内存结构。在进入applyTransform之前，还有一个非常关键的前置步骤，就是约束轴的计算。如果用户按了X、Y、Z键中的某个，变换方向会被锁定在对应的坐标轴方向上；如果按了Shift，约束轴逻辑还会切换成"跟随物体自身朝向"还是"跟随世界坐标"。
整条主循环的大致流程是这样的：
- 接收新事件。
- 判断是否是取消（右键或Esc）或确认（左键或回车）。
- 如果是鼠标移动，更新
t->mval像素坐标，并调用输入更新逻辑。 - 运行约束轴、精度、吸附等修饰条件。
- 调用
applyTransform把变换结果应用到选中元素。 - 标记3D视图区域需要重绘。
- 返回
OPERATOR_RUNNING_MODAL等待下一个事件。
这套循环的巧妙之处在于：任何时候按下确认键，操作就结束；按下取消键，所有物体恢复到进入模态前的状态。恢复是怎么做到的？因为在进入模态时，transform系统会把所有受影响元素的原始数据快照保存下来。取消时直接回写快照，确认时则丢弃快照。这个机制保证了Blender里G键移动时，你能放心地按Esc，不会有任何残留。
3. 状态位如何控制G键交互行为：全局flag与约束条件
读transform_modal除了看事件分支，更核心的是理解t->flag这个状态位集合。它就像一串开关，控制着整个变换过程的行为。在G键移动模式下，我会特别关注这几个flag：T_PROPORTIONAL、T_PRECISE、T_SNAP、T_INFER。每个flag都关联着一种交互增强机制。
先说T_PRECISE。这个标志由按住Shift键触发，对应的是Blender里"精确模式"的交互逻辑。普通模式下鼠标移动1个像素对应一定的位移量；但Shift按下去之后，位移和鼠标像素的比值会缩小很多，让你能进行像素级的微调。代码里这个行为通常在InputVector结构体的precision_factor字段中体现，T_PRECISE置位时会把这个因子从默认值切换到一个小值。
再说T_SNAP。按Ctrl触发吸附，它的底层逻辑其实并不在transform_modal里做具体计算，而是在输入更新的早期阶段调用吸附相关模块，把目标点"修正"到最近的吸附位置。如果你跟踪过G键加Ctrl的过程，会发现鼠标移动过程中，物体并不是平滑地跟手移动，而是一段段地跳变，这就是吸附点修正的结果。
T_PROPORTIONAL对应的是O键开启的关联衰减（Falloff）功能，在编辑模式下非常常用。移动一个顶点时，周围一定范围内的顶点也跟着动，只是越远影响越小。这个flag置位后，transform_modal会在应用阶段额外调用衰减权重计算，为每个受影响顶点生成0到1之间的权重值，再乘上位移量。
值得单独强调的是 flag 的切换时机。很多状态位的置位和维护并不在transform_modal内部，而是在transform_modal调用的辅助函数里完成，或者由算子管理器在事件预处理中更新。你自己写模态操作符时，最容易犯的错就是把所有输入修改都堆在模态回调里，导致函数越写越长、逻辑失控。Blender的源码把很多状态更新拆到了独立函数里，比如transform_event_xyz_constraint、transform_event_auto_ik、transform_event_snap，这样的拆分逻辑值得学习。
所以从源码阅读的角度，我建议你在看transform_modal时，先把函数里所有t->flag & XXX的判断点列出来，逐个去查这些flag是在哪里被置位和清除的。你会惊讶地发现，很多flag的置位代码是散布在多个文件里的。这种"状态分散"的模式虽然增加了阅读难度，但保证了扩展性——新增一种变换工具时，不需要改动主循环，只需要增加对应的状态处理和更新函数。
4. mode开关：为什么同一个循环能驱动不同变换类型
G键默认是移动，但如果你按下G之后再按X或Y或Z，实现的是沿某个轴移动；又或者你按G之后快速按一下S，会变成缩放。这些模式切换在transform_modal里是怎么处理的？
核心答案是t->mode这个字段。在Blender的变换系统里，模式被定义为TFM_TRANSLATION、TFM_ROTATION、TFM_RESIZE等等枚举值。transform_modal在收到模式切换的按键事件后，会调用transform_mode_set之类的函数去改变t->mode，并重置一些输入缓冲。随后，虽然模态循环还是同一个函数，但内部调用的applyTransform会根据t->mode分发到不同实现——移动模式对应applyTrasl（实际是applyTransform内部根据mode分发），旋转对应applyRotation，缩放对应applyResize。
这个设计的本质是策略模式：主循环只负责事件接收和通用状态管理，具体的变换数学委托给不同模式实现。新增一种变换模式时，你不需要改主循环，只需要实现一套新的"输入到参数"的映射函数和"参数到数据"的应用函数，然后把它注册进模式分发表。
但这里有一个隐藏的细节容易被忽略：切换模式之后，原来的位移增量并不会清零，而是做了一次坐标空间的换算。比如你先按G进入移动，移动了一段距离，再按S切换为缩放，此时缩放的中心点是什么？在Blender的默认交互中，这个中心点不是物体原点，而是当前鼠标在场景中的映射点。这种连续变换的实现逻辑在transform_mode相关文件里非常隐蔽。我建议你实际测试一次：进入G模式后按住Shift再按S，你会发现就变成了缩放且中心点还是原始原点——这中间的差异就是源码里某个分支在起作用。
另外，t->mode还影响一个决定性的行为：数值输入。按G之后直接输入数字（比如按G然后按1.5再按回车），底层是t->value的数值增量被更新。而在旋转模式中，同样输入1.5表示的是1.5度。同一个数值输入解析函数，会根据当前mode决定数值单位。理解了这一点，你在扩展自己的工具时就会注意：数值输入必须与模式联动，否则会出现"输入10，结果移动了10度而不是10米"这样的错乱。
读模式切换相关代码还有一个值得注意的点：G键进入变换后，如果按G再按G，会进入"全局坐标系"模式，也就是让变换轴跟随世界坐标而不是物体自身朝向。这个交互在transform_modal中对应的是坐标系的切换逻辑，代码里叫T_XYZ_GLOBAL。它其实是在约束轴计算那一层做文章：初次的G键会读取当前变换朝向，再次按G会强制使用全局朝向。很多用户不知道这个快捷键的存在，但同时这也是分析源码时最容易错过的细节。
5. 鼠标移动与数值输入的归一化处理
鼠标位移到变换参数的映射，是transform_modal的核心技术细节之一。刚开始阅读源码时，我一度被各种Fac、Center、Dst、Smalldim之类的变量绕晕，后来慢慢梳理出这套映射背后的统一逻辑。
首先要理解一个基础概念：Blender的变换增量不是直接用像素差值。像素坐标在进入数学计算前，会被归一化为"视口空间比例"。代码里通常用一个叫做fac的系数来乘上像素位移，这个系数跟3D视图的缩放比例、透视角度、物体到相机的距离有关。这就是为什么在近处缩放视图时，鼠标轻轻一拖物体就大幅移动，而远处时移动量很小。
归一化做完之后，位移量还要经过坐标空间变换。屏幕上的上下左右，在3D场景中可能对应X轴、Y轴或者一个倾斜方向，具体取决于当前视图的旋转角度。这部分逻辑分散在project相关函数中，它们的作用是把2D像素坐标转换为3D空间坐标。transform_modal里每次鼠标移动都会更新t->mval，并且多数情况下会立刻调用一次视图重新计算，确保移动过程中的坐标转换始终基于最新视图状态。
这里有一个我在实测中踩过的坑：在执行变换的过程中，如果你用鼠标滚轮改变了视图缩放，transform_modal也会收到滚轮事件。但默认情况下滚轮事件不会退出变换，也不会打断交互。视图缩放变化后，同一段鼠标位移对应的实际场景位移会改变，但已累计的变换增量不会自动重新映射——这可能导致物体突然"跳"一下。Blender在源码层面不是没处理这个，而是在事件分发前对滚轮做了单独过滤，避免滚轮进入变换增量逻辑。理解这个过滤器的工作方式，对做自定义工具时处理"哪些事件该进模态、哪些该给视图操作"非常有帮助。
关于数值输入，transform_modal中会检测数字键、小数点、负号和回车键，这些输入会进入一个独立的数值缓冲区。用户在键盘上输入的字符被组织成一个字符串，最终在回车时解析成浮点数，作为增量值应用到当前变换。这里有个对用户友好但对源码阅读不友好的地方：数值字符串的解析逻辑不在transform_modal里，而是在一个专门处理数字输入的辅助模块中。你按下G后输入1.5，这期间每一步都被暂存在一个局部数组中，transform_modal本质上只充当了"保持模态循环活着"的角色，真正的解析和回显都交给子模块。这样拆分的目的是方便将来支持不同的数值格式。
如果你需要调试自定义工具，这里有个很实用的技巧：在transform_modal的入口处写一个条件断点，条件是event->type == EVT_LEFTMOUSE，然后配合printf打印t->mval和当前的t->value，你可以精确看到确认移动那一瞬间鼠标最后的位置和物体的最终位移。这种方法我用了很久，比单纯读代码快得多。
6. 读源码与调试的实操建议：我常用的几个手段
聊到实操，这部分可能比前面的原理拆解更直接。读transform_modal这类复杂的C源码，我一般不是从头到尾线性读，而是带着问题去看代码。比如我会问自己三个问题：某个按键按下后，变更的状态在哪个函数里被写入？变换值在哪个环节被写回给物体？取消的回滚为什么能彻底恢复？带着问题定位代码，效率高得多。
第一个实用的手段是：利用快捷键的行为反查代码路径。Blender的每个快捷键对应一个事件，你可以在wm_event_system里查看按键分发规则，但更快的办法是直接在源码中搜索操作符的idname，再反向找到invoke、exec、modal三个关键函数。以G键为例，搜索TRANSFORM_OT_translate能找到注册入口，点进去之后顺着invoke指针就能找到transform_invoke，再顺着它的WM_event_add_modal_handler调用点找到对应的模态回调。
第二个手段是：学会用CTRACE或printf调试。Blender源码里其实有很多地方预留了调试开关，比如某些操作在运行时会检测G.debug标志并输出调试信息。但transform_modal内部并没有太多现成的调试输出，所以我自己会在本地源码里加临时的printf语句，打印事件类型、flag、mode、当前鼠标位置等信息。因为Blender是开源的，改完源码重新编译的时间虽然有点长，但调试效果非常直观。
第三个手段是：对照Python模态操作符的写法加深理解。Blender Python API 里，模态操作符的模板是invoke里调用context.window_manager.modal_handler_add，之后在modal回调里处理事件并返回RUNNING_MODAL。这个结构其实就是C层transform_modal的"平民版"。我在带朋友入门源码阅读时，总会先让他们写一个简单的Python模态操作符，感受事件循环的节奏，再回头读C代码，瞬间就明白了customdata的角色和状态保持思路。
在我自己的实践中，调试transform_modal最有效的一次，是跟踪一个"物体在特定视图角度下移动方向错乱"的问题。当时我怀疑是投影矩阵计算的问题，于是在transform_modal里打印鼠标像素坐标和t->space->mval的换算结果，对比后发现错误出在视图旋转后的坐标基向量没有正确归一化。这类问题如果光靠读代码，可能要耗掉好几天，但加上运行时打印，几小时就定位到了。
还有一个小细节建议：transform_modal的代码里充满了各种if (event->type == XXX)分支，如果你是在学习而非开发，完全可以把这些if分支的XXX类型列成一张表，对照Blender官方文档里的按键说明逐条验证。我列过一份，大概有20多个事件分支，覆盖了确认、取消、数值输入、坐标系切换、约束轴、精度、吸附等全部交互。这张表列出来之后，整个G键交互的交互全景就清晰了。
读源码这件事，没有太多捷径，但是方法论对了，能省下大量时间。我当初是从Python侧的模态操作符开始，逐步往下钻到C源码，中间断断续续花了小半年才把transform_modal的相关逻辑理通。现在回头看，最值得投入精力的就是那三个核心问题：事件从哪来、状态存哪去、结果写给谁。这三个问题捋顺了，Blender里任何变换操作脱离不了这个框架。
如果你正在写自己的变换工具，最后再分享一个我之前踩过的坑：transform_modal里的事件分支，看起来都是独立的，但它们的执行顺序非常讲究。比如数值输入的回车确认，必须在鼠标事件的更新之后处理，否则会出现"物体跳到错误位置"的竞态问题。这种顺序依赖在源码里没有注释，完全要靠实际测试顺手调整时踩一遍，才能真切理解为什么作者把某些分支放在前面、另一些放在后面。建议你自己改顺序试试，跑几个典型操作流程，比读十遍注释都管用。
