three.js 节点材质中的 ModelNode 解析：从 NodeFrame 动态绑定模型变换与坐标度量

three.js 节点材质中的 ModelNode 解析：从 NodeFrame 动态绑定模型变换与坐标度量

【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js

ModelNode 是 three.js 节点材质（TSL / Node Material）体系中用于访问"当前被渲染 3D 对象"变换信息的核心访问器节点。与需要显式传入对象引用的 Object3DNode 不同，ModelNode 直接从节点帧（NodeFrame）状态中提取被渲染对象，因此天然适配批量渲染、蒙皮、实例化等需要"逐对象复用同一材质"的场景。读完本文，你将理解 ModelNode 的五个 scope 各自代表的坐标系与矩阵语义、update()的刷新机制，以及它在着色器中以 uniform 暴露的世界位置、观察空间位置、朝向、缩放与世界矩阵等度量的正确用法。

ModelNode 是什么

ModelNode 是Object3DNode的特化版本，位于 src/nodes/accessors/ModelNode.js，其继承链为：

EventDispatcher → Node → Object3DNode → ModelNode

从源码结构看，ModelNode 本体非常薄——它只覆盖了两点行为：

1. 不保存对象引用。构造函数仅接收scope，并把对象的引用获取推迟到每一帧的update()阶段；
2. 从帧状态取对象。在update()中执行this.object3d = frame.object;，即从当前NodeFrame上取回正在被渲染的对象，随后调用父类Object3DNode.update()完成数值刷新。

// src/nodes/accessors/ModelNode.js（节选） class ModelNode extends Object3DNode { static get type() { return 'ModelNode'; } constructor( scope ) { super( scope ); } update( frame ) { this.object3d = frame.object; super.update( frame ); } }

这段实现正是"ModelNode 与 Object3DNode 的本质差异"：Object3DNode在构造时（或通过 TSL 代理函数）绑定一个具体的 Object3D 实例，适合"固定对象、固定材质"的场景；而ModelNode绑定的是"当前帧正在渲染的对象"，同一棵节点材质可以被场景中任意数量的 Mesh 共享，渲染到谁身上就自动读取谁的矩阵与位置。

构造函数与 scope 参数

new ModelNode( scope : 'position' | 'viewPosition' | 'direction' | 'scale' | 'worldMatrix' )

构造一个新的模型节点，scope决定该节点在着色器中暴露的变换度量类型，源码中对应五种静态常量（见 src/nodes/accessors/Object3DNode.js）：

在父类Object3DNode中还额外支持RADIUS（float，对象包围球半径），因此从"生成节点类型"的方法看，worldMatrix映射为mat4，四个向量类 scope 映射为vec3，radius映射为float（Object3DNode.js）。

注意 scope 对对象引用的影响：在 TSL 中通常不会直接new ModelNode(...)，而是使用预置的不可变单例符号（见下文"TSL 便捷符号"），这些符号在import时已经确定了各自 scope。

update(frame)：帧驱动的对象绑定与度量刷新

.update( frame : NodeFrame )覆写了Object3DNode.update，其职责可拆成两步：

1. 绑定对象：this.object3d = frame.object;，即从当前节点帧取回正在渲染的 3D 对象；
2. 刷新 uniform：调用父类update，按 scope 把对应的矩阵/向量写入内部UniformNode。

NodeFrame是节点系统的"每帧上下文"，在 src/nodes/core/NodeFrame.js 中保存了renderer、scene、object、camera、material以及time、deltaTime、frameId、renderId等状态；渲染器在绘制前通过 NodeManager 的getNodeFrame()把当前渲染对象写入nodeFrame.object = object，随后逐对象调用节点的update()。

因为该节点声明了updateType = NodeUpdateType.OBJECT（见 Object3DNode.js），NodeFrame.updateNode()会在 OBJECT 模式下对每个渲染对象都执行一次update（NodeFrame.js），这正是"每个物体拿到自己的矩阵"的机制保证。

父类update()对每个 scope 的底层计算如下（Object3DNode.js）：

• WORLD_MATRIX：直接把object.matrixWorld赋给 uniform，每次更新时 JS 侧只转移矩阵引用，开销最小；
• POSITION：调用Vector3.setFromMatrixPosition( matrixWorld )提取平移；
• SCALE：调用Vector3.setFromMatrixScale( matrixWorld )提取各轴缩放；
• DIRECTION：调用Object3D.getWorldDirection()得到世界空间朝向（默认取本地+Z方向经世界矩阵变换后的结果，供lookAt类逻辑使用的语义约定）；
• VIEW_POSITION：先取世界位置，再applyMatrix4( camera.matrixWorldInverse )变换到相机空间，等价于"把模型摆到相机坐标系下看"。

TSL 便捷符号：以节点声明方式使用 ModelNode

为了让着色器代码接近可读的数学表达式，ModelNode 在源码文件末尾以nodeImmutable导出了一组预置单例（ModelNode.js），并且这些符号全部在 src/Three.TSL.js 中对外导出，可从three/tsl直接引入：

其中modelNormalMatrix、modelWorldMatrixInverse、modelViewMatrix系列并非严格意义上的 ModelNode 实例：

• modelNormalMatrix与modelWorldMatrixInverse是使用uniform().onObjectUpdate()的 Uniform 节点——每当对象更新时，分别通过getNormalMatrix( matrixWorld )与copy( matrixWorld ).invert()在 CPU 上计算；
• modelViewMatrix默认返回modelViewMatrix（即cameraViewMatrix * modelWorldMatrix，在着色器内以 mediump 精度连乘得到），但优先读取渲染器上下文中已有的builder.context.modelViewMatrix，避免重复计算；
• highpModelViewMatrix则把矩阵乘法放到 JS 侧执行（object.modelViewMatrix.multiplyMatrices( camera.matrixWorldInverse, object.matrixWorld )），以 CPU 计算换取着色器内的高精度，适合大尺度坐标、深度精度敏感的场景。

这些符号在 three.js 内部材质中被大量复用。例如 src/materials/nodes/NodeMaterial.js 用modelViewMatrix.mul( positionLocal ).xyz计算顶点的观察空间位置；src/materials/nodes/Line2NodeMaterial.js 用modelViewMatrix与modelWorldMatrixInverse处理线段端点。examples 目录中的 TSL 示例（如 CurveModifierGPU.js、Raymarching.js）也以这些模型度量参与自定义着色逻辑。

实战用法：在节点材质中使用模型度量

以一个基于MeshBasicNodeMaterial的简单片段为例，把对象的世界位置作为颜色分量、并按到相机的观察距离做衰减：

import * as THREE from 'three'; import { modelPosition, modelViewPosition, modelViewMatrix, positionLocal, vec3 } from 'three/tsl'; const material = new THREE.MeshBasicNodeMaterial(); material.colorNode = modelPosition.toVec3(); // 世界位置直接参与着色 // 更常见的组合：观察空间距离驱动的衰减 material.colorNode = vec3( 0.5 ).mul( modelViewPosition.z.negate() );

几点约束与建议：

• 不要手动new ModelNode()后反复传入对象。既然它从NodeFrame取对象，直接复用modelPosition这类单例即可；若你的确需要绑定某一个特定对象（例如把某个辅助物体的矩阵塞进材质），应改用 Object3DNode 系列 的objectPosition( mesh )、objectWorldMatrix( mesh )等带参代理函数；
• 更新时机。ModelNode 依赖渲染循环中NodeFrame的状态填充，只有通过 renderer 的正常渲染流程才会刷新；不要在update()之外、或对象尚未加入场景时假设其 uniform 已同步；
• 精度策略。默认modelViewMatrix是着色器内的 mediump 连乘；在需要高质量大世界坐标、深度或矩阵精度时，可切换为 CPU 计算的highpModelViewMatrix（对应源码中的isHighPrecisionModelViewMatrix标志，见 ModelNode.js），以少量 CPU 开销换取 GPU 端精度；
• 实例化与蒙皮。由于绑定的是"正在渲染的对象"而非固定对象，ModelNode 天然支持共享材质的多物体与实例化渲染路径。

与其他访问器的关系

• 同类"按对象绑定"的还有object3DModelMatrix、modelViewMatrix等常规矩阵 uniform，它们与 ModelNode 一起构成节点材质中"模型变换上下文"的完整度量集；
• 与 ModelNode 对应的通用节点是 Object3DNode：后者是"对象即参数"（构造时确定对象），前者是"对象即状态"（帧内动态绑定），二者共享同一套 scope 计算逻辑与 uniform 更新机制；
• NodeFrame是二者共同的运行环境，负责在每个渲染对象上触发更新，可进一步阅读 src/nodes/core/NodeFrame.js 了解 FRAME / RENDER / OBJECT 三种更新粒度的调度差异。

小结

ModelNode 用极简的实现（构造传 scope + 帧内取对象）把"当前渲染对象的变换度量"接入 TSL 节点图：update()从NodeFrame.object绑定对象后，按position / viewPosition / direction / scale / worldMatrix五种 scope 刷新内部 uniform；再配合modelPosition、modelWorldMatrix、modelViewMatrix等预置符号，让材质编写者可以像写数学表达式一样读取模型的世界/观察空间信息。理解它也就理解了节点材质中"逐对象 uniform 刷新"这一整套工作流。

【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js