QSGRenderNode Class

Documentación de las funciones miembro

[override virtual noexcept] QSGRenderNode::~QSGRenderNode()

Destruye el nodo de renderizado. Se espera que las clases derivadas realicen aquí una limpieza similar a releaseResources().

Con QRhi y recursos como QRhiBuffer, QRhiTexture, QRhiGraphicsPipeline, etc., a menudo es una buena práctica utilizar punteros inteligentes, como std::unique_ptr, que a menudo pueden evitar la necesidad de implementar un destructor, y conducir a un código fuente más compacto. Tenga en cuenta, sin embargo, que la implementación de releaseResources(), que probablemente contenga un número de llamadas a reset() en los unique_ptrs, sigue siendo importante.

Véase también releaseResources().

[virtual] QSGRenderNode::StateFlags QSGRenderNode::changedStates() const

Esta función debería devolver una máscara donde cada bit representa estados gráficos cambiados por la función render().

La implementación por defecto devuelve 0, lo que significa que no se ha cambiado ningún estado relevante en render().

const QSGClipNode *QSGRenderNode::clipList() const

Devuelve la lista de clips actual.

[since 6.6] QRhiCommandBuffer *QSGRenderNode::commandBuffer() const

Devuelve el buffer de comandos actual.

Esta función se introdujo en Qt 6.6.

Véase también renderTarget().

[virtual] QSGRenderNode::RenderingFlags QSGRenderNode::flags() const

Devuelve banderas 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 el puntero a la matriz modelo-vista actual.

[virtual, since 6.0] void QSGRenderNode::prepare()

Llamada desde la fase de preparación de la trama. Hay una llamada a esta función antes de cada invocación de render().

A diferencia de render(), esta función se llama antes de que el scenegraph comience a grabar el pase de renderizado para el fotograma actual en el buffer de comandos subyacente. Esto es útil cuando se hace renderizado con APIs gráficas, como Vulkan, donde el tipo de operaciones de copia necesitarán ser grabadas antes del pase de renderizado.

La implementación por defecto está vacía.

Cuando se implementa un QSGRenderNode que utiliza QRhi para renderizar, consulta el objeto QRhi desde el QQuickWindow a través de QQuickWindow::rhi(). Para obtener un QRhiCommandBuffer al que enviar el trabajo, llame a commandBuffer(). Para consultar información sobre el objetivo de renderizado activo, llame a renderTarget(). Ver el ejemplo {Scene Graph - Custom QSGRenderNode} para más detalles.

Esta función se introdujo en Qt 6.0.

[since 6.5] const QMatrix4x4 *QSGRenderNode::projectionMatrix() const

Devuelve el puntero a la matriz de proyección actual.

En render() esta es la misma matriz que se devuelve desde RenderState::projectionMatrix(). Este getter existe para que prepare() también tenga una forma de consultar la matriz de proyección.

Cuando se trabaja con una API gráfica moderna, o con la propia capa de abstracción gráfica de Qt, es más que probable que uno quiera cargar *projectionMatrix() * *matrix() en un buffer uniforme. Sin embargo, eso es algo que hay que hacer en prepare(), así que fuera de la grabación de un pase de render. Por eso ambas matrices son consultables 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 de elemento para el área que toca render(). El valor sólo se utiliza cuando flags() incluye BoundedRectRendering, ignorándose en caso contrario.

Informar del rectángulo en combinación con BoundedRectRendering es especialmente importante con el backend software porque, de lo contrario, tener un rendernode en la escena desencadenaría actualizaciones a pantalla completa, saltándose todas las optimizaciones de actualización parcial.

Para los rendernodes que cubran toda el área de un QQuickItem correspondiente, el valor de retorno será (0, 0, item->width(), item->height()).

Véase también flags().

[virtual] void QSGRenderNode::releaseResources()

Esta función es llamada cuando todos los recursos gráficos personalizados asignados por este nodo tienen que ser liberados inmediatamente. En caso de que el nodo no asigne directamente recursos gráficos (buffers, texturas, objetivos de renderizado, vallas, etc.) a través de la API gráfica que esté en uso, no hay nada que hacer aquí.

No liberar todos los recursos personalizados puede conducir a un comportamiento incorrecto en escenarios de pérdida de dispositivos gráficos en algunos sistemas, ya que la reinicialización posterior del sistema gráfico puede fallar.

Al contrario que con el destructor, se espera que render() pueda reinicializar todos los recursos que necesite cuando se llame después de una llamada a releaseResources().

Con OpenGL, el contexto OpenGL del scenegraph será actual tanto cuando se llame al destructor como a esta función.

[pure virtual] void QSGRenderNode::render(const QSGRenderNode::RenderState *state)

Esta función es llamada por el renderizador y debe pintar este nodo invocando directamente comandos a través de QRhi o directamente a través de la API gráfica subyacente (OpenGL, Direct3D, etc.).

La opacidad efectiva puede recuperarse con inheritedOpacity().

La matriz de proyección está disponible a través de state, mientras que la matriz modelo-vista puede obtenerse con matrix(). La matriz combinada es la matriz de proyección multiplicada por la matriz modelo-vista. La matriz de proyección garantiza el apilamiento correcto de los elementos de la escena.

Cuando se utilizan las matrices proporcionadas, el sistema de coordenadas para los datos de vértices sigue las convenciones habituales de QQuickItem: arriba-izquierda es (0, 0), abajo-derecha es la correspondiente anchura() y altura() de QQuickItem menos uno. Por ejemplo, suponiendo una disposición de coordenadas de dos flotadores (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 la dirección contraria a las agujas del reloj.

La información de recorte se calcula antes de llamar a la función. Las implementaciones que deseen tener en cuenta el recorte pueden configurar la tijera o el stencil basándose en la información de state. El búfer del stencil se rellena con las formas de recorte necesarias, pero depende de la implementación habilitar la comprobación del stencil.

Algunos backends de scenegraph, software en particular, no utilizan ni tijera ni stencil. En estos casos, la región de clip se proporciona como un QRegion normal.

Al implementar un QSGRenderNode que utilice QRhi para renderizar, consulte el objeto QRhi desde el QQuickWindow a través de QQuickWindow::rhi(). Para obtener un QRhiCommandBuffer al que enviar el trabajo, llame a commandBuffer(). Para consultar información sobre el objetivo de renderizado activo, llame a renderTarget(). Ver el ejemplo {Scene Graph - Custom QSGRenderNode} para más detalles.

Con Qt 6 y su renderizador de gráficos de escena basado en QRhi, no se deben hacer suposiciones sobre el estado activo (OpenGL) cuando se llama a esta función, incluso cuando OpenGL está en uso. No se debe asumir nada sobre los pipelines y estados dinámicos vinculados en la lista de comandos/buffer cuando se llama a esta función.

Con algunas APIs gráficas, incluyendo cuando se usa QRhi directamente, puede ser necesario reimplementar prepare() además, o alternativamente conectarse a la señal QQuickWindow::beforeRendering(). Estos son llamados/emitidos antes de grabar el comienzo de un renderpass en el buffer de comandos (vkCmdBeginRenderPass con Vulkan, o comenzando a codificar vía MTLRenderCommandEncoder en el caso de Metal. Las operaciones de copia de grabación no se pueden hacer dentro de render() con tales APIs. Más bien, haga tales 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 objetivo de renderizado actual.

Se proporciona principalmente para permitir las implementaciones de prepare() y render() que utilizan QRhi accediendo a QRhiRenderTarget's renderPassDescriptor o pixel size.

Para construir un QRhiGraphicsPipeline, lo que implica tener que proporcionar un QRhiRenderPassDescriptor, consulta el renderPassDescriptor del objetivo de renderizado. Tenga en cuenta, sin embargo, que el objetivo de renderizado puede cambiar a lo largo de la vida del QQuickItem personalizado y del QSGRenderNode. Por ejemplo, considere lo que sucede cuando se establece dinámicamente layer.enabled: true en el elemento o en un ancestro del mismo: esto desencadena el renderizado en una textura, no directamente en la ventana, lo que significa que el QSGRenderNode va a trabajar con un objetivo de renderizado diferente a partir de entonces. El nuevo objetivo de renderizado puede entonces tener un formato de píxel diferente, lo que puede hacer incompatibles los pipelines gráficos ya construidos. Esto puede ser manejado con la 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().