QOpenGLWidget Class

详细说明

Qt OpenGL Widget 提供将 OpenGL 图形集成到 Qt 应用程序中的功能。其使用非常简单：让您的类继承自该类，并像使用其他QWidget 一样使用该子类，唯一的区别在于您可以选择使用QPainter 还是标准 OpenGL 渲染命令。

QOpenGLWidget 提供了三个便捷的虚函数，您可以在子类中重写这些函数以执行典型的 OpenGL 任务：

• paintGL() - 渲染 OpenGL 场景。每当小部件需要更新时，该函数都会被调用。
• resizeGL() - 设置 OpenGL 视口、投影等。每当控件被调整大小时都会被调用（在首次显示时也会被调用，因为所有新创建的控件都会自动触发调整大小事件）。
• initializeGL() - 配置 OpenGL 资源和状态。在首次调用 `resizeGL()` 或 `paintGL()` 之前会调用一次。

如果您需要从paintGL()以外的地方触发重绘（一个典型的例子是使用timers 来动画化场景），则应调用控件的update()函数来安排更新。

当调用paintGL()、resizeGL() 或initializeGL() 时，您的控件的 OpenGL 渲染上下文会被设为当前上下文。如果您需要从其他位置（例如在控件的构造函数中或您自己的绘制函数中）调用标准的 OpenGL API 函数，则必须先调用makeCurrent()。

所有渲染操作均在 OpenGL 帧缓冲区对象中进行。makeCurrent() 确保该对象已在上下文中绑定。在paintGL() 的渲染代码中创建和绑定额外的帧缓冲区对象时，请牢记这一点。切勿重新绑定 ID 为 0 的帧缓冲区。相反，应调用defaultFramebufferObject() 来获取应绑定的 ID。

当平台支持时，QOpenGLWidget 允许使用不同的 OpenGL 版本和配置文件。 只需通过setFormat() 设置所需的格式即可。但请注意，在同一窗口中存在多个 QOpenGLWidget 实例时，它们必须使用相同的格式，或者至少使用不会导致上下文无法共享的格式。为解决此问题，建议优先使用QSurfaceFormat::setDefaultFormat() 而不是setFormat()。

绘制技术

如上所述，请通过以下方式继承 QOpenGLWidget 类以渲染纯 3D 内容：

• 重写initializeGL()和resizeGL()函数，以设置OpenGL状态并提供透视变换。
• 重写paintGL() 函数来绘制 3D 场景，且仅调用 OpenGL 函数。

还可以通过QPainter 在 QOpenGLWidget 的子类上绘制 2D 图形：

• 在 `paintGL()` 中，不要发出 OpenGL 命令，而是构建一个 `QPainter ` 对象以供小部件使用。
• 使用QPainter 的成员函数绘制基本图形。
• 仍然可以直接发出 OpenGL 命令。但是，必须确保这些命令被画家对象的 beginNativePainting() 和 endNativePainting() 调用所包围。

当仅使用QPainter 进行绘制时，也可以像处理普通控件那样进行绘制：通过重写paintEvent()方法。

• 重写paintEvent() 函数。
• 构建一个以该小部件为目标的QPainter 对象。可将小部件传递给构造函数，或传递给QPainter::begin() 函数。
• 使用QPainter 的成员函数绘制基元。
• 绘制完成后，QPainter 实例将被销毁。或者，可以显式调用QPainter::end()。

OpenGL 函数调用、头文件和 QOpenGLFunctions

在调用 OpenGL 函数时，强烈建议避免直接调用函数。相反，应优先使用QOpenGLFunctions （当开发可移植应用程序时），或使用带版本号的变体（例如，当针对现代、仅限桌面的 OpenGL 时，使用QOpenGLFunctions_3_2_Core 及类似函数）。 这样，应用程序将在所有 Qt 构建配置中正常运行，包括那些执行动态 OpenGL 实现加载的配置——这意味着应用程序不会直接链接到 GL 实现，因此无法进行直接函数调用。

在 `paintGL()` 中，可通过调用 `QOpenGLContext::currentContext()` 随时访问当前上下文。从该上下文中，可通过调用 `QOpenGLContext::functions()` 获取一个已初始化、可直接使用的 `QOpenGLFunctions ` 实例。除了在每个 GL 调用前添加前缀外，另一种方法是继承自 `QOpenGLFunctions `，并在 `initializeGL()` 中调用 `QOpenGLFunctions::initializeOpenGLFunctions()`。

关于 OpenGL 头文件，请注意在大多数情况下无需直接包含 GL.h 等头文件。与 OpenGL 相关的 Qt OpenGL 头文件会包含 qopengl.h，而该头文件会自动包含适用于该系统的相应头文件。 这可能是 OpenGL ES 3.x 或 2.0 的头文件、可用的最高版本，或是系统提供的 gl.h。 此外，Qt OpenGL 和 Qt OpenGL ES 提供了扩展头文件（在某些系统上称为 glext.h）的副本。在可行的情况下，这些头文件将在平台上自动包含。这意味着来自 ARB、EXT、OES 扩展的常量和函数指针 typedef 将自动可用。

代码示例

入门时，最简单的 QOpenGLWidget 子类可以如下所示：

class MyGLWidget : public QOpenGLWidget
{
public:
    MyGLWidget(QWidget *parent) : QOpenGLWidget(parent) { }

protected:
    void initializeGL() override
    {
        // Set up the rendering context, load shaders and other resources, etc.:
        QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
        f->glClearColor(1.0f, 1.0f, 1.0f, 1.0f);
        ...
    }

    void resizeGL(int w, int h) override
    {
        // Update projection matrix and other size related settings:
        m_projection.setToIdentity();
        m_projection.perspective(45.0f, w / float(h), 0.01f, 100.0f);
        ...
    }

    void paintGL() override
    {
        // Draw the scene:
        QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
        f->glClear(GL_COLOR_BUFFER_BIT);
        ...
    }

};

或者，也可以通过继承自QOpenGLFunctions 来避免为每个OpenGL调用添加前缀：

class MyGLWidget : public QOpenGLWidget, protected QOpenGLFunctions
{
    ...
    void initializeGL() override
    {
        initializeOpenGLFunctions();
        glClearColor(...);
        ...
    }
    ...
};

若要获取与特定 OpenGL 版本或配置文件兼容的上下文，或请求深度和模板缓冲区，请调用setFormat()：

QOpenGLWidget *widget = new QOpenGLWidget(parent);
QSurfaceFormat format;
format.setDepthBufferSize(24);
format.setStencilBufferSize(8);
format.setVersion(3, 2);
format.setProfile(QSurfaceFormat::CoreProfile);
widget->setFormat(format); // must be called before the widget or its parent window gets shown

对于 OpenGL 3.0 及以上版本的上下文，当可移植性不是关键考虑因素时，带版本号的 `QOpenGLFunctions ` 变体可方便地访问给定版本中所有可用的现代 OpenGL 函数：

    ...
    void paintGL() override
    {
        QOpenGLFunctions_3_2_Core *f = QOpenGLContext::currentContext()->versionFunctions<QOpenGLFunctions_3_2_Core>();
        ...
        f->glDrawArraysInstanced(...);
        ...
    }
    ...

如上所述，将请求的格式全局设置更为简单且稳健，这样在应用程序生命周期内，该设置将适用于所有窗口和上下文。以下是一个示例：

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QSurfaceFormat format;
    format.setDepthBufferSize(24);
    format.setStencilBufferSize(8);
    format.setVersion(3, 2);
    format.setProfile(QSurfaceFormat::CoreProfile);
    QSurfaceFormat::setDefaultFormat(format);

    MyWidget widget;
    widget.show();

    return app.exec();
}

多采样

要启用多采样，请在传递给 `setFormat()` 的 `QSurfaceFormat ` 上设置所需采样数。在不支持多采样的系统上，该请求可能会被忽略。

多采样功能需要系统支持多采样渲染缓冲区和帧缓冲区复制操作。 在 OpenGL ES 2.0 的实现中，这些功能很可能不存在。这意味着将无法使用多采样。在现代 OpenGL 版本以及 OpenGL ES 3.0 及更高版本中，这通常已不再是问题。

多线程

通过公开控件的QOpenGLContext ，可在各线程上创建与之共享的额外渲染上下文，从而支持在工作线程上执行离屏渲染（例如生成纹理，随后在GUI/主线程的paintGL()中使用）。

通过重新实现paintEvent()使其不执行任何操作，即可在 GUI/主线程之外直接向 QOpenGLWidget 的帧缓冲区绘制。必须通过QObject::moveToThread() 更改上下文的线程亲和性。之后，makeCurrent() 和doneCurrent() 即可在工作线程上使用。 请注意，之后务必将上下文移回 GUI/主线程。

无法仅针对 QOpenGLWidget 触发缓冲区交换，因为它没有真正的、显示在屏幕上的本机绘制表面。在 GUI 线程上管理合成和缓冲区交换是小部件堆栈的职责。当一个线程完成对帧缓冲区的更新后，应在 GUI/主线程上调用update() 来调度合成操作。

必须格外注意，避免在 GUI/主线程执行合成操作时使用帧缓冲区。当合成开始和结束时，将发出aboutToCompose() 和frameSwapped() 信号。这些信号是在 GUI/主线程上发出的。 这意味着，如果使用直接连接，aboutToCompose() 可能会阻塞 GUI/主线程，直到工作线程完成渲染为止。此后，工作线程必须停止进一步渲染，直到发出frameSwapped() 信号为止。 如果这种情况无法接受，则工作线程必须实现双缓冲机制。这涉及使用由该线程完全控制的替代渲染目标（例如一个额外的帧缓冲区对象）进行绘制，并在适当的时候将其复制到 QOpenGLWidget 的帧缓冲区中。

上下文共享

当多个 QOpenGLWidget 作为子控件添加到同一个顶级控件时，它们的上下文将相互共享。这不适用于属于不同窗口的 QOpenGLWidget 实例。

这意味着同一窗口中的所有 QOpenGLWidget 都可以访问彼此的可共享资源（如纹理），无需额外的“全局共享”上下文。

要设置属于不同窗口的 QOpenGLWidget 实例之间的共享，请在实例化QApplication 之前设置Qt::AA_ShareOpenGLContexts 应用程序属性。这将触发所有 QOpenGLWidget 实例之间的共享，无需任何额外步骤。

也可以创建额外的QOpenGLContext 实例，使其与QOpenGLWidget的上下文共享纹理等资源。只需在调用QOpenGLContext::create()之前，将context()返回的指针传递给QOpenGLContext::setShareContext()即可。生成的上下文还可以在不同的线程上使用，从而支持多线程生成纹理和异步纹理上传。

请注意，在底层图形驱动程序方面，QOpenGLWidget 期望驱动程序提供符合标准的资源共享实现。例如，某些驱动程序（特别是针对移动设备和嵌入式硬件的驱动程序）在为现有上下文与后续创建的上下文之间建立共享时会出现问题。还有些驱动程序在尝试在不同线程之间使用共享资源时，可能会表现出意料之外的行为。

资源初始化和清理

每当调用initializeGL()和paintGL()时，QOpenGLWidget关联的OpenGL上下文均保证处于活动状态。请勿在调用initializeGL()之前尝试创建OpenGL资源。例如，若在子类的构造函数中尝试编译着色器、初始化顶点缓冲对象或上传纹理数据，都会导致操作失败。 这些操作必须推迟到initializeGL() 时执行。Qt OpenGL 辅助类（如QOpenGLBuffer 或QOpenGLVertexArrayObject ）具有相应的延迟行为：它们可以在没有上下文的情况下实例化，但所有初始化操作都会推迟到调用create() 或类似函数时才进行。 这意味着它们可以在 QOpenGLWidget 子类中作为普通的（非指针）成员变量使用，但create() 或类似函数只能在initializeGL() 中调用。 但请注意，并非所有类都采用这种设计。如有疑问，请将成员变量定义为指针，并分别在initializeGL()中动态创建实例，在析构函数中动态销毁实例。

释放资源时，上下文也必须处于活动状态。因此，执行此类清理操作的析构函数应在销毁任何 OpenGL 资源或封装类之前，先调用 `makeCurrent()`。请避免通过 `deleteLater()` 或 `QObject` 的父子关系机制进行延迟删除。因为无法保证在相关实例真正被销毁时，正确的上下文仍处于活动状态。

因此，在资源初始化和销毁方面，典型的子类通常如下所示：

class MyGLWidget : public QOpenGLWidget
{
    ...

private:
    QOpenGLVertexArrayObject m_vao;
    QOpenGLBuffer m_vbo;
    QOpenGLShaderProgram *m_program;
    QOpenGLShader *m_shader;
    QOpenGLTexture *m_texture;
};

MyGLWidget::MyGLWidget()
    : m_program(0), m_shader(0), m_texture(0)
{
    // No OpenGL resource initialization is done here.
}

MyGLWidget::~MyGLWidget()
{
    // Make sure the context is current and then explicitly
    // destroy all underlying OpenGL resources.
    makeCurrent();

    delete m_texture;
    delete m_shader;
    delete m_program;

    m_vbo.destroy();
    m_vao.destroy();

    doneCurrent();
}

void MyGLWidget::initializeGL()
{
    m_vao.create();
    if (m_vao.isCreated())
        m_vao.bind();

    m_vbo.create();
    m_vbo.bind();
    m_vbo.allocate(...);

    m_texture = new QOpenGLTexture(QImage(...));

    m_shader = new QOpenGLShader(...);
    m_program = new QOpenGLShaderProgram(...);

    ...
}

这种做法在大多数情况下可行，但作为通用解决方案并不完全理想。当小部件被重新关联到父窗口，从而最终位于一个完全不同的顶级窗口中时，还需要采取额外措施：通过订阅 `QOpenGLContext` 的 `aboutToBeDestroyed()` 信号，可以在 OpenGL 上下文即将被释放时执行清理操作。

MyGLWidget::~MyGLWidget()
{
    cleanup();
}

void MyGLWidget::initializeGL()
{
    ...
    connect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}

void MyGLWidget::cleanup()
{
    makeCurrent();
    delete m_texture;
    m_texture = 0;
    ...
    doneCurrent();
    disconnect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}

由于上下文共享，正确的清理工作尤为重要。尽管每个 QOpenGLWidget 的关联上下文会随 QOpenGLWidget 一起销毁，但该上下文中的可共享资源（如纹理）将保持有效，直到包含该 QOpenGLWidget 的顶级窗口被销毁为止。 此外，Qt::AA_ShareOpenGLContexts 等设置以及某些Qt模块可能会触发更广泛的上下文共享范围，这可能导致相关资源在应用程序的整个生命周期内都保持活动状态。因此，最安全且最稳健的做法是始终对QOpenGLWidget中使用的所有资源和资源封装器进行显式清理。

限制与其他注意事项

将其他小部件放置在 QOpenGLWidget 下方并使其透明，不会产生预期的效果：下方的 widget 将不可见。这是因为实际上 QOpenGLWidget 会在所有其他常规（非 OpenGL）小部件之前被绘制，因此此类“透明”解决方案并不可行。 其他类型的布局（例如将小部件放置在 QOpenGLWidget 之上）将按预期工作。

在绝对必要的情况下，可以通过在 QOpenGLWidget 上设置Qt::WA_AlwaysStackOnTop 属性来克服这一限制。 但请注意，这会破坏堆叠顺序，例如将无法在 QOpenGLWidget 上方放置其他小部件，因此仅应在需要半透明的 QOpenGLWidget 且其下方其他小部件可见的情况下使用。

请注意，当下方没有其他小部件且目的是创建一个半透明窗口时，此限制不适用。在这种情况下，在顶级窗口上设置Qt::WA_TranslucentBackground 的传统方法就足够了。 请注意，如果仅希望在 QOpenGLWidget 中实现透明区域，则在启用 `Qt::WA_TranslucentBackground` 之后，需要将 `Qt::WA_NoSystemBackground ` 重新设置为 `false `。此外，根据系统情况，可能还需要通过 `setFormat()` 为 QOpenGLWidget 的上下文请求一个 alpha 通道。

QOpenGLWidget 支持多种更新行为，与QOpenGLWindow 类似。在保留模式下，上一次paintGL() 调用渲染的内容可在下次调用中使用，从而支持增量渲染。在非保留模式下，内容将被丢失，此时paintGL() 的实现需要重新绘制视图中的所有内容。

在 Qt 5.5 之前，QOpenGLWidget 的默认行为是在paintGL() 调用之间保留已渲染的内容。自 Qt 5.5 起，默认行为改为不保留，因为这能提供更好的性能，且大多数应用程序并不需要之前的内容。 这与基于 OpenGL 的QWindow 的语义相似，也符合QOpenGLWindow 的默认行为——即每帧都会使颜色和辅助缓冲区失效。若要恢复保留内容的行为，请使用PartialUpdate 参数调用setUpdateBehavior()。

一旦将 QOpenGLWidget 添加到控件层次结构中，顶级窗口的内容将通过基于 OpenGL 的渲染进行刷新。除 QOpenGLWidget 以外的控件仍会使用基于软件的绘制器来绘制其内容，但最终的合成操作是通过 3D API 完成的。

替代方案

将 QOpenGLWidget 添加到窗口中会为整个窗口启用基于 OpenGL 的合成。在某些特殊情况下，这可能并不理想，此时需要采用旧式的 QGLWidget 风格行为，即使用单独的原生子窗口。 了解此方法局限性（例如在重叠、透明度、滚动视图和 MDI 区域方面）的桌面应用程序，可以使用QOpenGLWindow 配合QWidget::createWindowContainer()。这是 QGLWidget 的现代替代方案，由于省去了额外的合成步骤，其运行速度比 QOpenGLWidget 更快。 强烈建议仅在别无选择的情况下才使用此方法。请注意，此选项不适用于大多数嵌入式和移动平台，且已知在某些桌面平台（如 macOS）上也存在问题。稳定且跨平台的解决方案始终是 QOpenGLWidget。

立体渲染

从 6.5 版本开始，QOpenGLWidget 支持立体渲染。要启用该功能，请在创建窗口之前，使用 QSurfaceFormat::SetDefaultFormat() 全局设置QSurfaceFormat::StereoBuffers 标志。

这将触发每帧调用两次paintGL()，每次针对一个QOpenGLWidget::TargetBuffer 。在paintGL()中，调用currentTargetBuffer()来查询当前正在绘制的是哪个缓冲区。

OpenGL 是 Silicon Graphics, Inc. 在美国和其他国家/地区的注册商标。