tactileipc3d/BACKGROUND_GRID.md

屏幕空间背景（白底 + 灰色网格线）说明

这份文档解释项目里新增的“3D 软件常见的白色背景 + 灰色分割线网格”是怎么实现的，以及如何调整效果。

需求点：

• 背景看起来更“科技感”（轻微渐变 + 网格线 + vignette）
• 背景不随相机旋转（不受 yaw/pitch/zoom 影响）

---

实现方式概览（为什么它不会旋转）

我们采用“屏幕空间（screen-space）”绘制方式：

1. 画一个全屏 quad（两个三角形），顶点坐标直接写在裁剪空间 NDC（[-1,1]）
2. fragment shader 使用 gl_FragCoord（屏幕像素坐标）生成网格线

由于整个背景是直接画在屏幕坐标系里，不使用 uMVP，所以它不会跟着相机旋转或移动。

---

关键文件

• 资源注册：resources.qrc
  • 新增：shaders/bg.vert、shaders/bg.frag
• Shader：
  • shaders/bg.vert：全屏 quad 的顶点 shader（裁剪空间直出）
  • shaders/bg.frag：背景颜色 + 抗锯齿网格线（基于 gl_FragCoord）
• C++（OpenGLWidget）：
  • src/glwidget.h：新增 m_bgProg、m_bgVao/m_bgVbo、initBackgroundGeometry_()
  • src/glwidget.cpp
    • GLWidget::initPrograms_()：编译/链接背景 program
    • GLWidget::initBackgroundGeometry_()：创建全屏 quad VAO/VBO
    • GLWidget::paintGL()：先画背景（关闭深度写入），再画 3D 内容

---

渲染顺序（为什么不会影响 3D 深度）

背景绘制发生在 GLWidget::paintGL() 的最前面：

1. glClear(...) 清空颜色/深度
2. 绘制背景（屏幕空间）
   • glDisable(GL_DEPTH_TEST);
   • glDepthMask(GL_FALSE);（不写深度）
3. 恢复深度状态
   • glDepthMask(GL_TRUE);
   • glEnable(GL_DEPTH_TEST);
4. 再绘制 panel / dots（正常 3D 深度测试）

因此：背景永远在最底层，而且不会把深度缓冲弄脏。

---

全屏 quad（背景几何）

GLWidget::initBackgroundGeometry_() 创建一个覆盖整个屏幕的矩形（两个三角形）：

• 顶点坐标是 NDC（裁剪空间）：
  • (-1,-1) 到 (1,1)
• 顶点 shader（shaders/bg.vert）仅仅把它输出到 gl_Position

这样不需要任何相机矩阵，也不会“跟着相机”动。

---

网格线怎么画出来的（bg.frag）

shaders/bg.frag 主要做了三件事：

1) 背景渐变底色

• 使用 uv = gl_FragCoord.xy / uViewport 得到 0..1 的屏幕坐标
• 在 y 方向做一个轻微渐变（上更亮、下稍灰）

2) 细网格 + 粗网格（分割线）

用 uMinorStep / uMajorStep（单位：像素）控制网格间距：

• uMinorStep：细分格子（更淡）
• uMajorStep：粗分格子（更明显）

网格线本质是对 fract(coord / step) 做“距离最近线”的计算，然后用 fwidth 做抗锯齿：

• fwidth 会随着屏幕像素密度和视角变化自动调整边缘过渡，避免锯齿

3) 轻微 vignette

四角略暗、中心略亮，让画面更聚焦、更像 3D 软件视口。

---

HiDPI 注意点（为什么要乘 devicePixelRatio）

Qt 的 width()/height() 是“逻辑像素”；而 gl_FragCoord 是“物理像素”。

所以背景在 C++ 里传入：

• uViewport = (width * dpr, height * dpr)
• 网格 step 也乘 dpr

否则在高 DPI 屏幕上网格会显得“变密/变粗”。

---

如何调整外观（常用参数）

调整网格密度

在 src/glwidget.cpp 里设置了：

• uMinorStep = 24 px（细线间距）
• uMajorStep = 120 px（粗线间距）

改这两个值就能让网格更密/更稀。

调整颜色/强度/科技感

在 shaders/bg.frag 里可以改：

• topCol/botCol：背景渐变颜色
• minorCol/majorCol：网格线颜色
• mix(...) 的系数：线条深浅
• vignette 强度：dot(p,p) 前面的系数

---

可选增强（如果你想更像 Blender/Unity）

• 加“坐标轴线”（X 红、Z 蓝或灰色加深）并在中心画十字
• 增加 UI 开关：显示/隐藏网格、调 step、调强度
• 增加“地平线”或 “ground plane” 的淡淡雾化效果