QSGRenderNode Class
La clase QSGRenderNode representa un conjunto de comandos de renderizado personalizados dirigidos a la API gráfica que utiliza el grafo de escena. Más información...
| Encabezado: | #include <QSGRenderNode> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Heredan: | QSGNode |
Tipos públicos
| struct | RenderState |
| enum | RenderingFlag { BoundedRectRendering, DepthAwareRendering, OpaqueRendering, NoExternalRendering } |
| flags | RenderingFlags |
| enum | StateFlag { ViewportState, ScissorState, DepthState, StencilState, ColorState, …, RenderTargetState } |
| flags | StateFlags |
Funciones públicas
| virtual | ~QSGRenderNode() override |
| virtual QSGRenderNode::StateFlags | changedStates() const |
| const QSGClipNode * | clipList() const |
(since 6.6) QRhiCommandBuffer * | commandBuffer() const |
| virtual QSGRenderNode::RenderingFlags | flags() const |
| qreal | inheritedOpacity() const |
| const QMatrix4x4 * | matrix() const |
(since 6.0) virtual void | prepare() |
(since 6.5) const QMatrix4x4 * | projectionMatrix() const |
| virtual QRectF | rect() const |
| virtual void | releaseResources() |
| virtual void | render(const QSGRenderNode::RenderState *state) = 0 |
(since 6.6) QRhiRenderTarget * | renderTarget() const |
Descripción detallada
QSGRenderNode permite crear nodos de grafo de escena que realizan su propio renderizado personalizado a través de « QRhi » (el enfoque habitual a partir de Qt 6.6), directamente a través de una API de gráficos 3D como OpenGL, Vulkan o Metal, o, cuando se utiliza el backend « software », a través de QPainter.
QSGRenderNode permite una de las tres formas de integrar el renderizado 2D/3D personalizado en una escena de Qt Quick. Las otras dos opciones consisten en realizar el renderizado before o after el propio renderizado de la escena Qt Quick, o bien generar un paso de renderizado completamente independiente dirigido a un destino de renderizado específico (una textura) y, a continuación, hacer que un elemento de la escena muestre dicha textura. El enfoque basado en QSGRenderNode es similar al anterior, en el sentido de que no implica pases de renderizado ni objetivos de renderizado adicionales, y permite insertar comandos de renderizado personalizados «en línea» con el propio renderizado de la escena Qt Quick. Véase «Qt Quick Scene Graph» para un análisis más detallado de los tres enfoques.
Véase también Gráfico de escena - QSGRenderNode personalizado.
Documentación sobre tipos de miembros
enum QSGRenderNode::RenderingFlag
flags QSGRenderNode::RenderingFlags
Valores posibles para la máscara de bits devuelta por la función ` flags()`.
| Constante | Valor | Descripción |
|---|---|---|
QSGRenderNode::BoundedRectRendering | 0x01 | Indica que la implementación de ` render()` no realiza el renderizado fuera del área indicada por ` rect()` en coordenadas del elemento. Estas implementaciones de nodos pueden dar lugar a un renderizado más eficiente, dependiendo del backend del grafo de escena. Por ejemplo, el backend ` software ` puede seguir utilizando la ruta de actualización parcial, más óptima, cuando todos los nodos de renderizado de la escena tienen este indicador activado. |
QSGRenderNode::DepthAwareRendering | 0x02 | Indica que las implementaciones de render() se ajustan a las expectativas del grafo de escena, ya que solo generan un valor Z igual a 0 en coordenadas de escena, que posteriormente se transforma mediante las matrices obtenidas de RenderState::projectionMatrix() y matrix(), tal y como se describe en las notas de render(). Dichas implementaciones de nodos pueden dar lugar a un renderizado más eficiente, dependiendo del backend del grafo de escena. Por ejemplo, el renderizador OpenGL por lotes puede seguir utilizando una ruta más óptima cuando todos los nodos de renderizado de la escena tienen este indicador activado. |
QSGRenderNode::OpaqueRendering | 0x04 | Indica que la implementación de render() escribe píxeles opacos para toda el área indicada por rect(). Por defecto, los renderizadores deben asumir que render() también puede generar píxeles semitransparentes o totalmente transparentes. Establecer este indicador puede mejorar el rendimiento en algunos casos. |
QSGRenderNode::NoExternalRendering | 0x08 | Indica que las implementaciones de prepare() y render() utilizan exclusivamente la familia de API QRhi, en lugar de llamar directamente a una API 3D como OpenGL, Vulkan o Metal. |
El tipo `RenderingFlags` es un `typedef` para ` QFlags<RenderingFlag>`. Almacena una combinación OR de valores de `RenderingFlag`.
Véase también render(), prepare(), rect() y QRhi.
enum QSGRenderNode::StateFlag
flags QSGRenderNode::StateFlags
Esta enumeración contiene los valores posibles que se pueden utilizar en la máscara de bits devuelta por la función ` changedStates()`.
| Constante | Valor | Descripción |
|---|---|---|
QSGRenderNode::ViewportState | 0x40 | Ventana de visualización |
QSGRenderNode::ScissorState | 0x04 | Estado de prueba de tijera activado, rectángulo de tijera |
QSGRenderNode::DepthState | 0x01 | Este valor no tiene ningún efecto en Qt 6. |
QSGRenderNode::StencilState | 0x02 | Este valor no tiene ningún efecto en Qt 6. |
QSGRenderNode::ColorState | 0x08 | Este valor no tiene ningún efecto en Qt 6. |
QSGRenderNode::BlendState | 0x10 | Este valor no tiene ningún efecto en Qt 6. |
QSGRenderNode::CullState | 0x20 | Este valor no tiene ningún efecto en Qt 6. |
QSGRenderNode::RenderTargetState | 0x80 | Este valor no tiene ningún efecto en Qt 6. |
El tipo StateFlags es un typedef para QFlags<StateFlag>. Almacena una combinación OR de valores de StateFlag.
Documentación de las funciones miembro
[override virtual noexcept] QSGRenderNode::~QSGRenderNode()
Elimina el nodo de renderizado. Se espera que las clases derivadas realicen aquí una limpieza similar a la de releaseResources() .
Con QRhi y recursos como QRhiBuffer, QRhiTexture, QRhiGraphicsPipeline, etc., suele ser una buena práctica utilizar punteros inteligentes, como std::unique_ptr, lo que a menudo permite evitar la necesidad de implementar un destructor y da lugar a un código fuente más compacto. Sin embargo, hay que tener en cuenta que sigue siendo importante implementar releaseResources(), que probablemente contenga varias llamadas a reset() sobre los unique_ptrs.
Véase también releaseResources().
[virtual] QSGRenderNode::StateFlags QSGRenderNode::changedStates() const
Esta función debe devolver una máscara en la que cada bit represente los estados gráficos modificados por la función render().
Nota: Con Qt 6 y el renderizado basado en ` QRhi`, los únicos valores relevantes son ` ViewportState ` y ` ScissorState`. Se pueden devolver otros valores, pero en la práctica se ignoran.
| Constante | Descripción |
|---|---|
ViewportState | Ventana de visualización |
ScissorState | Estado de la prueba de tijera activada, rectángulo de tijera |
DepthState | Este valor no tiene ningún efecto en Qt 6. |
StencilState | Este valor no tiene ningún efecto en Qt 6. |
ColorState | Este valor no tiene ningún efecto en Qt 6. |
BlendState | Este valor no tiene ningún efecto en Qt 6. |
CullState | Este valor no tiene ningún efecto en Qt 6. |
RenderTargetState | Este valor no tiene ningún efecto en Qt 6. |
La implementación por defecto devuelve 0, lo que significa que no se ha modificado ningún estado relevante en render().
Nota: Esta función puede llamarse antes de render().
const QSGClipNode *QSGRenderNode::clipList() const
Devuelve la lista de clips actual.
[since 6.6] QRhiCommandBuffer *QSGRenderNode::commandBuffer() const
Devuelve el búfer de comandos actual.
Esta función se introdujo en Qt 6.6.
Véase también renderTarget().
[virtual] QSGRenderNode::RenderingFlags QSGRenderNode::flags() const
Devuelve indicadores que describen el comportamiento de este nodo de renderizado.
La implementación por defecto devuelve 0.
Véase también RenderingFlag y rect().
qreal QSGRenderNode::inheritedOpacity() const
Devuelve la opacidad efectiva actual.
const QMatrix4x4 *QSGRenderNode::matrix() const
Devuelve un puntero a la matriz modelo-vista actual.
[virtual, since 6.0] void QSGRenderNode::prepare()
Se invoca desde la fase de preparación del fotograma. Se realiza una llamada a esta función antes de cada invocación de ` render()`.
A diferencia de render(), esta función se invoca antes de que el grafo de escena comience a registrar la pasada de renderizado del fotograma actual en el búfer de comandos subyacente. Esto resulta útil al realizar el renderizado con API gráficas, como Vulkan, en las que es necesario registrar operaciones de tipo «copia» antes de la pasada de renderizado.
La implementación por defecto está vacía.
Al implementar un ` QSGRenderNode ` que utilice ` QRhi ` para el renderizado, consulta el objeto ` QRhi ` del ` QQuickWindow ` mediante ` QQuickWindow::rhi()`. Para obtener un ` QRhiCommandBuffer ` al que enviar el trabajo, llama a ` commandBuffer()`. Para consultar información sobre el destino de renderizado activo, llama a ` renderTarget()`. Consulta el ejemplo {Scene Graph - Custom QSGRenderNode} para obtener más detalles.
Esta función se introdujo en Qt 6.0.
[since 6.5] const QMatrix4x4 *QSGRenderNode::projectionMatrix() const
Devuelve un puntero a la matriz de proyección actual.
En ` render()` se trata de la misma matriz que devuelve ` RenderState::projectionMatrix()`. Este getter existe para que ` prepare()` también tenga una forma de consultar la matriz de proyección.
Al trabajar con una API gráfica moderna, o con la propia capa de abstracción gráfica de Qt, es muy probable que se quiera cargar *projectionMatrix() * *matrix() en un búfer uniforme. Sin embargo, eso es algo que debe hacerse en prepare(), es decir, fuera de la grabación de una pasada de renderizado. Por eso ambas matrices se pueden consultar directamente desde ` QSGRenderNode`, tanto en ` prepare()` como en ` render()`.
Esta función se introdujo en Qt 6.5.
[virtual] QRectF QSGRenderNode::rect() const
Devuelve el rectángulo delimitador, en coordenadas del elemento, del área que toca render(). El valor solo se utiliza cuando flags() incluye BoundedRectRendering; en caso contrario, se ignora.
Indicar el rectángulo junto con BoundedRectRendering es especialmente importante con el backend software, ya que, de lo contrario, la presencia de un nodo de renderizado en la escena activaría actualizaciones a pantalla completa, omitiendo todas las optimizaciones de actualizaciones parciales.
Para los nodos de renderizado que cubren toda el área de un « QQuickItem » correspondiente, el valor devuelto será (0, 0, item->width(), item->height()).
Nota: Los nodos también pueden renderizarse fuera de los límites especificados por el ancho y la altura del elemento, ya que los nodos del grafo de escena no están limitados por la geometría del QQuickItem, siempre y cuando esto se informe correctamente desde esta función.
Véase también flags().
[virtual] void QSGRenderNode::releaseResources()
Esta función se invoca cuando es necesario liberar inmediatamente todos los recursos gráficos personalizados asignados por este nodo. En caso de que el nodo no asigne directamente recursos gráficos (búferes, texturas, destinos de renderizado, vallas, etc.) a través de la API gráfica que se esté utilizando, no hay nada que hacer aquí.
Si no se liberan todos los recursos personalizados, puede producirse un comportamiento incorrecto en situaciones de pérdida del dispositivo gráfico en algunos sistemas, ya que la reinicialización posterior del sistema gráfico podría fallar.
Nota: Algunos backends de grafos de escena pueden optar por no llamar a esta función. Por lo tanto, se espera que las implementaciones de ` QSGRenderNode ` realicen la limpieza tanto en su destructor como en `releaseResources()`.
A diferencia de lo que ocurre con el destructor, se espera que ` render()` pueda reiniciar todos los recursos que necesite cuando se llame a ella tras una llamada a `releaseResources()`.
Con OpenGL, el contexto OpenGL del grafo de escena estará activo tanto al llamar al destructor como a esta función.
[pure virtual] void QSGRenderNode::render(const QSGRenderNode::RenderState *state)
El renderizador invoca esta función, que debe dibujar este nodo ejecutando comandos directamente mediante ` QRhi ` o a través de la API gráfica subyacente (OpenGL, Direct3D, etc.).
La opacidad efectiva se puede obtener con ` inheritedOpacity()`.
La matriz de proyección está disponible a través de ` state`, mientras que la matriz modelo-vista se puede obtener con ` matrix()`. La matriz combinada es, por tanto, el producto de la matriz de proyección por la matriz modelo-vista. La matriz de proyección garantiza la superposición correcta de los elementos de la escena.
Al utilizar las matrices proporcionadas, el sistema de coordenadas para los datos de los vértices sigue las convenciones habituales de QQuickItem: la esquina superior izquierda es (0, 0), y la esquina inferior derecha es el valor correspondiente de width() y height() de QQuickItem menos uno. Por ejemplo, suponiendo una disposición de coordenadas de dos valores flotantes (x-y) por vértice, un triángulo que cubra la mitad del elemento puede especificarse como (anchura - 1, altura - 1), (0, 0), (0, altura - 1) utilizando el sentido antihorario.
Nota: QSGRenderNode se proporciona como un medio para implementar elementos personalizados de Qt Quick en 2D o 2,5D. No está pensado para integrar contenido 3D real en la escena de Qt Quick. Ese caso de uso se gestiona mejor mediante otros métodos para integrar renderizado personalizado.
Nota: QSGRenderNode puede ofrecer un rendimiento significativamente mejor que los enfoques basados en texturas (como, por ejemplo, QQuickRhiItem), especialmente en sistemas donde la potencia de procesamiento de fragmentos es limitada. Esto se debe a que evita renderizar en una textura y, a continuación, dibujar un cuadrilátero texturizado. En su lugar, QSGRenderNode permite registrar llamadas de dibujo en línea con los demás comandos del grafo de escena, evitando así un destino de renderizado adicional y las operaciones de texturizado y mezcla, que pueden resultar costosas.
La información de recorte se calcula antes de que se llame a la función. Las implementaciones que deseen tener en cuenta el recorte pueden configurar el recorte por tijera o el stencil basándose en la información de state. El búfer de stencil se rellena con las formas de recorte necesarias, pero depende de la implementación habilitar la comprobación de stencil.
Algunos backends del grafo de escena, en particular los de software, no utilizan ni «scissoring» ni estarcido. En esos casos, la región de recorte se proporciona como un « QRegion » ordinario.
Al implementar un ` QSGRenderNode ` que utilice un ` QRhi ` para renderizar, consulta el objeto ` QRhi ` desde el ` QQuickWindow ` mediante ` QQuickWindow::rhi()`. Para obtener un ` QRhiCommandBuffer ` al que enviar el trabajo, llama a ` commandBuffer()`. Para consultar información sobre el destino de renderizado activo, llama a ` renderTarget()`. Consulta el ejemplo {Scene Graph - Custom QSGRenderNode} para obtener más detalles.
Con Qt 6 y su renderizador de grafo de escena basado en « QRhi », no se deben hacer suposiciones sobre el estado activo (OpenGL) cuando se llama a esta función, incluso cuando se está utilizando OpenGL. No se debe dar nada por sentado respecto a los pipelines y los estados dinámicos vinculados a la lista de comandos o al búfer cuando se llama a esta función.
Nota: Se espera que las escriturasde profundidad estén desactivadas. Activarlas puede dar lugar a resultados inesperados, dependiendo del backend del grafo de escena utilizado y del contenido de la escena, por lo que se recomienda actuar con precaución al respecto.
Nota: En Qt 6, ` changedStates()` tiene un uso limitado. Consulte la documentación de ` changedStates()` para obtener más información.
Con algunas API gráficas, incluso al utilizar QRhi directamente, puede ser necesario reimplementar además prepare() o, como alternativa, conectarse a la señal QQuickWindow::beforeRendering(). Estas se invocan o emiten antes de registrar el inicio de un renderpass en el búfer de comandos (vkCmdBeginRenderPass con Vulkan, o al comenzar a codificar mediante MTLRenderCommandEncoder en el caso de Metal). Las operaciones de copia de grabación no se pueden realizar dentro de `render()` con dichas API. En su lugar, realiza dichas operaciones en ` prepare()` o en la ranura conectada a `beforeRendering` (con `DirectConnection`).
Véase también QSGRendererInterface y QQuickWindow::rendererInterface().
[since 6.6] QRhiRenderTarget *QSGRenderNode::renderTarget() const
Devuelve el destino de renderizado actual.
Esto se proporciona principalmente para permitir que las implementaciones de ` prepare()` y ` render()` que utilizan ` QRhi ` accedan a ` renderPassDescriptor ` o ` pixel size` del ` QRhiRenderTarget`.
Para crear un QRhiGraphicsPipeline, lo que implica tener que proporcionar un QRhiRenderPassDescriptor, consulta el renderPassDescriptor del render target. Sin embargo, hay que tener en cuenta que el destino de renderizado puede cambiar a lo largo del ciclo de vida del QQuickItem personalizado y del QSGRenderNode. Por ejemplo, piensa en lo que ocurre al establecer dinámicamente layer.enabled: true en el elemento o en uno de sus antecesores: esto provoca que el renderizado se realice en una textura, no directamente en la ventana, lo que significa que el QSGRenderNode va a trabajar con un destino de renderizado diferente a partir de ese momento. El nuevo destino de renderizado puede tener entonces un formato de píxeles diferente, lo que puede hacer que las tuberías gráficas ya creadas resulten incompatibles. Esto se puede gestionar con una lógica como la siguiente:
if (m_pipeline && renderTarget()->renderPassDescriptor()->serializedFormat() != m_renderPassFormat) {
delete m_pipeline;
m_pipeline = nullptr;
}
if (!m_pipeline) {
// Build a new QRhiGraphicsPipeline.
// ...
// Store the serialized format for fast and simple comparisons later on.
m_renderPassFormat = renderTarget()->renderPassDescriptor()->serializedFormat();
}Esta función se introdujo en Qt 6.6.
Véase también commandBuffer().
© 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.