# Datoviz 迁移与封装审计

## 线程与数据边界

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

当前帧数据流：

```text
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 通过。