# Datoviz 迁移与封装审计

## 目标边界

Renderive 只负责逻辑状态收集、批量数据收集、Kernel 帧策略调度、输入事件汇聚和像素帧发布。Datoviz 的 scene/visual API 只允许在 `Render_Domain` 所属线程创建、修改、渲染和销毁，对外接口不暴露 `Dvz*`、Vulkan 对象、缓冲区角色或工作线程状态。

当前垂直切片的数据流为：

```text
Point_State --Kernel Double_State_Strategy--+
                                             +--帧边界--> Point_Frame_Strategy
Point payload --Kernel Multi_Double_Buffer_Strategy-----------+
Kernel Event --Input_Collector---------------+                 v
                                                     Render_Domain 单线程
                                                            |
                                                     Datoviz Point Visual
                                                            |
                                               Vulkan 外部目标 + RGBA8 回读
                                                            |
                                                   immutable Pixel_Frame
                                                            |
                                                   WebSocket RVP1 像素帧
```

## 已迁移的 Datoviz 生产模块

`render_3D/datoviz/CMakeLists.txt` 已直接编译以下模块，现有 Point 后端不再需要复制 Datoviz 实现：

- 基础层：`common`、`fileio`、`geom`、`math`、`thread`。
- 输入与控制器：`input`、`controller`。
- GPU：`vk`、`vklite`、`drp2`。
- 场景层：`scene` 以及 `scene/visuals` 下全部生产源、GLSL/WGSL 注册表和 SPIR-V 构建产物。
- Visual family：point、pixel、marker、segment、path、image、mesh、volume、primitive、sphere、glyph、text、labels、splat、vector。

`registry` 和 `stroke` 是 visual 内部支撑目录，不是独立业务组件，不应再增加一层公共包装。

明确不迁移 `app`、`gui`、原生 window/canvas、stream、video、Qt bridge 和 wasm。无窗口像素服务由 Renderive 自己的帧策略、事件入口和 Web 传输承担，这些上游模块没有消费者，迁入会形成第二套调度和事件来源。

## 已完成的 Point 封装

- `Point_Visual`：直接组合状态与实时数据策略；`Point_State` 只保存样式、变换、可见性和深度测试。
- `Point_Visual`：状态使用 Kernel `Double_State_Strategy`，不可变点集使用单 Entry 的 `Multi_Double_Buffer_Strategy` 在帧边界发布。
- `Point_Scene`：只使用满足 Kernel frame-control concept 的 3D `Point_Frame_Strategy`；统一发布 `Frame_Status` 查询。
- `Datoviz_Point_Backend`：所有 Datoviz/Vulkan 资源均限制在单一 `Render_Domain`；批量属性使用 `dvz_visual_set_data_many()` 原子提交。
- 输入：Kernel pointer/wheel/key 事件映射到 Datoviz router/arcball；Web 保留事件的真实派生类型，不经过 `Event` 切片。
- 输出：外部 RGBA8 target 渲染、同步回读并发布不可变 `Pixel_Frame`。
- Demo/Web：`Point_Demo`、图库案例 `point_3d`、RVP1 RGBA 编码、三种帧模式动作和前端目录展示。

## 后续 visual 包装批次

Datoviz 生产源码和上游测试已经迁入；以下是尚未实现的 Renderive 业务包装，不应在没有业务消费者时一次性生成空类：

1. 点/线批量族：Pixel、Marker、Segment、Path、Vector、Sphere、Splat。复用 Point 的状态/实时数据/单线程后端结构，但每个 family 保留自己的业务状态和 Datoviz 属性映射。
2. 几何族：Primitive、Mesh。分别建模顶点/索引/实例数据；索引和实例不可复制成 visual 成员的第二份权威数据。
3. 图像与文字族：Image、Glyph、Labels、Text。纹理/字形数据使用 real-time data 或具有明确所有权的资源对象，不能把 Datoviz field 指针暴露到公共接口。
4. 体数据：Volume。体素 payload、传输函数和采样状态分离；大体数据必须走实时数据接口，不能进入双缓冲小状态对象。

每新增一个 family 都必须同时完成：状态边界测试、并发批量数据测试、Datoviz 属性映射测试、真实 GPU 像素测试、resize 测试、三种帧策略测试、事件测试，以及 Web 展示测试。Point 的实现是这些测试的基准，不是供公共 API 继承的万能基类。

## 测试覆盖

- Datoviz scene runner：558/558，通过；其中已包含 Point 的 typed upload、属性校验、item range、resize、external buffer、large count、GLSL/WGSL emit 和 GPU 执行测试。
- Renderive Point 状态/Kernel 策略测试：4/4，通过。
- Renderive Point Vulkan/事件集成测试：2/2，通过。
- Web Point 专项测试：8/8，通过，覆盖 RGBA 行步长、目录动作、resize、自动低延迟、Web 事件透传、Manual 快照、Playback 顺序和增删恢复。
- `webapp_gallery`：TypeScript 与 Vite production build 通过。

## 状态来源检查

| 状态 | 唯一权威来源 | 读取方式 |
| --- | --- | --- |
| Point 样式/变换/可见性 | `Point_Visual` 的 Kernel 双状态策略 | 帧边界发布快照 |
| Point 大批量数据 | `Point_Visual` 的 Kernel 双缓冲 | 不可变已发布点集 |
| viewport/clear color | `Scene_State_Buffer` | 帧边界发布快照 |
| 输入事件 | `Input_Collector` 队列 | 每帧 drain |
| 帧生命周期/计数 | Kernel frame strategy | `Frame_Status` 即时查询 |
| Datoviz/Vulkan 资源 | `Datoviz_Point_Backend` | 仅 Render_Domain 内访问 |
| 对外像素 | `Point_Scene::latest_frame()` | 不可变共享快照 |