QQuickWindow Class

Documentación de las funciones miembro

[explicit] QQuickWindow::QQuickWindow(QQuickRenderControl *control)

Construye una ventana para mostrar una escena QML, cuya renderización será controlada por el objeto control. Consulte la documentación de QQuickRenderControl para obtener más información.

[explicit] QQuickWindow::QQuickWindow(QWindow *parent = nullptr)

Construye una ventana para mostrar una escena QML con la ventana padre parent.

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

Destruye la ventana.

[override virtual] QAccessibleInterface *QQuickWindow::accessibleRoot() const

Devuelve una interfaz de accesibilidad para esta ventana, o 0 si no se puede crear dicha interfaz.

[signal] void QQuickWindow::afterAnimating()

Esta señal se emite en el subproceso GUI antes de solicitar al subproceso de renderizado que realice la sincronización del gráfico de la escena.

A diferencia de otras señales similares, ésta se emite en el subproceso GUI en lugar de en el subproceso de renderizado. Puede utilizarse para sincronizar sistemas de animación externos con el contenido QML. Al mismo tiempo, esto significa que esta señal no es adecuada para activar operaciones gráficas.

[signal, since 6.0] void QQuickWindow::afterFrameEnd()

Esta señal se emite cuando el gráfico de escena ha enviado un fotograma. Se emite después de todas las demás señales relacionadas, como afterRendering(). Es la última señal que emite el subproceso de renderizado del gráfico de escena al renderizar un fotograma.

Esta función se introdujo en Qt 6.0.

Véase también beforeFrameBegin() y rendererInterface().

[signal] void QQuickWindow::afterRenderPassRecording()

Esta señal se emite después de que el scenegraph haya grabado los comandos para su pase de renderizado principal, pero el pase aún no ha finalizado en el buffer de comandos.

Esta señal se emite antes que afterRendering(), y garantiza que no sólo el fotograma sino también la grabación del pase de renderizado principal del scenegraph siguen activos. Esto permite insertar comandos sin tener que generar un pase de renderizado completo por separado (que normalmente borraría las imágenes adjuntas). Los objetos gráficos nativos pueden consultarse a través de QSGRendererInterface.

Véase también rendererInterface() y Gráfico de escena - RHI bajo QML.

[signal] void QQuickWindow::afterRendering()

La señal se emite después de que el gráfico de escena haya añadido sus comandos al búfer de comandos, que aún no se ha enviado a la cola de gráficos. Si se desea, la función de ranura conectada a esta señal puede consultar recursos nativos, como el búfer de comandos, antes a través de QSGRendererInterface. Nótese, sin embargo, que el pase (o pases) de renderizado ya están grabados en este punto y no es posible añadir más comandos dentro del pase del scenegraph. En su lugar, utilice afterRenderPassRecording() para ello. Por lo tanto, esta señal tiene un uso limitado en Qt 6, a diferencia de Qt 5. Más bien, es la combinación de beforeRendering() y beforeRenderPassRecording(), o beforeRendering() y afterRenderPassRecording(), lo que se utiliza normalmente para lograr la sub- o superposición del renderizado personalizado.

Véase también rendererInterface(), Gráfico de escena - RHI bajo QML, Gráfico de escena - OpenGL bajo QML, Gráfico de escena - Metal bajo QML, Gráfico de escena - Vulkan bajo QML y Gráfico de escena - Direct3D 11 bajo QML.

[signal] void QQuickWindow::afterSynchronizing()

Esta señal se emite después de sincronizar el gráfico de escena con el estado QML.

Esta señal se puede utilizar para hacer la preparación necesaria después de las llamadas a QQuickItem::updatePaintNode(), mientras que el hilo GUI está todavía bloqueado.

Cuando se utiliza OpenGL, el QOpenGLContext utilizado para el renderizado por el gráfico de escena se vinculará en este punto.

[signal, since 6.0] void QQuickWindow::beforeFrameBegin()

Esta señal se emite antes de que el gráfico de escena comience a preparar el fotograma. Precede a señales como beforeSynchronizing() o beforeRendering(). Es la primera señal que emite el subproceso de renderizado del gráfico de escena cuando comienza a preparar un nuevo fotograma.

Esta señal es relevante para frameworks gráficos de bajo nivel que necesitan ejecutar ciertas operaciones, como la limpieza de recursos, en una etapa en la que Qt Quick no ha iniciado la grabación de un nuevo frame a través de las APIs de interfaz del hardware de renderizado subyacente.

Esta función se introdujo en Qt 6.0.

Véase también afterFrameEnd() y rendererInterface().

[signal] void QQuickWindow::beforeRenderPassRecording()

Esta señal se emite antes de que el scenegraph comience a grabar comandos para el pase de render principal. (Las capas tienen sus propios pases y están completamente grabadas para cuando se emite esta señal). El pase de renderizado ya está activo en el buffer de comandos cuando se emite la señal.

Esta señal se emite más tarde que beforeRendering() y garantiza que no sólo está activo el fotograma, sino también la grabación del pase de renderizado principal del scenegraph. Esto permite insertar comandos sin tener que generar un pase de renderizado completo por separado (que normalmente borraría las imágenes adjuntas). Los objetos gráficos nativos pueden consultarse a través de QSGRendererInterface.

Véase también rendererInterface() y Scene Graph - RHI Under QML.

[signal] void QQuickWindow::beforeRendering()

Esta señal se emite después de que se hayan realizado los preparativos para la trama, lo que significa que hay un búfer de comandos en modo de grabación, en su caso. Si se desea, la función de slot conectada a esta señal puede consultar recursos nativos como el comando anterior a través de QSGRendererInterface. Tenga en cuenta, sin embargo, que la grabación del pase de renderizado principal aún no se ha iniciado en este punto y no es posible añadir comandos dentro de ese pase. Iniciar un pase significa borrar los buffers de color, profundidad y stencil, por lo que no es posible conseguir un renderizado de tipo underlay simplemente conectándose a esta señal. En su lugar, conéctese a beforeRenderPassRecording(). Sin embargo, la conexión a esta señal sigue siendo importante si se desea la grabación de comandos de tipo copia, ya que éstos no se pueden poner en cola dentro de un pase de renderizado.

Véase también rendererInterface(), Gráfico de escena - RHI bajo QML, Gráfico de escena - OpenGL bajo QML, Gráfico de escena - Metal bajo QML, Gráfico de escena - Vulkan bajo QML y Gráfico de escena - Direct3D 11 bajo QML.

[signal] void QQuickWindow::beforeSynchronizing()

Esta señal se emite antes de que el gráfico de escena se sincronice con el estado QML.

Aunque la señal se emite desde el subproceso de renderización del gráfico de la escena, se garantiza que el subproceso de la interfaz gráfica de usuario está bloqueado, al igual que en QQuickItem::updatePaintNode(). Por lo tanto, es seguro acceder a los datos del subproceso GUI en una ranura o lambda que esté conectada con Qt::DirectConnection.

Esta señal puede utilizarse para realizar cualquier preparación necesaria antes de llamar a QQuickItem::updatePaintNode().

Cuando se utiliza OpenGL, el QOpenGLContext utilizado para el renderizado por el gráfico de escena se vinculará en este punto.

void QQuickWindow::beginExternalCommands()

Cuando se mezclan comandos de gráficos sin procesar (OpenGL, Vulkan, Metal, etc.) con el renderizado del gráfico de escena, es necesario llamar a esta función antes de grabar los comandos en el búfer de comandos utilizado por el gráfico de escena para renderizar su pase de renderizado principal. Esto es para evitar el estado de clobbering.

En la práctica, esta función se llama a menudo desde una ranura conectada a las señales beforeRenderPassRecording() o afterRenderPassRecording().

La función no necesita ser llamada cuando se graban comandos en el propio buffer de comandos de la aplicación (por ejemplo, un VkCommandBuffer o MTLCommandBuffer + MTLRenderCommandEncoder creado y gestionado por la aplicación, no recuperado del gráfico de escena). Con APIs gráficas en las que no se expone el concepto de buffer de comandos nativo (OpenGL, Direct 3D 11), beginExternalCommands() y endExternalCommands() juntos proporcionan un reemplazo para la función resetOpenGLState() de Qt 5.

Llamar a esta función y a endExternalCommands() no es necesario dentro de la implementación de render() de un QSGRenderNode porque el gráfico de escena realiza los pasos necesarios implícitamente para los nodos de render.

Los objetos gráficos nativos (como, dispositivo gráfico, buffer de comandos o codificador) son accesibles a través de QSGRendererInterface::getResource().

Véase también endExternalCommands() y QQuickOpenGLUtils::resetOpenGLState().

[override virtual protected] void QQuickWindow::closeEvent(QCloseEvent *e)

Reimplementa: QWindow::closeEvent(QCloseEvent *ev).

QSGImageNode *QQuickWindow::createImageNode() const

Crea un nodo de imagen simple. Cuando el scenegraph no está inicializado, el valor de retorno es null.

Se trata de una alternativa cruzada a la construcción directa de QSGSimpleTextureNode.

Véase también QSGImageNode.

QSGNinePatchNode *QQuickWindow::createNinePatchNode() const

Crea un nodo de nueve parches. Cuando el escenario no está inicializado, el valor devuelto es null.

QSGRectangleNode *QQuickWindow::createRectangleNode() const

Crea un nodo rectángulo simple. Cuando el scenegraph no está inicializado, el valor de retorno es null.

Se trata de una alternativa cruzada a la construcción directa de QSGSimpleRectNode.

Véase también QSGRectangleNode.

[since 6.7] QSGTextNode *QQuickWindow::createTextNode() const

Crea un nodo de texto. Cuando el scenegraph no está inicializado, el valor de retorno es null.

Esta función se introdujo en Qt 6.7.

Véase también QSGTextNode.

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image, QQuickWindow::CreateTextureOptions options) const

Crea un nuevo QSGTexture a partir del image suministrado. Si la imagen tiene un canal alfa, la textura correspondiente tendrá un canal alfa.

La persona que llama a la función es responsable de borrar la textura devuelta. El objeto de textura nativo subyacente se destruye junto con QSGTexture.

Cuando options contiene TextureCanUseAtlas, el motor puede colocar la imagen en un atlas de texturas. Las texturas en un atlas necesitan depender de QSGTexture::normalizedTextureSubRect() para su geometría y no soportarán QSGTexture::Repeat. Otros valores de CreateTextureOption son ignorados.

Cuando options contiene TextureIsOpaque, el motor creará una textura RGB que devuelve false para QSGTexture::hasAlphaChannel(). Las texturas opacas serán en la mayoría de los casos más rápidas de renderizar. Cuando esta bandera no está activada, la textura tendrá un canal alfa basado en el formato de la imagen.

Cuando options contiene TextureHasMipmaps, el motor creará una textura que puede utilizar el filtrado mipmap. Las texturas mipmapped no pueden estar en un atlas.

Establecer TextureHasAlphaChannel en options no sirve de nada para esta función, ya que asumir un canal alfa y la mezcla es el valor predeterminado. Para evitarlo, defina TextureIsOpaque.

Cuando el gráfico de escena utiliza OpenGL, la textura devuelta utilizará GL_TEXTURE_2D como destino de textura y GL_RGBA como formato interno. Con otras APIs gráficas, el formato de textura es normalmente RGBA8. Reimplemente QSGTexture para crear texturas con parámetros diferentes.

Esta función puede ser llamada tanto desde el hilo principal como desde el hilo de renderizado.

Ver también sceneGraphInitialized() y QSGTexture.

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image) const

[since 6.6] QSGTexture *QQuickWindow::createTextureFromRhiTexture(QRhiTexture *texture, QQuickWindow::CreateTextureOptions options = {}) const

Crea un nuevo QSGTexture a partir del texture suministrado.

Utilice options para personalizar los atributos de textura. Esta función sólo tiene en cuenta la bandera TextureHasAlphaChannel. Cuando se establece, el renderizador de gráficos de escena siempre trata el QSGTexture resultante como si necesitara mezcla. Para las texturas que son totalmente opacas, no establecer la bandera puede ahorrar el coste de realizar la mezcla alfa durante el renderizado. La bandera no tiene correspondencia directa con el format del QRhiTexture, es decir, no fijar la bandera teniendo un formato de textura como el comúnmente utilizado QRhiTexture::RGBA8 es perfectamente normal.

El mipmapping no está controlado por options ya que texture ya está creado y tiene incorporada la presencia o ausencia de mipmaps.

El QSGTexture devuelto es el propietario de QRhiTexture, lo que significa que texture se destruye junto con el QSGTexture devuelto.

Si texture posee sus recursos gráficos nativos subyacentes (objeto de textura OpenGL, imagen Vulkan, etc.), eso depende de cómo fue creado QRhiTexture (QRhiTexture::create() o QRhiTexture::createFrom()), y eso no es controlado o cambiado por esta función.

Esta función se introdujo en Qt 6.6.

Véase también createTextureFromImage(), sceneGraphInitialized(), y QSGTexture.

[signal, since 6.11] void QQuickWindow::devicePixelRatioChanged()

Esta señal se emite cuando se ha modificado la proporción efectiva de píxeles del dispositivo.

Esta función se introdujo en Qt 6.11.

Véase también effectiveDevicePixelRatio().

qreal QQuickWindow::effectiveDevicePixelRatio() const

Devuelve la proporción de píxeles del dispositivo para esta ventana.

Esto es diferente de QWindow::devicePixelRatio() en que soporta el renderizado redirigido a través de QQuickRenderControl y QQuickRenderTarget. Cuando se utiliza un QQuickRenderControl, el QQuickWindow a menudo no se crea completamente, lo que significa que nunca se muestra y no hay una ventana nativa subyacente creada en el sistema de ventanas. Como resultado, la consulta de propiedades como la proporción de píxeles del dispositivo no puede dar resultados correctos. Esta función tiene en cuenta tanto QQuickRenderControl::renderWindowFor() como QQuickRenderTarget::devicePixelRatio(). Cuando no hay redirección, el resultado es el mismo que QWindow::devicePixelRatio().

Véase también QQuickRenderControl, QQuickRenderTarget, setRenderTarget(), y QWindow::devicePixelRatio().

void QQuickWindow::endExternalCommands()

Cuando se mezclan comandos de gráficos sin procesar (OpenGL, Vulkan, Metal, etc.) con el renderizado de gráficos de escena, es necesario llamar a esta función después de grabar comandos en el búfer de comandos utilizado por el gráfico de escena para renderizar su pase de renderizado principal. Esto es para evitar el estado de clobbering.

En la práctica, esta función se llama a menudo desde una ranura conectada a las señales beforeRenderPassRecording() o afterRenderPassRecording().

La función no necesita ser llamada cuando se graban comandos en el propio buffer de comandos de la aplicación (por ejemplo, un VkCommandBuffer o MTLCommandBuffer + MTLRenderCommandEncoder creado y gestionado por la aplicación, no recuperado del gráfico de escena). Con las API de gráficos en las que no se expone el concepto de búfer de comandos nativo (OpenGL, Direct 3D 11), beginExternalCommands() y endExternalCommands() proporcionan conjuntamente un sustituto de la función resetOpenGLState() de Qt 5.

Llamar a esta función y a beginExternalCommands() no es necesario dentro de la implementación de render() de un QSGRenderNode porque el gráfico de escena realiza los pasos necesarios implícitamente para los nodos de render.

Véase también beginExternalCommands() y QQuickOpenGLUtils::resetOpenGLState().

[override virtual protected] bool QQuickWindow::event(QEvent *event)

Reimplementa: QWindow::event(QEvent *ev).

[override virtual protected] void QQuickWindow::exposeEvent(QExposeEvent *)

Reimplementa: QWindow::exposeEvent(QExposeEvent *ev).

[override virtual protected] void QQuickWindow::focusInEvent(QFocusEvent *ev)

Reimplementa: QWindow::focusInEvent(QFocusEvent *ev).

[override virtual protected] void QQuickWindow::focusOutEvent(QFocusEvent *ev)

Reimplementa: QWindow::focusOutEvent(QFocusEvent *ev).

[signal] void QQuickWindow::frameSwapped()

Esta señal se emite cuando un fotograma se ha puesto en cola para su presentación. Con la sincronización vertical activada, la señal se emite como máximo una vez por intervalo vsync en una escena de animación continua.

Esta señal se emitirá desde el subproceso de renderizado del gráfico de la escena.

QImage QQuickWindow::grabWindow()

Toma el contenido de la ventana y lo devuelve como imagen.

Es posible llamar a la función grabWindow() cuando la ventana no está visible. Esto requiere que la ventana sea created y tenga un tamaño válido y que no haya otras instancias de QQuickWindow renderizándose en el mismo proceso.

[static, since 6.0] QSGRendererInterface::GraphicsApi QQuickWindow::graphicsApi()

Devuelve la API gráfica que utilizaría el gráfico de escena si se inicializara en este momento.

La forma estándar de consultar la API utilizada por el gráfico de escena es utilizar QSGRendererInterface::graphicsApi() una vez que el gráfico de escena se ha inicializado, por ejemplo cuando o después de que se emita la señal sceneGraphInitialized(). En ese caso se obtiene el resultado verdadero, real, porque entonces se sabe que todo se inicializó correctamente usando esa API de gráficos.

Esto no siempre es conveniente. Si la aplicación necesita configurar frameworks externos, o necesita trabajar con setGraphicsDevice() de una manera que depende de la lógica de selección de la API incorporada en el gráfico de escena, no siempre es feasiable aplazar tales operaciones hasta después de que QQuickWindow se haya hecho visible o QQuickRenderControl::initialize() haya sido llamado.

Por lo tanto, esta función estática se proporciona como contrapartida a setGraphicsApi(): puede llamarse en cualquier momento, y el resultado refleja qué API elegiría el gráfico de escena si estuviera inicializado en el momento de la llamada.

Esta función se introdujo en Qt 6.0.

Véase también setGraphicsApi().

[since 6.0] QQuickGraphicsConfiguration QQuickWindow::graphicsConfiguration() const

Devuelve el QQuickGraphicsConfiguration pasado a setGraphicsConfiguration(), o uno construido por defecto en caso contrario.

Esta función se introdujo en Qt 6.0.

Véase también setGraphicsConfiguration().

[since 6.0] QQuickGraphicsDevice QQuickWindow::graphicsDevice() const

Devuelve el QQuickGraphicsDevice pasado a setGraphicsDevice(), o uno construido por defecto en caso contrario.

Esta función se introdujo en Qt 6.0.

Véase también setGraphicsDevice().

const QQuickWindow::GraphicsStateInfo &QQuickWindow::graphicsStateInfo()

Devuelve una referencia a una estructura GraphicsStateInfo que describe parte del estado interno del RHI, en particular, el estado de almacenamiento en búfer doble o triple del backend (como las integraciones de Vulkan o Metal). Esto es relevante cuando las APIs gráficas subyacentes son Vulkan o Metal, y el código de renderizado externo desea realizar doble o triple buffering de sus propios recursos que cambian a menudo, tales como, buffers uniformes, con el fin de evitar el estancamiento del pipeline.

[static] bool QQuickWindow::hasDefaultAlphaBuffer()

Devuelve si se utiliza la transparencia alfa en las ventanas recién creadas.

Véase también setDefaultAlphaBuffer().

[override virtual protected] void QQuickWindow::hideEvent(QHideEvent *)

Reimplementa: QWindow::hideEvent(QHideEvent *ev).

QQmlIncubationController *QQuickWindow::incubationController() const

Devuelve un controlador de incubación que empalma la incubación entre marcos para esta ventana. QQuickView instala automáticamente este controlador por usted, de lo contrario tendrá que instalarlo usted mismo utilizando QQmlEngine::setIncubationController().

El controlador es propiedad de la ventana y será destruido cuando la ventana sea eliminada.

bool QQuickWindow::isPersistentGraphics() const

Devuelve si los recursos gráficos esenciales pueden liberarse durante el tiempo de vida de QQuickWindow.

Véase también setPersistentGraphics().

bool QQuickWindow::isPersistentSceneGraph() const

Devuelve si los nodos y recursos del grafo de escena pueden ser liberados durante el tiempo de vida de este QQuickWindow.

bool QQuickWindow::isSceneGraphInitialized() const

Devuelve true si el gráfico de escena ha sido inicializado; en caso contrario devuelve false.

[override virtual protected] void QQuickWindow::keyPressEvent(QKeyEvent *e)

Reimplementa: QWindow::keyPressEvent(QKeyEvent *ev).

[override virtual protected] void QQuickWindow::keyReleaseEvent(QKeyEvent *e)

Reimplementa: QWindow::keyReleaseEvent(QKeyEvent *ev).

[override virtual protected] void QQuickWindow::mouseDoubleClickEvent(QMouseEvent *event)

Reimplementa: QWindow::mouseDoubleClickEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mouseMoveEvent(QMouseEvent *event)

Reimplementa: QWindow::mouseMoveEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mousePressEvent(QMouseEvent *event)

Reimplementa: QWindow::mousePressEvent(QMouseEvent *ev).

[override virtual protected] void QQuickWindow::mouseReleaseEvent(QMouseEvent *event)

Reimplementa: QWindow::mouseReleaseEvent(QMouseEvent *ev).

[slot] void QQuickWindow::releaseResources()

Esta función intenta liberar los recursos redundantes actualmente retenidos por la escena QML.

Al llamar a esta función, se solicita al gráfico de escena que libere los recursos gráficos almacenados en caché, como los objetos del conducto de gráficos, los programas de sombreado o los datos de imagen.

Además, dependiendo del bucle de renderizado en uso, esta función también puede provocar que se libere el gráfico de escena y todos los recursos de renderizado relacionados con la ventana. Si esto ocurre, se emitirá la señal sceneGraphInvalidated(), permitiendo a los usuarios limpiar sus propios recursos gráficos. Las funciones setPersistentGraphics() y setPersistentSceneGraph() se pueden utilizar para evitar que esto suceda, si el manejo de la limpieza no es factible en la aplicación, a costa de un mayor uso de memoria.

Véase también sceneGraphInvalidated(), setPersistentGraphics(), y setPersistentSceneGraph().

[since 6.0] QQuickRenderTarget QQuickWindow::renderTarget() const

Devuelve el QQuickRenderTarget pasado a setRenderTarget(), o uno construido por defecto en caso contrario.

Esta función se introdujo en Qt 6.0.

Véase también setRenderTarget().

QSGRendererInterface *QQuickWindow::rendererInterface() const

Devuelve la interfaz actual del renderizador. El valor siempre es válido y nunca es nulo.

Véase también QSGRenderNode y QSGRendererInterface.

[override virtual protected] void QQuickWindow::resizeEvent(QResizeEvent *ev)

Reimplementa: QWindow::resizeEvent(QResizeEvent *ev).

[since 6.6] QRhi *QQuickWindow::rhi() const

Devuelve el objeto QRhi utilizado por esta ventana para el renderizado.

Disponible sólo cuando la ventana utiliza la API 3D de Qt y las abstracciones del lenguaje de sombreado, lo que significa que el resultado es siempre nulo cuando se utiliza la adaptación software.

El resultado sólo es válido cuando se ha inicializado el renderizado, lo que se indica mediante la emisión de la señal sceneGraphInitialized(). Antes de ese momento, el valor devuelto es nulo. Con un QQuickWindow scenegraph regular, en pantalla, la inicialización ocurre típicamente cuando la ventana nativa se expone (se muestra) la primera vez. Cuando se utiliza QQuickRenderControl, la inicialización se realiza en la llamada explícita a initialize().

En la práctica, esta función es un atajo para consultar QRhi a través de QSGRendererInterface.

Esta función se introdujo en Qt 6.6.

[signal] void QQuickWindow::sceneGraphAboutToStop()

Esta señal se emite en el hilo de renderizado cuando el gráfico de la escena está a punto de dejar de renderizarse. Esto ocurre normalmente porque la ventana se ha ocultado.

Las aplicaciones pueden utilizar esta señal para liberar recursos, pero deben estar preparadas para reinstalarlos de nuevo rápidamente. El gráfico de escena y el contexto gráfico no se liberan en este momento.

Véase también sceneGraphInvalidated().

[static] QString QQuickWindow::sceneGraphBackend()

Devuelve el backend del scenegraph Qt Quick solicitado.

Véase también setSceneGraphBackend().

[signal] void QQuickWindow::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)

Esta señal se emite cuando se produce un error durante la inicialización del gráfico de escena.

Las aplicaciones deben conectarse a esta señal si desean gestionar errores, como fallos en la creación de contextos gráficos, de forma personalizada. Cuando no hay ninguna ranura conectada a la señal, el comportamiento será diferente: Quick imprimirá el mensaje message, o mostrará un cuadro de mensaje, y terminará la aplicación.

Esta señal será emitida desde el hilo GUI.

[signal] void QQuickWindow::sceneGraphInitialized()

Esta señal se emite cuando el gráfico de escena se ha inicializado.

Esta señal se emitirá desde el subproceso de renderizado del gráfico de escena.

[signal] void QQuickWindow::sceneGraphInvalidated()

Esta señal se emite cuando el gráfico de escena ha sido invalidado.

Esta señal implica que el contexto de renderizado gráfico utilizado ha sido invalidado y todos los recursos de usuario ligados a ese contexto deben ser liberados.

Cuando se renderiza con OpenGL, el QOpenGLContext de esta ventana estará ligado cuando se llame a esta función. La única excepción es si el OpenGL nativo ha sido destruido fuera del control de Qt, por ejemplo a través de EGL_CONTEXT_LOST.

Esta señal será emitida desde el hilo de renderizado del gráfico de escena.

void QQuickWindow::scheduleRenderJob(QRunnable *job, QQuickWindow::RenderStage stage)

Programa job para que se ejecute cuando el renderizado de esta ventana alcance el valor dado stage.

Esto es una conveniencia a las señales equivalentes en QQuickWindow para tareas "one shot".

La ventana toma posesión de job y la borrará cuando el trabajo se haya completado.

Si la renderización se detiene antes de que job tenga la oportunidad de ejecutarse, el trabajo se ejecutará y luego se borrará como parte de la limpieza del gráfico de la escena. Si la ventana nunca se muestra y no hay renderizado antes de que QQuickWindow se destruya, todos los trabajos pendientes se destruirán sin que se llame a su método run().

Si la renderización está ocurriendo en un hilo diferente, entonces el trabajo ocurrirá en el hilo de renderización.

Si stage es NoStage, job se ejecutará lo antes posible siempre que el hilo de renderizado no esté ocupado renderizando un fotograma. Si la ventana no está expuesta, y no es renderizable, en el momento en que el trabajo es publicado o manejado, el trabajo es borrado sin ejecutar el método run(). Si se está utilizando un renderizador sin hilos, el método run() del trabajo se ejecuta de forma sincrónica. Cuando se renderiza con OpenGL, el contexto OpenGL se cambia al contexto del renderizador antes de ejecutar cualquier trabajo, incluyendo los trabajos de NoStage.

Ver también beforeRendering(), afterRendering(), beforeSynchronizing(), afterSynchronizing(), frameSwapped(), y sceneGraphInvalidated().

[static] void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)

useAlpha especifica si se debe utilizar la transparencia alfa en las ventanas recién creadas.

En cualquier aplicación que espere crear ventanas translúcidas, es necesario establecer este valor a true antes de crear la primera QQuickWindow. El valor por defecto es false.

Véase también hasDefaultAlphaBuffer().

[static, since 6.0] void QQuickWindow::setGraphicsApi(QSGRendererInterface::GraphicsApi api)

Solicita los gráficos especificados api.

Cuando se utiliza la adaptación de gráficos incorporada y predeterminada, api especifica qué API de gráficos (OpenGL, Vulkan, Metal o Direct3D) debe utilizar el gráfico de escena para renderizar. Además, el backend software también está integrado y puede solicitarse estableciendo api en QSGRendererInterface::Software.

A diferencia de setSceneGraphBackend(), que sólo se puede utilizar para solicitar un backend determinado (incorporado o instalado como plugins cargados dinámicamente), esta función trabaja con el concepto de APIs gráficas de nivel superior. Cubre los backends que se suministran con Qt Quick, y por lo tanto tienen valores correspondientes en el enum QSGRendererInterface::GraphicsApi.

Cuando no se llama a esta función en absoluto, y tampoco se establece la variable de entorno equivalente QSG_RHI_BACKEND, el gráfico de escena elegirá la API gráfica a utilizar basándose en la plataforma.

Esta función adquiere importancia en aplicaciones que sólo están preparadas para renderizar con una API determinada. Por ejemplo, si la aplicación renderiza de forma nativa con OpenGL o Vulkan, querrá asegurarse de que Qt Quick renderiza también con OpenGL o Vulkan. Se espera que estas aplicaciones llamen a esta función al principio de su función main().

Para consultar qué API gráfica está utilizando el gráfico de escena para renderizar, QSGRendererInterface::graphicsApi() después del gráfico de escena has initialized, lo que suele ocurrir o bien cuando la ventana se hace visible por primera vez, o bien cuando se llama a QQuickRenderControl::initialize().

Para volver al comportamiento por defecto, donde el gráfico de escena elige una API gráfica basada en la plataforma y otras condiciones, establece api a QSGRendererInterface::Unknown.

Esta función se introdujo en Qt 6.0.

Véase también graphicsApi().

[since 6.0] void QQuickWindow::setGraphicsConfiguration(const QQuickGraphicsConfiguration &config)

Establece la configuración gráfica para esta ventana. config contiene varios ajustes que pueden ser tenidos en cuenta por el gráfico de escena al inicializar los dispositivos y contextos gráficos subyacentes.

Dicha configuración adicional, especificando por ejemplo qué extensiones de dispositivo habilitar para Vulkan, se vuelve relevante y esencial cuando se integra código de renderizado gráfico nativo que depende de ciertas extensiones. Lo mismo ocurre cuando se integra con motores 3D o VR externos, como OpenXR.

QQuickGraphicsConfiguration Las instancias son implícitamente compartidas, copiables, y pueden ser pasadas por valor.

Esta función se introdujo en Qt 6.0.

Véase también graphicsConfiguration().

[since 6.0] void QQuickWindow::setGraphicsDevice(const QQuickGraphicsDevice &device)

Establece los objetos de dispositivo gráfico para esta ventana. El scenegraph utilizará el dispositivo existente, el dispositivo físico y otros objetos especificados por device en lugar de crear nuevos.

Esta función se utiliza muy a menudo en combinación con QQuickRenderControl y setRenderTarget(), con el fin de redirigir Qt Quick renderizado en una textura.

Un QQuickGraphicsDevice construido por defecto no cambia el comportamiento por defecto de ninguna manera. Una vez que se pasa un device creado a través de una de las funciones de fábrica de QQuickGraphicsDevice, como, QQuickGraphicsDevice::fromDeviceObjects(), y el scenegraph utiliza una API de gráficos coincidente (con el ejemplo de fromDeviceObjects(), que sería Vulkan), el scenegraph utilizará los objetos de dispositivo existentes (como, el VkPhysicalDevice, VkDevice, y el índice de familia de cola de gráficos, en el caso de Vulkan) encapsulados por el QQuickGraphicsDevice. Esto permite utilizar el mismo dispositivo, y así compartir recursos, como buffers y texturas, entre Qt Quick y los motores de render nativos.

Como ejemplo, esta vez con Direct3D, se espera que el uso típico sea el siguiente:

// native graphics resources set up by a custom D3D rendering engine
ID3D11Device *device;
ID3D11DeviceContext *context;
ID3D11Texture2D *texture;
...
// now to redirect Qt Quick content into 'texture' we could do the following:
QQuickRenderControl *renderControl = new QQuickRenderControl;
QQuickWindow *window = new QQuickWindow(renderControl); // this window will never be shown on-screen
...
window->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(device, context));
renderControl->initialize();
window->setRenderTarget(QQuickRenderTarget::fromD3D11Texture(texture, textureSize);
...

El aspecto clave del uso de esta función es asegurar que los recursos o handles a recursos, como texture en el ejemplo anterior, sean visibles y utilizables tanto por el motor de renderizado externo como por el renderizador del scenegraph. Esto requiere utilizar el mismo dispositivo gráfico (o con OpenGL, el contexto OpenGL).

QQuickGraphicsDevice Las instancias son implícitamente compartidas, copiables y pueden pasarse por valor. No poseen los objetos nativos asociados (como el ID3D11Device del ejemplo).

Esta función se introdujo en Qt 6.0.

Véase también graphicsDevice(), QQuickRenderControl, setRenderTarget(), y setGraphicsApi().

void QQuickWindow::setPersistentGraphics(bool persistent)

Establece si los recursos gráficos (dispositivo gráfico o contexto, swapchain, buffers, texturas) deben ser preservados, y no pueden ser liberados hasta que la última ventana sea eliminada, a persistent. El valor por defecto es true.

Cuando se llama a releaseResources(), o cuando la ventana se oculta (más específicamente, no renderizable), algunos bucles de render tienen la posibilidad de liberar todos los recursos gráficos, no sólo los almacenados en caché. Esto puede liberar memoria temporalmente, pero también significa que el motor de renderizado tendrá que hacer una reinicialización completa y potencialmente costosa de los recursos cuando la ventana necesite ser renderizada de nuevo.

Véase también isPersistentGraphics(), setPersistentSceneGraph(), sceneGraphInitialized(), sceneGraphInvalidated() y releaseResources().

void QQuickWindow::setPersistentSceneGraph(bool persistent)

Establece si los nodos y recursos del gráfico de escena son persistent. Persistente significa que los nodos y recursos no pueden ser liberados. El valor por defecto es true.

Al llamar a releaseResources(), cuando la ventana se oculta (más específicamente, no renderizable), algunos bucles de render tienen la posibilidad de liberar los nodos del gráfico de escena y los recursos gráficos relacionados. Esto libera memoria temporalmente, pero también significará que el gráfico de escena tiene que ser reconstruido cuando la ventana se renderice la próxima vez.

Véase también isPersistentSceneGraph(), setPersistentGraphics(), sceneGraphInvalidated(), sceneGraphInitialized(), y releaseResources().

[since 6.0] void QQuickWindow::setRenderTarget(const QQuickRenderTarget &target)

Establece el objetivo de renderizado de esta ventana en target.

Un QQuickRenderTarget sirve como un manejador opaco para un objeto nativo renderizable, más comúnmente una textura 2D, y metadatos asociados, como el tamaño en píxeles.

Un QQuickRenderTarget construido por defecto significa que no hay redirección. Por otro lado, un target válido, creado a través de una de las funciones estáticas de fábrica de QQuickRenderTarget, permite redirigir el renderizado de la escena Qt Quick: ya no se dirigirá a los buffers de color de la superficie asociada a la ventana, sino a las texturas u otros objetos gráficos especificados en target.

Por ejemplo, suponiendo que el scenegraph esté utilizando Vulkan para renderizar, se puede redirigir su salida a un VkImage. Para APIs gráficas como Vulkan, también se debe proporcionar el diseño de la imagen. Las instancias de QQuickRenderTarget se comparten implícitamente, son copiables y se pueden pasar por valor. Sin embargo, no son propietarias de los objetos nativos asociados (como la VkImage del ejemplo).

QQuickRenderTarget rt = QQuickRenderTarget::fromVulkanImage(vulkanImage, VK_IMAGE_LAYOUT_PREINITIALIZED, pixelSize);
quickWindow->setRenderTarget(rt);

Esta función se utiliza muy a menudo en combinación con QQuickRenderControl y un QQuickWindow invisible, con el fin de renderizar el contenido de Qt Quick en una textura, sin crear una ventana nativa en pantalla para este QQuickWindow.

Cuando el objetivo deseado, o los datos asociados, como el tamaño, cambien, llame a esta función con un nuevo QQuickRenderTarget. Construir instancias de QQuickRenderTarget y llamar a esta función es barato, pero tenga en cuenta que establecer un nuevo target con un objeto nativo diferente u otros datos puede llevar a pasos de inicialización potencialmente caros cuando el scenegraph está a punto de renderizar el siguiente fotograma. Por lo tanto, cambie el objetivo sólo cuando sea necesario.

Esta función se introdujo en Qt 6.0.

Ver también renderTarget(), QQuickRenderControl, setGraphicsDevice(), y setGraphicsApi().

[static] void QQuickWindow::setSceneGraphBackend(const QString &backend)

Solicita un Qt Quick scenegraph backend. Los backends pueden estar incorporados o instalarse en forma de plugins cargados dinámicamente.

Consulte Cambiar entre adaptaciones en su aplicación para obtener más información sobre la lista de backends. Si backend no es válido o se produce un error, la solicitud se ignora.

Véase también sceneGraphBackend().

[static] void QQuickWindow::setTextRenderType(QQuickWindow::TextRenderType renderType)

Establece el tipo de representación por defecto de los elementos de tipo texto en Qt Quick a renderType.

Véase también textRenderType().

[override virtual protected] void QQuickWindow::showEvent(QShowEvent *)

Reimplementa: QWindow::showEvent(QShowEvent *ev).

[since 6.6] QRhiSwapChain *QQuickWindow::swapChain() const

Devuelve el QRhiSwapChain utilizado por esta ventana, si existe.

Esta función se introdujo en Qt 6.6.

[override virtual protected] void QQuickWindow::tabletEvent(QTabletEvent *event)

Reimplementa: QWindow::tabletEvent(QTabletEvent *ev).

[static] QQuickWindow::TextRenderType QQuickWindow::textRenderType()

Devuelve el tipo de representación de los elementos de tipo texto en Qt Quick. El valor por defecto es QQuickWindow::QtTextRendering.

Véase también setTextRenderType().

[slot] void QQuickWindow::update()

Programa la ventana para renderizar otro fotograma.

Llamar a QQuickWindow::update() difiere de QQuickItem::update() en que siempre desencadena un repintado, independientemente de los cambios en el gráfico de escena subyacente o no.

[override virtual protected] void QQuickWindow::wheelEvent(QWheelEvent *event)

Reimplementa: QWindow::wheelEvent(QWheelEvent *ev).