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

这份文档解释项目里新增的“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” 的淡淡雾化效果