QOpenGLDebugLogger Class

Descripción detallada

Introducción

La programación OpenGL puede ser muy propensa a errores. La mayoría de las veces, una sola llamada fallida a OpenGL puede hacer que toda una parte de una aplicación deje de funcionar, sin que se dibuje nada en la pantalla.

La única forma de estar seguro de que no se devuelven errores desde la implementación de OpenGL es comprobarlo con glGetError después de cada llamada a la API. Además, los errores de OpenGL se apilan, por lo que glGetError debería usarse siempre en un bucle como éste:

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

Si intentas limpiar la pila de errores, asegúrate no sólo de seguir hasta que se devuelva GL_NO_ERROR sino también de romper en GL_CONTEXT_LOST ya que ese valor de error seguirá repitiéndose.

También hay mucha otra información que nos interesa (como desarrolladores de aplicaciones), por ejemplo problemas de rendimiento, o advertencias sobre el uso de APIs obsoletas. Este tipo de mensajes no se reportan a través de los mecanismos ordinarios de reporte de errores de OpenGL.

QOpenGLDebugLogger pretende solucionar estos problemas proporcionando acceso al registro de depuración de OpenGL. Si tu implementación de OpenGL lo soporta (exponiendo la extensión GL_KHR_debug ), los mensajes del servidor OpenGL se registrarán en un registro interno de OpenGL, o se pasarán en "tiempo real" a los oyentes cuando se generen desde OpenGL.

QOpenGLDebugLogger soporta ambos modos de operación. Consulta las siguientes secciones para conocer las diferencias entre ellos.

Creando un Contexto de Depuración OpenGL

Por razones de eficiencia, a las implementaciones OpenGL se les permite no crear ninguna salida de depuración, a menos que el contexto OpenGL sea un contexto de depuración. Para crear un contexto de depuración desde Qt, debe establecer la opción de formato QSurfaceFormat::DebugContext en el QSurfaceFormat utilizado para crear el objeto 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();

Tenga en cuenta que solicitar un perfil 3.2 OpenGL Core Profile es sólo para los propósitos del ejemplo; esta clase no está ligada a ninguna versión específica de OpenGL u OpenGL ES, ya que depende de la disponibilidad de la extensión GL_KHR_debug (ver más abajo).

Creando e Inicializando un QOpenGLDebugLogger

QOpenGLDebugLogger es una simple clase derivada de QObject. Como todas las subclases de QObject, creas una instancia (y opcionalmente especificas un objeto padre), y como las otras funciones OpenGL en Qt debes inicializarla antes de usarla llamando a initialize() mientras haya un contexto OpenGL actual:

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

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

Ten en cuenta que la extensión GL_KHR_debug debe estar disponible en el contexto para poder acceder a los mensajes registrados por OpenGL. Puedes comprobar la presencia de esta extensión llamando a:

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

donde ctx es un QOpenGLContext válido. Si la extensión no está disponible, initialize() devolverá false.

Lectura del registro de depuración interno de OpenGL

Las implementaciones de OpenGL mantienen un registro interno de mensajes de depuración. Los mensajes almacenados en este registro pueden ser recuperados utilizando la función loggedMessages():

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

El registro interno tiene un tamaño limitado; cuando se llene, los mensajes antiguos se descartarán para hacer sitio a los nuevos mensajes entrantes. Cuando llame a loggedMessages(), el registro interno también se vaciará.

Si quieres asegurarte de no perder ningún mensaje de depuración, debes utilizar el registro en tiempo real en lugar de llamar a esta función. Sin embargo, es posible que se sigan generando mensajes de depuración en el intervalo de tiempo entre la creación del contexto y la activación del registro en tiempo real (o, en general, cuando el registro en tiempo real está desactivado).

Registro de mensajes en tiempo real

También es posible recibir un flujo de mensajes de depuración del servidor OpenGL a medida que son generados por la implementación. Para ello, es necesario conectar una ranura adecuada a la señal messageLogged(), e iniciar el registro llamando a startLogging():

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

Del mismo modo, el registro puede desactivarse en cualquier momento llamando a la función stopLogging().

El registro en tiempo real puede ser asíncrono o síncrono, dependiendo del parámetro que se pase a startLogging(). Cuando el registro se realiza en modo asíncrono (el predeterminado, ya que tiene una sobrecarga muy pequeña), la implementación de OpenGL puede generar mensajes en cualquier momento, y/o en un orden diferente del orden de los comandos de OpenGL que causaron que se registraran esos mensajes. Los mensajes también podrían ser generados desde un hilo diferente al hilo al que el contexto está actualmente vinculado. Esto se debe a que las implementaciones de OpenGL suelen estar muy hiladas y ser asíncronas, por lo que no se ofrecen garantías sobre el orden relativo y los tiempos de los mensajes de depuración.

Por otro lado, el registro en modo síncrono tiene una sobrecarga elevada, pero la implementación de OpenGL garantiza que todos los mensajes causados por un determinado comando se reciben en orden, antes de que el comando regrese, y desde el mismo hilo al que está vinculado el contexto OpenGL.

Esto significa que cuando se registra en modo síncrono podrás ejecutar tu aplicación OpenGL en un depurador, poner un punto de interrupción en una ranura conectada a la señal messageLogged(), y ver en el backtrace la llamada exacta que causó el mensaje registrado. Esto puede ser extremadamente útil para depurar un problema de OpenGL. Ten en cuenta que si el renderizado OpenGL está ocurriendo en otro hilo, debes forzar el tipo de conexión señal/ranura a Qt::DirectConnection para poder ver el backtrace real.

Consulte la documentación LoggingMode enum para obtener más información sobre los modos de registro.

Inserción de mensajes en el registro de depuración

Es posible para aplicaciones y librerías insertar mensajes personalizados en el registro de depuración, por ejemplo para marcar un grupo de comandos OpenGL relacionados y así poder identificar eventuales mensajes provenientes de ellos.

Para ello, puedes crear un objeto QOpenGLDebugMessage llamando a createApplicationMessage() o createThirdPartyMessage(), y luego insertarlo en el registro llamando a logMessage():

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

logger->logMessage(message);

Ten en cuenta que las implementaciones de OpenGL tienen un límite específico del fabricante en cuanto a la longitud de los mensajes que pueden insertarse en el registro de depuración. Puedes recuperar esta longitud llamando al método maximumMessageLength(); los mensajes más largos que el límite se truncarán automáticamente.

Control de la salida de depuración

QOpenGLDebugMessage también puede aplicar filtros a los mensajes de depuración y, por tanto, limitar la cantidad de mensajes registrados. Puede activar o desactivar el registro de mensajes llamando a enableMessages() y disableMessages() respectivamente. Por defecto, se registran todos los mensajes.

Es posible activar o desactivar los mensajes seleccionándolos por:

• fuente, tipo y gravedad (e incluyendo todos los ids en la selección);
• id, fuente y tipo (e incluyendo todas las severidades en la selección).

Tenga en cuenta que el estado "activado" de un mensaje determinado es una propiedad de la tupla (id, source, type, severity); los atributos del mensaje no forman una jerarquía de ningún tipo. Debes tener cuidado con el orden de las llamadas a enableMessages() y disableMessages(), ya que cambiará qué mensajes se habilitarán / deshabilitarán.

No es posible filtrar por el propio texto del mensaje; las aplicaciones tienen que hacerlo por su cuenta (en las ranuras conectadas a la señal messageLogged(), o después de obtener los mensajes en el registro de depuración interno a través de loggedMessages()).

Para simplificar la gestión de los estados habilitados / deshabilitados, QOpenGLDebugMessage también soporta el concepto de debug groups. Un grupo de depuración contiene el grupo de configuraciones habilitadas / deshabilitadas de los mensajes de depuración. Además, los grupos de depuración se organizan en una pila: es posible insertar y extraer grupos llamando a pushGroup() y popGroup() respectivamente. (Cuando se crea un contexto OpenGL, ya hay un grupo en la pila).

Las funciones enableMessages() y disableMessages() modificarán la configuración del grupo de depuración actual, es decir, el que se encuentra en la parte superior de la pila de grupos de depuración.

Cuando se introduce un nuevo grupo en la pila de grupos de depuración, heredará la configuración del grupo que se encontraba anteriormente en la parte superior de la pila. A la inversa, al hacer popping de un grupo de depuración se restaurará la configuración del grupo de depuración que se convierte en el nuevo top.

La inserción (o extracción) de grupos de depuración también generará automáticamente un mensaje de depuración del tipo QOpenGLDebugMessage::GroupPushType (o GroupPopType).