QOpenGLDebugLogger Class

Ausführliche Beschreibung

Einleitung

Die OpenGL-Programmierung kann sehr fehleranfällig sein. Meistens kann bereits ein einziger fehlgeschlagener OpenGL-Aufruf dazu führen, dass ein ganzer Teil einer Anwendung nicht mehr funktioniert und auf dem Bildschirm nichts mehr angezeigt wird.

Die einzige Möglichkeit, sicherzustellen, dass von der OpenGL-Implementierung keine Fehler zurückgegeben werden, besteht darin, nach jedem einzelnen API-Aufruf mit ` glGetError ` zu prüfen. Da sich OpenGL-Fehler zudem anhäufen, sollte `glGetError` immer in einer Schleife wie dieser verwendet werden:

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

Wenn Sie versuchen, den Fehlerstapel zu löschen, achten Sie darauf, nicht einfach so lange fortzufahren, bis GL_NO_ERROR zurückgegeben wird, sondern auch bei GL_CONTEXT_LOST abzubrechen, da dieser Fehlerwert immer wieder auftritt.

Es gibt noch viele weitere Informationen, die für uns (als Anwendungsentwickler) von Interesse sind, beispielsweise Leistungsprobleme oder Warnungen zur Verwendung veralteter APIs. Diese Art von Meldungen werden nicht über die üblichen OpenGL-Fehlermeldemechanismen gemeldet.

QOpenGLDebugLogger zielt darauf ab, diese Probleme zu beheben, indem es Zugriff auf das OpenGL-Debug-Protokoll bietet. Wenn Ihre OpenGL-Implementierung dies unterstützt (durch Bereitstellung der Erweiterung „ GL_KHR_debug “), werden Meldungen vom OpenGL-Server entweder in einem internen OpenGL-Protokoll protokolliert oder „in Echtzeit“ an Listener weitergeleitet, sobald sie von OpenGL generiert werden.

QOpenGLDebugLogger unterstützt beide Betriebsmodi. In den folgenden Abschnitten erfahren Sie mehr über die Unterschiede zwischen diesen Modi.

Erstellen eines OpenGL-Debug-Kontexts

Aus Effizienzgründen ist es OpenGL-Implementierungen gestattet, überhaupt keine Debug-Ausgabe zu erzeugen, es sei denn, der OpenGL-Kontext ist ein Debug-Kontext. Um einen Debug-Kontext über Qt zu erstellen, müssen Sie die Formatoption „ QSurfaceFormat::DebugContext “ für den „ QSurfaceFormat “ festlegen, der zum Erstellen des „ QOpenGLContext “-Objekts verwendet wird:

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();

Beachten Sie, dass die Anforderung eines OpenGL-Core-Profils 3.2 nur zu Beispielzwecken dient; diese Klasse ist nicht an eine bestimmte OpenGL- oder OpenGL ES-Version gebunden, da sie auf der Verfügbarkeit der Erweiterung „ GL_KHR_debug “ beruht (siehe unten).

Erstellen und Initialisieren eines `QOpenGLDebugLogger`

`QOpenGLDebugLogger` ist eine einfache, von ` QObject` abgeleitete Klasse. Genau wie bei allen Unterklassen von ` QObject ` erstellen Sie eine Instanz (und geben optional ein übergeordnetes Objekt an), und wie bei den anderen OpenGL-Funktionen in Qt müssen Sie diese vor der Verwendung initialisieren, indem Sie ` initialize()` aufrufen, solange ein aktueller OpenGL-Kontext vorhanden ist:

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

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

Beachten Sie, dass die Erweiterung „ GL_KHR_debug “ im Kontext verfügbar sein muss, um auf die von OpenGL protokollierten Meldungen zugreifen zu können. Sie können das Vorhandensein dieser Erweiterung durch den Aufruf von:

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

wobei ` ctx ` ein gültiger ` QOpenGLContext` ist. Ist die Erweiterung nicht verfügbar, gibt ` initialize()` den Wert `false` zurück.

Auslesen des internen OpenGL-Debug-Protokolls

OpenGL-Implementierungen führen ein internes Protokoll mit Debug-Meldungen. Die in diesem Protokoll gespeicherten Meldungen können mithilfe der Funktion ` loggedMessages()` abgerufen werden:

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

Das interne Protokoll hat eine begrenzte Größe; wenn es voll ist, werden ältere Meldungen verworfen, um Platz für neu eingehende Meldungen zu schaffen. Wenn Sie ` loggedMessages()` aufrufen, wird das interne Protokoll ebenfalls geleert.

Wenn Sie sicherstellen möchten, dass keine Debug-Meldung verloren geht, müssen Sie anstelle des Aufrufs dieser Funktion die Echtzeitprotokollierung verwenden. Es können jedoch weiterhin Debug-Meldungen in der Zeitspanne zwischen der Erstellung des Kontexts und der Aktivierung der Echtzeitprotokollierung (oder generell, wenn die Echtzeitprotokollierung deaktiviert ist) generiert werden.

Echtzeit-Protokollierung von Meldungen

Es ist auch möglich, einen Strom von Debug-Meldungen vom OpenGL-Server zu empfangen, sobald diese von der Implementierung generiert werden. Dazu müssen Sie einen geeigneten Slot mit dem Signal ` messageLogged()` verbinden und die Protokollierung durch Aufruf von ` startLogging()` starten:

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

Ebenso kann die Protokollierung jederzeit durch Aufruf der Funktion ` stopLogging()` deaktiviert werden.

Die Echtzeitprotokollierung kann je nach dem an ` startLogging()` übergebenen Parameter entweder asynchron oder synchron erfolgen. Bei der Protokollierung im asynchronen Modus (Standard, da er einen sehr geringen Overhead aufweist) kann die OpenGL-Implementierung Meldungen jederzeit und/oder in einer Reihenfolge generieren, die von der Reihenfolge der OpenGL-Befehle abweicht, die zur Protokollierung dieser Meldungen geführt haben. Die Meldungen können auch von einem Thread generiert werden, der sich von dem Thread unterscheidet, an den der Kontext derzeit gebunden ist. Dies liegt daran, dass OpenGL-Implementierungen in der Regel stark multithreaded und asynchron sind, weshalb keine Garantien hinsichtlich der relativen Reihenfolge und des Zeitpunkts der Debug-Meldungen gegeben werden.

Andererseits ist die Protokollierung im synchronen Modus mit hohem Overhead verbunden, aber die OpenGL-Implementierung garantiert, dass alle durch einen bestimmten Befehl ausgelösten Meldungen in der richtigen Reihenfolge empfangen werden, bevor der Befehl zurückkehrt, und zwar von demselben Thread, an den der OpenGL-Kontext gebunden ist.

Das bedeutet, dass Sie bei der Protokollierung im synchronen Modus Ihre OpenGL-Anwendung in einem Debugger ausführen, einen Haltepunkt an einem Slot setzen können, der mit dem Signal „ messageLogged()“ verbunden ist, und im Backtrace den genauen Aufruf sehen können, der die protokollierte Meldung ausgelöst hat. Dies kann für die Fehlersuche bei einem OpenGL-Problem äußerst nützlich sein. Beachten Sie, dass Sie, falls das OpenGL-Rendering in einem anderen Thread erfolgt, den Signal-/Slot-Verbindungstyp auf „ Qt::DirectConnection “ festlegen müssen, um den tatsächlichen Backtrace sehen zu können.

Weitere Informationen zu den Protokollierungsmodi finden Sie in der Dokumentation zur Enumeration „ LoggingMode “.

Einfügen von Meldungen in das Debug-Protokoll

Anwendungen und Bibliotheken können benutzerdefinierte Meldungen in das Debug-Protokoll einfügen, beispielsweise um eine Gruppe zusammenhängender OpenGL-Befehle zu kennzeichnen und so eventuelle von diesen stammende Meldungen identifizieren zu können.

Dazu können Sie ein ` QOpenGLDebugMessage `-Objekt erstellen, indem Sie ` createApplicationMessage()` oder ` createThirdPartyMessage()` aufrufen, und es anschließend durch Aufruf von ` logMessage()` in das Protokoll einfügen:

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

logger->logMessage(message);

Beachten Sie, dass OpenGL-Implementierungen eine herstellerspezifische Begrenzung für die Länge der Meldungen haben, die in das Debug-Protokoll eingefügt werden können. Sie können diese Länge durch Aufruf der Methode ` maximumMessageLength()` abrufen; Meldungen, die länger als diese Grenze sind, werden automatisch gekürzt.

Steuerung der Debug-Ausgabe

QOpenGLDebugMessage kann zudem Filter auf die Debug-Meldungen anwenden und so die Anzahl der protokollierten Meldungen begrenzen. Sie können die Protokollierung von Meldungen aktivieren oder deaktivieren, indem Sie jeweils enableMessages() und disableMessages() aufrufen. Standardmäßig werden alle Meldungen protokolliert.

Es ist möglich, Meldungen durch Auswahl folgender Kriterien zu aktivieren oder zu deaktivieren:

• Quelle, Typ und Schweregrad (wobei alle IDs in die Auswahl einbezogen werden);
• ID, Quelle und Typ (wobei alle Schweregrade in die Auswahl einbezogen werden).

Beachten Sie, dass der Status „aktiviert“ für eine bestimmte Meldung eine Eigenschaft des Tupels (ID, Quelle, Typ, Schweregrad) ist; die Meldungsattribute bilden keinerlei Hierarchie. Sie sollten auf die Reihenfolge der Aufrufe von ` enableMessages()` und ` disableMessages()` achten, da sich dadurch ändert, welche Meldungen aktiviert bzw. deaktiviert werden.

Es ist nicht möglich, nach dem Meldungstext selbst zu filtern; Anwendungen müssen dies selbst übernehmen (in Slots, die mit dem Signal ` messageLogged()` verbunden sind, oder nach dem Abrufen der Meldungen im internen Debug-Protokoll über ` loggedMessages()`).

Um die Verwaltung der Aktivierungs-/Deaktivierungszustände zu vereinfachen, unterstützt „ QOpenGLDebugMessage “ außerdem das Konzept der „ debug groups “. Eine Debug-Gruppe enthält die Gesamtheit der aktivierten bzw. deaktivierten Konfigurationen von Debug-Meldungen. Zudem sind Debug-Gruppen in einem Stapel organisiert: Es ist möglich, Gruppen durch Aufruf von pushGroup() bzw. popGroup() auf den Stapel zu schieben bzw. vom Stapel zu entfernen. (Wenn ein OpenGL-Kontext erstellt wird, befindet sich bereits eine Gruppe im Stapel.)

Die Funktionen „ enableMessages()“ und „ disableMessages()“ ändern die Konfiguration der aktuellen Debug-Gruppe, d. h. der Gruppe, die sich ganz oben im Debug-Gruppen-Stapel befindet.

Wenn eine neue Gruppe auf den Debug-Gruppen-Stapel gelegt wird, übernimmt sie die Konfiguration der Gruppe, die zuvor ganz oben auf dem Stapel lag. Umgekehrt wird durch das Entfernen einer Debug-Gruppe die Konfiguration der Debug-Gruppe wiederhergestellt, die nun an die Spitze rückt.

Das Einfügen (bzw. Entfernen) von Debug-Gruppen generiert außerdem automatisch eine Debug-Meldung vom Typ „ QOpenGLDebugMessage::GroupPushType “ (bzw. „ GroupPopType “).