tactileipc3d/AUTO_PANEL_SIZING.md

自动适配：点阵不越界 + 面板尺寸跟随点阵

这份文档说明本项目里为了实现：

1. 圆点（点阵）始终落在面板顶面上，不越界
2. 面板的宽/深（W/D）根据点阵规格自动缩放
3. 面板厚度（H）保持独立可控（不随点阵改变）

所做的代码改动和使用方式。

---

现象 & 根因

当前点阵的摆放逻辑（src/glwidget.cpp 的 GLWidget::updateInstanceBufferIfNeeded_()）是：

• 点阵中心围绕原点居中摆放
• 每个点的中心坐标：
  • x = c * pitch - (cols-1)*pitch/2
  • z = r * pitch - (rows-1)*pitch/2
• 所以 点中心 的范围一定在：
  • x ∈ [-gridW/2, +gridW/2]，其中 gridW = (cols-1)*pitch
  • z ∈ [-gridD/2, +gridD/2]，其中 gridD = (rows-1)*pitch

但每个点是“有半径”的（dotRadius），在 shader 里实际画出来的圆会占据：

• x 方向还会向外多出 dotRadius
• z 方向还会向外多出 dotRadius

如果面板的 W/D 没有随点阵变化而调整，就会出现你截图里那种：外圈点的圆形被画到了面板外（看起来像“越界”）。

---

解决思路（数学上怎么保证不越界）

要让“圆点的边缘”也不越界，需要满足：

• 面板半宽 panelW/2 >= gridW/2 + dotRadius
• 面板半深 panelD/2 >= gridD/2 + dotRadius

等价于：

• panelW >= gridW + 2*dotRadius
• panelD >= gridD + 2*dotRadius

本项目采用的就是这条公式。

如果你希望四周再留白一点，只要把公式改成：+ 2*(dotRadius + margin) 即可。

---

代码改动点（做了什么）

1) setSpec() 里自动计算面板 W/D

文件：src/glwidget.cpp，函数：GLWidget::setSpec(...)

做的事：

• 对 rows/cols/pitch/dotRadius 做了下限保护（避免负数）
• 根据点阵规格计算面板顶面 m_panelW/m_panelD：
  • gridW = (cols-1) * pitch
  • gridD = (rows-1) * pitch
  • m_panelW = gridW + 2*dotRadius
  • m_panelD = gridD + 2*dotRadius
• 标记面板几何和 dots 几何需要重建（dirty flag）

这样一旦你改点阵规格，面板会自动缩放到刚好包住点阵。

---

2) 厚度单独控制：setPanelThickness()

文件：src/glwidget.h / src/glwidget.cpp

新增接口：

• void setPanelThickness(float h);

它只修改 m_panelH（厚度），并标记面板几何需要重建。

---

3) 由于 W/D 会变：需要“重建几何体 buffer”

原因：面板顶面矩形的顶点坐标依赖 m_panelW/m_panelD，改变后必须重建 VBO/IBO/VAO 才能反映到 GPU。

做法：

• 新增两个 dirty flag：
  • m_panelGeometryDirty
  • m_dotsGeometryDirty
• 在 GLWidget::paintGL() 的开头判断 dirty：
  • dirty 就调用 initPanelGeometry_() / initDotGeometry_() 重建
  • dots 重建后会重新分配 instanceVBO，所以把 m_valuesDirty = true，确保下一帧重新上传 instance 数据

---

4) initPanelGeometry_() / initDotGeometry_() 现在会先删旧 buffer

因为会重复调用重建，所以这两个函数里加入了：

• 先 glDeleteBuffers / glDeleteVertexArrays
• 再重新 glGen* 创建新资源

保证不会重复堆积资源（泄漏）或引用旧 VAO。

---

5) main.cpp 不再手动写死面板 W/D

文件：main.cpp

把原来的：

• glw->setPanelSize(1.2f, 0.08f, 1.2f);

改为：

• glw->setPanelThickness(0.08f);

原因：如果继续调用 setPanelSize()，你会把 setSpec() 自动算出来的 W/D 覆盖掉，越界问题就会回来。

---

使用方式（你应该怎么调用）

推荐顺序：

1. glw->setSpec(rows, cols, pitch, dotRadius);
   • 会自动算出 panelW/panelD，保证点不越界
2. glw->setPanelThickness(panelH);
   • 只改厚度，不影响自动宽深
3. glw->setRange(minV, maxV);
4. glw->submitValues(values);

如果你确实想手动指定面板大小（不走自动适配），可以再调用：

• glw->setPanelSize(w, h, d);

但要理解：这会覆盖自动计算的 W/D，点可能再次越界（除非你按本文公式算好）。

---

可选改进（按你需求继续拓展）

• 加边距（不要贴边）：在 setSpec() 里引入 margin，把公式改成：
  m_panelW = gridW + 2*(m_dotRadius + margin)
m_panelD = gridD + 2*(m_dotRadius + margin)
• 让点阵填满面板但不改变 pitch：目前面板跟着 pitch 走；如果你希望面板固定而 pitch 自适配，需要反过来解 pitch。