QOpenGLWidget是Qt中唯一推荐的OpenGL嵌入方式，需继承使用且QSurfaceFormat须在QApplication前设置；initializeGL仅创建资源，状态设置应放在paintGL开头，并用width()/height()设glViewport。
QOpenGLWidget 是 Qt 里唯一靠谱的嵌入方式
Qt 官方早已弃用 QGLWidget，从 Qt 5.4 起主推 QOpenGLWidget。它不是“包装 OpenGL”，而是把 OpenGL 上下文和 Qt 的 widget 生命周期对齐——渲染在 paintGL 里做，resize 在 resizeGL 里处理，初始化在 initializeGL 里完成。硬上原生 wglCreateContext 或 eglCreateContext 会和 Qt 的事件循环、线程模型冲突，轻则黑屏，重则崩溃。
常见错误现象：QOpenGLContext::makeCurrent() failed、paintGL not called、窗口 resize 后纹理错位。根本原因往往是手动管理上下文，或误以为继承 QWidget + 自己调 glXMakeCurrent 就能绕过 Qt。
- 必须继承
QOpenGLWidget，不能只靠QOpenGLContext+ 普通QWidget -
QSurfaceFormat必须在QApplication构造前设置，否则 MSAA、OpenGL 版本等配置无效 - 若需共享纹理/缓冲区给其他线程（如解码线程），得显式调用
context()->shareContext()，且共享上下文必须同属一个QOpenGLContextGroup
initializeGL 里别直接调 glClearColor 等状态函数
initializeGL 的作用是创建资源（着色器、VBO、VAO、纹理），不是设默认状态。此时 OpenGL 上下文虽已激活，但 widget 尚未完成布局，视口尺寸不可靠。提前调 glClearColor 或 glEnable(GL_DEPTH_TEST) 看似无害，实则埋雷：如果 widget 被隐藏后又显示，Qt 可能重建上下文，而这些状态不会自动恢复，导致后续渲染异常（比如深度测试失效却查不出原因）。
使用场景：初始化阶段只做三件事——编译链接着色器、生成并绑定 VAO/VBO、加载纹理。所有状态设置（清屏色、混合模式、深度测试）统一挪到 paintGL 开头。
立即学习“C++免费学习笔记（深入）”；
-
glGenBuffers、glCreateShader、glTexImage2D放initializeGL -
glClearColor、glEnable、glViewport放paintGL开头 - 若需跨帧保持状态（如启用 blending），在
paintGL结尾用glDisable显式关掉，避免污染下一帧
paintGL 中 glViewport 必须用 widget 尺寸，别信 devicePixelRatio
Qt 高分屏适配靠 devicePixelRatio()，但 QOpenGLWidget 内部已自动将 framebuffer 缩放，你拿到的 width() 和 height() 就是逻辑像素尺寸，对应正确的 framebuffer 大小。手动乘 devicePixelRatio() 会导致视口超出 framebuffer 边界，渲染内容被裁剪或拉伸。
性能影响：错误计算 glViewport 不仅出图错，还会触发 Qt 内部的 framebuffer 重分配，频繁 resize 时卡顿明显。
- 正确写法：
glViewport(0, 0, width(), height()) - 错误写法：
glViewport(0, 0, width() * devicePixelRatio(), height() * devicePixelRatio()) - 检查是否生效：在
paintGL开头加qDebug() ，确认三者关系符合预期
多线程渲染必须用 QOpenGLFunctions_XXX，别混用 glew 或 gl3w
QOpenGLWidget 的 OpenGL 函数指针由 QOpenGLFunctions 子类提供，它们和当前上下文绑定。若在非 paintGL 线程（如后台计算线程）里用 glewInit() 或 gl3wInit() 获取函数地址，会拿到错误的函数表，导致 glDrawArrays 崩溃或静默失败。
兼容性影响：不同平台 OpenGL 扩展暴露方式不同，glew 默认走 WGL/EGL/GLEW_GET_FUN，而 Qt 的 QOpenGLFunctions 走 QOpenGLContext::getProcAddress，二者不互通。
- 所有 OpenGL 调用（包括线程内）必须通过
QOpenGLFunctions_4_1_Core（按实际版本选）实例调用，例如functions->glDrawArrays(...) - 线程中使用前，先调
context->makeCurrent(surface)，再用context->functions()获取函数指针 - 绝对不要在 .cpp 里 #include <GL/glew.h> 或 <GL/gl3w.h>，Qt 自带的 OpenGL 头已足够
最易被忽略的是上下文归属——哪怕你在线程里正确调了 makeCurrent，如果这个 QOpenGLContext 没和 QOpenGLWidget 的 context 共享资源（比如没传 widget->context() 作父上下文），纹理就无法跨线程访问。共享不是默认行为，得手写那行 newContext->setShareContext(widget->context())。
