QOpenGLDebugLogger 类

详细描述

简介

OpenGL编程很容易出错。大多数时候，对一个OpenGL函数的调用失败可能会导致整个应用程序的部分功能停止工作，并且在屏幕上没有任何东西被绘制。

确保没有发生错误返回的OpenGL实现的唯一方法是，在每次调用API之后都使用glGetError进行检查。此外，OpenGL错误会累积起来，因此应该始终像这样在一个循环中使用glGetError。

GLenum error = GL_NO_ERROR;
do {
    error = glGetError();
    if (error != GL_NO_ERROR) {
        // handle the error
    }
} while (error != GL_NO_ERROR);

如果你试图清除错误堆栈，确保不仅仅继续到返回GL_NO_ERROR，还要在GL_CONTEXT_LOST上中断，因为这个错误值会不断地重复。

我们还有许多其他感兴趣的信息（作为应用程序开发者），例如性能问题，或关于使用已过时API的警告。这类消息不会通过常规的OpenGL错误报告机制报告。

QOpenGLDebugLogger旨在通过提供对OpenGL调试日志的访问来解决这些问题。如果你的OpenGL实现支持它（通过公开GL_KHR_debug扩展），那么OpenGL服务器的消息将会被记录在内部OpenGL日志中，或者实时传递给监听器，当它们由OpenGL产生时。

QOpenGLDebugLogger支持这两种工作模式。参考以下部分以了解它们之间的差异。

创建OpenGL调试上下文

出于效率原因，OpenGL实现被允许不创建任何调试输出，除非OpenGL上下文是一个调试上下文。要从Qt创建一个调试上下文，必须将QSurfaceFormat::DebugContext格式选项设置在用于创建QOpenGLContext对象的QSurfaceFormat上。

QSurfaceFormat format;
// asks for a OpenGL 3.2 debug context using the Core profile
format.setMajorVersion(3);
format.setMinorVersion(2);
format.setProfile(QSurfaceFormat::CoreProfile);
format.setOption(QSurfaceFormat::DebugContext);

QOpenGLContext *context = new QOpenGLContext;
context->setFormat(format);
context->create();

请注意，请求3.2OpenGL核心配置文件只是为了示例目的；此类不与任何特定的OpenGL或OpenGL ES版本绑定，因为它依赖于GL_KHR_debug扩展（下面将说明）。

创建和初始化QOpenGLDebugLogger

QOpenGLDebugLogger是一个简单的QObject-派生类。就像所有QObject子类一样，你创建一个实例（可以指定父对象），并且正如Qt中的其他OpenGL函数，你必须在使用前调用initialize()来初始化它。

QOpenGLContext *ctx = QOpenGLContext::currentContext();
QOpenGLDebugLogger *logger = new QOpenGLDebugLogger(this);

logger->initialize(); // initializes in the current context, i.e. ctx

请注意，要访问OpenGL记录的消息，上下文中必须GL_KHR_debug扩展必须可用。你可以通过调用它们的存在来检查这个扩展

ctx->hasExtension(QByteArrayLiteral("GL_KHR_debug"));

其中ctx是一个有效的QOpenGLContext。如果扩展不可用，initialize()将返回false。

读取内部OpenGL调试日志

OpenGL实现保留一个调试消息的内部日志。可以使用loggedMessages()函数检索存储在该日志中的消息。

const QList<QOpenGLDebugMessage> messages = logger->loggedMessages();
for (const QOpenGLDebugMessage &message : messages)
    qDebug() << message;

内部日志的大小有限；当它填满时，较旧的消息将被丢弃以为新到来的消息腾出空间。当你调用loggedMessages()时，内部日志也将被清空。

如果您想确保不丢失任何调试信息，必须使用实时日志记录而不是调用此函数。然而，在上下文创建和实时日志激活之间（或者在一般而言，实时日志被禁用时），仍然可能会生成调试信息。

消息的实时日志记录

也可以从OpenGL服务器以生成方式即时接收调试信息流。要执行此操作，您需要将适当的槽连接到 messageLogged() 信号，并通过调用 startLogging() 开始记录。

connect(logger, &QOpenGLDebugLogger::messageLogged, receiver, &LogHandler::handleLoggedMessage);
logger->startLogging();

同样，可以通过调用 stopLogging() 函数在任何时候禁用日志记录。

实时日志可以是异步的或同步的，具体取决于传递给 startLogging() 的参数。在异步模式（默认模式，因为它有很小的开销）中，OpenGL实现可以随时生成消息，并且/或按不同的顺序生成，不同于导致记录消息的OpenGL命令的顺序。这些消息也可以由一个与当前绑定上下文的线程不同的线程生成。这是因为OpenGL实现通常是高度多线程和异步的，因此不保证调试信息的相对顺序和时序。

另一方面，同步模式的日志记录开销很高，但OpenGL实现保证在命令返回之前按顺序接收由某个命令引起的所有消息，并且来自OpenGL上下文绑定的相同线程。

这意味着，在进行同步模式日志记录时，您将能够将OpenGL应用程序在调试器中运行，在连接到 messageLogged() 信号的槽上设置断点，并在调用栈中看到导致记录消息的确切调用。这可以极大地帮助调试OpenGL问题。请注意，如果OpenGL渲染在另一个线程中发生，您必须将信号/槽连接类型强制设置为 Qt::DirectConnection，以便能够看到实际的调用栈。

有关日志记录模式的更多信息，请参阅 LoggingMode 枚举文档。

将消息插入调试日志

应用程序和库可以插入自定义消息到调试日志中，例如为了标记一组相关的OpenGL命令，进而能够识别它们生成的可能消息。

为此，您可以通过调用 QOpenGLDebugMessage 对象的 createApplicationMessage() 或 createThirdPartyMessage() 来创建，然后将它插入到日志中，通过调用 logMessage()。

QOpenGLDebugMessage message =
    QOpenGLDebugMessage::createApplicationMessage(QStringLiteral("Custom message"));

logger->logMessage(message);

请注意，OpenGL实现对于可以插入到调试日志中的消息长度有限制，这是由厂商特定的。您可以通过调用 maximumMessageLength() 方法来检索这个长度；超过限制的消息将被自动截断。

控制系统调试输出

QOpenGLDebugMessage 还可以应用过滤器到调试信息中，从而限制记录的消息数量。您可以通过调用 enableMessages() 和 disableMessages() 分别启用或禁用消息记录。默认情况下，所有消息都会被记录。

可以通过选择以下选项来启用或禁用消息：

• 源、类型和严重性（包括所选的所有id）
• id、源和类型（包括所选的所有严重性）

请注意，特定消息的“启用”状态是（id，源，类型，严重性）元组的属性；消息属性 不 形成一个任何类型的层级结构。应该小心调用 enableMessages() 和 disableMessages() 的顺序，因为它将改变哪些消息被启用/禁用。

无法根据消息文本来进行过滤；应用程序必须自行完成（在连接到 messageLogged() 信号的槽中，或在通过 loggedMessages() 获取内部调试日志后）。

为了简化启用/禁用状态的管理的复杂性，QOpenGLDebugMessage 也支持 调试组 的概念。调试组包含调试消息的启用/禁用配置组。此外，调试组是按堆栈组织的；可以通过调用 pushGroup() 和 popGroup() 分别压栈和出栈组。（当创建OpenGL上下文时，堆栈中已有组）。

函数 enableMessages() 和 disableMessages() 将修改当前调试组的配置，即调试组堆栈顶部的那个。

当新的组被压入调试组堆栈时，它将继承堆栈顶部之前组的配置。反之，出栈调试组将恢复成为新堆栈顶部的调试组的配置。

压入（分别出栈）调试组也将自动生成类型为 QOpenGLDebugMessage::GroupPushType（分别 GroupPopType）的调试信息。