QOpenGLDebugLogger Class
QOpenGLDebugLogger permite registrar mensajes de depuración de OpenGL. Más información...
| Encabezado: | #include <QOpenGLDebugLogger> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS OpenGL) target_link_libraries(mytarget PRIVATE Qt6::OpenGL) |
| qmake: | QT += opengl |
| Heredado de: | QObject |
- Lista de todos los miembros, incluidos los heredados
- QOpenGLDebugLogger forma parte de «Renderización en 3D».
Tipos públicos
| enum | LoggingMode { AsynchronousLogging, SynchronousLogging } |
Propiedades
- loggingMode : LoggingMode
Funciones públicas
| QOpenGLDebugLogger(QObject *parent = nullptr) | |
| virtual | ~QOpenGLDebugLogger() |
| void | disableMessages(QOpenGLDebugMessage::Sources sources = QOpenGLDebugMessage::AnySource, QOpenGLDebugMessage::Types types = QOpenGLDebugMessage::AnyType, QOpenGLDebugMessage::Severities severities = QOpenGLDebugMessage::AnySeverity) |
| void | disableMessages(const QList<GLuint> &ids, QOpenGLDebugMessage::Sources sources = QOpenGLDebugMessage::AnySource, QOpenGLDebugMessage::Types types = QOpenGLDebugMessage::AnyType) |
| void | enableMessages(QOpenGLDebugMessage::Sources sources = QOpenGLDebugMessage::AnySource, QOpenGLDebugMessage::Types types = QOpenGLDebugMessage::AnyType, QOpenGLDebugMessage::Severities severities = QOpenGLDebugMessage::AnySeverity) |
| void | enableMessages(const QList<GLuint> &ids, QOpenGLDebugMessage::Sources sources = QOpenGLDebugMessage::AnySource, QOpenGLDebugMessage::Types types = QOpenGLDebugMessage::AnyType) |
| bool | initialize() |
| bool | isLogging() const |
| QList<QOpenGLDebugMessage> | loggedMessages() const |
| QOpenGLDebugLogger::LoggingMode | loggingMode() const |
| qint64 | maximumMessageLength() const |
| void | popGroup() |
| void | pushGroup(const QString &name, GLuint id = 0, QOpenGLDebugMessage::Source source = QOpenGLDebugMessage::ApplicationSource) |
Ranuras públicas
| void | logMessage(const QOpenGLDebugMessage &debugMessage) |
| void | startLogging(QOpenGLDebugLogger::LoggingMode loggingMode = AsynchronousLogging) |
| void | stopLogging() |
Señales
| void | messageLogged(const QOpenGLDebugMessage &debugMessage) |
Descripción detallada
Introducción
La programación con 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 la aplicación deje de funcionar, sin que se muestre nada en la pantalla.
La única forma de asegurarse de que la implementación de OpenGL no devuelve ningún error es comprobarlo con ` glGetError ` después de cada llamada a la API. Además, los errores de OpenGL se acumulan, por lo que `glGetError` siempre debe utilizarse en un bucle como este:
GLenum error = GL_NO_ERROR;
do {
error = glGetError();
if (error != GL_NO_ERROR) {
// handle the error
}
} while (error != GL_NO_ERROR);Si intentas borrar la pila de errores, asegúrate no solo de continuar hasta que se devuelva GL_NO_ERROR, sino también de detener el proceso ante GL_CONTEXT_LOST, ya que ese valor de error se repetirá continuamente.
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 API obsoletas. Ese tipo de mensajes no se notifican a través de los mecanismos habituales de notificación de errores de OpenGL.
QOpenGLDebugLogger tiene como objetivo abordar estos problemas proporcionando acceso al registro de depuración de OpenGL. Si tu implementación de OpenGL lo admite (exponiendo la extensión GL_KHR_debug ), los mensajes del servidor de OpenGL se registrarán en un registro interno de OpenGL o se transmitirán en «tiempo real» a los oyentes a medida que se generen desde OpenGL.
QOpenGLDebugLogger admite ambos modos de funcionamiento. Consulta las siguientes secciones para conocer las diferencias entre ellos.
Creación de un contexto de depuración de OpenGL
Por motivos de eficiencia, las implementaciones de OpenGL pueden no generar ninguna salida de depuración, a menos que el contexto de 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 objeto « 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();Ten en cuenta que solicitar un perfil OpenGL Core 3.2 es solo a efectos del ejemplo; esta clase no está vinculada a ninguna versión específica de OpenGL u OpenGL ES, ya que depende de la disponibilidad de la extensión « GL_KHR_debug » (véase más abajo).
Creación e inicialización de un QOpenGLDebugLogger
`QOpenGLDebugLogger` es una sencilla clase derivada de ` QObject`. Al igual que todas las subclases de ` QObject `, se crea una instancia (y, opcionalmente, se especifica un objeto padre) y, al igual que con el resto de funciones de Qt OpenGL, hay que inicializarla antes de usarla llamando a ` initialize()` mientras exista un contexto de OpenGL activo:
QOpenGLContext *ctx = QOpenGLContext::currentContext();
QOpenGLDebugLogger *logger = new QOpenGLDebugLogger(this);
logger->initialize(); // initializes in the current context, i.e. ctxTen 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 recuperarse utilizando la función loggedMessages():
const QList<QOpenGLDebugMessage> messages = logger->loggedMessages();
for (const QOpenGLDebugMessage&message: messages)
qDebug() << message;El registro interno tiene un tamaño limitado; cuando se llena, los mensajes más antiguos se descartan para dejar espacio a los nuevos mensajes entrantes. Al llamar a la función ` 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 comprendido 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 en tiempo real de mensajes
También es posible recibir un flujo de mensajes de depuración del servidor OpenGL a medida que los genera 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 se puede desactivar 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 pasado a startLogging(). Cuando se registra 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 al de los comandos de OpenGL que provocaron el registro de dichos mensajes. Los mensajes también podrían generarse desde un hilo distinto al hilo al que está vinculado actualmente el contexto. Esto se debe a que las implementaciones de OpenGL suelen ser altamente multihilo y asíncronas, por lo que no se ofrecen garantías sobre el orden relativo ni los tiempos de los mensajes de depuración.
Por otro lado, el registro en modo síncrono conlleva una sobrecarga elevada, pero la implementación de OpenGL garantiza que todos los mensajes generados por un comando determinado se reciban en orden, antes de que el comando devuelva un resultado, y desde el mismo hilo al que está vinculado el contexto de OpenGL.
Esto significa que, al registrar en modo síncrono, podrás ejecutar tu aplicación OpenGL en un depurador, colocar un punto de interrupción en una ranura conectada a la señal messageLogged() y ver en el seguimiento de pila la llamada exacta que provocó el mensaje registrado. Esto puede resultar extremadamente útil para depurar un problema de OpenGL. Ten en cuenta que, si el renderizado de OpenGL se está realizando en otro hilo, debes forzar el tipo de conexión de señal/ranura a « Qt::DirectConnection » para poder ver el seguimiento de pila real.
Consulte la documentación de la enumeración LoggingMode para obtener más información sobre los modos de registro.
Nota: Cuando el registro en tiempo real está habilitado, los mensajes de depuración ya no se insertarán en el registro de depuración interno de OpenGL; los mensajes que ya estén presentes en el registro interno no se eliminarán, ni se emitirán a través de la señal messageLogged(). Dado que es posible que se generen algunos mensajes antes de que se inicie el registro en tiempo real (y, por lo tanto, se mantengan en el registro interno de OpenGL), es importante comprobar siempre si contiene algún mensaje tras llamar a ` startLogging()`.
Inserción de mensajes en el registro de depuración
Las aplicaciones y bibliotecas pueden insertar mensajes personalizados en el registro de depuración, por ejemplo, para marcar un grupo de comandos OpenGL relacionados y, de este modo, poder identificar posteriormente los mensajes que puedan proceder de ellos.
Para ello, puedes crear un objeto ` QOpenGLDebugMessage ` llamando a ` createApplicationMessage()` o ` createThirdPartyMessage()`, y a continuación 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 proveedor en cuanto a la longitud de los mensajes que se pueden insertar en el registro de depuración. Puedes obtener esta longitud llamando al método maximumMessageLength(); los mensajes que superen el límite se truncarán automáticamente.
Control de la salida de depuración
QOpenGLDebugMessage también permite aplicar filtros a los mensajes de depuración y, por lo tanto, limitar la cantidad de mensajes registrados. Se puede activar o desactivar el registro de mensajes llamando a enableMessages() y disableMessages(), respectivamente. Por defecto, se registran todos los mensajes.
Es posible habilitar o deshabilitar mensajes seleccionándolos por:
- fuente, tipo y gravedad (e incluyendo todos los ID en la selección);
- ID, origen y tipo (e incluyendo todas las gravedades en la selección).
Ten en cuenta que el estado «activado» de un mensaje determinado es una propiedad de la tupla (id, fuente, tipo, gravedad); los atributos del mensaje no forman jerarquía alguna. Debes tener cuidado con el orden de las llamadas a enableMessages() y disableMessages(), ya que esto determinará qué mensajes se activarán o desactivarán.
No es posible filtrar por el propio texto del mensaje; las aplicaciones deben hacerlo por sí mismas (en slots conectados a la señal messageLogged() o tras recuperar los mensajes del registro de depuración interno mediante loggedMessages()).
Para simplificar la gestión de los estados de activación y desactivación, QOpenGLDebugMessage también admite el concepto de debug groups. Un grupo de depuración contiene el conjunto de configuraciones de activación y desactivación 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 inserta un nuevo grupo en la pila de grupos de depuración, este heredará la configuración del grupo que se encontraba anteriormente en la parte superior de la pila. A la inversa, al extraer un grupo de depuración se restablecerá la configuración del grupo de depuración que pase a ocupar la nueva posición superior.
Al insertar (o extraer, respectivamente) grupos de depuración, también se generará automáticamente un mensaje de depuración de tipo « QOpenGLDebugMessage::GroupPushType » (o « GroupPopType », respectivamente).
Véase también QOpenGLDebugMessage.
Documentación sobre los tipos de miembros
enum QOpenGLDebugLogger::LoggingMode
La enumeración `LoggingMode` define el modo de registro del objeto registrador.
| Constante | Valor | Descripción |
|---|---|---|
QOpenGLDebugLogger::AsynchronousLogging | 0 | Los mensajes del servidor OpenGL se registran de forma asíncrona. Esto significa que los mensajes pueden registrarse algún tiempo después de las acciones de OpenGL correspondientes que los provocaron, e incluso recibirse fuera de orden, dependiendo de la implementación de OpenGL. Este modo tiene un impacto muy bajo en el rendimiento, ya que las implementaciones de OpenGL son, por naturaleza, altamente multihilo y asíncronas. |
QOpenGLDebugLogger::SynchronousLogging | 1 | Los mensajes del servidor OpenGL se registran de forma sincrónica y secuencial. Esto supone una grave merma en el rendimiento, ya que las implementaciones de OpenGL son muy asíncronas por naturaleza; sin embargo, resulta muy útil para depurar problemas de OpenGL, ya que OpenGL garantiza que los mensajes generados por un comando de OpenGL se registrarán antes de que la ejecución del comando correspondiente haya finalizado. Por lo tanto, puedes colocar un punto de interrupción en la señal ` messageLogged()` y ver en el seguimiento de pila qué comando de OpenGL lo ha provocado; la única salvedad es que, si estás utilizando OpenGL desde varios subprocesos, es posible que tengas que forzar la conexión directa al conectarte a la señal ` messageLogged()`. |
Documentación de propiedades
[read-only] loggingMode : LoggingMode
Esta propiedad contiene el modo de registro pasado a la función ` startLogging()`.
Ten en cuenta que el registro debe haberse iniciado; de lo contrario, el valor de esta propiedad no tendrá sentido.
Funciones de acceso:
| QOpenGLDebugLogger::LoggingMode | loggingMode() const |
Véase también startLogging() y isLogging().
Documentación de funciones de miembro
[explicit] QOpenGLDebugLogger::QOpenGLDebugLogger(QObject *parent = nullptr)
Crea un nuevo objeto de registro con el ` parent` indicado.
Nota: El objeto debe inicializarse antes de que se pueda realizar el registro.
Véase también initialize().
[virtual noexcept] QOpenGLDebugLogger::~QOpenGLDebugLogger()
Elimina el objeto «logger».
void QOpenGLDebugLogger::disableMessages(QOpenGLDebugMessage::Sources sources = QOpenGLDebugMessage::AnySource, QOpenGLDebugMessage::Types types = QOpenGLDebugMessage::AnyType, QOpenGLDebugMessage::Severities severities = QOpenGLDebugMessage::AnySeverity)
Desactiva el registro de mensajes con el « sources » indicado, el « types » indicado y el « severities » indicado, así como con cualquier identificador de mensaje.
El registro quedará desactivado en el grupo de control actual.
Véase también enableMessages(), pushGroup() y popGroup().
void QOpenGLDebugLogger::disableMessages(const QList<GLuint> &ids, QOpenGLDebugMessage::Sources sources = QOpenGLDebugMessage::AnySource, QOpenGLDebugMessage::Types types = QOpenGLDebugMessage::AnyType)
Desactiva el registro de mensajes con el « ids » especificado, procedentes del « sources » especificado y con el « types » especificado, independientemente de su nivel de gravedad.
El registro se desactivará en el grupo de control actual.
Véase también enableMessages(), pushGroup() y popGroup().
void QOpenGLDebugLogger::enableMessages(QOpenGLDebugMessage::Sources sources = QOpenGLDebugMessage::AnySource, QOpenGLDebugMessage::Types types = QOpenGLDebugMessage::AnyType, QOpenGLDebugMessage::Severities severities = QOpenGLDebugMessage::AnySeverity)
Habilita el registro de mensajes procedentes de la dirección sources, de la dirección types y con el severities indicado, así como de cualquier ID de mensaje.
El registro se habilitará en el grupo de control actual.
Véase también disableMessages(), pushGroup() y popGroup().
void QOpenGLDebugLogger::enableMessages(const QList<GLuint> &ids, QOpenGLDebugMessage::Sources sources = QOpenGLDebugMessage::AnySource, QOpenGLDebugMessage::Types types = QOpenGLDebugMessage::AnyType)
Habilita el registro de mensajes con el « ids » especificado, procedentes del « sources » especificado y con el « types » especificado, independientemente de su nivel de gravedad.
El registro se habilitará en el grupo de control actual.
Véase también disableMessages(), pushGroup() y popGroup().
bool QOpenGLDebugLogger::initialize()
Inicializa el objeto en el contexto actual de OpenGL. Para que la inicialización se realice correctamente, el contexto debe admitir la extensión « GL_KHR_debug ». El objeto debe inicializarse antes de que pueda realizarse cualquier registro.
Es seguro llamar a esta función varias veces desde el mismo contexto.
Esta función también se puede utilizar para cambiar el contexto de un objeto previamente inicializado; ten en cuenta que, en este caso, el objeto no debe estar registrando datos cuando se llame a esta función.
Devuelve ` true ` si el registrador se ha inicializado correctamente; en caso contrario, devuelve `false`.
Véase también QOpenGLContext.
bool QOpenGLDebugLogger::isLogging() const
Devuelve ` true ` si este objeto está registrando datos en ese momento; en caso contrario, devuelve `false`.
Véase también startLogging().
[slot] void QOpenGLDebugLogger::logMessage(const QOpenGLDebugMessage &debugMessage)
Inserta el mensaje debugMessage en el registro de depuración de OpenGL. Esto permite a las aplicaciones o bibliotecas insertar mensajes personalizados que pueden facilitar la depuración de aplicaciones OpenGL.
Nota: debugMessage debe tener como origen QOpenGLDebugMessage::ApplicationSource o QOpenGLDebugMessage::ThirdPartySource, así como un tipo y una gravedad válidos; de lo contrario, no se insertará en el registro.
Nota: El objeto debe estar inicializado antes de que pueda realizarse el registro.
Véase también initialize().
QList<QOpenGLDebugMessage> QOpenGLDebugLogger::loggedMessages() const
Lee todos los mensajes disponibles en el registro de depuración interno de OpenGL y los devuelve. Además, esta función borra el registro de depuración interno, de modo que las llamadas posteriores no devolverán mensajes que ya se hayan devuelto.
Véase también startLogging().
QOpenGLDebugLogger::LoggingMode QOpenGLDebugLogger::loggingMode() const
Devuelve el modo de registro del objeto.
Nota: Funcióngetter para la propiedad loggingMode.
Véase también startLogging().
qint64 QOpenGLDebugLogger::maximumMessageLength() const
Devuelve la longitud máxima admitida, en bytes, para el texto de los mensajes pasados a logMessage(). Esta es también la longitud máxima del nombre de un grupo de depuración, ya que al añadir o eliminar grupos se registrará automáticamente un mensaje con el nombre del grupo de depuración como texto del mensaje.
Si el texto de un mensaje es demasiado largo, QOpenGLDebugLogger lo truncará automáticamente.
Nota: Los textosde los mensajes se codifican en UTF-8 cuando se pasan a OpenGL, por lo que su tamaño en bytes no suele coincidir con la cantidad de unidades de código UTF-16, tal y como devuelve, por ejemplo, la función ` QString::length()`. (Sí coincide si el mensaje contiene únicamente datos ASCII de 7 bits, lo cual es habitual en los mensajes de depuración.)
[signal] void QOpenGLDebugLogger::messageLogged(const QOpenGLDebugMessage &debugMessage)
Esta señal se emite cuando el servidor OpenGL registra un mensaje de depuración (enmarcado por el argumento « debugMessage »).
Dependiendo de la implementación de OpenGL, esta señal puede emitirse desde hilos distintos de aquel o aquellos en los que se encuentran los receptores, e incluso desde un hilo diferente al del QOpenGLContext en el que se ha inicializado este objeto. Además, la señal podría emitirse desde varios subprocesos al mismo tiempo. Normalmente esto no supone ningún problema, ya que Qt utilizará una conexión en cola para las emisiones de señales entre subprocesos; sin embargo, si se fuerza el tipo de conexión a «Direct», hay que tener en cuenta las posibles situaciones de carrera en las ranuras conectadas a esta señal.
Si se ha iniciado el registro de eventos en modo « SynchronousLogging », OpenGL garantiza que esta señal se emitirá desde el mismo hilo al que se ha vinculado el « QOpenGLContext », y nunca se producirán invocaciones concurrentes.
Nota: El registro debe haberse iniciado; de lo contrario, esta señal no se emitirá.
Véase también startLogging().
void QOpenGLDebugLogger::popGroup()
Extrae el grupo de depuración situado en la parte superior de la pila de grupos de depuración. Si el grupo se extrae correctamente, OpenGL registrará automáticamente un mensaje con el texto, el ID y la fuente que coincidan con los del grupo extraído, el tipo « QOpenGLDebugMessage::GroupPopType » y la gravedad « QOpenGLDebugMessage::NotificationSeverity ».
Al extraer un grupo de depuración, se restablecerán los ajustes de filtrado de mensajes del grupo que pase a ocupar la parte superior de la pila de grupos de depuración.
Nota: El objeto debe estar inicializado antes de gestionar grupos de depuración.
Véase también pushGroup().
void QOpenGLDebugLogger::pushGroup(const QString &name, GLuint id = 0, QOpenGLDebugMessage::Source source = QOpenGLDebugMessage::ApplicationSource)
Añade un grupo de depuración con el nombre « name », el ID « id » y la fuente « source » a la pila de grupos de depuración. Si el grupo se añade correctamente, OpenGL registrará automáticamente un mensaje con el texto « name », el ID « id », la fuente « source », el tipo « QOpenGLDebugMessage::GroupPushType » y la gravedad « QOpenGLDebugMessage::NotificationSeverity ».
El grupo recién añadido heredará la misma configuración de filtrado que el grupo que se encontraba en la parte superior de la pila; es decir, el filtrado no se modificará al añadir un nuevo grupo.
Nota: El « source » debe ser « QOpenGLDebugMessage::ApplicationSource » o « QOpenGLDebugMessage::ThirdPartySource »; de lo contrario, el grupo no se añadirá a la pila.
Nota: El objeto debe inicializarse antes de gestionar grupos de depuración.
Véase también popGroup(), enableMessages() y disableMessages().
[slot] void QOpenGLDebugLogger::startLogging(QOpenGLDebugLogger::LoggingMode loggingMode = AsynchronousLogging)
Inicia el registro de mensajes procedentes del servidor OpenGL. Cuando se recibe un nuevo mensaje, se emite la señal messageLogged(), que lleva como argumento el mensaje registrado.
loggingMode Especifica si el registro debe ser asíncrono (por defecto) o síncrono.
QOpenGLDebugLogger Registrará los valores de ` GL_DEBUG_OUTPUT ` y ` GL_DEBUG_OUTPUT_SYNCHRONOUS ` al iniciar el registro, y los restablecerá al detenerlo. Además, cualquier callback de depuración de OpenGL definida por el usuario que esté instalada cuando se invoque esta función se restablecerá al detener el registro; ` QOpenGLDebugLogger ` garantizará que la callback preexistente siga invocándose durante el registro.
Nota: Noes posible cambiar el modo de registro sin detenerlo y volver a iniciarlo. Esto podría cambiar en una futura versión de Qt.
Nota: El objeto debe estar inicializado antes de que pueda realizarse el registro.
Véase también stopLogging() y initialize().
[slot] void QOpenGLDebugLogger::stopLogging()
Deja de registrar los mensajes del servidor OpenGL.
Véase también startLogging().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.