Qt Quick Grafo de escena
El grafo de escena en Qt Quick
Qt Quick 2 utiliza un grafo de escena específico que, posteriormente, se recorre y se renderiza mediante una API gráfica como OpenGL ES, OpenGL, Vulkan, Metal o Direct 3D. El uso de un grafo de escena para los gráficos, en lugar de los sistemas tradicionales de dibujo imperativos (QPainter y similares), permite conservar la escena que se va a renderizar entre fotogramas y conocer el conjunto completo de primitivas que se van a renderizar antes de que comience el proceso. Esto abre la puerta a una serie de optimizaciones, como el renderizado por lotes para minimizar los cambios de estado y el descarte de primitivas ocultas.
Por ejemplo, supongamos que una interfaz de usuario contiene una lista de diez elementos, cada uno de los cuales tiene un color de fondo, un icono y un texto. Si se utilizaran las técnicas de dibujo tradicionales, esto daría lugar a 30 llamadas de dibujo y a un número similar de cambios de estado. Un grafo de escena, por el contrario, podría reorganizar las primitivas que se van a renderizar de tal forma que todos los fondos se dibujen en una sola llamada, luego todos los iconos y, por último, todo el texto, reduciendo así el número total de llamadas de dibujo a solo 3. El procesamiento por lotes y la reducción de los cambios de estado como esta pueden mejorar considerablemente el rendimiento en determinados tipos de hardware.
El grafo de escena está estrechamente vinculado a « Qt Quick » 2.0 y no puede utilizarse de forma independiente. El grafo de escena es gestionado y renderizado por la clase « QQuickWindow », y los tipos de «Item» personalizados pueden añadir sus primitivas gráficas al grafo de escena mediante una llamada a « QQuickItem::updatePaintNode()».
El grafo de escena es una representación gráfica de la escena de elementos, una estructura independiente que contiene información suficiente para renderizar todos los elementos. Una vez configurado, puede manipularse y renderizarse independientemente del estado de los elementos. En muchas plataformas, el grafo de escena incluso se renderizará en un hilo de renderizado dedicado mientras el hilo de la interfaz gráfica de usuario prepara el estado del siguiente fotograma.
Nota: Gran parte de la información que figura en esta página es específica del comportamiento predeterminado e integrado del grafo de escena « Qt Quick ». Al utilizar una adaptación alternativa del grafo de escena, como la adaptación « software », es posible que no se apliquen todos los conceptos. Para obtener más información sobre las diferentes adaptaciones del grafo de escena, consulta Adaptaciones del grafo de escena.
Qt Quick Estructura del grafo de escena
El grafo de escena se compone de varios tipos de nodos predefinidos, cada uno de los cuales cumple una función específica. Aunque nos referimos a él como «grafo de escena», una definición más precisa sería «árbol de nodos». El árbol se construye a partir de tipos de « QQuickItem » en la escena QML y, internamente, la escena es procesada por un renderizador que se encarga de dibujarla. Los nodos en sí mismos no contienen ningún código de dibujo activo ni ninguna función virtual « paint() ».
Aunque el árbol de nodos se construye en su mayor parte internamente a partir de los tipos QML existentes de « Qt Quick », los usuarios también pueden añadir subárboles completos con su propio contenido, incluidos subárboles que representan modelos 3D.
Nodos
El nodo más importante para los usuarios es el QSGGeometryNode. Se utiliza para definir gráficos personalizados mediante la definición de su geometría y su material. La geometría se define mediante QSGGeometry y describe la forma o malla de la primitiva gráfica. Puede ser una línea, un rectángulo, un polígono, varios rectángulos desconectados o una malla 3D compleja. El material define cómo se rellenan los píxeles de esta forma.
Un nodo puede tener cualquier número de hijos, y los nodos de geometría se renderizarán de forma que aparezcan en orden descendente, con los padres detrás de sus hijos.
Nota: Esto no dice nada sobre el orden de renderizado real en el renderizador. Solo se garantiza el resultado visual.
Los nodos disponibles son:
Implementa la funcionalidad de recorte en el grafo de escena | |
Se utiliza para todo el contenido renderizado en el grafo de escena | |
La clase base para todos los nodos del grafo de escena | |
Se utiliza para cambiar la opacidad de los nodos | |
Implementa transformaciones en el grafo de escena |
Los nodos personalizados se añaden al grafo de escena creando una subclase de ` QQuickItem::updatePaintNode()` y estableciendo el indicador ` QQuickItem::ItemHasContents `.
Advertencia: Es fundamental que las operaciones gráficas nativas (OpenGL, Vulkan, Metal, etc.) y la interacción con el grafo de escena se realicen exclusivamente en el hilo de renderizado, principalmente durante la llamada a `updatePaintNode()`. La regla general es utilizar únicamente clases con el prefijo «QSG» dentro de la función ` QQuickItem::updatePaintNode()`.
Para obtener más detalles, consulta «Grafo de escena: geometría personalizada».
Preprocesamiento
Los nodos disponen de una función virtual ` QSGNode::preprocess()`, que se invoca antes de que se renderice el grafo de escena. Las subclases de los nodos pueden establecer el indicador ` QSGNode::UsePreprocess ` y sobrescribir la función ` QSGNode::preprocess()` para realizar los preparativos finales de su nodo. Por ejemplo, dividir una curva Bézier en el nivel de detalle adecuado para el factor de escala actual o actualizar una sección de una textura.
Propiedad de los nodos
La propiedad de los nodos la establece explícitamente el creador o bien el grafo de escena al activar el indicador « QSGNode::OwnedByParent ». A menudo es preferible asignar la propiedad al grafo de escena, ya que simplifica la limpieza cuando el grafo de escena se ejecuta fuera del hilo de la interfaz gráfica de usuario.
Materiales
El material describe cómo se rellena el interior de una geometría en un « QSGGeometryNode ». Encapsula los sombreadores gráficos para las etapas de vértices y fragmentos del proceso de renderizado y ofrece una gran flexibilidad en cuanto a lo que se puede conseguir, aunque la mayoría de los elementos de « Qt Quick » solo utilizan materiales muy básicos, como rellenos de color liso y texturas.
Los usuarios que solo deseen aplicar un sombreado personalizado a un tipo de elemento QML pueden hacerlo directamente en QML utilizando el tipo « ShaderEffect ».
A continuación se muestra una lista completa de clases de materiales:
Una forma práctica de renderizar geometría de color sólido en el grafo de escena | |
Encapsula el estado de renderizado de un programa de sombreado | |
Representa un programa de sombreado independiente de la API gráfica | |
Se utiliza como un token de tipo único en combinación con QSGMaterial | |
Una forma práctica de renderizar geometría texturizada en el grafo de escena | |
Forma práctica de renderizar geometría texturizada en el grafo de escena | |
Forma práctica de renderizar geometría coloreada por vértice en el grafo de escena |
Nodos de conveniencia
La API del grafo de escena es de bajo nivel y se centra en el rendimiento más que en la comodidad. Escribir geometrías y materiales personalizados desde cero, incluso los más básicos, requiere una cantidad de código nada desdeñable. Por este motivo, la API incluye algunas clases de conveniencia para que los nodos personalizados más comunes estén fácilmente disponibles.
- QSGSimpleRectNode - una subclase de ` QSGGeometryNode ` que define una geometría rectangular con un material de color sólido.
- QSGSimpleTextureNode - Una subclase de ` QSGGeometryNode ` que define una geometría rectangular con un material de textura.
Grafo de escena y renderizado
El renderizado del grafo de escena se lleva a cabo internamente en la clase ` QQuickWindow `, y no existe una API pública para acceder a él. Sin embargo, hay algunos puntos en el proceso de renderizado en los que el usuario puede incorporar código de aplicación. Esto puede utilizarse para añadir contenido personalizado al grafo de escena o para insertar comandos de renderizado arbitrarios llamando directamente a la API gráfica (OpenGL, Vulkan, Metal, etc.) que utiliza el grafo de escena. Los puntos de integración vienen definidos por el bucle de renderizado.
Para obtener una descripción detallada del funcionamiento del renderizador del grafo de escena, consulta «Renderizador predeterminado del grafo de escena deQt Quick ».
Hay dos variantes de bucle de renderizado disponibles: basic y threaded. basic es de un solo hilo, mientras que threaded realiza el renderizado del grafo de escena en un hilo dedicado. Qt intenta elegir un bucle adecuado en función de la plataforma y, posiblemente, de los controladores gráficos en uso. Cuando esto no resulta satisfactorio, o con fines de prueba, se puede utilizar la variable de entorno QSG_RENDER_LOOP para forzar el uso de un bucle determinado. Para comprobar qué bucle de renderizado se está utilizando, activa la opción « qt.scenegraph.general » ( logging category).
Bucle de renderizado multihilo («threaded»)
En muchas configuraciones, el renderizado del grafo de escena se realizará en un hilo de renderizado dedicado. Esto se hace para aumentar el paralelismo de los procesadores multinúcleo y aprovechar mejor los tiempos de espera, como los que se producen al esperar una llamada bloqueante al búfer de intercambio. Esto ofrece mejoras significativas en el rendimiento, pero impone ciertas restricciones sobre dónde y cuándo puede producirse la interacción con el grafo de escena.
A continuación se ofrece una descripción sencilla de cómo se renderiza un fotograma con el bucle de renderizado multihilo y OpenGL. Los pasos son los mismos que con otras API gráficas, salvo por los aspectos específicos del contexto de OpenGL.

- Se produce un cambio en la escena QML, lo que provoca que se llame a `
QQuickItem::update()`. Esto puede ser el resultado, por ejemplo, de una animación o de una entrada del usuario. Se envía un evento al hilo de renderizado para iniciar un nuevo fotograma. - El hilo de renderizado se prepara para dibujar un nuevo fotograma e inicia un bloqueo en el hilo de la interfaz gráfica de usuario.
- Mientras el hilo de renderizado prepara el nuevo fotograma, el hilo de la interfaz gráfica de usuario llama a ` QQuickItem::updatePolish()` para realizar los últimos retoques en los elementos antes de que se rendericen.
- El hilo de la interfaz gráfica de usuario queda bloqueado.
- Se emite la señal ` QQuickWindow::beforeSynchronizing()`. Las aplicaciones pueden establecer conexiones directas (utilizando ` Qt::DirectConnection`) con esta señal para realizar cualquier preparación necesaria antes de llamar a ` QQuickItem::updatePaintNode()`.
- Sincronización del estado de QML con el grafo de escena. Esto se lleva a cabo llamando a la función ` QQuickItem::updatePaintNode()` en todos los elementos que hayan cambiado desde el fotograma anterior. Este es el único momento en el que los elementos de QML y los nodos del grafo de escena interactúan.
- Se libera el bloqueo del hilo de la interfaz gráfica de usuario.
- Se renderiza el grafo de escena:
- Se emite la señal « QQuickWindow::beforeRendering()». Las aplicaciones pueden establecer conexiones directas (mediante « Qt::DirectConnection ») con esta señal para utilizar llamadas personalizadas a la API gráfica, que luego se superpondrán visualmente debajo de la escena QML.
- A los elementos que hayan especificado ` QSGNode::UsePreprocess` se les invocará la función ` QSGNode::preprocess()`.
- El renderizador procesa los nodos.
- El renderizador genera estados y registra llamadas de dibujo para la API gráfica en uso.
- Se emite la señal « QQuickWindow::afterRendering()». Las aplicaciones pueden establecer conexiones directas (mediante « Qt::DirectConnection ») con esta señal para emitir llamadas personalizadas a la API gráfica, que luego se superpondrán visualmente sobre la escena QML.
- El fotograma ya está listo. Se intercambian los búferes (OpenGL) o se registra un comando de presentación y los búferes de comandos se envían a una cola gráfica (Vulkan, Metal). Se emite QQuickWindow::frameSwapped().
- Mientras el hilo de renderizado está renderizando, la interfaz gráfica de usuario (GUI) tiene libertad para avanzar en las animaciones, procesar eventos, etc.
El renderizador multihilo se utiliza actualmente de forma predeterminada en Windows con Direct3D 11 y con OpenGL cuando se utiliza opengl32.dll; en Linux, excepto con Mesa llvmpipe; en macOS con Metal; en plataformas móviles; y en Linux embebido con EGLFS, así como con Vulkan independientemente de la plataforma. Todo esto puede cambiar en futuras versiones. Siempre es posible forzar el uso del renderizador multihilo configurando ` QSG_RENDER_LOOP=threaded ` en el entorno.
Bucle de renderizado sin subprocesos («básico»)
El bucle de renderizado sin subprocesos se utiliza actualmente de forma predeterminada en Windows con OpenGL cuando no se utiliza el archivo opengl32.dll estándar del sistema, en macOS con OpenGL, en WebAssembly y en Linux con algunos controladores. En este último caso, se trata principalmente de una medida de precaución, ya que no se han probado todas las combinaciones de controladores de OpenGL y sistemas de ventanas.
En macOS y OpenGL, el bucle de renderizado multihilo no es compatible al compilar con Xcode 10 (SDK 10.14) o versiones posteriores, ya que esto habilita las vistas respaldadas por capas en macOS 10.14. Puedes compilar con Xcode 9 (SDK 10.13) para desactivar el respaldo de capas; en ese caso, el bucle de renderizado multihilo estará disponible y se utilizará de forma predeterminada. No existe tal restricción con Metal.
El bucle de renderizado en subprocesos no es compatible con WebAssembly, ya que la plataforma web tiene una compatibilidad limitada con el uso de WebGL en subprocesos distintos del subproceso principal, así como una compatibilidad limitada con el bloqueo del subproceso principal.
Incluso cuando se utilice el bucle de renderizado sin subprocesos, debes escribir el código como si estuvieras utilizando el renderizador con subprocesos, ya que, de no hacerlo, el código dejará de ser portátil.
A continuación se muestra una ilustración simplificada de la secuencia de renderizado de fotogramas en el renderizador sin subprocesos.

Animaciones de conducción
¿A qué se refiere « Advance Animations » en los diagramas anteriores?
Por defecto, una animación de « Qt Quick » (como, por ejemplo, NumberAnimation) se controla mediante el controlador de animación predeterminado. Este se basa en temporizadores básicos del sistema, como QObject::startTimer(). El temporizador suele funcionar con un intervalo de 16 milisegundos. Aunque esto nunca será totalmente preciso y también depende de la precisión de los temporizadores de la plataforma subyacente, tiene la ventaja de ser independiente del renderizado. Proporciona resultados uniformes independientemente de la frecuencia de actualización de la pantalla y de si la sincronización con la sincronización vertical de la pantalla está activa o no. Así es como funcionan las animaciones con el bucle de renderizado « basic ».
Para ofrecer resultados más precisos con menos saltos en pantalla, independientemente del diseño del bucle de renderizado (ya sea de un solo hilo o de varios hilos), un bucle de renderizado puede optar por implementar su propio controlador de animación personalizado y hacerse cargo personalmente de l advancing, sin depender de temporizadores.
Esto es lo que implementa el bucle de renderizado de threaded. De hecho, no instala uno, sino dos controladores de animación: uno en el hilo de la interfaz gráfica de usuario (para gestionar animaciones normales, como NumberAnimation) y otro en el hilo de renderizado (para gestionar animaciones del hilo de renderizado, es decir, los tipos de Animator, como OpacityAnimator o XAnimator). Ambas se actualizan durante la preparación de un fotograma, es decir, las animaciones ahora se sincronizan con el renderizado. Esto tiene sentido, ya que la presentación se limita a la sincronización vertical de la pantalla por parte de la pila gráfica subyacente.
Por lo tanto, en el diagrama del bucle de renderizado de « threaded » anterior, hay un paso explícito de « Advance animations » en ambos subprocesos. Para el hilo de renderizado, esto es trivial: dado que el hilo está limitado por la sincronización vertical (vsync), hacer avanzar las animaciones (para tipos de « Animator ») en cada fotograma como si hubieran transcurrido 16,67 milisegundos ofrece resultados más precisos que basarse en un temporizador del sistema. (cuando se limita a la sincronización de vsync, que es de 1000/60 milisegundos con una frecuencia de actualización de 60 Hz, es razonable suponer que ha transcurrido aproximadamente ese tiempo desde que se realizó la misma operación para el fotograma anterior)
El mismo enfoque funciona también para las animaciones en el hilo de la interfaz gráfica de usuario (principal): debido a la sincronización esencial de los datos entre los hilos de la interfaz gráfica de usuario y de renderizado, el hilo de la interfaz gráfica de usuario queda, en la práctica, limitado a la misma frecuencia que el hilo de renderizado, al tiempo que sigue teniendo la ventaja de tener menos trabajo que realizar, lo que deja más margen para la lógica de la aplicación, ya que gran parte de los preparativos de renderizado se descargan ahora al hilo de renderizado.
Aunque en los ejemplos anteriores se utilizaban 60 fotogramas por segundo, « Qt Quick » también está preparado para otras frecuencias de actualización: la frecuencia se consulta a través de la interfaz « QScreen » y de la plataforma. Por ejemplo, con una pantalla de 144 Hz, el intervalo es de 6,94 ms. Al mismo tiempo, esto es precisamente lo que puede causar problemas si la limitación basada en vsync no funciona como se espera, ya que si lo que el bucle de renderizado cree que está ocurriendo no se corresponde con la realidad, se producirá un ritmo de animación incorrecto.
Nota: A partir de Qt 6.5, el bucle de renderizado multihilo ofrece la posibilidad de optar por otro controlador de animación, basado únicamente en el tiempo transcurrido (QElapsedTimer). Para habilitarlo, establece la variable de entorno QSG_USE_SIMPLE_ANIMATION_DRIVER en un valor distinto de cero. Esto tiene la ventaja de no necesitar ninguna infraestructura para recurrir a un « QTimer » cuando hay varias ventanas, de no requerir heurísticas que intenten determinar si la limitación basada en vsync falta o no funciona, de ser compatible con cualquier tipo de desviación temporal en la limitación de vsync, y no estar supeditado a la frecuencia de actualización de la pantalla principal, lo que podría mejorar su funcionamiento en configuraciones multipantalla. Además, gestiona correctamente las animaciones del hilo de renderizado (del tipo Animator ) incluso si la limitación basada en vsync no funciona o está desactivada. Por otro lado, las animaciones pueden percibirse como menos fluidas con este enfoque. Teniendo en cuenta la compatibilidad, por el momento se ofrece como una función opcional.
En resumen, se espera que el bucle de renderizado « threaded » proporcione animaciones más fluidas y con menos saltos, siempre que se cumplan las siguientes condiciones:
- Que haya exactamente una ventana (como en « QQuickWindow ») en pantalla.
- La limitación basada en VSync funciona según lo esperado con la pila subyacente de gráficos y visualización.
¿Qué ocurre si no hay ninguna ventana visible o hay más de una?
Cuando no hay ninguna ventana que se pueda renderizar, por ejemplo, porque nuestro QQuickWindow está minimizado (Windows) o totalmente oculto (macOS), no podemos mostrar fotogramas, por lo que no podemos confiar en que el hilo «funcione» al ritmo de la frecuencia de actualización de la pantalla. En este caso, el bucle de renderizado de threaded cambia automáticamente a un enfoque basado en el temporizador del sistema para controlar las animaciones, es decir, pasa temporalmente al mecanismo que utilizaría el bucle de basic.
Lo mismo ocurre cuando hay más de una instancia de « QQuickWindow » en pantalla. El modelo presentado anteriormente para hacer avanzar las animaciones en el hilo de la interfaz gráfica de usuario, que funciona gracias a su sincronización con el hilo de renderizado, ya no resulta satisfactorio, ya que ahora hay múltiples puntos de sincronización con múltiples hilos de renderizado (uno por ventana). En este caso, también resulta necesario recurrir al enfoque basado en el temporizador del sistema, ya que la duración y la frecuencia con las que se bloqueará el hilo de la interfaz gráfica dependen ahora de varios factores, entre ellos el contenido de las ventanas (¿se están animando? ¿con qué frecuencia se actualizan?) y del comportamiento de la pila gráfica (¿cómo gestiona exactamente que dos o más hilos se presenten con «wait-for-vsync»?). Dado que no podemos garantizar que se limite a la tasa de presentación de la ventana (¿qué ventana sería esa, para empezar?) de una manera estable y multiplataforma, el avance de las animaciones no puede basarse en el renderizado.
Este cambio en los mecanismos de gestión de la animación es transparente para las aplicaciones.
¿Qué ocurre si la limitación basada en vsync no funciona, está desactivada globalmente o la propia aplicación la ha desactivado?
El bucle de renderizado de « threaded » se basa en la implementación de la API gráfica y/o en el sistema de ventanas para la limitación, por ejemplo, solicitando un intervalo de intercambio de 1 en el caso de OpenGL (GLX, EGL, WGL), llamando a Present() con un intervalo de 1 para Direct 3D, o utilizando el modo de presentación « FIFO » con Vulkan.
Algunos controladores gráficos permiten a los usuarios anular esta configuración y desactivarla, ignorando la solicitud de Qt. Un ejemplo de ello sería un panel de control del controlador gráfico a nivel del sistema que permita anular la configuración de la aplicación en lo que respecta a la sincronización vertical (vsync). También puede ocurrir que una pila gráfica no sea capaz de proporcionar una limitación adecuada basada en vsync, lo que puede suceder en algunas máquinas virtuales (principalmente debido al uso de una implementación de OpenGL o Vulkan basada en rasterización por software).
Sin el bloqueo en la operación de intercambio/presentación (o en alguna otra operación gráfica), dicho bucle de renderizado avanzaría las animaciones demasiado rápido. Esto no supondría ningún problema con el bucle de renderizado « basic », ya que este siempre se basa en los temporizadores del sistema. Con « threaded », el comportamiento puede variar en función de la versión de Qt:
- Si se sabe que un sistema no puede proporcionar una limitación basada en vsync, la única opción antes de Qt 6.4 era utilizar el bucle de renderizado «
basic», configurando manualmente `QSG_RENDER_LOOP=basic` en el entorno antes de ejecutar la aplicación. - A partir de Qt 6.4, tanto establecer la variable de entorno `
QSG_NO_VSYNC` en un valor distinto de cero como establecer ` QSurfaceFormat::swapInterval()` de la ventana en `0` pueden aliviar el problema: al solicitar explícitamente la desactivación del bloqueo basado en vsync —independientemente de que la solicitud tenga algún efecto en la práctica—, el bucle de renderizado dethreadedpuede, por extensión, reconocer que confiar en vsync para controlar las animaciones es inútil, y recurrirá al uso de temporizadores del sistema, tal y como lo haría si hubiera más de una ventana. - Aún mejor, a partir de Qt 6.4, el grafo de escena también intenta reconocer, mediante algunas heurísticas sencillas, que los fotogramas se están presentando «demasiado rápido», y cambia automáticamente a los temporizadores del sistema si lo considera necesario. Esto significa que, en la mayoría de los casos, no habrá necesidad de hacer nada y las aplicaciones ejecutarán las animaciones según lo esperado, incluso cuando el bucle de renderizado predeterminado sea el de «
threaded». Aunque esto es transparente para las aplicaciones, a efectos de resolución de problemas y desarrollo resulta útil saber que se registra con un mensaje de «"Window 0x7ffc8489c3d0 is determined to have broken vsync throttling ..."» que se muestra cuando se habilita «QSG_INFO» o «qt.scenegraph.general». Este método tiene el inconveniente de que solo se activa tras un pequeño conjunto de fotogramas, ya que primero necesita recopilar datos para realizar la evaluación, lo que significa que, al abrir un QQuickWindow, la aplicación puede seguir mostrando animaciones excesivamente rápidas durante un breve periodo de tiempo. Además, es posible que no detecte todas las situaciones posibles en las que se rompa la sincronización vertical (vsync).
Sin embargo, recuerda que, por diseño, nada de esto ayuda a renderizar animaciones de subproceso (del tipo Animator ). En ausencia de un bloqueo basado en vsync, animators avanzará de forma incorrecta por defecto, más rápido de lo esperado, incluso cuando se activen las soluciones provisionales para animations normales. Si esto supone un problema, considera utilizar el controlador de animación alternativo configurando QSG_USE_SIMPLE_ANIMATION_DRIVER.
Nota: Ten en cuenta que la lógica del bucle de renderizado y el procesamiento de eventos en el hilo de la interfaz gráfica de usuario (principal) no están necesariamente sin restricciones, incluso si se desactiva la espera de vsync: ambos bucles de renderizado programan actualizaciones para las ventanas mediante QWindow::requestUpdate(). Esto se respalda con un temporizador del hilo de la interfaz gráfica de usuario de 5 ms en la mayoría de las plataformas, con el fin de dar tiempo para el procesamiento de eventos. En algunas plataformas, por ejemplo, macOS, se utilizan API específicas de la plataforma (como CVDisplayLink) para recibir notificaciones sobre el momento adecuado para preparar un nuevo fotograma, lo que probablemente esté vinculado de alguna forma al vsync de la pantalla. Esto puede ser relevante en pruebas de rendimiento y situaciones similares. Para aplicaciones y herramientas que intenten realizar pruebas de rendimiento de bajo nivel, puede resultar beneficioso establecer la variable de entorno ` QT_QPA_UPDATE_IDLE_TIME ` en ` 0 `, con el fin de reducir potencialmente el tiempo de inactividad en el hilo de la interfaz gráfica de usuario. Para el uso normal de la aplicación, los valores predeterminados deberían ser suficientes en la mayoría de los casos.
Nota: En caso de duda, activa las categorías de registro « qt.scenegraph.general » y « qt.scenegraph.time.renderloop » para la resolución de problemas, ya que pueden revelar algunas pistas sobre por qué el renderizado y las animaciones no se ejecutan al ritmo esperado.
Control personalizado del renderizado con QQuickRenderControl
Al utilizar ` QQuickRenderControl`, la responsabilidad de gestionar el bucle de renderizado se transfiere a la aplicación. En este caso, no se utiliza ningún bucle de renderizado integrado. En su lugar, corresponde a la aplicación invocar los pasos de pulido, sincronización y renderizado en el momento adecuado. Es posible implementar un comportamiento con o sin subprocesos, similar a los mostrados anteriormente.
Además, es posible que las aplicaciones deseen implementar e instalar su propio QAnimationDriver junto con QQuickRenderControl. Esto proporciona un control total sobre el control de las animaciones de Qt Quick, lo cual puede resultar especialmente importante para contenidos que no se muestran en pantalla y que no guardan relación con la frecuencia de presentación, simplemente porque no se está mostrando el fotograma en cuestión. Esto es opcional; por defecto, las animaciones avanzarán según el temporizador del sistema.
Ampliación del grafo de escena con renderizado 3D nativo y basado en QRhi
El grafo de escena ofrece tres métodos para integrar comandos gráficos proporcionados por la aplicación:
- Emisión de comandos basados en « QRhi » o en OpenGL, Vulkan, Metal y Direct3D directamente antes o después del propio renderizado del grafo de escena. En la práctica, esto añade al principio o al final un conjunto de llamadas de dibujo en la pasada de renderizado principal. No se utiliza ningún destino de renderizado adicional.
- Realizar el renderizado en una textura y crear un nodo texturizado en el grafo de escena. Esto implica una pasada de renderizado y un destino de renderizado adicionales.
- Emisión de llamadas de dibujo en línea con el propio renderizado del grafo de escena mediante la instanciación de una subclase de ` QSGRenderNode ` en el grafo de escena. Esto es similar al primer enfoque, pero las llamadas de dibujo personalizadas se inyectan efectivamente en el flujo de comandos del grafo de escena.
Modo de superposición/subyacente
Al conectarse a las señales « QQuickWindow::beforeRendering()» y « QQuickWindow::afterRendering()», las aplicaciones pueden realizar llamadas a la API 3D nativa o a « QRhi » directamente en el mismo contexto en el que se está renderizando el grafo de escena. Con API como Vulkan o Metal, las aplicaciones pueden consultar objetos nativos —como el búfer de comandos del grafo de escena— a través de « QSGRendererInterface », y registrar comandos en él según consideren oportuno. Tal y como indican los nombres de las señales, el usuario puede renderizar contenido bien bajo una escena de Qt Quick o bien sobre ella. La ventaja de esta integración es que no se necesitan objetivos de renderizado adicionales para realizar el renderizado, y se elimina un paso de texturizado que podría resultar costoso. La desventaja es que el renderizado personalizado solo puede ejecutarse al principio o al final del propio renderizado de Qt Quick. El uso de ` QSGRenderNode ` en lugar de las señales ` QQuickWindow ` puede aliviar en cierta medida esa restricción, pero en cualquier caso hay que tener cuidado con el contenido 3D y el uso del búfer de profundidad, ya que basarse en las pruebas de profundidad y renderizar con la escritura de profundidad habilitada puede crear fácilmente situaciones en las que el uso del búfer de profundidad del contenido personalizado y el de Qt Quick entren en conflicto entre sí.
A partir de Qt 6.6, las API de QRhi se consideran semipúblicas, es decir, se ofrecen a las aplicaciones y están documentadas, aunque con una garantía de compatibilidad limitada. Esto permite crear código de renderizado 2D/3D portátil y multiplataforma utilizando las mismas abstracciones gráficas y de sombreadores que utiliza el propio grafo de escena.
El ejemplo «Scene Graph - RHI Under QML » muestra cómo implementar el enfoque de subcapa/superposición utilizando QRhi.
El ejemplo «Scene Graph - OpenGL Under QML » muestra cómo utilizar estas señales con OpenGL.
El ejemplo «Scene Graph - Direct3D 11 Under QML » muestra cómo utilizar estas señales con Direct3D.
El ejemplo «Grafo de escena: Metal en QML» muestra cómo utilizar estas señales con Metal.
El ejemplo «Scene Graph - Vulkan Under QML » muestra cómo utilizar estas señales con Vulkan.
A partir de Qt 6.0, el uso directo de la API gráfica subyacente debe estar enmarcado por una llamada a QQuickWindow::beginExternalCommands() y QQuickWindow::endExternalCommands(). Este concepto puede resultar familiar por QPainter::beginNativePainting(), y tiene una finalidad similar: permite que el grafo de escena Qt Quick reconozca que cualquier estado almacenado en caché y cualquier suposición sobre el estado dentro de la pasada de renderizado actualmente registrada, si la hay, ya no son válidos, ya que el código de la aplicación puede haberlos alterado al trabajar directamente con la API gráfica subyacente. Esto no es aplicable ni necesario cuando se utiliza QRhi.
Al combinar el renderizado OpenGL personalizado con el grafo de escena, es importante que la aplicación no deje el contexto de OpenGL en un estado con búferes vinculados, atributos habilitados, valores especiales en el búfer Z o en el búfer de plantilla, o similares. Hacerlo puede dar lugar a un comportamiento impredecible.
El código de renderizado personalizado debe tener en cuenta los subprocesos, en el sentido de que no debe dar por sentado que se ejecuta en el subproceso de la interfaz gráfica de usuario (principal) de la aplicación. Al conectarse a las señales QQuickWindow, la aplicación debe utilizar Qt::DirectConnection y tener en cuenta que las ranuras conectadas se invocan en el subproceso de renderizado dedicado del grafo de escena, si existe.
El enfoque basado en texturas
La alternativa basada en texturas es el enfoque más flexible cuando la aplicación necesita disponer de una imagen 2D «aplanada» de algún renderizado 3D personalizado dentro de la escena Qt Quick. Esto también permite utilizar un búfer de profundidad/estarcido dedicado que sea independiente de los búferes utilizados por la pasada de renderizado principal.
Al utilizar OpenGL, se puede recurrir a la clase de conveniencia heredada ` QQuickFramebufferObject ` para lograrlo. Los renderizadores personalizados basados en ` QRhi` y las API gráficas distintas de OpenGL también pueden seguir este enfoque, aunque ` QQuickFramebufferObject ` no las admita actualmente. En los siguientes ejemplos se muestra cómo crear y renderizar directamente en una textura con la API subyacente, para a continuación envolver y utilizar este recurso en una escena de Qt Quick dentro de un QQuickItem personalizado:
Grafo de escena: ejemplode elemento de textura RHI.
Grafo de escena: ejemplode importación de texturas de Vulkan.
Grafo de escena: ejemplode importación de texturas Metal.
El enfoque en línea
Al utilizar QSGRenderNode, las llamadas de dibujo personalizadas no se insertan al principio ni al final de la grabación de la pasada de renderizado del grafo de escena, sino durante el proceso de renderizado del mismo. Esto se consigue creando un ` QQuickItem ` personalizado basado en una instancia de ` QSGRenderNode`, un nodo del grafo de escena que existe específicamente para permitir la emisión de comandos gráficos, ya sea a través de ` QRhi ` o de una API 3D nativa como OpenGL, Vulkan, Metal o Direct 3D.
El ejemplo «Grafo de escena: QSGRenderNode personalizado» muestra cómo funciona este enfoque.
Elementos personalizados con QPainter
El ` QQuickItem ` proporciona una subclase, ` QQuickPaintedItem`, que permite a los usuarios renderizar contenido utilizando ` QPainter`.
Advertencia: El uso de QQuickPaintedItem implica el uso de una superficie 2D indirecta para renderizar su contenido, ya sea mediante rasterización por software o mediante un objeto de búfer de fotogramas (FBO) de OpenGL, por lo que el renderizado es una operación en dos pasos. Primero se rasteriza la superficie y, a continuación, se dibuja. El uso directo de la API del grafo de escena siempre es significativamente más rápido.
Compatibilidad con el registro
El grafo de escena admite varias categorías de registro. Estas pueden resultar útiles para localizar tanto problemas de rendimiento como errores, además de ser de gran ayuda para los colaboradores de Qt.
qt.scenegraph.time.texture- registra el tiempo dedicado a la carga de texturasqt.scenegraph.time.compilation- registra el tiempo dedicado a la compilación de shadersqt.scenegraph.time.renderer- Registra el tiempo dedicado a los distintos pasos del renderizadorqt.scenegraph.time.renderloop- Registra el tiempo dedicado a los distintos pasos del bucle de renderizado. Con el bucle de renderizado «threaded», esto permite conocer el tiempo transcurrido entre los distintos pasos de preparación de fotogramas, tanto en la interfaz gráfica de usuario como en el hilo de renderizado. Por lo tanto, también puede ser una herramienta útil para la resolución de problemas, por ejemplo, para confirmar cómo la limitación basada en vsync y otros activadores de bajo nivel de Qt, como QWindow::requestUpdate(), afectan al proceso de renderizado y presentación.qt.scenegraph.time.glyph- registra el tiempo dedicado a preparar los glifos del campo de distanciaqt.scenegraph.general- registra información general sobre diversas partes del grafo de escena y la pila de gráficosqt.scenegraph.renderloop- crea un registro detallado de las distintas etapas implicadas en el renderizado. Este modo de registro resulta especialmente útil para los desarrolladores que trabajan con Qt.
También está disponible la variable de entorno heredada ` QSG_INFO `. Al establecerla en un valor distinto de cero, se habilita la categoría ` qt.scenegraph.general `.
Nota: Si se producen problemas gráficos, o en caso de duda sobre qué bucle de renderizado o API gráfica se está utilizando, inicie siempre la aplicación con al menos qt.scenegraph.general y qt.rhi.* habilitados, o con QSG_INFO=1 configurado. De este modo, se mostrará información esencial en la salida de depuración durante la inicialización.
Backend del grafo de escena
Además de la API pública, el grafo de escena cuenta con una capa de adaptación que permite realizar adaptaciones específicas para el hardware. Se trata de una API de complementos privada, interna y no documentada, que permite a los equipos de adaptación de hardware sacar el máximo partido a su hardware. Incluye:
- Texturas personalizadas; concretamente, la implementación de ` QQuickWindow::createTextureFromImage ` y la representación interna de la textura utilizada por los tipos ` Image ` y ` BorderImage `.
- Renderizador personalizado; la capa de adaptación permite al complemento decidir cómo se recorre y se renderiza el grafo de escena, lo que hace posible optimizar el algoritmo de renderizado para un hardware específico o utilizar extensiones que mejoren el rendimiento.
- Implementación personalizada del grafo de escena de muchos de los tipos QML predeterminados, incluida la representación de texto y fuentes.
- Controlador de animación personalizado; permite que el sistema de animación se integre en la frecuencia de actualización vertical de la pantalla a bajo nivel para conseguir un renderizado fluido.
- Bucle de renderizado personalizado; permite un mayor control sobre cómo gestiona QML las ventanas múltiples.
© 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.