QQuickRhiItemRenderer Class
Un `QQuickRhiItemRenderer` implementa la lógica de representación de un ` QQuickRhiItem`. Más información...
| Encabezado: | #include <QQuickRhiItemRenderer> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Desde: | Qt 6.7 |
| Estado: | Versión preliminar |
Esta clase se encuentra en fase de vista previa tecnológica y está sujeta a cambios.
Funciones públicas
| QQuickRhiItemRenderer() | |
| virtual | ~QQuickRhiItemRenderer() |
Funciones protegidas
| QRhiTexture * | colorTexture() const |
| QRhiRenderBuffer * | depthStencilBuffer() const |
| virtual void | initialize(QRhiCommandBuffer *cb) = 0 |
| QRhiRenderBuffer * | msaaColorBuffer() const |
| virtual void | render(QRhiCommandBuffer *cb) = 0 |
| QRhiRenderTarget * | renderTarget() const |
| QRhiTexture * | resolveTexture() const |
| QRhi * | rhi() const |
| virtual void | synchronize(QQuickRhiItem *item) = 0 |
| void | update() |
Descripción detallada
Nota: QQuickRhiItem y QQuickRhiItemRenderer se encuentran en fase de vista previa tecnológica en Qt 6.7. La API está en desarrollo y sujeta a cambios.
Véase también QQuickRhiItem y QRhi.
Documentación de las funciones miembro
QQuickRhiItemRenderer::QQuickRhiItemRenderer()
Crea un nuevo renderizador.
Esta función se invoca en el hilo de renderizado durante la fase de sincronización del grafo de escena, cuando el hilo de la interfaz gráfica de usuario está bloqueado.
Véase también ` QQuickRhiItem::createRenderer()`.
[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()
El renderizador se elimina automáticamente cuando se liberan los recursos del grafo de escena correspondientes al elemento « QQuickRhiItem ».
Esta función se invoca en el hilo de renderizado.
En determinadas condiciones, es normal y previsible que el objeto renderizador se destruya y, a continuación, se vuelva a crear. Esto se debe a que la vida útil del renderizador sigue, en la práctica, la del nodo del gráfico de escena subyacente. Por ejemplo, al cambiar el padre de un objeto « QQuickRhiItem » para que pase a pertenecer a un « QQuickWindow » diferente, todos los nodos del gráfico de escena se eliminan y se vuelven a crear debido al cambio de ventana. Esto también implicará eliminar y crear un nuevo ` QQuickRhiItemRenderer`.
A diferencia de QRhiWidget, QQuickRhiItemRenderer no necesita implementar rutas de código adicionales para liberar (o liberar anticipadamente) los recursos gráficos creados mediante QRhi. Basta con liberarlo todo en el destructor o recurrir a punteros inteligentes.
[protected] QRhiTexture *QQuickRhiItemRenderer::colorTexture() const
Devuelve la textura que hace las veces de búfer de color para el elemento.
Solo debe llamarse desde ` initialize()` y ` render()`.
A diferencia del búfer de profundidad-estencil y de ` QRhiRenderTarget`, esta textura está siempre disponible y la gestiona ` QQuickRhiItem`, independientemente del valor de ` isAutoRenderTargetEnabled`.
Nota: Cuando sampleCount es mayor que 1, y por lo tanto está habilitado el antialiasing multimuestra, el valor devuelto es nullptr. En su lugar, consulta el QRhiRenderBuffer llamando a msaaColorBuffer().
Nota: El tamañode la textura de fondo y el número de muestras también se pueden consultar a través del valor QRhiRenderTarget devuelto por renderTarget(). Esto puede resultar más cómodo y compacto que consultarlo a través de QRhiTexture o QRhiRenderBuffer, ya que funciona independientemente de si se utiliza el multimuestreo o no.
Véase también msaaColorBuffer(), depthStencilBuffer(), renderTarget() y resolveTexture().
[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::depthStencilBuffer() const
Devuelve el búfer de profundidad-estencil utilizado en el renderizado del elemento.
Solo debe llamarse desde ` initialize()` y ` render()`.
Solo está disponible cuando isAutoRenderTargetEnabled es true. De lo contrario, el valor devuelto es nullptr y corresponde a la reimplementación de initialize() crear y gestionar un búfer de profundidad-estencil y un QRhiTextureRenderTarget.
Véanse también colorTexture() y renderTarget().
[pure virtual protected] void QQuickRhiItemRenderer::initialize(QRhiCommandBuffer *cb)
Se invoca cuando el elemento se inicializa por primera vez, cuando cambia el tamaño, el formato o el número de muestras de la textura asociada, o cuando el ` QRhi ` o la textura cambian por cualquier motivo. Se espera que la función mantenga (cree si aún no se ha creado, ajuste y reconstruya si el tamaño ha cambiado) los recursos gráficos utilizados por el código de renderizado en ` render()`.
Para consultar el objeto ` QRhi`, ` QRhiTexture` y otros objetos relacionados, llame a ` rhi()`, ` colorTexture()`, ` depthStencilBuffer()` y ` renderTarget()`.
Cuando cambia el tamaño del elemento, el objeto ` QRhi `, la textura del búfer de color y los objetos del búfer de profundidad y del búfer de plantilla son todas las mismas instancias (por lo que los métodos de lectura devuelven los mismos punteros) que antes, pero es probable que los búferes de color y de profundidad/plantilla se hayan reconstruido, lo que significa que ` size ` y el recurso de textura nativo subyacente pueden ser diferentes a los de la última invocación.
Las reimplementaciones también deben estar preparadas para que el objeto ` QRhi ` y la textura del búfer de color puedan cambiar entre las invocaciones de esta función. Por ejemplo, cuando se cambia la relación de parentesco del elemento para que pertenezca a un nuevo ` QQuickWindow`, el ` QRhi ` y todos los recursos relacionados gestionados por el ` QQuickRhiItem ` serán instancias diferentes a las anteriores en la siguiente llamada a esta función. Por lo tanto, es importante que se destruyan todos los recursos ` QRhi ` existentes creados previamente por la subclase, ya que pertenecen al anterior ` QRhi `, que ya no debería utilizarse.
Cuando isAutoRenderTargetEnabled es true —que es el valor por defecto—, se crean y gestionan automáticamente un «depth-stencil» QRhiRenderBuffer y un QRhiTextureRenderTarget asociados a colorTexture() (o msaaColorBuffer()) y al búfer de profundidad-estencil. Las reimplementaciones de initialize() y render() pueden consultar dichos objetos mediante depthStencilBuffer() y renderTarget(). Cuando isAutoRenderTargetEnabled se establece en false, estos objetos ya no se crean ni se gestionan automáticamente. En su lugar, corresponderá a la implementación de initialize() crear los búferes y configurar el destino de renderizado como considere oportuno. Al gestionar manualmente adjuntos adicionales de color o profundidad-plantilla para el destino de renderizado, su tamaño y número de muestras deben coincidir siempre con el tamaño y el número de muestras de colorTexture() (o msaaColorBuffer()); de lo contrario, pueden producirse errores de renderizado o de validación de la API 3D.
Se espera que los recursos gráficos creados por la subclase se liberen en la implementación del destructor de la subclase.
cb es el búfer de comando ( QRhiCommandBuffer ) del fotograma actual. La función se invoca mientras se graba un fotograma, pero sin un paso de renderizado activo. El búfer de comando se proporciona principalmente para permitir la puesta en cola de resource updates sin tener que recurrir a render().
Esta función se invoca en el hilo de renderizado, si existe.
Véase también render().
[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::msaaColorBuffer() const
Devuelve el búfer de renderizado que actúa como búfer de color multimuestra para el elemento.
Solo debe llamarse desde ` initialize()` y ` render()`.
Cuando sampleCount es mayor que 1, y por lo tanto el antialiasing multimuestra está habilitado, el QRhiRenderBuffer devuelto tiene un recuento de muestras coincidente y actúa como búfer de color. Los flujos de trabajo gráficos utilizados para renderizar en este búfer deben crearse con el mismo recuento de muestras, y el recuento de muestras del búfer de profundidad-plantilla también debe coincidir. Se espera que el contenido de multimuestra se resuelva en la textura devuelta por ` resolveTexture()` (). Cuando ` isAutoRenderTargetEnabled ` es ` true`, ` renderTarget()` se configura automáticamente para ello, estableciendo `msaaColorBuffer()` como ` renderbuffer ` del accesorio de color 0 y ` resolveTexture()` como su ` resolveTexture`.
Cuando no se utiliza MSAA, el valor de retorno es ` nullptr`. En ese caso, utilice ` colorTexture()` en su lugar.
Dependiendo de la API de gráficos 3D subyacente, puede que no haya ninguna diferencia práctica entre las texturas multimuestra y los búferes de renderizado de color con un número de muestras superior a 1 (QRhi puede que simplemente asigne ambos al mismo tipo de recurso nativo). Sin embargo, algunas API más antiguas pueden diferenciar entre texturas y búferes de renderizado. Para ser compatible con OpenGL ES 3.0, donde hay disponibles búferes de renderizado multimuestra, pero no texturas multimuestra, QQuickRhiItem siempre realiza MSAA utilizando un QRhiRenderBuffer multimuestra como adjunto de color (y nunca un QRhiTexture multimuestra).
Nota: El tamañode la textura de fondo y el número de muestras también pueden consultarse a través de la QRhiRenderTarget devuelta por renderTarget(). Esto puede resultar más cómodo y compacto que consultarlo a partir de la QRhiTexture o la QRhiRenderBuffer, ya que funciona independientemente de si se utiliza el multimuestreo o no.
Véanse también colorTexture(), depthStencilBuffer(), renderTarget() y resolveTexture().
[pure virtual protected] void QQuickRhiItemRenderer::render(QRhiCommandBuffer *cb)
Se invoca cuando es necesario actualizar el contenido del búfer de color de fondo.
Siempre se realiza al menos una llamada a ` initialize()` antes de que se llame a esta función.
Para solicitar actualizaciones, llama a ` QQuickItem::update()` cuando realices la llamada desde QML o desde código C++ en el hilo principal/GUI (por ejemplo, en un setter de propiedad), o a ` update()` cuando realices la llamada desde una llamada de retorno de ` QQuickRhiItemRenderer `. Llamar a ` update()` de ` QQuickRhiItemRenderer` desde dentro de `render()` provocará que se activen actualizaciones de forma continua.
cb es el « QRhiCommandBuffer » del fotograma actual. La función se invoca mientras se graba un fotograma, pero sin una pasada de renderizado activa.
Esta función se invoca en el hilo de renderizado, si existe.
Véase también initialize() y synchronize().
[protected] QRhiRenderTarget *QQuickRhiItemRenderer::renderTarget() const
Devuelve el objeto de destino de renderizado que debe utilizarse con ` QRhiCommandBuffer::beginPass()` en las reimplementaciones de ` render()`.
Solo debe llamarse desde ` initialize()` y ` render()`.
Solo está disponible cuando isAutoRenderTargetEnabled es true. De lo contrario, el valor devuelto es nullptr y corresponde a la reimplementación de initialize() crear y gestionar un búfer de profundidad-estencil y un QRhiTextureRenderTarget.
Al crear graphics pipelines, se necesita un QRhiRenderPassDescriptor. Este se puede consultar a partir del QRhiTextureRenderTarget devuelto llamando a renderPassDescriptor().
Nota: El objeto QRhiTextureRenderTarget devuelto siempre indica un devicePixelRatio() de 1. Esto se debe a que solo las cadenas de intercambio (swapchains) y la ventana asociada tienen un concepto de relación de píxeles del dispositivo, no las texturas, y el objetivo de renderizado aquí siempre hace referencia a una textura. Si el factor de escala en pantalla es relevante para el renderizado, consúltalo y guárdalo a través del window()->effectiveDevicePixelRatio() del elemento en synchronize(). Al hacerlo, es preferible utilizar siempre ` effectiveDevicePixelRatio()` en lugar de ` devicePixelRatio()` de la clase base.
Véanse también colorTexture(), depthStencilBuffer() y QQuickWindow::effectiveDevicePixelRatio().
[protected] QRhiTexture *QQuickRhiItemRenderer::resolveTexture() const
Devuelve la textura no multimuestra a la que se resuelve el contenido multimuestra.
El resultado es ` nullptr ` cuando el antialiasing multimuestra no está habilitado.
Solo debe llamarse desde initialize() y render().
Con el MSAA activado, esta es la textura que utiliza el nodo del grafo de escena subyacente del elemento al texturizar un cuadrante en la pasada de renderizado principal de Qt Quick. Sin embargo, el renderizado de QQuickRhiItemRenderer debe tener como destino el QRhiRenderBuffer (multimuestra) devuelto por msaaColorBuffer(). Cuando isAutoRenderTargetEnabled es true, de esto se encarga el QRhiRenderTarget devuelto por renderTarget(). De lo contrario, corresponde al código de la subclase configurar correctamente un objeto de destino de renderizado con el búfer de color y las texturas de resolución.
Véase también colorTexture().
[protected] QRhi *QQuickRhiItemRenderer::rhi() const
Devuelve el objeto ` QRhi ` actual.
Solo debe invocarse desde ` initialize()` y ` render()`.
[pure virtual protected] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)
Esta función se invoca en el hilo de renderizado, si existe, mientras el hilo principal o de la interfaz gráfica de usuario está bloqueado. Se invoca desde the item's synchronize step, y permite leer y escribir datos pertenecientes a los hilos principal y de renderizado. Normalmente, los valores de las propiedades almacenados en QQuickRhiItem se copian en QQuickRhiItemRenderer, de modo que puedan leerse posteriormente de forma segura en render() cuando los hilos de renderizado y principal continúen trabajando en paralelo.
Véanse también initialize() y render().
[protected] void QQuickRhiItemRenderer::update()
Llama a esta función cuando sea necesario actualizar el contenido del búfer de color fuera de pantalla. (Es decir, para solicitar que se vuelva a llamar a ` render()`; la llamada se realizará más adelante, y ten en cuenta que las actualizaciones suelen estar limitadas a la frecuencia de presentación).
Esta función se puede llamar desde ` render()` para programar una actualización.
Nota: Esta función debe utilizarse desde dentro del renderizador. Para actualizar el elemento en el hilo de la interfaz gráfica de usuario, utiliza QQuickRhiItem::update().
© 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.