1. 为什么我把方案压在 Qt 5.12 加 OpenGL 上

做三维地球这个事，说大不大，说小也不小。一个能转、能缩放、能点、能标绘的球，看起来需求很朴素，但真正落地的时候，围绕它的技术选型、坐标系约定、纹理规范、相机手感、性能边界，每一项都能单独写一篇。我这几年在几个项目里反复踩过这条路，最后一次是从零搭一套基于 Qt 5.12 和 OpenGL 的三维地球开发框架，服务于一个半离线场景的桌面客户端，最终把一套可复用的渲染骨架沉淀了下来。这篇文章我就把这套东西拆开讲透，从为什么这么选，到球面网格怎么算，到着色器怎么写，到黑屏了怎么查。

先说适合谁看。如果你会用 Qt 写窗口和按钮，但一提到 OpenGL 就觉得隔着一层窗户纸；或者你已经在用某个三维框架，但遇到"为什么纹理倒过来了""为什么地球一半是黑的"这种问题找不到北；再或者你正准备做一个带地图、带轨迹、带标注的三维展示界面，需要一个轻量、可控、不依赖大引擎的方案，那这篇内容应该能省掉你不少试错时间。文章里所有代码都是可编译的骨架，不是伪代码，参数也是我在实际项目里跑通的数值。

1.1 先把需求边界划清楚再谈选型

我见过太多项目在选型阶段就开始纠结，纠结到最后把时间全花在比较框架上，真正的地球还没出来一个圆。我的做法是先画需求边界，四个问题问清楚，答案基本就决定了技术路线。

第一，这个地球是"看得过去"还是要"看得精细"。如果只是拿来做界面装饰、做数据可视化的底图，几万个三角形加上一张等距圆柱投影的贴图，完全够用，甚至比高精度的方案更好维护。但如果要做到城市级别甚至街道级别，那就必须上瓦片金字塔和 LOD 调度，那已经是另一个量级的工作。

第二，有没有离线要求。某公司的那次项目里，客户端要在没有外网的机房里跑，所有资源必须内置，这就直接排掉了一大批依赖在线服务的方案。

第三，交互深度到哪里。只是拖拽旋转和滚轮缩放，还是要做射线拾取、多图层标绘、动态轨迹、三维模型摆放。拾取这个能力很关键，它决定了你要不要维护一套完整的屏幕到世界坐标的转换链路。

第四，团队的技术存量。Qt 桌面开发的人手好找，OpenGL 熟手不好找，但 Qt 自带的 QOpenGLWidget 加上一套规范化的封装，能让只懂 Qt 的人在一两周内接手维护，这个工程价值很高。

把这四个问题答完，你会发现大部分中小型项目的答案都落在同一片区域：不需要重型三维引擎，需要一个自己能完全掌控的轻量渲染器。

1.2 三条路线的真实取舍

我把当时摆在桌上的三条路线拉了个表，这个表后来被我复用了好几次，直接贴出来。

QPainter 那条路我用过，做旋转的二维球面贴图效果，确实能以假乱真，但只要客户说一句"我要看到背面的边缘有弧度""我要光照有明暗"，这条路立刻崩。它的本质是把球面点投影到平面再画，没有真正的深度信息，遮挡关系全靠自己算，稍微加点东西就撑不住。

完整三维引擎那条路，能力没得说，但代价是项目里多了一整套需要理解的世界观，坐标系、节点树、渲染状态、资源管理，全得学。而且一旦遇到引擎的坑，排查成本高得离谱。

最后我选的是中间这条路。Qt 5.12 是个长期支持版本，QOpenGLWidget 这个类在 5.4 引入后到 5.12 已经相当稳定，它把 OpenGL 上下文和 QWidget 的生命周期绑在一起，还自带了事件转发和缩放处理，比老的 QGLWidget 干净得多。更关键的是，Qt 自带的 QOpenGLShaderProgram、QOpenGLBuffer、QOpenGLVertexArrayObject、QOpenGLTexture 这一套封装，把最容易写错的资源管理包了一层，同时没有把底层 API 藏起来，该自己控制的地方照样能控制。

提醒一句：很多人在 Qt 里加QT += opengl是为了用 QGLWidget，但 QOpenGLWidget 本身属于 QtWidgets 模块，相关的 OpenGL 封装类属于 QtGui 模块。Qt 5 里这两个模块是默认带的，工程里真正需要额外配置的是QT += widgets和图形上下文格式，别被网上老教程带偏。

2. 三维地球的整体架构与渲染主链路

动手写代码之前，我习惯先把模块分层画清楚，哪怕只是在纸上画几个框。三维地球这个玩意最容易失控的地方，是把坐标转换、几何生成、渲染状态、交互逻辑全糊在一个类里，写着写着就变成一个三千行的巨无霸，后面谁接手都要骂人。

2.1 五层拆分与职责边界

我最终落地的分层是这样的，五层，每层单一职责，层与层之间只走明确的接口。

数据层负责一切"喂进来的东西"：地球贴图、法线贴图、国界矢量、标注点位、轨迹点串。这一层不碰 OpenGL，只做加载、解析、内存布局，输出的是纯 CPU 侧的数组和结构体。

几何层负责把数据变成顶点。球面网格生成、经纬度网格线、标注图元的四边形、轨迹的带状条带，全在这一层产出。它的输出永远是QVector<Vertex>加QVector<GLuint>这种朴素结构，方便测试，也方便在没开窗口的情况下单测。

渲染层是唯一碰 OpenGL 的地方：着色器编译、缓冲上传、纹理绑定、绘制调用、状态切换。这一层只认几何层给的数组，不关心数据从哪来。

交互层处理鼠标键盘滚轮，把屏幕动作翻译成相机的球坐标变化，把点击翻译成射线，再翻译成经纬度。

UI 层就是 Qt 的窗口、工具栏、状态栏，负责把交互结果展示出来，也负责把用户的图层开关传下去。

这么拆之后，有一个很实际的好处：几何层和交互层的坐标换算逻辑可以完全脱离窗口环境测试。我在项目里专门写了一组不依赖 OpenGL 上下文的用例，专门验证"经纬度转球面点再转回来"这条链路，误差在1e-5度以内才算过。这类测试在后期改代码时救了我好几次。

2.2 一帧画面到底走了哪些步骤

很多人写paintGL的时候是想到什么写什么，结果画面闪、状态错、性能差。我把一帧的流程固定下来，形成肌肉记忆。

1. 计算本帧时间差，更新相机缓动和动画插值，得到最新的视图矩阵。
2. 清空颜色缓冲和深度缓冲，颜色清成背景色，深度清成 1.0。
3. 绑定着色器程序，把投影矩阵、视图矩阵、模型矩阵、光照方向、纹理单元这些 uniform 一次性设好。
4. 绑定顶点数组对象，让顶点属性指针的配置一次生效、后续复用。
5. 绑定纹理到指定纹理单元，设置采样器 uniform 对应同一个单元号。
6. 打开深度测试和背面剔除，设置正确的正面绕序。
7. 发出绘制调用，按索引数量绘制三角形。
8. 解绑资源，交还给 Qt。

这八步里，第 3 步和第 4 步是最容易出错的。uniform 忘了设，画面要么全黑要么全白；顶点属性指针没和 VAO 绑定在一起，换个对象就乱套。我见过最典型的问题是有人把glVertexAttribPointer放在 VAO 绑定之外调用，结果第一次画对了，第二次画全乱，查了半天以为数据坏了。

2.3 坐标系约定：一次定死，绝不复用不同口径

三维地球里最要命的事情之一是坐标系混乱。我给自己定的规矩是三个坐标系各管一段，绝不混用。

世界坐标系是右手系，Y 轴朝上，Z 轴朝向观察者，单位长度和地球半径一致。我一般把地球半径定义为 1.0，所有距离都用相对单位，这样透视投影的近远裁剪面好设，深度精度也稳。

球面坐标用经度、纬度、海拔三个量。经度从 -180 到 180，纬度从 -90 到 90，海拔以半径为单位偏移。这个口径和常见的等距圆柱投影贴图完全对应，是后面贴图不出错的前提。

屏幕坐标就是 Qt 给的像素坐标，但要注意高 DPI 下的设备像素比。Qt 5.12 里QWidget::width()返回的是逻辑像素，而 OpenGL 的视口用的是物理像素，两者之间差一个devicePixelRatioF()。这个细节在 4K 屏上会直接导致画面只渲染左下角四分之一，我第一次遇到时以为是投影矩阵算错了。

把这张表贴在文档最上面，后面所有换算都对照它，能省掉至少一半的坐标类 bug。

3. 球体几何：经纬度网格怎么生成才不出错

球体网格是三维地球的骨架，它决定了贴图是否对齐、法线是否平滑、接缝是否明显。这一块看起来是纯数学，但实际写起来坑非常多，尤其是绕序和 UV 的映射方向，错一点点就是"地球内外翻转"或者"贴图上下颠倒"。

3.1 参数化球面的推导过程

标准做法是把球面按纬度和经度切成网格，纬度方向叫 stack，经度方向叫 slice。参数化公式如下，其中 φ 是从北极算起的极角，范围 0 到 π，θ 是绕 Y 轴的方位角，范围 0 到 2π。

x = R * sin(φ) * cos(θ) y = R * cos(φ) z = R * sin(φ) * sin(θ)

φ 等于 0 时sin(φ)为 0、cos(φ)为 1，点落在北极(0, R, 0)；φ 等于 π 时落在南极。θ 从 0 走到 2π，点绕 Y 轴转一整圈。这个公式的好处是 Y 轴天然朝上，和我的世界坐标约定一致，不需要额外做轴变换。

UV 的映射要和 Φ、θ 严格对应。我采用的规则是u = θ / 2π，v = 1 - φ / π。为什么要反过来？因为等距圆柱投影贴图的第一行像素对应的是北极，而 OpenGL 的纹理坐标 v 等于 0 通常对应贴图的底部，不翻一下就会出现南极贴到北极的情况。这个方向问题后面在纹理加载那一节还会再撞一次。

3.2 顶点结构体与法线处理

顶点我定义一个结构体，位置、法线、UV 三个分量，全部用QVector3D和QVector2D装，因为 Qt 的这些类型自带normalized()、dotProduct()这些方法，写起来省事，底层是连续内存，直接能上传到显存。

struct Vertex { QVector3D pos; QVector3D nrm; QVector2D uv; };

法线对于标准球是最简单的：单位球上任意一点的法线就是该点位置向量归一化。这里有个小细节，如果你的球体半径不是 1，法线仍然是位置向量除以半径，或者直接归一化，别去乘半径。

有人问过为什么不给球体加切线基。如果你的着色器只做朗伯漫反射和简单的镜面高光，法线足够；但如果后面要做法线贴图、要做地形起伏、要用各向异性过滤，那就需要切线基。我的建议是先不做，等真的需要法线贴图了再加，否则顶点数据从 32 字节涨到 44 字节，一千万个顶点就是多出 120MB 显存，得不偿失。

3.3 索引缓冲与接缝的处理技巧

索引这块，我踩过最深的坑是三角形的绕序。OpenGL 默认认为逆时针绕序是正面，如果你生成的三角形是顺时针，再打开背面剔除，整个地球会变成一个空心的黑洞，你只能看到内壁。更坑的是这种错误在关闭剔除时完全看不出来，一旦开启就"地球消失了"。

我最终确定的生成逻辑是这样：以(i, j)表示第 i 圈第 j 个顶点，索引编号为i * (slices + 1) + j。每个格子生成两个三角形，第一个是a, a+1, b，第二个是a+1, b+1, b，其中a是当前顶点，a+1是同一圈的下一个经度，b是下一圈的同经度顶点。这套顺序在右手系、Y 轴朝上、默认GL_CCW的前提下，从球外看向球心是逆时针。

void buildSphere(float radius, int stacks, int slices, QVector<Vertex> &verts, QVector<GLuint> &idx) { const float PI = 3.14159265358979f; verts.clear(); idx.clear(); verts.reserve((stacks + 1) * (slices + 1)); for (int i = 0; i <= stacks; ++i) { float v = float(i) / float(stacks); float phi = v * PI; float sp = std::sin(phi); float cp = std::cos(phi); for (int j = 0; j <= slices; ++j) { float u = float(j) / float(slices); float theta = u * 2.0f * PI; Vertex vert; vert.pos = QVector3D(radius * sp * std::cos(theta), radius * cp, radius * sp * std::sin(theta)); vert.nrm = vert.pos.normalized(); vert.uv = QVector2D(u, 1.0f - v); verts.push_back(vert); } } for (int i = 0; i < stacks; ++i) { for (int j = 0; j < slices; ++j) { GLuint a = GLuint(i * (slices + 1) + j); GLuint b = a + GLuint(slices + 1); idx << a << a + 1 << b; idx << a + 1 << b + 1 << b; } } }

关于接缝，有一个取舍要说清楚。我保留了重复的接缝顶点，也就是 j 等于 0 和 j 等于 slices 时位置相同但 UV 不同的两个顶点。这样贴图在接缝处能正确采样到 u 等于 0 和 u 等于 1，不会出现一整条色带。代价是多出一列顶点，对几万个顶点的球来说完全可以接受。如果你图省事合并了接缝顶点，那贴图在 180 度经线上必然出问题，mipmap 一混合就是一条明显的缝。

细分参数的经验值：桌面端做全屏展示，stacks = 64, slices = 128出来的球边缘已经看不出棱角，顶点数约 8300 个，索引数约 49000 个，对现代显卡来说是毛毛雨。如果在低端设备或者嵌入式上跑，降到32 x 64也能看，边缘会稍微有点多边形感，可以用法线插值弥补一部分观感。

4. 纹理贴图与着色器实现

几何搞定之后，画面能不能看就全看纹理和着色器了。这一块我踩过的坑比几何还多，而且每一个坑都特别有迷惑性，因为画面出问题时你很难一眼判断到底是纹理没加载、还是 UV 错了、还是着色器里的采样器没绑上。

4.1 纹理加载的三个必踩之坑

第一个坑是上下颠倒。前面说了球体的 v 坐标做了翻转，但如果贴图本身加载进来时没有处理，两个翻转叠加等于没翻，结果还是反的。Qt 的QImage原点在左上角，而 OpenGL 纹理坐标原点在左下角，标准做法是在上传之前调一次mirrored()。我一般的写法是这样。

QOpenGLTexture *loadEarthTexture(const QString &path) { QImage img(path); if (img.isNull()) { return nullptr; } img = img.convertToFormat(QImage::Format_RGBA8888); img = img.mirrored(false, true); // 垂直翻转，对齐 OpenGL 纹理原点 auto *tex = new QOpenGLTexture(img, QOpenGLTexture::GenerateMipMaps); tex->setWrapMode(QOpenGLTexture::DirectionS, QOpenGLTexture::Repeat); tex->setWrapMode(QOpenGLTexture::DirectionT, QOpenGLTexture::ClampToEdge); tex->setMinificationFilter(QOpenGLTexture::LinearMipMapLinear); tex->setMagnificationFilter(QOpenGLTexture::Linear); return tex; }

这里 S 方向用 Repeat、T 方向用 ClampToEdge，是经过考虑的。经度方向首尾相接，理论上用 Repeat 更自然；但因为我保留了接缝顶点，实际采样不会越界，用 Repeat 只是兜底。纬度方向到极点就结束了，用 ClampToEdge 能避免极点处采样到另一边去。

第二个坑是数据格式。QImage内部可能是 32 位 ARGB，直接丢给 OpenGL 当 RGBA 用，红蓝通道会对调，地球会变成诡异的紫色调。所以上传前必须convertToFormat(QImage::Format_RGBA8888)，把通道顺序钉死。

第三个坑是尺寸与显存。一张 8192 x 4096 的 RGBA8 贴图占 128MB 显存，加上 mipmap 再涨三分之一。很多集成显卡的共享显存根本扛不住，程序会在创建纹理时静默失败或者卡死。我的经验值是桌面独显用 8192 宽，集成显卡压到 4096 宽，移动端 2048 宽。视觉差异在正常观看距离下几乎看不出来，但稳定性差别巨大。

提示：加载贴图一定要检查isNull()并且检查isCreated()。我遇到过一次贴图文件路径写错，纹理对象创建成功但内容全黑，程序没报任何错，排查了半小时才发现是资源没打进包里。

4.2 着色器代码与 uniform 组织

着色器我选的是 GLSL 330 core，对应 OpenGL 3.3 核心模式。这个版本在 Qt 5.12 支持的桌面平台覆盖度最好，语法也比 120 干净得多，in、out、layout这些现代写法都能用。

顶点着色器负责三件事：把顶点变换到裁剪空间、把法线传到片元阶段、把 UV 和世界坐标传下去。世界坐标传下去是为了后面做大气边缘光或者拾取辅助。

#version 330 core layout(location = 0) in vec3 aPos; layout(location = 1) in vec3 aNormal; layout(location = 2) in vec2 aUV; uniform mat4 uModel; uniform mat4 uView; uniform mat4 uProjection; out vec3 vNormal; out vec2 vUV; out vec3 vWorldPos; void main() { vec4 world = uModel * vec4(aPos, 1.0); vWorldPos = world.xyz; vNormal = mat3(uModel) * aNormal; vUV = aUV; gl_Position = uProjection * uView * world; }

片元着色器先做最简单的朗伯光照，一个平行光加环境光，够用且不容易出错。

#version 330 core in vec3 vNormal; in vec2 vUV; in vec3 vWorldPos; uniform sampler2D uEarth; uniform vec3 uLightDir; out vec4 fragColor; void main() { vec3 n = normalize(vNormal); float diff = max(dot(n, normalize(-uLightDir)), 0.0); vec3 base = texture(uEarth, vUV).rgb; vec3 color = base * (0.18 + 0.95 * diff); fragColor = vec4(color, 1.0); }

uniform 的组织有个小技巧：我在渲染器里维护一个QHash<QByteArray, int>缓存 uniform 位置，只在上传着色器之后查一次，后面直接用缓存的整型位置。QOpenGLShaderProgram::uniformLocation每次调用都要走一次字符串查找，在每帧调用的场景下是白白浪费。

4.3 光照方向与大气边缘光的性价比

光照方向这个参数，我建议跟着相机走，也就是让光永远从相机的左前上方打过来。这样无论用户怎么转，地球总有一面是亮的、一面是暗的，立体感一直都在。如果固定在世界坐标里，转到背光面就是一片死黑，用户体验很差。

具体做法是把相机位置转换到世界空间，归一化后加一点偏移作为光方向。

QVector3D camDir = m_camera.position().normalized(); QVector3D lightDir = (camDir + QVector3D(0.35f, 0.55f, 0.25f)).normalized(); m_program.setUniformValue(m_lightLoc, lightDir);

至于大气边缘光，这是提升观感性价比最高的一个效果，代价很小。原理很简单：球体边缘处法线和视线方向接近垂直，此时dot(n, viewDir)接近 0，用这个值做一次幂运算叠加一层淡蓝色，边缘就会亮起来。

vec3 viewDir = normalize(uCameraPos - vWorldPos); float rim = 1.0 - max(dot(n, viewDir), 0.0); rim = pow(rim, 3.0) * 0.6; color += vec3(0.25, 0.45, 0.85) * rim;

这个效果在暗色背景上尤其明显，本来很平的一个球会立刻有"从太空看"的感觉。参数上边缘幂次我调到 3.0，系数 0.6，太强会显得发灰，太弱看不出来，这两个数字我用在不同分辨率下都还算稳。

5. 相机控制与屏幕拾取

一个三维地球好不好用，一半看画面，一半看手感。相机做得不好，用户转两下就晕；拾取做得不准，点哪都偏。

5.1 轨道相机的参数设计

我用的是轨道相机，也叫环绕相机，本质是把相机放在一个球坐标系上，看向球心。状态只有四个量：方位角、俯仰角、距离、目标点。

struct OrbitCamera { float yaw = 0.0f; // 水平角，度 float pitch = 20.0f; // 俯仰角，度 float dist = 3.2f; // 半径 1.0 的地球，3.2 倍距离比较合适 QVector3D target{0, 0, 0}; QVector3D position() const { float y = qDegreesToRadians(yaw); float p = qDegreesToRadians(pitch); return target + QVector3D(dist * std::cos(p) * std::sin(y), dist * std::sin(p), dist * std::cos(p) * std::cos(y)); } };

俯仰角一定要夹在负 89 到正 89 度之间。如果不夹，翻过极点之后画面会突然镜像翻转，用户会瞬间失去方向感。这个限制不是技术限制，是体验限制，我试过放开，结果测试的同事说"点着点着世界就颠倒了"。

距离也要夹范围。下限我设在 1.05，也就是刚好贴着地表，再近就穿进球里了；上限设 12，再远地球就变成一个小点，没意义。滚轮缩放我用指数映射，每格滚轮乘以 0.88，这样无论远近，缩放的手感都是均匀的。线性缩放的问题是近处太快远处太慢，用久了很难受。

鼠标拖拽我做了两档灵敏度：距离远的时候转得快一点，距离近的时候转得慢一点，系数是0.2f * (dist / 3.2f)。这样在贴近地表看细节的时候不会一拖就飞出去。

5.2 从屏幕像素到经纬度的完整链路

拾取这条链路是四个步骤，任何一步错了结果都会偏。

第一步，屏幕坐标转归一化设备坐标。注意 Y 轴要反过来，因为屏幕 Y 向下、NDC 里 Y 向上。

QVector3D GlobeWidget::screenToRay(const QPoint &pt) { float dpr = devicePixelRatioF(); float x = (2.0f * pt.x() * dpr) / width() - 1.0f; float y = 1.0f - (2.0f * pt.y() * dpr) / height(); QMatrix4x4 inv = (m_projection * m_view).inverted(); QVector4D n = inv * QVector4D(x, y, -1.0f, 1.0f); QVector4D f = inv * QVector4D(x, y, 1.0f, 1.0f); n /= n.w(); f /= f.w(); return (f.toVector3D() - n.toVector3D()).normalized(); }

第二步，射线与球求交。用解析解，比逐三角形遍历快几个数量级，而且不需要加速结构。

bool raySphere(const QVector3D &origin, const QVector3D &dir, float radius, QVector3D &hit) { float b = QVector3D::dotProduct(origin, dir); float c = QVector3D::dotProduct(origin, origin) - radius * radius; float disc = b * b - c; if (disc < 0.0f) return false; float t = -b - std::sqrt(disc); if (t < 0.0f) t = -b + std::sqrt(disc); if (t < 0.0f) return false; hit = origin + dir * t; return true; }

这里要特别注意origin是射线起点，通常是相机位置。如果相机在地球内部，c会是负数，第一个解是负的，取第二个解就得到出射点，行为是对的。

第三步，交点转经纬度。这一步的对应关系和贴图映射必须完全一致，否则你点击的位置和显示的位置会差一截。

float lat = std::asin(hit.y() / radius) * 180.0f / PI; float lon = std::atan2(hit.z(), hit.x()) * 180.0f / PI;

第四步，反算 UV 校验。u = (lon + 180) / 360，v = (90 - lat) / 180，用这个去采样贴图应该和渲染出来的颜色一致。我写了一个校验模式，点击后把采样到的像素颜色打印出来，如果和肉眼看到的不一样，说明映射链路上还有错。

心得：atan2的参数顺序是(y, x)，我见过不止一个人写成(x, z)或者(z, x)，结果经度整个错位 90 度。写完之后拿几个已知坐标验证，比如经度 0 纬度 0 应该落在赤道和本初子午线的交点上。

6. 常见问题排查实录

这一节是我这几年积累的问题表，基本覆盖了新手在这条路上会撞到的大部分墙。我把现象、可能原因、排查手段放在一张表里，遇到问题从上往下对一遍，命中率很高。

6.1 黑屏与白屏问题速查

黑屏是最打击人的，因为可能性太多，从上下文没建起来到着色器编译失败都有可能。我的排查顺序是固定的。

其中"只有四分之一画面"这一条，我在 4K 显示器上至少踩过三次。原因是resizeGL(w, h)里直接用了 Qt 传进来的逻辑像素，而glViewport期望的是物理像素。Qt 5.12 默认不开启高 DPI 缩放的话，逻辑像素和物理像素可能是 1:2，视口只覆盖左下角，画面就被裁掉了。

还有一个隐蔽的黑屏原因：着色器编译失败但程序没检查日志，导致link()失败后依然调用了bind()，此时绑定的程序对象是 0，绘制调用被静默忽略。养成习惯，上传完着色器立刻打印log()，编译错误一次就看到了。

if (!m_program.addShaderFromSourceCode(QOpenGLShader::Vertex, vs)) { qWarning() << "VS 编译失败:" << m_program.log(); return; } if (!m_program.link()) { qWarning() << "链接失败:" << m_program.log(); return; }

6.2 纹理与渲染异常的定位方法

纹理类问题有一个通用排查手法：把片元着色器改成直接输出 UV 作为颜色，fragColor = vec4(vUV, 0.0, 1.0)。此时画面应该呈现红绿渐变，红通道沿经度变化，绿通道沿纬度变化。如果渐变方向不对，说明 UV 映射错了；如果渐变正常但贴图还是错的，说明问题出在纹理加载或者采样。

地球贴图出现一条竖直的缝是最典型的接缝问题，原因是接缝处 UV 从接近 1 跳回 0，如果此时开启 mipmap 且采样模式是 Repeat，硬件会取到两端的平均值，出现一条颜色错误的带。保留接缝顶点、S 方向用 ClampToEdge 或者干脆把 u 坐标在临界点微调到 0.001，都能解决。

法线方向反了会导致地球一半全黑，且明暗分界线不是柔和的渐变而是硬的。这种情况直接把法线取反再画一次就能确认。如果取反后画面正常了，说明你的三角形绕序或者法线计算有符号错误，回头检查buildSphere里的交叉方向。

还有一类问题来自投影矩阵。如果近裁剪面设得太小、远裁剪面设得太大，深度精度不够，球面会出现一圈一圈的摩尔纹，看起来像是球面被切成了洋葱。我的设置是近 0.01、远 20，配合半径 1 的球，深度分布非常均匀。有人喜欢照抄教程里的 0.1 到 1000，那在球体尺度上完全是浪费精度。

6.3 性能问题的几种典型来源

三维地球跑到 60 帧不难，但跑到 60 帧同时 CPU 占用低于 10% 就需要一点点功夫了。我遇到的性能问题基本集中在四个地方。

第一是每帧重复创建资源。有人把QOpenGLBuffer和QOpenGLTexture写在paintGL里面，每帧 new 一次，内存泄漏加上驱动同步，帧率会从 60 掉到个位数。资源创建一律放initializeGL，销毁放析构函数。

第二是垂直同步。Qt 默认是否开启取决于平台，某些平台上QSurfaceFormat::setSwapInterval(0)能明显提高帧率，但会带来画面撕裂。我的选择是保持开启，因为视觉体验更重要，而且地球这种场景不需要极限帧率。

第三是过度绘制。如果背景是全屏的星空球，地球又占了大半屏幕，片元着色器的调用次数会翻倍。解决办法是先画背景再画地球，利用深度测试提前剔除；或者把星空做成静态纹理贴在背景四边形上，不要用几何体。

第四是软件渲染回退。Windows 上如果显卡驱动异常，Qt 会自动回退到内置的软件 OpenGL 实现，帧率会掉到 5 帧以下且 CPU 单核跑满。判断方法是打印QOpenGLContext::currentContext()->format().renderableType()和vendorString()，如果看到软件渲染的标识，就是驱动环境问题，需要部署时把对应的回退库一起打包。

7. 从能跑到好用的最后几公里

球体转起来、贴图对了、点击准了，这时候交付其实还差一口气。真正让一个三维地球从"技术演示"变成"能用的产品"的，是后面这些细节，而它们往往在需求文档里一个字都不会提。

7.1 抗锯齿与画面质感的调优

OpenGL 原生的抗锯齿能力有两档，一是多重采样，二是着色器里的后处理。我选前者，因为代价小、代码零改动，只需要在创建上下文之前设置采样数。

QSurfaceFormat fmt; fmt.setVersion(3, 3); fmt.setProfile(QSurfaceFormat::CoreProfile); fmt.setDepthBufferSize(24); fmt.setSamples(4); QSurfaceFormat::setDefaultFormat(fmt);

这段代码必须放在QApplication构造之前，或者至少在第一个 OpenGL 控件创建之前。放晚了不生效，而且不会报错，这是我见过最常见的"设置了但没效果"的原因之一。

采样数不是越高越好。4 倍采样在大多数场景下已经消除了球边缘的锯齿，8 倍会显著增加显存和带宽开销，在集成显卡上可能直接把帧率砍掉一半。我在项目里做过对比，4 倍和 8 倍的视觉差异在 1080p 下要贴着屏幕才能看出来。

还有一个提升质感的小技巧：给球体加一层极淡的背面渲染作为"内壁"，当相机靠近地表时能看到地球另一侧的轮廓，视觉上更有厚度。这个做法要在关闭深度写入的情况下画一遍背面，成本很低。

7.2 后续可以继续扩展的三个方向

第一个方向是瓦片化。现在是一张贴图贴满全球，分辨率上限由单张纹理的尺寸决定。如果要做到城市级，就必须把地球按经纬度切成瓦片金字塔，根据相机距离动态加载对应层级的瓦片。这个改动的核心不在渲染，而在调度：什么时候请求、请求哪个层级、缓存多少张、超出预算淘汰哪些。数据结构和缓存策略往往比渲染代码还长。

第二个方向是标绘系统。标注点、连线、区域面，本质上都是在球面上生成额外的几何体。点用面向相机的四边形，也就是广告牌；线用带状三角形条带，沿大圆插值；面用多边形三角化加上球面投影。这里最麻烦的是深度冲突，标注必须稍微抬高一点点海拔，否则会和地表贴图打架，出现闪烁。

第三个方向是多图层混合。比如在地球上叠加云层、夜光、国界线，这些都是独立纹理。做法是用多个采样器在片元着色器里混合，或者分层渲染多次。我倾向后者，因为每一层的混合公式可能不一样，写在一个着色器里会越来越难维护。

7.3 我在这个项目里最想强调的两条经验

第一条是先把坐标链路用数字钉死，再动手写渲染。我最初的项目里，经纬度、球面坐标、UV、屏幕坐标这四套东西的对应关系是靠记忆维护的，结果每加一个功能就要重新推导一遍，还经常推错。后来我把它们写成一张对照表并且配了一组单元测试，输入经纬度输出世界坐标再输出 UV，跑一遍全绿才允许提交，代码质量立刻稳定下来。

第二条是让渲染器只认数据，不认业务。渲染器里不要出现"国界""城市""轨迹"这些词，它只认识顶点数组和纹理。业务逻辑在上层组装几何体，渲染器负责画。这条规矩让我在后来的迭代里换了三次数据源，渲染器一行没改。

三维地球这个方向，入门门槛其实比想象中低，一个球、一张图、一个相机，两三百行代码就能转起来；但要做好，细节是无底洞，光照、接缝、拾取、性能，每一项都能再挖很久。我的建议是先跑通最小闭环，能转能看，然后对着实际使用中的别扭之处一个个改，比一上来就设计一套完美架构要靠谱得多。