QOpenGLDebugLogger Class

Description détaillée

Introduction

La programmation OpenGL peut être très sujette aux erreurs. La plupart du temps, un seul appel défaillant à OpenGL peut entraîner l'arrêt de toute une partie de l'application, sans que rien ne soit dessiné à l'écran.

Le seul moyen d'être sûr 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'empilent, c'est pourquoi glGetError devrait toujours être utilisé 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 d'effacer la pile d'erreurs, assurez-vous de ne pas continuer jusqu'à ce que GL_NO_ERROR soit retourné, mais aussi de vous arrêter sur GL_CONTEXT_LOST car cette valeur d'erreur continuera à se répéter.

Il existe également de nombreuses autres informations qui nous intéressent (en tant que développeurs d'applications), par exemple les problèmes de performance ou les avertissements concernant l'utilisation d'API obsolètes. Ces types de messages ne sont pas rapportés par les mécanismes ordinaires de rapport d'erreur d'OpenGL.

QOpenGLDebugLogger vise à résoudre ces problèmes en fournissant un accès au journal de débogage d'OpenGL. Si votre implémentation OpenGL le supporte (en exposant l'extension GL_KHR_debug ), les messages du serveur OpenGL seront soit enregistrés dans un journal interne OpenGL, soit transmis en "temps réel" aux auditeurs lorsqu'ils sont générés par OpenGL.

QOpenGLDebugLogger supporte ces deux modes de fonctionnement. Référez-vous aux sections suivantes pour connaître les différences entre les deux.

Créer un contexte de débogage OpenGL

Pour des raisons d'efficacité, les implémentations OpenGL sont autorisées à ne pas créer de sortie de débogage, à moins que le contexte OpenGL ne soit un contexte de débogage. Afin de créer un contexte de débogage à partir de Qt XML, vous devez définir l'option de format QSurfaceFormat::DebugContext sur l'objet 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();

Cette classe n'est pas liée à une 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 simple classe dérivée de QObject. Comme toutes les sous-classes de QObject, vous créez une instance (et optionnellement vous spécifiez un objet parent), et comme les autres fonctions OpenGL dans QtGL vous devez l'initialiser avant de l'utiliser en appelant initialize() tant qu'il y a un contexte OpenGL en cours :

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 afin d'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 un QOpenGLContext valide. Si l'extension n'est pas disponible, initialize() renverra false.

Lire le journal de débogage interne d'OpenGL

Les implémentations OpenGL conservent un journal interne des messages de débogage. Les messages stockés dans ce journal peuvent être récupérés en utilisant 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 se remplit, les anciens messages sont supprimés pour faire de la place aux nouveaux messages entrants. Lorsque vous appelez loggedMessages(), le journal interne est également vidé.

Si vous voulez être sûr de ne perdre aucun message de débogage, vous devez utiliser la journalisation en temps réel au lieu d'appeler cette fonction. Toutefois, des messages de débogage peuvent encore être générés entre la création du contexte et l'activation de la journalisation en temps réel (ou, en général, lorsque la journalisation en temps réel est désactivée).

Enregistrement en temps réel des messages

Il est également possible de recevoir un flux de messages de débogage 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 l'enregistrement 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().

L'enregistrement en temps réel peut être asynchrone ou synchrone, en fonction du paramètre transmis à startLogging(). Lorsque l'enregistrement se fait en mode asynchrone (le mode par défaut, car il a un très faible surcoût), l'implémentation OpenGL peut générer des messages à tout moment, et/ou dans un ordre différent de l'ordre des commandes OpenGL qui ont causé l'enregistrement de ces messages. Les messages peuvent également être générés à partir d'un thread différent de celui auquel le contexte est actuellement lié. Ceci est dû au fait que les implémentations d'OpenGL sont généralement hautement threadées et asynchrones, et donc aucune garantie n'est donnée quant à l'ordre relatif et à la chronologie des messages de débogage.

D'un autre côté, l'enregistrement en mode synchrone a un coût élevé, mais l'implémentation OpenGL garantit que tous les messages provoqués par une certaine commande sont reçus dans l'ordre, avant que la commande ne revienne, et depuis le même thread auquel le contexte OpenGL est lié.

Cela signifie que lorsque vous enregistrez 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 le backtrace l'appel exact qui a causé le message enregistré. Cela peut être extrêmement utile pour déboguer un problème OpenGL. Notez que si le rendu OpenGL se produit dans un autre thread, vous devez forcer le type de connexion signal/emplacement à Qt::DirectConnection afin de pouvoir voir la trace arrière réelle.

Reportez-vous à la documentation de l'enum LoggingMode pour plus d'informations sur les modes de journalisation.

Insérer des messages dans le journal de débogage

Il est possible pour les applications et les bibliothèques d'insérer des messages personnalisés dans le journal de débogage, par exemple pour marquer un groupe de commandes OpenGL liées et ainsi être capable d'identifier d'éventuels messages provenant de ces commandes.

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 ont une limite spécifique au fournisseur pour la longueur des messages qui peuvent ê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 plus longs que la limite seront automatiquement tronqués.

Contrôle de la sortie de débogage

QOpenGLDebugMessage Le logiciel de débogage permet également d'appliquer des filtres aux messages de débogage, et donc de limiter la quantité 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 les messages en les sélectionnant par :

• la source, le type et la gravité (en incluant tous les identifiants dans la sélection) ;
• id, source et type (et en incluant toutes les sévérités dans la sélection).

Notez que l'état "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 il modifiera les messages qui seront activés/désactivés.

Il n'est pas possible de filtrer par le texte du message lui-même ; les applications doivent le faire elles-mêmes (dans les emplacements connectés au signal messageLogged(), ou après avoir récupéré les messages dans le journal de débogage interne par l'intermédiaire de loggedMessages()).

Afin de simplifier la gestion des statuts activé / désactivé, QOpenGLDebugMessage prend également en charge le concept de debug groups. Un groupe de débogage contient le groupe des configurations activées / désactivées des messages de débogage. De plus, les groupes de débogage sont organisés en pile : il est possible de pousser et de sortir des groupes en appelant respectivement pushGroup() et popGroup(). (Lorsqu'un contexte OpenGL est créé, il y a déjà un groupe 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 poussé sur la pile des groupes de débogage, il hérite de la configuration du groupe qui se trouvait précédemment au sommet de la pile. Vice versa, l'extraction d'un groupe de débogage rétablit la configuration du groupe de débogage qui devient le nouveau sommet de la pile.

Le fait de pousser (respectivement d'enlever) des groupes de débogage génère aussi automatiquement un message de débogage de type QOpenGLDebugMessage::GroupPushType (respectivement GroupPopType).