RobotMetaCore/docs/impanda3d_offscreen_imgui_summary.md

ImPanda3D 离屏渲染编辑器实现总结

目标

这个原型的目标是把 Panda3D 作为场景渲染层，把 ImGui 作为编辑器 GUI 层，形成一个类似编辑器的基础架构：

• Panda3D 负责场景、相机、灯光、材质和离屏渲染
• Hello ImGui / imgui-bundle 负责 Docking、Viewport、Hierarchy、Inspector、Stats 等编辑器面板
• Panda3D 的离屏结果最终显示到 ImGui 的 Viewport 中

当前实现不是把 Panda3D 直接嵌进 ImGui 的同一个实时 OpenGL 渲染流程里，而是采用更稳妥的路径：

Panda3D worker thread -> offscreen buffer -> RAM RGBA -> GlTexture -> ImGui viewport

当前模块拆分

主入口已经收口到 main.py，核心逻辑拆分到 src/impanda3d/：

• src/impanda3d/config.py 负责 Panda3D 运行时配置，例如 window-type offscreen
• src/impanda3d/types.py 放编辑器共享数据结构，例如 CameraState、SceneNodeSnapshot
• src/impanda3d/scene.py 负责预览场景搭建、灯光、材质、相机状态应用
• src/impanda3d/renderer.py 负责 Panda3D 离屏渲染线程、帧同步、场景快照、simplepbr 初始化
• src/impanda3d/editor.py 负责 ImGui 编辑器布局、Viewport 绘制、Hierarchy、Inspector、Stats、输入交互
• src/impanda3d/app.py 负责组装 EditorApp 并启动 immapp.run()

这样拆分后的好处是：

• Panda3D 渲染逻辑和 ImGui 编辑器逻辑解耦
• 场景搭建和渲染线程逻辑不再混在一个文件里
• 后续继续加 Gizmo、场景编辑、资源浏览器时更容易扩展

实现流程

1. 先验证 Panda3D 可以离屏渲染

最初的方向参考了 example/QPanda3D 的思路，本质上是先证明 Panda3D 内容可以不直接显示在自己的窗口里，而是输出到一个中间图像目标，再由别的 GUI 系统承接。

这一步确认了一个关键事实：Panda3D 的场景内容可以稳定离屏输出，因此它可以作为编辑器内部的渲染子系统存在。

2. 用 Hello ImGui 搭出编辑器壳子

接着把编辑器界面切换为 imgui-bundle / Hello ImGui：

• 使用 Docking 布局
• 构建 Viewport、Hierarchy、Inspector、Stats
• 用状态栏显示当前渲染路径和帧率

这个阶段重点不是视觉效果，而是先确定编辑器基础 UI 壳子已经成立。

3. Panda3D 输出到离屏 Buffer

在 Panda3D 侧使用 ShowBase(windowType="offscreen")，然后手动创建离屏 buffer：

• 配置 FrameBufferProperties
• 创建 GraphicsOutput
• 把颜色结果输出到 Texture
• 使用 RTMCopyRam 拿到 RGBA 数据

这样就有了一个稳定的离屏渲染目标，后面 ImGui 只需要消费这个结果。

4. Panda3D 放到独立 worker thread

最早的问题是：如果把 Panda3D 渲染和 Hello ImGui 的 GUI 渲染强行放在同一个 OpenGL 生命周期里，容易出现黑屏或初始化异常。

因此当前方案改成：

• 主线程只负责 ImGui
• Panda3D 在独立线程里跑离屏渲染
• 线程之间只交换最新一帧的 RGBA 数据和场景快照

这一步是整个原型最关键的架构调整。它牺牲了一部分纯粹的理论性能上限，但换来了明显更高的稳定性和更低的集成复杂度。

5. Viewport 从 immvision.image() 改为原始纹理绘制

中间版本里，Viewport 是通过 immvision.image() 直接显示 numpy 图像。这个方案可以工作，但暴露了两个问题：

• 图像区域不容易精确铺满整个 viewport 内容区
• UI 侧封装层更厚，控制空间和性能都不够理想

后面改成：

• Panda3D worker 继续产出 RGBA numpy 数据
• UI 侧把最新帧更新到 immvision.GlTexture
• 用 ImGui 原始 draw list 的 add_image() 直接把纹理画满当前 viewport 矩形

这个改动之后，viewport 铺满问题得到解决，帧率也比之前更高。

6. 集成 panda3d-simplepbr

在离屏 buffer 方案稳定后，把 panda3d-simplepbr 接入到 Panda3D worker 内部：

• simplepbr.init() 绑定到离屏 buffer
• camera_node 指向离屏相机
• taskmgr 使用 Panda3D 自己的 base.taskMgr

这让离屏预览不再只是基础固定管线效果，而是具备更接近现代预览窗口的材质表现。

7. 调整灯光与场景，让画面更像编辑器预览

在 simplepbr 加入后，又继续把场景从 Panda3D demo 风格调整为更像编辑器预览：

• 背景改为中性深灰
• 使用环境光、主光、补光、轮廓光、反弹光
• 放置地面、背景板、展示台
• 给预览模型设置更中性的材质参数

目标不是做一张“漂亮的 demo 图”，而是做一个更适合观察模型、材质和轮廓的编辑器预览环境。

遇到的问题与解决方法

1. 同线程 OpenGL 集成导致黑屏

问题

把 Panda3D 渲染塞进 Hello ImGui 同一个 GUI 渲染流程里时，窗口可能是黑屏，或者后续没有正常渲染。

原因

Panda3D 和 Hello ImGui 都会对 OpenGL 上下文和渲染生命周期进行管理。Python 这一层再叠加后，两个系统直接共用一个渲染时序非常脆弱。

解决

放弃“同线程同上下文直连”的做法，改成 Panda3D worker thread 离屏渲染，UI 线程只做纹理上传与显示。

2. 探索过原生纹理直连，但当前环境不可行

问题

理论上最理想的路径是零拷贝共享 GPU 纹理，也就是 Panda3D 渲染出一张纹理，ImGui 直接拿这个原生 texture id 显示。

实际结果

做过验证后发现，这条路径在当前 Python + Panda3D + Hello ImGui 组合下不稳定：

• Panda3D 的 native texture id 的确能拿到
• 但把 Panda3D 初始化塞进 Hello ImGui 主线程 GL 生命周期时，会破坏 ImGui backend 的设备对象初始化
• 实际表现包括 ImGui_ImplOpenGL3_CreateDeviceObjects() failed

结论

当前工程里不采用共享原生纹理的做法，优先使用稳定的离屏 RGBA 回传路径。

3. simplepbr 接入后，worker 线程需要 taskMgr.step()

问题

simplepbr 并不是纯静态初始化，它会往 Panda3D 的 task manager 注册任务。因此如果只手动调用底层 graphicsEngine.render_frame()，效果链不会完整更新。

解决

在 worker 线程中使用：

base.taskMgr.step()

这样 simplepbr 相关任务也会一起推进，离屏画面才能正常带上 PBR 效果。

4. taskMgr.step() 在子线程里触发 signal only works in main thread

问题

一旦在 worker thread 调用 base.taskMgr.step()，就会遇到类似异常：

ValueError('signal only works in main thread of the main interpreter')

原因

Panda3D 的 TaskManager 在 step() 过程中会尝试处理 SIGINT 相关逻辑，而 Python 的 signal 机制只允许主线程这么做。

解决

在 worker 循环内临时禁用 direct.task.Task.signal 这一分支，结束时再恢复原值：

• 进入 worker 主循环前保存旧值
• 运行时设置 PandaTaskModule.signal = None
• finally 中恢复

这是当前架构下让 Panda3D task 系统在子线程可用的关键兼容处理。

5. Viewport 不能完全铺满

问题

早期使用 immvision.image() 时，图像在 viewport 里没有完全铺满，存在明显空白边界。

原因

immvision.image() 更偏向通用图像查看组件，不是专门为“编辑器主视口完全填充绘制”设计的。它会带来自己的布局、显示参数和边距语义。

解决

改用：

• imgui.invisible_button() 占满可用区域
• 读取该区域的 rect_min / rect_max
• 用 draw_list.add_image() 直接绘制

这样可以严格按 viewport 内容区绘制，结果更像真正的编辑器视图。

6. 帧率不高

问题

最初版本里帧率偏低，特别是在 viewport 放大时更明显。

主要瓶颈

• Panda3D 离屏渲染本身有成本
• RTMCopyRam 会发生 GPU 到 CPU 的读回
• numpy 帧数据更新会有额外内存带宽消耗
• UI 层如果使用更高层封装控件，也会增加额外开销

已做优化

• Viewport 改为 GlTexture + draw_list.add_image()
• 减少不必要的图像路径封装
• 使用双缓冲思路保存最新帧
• 场景树快照不再每帧更新，而是按周期更新
• 增加 Render Scale 滑杆，让用户可以主动降低离屏渲染分辨率
• UV 翻转放到 ImGui 采样坐标层面处理，避免额外整帧翻转拷贝

性能结论

就当前架构而言，性能属于“可用的编辑器原型级别”，但不属于最优路径。

它的最大瓶颈仍然是：

Panda3D offscreen -> GPU readback -> CPU numpy -> OpenGL upload

也就是说，它本质上还是一条“读回再上传”的链路，不是共享 GPU 纹理链路。

当前架构的性能判断

从工程稳定性和落地难度看，当前架构是合理的：

• 优点是稳定、可控、容易调试、便于继续扩展编辑器逻辑
• 缺点是存在 CPU 读回和二次上传，性能上限受限

如果只是做编辑器原型、工具界面、节点树、Inspector、简单 Gizmo 和中等规模场景预览，这条路径是可以继续推进的。

如果以后要做更高帧率、更大分辨率、更多后处理、更多编辑器叠加层，那么后续需要继续评估：

• 是否能做稳定的共享 GPU 纹理
• 是否能改为更低开销的图像桥接方式
• 是否需要把 Panda3D 视口彻底作为独立原生窗口嵌入

当前代码状态

目前代码已经完成这些能力：

• Panda3D 在独立线程离屏渲染
• ImGui 编辑器 Docking 布局可用
• Viewport 可完整铺满内容区
• 支持鼠标 orbit、pan、dolly
• 支持 simplepbr 离屏预览
• 预览场景更接近编辑器环境而非 demo 场景
• 支持基础场景层级查看和 Inspector 信息展示
• 支持渲染缩放以平衡分辨率与帧率

下一步建议

• 把场景数据和渲染线程进一步抽象成编辑器服务层
• 引入 Gizmo 与对象选中反馈
• 给 Inspector 增加真正的属性编辑，而不是只读展示
• 加入资源浏览器、场景保存和加载
• 继续评估更低开销的纹理共享路径
• 为线程同步、关闭流程、异常恢复补充更系统的测试