Aethera/render_3D/DATOVIZ_MIGRATION_AUDIT.md

Datoviz 迁移与封装审计

线程与数据边界

Renderive 负责状态发布、实时数据交换、oneTBB CPU 数据准备、事件入口、帧调度和像素帧发布。Datoviz 的 scene/visual mutation、FramePlan emission、DRP2 execution、GPU submission 与 readback 全部归单一 Render_Domain 所有。

当前帧数据流：

Scene / Renderable state ----+
Point bulk data -------------+-- frame publication snapshot
                              |
                              +-- oneTBB Flow Graph: per-renderable CPU prepare
                              |       |
Kernel Event -----------------+       +-- immutable Prepared_Point
                                      |
                                      v
                              Render_Domain (single thread)
                                      |
                              Datoviz apply / emit / DRP2 / GPU
                                      |
                              externally owned Frame_3D

oneTBB worker 不调用 dvz_*。Datoviz FramePlan 继续负责 GPU upload/render/copy/readback 依赖，Renderive RenderPlan 只负责应用级 CPU prepare 依赖和末端单一 render node。

帧快照

• Scene_Base::publish_frame_state(Abstract_Frame&) 在 frame-control 的发布边界交换 Scene、Renderable 与实时数据。
• Frame_Render_Snapshot 保存对应帧的 Scene 状态、Renderable 元数据和类型安全的大数据共享快照。
• Manual、Low Latency、Playback 保存同一类快照；Playback 出队不会读取后来版本的数据。
• oneTBB prepare 只从帧快照读取输入并发布不可变 prepared output。
• Scene render node 等待所有末端 prepare 依赖，然后在 Render_Domain 串行消费 prepared output。

Point 封装

• Point_Visual 的小状态由 Renderable 状态策略管理。
• 点集的唯一权威来源是 Multi_Double_Buffer_Strategy；帧只持有已发布版本的不可变共享快照。
• positions、colors、sizes、sigma、angles、radii、normals 等派生数组只存在于 Prepared_Point，不保存为 Visual 成员。
• Point_Scene 复用 Kernel Scene3D_Context、frame-control、RenderPlan、oneTBB Flow Graph、capture 和 observer。
• Pointer、wheel、key 直接保留 Kernel Event 语义并投递到 Render_Domain，没有第二套输入命令或收集队列。
• 后端只应用 prepared data，并负责 Datoviz/Vulkan 资源和写入调用方持有的 Frame_3D。

唯一状态源检查

数据	权威来源	帧内读取
Point 样式、变换、可见性	Point_Visual 状态策略	发布帧快照
Point 大批量数据	Point_Visual 双缓冲策略	不可变共享快照
viewport、clear color、visual family	Scene3D_Context 状态策略	发布帧快照
输入	Kernel Event	Render_Domain 直接处理
CPU 派生数组	当前帧 oneTBB prepare	Prepared_Point
Datoviz/Vulkan 资源	Datoviz_Visual_Backend	仅 Render_Domain
输出像素	最近完成的 render node	Point_Scene::latest_frame()

验证

• Renderive CTest：Kernel、render2D、render3D、Datoviz、Qt、Web 全套通过。
• Point 状态/并发快照、真实 Vulkan 渲染、resize、事件和 Playback 历史顺序均有测试覆盖。
• webapp_gallery Vitest、TypeScript 和 Vite production build 通过。