QQuickRenderControl Class
La clase `QQuickRenderControl` proporciona un mecanismo para renderizar el grafo de escena de ` Qt Quick ` en un destino de renderizado fuera de pantalla, de forma totalmente controlada por la aplicación. Más información...
| Encabezado: | #include <QQuickRenderControl> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| Heredan: | 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, junto con sus bucles de renderizado internos asociados, renderizan la escena Qt Quick en una ventana nativa. En algunos casos, por ejemplo al integrar con motores de renderizado de terceros como OpenGL, Vulkan, Metal o Direct 3D, puede resultar útil obtener la escena en una textura que luego pueda ser utilizada de forma arbitraria por el motor de renderizado externo. Este mecanismo también resulta esencial a la hora de integrarse con un marco de trabajo de realidad virtual. QQuickRenderControl lo hace posible mediante aceleración por hardware, a diferencia de la alternativa, limitada en cuanto a rendimiento, que consiste en utilizar QQuickWindow::grabWindow()
Al utilizar un `QQuickRenderControl`, el ` QQuickWindow ` no debe tener la propiedad ` shown ` (no será visible en pantalla) y no habrá una ventana nativa subyacente para él. En su lugar, la instancia de ` QQuickWindow ` se asocia al objeto de control de renderizado, utilizando la sobrecarga del constructor ` QQuickWindow ` y un objeto de textura o imagen especificado mediante ` QQuickWindow::setRenderTarget()`. El objeto ` QQuickWindow ` sigue siendo esencial, ya que representa la escena de ` Qt Quick ` y proporciona la mayor parte de los mecanismos de gestión de la escena y de entrega 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, los contextos y los objetos de imagen y textura recae en la aplicación. El dispositivo o contexto que utilizará Qt Quick debe crearse antes de llamar a initialize(). La creación del objeto de textura puede aplazarse; véase más adelante. Qt 5.4 introduce la capacidad de QOpenGLContext para adoptar contextos nativos existentes. Junto con QQuickRenderControl, esto permite crear un QOpenGLContext que comparta el contexto existente de un motor de renderizado externo. Este nuevo QOpenGLContext puede utilizarse entonces para renderizar la escena Qt Quick en una textura a la que también pueda acceder el contexto del otro motor. Para Vulkan, Metal y Direct 3D no existen envoltorios proporcionados por Qt para los objetos de dispositivo, por lo que los existentes pueden pasarse tal cual mediante ` QQuickWindow::setGraphicsDevice()` ().
La carga y la instanciación de los componentes QML se realizan utilizando un ` QQmlEngine`. Una vez creado el objeto raíz, deberá vincularse como padre al `contentItem()` de ` QQuickWindow`.
Las aplicaciones normalmente tendrán que conectarse a cuatro señales importantes:
- QQuickWindow::sceneGraphInitialized() Emitida en algún momento tras llamar a ` QQuickRenderControl::initialize()`. Al recibir esta señal, se espera que la aplicación cree su objeto framebuffer y lo asocie con el ` QQuickWindow`.
- QQuickWindow::sceneGraphInvalidated() Cuando se liberan los recursos del grafo de escena, el objeto framebuffer también puede destruirse.
- QQuickRenderControl::renderRequested() Indica que la escena debe renderizarse llamando a ` render()`. Tras establecer el contexto como actual, se espera que las aplicaciones llamen a ` render()`.
- QQuickRenderControl::sceneChanged() Indica que la escena ha cambiado, lo que significa que, antes del renderizado, también es necesario realizar el pulido y la sincronización.
Para enviar eventos —por ejemplo, eventos de ratón o teclado— a la escena, utiliza ` QCoreApplication::sendEvent()` con la instancia de ` QQuickWindow ` como receptor.
En el caso de los eventos de teclas, 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 a la escena (el ` QQuickWindow`).
Documentación de funciones miembro
[explicit] QQuickRenderControl::QQuickRenderControl(QObject *parent = nullptr)
Crea un objeto `QQuickRenderControl`, cuyo objeto padre es ` parent`.
[override virtual noexcept] QQuickRenderControl::~QQuickRenderControl()
Destruye la instancia. Libera todos los recursos del grafo de escena.
Véase también invalidate().
[since 6.0] void QQuickRenderControl::beginFrame()
Especifica el inicio de un fotograma gráfico. Las llamadas a ` sync()` o ` render()` deben estar enmarcadas entre llamadas a `beginFrame()` y ` endFrame()`.
A diferencia del entorno anterior de Qt 5, que solo utilizaba OpenGL, el renderizado con otras API gráficas requiere puntos de inicio y fin de un fotograma mejor definidos. Al controlar manualmente el bucle de renderizado mediante ` QQuickRenderControl`, ahora corresponde al usuario de ` QQuickRenderControl ` especificar estos puntos.
Un paso de actualización típico, que incluya la inicialización del renderizado en una textura existente, podría tener el siguiente aspecto. El fragmento de código de ejemplo parte de la base de Direct3D 11, pero los mismos conceptos se aplican también a otras API gráficas.
if (!m_quickInitialized) {
m_quickWindow->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(m_engine->device(), m_engine->context()));
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(); // Los comandos de renderizado de Qt Quick se envían al contexto del dispositivo aquíNota: Esta función no tiene por qué ser llamada, y no debe serlo, cuando se utiliza la adaptación de 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 la cadena de intercambio) que se esté grabando en el 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 configura automáticamente un ` QRhiCommandBuffer `. Ese es el búfer de comandos que utiliza el grafo de escena ` Qt Quick `, pero en algunos casos las aplicaciones también pueden querer consultarlo, por ejemplo, para realizar actualizaciones de recursos (como la lectura de una textura).
La referencia al búfer de comandos devuelta solo debe utilizarse entre beginFrame() y endFrame(). Existen excepciones específicas; por ejemplo, es válido llamar a lastCompletedGpuTime() en el búfer de comandos justo después de endFrame(), pero antes de la siguiente llamada a beginFrame().
Nota: Esta función no es aplicable y devuelve null cuando se utiliza la adaptación de 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 fotograma gráfico. Las llamadas a ` sync()` o ` render()` deben estar enmarcadas entre llamadas a ` beginFrame()` y `endFrame()`.
Cuando se llama a esta función, cualquier comando gráfico puesto en cola por el grafo de escena se envía al contexto o a la cola de comandos, según corresponda.
Nota: No es necesario, ni debe, llamarse aesta función 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 grafo de escena. Cuando se utiliza una API gráfica, como Vulkan, Metal, OpenGL o Direct3D, para el renderizado de Qt Quick, QQuickRenderControl configurará un motor de renderizado adecuado al llamar a esta función. Esta infraestructura de renderizado permanece activa mientras exista el QQuickRenderControl.
Para controlar qué API gráfica utiliza Qt Quick, llama a QQuickWindow::setGraphicsApi() con una de las constantes QSGRendererInterface:GraphicsApi. Esto debe hacerse antes de llamar a esta función.
Para evitar que el grafo de escena cree sus propios objetos de dispositivo y de contexto, especifica un ` QQuickGraphicsDevice` adecuado, que envuelva los objetos gráficos existentes, llamando a ` QQuickWindow::setGraphicsDevice()`.
Para configurar qué extensiones de dispositivo se deben habilitar (por ejemplo, para Vulkan), llama a ` QQuickWindow::setGraphicsConfiguration()` antes de esta función.
Nota: Al utilizar Vulkan, ` QQuickRenderControl ` no crea un ` QVulkanInstance ` automáticamente. Por el contrario, 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 extensiones de instancia deseadas de ` Qt Quick` 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 ser llamada, ni debe serlo, cuando se utiliza la adaptación « software » de « Qt Quick ».
Con la adaptación predeterminada de ` 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 utiliza ` QQuickRenderControl `. Para que este nuevo objeto ` QRhi ` adopte algún recurso de dispositivo o contexto ya existente (por ejemplo, utilizar un ` QOpenGLContext ` ya existente en lugar de crear uno nuevo), utilice ` QQuickWindow::setGraphicsDevice()` tal y como se ha mencionado anteriormente. Cuando la aplicación desee que la representación de Qt Quick utilice un objeto QRhi ya existente, esto también es posible mediante QQuickGraphicsDevice::fromRhi(). Cuando se establece dicho QQuickGraphicsDevice, que hace referencia a un QRhi ya existente, no se creará ningún objeto QRhi nuevo y dedicado en initialize().
Esta función se introdujo en Qt 6.0.
Véase también QQuickRenderTarget, QQuickGraphicsDevice y QQuickGraphicsConfiguration::preferredInstanceExtensions().
void QQuickRenderControl::invalidate()
Detener el renderizado y liberar recursos.
Esto equivale a las operaciones de limpieza que se producen en un QQuickWindow real cuando la ventana se oculta.
Esta función se invoca desde el destructor. Por lo tanto, normalmente no será necesario invocarla directamente.
Una vez que se ha llamado a `invalidate()`, es posible reutilizar la instancia de ` QQuickRenderControl ` llamando de nuevo a ` initialize()`.
Nota: Esta función no tiene en cuenta QQuickWindow::persistentSceneGraph() ni QQuickWindow::persistentGraphics(). Esto significa que los recursos específicos del contexto siempre se liberan.
void QQuickRenderControl::polishItems()
Esta función debe llamarse lo más tarde posible antes de « sync()». En un entorno con subprocesos, el renderizado puede realizarse en paralelo con esta función.
void QQuickRenderControl::prepareThread(QThread *targetThread)
Prepara el renderizado de la escena « Qt Quick » fuera del hilo de la interfaz gráfica de usuario.
targetThread Especifica el hilo en el que se llevarán a cabo la sincronización y la representación. No es necesario llamar a esta función en un escenario de un solo hilo.
void QQuickRenderControl::render()
Renderiza el grafo de escena utilizando el contexto actual.
[signal] void QQuickRenderControl::renderRequested()
Esta señal se emite cuando es necesario renderizar el grafo de escena. No es necesario llamar a ` sync()`.
Nota: Evita activar el renderizado directamente cuando se emita esta señal. En su lugar, es preferible aplazarlo utilizando, por ejemplo, un temporizador. Esto mejorará el rendimiento.
[virtual] QWindow *QQuickRenderControl::renderWindow(QPoint *offset)
Se vuelve a implementar en las subclases para devolver la ventana real en la que este control de representación está realizando la representación.
Si ` offset ` no es nulo, se establece como el desplazamiento del control dentro de la ventana.
Nota: Aunque no es obligatorio, reimplementar esta función resulta esencial para dar soporte a múltiples pantallas con diferentes relaciones de píxeles del dispositivo y para posicionar correctamente las ventanas emergentes abiertas desde QML. Por lo tanto, se recomienda encarecidamente implementarla en las subclases.
[static] QWindow *QQuickRenderControl::renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr)
Devuelve la ventana real en la que se está representando win, si la hay.
Si offset no es nulo, se establece en el desplazamiento de la representación dentro de su ventana.
[since 6.6] QRhi *QQuickRenderControl::rhi() const
Devuelve el objeto ` QRhi ` al que está asociado este ` QQuickRenderControl `.
Nota: El objeto ` QRhi ` solo existe cuando la función ` 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 número de muestras actual. Un valor de 1 o 0 indica 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 escena, lo que significa que es necesario llamar a « polishItems()» y « sync()». Si « sync()» devuelve «true», entonces es necesario llamar a « render()».
Nota: Evita activar el pulido, la sincronización y el renderizado directamente cuando se emita esta señal. En su lugar, es preferible aplazarlo utilizando, por ejemplo, un temporizador. Esto mejorará el rendimiento.
[since 6.0] void QQuickRenderControl::setSamples(int sampleCount)
Establece el número de muestras que se utilizarán para el multisampling. Cuando sampleCount es 0 o 1, el multisampling queda desactivado.
Nota: Esta función siempre se utiliza en combinación con un destino de renderizado 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.
Véase también samples(), initialize() y QQuickRenderTarget.
bool QQuickRenderControl::sync()
Esta función se utiliza para sincronizar la escena QML con el grafo de escena de renderizado.
Si se utiliza un hilo de renderizado dedicado, el hilo de la interfaz gráfica de usuario debe bloquearse mientras dure esta llamada.
Devuelve «true» si la sincronización ha modificado el grafo de escena.
[since 6.0] QQuickWindow *QQuickRenderControl::window() const
Devuelve el « QQuickWindow » al que está asociado este « QQuickRenderControl ».
Nota: Un ` QQuickRenderControl ` se asocia a un ` QQuickWindow ` al crear el ` QQuickWindow`. El valor devuelto por esta función es `null` antes de ese momento.
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.