独立 3D 扩展

接入方式

kui_ext_3d 独立于 KUI 核心，通过纯 C ABI 对接，使用 Filament 与 Bullet 等后端。新项目按 SDK 外 find_package(Kui) 的方式集成；默认关闭的旧仓内 3D 不能当作同一发布入口。

约束和排错

运行时需要同目录的 procedural_pbr.filamat sidecar。创建场景、资产和物理对象后按协议释放；失效通知必须使后续帧更新。测试包含首帧、连续绘制、尺寸变化和销毁，不能只看三角形首次出现。

独立 3D 元素

kui-3d-view 由独立 kui_ext_3d 注册。扩展通过纯 C ABI 接入，包含自身渲染与物理依赖；新集成使用独立扩展，默认关闭的旧仓内 3D 路径不作为新项目方向。

<kui-3d-view style="width:100%;height:480px"></kui-3d-view>

场景、资产与物理

当前注册表包含几何体、灯光、相机、glTF 资产、资产动画、刚体、约束与射线检测等方法。创建、加入场景与销毁属于不同操作；资产和实体句柄需要由应用管理生命周期。

• 场景方法 →
• 资产加载 →
• 物理接口 →

部署材质与运行检查

procedural_pbr.filamat 是必需 sidecar，Windows 放在扩展 bin 同目录。运行时检查材质加载、首帧、窗口缩放、透明度、动画和持续重绘；某次模型截图不能代替这些检查。

• 扩展部署 →

在最小场景验证依赖

按下面的顺序验证一个最小场景，再接入完整应用。

1. 按 SDK component 说明带上独立扩展与材质 sidecar。
2. 先运行最小场景，再添加模型、纹理和物理能力。
3. 布局尺寸、相机、光照和资源路径分别确认，黑屏不一定是渲染器失败。
4. 窗口关闭时释放扩展对象；不要直接依赖核心内部 3D 类型。