更新前

doc/整体架构思路.md

@@ -308,6 +308,30 @@ RenderCache 不应该由属性 setter 直接修改。
 
 数据输入函数只追加 edit_input。
 
+RenderAble 可以选择开启独立像素缓存：
+
+```text
+RenderAble::setIndependentPixelCache(true)
+```
+
+开启后：
+
+```text
+该 RenderAble 的 markRenderDirty 不再触发整张 Plot renderColor。
+该 RenderAble 单独 prepare/draw 到自己的透明 QImage。
+Plot::paintEvent 在绘制 Plot 级 ColorBuffer 后叠加独立像素缓存。
+```
+
+默认不开启。
+
+它适合：
+
+```text
+PerformanceShower
+轻量 overlay
+高频变化但不应该触发整图重绘的辅助层
+```
+
 ## 7. Color 三缓冲
 
 Color 有三个角色：
@@ -391,7 +415,7 @@ Try
 RenderAble 层：
 
 ```text
-Triple_Buffer_Mode
+Plot_Buffer_Acquire_Mode
 ```
 
 控制单个 RenderAble 在后台 draw 阶段获取 State_Render lease 的行为。
@@ -420,6 +444,22 @@ Try 失败后没有统一返回值表达本次修改是否被接受。
 在没有重新设计 API 返回语义前，不允许静默丢弃编辑和输入。
 ```
 
+Plot 还保存一个 RenderAble 默认获取策略：
+
+```text
+Plot::renderAbleBufferAcquireMode()
+Plot::setRenderAbleBufferAcquireMode()
+```
+
+RenderAble init 到 Plot 时会复制父 Plot 当前的默认策略。
+
+之后单个 RenderAble 可以独立调用：
+
+```text
+RenderAble::bufferAcquireMode()
+RenderAble::setBufferAcquireMode()
+```
+
 ## 9. 调度版本
 
 渲染调度使用 RenderPipeline 的帧版本。
@@ -633,6 +673,8 @@ PerformanceShower:
     计数使用 CPP_Core/Core/Statistics::Speed_Statistics。
     耗时使用 CPP_Core/Core/Statistics::Value_Statistics。
     Value_Statistics 提供 instant / smooth / variation。
+    开启独立像素缓存，不进入 Plot 整图 renderColor。
+    统计写入按观察者节流刷新，不允许每条事件触发整图 dirty。
 ```
 
 不允许重新引入：
@@ -694,30 +736,34 @@ Cacl 需要在析构时写统计。
 
 统计写入走 Input 三缓冲：
 
-计数类数据：
+统计类型：
 
 ```text
-PerformanceShower::counterIncrease()
-    ↓
-PerformanceShowerInputData
-    ↓
-prepareData()
-    ↓
-Psc::Speed_Statistics::update(1)
+Duration：
+    阶段耗时，使用 Psc::Value_Statistics。
+
+Counter：
+    事件频率，使用 Psc::Speed_Statistics。
+
+Gauge：
+    当前数值状态。
+
+State：
+    当前文本状态。
 ```
 
-耗时类数据：
+统计链路：
 
 ```text
-Cacl 析构
+PerformanceShower::recordDuration / incrementCounter / setGauge / setState
     ↓
-PerformanceShower::recordCost()
-    ↓
-PerformanceShowerInputData
+PerformanceShowerInputData events
     ↓
 prepareData()
     ↓
-Psc::Value_Statistics::update(useTime)
+PerformanceShowerPrivate::mScopes
+    ↓
+draw()
 ```
 
 Value_Statistics 的含义：
@@ -735,14 +781,118 @@ smooth：
 variation：
     类似 RTTVAR 的波动估计。
     它不是严格方差或标准差，而是 instant 与 smooth 偏差的 EWMA。
+
+p95：
+    最近 64 次采样的 95 分位估计。
 ```
 
-性能框显示耗时时使用：
+性能框当前分组：
 
 ```text
-instant
-SRTT
-RTTVAR
+Pipeline：
+    schedulerQueueWait
+    requestToSubmit
+    cpuQueueWait
+    prepareData
+    renderColor
+    draw
+    publishRenderColor
+    updateToPaint
+    paintEvent
+    jobState
+    activeRenderTasks
+    renderEnabled
+    paintBufferAcquireMode
+    renderAbleDefaultAcquireMode
+    paintRequestPending
+    editStateVersion
+    renderStateVersion
+
+RenderAble：
+    <RenderAble>.prepareData
+    <RenderAble>.draw
+    <RenderAble>.stateLeaseMiss
+    <RenderAble>.bufferAcquireMode
+
+Buffer：
+    Color.mark/swap/busy/swapNoNeed/wait
+    <RenderAble>.State.mark/swap/busy/swapNoNeed/wait
+    <RenderAble>.Input.mark/swap/busy/swapNoNeed/wait
+```
+
+性能框显示策略：
+
+```text
+默认视图：
+    Plot
+
+Plot 视图显示：
+    Pipeline
+    General
+    Color buffer
+
+左侧栏显示：
+    一级：Plot / 每个有统计数据的 RenderAble
+    二级：当前对象拥有的数据面
+
+Plot 的二级数据面：
+    Pipeline
+    General
+    Color
+
+RenderAble 的二级数据面：
+    RenderAble
+    State
+    Input
+
+内容区：
+    不显示 [Pipeline] / [Buffer] / [RenderAble] 这种分组标题。
+    当前层级已经表达数据归属。
+    指标名会去掉已由层级表达的对象和缓冲前缀。
+内容过长时显示滚动条，鼠标滚轮滚动内容区。
+
+布局宽度策略：
+    左侧两级栏宽只在栏项目变化时重算。
+    右侧指标内容宽只在切换视图时重算。
+```
+
+PerformanceShower 的刷新策略：
+
+```text
+统计事件：
+    写入 PerformanceShower Input。
+    不逐条 markRenderDirty。
+
+观察者刷新：
+    普通统计事件最多 10Hz 触发一次独立像素缓存刷新。
+    Clear / 选择视图 / 滚动 立即刷新。
+
+排除项：
+    PerformanceShower 自身不进入 RenderAble 性能统计列表。
+```
+
+Pull snapshot 的含义：
+
+```text
+Push gauge：
+    每帧主动把每个 RenderAble 的每个 Buffer 统计写成事件。
+    会制造大量 PerformanceShower Input。
+
+Pull snapshot：
+    Buffer 控制器只维护 atomic 计数。
+    性能面板刷新时按需读取当前快照。
+    没有面板刷新就不产生统计事件。
+```
+
+完整性能面板最终应该使用 QWidget：
+
+```text
+Overlay：
+    只显示摘要。
+
+右键菜单 QWidget 面板：
+    显示完整 Pipeline / RenderAble / Buffer 树。
+    使用低频 pull snapshot 刷新。
 ```
 
 ## 17. 最终规则