QOpenGLWidget Class

详细说明

QOpenGLWidget 为显示集成到 Qt 应用程序中的 OpenGL 图形提供功能。它的使用非常简单：让您的类继承自它，然后像使用其他QWidget 一样使用子类，只不过您可以选择使用QPainter 或标准 OpenGL 渲染命令。

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

• paintGL() - 渲染 OpenGL 场景。每当需要更新 widget 时都会被调用。
• 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 对象。将 widget 传递给构造函数或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 头文件将包括 qopengl.h，而 qopengl.h 又将包括一个合适的系统头文件。这可能是 OpenGL ES 3.x 或 2.0 头文件（可用的最高版本），也可能是系统提供的 gl.h。此外，Qt 还为 OpenGL 和 OpenGL ES 提供了扩展头文件的副本（在某些系统中称为 glext.h）。在可行的情况下，这些扩展头文件会在平台上自动包含。这意味着来自 ARB、EXT 和 OES 扩展的常量和函数指针类型定义将自动可用。

代码示例

要开始使用，最简单的 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 及以上版本中，这通常不再是问题。

线程

在工作线程上执行屏幕外渲染（例如生成纹理，然后在paintGL() 中用于 GUI/主线程），可通过公开部件的QOpenGLContext 来支持，这样就可以在每个线程上创建与之共享的附加上下文。

在图形用户界面/主线程之外直接向 QOpenGLWidget 的帧缓冲区绘制图形，可以通过重新实现paintEvent() 来实现。必须通过QObject::moveToThread() 更改上下文的线程亲和性。之后，makeCurrent() 和doneCurrent() 就可以在工作线程上使用了。之后要注意将上下文移回 GUI/主线程。

仅为 QOpenGLWidget 触发缓冲区交换是不可能的，因为它没有真正的屏幕原生表面。在图形用户界面线程上，由部件栈来管理组成和缓冲区交换。当一个线程更新完帧缓冲区后，在 GUI/主线程上调用update() 来安排合成。

在图形用户界面/主线程执行合成时，必须格外注意避免使用帧缓冲区。合成开始和结束时，将发出aboutToCompose() 和frameSwapped() 信号。它们是在图形用户界面/主线程上发出的。这意味着通过使用直接连接aboutToCompose() 可以阻塞 GUI/主线程，直到工作线程完成渲染。在此之后，工作线程不得再执行任何呈现操作，直到frameSwapped() 信号发出为止。如果无法接受这种情况，工作线程必须执行双重缓冲机制。这包括使用完全由线程控制的其他渲染目标（如额外的帧缓冲对象）进行绘制，并在适当的时间混合到 QOpenGLWidget 的帧缓冲中。

上下文共享

当多个 QOpenGLWidget 被添加为同一顶层 widget 的子 widget 时，它们的上下文将相互共享。这不适用于属于不同窗口的 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 XML 模块等设置可能会触发更广泛的上下文共享范围，从而可能导致相关资源在应用程序的整个生命周期内都保持有效。因此，最安全、最稳健的方法始终是对 QOpenGLWidget 中使用的所有资源和资源包装器执行显式清理。

限制和其他注意事项

在 QOpenGLWidget 下面放置其他窗口小部件并使 QOpenGLWidget 透明不会导致预期的结果：下面的部件将不可见。这是因为在实践中，QOpenGLWidget 是在所有其他常规的、非 OpenGL 的 widget 之前绘制的，因此透明类型的解决方案是不可行的。其他类型的布局，如在 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 被添加到 widget 层次结构中，顶层窗口的内容将通过基于 OpenGL 的渲染刷新。除 QOpenGLWidget 之外的其他窗口小部件将继续使用基于软件的绘制器绘制其内容，但最终合成是通过 3D API 完成的。

替代方案

在窗口中添加 QOpenGLWidget 可为整个窗口打开基于 OpenGL 的合成。在某些特殊情况下，这种方法可能并不理想，这时就需要使用 QOpenGLWidget 风格的老式行为，即单独的本地子窗口。了解这种方法的局限性（例如涉及重叠、透明度、滚动视图和 MDI 区域时）的桌面应用程序可以使用QOpenGLWindow 和QWidget::createWindowContainer()。这是 QGLWidget 的现代替代方案，由于没有额外的合成步骤，它比 QOpenGLWidget 更快。强烈建议将这种方法的使用限制在别无选择的情况下。请注意，该方案不适合大多数嵌入式和移动平台，而且在某些桌面平台（如 macOS）上也存在问题。稳定的跨平台解决方案始终是 QOpenGLWidget。

立体渲染

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

这将导致paintGL() 在每一帧中被调用两次，每个QOpenGLWidget::TargetBuffer 调用一次。在paintGL() 中，调用currentTargetBuffer() 来查询当前绘制的是哪一个。

OpenGL 是 Silicon Graphics 公司在美国和其他国家的商标。