场景与节点层级

坐标与单位约定

XGE 3D 采用右手坐标系、Y 轴向上，长度单位是米，角度是弧度，矩阵为列主序。场景变更与 GPU 调用由调用方在同一逻辑流中串行化——引擎不做隐式加锁，这保证了 API 行为可预测。

创建场景与节点

// 场景是所有 3D 对象的容器
xge3d_scene *pScene;
xge3dSceneCreate(&pScene);

// 在根下挂一个节点，再挂子节点
xge3d_node_t tParent, tChild;
xge3dNodeCreate(pScene, (xge3d_node_t){0}, &tParent);
xge3dNodeCreate(pScene, tParent, &tChild);

// 设置 TRS 变换（位置 / 四元数旋转 / 缩放）
xge3d_transform_t t = XGE3D_TRANSFORM_IDENTITY;
t.position = (xge3d_vec3_t){ 10, 0, -4 };
xge3dNodeSetTransform(pScene, tChild, &t);

// 查询世界矩阵（父链复合后的结果）
xge3d_mat4_t tWorld;
xge3dNodeGetWorldMatrix(pScene, tChild, &tWorld);

变换有两种写法：xge3dNodeSetTransform 接受 TRS 结构体，语义清晰；xge3dNodeSetMatrix 接受精确仿射矩阵，能保留导入资源的原始变换（包括切变）。两者选其一即可，后设置的覆盖先设置的。

生命周期的三条铁律

• 节点属于场景——不需要（也不能）手动释放单个节点数据，xge3dNodeDestroy 销毁节点及其全部后代。
• 重挂父节点保留局部矩阵——xge3dNodeSetParent 只改变层级，不清空变换，适合装配与换装。
• 场景先于资源释放——释放场景前，先释放挂接它的动画器等借用者；带已上传网格的场景销毁必须发生在 owning 上下文线程。

大世界的原点重定位

float 在 1e9 量级坐标下精度不足。XGE 的做法是场景持有双精度原点：xge3dSceneSetOrigin 设定附近全局原点，节点与相机都工作在相对坐标里；应用自己保管全局状态，需要时用 xge3dRelativePosition 与 xge3dCameraLookAtGlobal 在两套坐标间换算。

本章 API 速查

要点与常见陷阱

• 不要缓存节点句柄跨场景使用——句柄内含 scene 校验字段，外来句柄会被拒绝。
• 四元数 w 在最后——xge3d_quat_t{x,y,z,w}，与 glTF 一致，别和某些库的 w-first 混淆。
• CPU 场景 API 不依赖 xgeInit——可以在无窗口环境（如工具程序）里构建与查询场景。

进阶练习