📚 课程目录第3章 Qt图形架构

3. Qt图形架构

在 Qt 中做 OpenGL ES 集成，最容易踩坑的地方不是着色器语法，而是“我到底把 GL 画到了哪一层窗口上”。Qt 的图形栈并不是单一渲染路径，而是由 QWidget 光栅栈、QQuickWindow 场景图栈、QOpenGLWidget 的 FBO 合成栈共同组成。理解它们之间的层级、线程与上下文关系，才能决定 OpenGL ES 代码应该写在哪里、何时调用、如何与 Qt 的绘制循环对齐。

一、核心原理：四条图形路径与一个函数入口

Qt 图形栈可以按“窗口承载者”和“绘制执行者”两个维度拆开看：

QWidget：传统光栅化窗口系统。默认使用 CPU 光栅引擎（Raster）绘制到 QBackingStore，再交给平台窗口。它本身不直接暴露 OpenGL 上下文，但可以通过 QOpenGLWidget 或 QOpenGLWindow 嵌入 GL 渲染。
QQuickWindow：QML 场景图的宿主窗口。它内部使用 QSGRenderer，默认后端是 OpenGL（也可切换为 Vulkan、Metal、软件后端）。QML 的每个 Item 最终被编译成场景图节点，在渲染线程中批量提交 GL 命令。
QOpenGLWidget：QWidget 体系中的 GL 容器。它并不直接把 GL 画到屏幕，而是先渲染到一个 FBO（帧缓冲对象），再由 Qt 把该 FBO 作为纹理合成到 QWidget 的 backing store 中。因此它天然支持与普通 QWidget 混合布局。
QOpenGLFunctions：OpenGL ES 2.0/3.0 的函数入口封装。它解决了不同平台 GL 函数地址不一致的问题，提供 glClear、glDrawArrays、glCreateProgram 等标准接口。在 Qt 中，任何 GL 调用都应通过它或它的子类进行。

关键结论：QWidget 是“窗口容器”，QQuickWindow 是“场景图渲染器”，QOpenGLWidget 是“FBO 合成器”，QOpenGLFunctions 是“GL 函数入口”。四者不是替代关系，而是不同层级上的协作关系。

二、方法流程：一次 GL 绘制的完整链路

以 QOpenGLWidget 为例，一次典型的 OpenGL ES 绘制流程如下：

QWidget 布局系统为 QOpenGLWidget 分配几何区域。
Qt 创建离屏 FBO，并绑定 OpenGL 上下文。
调用 initializeGL()，此时通过 QOpenGLFunctions 初始化着色器、VBO、纹理。
调用 resizeGL(w,h)，设置视口与投影矩阵。
调用 paintGL()，执行 glClear、glUseProgram、glDrawArrays 等命令。
Qt 将 FBO 纹理合成到 QWidget 的 backing store，最终由平台窗口显示。

而在 QQuickWindow 中，流程不同：QML 引擎先构建场景图，渲染线程调用 QSGRenderer::render()，再通过 QQuickWindow::beforeRendering() 或 afterRendering() 信号插入自定义 GL 命令。此时必须使用 QQuickWindow::openglContext() 获取上下文，并确保在渲染线程中调用 GL 函数。

// QOpenGLWidget 中的典型 GL 初始化
void MyGLWidget::initializeGL() {
    initializeOpenGLFunctions();          // 绑定 QOpenGLFunctions
    glClearColor(0.1f, 0.2f, 0.3f, 1.0f);
    m_program.addShaderFromSourceCode(QOpenGLShader::Vertex, vs);
    m_program.addShaderFromSourceCode(QOpenGLShader::Fragment, fs);
    m_program.link();
}

void MyGLWidget::paintGL() {
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
    m_program.bind();
    glDrawArrays(GL_TRIANGLES, 0, 3);
    m_program.release();
}

三、案例场景：QML 中嵌入自定义 GL 渲染

假设我们有一个 QQuickWindow，希望在 QML 界面下方叠加一个自定义 OpenGL ES 渲染的三角形。做法是：连接 QQuickWindow::beforeRendering() 信号，在槽函数中调用 GL 命令。注意此时 QML 场景图已经准备好，但尚未提交绘制，因此自定义 GL 内容会先于 QML 内容绘制，形成背景层。

QObject::connect(window, &QQuickWindow::beforeRendering,
                 this, &MyRenderer::paint, Qt::DirectConnection);

void MyRenderer::paint() {
    window->beginExternalCommands();   // 确保 GL 状态与场景图隔离
    glClear(GL_COLOR_BUFFER_BIT);
    m_program.bind();
    glDrawArrays(GL_TRIANGLES, 0, 3);
    m_program.release();
    window->endExternalCommands();
}

如果使用 QOpenGLWidget，则可以直接在 paintGL() 中绘制，Qt 会自动处理 FBO 合成。两者最大的区别是：QQuickWindow 的 GL 调用发生在渲染线程，而 QOpenGLWidget 的 GL 调用发生在 GUI 线程（默认情况下）。

四、误区与复盘：常见错误与排查清单

误区一：在 QWidget 的 paintEvent() 中直接调用 glDrawArrays。QWidget 默认没有当前 GL 上下文，必须通过 QOpenGLWidget 或 QOpenGLWindow 才能获得有效上下文。

误区二：在 QQuickWindow 的 GUI 线程中调用 GL 函数。QQuickWindow 的 GL 上下文属于渲染线程，跨线程调用会导致未定义行为或崩溃。

误区三：忘记调用 initializeOpenGLFunctions()。QOpenGLFunctions 的函数指针需要初始化后才能使用，否则会直接崩溃。

排查时可按以下清单逐项确认：

检查项	QOpenGLWidget	QQuickWindow
GL 上下文所在线程	GUI 线程	渲染线程
函数入口	QOpenGLFunctions	QOpenGLFunctions + beginExternalCommands
绘制目标	FBO，再合成到 QWidget	直接绘制到窗口表面
与 QML 混合	不直接混合	通过 before/afterRendering 插入
典型入口函数	initializeGL / paintGL	beforeRendering / afterRendering

复盘来看，Qt 图形栈的设计哲学是“分层解耦”：QWidget 负责窗口与事件，QQuickWindow 负责场景图与渲染线程，QOpenGLWidget 负责 FBO 合成，QOpenGLFunctions 负责 GL 函数入口。只要明确每一层负责什么、GL 上下文属于谁、绘制发生在哪个线程，就能在 Qt 中稳定地集成 OpenGL ES，而不会陷入“画不出来”或“随机崩溃”的困境。