QOpenGLDebugLogger Class

Description détaillée

Introduction

La programmation OpenGL peut être source de nombreuses erreurs. La plupart du temps, un seul appel OpenGL qui échoue peut entraîner l'arrêt complet d'une partie de l'application, sans qu'aucun élément ne s'affiche à l'écran.

La seule façon de s'assurer qu'aucune erreur n'est renvoyée par l'implémentation OpenGL est de vérifier avec ` glGetError ` après chaque appel à l'API. De plus, les erreurs OpenGL s'accumulent ; il faut donc toujours utiliser `glGetError` dans une boucle comme celle-ci :

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

Si vous essayez de vider la pile d’erreurs, veillez non seulement à ne pas continuer jusqu’à ce que GL_NO_ERROR soit renvoyé, mais aussi à interrompre l’exécution en cas de GL_CONTEXT_LOST, car cette valeur d’erreur se répète indéfiniment.

Il existe également de nombreuses autres informations qui nous intéressent (en tant que développeurs d’applications), par exemple les problèmes de performances ou les avertissements concernant l’utilisation d’API obsolètes. Ce type de messages n’est pas signalé par les mécanismes habituels de signalement des erreurs OpenGL.

QOpenGLDebugLogger vise à résoudre ces problèmes en donnant accès au journal de débogage OpenGL. Si votre implémentation OpenGL le prend en charge (en exposant l’extension GL_KHR_debug ), les messages provenant du serveur OpenGL seront soit consignés dans un journal OpenGL interne, soit transmis en « temps réel » aux écouteurs au fur et à mesure de leur génération par OpenGL.

QOpenGLDebugLogger prend en charge ces deux modes de fonctionnement. Reportez-vous aux sections suivantes pour découvrir leurs différences.

Création d’un contexte de débogage OpenGL

Pour des raisons d’efficacité, les implémentations OpenGL sont autorisées à ne générer aucune sortie de débogage, sauf si le contexte OpenGL est un contexte de débogage. Pour créer un contexte de débogage à partir de Qt, vous devez définir l’option de format « QSurfaceFormat::DebugContext » sur l’ QSurfaceFormat utilisé pour créer l’objet ` QOpenGLContext ` :

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

Notez que la demande d’un profil OpenGL Core 3.2 n’est qu’à titre d’exemple ; cette classe n’est liée à aucune version spécifique d’OpenGL ou d’OpenGL ES, car elle repose sur la disponibilité de l’extension « GL_KHR_debug » (voir ci-dessous).

Création et initialisation d’un QOpenGLDebugLogger

QOpenGLDebugLogger est une classe simple dérivée de ` QObject`. À l’instar de toutes les sous-classes de ` QObject `, vous créez une instance (et spécifiez éventuellement un objet parent) et, comme pour les autres fonctions OpenGL de Qt, vous devez l’initialiser avant utilisation en appelant ` initialize()` tant qu’un contexte OpenGL est actif :

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

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

Notez que l’extension GL_KHR_debug doit être disponible dans le contexte pour pouvoir accéder aux messages enregistrés par OpenGL. Vous pouvez vérifier la présence de cette extension en appelant :

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

où ctx est une valeur valide de type QOpenGLContext. Si l'extension n'est pas disponible, la fonction initialize() renverra la valeur false.

Lecture du journal de débogage interne d'OpenGL

Les implémentations OpenGL tiennent un journal interne des messages de débogage. Les messages stockés dans ce journal peuvent être récupérés à l’aide de la fonction loggedMessages() :

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

Le journal interne a une taille limitée ; lorsqu’il est plein, les messages les plus anciens sont supprimés pour faire de la place aux nouveaux messages entrants. Lorsque vous appelez la fonction ` loggedMessages()`, le journal interne est également vidé.

Si vous souhaitez vous assurer de ne perdre aucun message de débogage, vous devez utiliser la journalisation en temps réel plutôt que d'appeler cette fonction. Cependant, des messages de débogage peuvent tout de même être générés pendant le laps de temps entre la création du contexte et l'activation de la journalisation en temps réel (ou, de manière générale, lorsque la journalisation en temps réel est désactivée).

Journalisation en temps réel des messages

Il est également possible de recevoir un flux de messages de débogage provenant du serveur OpenGL au fur et à mesure qu’ils sont générés par l’implémentation. Pour ce faire, vous devez connecter un slot approprié au signal ` messageLogged()` et démarrer la journalisation en appelant ` startLogging()` :

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

De même, la journalisation peut être désactivée à tout moment en appelant la fonction ` stopLogging()`.

La journalisation en temps réel peut être asynchrone ou synchrone, selon le paramètre passé à ` startLogging()`. En mode asynchrone (mode par défaut, car il n’entraîne qu’une très faible surcharge), l’implémentation OpenGL peut générer des messages à tout moment et/ou dans un ordre différent de celui des commandes OpenGL à l’origine de ces messages. Les messages peuvent également être générés par un thread différent de celui auquel le contexte est actuellement lié. En effet, les implémentations OpenGL sont généralement hautement multithreadées et asynchrones ; par conséquent, aucune garantie n’est donnée quant à l’ordre relatif et au timing des messages de débogage.

En revanche, la journalisation en mode synchrone implique une surcharge importante, mais l’implémentation OpenGL garantit que tous les messages générés par une commande donnée sont reçus dans l’ordre, avant que la commande ne renvoie une valeur, et à partir du même thread auquel le contexte OpenGL est lié.

Cela signifie que lorsque vous effectuez un journalisation en mode synchrone, vous pourrez exécuter votre application OpenGL dans un débogueur, placer un point d’arrêt sur un slot connecté au signal messageLogged(), et voir dans la trace de pile l’appel exact qui a généré le message journalisé. Cela peut s’avérer extrêmement utile pour déboguer un problème OpenGL. Notez que si le rendu OpenGL s’effectue dans un autre thread, vous devez forcer le type de connexion signal/slot à « Qt::DirectConnection » afin de pouvoir voir la trace de pile réelle.

Reportez-vous à la documentation sur l’énumération LoggingMode pour plus d’informations sur les modes de journalisation.

Insertion de messages dans le journal de débogage

Les applications et les bibliothèques ont la possibilité d’insérer des messages personnalisés dans le journal de débogage, par exemple pour marquer un groupe de commandes OpenGL associées et pouvoir ainsi identifier les messages éventuels provenant de celles-ci.

Pour ce faire, vous pouvez créer un objet ` QOpenGLDebugMessage ` en appelant ` createApplicationMessage()` ou ` createThirdPartyMessage()`, puis l’insérer dans le journal en appelant ` logMessage()` :

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

logger->logMessage(message);

Notez que les implémentations OpenGL imposent une limite, propre à chaque éditeur, quant à la longueur des messages pouvant être insérés dans le journal de débogage. Vous pouvez récupérer cette longueur en appelant la méthode maximumMessageLength() ; les messages dépassant cette limite seront automatiquement tronqués.

Contrôle de la sortie de débogage

QOpenGLDebugMessage Il est également possible d'appliquer des filtres aux messages de débogage, et donc de limiter le nombre de messages enregistrés. Vous pouvez activer ou désactiver l'enregistrement des messages en appelant respectivement enableMessages() et disableMessages(). Par défaut, tous les messages sont enregistrés.

Il est possible d’activer ou de désactiver des messages en les sélectionnant selon :

• source, type et niveau de gravité (en incluant tous les identifiants dans la sélection) ;
• ID, source et type (en incluant tous les niveaux de gravité dans la sélection).

Notez que le statut « activé » d’un message donné est une propriété du tuple (ID, source, type, gravité) ; les attributs du message ne forment aucune hiérarchie. Vous devez faire attention à l’ordre des appels à enableMessages() et disableMessages(), car cela modifie les messages qui seront activés ou désactivés.

Il n’est pas possible de filtrer en fonction du texte du message lui-même ; les applications doivent le faire elles-mêmes (dans des slots connectés au signal messageLogged() ou après avoir récupéré les messages dans le journal de débogage interne via loggedMessages()).

Afin de simplifier la gestion des états activés/désactivés, QOpenGLDebugMessage prend également en charge le concept de debug groups. Un groupe de débogage regroupe les configurations d’activation/désactivation des messages de débogage. De plus, les groupes de débogage sont organisés en pile : il est possible d’ajouter et de retirer des groupes en appelant respectivement pushGroup() et popGroup(). (Lorsqu’un contexte OpenGL est créé, un groupe se trouve déjà dans la pile).

Les fonctions ` enableMessages()` et ` disableMessages()` modifient la configuration du groupe de débogage actuel, c'est-à-dire celui qui se trouve au sommet de la pile des groupes de débogage.

Lorsqu’un nouveau groupe est ajouté à la pile des groupes de débogage, il hérite de la configuration du groupe qui se trouvait auparavant en haut de la pile. Inversement, le retrait d’un groupe de débogage rétablit la configuration du groupe de débogage qui devient alors le nouveau groupe en tête de pile.

L'ajout (ou le retrait) de groupes de débogage génère également automatiquement un message de débogage de type « QOpenGLDebugMessage::GroupPushType » (ou « GroupPopType »).