QQuickRenderControl Class
La clase QQuickRenderControl proporciona un mecanismo para renderizar el scenegraph Qt Quick en un objetivo de renderizado fuera de pantalla de una manera totalmente controlada por la aplicación. Más...
| Cabecera: | #include <QQuickRenderControl> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick)target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Hereda: | QObject |
Funciones públicas
| QQuickRenderControl(QObject *parent = nullptr) | |
| virtual | ~QQuickRenderControl() override |
(since 6.0) void | beginFrame() |
(since 6.6) QRhiCommandBuffer * | commandBuffer() const |
(since 6.0) void | endFrame() |
(since 6.0) bool | initialize() |
| void | invalidate() |
| void | polishItems() |
| void | prepareThread(QThread *targetThread) |
| void | render() |
| virtual QWindow * | renderWindow(QPoint *offset) |
(since 6.6) QRhi * | rhi() const |
(since 6.0) int | samples() const |
(since 6.0) void | setSamples(int sampleCount) |
| bool | sync() |
(since 6.0) QQuickWindow * | window() const |
Señales
| void | renderRequested() |
| void | sceneChanged() |
Miembros públicos estáticos
| QWindow * | renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr) |
Descripción detallada
QQuickWindow y QQuickView y sus bucles de render internos asociados renderizan la escena Qt Quick en una ventana nativa. En algunos casos, por ejemplo cuando se integra con renderizadores OpenGL, Vulkan, Metal, o Direct 3D de terceros, puede ser útil obtener la escena en una textura que luego puede ser utilizada de manera arbitraria por el motor de renderizado externo. Tal mecanismo es también esencial cuando se integra con un framework de VR. QQuickRenderControl hace esto posible de una manera acelerada por hardware, a diferencia de la alternativa de rendimiento limitado de usar QQuickWindow::grabWindow()
Cuando se usa un QQuickRenderControl, el QQuickWindow no debe ser shown (no será visible en pantalla) y no habrá una ventana nativa subyacente para él. En su lugar, la instancia QQuickWindow se asocia con el objeto de control de renderizado, utilizando la sobrecarga del constructor QQuickWindow, y un objeto de textura o imagen especificado a través de QQuickWindow::setRenderTarget(). El objeto QQuickWindow sigue siendo esencial, ya que representa la escena Qt Quick y proporciona la mayor parte de los mecanismos de gestión de la escena y de envío de eventos. Sin embargo, no actúa como una ventana real en pantalla desde la perspectiva del sistema de ventanas.
La gestión de los dispositivos gráficos, contextos y objetos de imagen y textura depende de la aplicación. El dispositivo o contexto que será utilizado por Qt Quick debe ser creado antes de llamar a initialize(). La creación del objeto textura puede ser diferida, ver más abajo. Qt 5.4 introduce la posibilidad de que QOpenGLContext adopte contextos nativos existentes. Junto con QQuickRenderControl esto hace posible crear un QOpenGLContext que comparte con un motor de renderizado externo el contexto existente. Este nuevo QOpenGLContext puede entonces ser utilizado para renderizar la escena Qt Quick en una textura que es accesible por el contexto del otro motor también. Para Vulkan, Metal y Direct 3D no hay envoltorios proporcionados por Qt para objetos de dispositivo, por lo que los existentes se pueden pasar tal cual a través de QQuickWindow::setGraphicsDevice().
La carga e instanciación de los componentes QML se realiza a través de QQmlEngine. Una vez creado el objeto raíz, será necesario asignarlo a QQuickWindow's contentItem().
Por lo general, las aplicaciones tendrán que conectarse a 4 señales importantes:
- QQuickWindow::sceneGraphInitialized() Emitida en algún momento después de llamar a QQuickRenderControl::initialize(). Tras esta señal, se espera que la aplicación cree su objeto framebuffer y lo asocie con QQuickWindow.
- QQuickWindow::sceneGraphInvalidated() Cuando los recursos del scenegraph son liberados, el objeto framebuffer puede ser destruido también.
- QQuickRenderControl::renderRequested() Indica que la escena debe ser renderizada llamando a render(). Después de actualizar el contexto, se espera que las aplicaciones llamen a render().
- QQuickRenderControl::sceneChanged() Indica que la escena ha cambiado, lo que significa que, antes de renderizarla, también es necesario pulirla y sincronizarla.
Para enviar eventos, por ejemplo de ratón o teclado, a la escena, se utiliza QCoreApplication::sendEvent() con la instancia QQuickWindow como receptor.
Para los eventos de teclado también puede ser necesario establecer el foco manualmente en el elemento deseado. En la práctica, esto implica llamar a forceActiveFocus() en el elemento deseado, por ejemplo el elemento raíz de la escena, una vez que está asociado con la escena (el QQuickWindow).
Documentación de las funciones miembro
[explicit] QQuickRenderControl::QQuickRenderControl(QObject *parent = nullptr)
Construye un objeto QQuickRenderControl, con el objeto padre parent.
[override virtual noexcept] QQuickRenderControl::~QQuickRenderControl()
Destruye la instancia. Libera todos los recursos del scenegraph.
Véase también invalidate().
[since 6.0] void QQuickRenderControl::beginFrame()
Especifica el inicio de un marco gráfico. Las llamadas a sync() o render() deben ir acompañadas de llamadas a beginFrame() y endFrame().
A diferencia del anterior mundo OpenGL de Qt 5, el renderizado con otras APIs gráficas requiere puntos más bien definidos de inicio y fin de un frame. Cuando se maneja manualmente el bucle de renderizado a través de QQuickRenderControl, ahora corresponde al usuario de QQuickRenderControl especificar estos puntos.
Un paso de actualización típico, incluyendo la inicialización de la renderización en una textura existente, podría parecerse a lo siguiente. El fragmento de ejemplo asume Direct3D 11 pero los mismos conceptos se aplican también a otras APIs gráficas.
if (!m_quickInitialized) { m_quickWindow->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(m_motor->dispositivo(), m_motor->contexto())); if (!m_renderControl->initialize()) qWarning("Failed to initialize redirected Qt Quick rendering"); m_quickWindow->setRenderTarget(QQuickRenderTarget::fromNativeTexture({ quint64(m_res.texture), 0}, QSize(QML_WIDTH, QML_HEIGHT),SAMPLE_COUNT)); m_quickInitialized = true; } m_renderControl->polishItems(); m_renderControl->beginFrame(); m_renderControl->sync(); m_renderControl->render(); m_renderControl->endFrame(); // Qt Quick's rendering commands are submitted to the device context here
Nota: Esta función no necesita ser, y no debe ser, llamada cuando se utiliza la adaptación software de Qt Quick.
Nota: Internamente beginFrame() y endFrame() invocan a beginOffscreenFrame() y endOffscreenFrame(), respectivamente. Esto implica que no debe haber ningún fotograma (ni fuera de pantalla, ni basado en swapchain) grabándose en QRhi cuando se llame a esta función.
Esta función se introdujo en Qt 6.0.
Véase también endFrame(), initialize(), sync(), render(), QQuickGraphicsDevice, y QQuickRenderTarget.
[since 6.6] QRhiCommandBuffer *QQuickRenderControl::commandBuffer() const
Devuelve el búfer de comandos actual.
Una vez que se llama a beginFrame(), se crea automáticamente un QRhiCommandBuffer. Ese es el búfer de comandos que utiliza Qt Quick scenegraph, pero en algunos casos las aplicaciones también pueden querer consultarlo, por ejemplo para emitir actualizaciones de recursos (por ejemplo, una lectura de textura).
La referencia a la memoria intermedia de comandos devuelta sólo debe utilizarse entre beginFrame() y endFrame(). Hay excepciones específicas, por ejemplo llamar a lastCompletedGpuTime() en el buffer de comandos justo después de endFrame(), pero antes del siguiente beginFrame(), es válido.
Nota: Esta función no es aplicable y devuelve null cuando se utiliza la adaptación software de Qt Quick.
Esta función se introdujo en Qt 6.6.
Véase también rhi(), beginFrame(), y endFrame().
[since 6.0] void QQuickRenderControl::endFrame()
Especifica el final de un marco gráfico. Las llamadas a sync() o render() deben ir acompañadas de llamadas a beginFrame() y endFrame().
Cuando se llama a esta función, todos los comandos gráficos en cola por el scenegraph se envían al contexto o a la cola de comandos, según corresponda.
Nota: Esta función no necesita ser, y no debe ser, llamada cuando se utiliza la adaptación software de Qt Quick.
Esta función se introdujo en Qt 6.0.
Véase también beginFrame(), initialize(), sync(), render(), QQuickGraphicsDevice, y QQuickRenderTarget.
[since 6.0] bool QQuickRenderControl::initialize()
Inicializa los recursos del gráfico de escena. Cuando se utiliza una API de gráficos, como Vulkan, Metal, OpenGL o Direct3D, para el renderizado de Qt Quick, QQuickRenderControl configurará un motor de renderizado apropiado cuando se llame a esta función. Esta infraestructura de renderizado existe mientras exista QQuickRenderControl.
Para controlar qué API gráfica utiliza Qt Quick, llame a QQuickWindow::setGraphicsApi() con una de las constantes QSGRendererInterface:GraphicsApi. Esto debe hacerse antes de llamar a esta función.
Para evitar que el scenegraph cree sus propios objetos de dispositivo y contexto, especifique un QQuickGraphicsDevice apropiado, envolviendo los objetos gráficos existentes, llamando a QQuickWindow::setGraphicsDevice().
Para configurar qué extensiones de dispositivo habilitar (por ejemplo, para Vulkan), llame a QQuickWindow::setGraphicsConfiguration() antes de esta función.
Nota: Cuando se utiliza Vulkan, QQuickRenderControl no crea un QVulkanInstance automáticamente. Más bien, es responsabilidad de la aplicación crear un QVulkanInstance y un associate it adecuados con el QQuickWindow. Antes de inicializar el QVulkanInstance, se recomienda encarecidamente consultar la lista de Qt Quick's extensiones de instancia deseadas llamando a la función estática QQuickGraphicsConfiguration::preferredInstanceExtensions() y pasar la lista devuelta a QVulkanInstance::setExtensions().
Devuelve true en caso de éxito, false en caso contrario.
Nota: Esta función no necesita ni debe ser llamada cuando se utiliza la adaptación software de Qt Quick.
Con la adaptación por defecto Qt Quick esta función crea un nuevo objeto QRhi, de forma similar a lo que ocurriría con un QQuickWindow en pantalla cuando no se utilizara QQuickRenderControl. Para hacer que este nuevo objeto QRhi adopte algún dispositivo o recurso contextual existente (por ejemplo, utilizar un QOpenGLContext existente en lugar de crear uno nuevo), utilice QQuickWindow::setGraphicsDevice() como se ha mencionado anteriormente. Si la aplicación desea que la representación de Qt Quick utilice un objeto QRhi ya existente, también puede hacerlo mediante QQuickGraphicsDevice::fromRhi(). Cuando se establece un QQuickGraphicsDevice, referenciando un QRhi ya existente, no habrá un nuevo objeto QRhi dedicado creado en initialize().
Esta función se introdujo en Qt 6.0.
Véase también QQuickRenderTarget, QQuickGraphicsDevice, y QQuickGraphicsConfiguration::preferredInstanceExtensions().
void QQuickRenderControl::invalidate()
Detiene la renderización y libera recursos.
Esto es el equivalente a las operaciones de limpieza que ocurren con un QQuickWindow real cuando la ventana se oculta.
Esta función es llamada desde el destructor. Por lo tanto, normalmente no será necesario llamarla directamente.
Una vez que se ha llamado a invalidate(), es posible reutilizar la instancia QQuickRenderControl llamando de nuevo a initialize().
Nota: Esta función no tiene en cuenta QQuickWindow::persistentSceneGraph() o QQuickWindow::persistentGraphics(). Esto significa que los recursos específicos del contexto son siempre liberados.
void QQuickRenderControl::polishItems()
Esta función debe ser llamada lo más tarde posible antes de sync(). En un escenario con hilos, el renderizado puede ocurrir en paralelo con esta función.
void QQuickRenderControl::prepareThread(QThread *targetThread)
Prepara el renderizado de la escena Qt Quick fuera del hilo GUI.
targetThread especifica el subproceso en el que tendrá lugar la sincronización y el renderizado. No hay necesidad de llamar a esta función en un escenario de un solo hilo.
void QQuickRenderControl::render()
Renderiza el escenario utilizando el contexto actual.
[signal] void QQuickRenderControl::renderRequested()
Esta señal se emite cuando es necesario renderizar el gráfico de la escena. No es necesario llamar a sync().
Nota: Evite activar el renderizado directamente cuando se emita esta señal. En su lugar, prefiera diferirlo utilizando un temporizador, por ejemplo. Esto mejorará el rendimiento.
[virtual] QWindow *QQuickRenderControl::renderWindow(QPoint *offset)
Reimplementado en subclases para devolver la ventana real en la que se está renderizando este control.
Si offset no es nulo, se establece al desplazamiento del control dentro de la ventana.
Nota: Aunque no es obligatorio, reimplementar esta función es esencial para soportar múltiples pantallas con diferentes proporciones de píxeles y posicionar correctamente las ventanas emergentes abiertas desde QML. Por lo tanto, es muy recomendable incluirla en las subclases.
[static] QWindow *QQuickRenderControl::renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr)
Devuelve la ventana real en la que se está renderizando win, si existe.
Si offset no es nulo, se establece al desplazamiento de la renderización dentro de su ventana.
[since 6.6] QRhi *QQuickRenderControl::rhi() const
Devuelve el QRhi al que está asociado este QQuickRenderControl.
Nota: El QRhi sólo existe cuando initialize() se ha completado con éxito. Antes de eso el valor devuelto es null.
Nota: Esta función no es aplicable y devuelve null cuando se utiliza la adaptación software de Qt Quick.
Esta función se introdujo en Qt 6.6.
Véase también commandBuffer(), beginFrame(), y endFrame().
[since 6.0] int QQuickRenderControl::samples() const
Devuelve el recuento de muestras actual. 1 o 0 significa que no hay multimuestreo.
Esta función se introdujo en Qt 6.0.
Véase también setSamples().
[signal] void QQuickRenderControl::sceneChanged()
Esta señal se emite cuando se actualiza el gráfico de la escena, lo que significa que es necesario llamar a polishItems() y sync(). Si sync() devuelve verdadero, entonces render() necesita ser llamado.
Nota: Evite activar el pulido, la sincronización y el renderizado directamente cuando se emita esta señal. En su lugar, prefiera diferirlo utilizando un temporizador, por ejemplo. Esto conducirá a un mejor rendimiento.
[since 6.0] void QQuickRenderControl::setSamples(int sampleCount)
Establece el número de muestras que se utilizarán para el multimuestreo. Cuando sampleCount es 0 o 1, el multimuestreo está desactivado.
Nota: Esta función se usa siempre en combinación con un objetivo de render multimuestreo, lo que significa que sampleCount debe coincidir con el número de muestras pasado a QQuickRenderTarget::fromNativeTexture(), que a su vez debe coincidir con el número de muestras de la textura nativa.
Esta función se introdujo en Qt 6.0.
Ver también samples(), initialize(), y QQuickRenderTarget.
bool QQuickRenderControl::sync()
Esta función se utiliza para sincronizar la escena QML con el gráfico de escena de renderizado.
Si se utiliza un subproceso de renderizado dedicado, el subproceso GUI debe bloquearse mientras dure esta llamada.
Devuelve true si la sincronización cambió el gráfico de escena.
[since 6.0] QQuickWindow *QQuickRenderControl::window() const
Devuelve el QQuickWindow al que está asociado este QQuickRenderControl.
Nota: Un QQuickRenderControl se asocia con un QQuickWindow cuando se construye el QQuickWindow. El valor de retorno de esta función es nulo antes de ese punto.
Esta función se introdujo en Qt 6.0.
© 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.
