QOpenGLDebugLogger Class

Detaillierte Beschreibung

Einführung

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

Die einzige Möglichkeit, sicher zu sein, dass die OpenGL-Implementierung keine Fehler zurückgibt, ist die Überprüfung mit glGetError nach jedem einzelnen API-Aufruf. Außerdem stapeln sich OpenGL-Fehler, daher 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 leeren, stellen Sie sicher, dass Sie nicht nur weitermachen, bis GL_NO_ERROR zurückgegeben wird, sondern auch bei GL_CONTEXT_LOST abbrechen, da dieser Fehlerwert immer wieder auftauchen wird.

Es gibt auch viele andere Informationen, an denen wir (als Anwendungsentwickler) interessiert sind, zum Beispiel Leistungsprobleme oder Warnungen über die Verwendung veralteter APIs. Diese Art von Meldungen werden nicht durch die normalen OpenGL-Fehlerberichtsmechanismen gemeldet.

QOpenGLDebugLogger zielt darauf ab, diese Probleme zu adressieren, indem es Zugriff auf das OpenGL-Debug-Log bietet. Wenn Ihre OpenGL-Implementierung dies unterstützt (indem Sie die GL_KHR_debug -Erweiterung zur Verfügung stellen), werden Meldungen vom OpenGL-Server entweder in einem internen OpenGL-Protokoll protokolliert oder in "Echtzeit" an Listener weitergegeben, wenn sie von OpenGL erzeugt werden.

QOpenGLDebugLogger unterstützt diese beiden Betriebsarten. Lesen Sie die folgenden Abschnitte, um die Unterschiede zwischen ihnen herauszufinden.

Erstellen eines OpenGL-Debug-Kontextes

Aus Effizienzgründen ist es OpenGL-Implementierungen erlaubt, überhaupt keine Debug-Ausgabe zu erzeugen, es sei denn, der OpenGL-Kontext ist ein Debug-Kontext. Um einen Debug-Kontext von Qt aus zu erstellen, müssen Sie die QSurfaceFormat::DebugContext Format-Option auf der QSurfaceFormat setzen, die 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 3.2 OpenGL Core Profils nur für die Zwecke des Beispiels ist; diese Klasse ist nicht an eine bestimmte OpenGL oder OpenGL ES Version gebunden, da sie von der Verfügbarkeit der GL_KHR_debug Erweiterung abhängt (siehe unten).

Erstellen und Initialisieren eines QOpenGLDebugLogger

QOpenGLDebugLogger ist eine einfache QObject-abgeleitete Klasse. Genau wie alle QObject Unterklassen erstellen Sie eine Instanz (und geben optional ein übergeordnetes Objekt an), und wie die anderen OpenGL-Funktionen in Qt müssen Sie sie vor der Verwendung initialisieren, indem Sie initialize() aufrufen, während es einen aktuellen OpenGL-Kontext gibt:

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 überprüfen, indem Sie aufrufen:

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

wobei ctx eine gültige QOpenGLContext ist. Wenn die Erweiterung nicht verfügbar ist, gibt initialize() false zurück.

Lesen des internen OpenGL-Debug-Protokolls

OpenGL-Implementierungen führen ein internes Protokoll mit Debug-Meldungen. Meldungen, die in diesem Protokoll gespeichert sind, können mit 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 die neu eingehenden Meldungen zu schaffen. Wenn Sie loggedMessages() aufrufen, wird auch das interne Protokoll geleert.

Wenn Sie sichergehen wollen, dass keine Debug-Meldungen verloren gehen, müssen Sie die Echtzeit-Protokollierung verwenden, anstatt diese Funktion aufzurufen. In der Zeitspanne zwischen der Kontexterzeugung und der Aktivierung der Echtzeitprotokollierung (oder generell, wenn die Echtzeitprotokollierung deaktiviert ist) können jedoch immer noch Debugmeldungen erzeugt werden.

Echtzeit-Protokollierung von Meldungen

Es ist auch möglich, einen Strom von Debug-Meldungen vom OpenGL-Server zu empfangen , während sie von der Implementierung erzeugt werden. Dazu müssen Sie einen geeigneten Slot mit dem Signal messageLogged() verbinden und die Protokollierung durch den 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 Echtzeit-Protokollierung kann entweder asynchron oder synchron erfolgen, je nach dem Parameter, der an startLogging() übergeben wird. Wenn die Protokollierung im asynchronen Modus erfolgt (die Standardeinstellung, da sie einen sehr geringen Overhead hat), kann die OpenGL-Implementierung jederzeit Nachrichten erzeugen und/oder in einer Reihenfolge, die von der Reihenfolge der OpenGL-Befehle abweicht, die die Protokollierung dieser Nachrichten verursacht haben. Die Meldungen könnten auch von einem anderen Thread als dem, an den der Kontext gerade gebunden ist, erzeugt werden. Dies liegt daran, dass OpenGL-Implementierungen in der Regel stark threaded und asynchron sind, und daher keine Garantien über die relative Reihenfolge und die Zeitpunkte der Debug-Meldungen gegeben werden.

Auf der anderen Seite hat die Protokollierung im synchronen Modus einen hohen Overhead, aber die OpenGL-Implementierung garantiert, dass alle Nachrichten, die durch einen bestimmten Befehl ausgelöst werden, in der Reihenfolge empfangen werden, bevor der Befehl zurückkehrt, und von demselben Thread, an den der OpenGL-Kontext gebunden ist.

Das bedeutet, dass Sie, wenn Sie im synchronen Modus protokollieren, in der Lage sein werden, Ihre OpenGL-Anwendung in einem Debugger laufen zu lassen, einen Haltepunkt auf einem Slot zu setzen, der mit dem messageLogged()-Signal verbunden ist, und in der Rückverfolgung den genauen Aufruf zu sehen, der die protokollierte Nachricht verursacht hat. Dies kann sehr nützlich sein, um ein OpenGL-Problem zu beheben. Beachten Sie, dass Sie, wenn das OpenGL-Rendering in einem anderen Thread stattfindet, den Signal/Slot-Verbindungstyp auf Qt::DirectConnection erzwingen müssen, um den tatsächlichen Backtrace sehen zu können.

Weitere Informationen über die Protokollierungsmodi finden Sie in der LoggingMode enum-Dokumentation.

Einfügen von Meldungen in das Debug-Protokoll

Es ist für Anwendungen und Bibliotheken möglich, benutzerdefinierte Meldungen in das Debug-Protokoll einzufügen, z.B. um eine Gruppe von zusammenhängenden OpenGL-Befehlen zu markieren und somit in der Lage zu sein, eventuelle Meldungen, die von ihnen kommen, zu identifizieren.

Um dies zu tun, können Sie ein QOpenGLDebugMessage Objekt durch Aufruf von createApplicationMessage() oder createThirdPartyMessage() erstellen und es dann durch Aufruf von logMessage() in das Protokoll einfügen:

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

logger->logMessage(message);

Beachten Sie, dass OpenGL-Implementierungen ein herstellerspezifisches Limit 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 den Aufruf der Methode maximumMessageLength() abrufen; Nachrichten, die länger als das Limit sind, werden automatisch abgeschnitten.

Kontrolle der Debug-Ausgabe

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

Es ist möglich, Meldungen zu aktivieren oder zu deaktivieren, indem man sie auswählt nach:

• Quelle, Typ und Schweregrad (und einschließlich aller IDs in der Auswahl);
• id, Quelle und Typ (und einschließlich aller Schweregrade in der Auswahl).

Beachten Sie, dass der Status "aktiviert" für eine bestimmte Meldung eine Eigenschaft des Tupels (id, source, type, severity) ist; die Meldungsattribute bilden keine Hierarchie irgendeiner Art. Sie sollten auf die Reihenfolge der Aufrufe von enableMessages() und disableMessages() achten, da sich dadurch ändert, welche Nachrichten aktiviert/deaktiviert werden.

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

Um die Verwaltung der aktivierten/deaktivierten Zustände zu vereinfachen, unterstützt QOpenGLDebugMessage auch das Konzept von debug groups. Eine Debug-Gruppe enthält die Gruppe der aktivierten/deaktivierten Konfigurationen von Debug-Meldungen. Darüber hinaus sind Debug-Gruppen in einem Stapel organisiert: es ist möglich, Gruppen durch den Aufruf von pushGroup() und popGroup() zu verschieben bzw. 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 oben auf dem Stapel der Debug-Gruppen befindet.

Wenn eine neue Gruppe auf den Stapel der Debug-Gruppen geschoben wird, erbt sie die Konfiguration der Gruppe, die sich zuvor an der Spitze des Stapels befand. Umgekehrt wird durch das Entfernen einer Debug-Gruppe die Konfiguration der Debug-Gruppe wiederhergestellt, die nun an der Spitze steht.

Das Verschieben (bzw. Herausnehmen) von Debug-Gruppen erzeugt auch automatisch eine Debug-Meldung vom Typ QOpenGLDebugMessage::GroupPushType (bzw. GroupPopType).