QQuickRhiItemRenderer Class

Documentación de Funciones Miembro

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

Construye un nuevo renderizador.

Esta función es llamada en el hilo de renderizado durante la fase de sincronización del gráfico de escena cuando el hilo GUI está bloqueado.

Véase también QQuickRhiItem::createRenderer().

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

El Renderizador se elimina automáticamente cuando se limpian los recursos del gráfico de escena para el elemento QQuickRhiItem.

Esta función es llamada en el hilo de renderizado.

Bajo ciertas condiciones es normal y esperado que el objeto renderizador sea destruido y luego recreado. Esto se debe a que el tiempo de vida del renderizador sigue al nodo del grafo de escena subyacente. Por ejemplo, cuando se cambia el padre de un objeto QQuickRhiItem para que pertenezca 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á la eliminación y creación de 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 a través de QRhi. Es suficiente con liberar todo en el destructor, o confiar en punteros inteligentes.

[protected] QRhiTexture *QQuickRhiItemRenderer::colorTexture() const

Devuelve la textura que sirve como buffer de color para el ítem.

Sólo debe llamarse desde initialize() y render().

A diferencia del búfer de profundidad y de QRhiRenderTarget, esta textura está siempre disponible y es gestionada por QQuickRhiItem, independientemente del valor de isAutoRenderTargetEnabled.

Véase también msaaColorBuffer(), depthStencilBuffer(), renderTarget() y resolveTexture().

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::depthStencilBuffer() const

Devuelve el búfer de profundidad-esténcil utilizado por el renderizado del elemento.

Sólo debe invocarse desde initialize() y render().

Disponible sólo cuando isAutoRenderTargetEnabled es true. En caso contrario, el valor devuelto es nullptr y corresponde a la reimplementación de initialize() crear y gestionar un búfer de profundidad y un QRhiTextureRenderTarget.

Véase también colorTexture() y renderTarget().

[pure virtual protected] void QQuickRhiItemRenderer::initialize(QRhiCommandBuffer *cb)

Llamada cuando el elemento es inicializado por primera vez, cuando el tamaño, formato o conteo de muestras de la textura asociada cambia, o cuando el QRhi o la textura cambian por cualquier razón. 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 los objetos QRhi, QRhiTexture, y otros objetos relacionados, llame a rhi(), colorTexture(), depthStencilBuffer(), y renderTarget().

Cuando el tamaño del elemento cambia, el objeto QRhi, la textura del búfer de color y los objetos del búfer de la plantilla de profundidad son todos las mismas instancias (por lo que los getters devuelven los mismos punteros) que antes, pero los búferes de color y profundidad/esténcil probablemente se habrán reconstruido, lo que significa que size y el recurso de textura nativa subyacente pueden ser diferentes que en 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 invocaciones de esta función. Por ejemplo, cuando el elemento se reparente para que pertenezca a un nuevo QQuickWindow, el QRhi y todos los recursos relacionados gestionados por el QQuickRhiItem serán instancias diferentes que antes en la siguiente llamada a esta función. Es importante entonces que todos los recursos QRhi previamente creados por la subclase sean destruidos porque pertenecen al QRhi anterior que ya no debe ser utilizado.

Cuando isAutoRenderTargetEnabled es true, que es el valor por defecto, se crean y gestionan automáticamente un depth-stencil QRhiRenderBuffer y un QRhiTextureRenderTarget asociados al colorTexture() (o msaaColorBuffer()) y al buffer depth-stencil. Las reimplementaciones de initialize() y render() pueden consultar estos objetos a través de depthStencilBuffer() y renderTarget(). Cuando isAutoRenderTargetEnabled se establece en false, estos objetos ya no se crean y gestionan automáticamente. En su lugar, será la implementación de initialize() la que cree los buffers y configure el objetivo de renderizado como considere oportuno. Cuando se gestionen manualmente adjuntos adicionales de color o profundidad para el objetivo de renderizado, su tamaño y número de muestras deben seguir siempre el tamaño y número de muestras de colorTexture() (o msaaColorBuffer()), de lo contrario pueden producirse errores de validación de la API 3D o de renderizado.

Se espera que los recursos gráficos creados por la subclase se liberen en la implementación del destructor de la subclase.

cb es QRhiCommandBuffer para el fotograma actual. La función es llamada con un fotograma siendo grabado, pero sin un pase de render activo. El buffer de comandos se proporciona principalmente para permitir la puesta en cola de resource updates sin diferir a render().

Esta función se ejecuta en el hilo de renderizado, si existe.

Véase también render().

[protected] QRhiRenderBuffer *QQuickRhiItemRenderer::msaaColorBuffer() const

Devuelve el búfer de renderizado que sirve como búfer de color multimuestra para el elemento.

Sólo debe invocarse desde initialize() y render().

Cuando sampleCount es mayor que 1, y por lo tanto el antialising multimuestra está activado, el QRhiRenderBuffer devuelto tiene un recuento de muestras coincidente y sirve como búfer de color. Los conductos 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 también debe coincidir. Se espera que el contenido multimuestra se resuelva en la textura devuelta por resolveTexture(). Cuando isAutoRenderTargetEnabled es true, renderTarget() se configura automáticamente para hacer esto, estableciendo msaaColorBuffer() como el renderbuffer del adjunto de color 0 y resolveTexture() como su resolveTexture.

Cuando MSAA no está en uso, el valor de retorno es nullptr. Utilice entonces colorTexture() en su lugar.

Dependiendo de la API de gráficos 3D subyacente, puede que no haya diferencia práctica entre las texturas multimuestra y los renderbuffers de color con un recuento de muestras superior a 1 (QRhi puede simplemente asignar ambos al mismo tipo de recurso nativo). Sin embargo, algunas API más antiguas pueden diferenciar entre texturas y renderbuffers. Con el fin de soportar OpenGL ES 3.0, donde los renderbuffers multimuestra están disponibles, pero las texturas multimuestra no, QQuickRhiItem siempre realiza MSAA utilizando un QRhiRenderBuffer multimuestra como adjunto de color (y nunca un QRhiTexture multimuestra).

Véase también colorTexture(), depthStencilBuffer(), renderTarget() y resolveTexture().

[pure virtual protected] void QQuickRhiItemRenderer::render(QRhiCommandBuffer *cb)

Llamada cuando es necesario actualizar el contenido del búfer de color de fondo.

Siempre hay al menos una llamada a initialize() antes de llamar a esta función.

Para solicitar actualizaciones, llame a QQuickItem::update() cuando llame desde QML o desde código C++ en el hilo principal/GUI (por ejemplo, cuando esté en un definidor de propiedades), o update() cuando llame desde dentro de una llamada de retorno QQuickRhiItemRenderer. Llamar a QQuickRhiItemRenderer's update() desde dentro de render() provocará que se disparen actualizaciones continuamente.

cb es el QRhiCommandBuffer para el fotograma actual. La función es llamada con un frame siendo grabado, pero sin un pase de render activo.

Esta función es llamada en el hilo de renderizado, si hay uno.

Ver también initialize() y synchronize().

[protected] QRhiRenderTarget *QQuickRhiItemRenderer::renderTarget() const

Devuelve el objeto de destino de renderizado que debe utilizarse con QRhiCommandBuffer::beginPass() en reimplementaciones de render().

Sólo debe llamarse desde initialize() y render().

Disponible sólo cuando isAutoRenderTargetEnabled es true. En caso contrario, el valor devuelto es nullptr y corresponde a la reimplementación de initialize() crear y gestionar un búfer de profundidad y un QRhiTextureRenderTarget.

Al crear graphics pipelines, se necesita un QRhiRenderPassDescriptor. Este puede ser consultado desde el QRhiTextureRenderTarget devuelto llamando a renderPassDescriptor().

Véase 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á activado.

Sólo debe invocarse desde initialize() y render().

Con MSAA activado, esta es la textura que utiliza el nodo del gráfico de escena subyacente al texturizar un quad en el pase de renderizado principal de Qt Quick. Sin embargo, el renderizado de QQuickRhiItemRenderer debe tener como objetivo la (multimuestra) QRhiRenderBuffer devuelta desde msaaColorBuffer(). Cuando isAutoRenderTargetEnabled es true, de esto se encarga el QRhiRenderTarget devuelto por renderTarget(). De lo contrario, depende del código de la subclase configurar correctamente un objeto de destino de renderizado tanto con el búfer de color como con las texturas de resolución.

Véase también colorTexture().

[protected] QRhi *QQuickRhiItemRenderer::rhi() const

Devuelve el objeto QRhi actual.

Sólo debe invocarse desde initialize() y render().

[pure virtual protected] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)

Esta función es llamada en el hilo de renderizado, si existe, mientras el hilo principal/GUI está bloqueado. Se llama desde the item's synchronize stepy permite leer y escribir datos pertenecientes a los subprocesos principal y de renderizado. Típicamente los valores de las propiedades almacenados en QQuickRhiItem son copiados en QQuickRhiItemRenderer, para que puedan ser leídos con seguridad después en render() cuando los hilos de render y principal continúan trabajando en paralelo.

Ver también initialize() y render().

[protected] void QQuickRhiItemRenderer::update()

Llama a esta función cuando el contenido del buffer de color fuera de pantalla debe ser actualizado. (es decir, para solicitar que se vuelva a llamar a render(); la llamada se producirá en un momento posterior, y tenga en cuenta que las actualizaciones se limitan normalmente a la velocidad de presentación).

Esta función puede llamarse desde render() para programar una actualización.