QOpenGLWidget 类

详细描述

QOpenGLWidget 提供了将 OpenGL 图形集成到 Qt 应用中的功能。使用非常简单：让你的类继承自它，并像使用其他任何 QWidget 一样使用子类，只不过你可以选择使用 QPainter 或标准的 OpenGL 绘制命令。

QOpenGLWidget 提供了三个方便的虚拟函数，你可以在你的子类中重新实现它们来执行典型的 OpenGL 任务

• paintGL() - 绘制 OpenGL 场景。每次小部件需要更新时都会调用。
• resizeGL() - 设置 OpenGL 视口、投影等。每次小部件被调整大小（并在第一次显示时，因为所有新创建的小部件都会自动收到一个调整大小事件）时都会调用。
• initializeGL() - 设置 OpenGL 资源和状态。在首次调用 resizeGL() 或 paintGL() 之前调用一次。

如果您需要从非 paintGL() 的地方触发重绘（一个典型的例子是在使用 定时器 进行场景动画时），您应调用小部件的 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命令。但是，必须确保这些命令被painter的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调用的前缀的替代方案，可以在initializeGL()中从QOpenGLFunctions继承并调用QOpenGLFunctions::initializeOpenGLFunctions()。

至于OpenGL头文件，请注意，在大多数情况下，将不需要直接包含诸如GL.h之类的任何头文件。OpenGL相关 Qt 头文件将包含qopengl.h，它将进而包含适合系统的适当头文件。这可能是OpenGL ES 3.x或2.0头文件，这是可获得的最高的版本，或者是一个系统提供的gl.h。此外，作为Qt的一部分，提供了与OpenGL和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();
}

多重采样

要启用多重采样，请在传递给QSurfaceFormat的参数中设置请求的样本数，并在setFormat()上设置。在不支持它的系统上，请求可能会被忽略。

多重采样支持需要支持多采样渲染缓冲区和帧缓冲区重填。在OpenGL ES 2.0实现中，这些可能不存在。这意味着无法使用多重采样。在现代OpenGL版本和OpenGL ES 3.0及以上版本中，这通常不再成问题。

线程

例如，在辅助线程上执行离屏渲染以生成在GUI/main线程中的paintGL()中使用的纹理，支持通过在每个线程上创建共享此上下文的附加上下文来公开小部件的QOpenGLContext。

在GUI/main线程之外直接向paintEvent()绘制到QOpenGLWidget的帧缓冲区是可能的，通过重写它是空的。必须通过QObject::moveToThread()更改上下文的线程亲和性。之后，makeCurrent()和doneCurrent()在辅助线程上可行。注意之后将上下文恢复到GUI/main线程。

由于没有真正的、屏幕上的原生表面，因此无法仅仅为QOpenGLWidget触发缓冲区交换。管理组成和缓冲区交换的责任在于小部件堆栈，在gui线程上。当线程完成更新帧缓冲区时，请在GUI/main线程上调用update()来安排组成。

必须格外小心，以避免在GUI/main线程执行组合期间使用帧缓冲区。当组合开始和结束时，将发出信号aboutToCompose()和frameSwapped()。这些信号在GUI/main线程上发出。这意味着通过使用直接的连接aboutToCompose()将阻止GUI/main线程，直到辅助线程完成其渲染。之后，辅助线程必须停止进一步的渲染，直到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的父机制进行延迟删除。无法保证在问题实例真正被销毁时上下文 bude 当前上下文。

典型子类在资源初始化和销毁方面的外观通常如下所示

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 透明不会导致预期的结果：下面的部件不会可见。这是因为实际中，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的默认行为相匹配，即在每一帧中使颜色和辅助缓冲区无效。要恢复保留行为，请调用setUpdateBehavior()并使用PartialUpdate。

一旦QOpenGLWidget被添加到窗口层次结构中，顶层窗口的内容将通过OpenGL-based rendering刷新。除了QOpenGLWidget之外的控件将继续使用软件化的画家绘制其内容，但最终的合成是通过3D API完成的。

替代方案

将QOpenGLWidget添加到窗口中将为整个窗口开启基于OpenGL的合成。在某些特殊情况下，这可能不是理想的，而希望使用类似QGLWidget的旧样式行为，带有单独的、本地的子窗口。理解此方法局限性的桌面应用程序（例如，在重叠、透明度、滚动视图和MDI区域时）可以使用QOpenGLWindow与QWidget::createWindowContainer()。这是QGLWidget的现代替代品，由于没有额外的合成步骤，速度比QOpenGLWidget快。强烈建议将此方法的用途限制在没有其他选择的情况下。请注意，此选项对于大多数嵌入式和移动平台来说不合适，并且已知在某些桌面平台（如macOS）上存在一些问题。始终推荐使用稳定的跨平台解决方案，即QOpenGLWidget。

立体渲染

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

这将会触发在每个帧中调用 paintGL() 两次，一次对应每个 QOpenGLWidget::TargetBuffer。在 paintGL() 中调用 currentTargetBuffer() 来查询当前正在绘制到哪一个。

OpenGL是硅 Graphics，Inc. 在美国及其他国家的注册商标。