En esta página

QQuickGraphicsConfiguration Class

QQuickGraphicsConfiguration controla los ajustes gráficos de nivel inferior de QQuickWindow. Más información...

Encabezado: #include <QQuickGraphicsConfiguration>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick
Desde: Qt 6.0

Funciones públicas

QQuickGraphicsConfiguration()
~QQuickGraphicsConfiguration()
QByteArrayList deviceExtensions() const
(since 6.5) bool isAutomaticPipelineCacheEnabled() const
bool isDebugLayerEnabled() const
bool isDebugMarkersEnabled() const
bool isDepthBufferEnabledFor2D() const
QString pipelineCacheLoadFile() const
QString pipelineCacheSaveFile() const
bool prefersSoftwareDevice() const
(since 6.5) void setAutomaticPipelineCache(bool enable)
(since 6.5) void setDebugLayer(bool enable)
(since 6.5) void setDebugMarkers(bool enable)
void setDepthBufferFor2D(bool enable)
void setDeviceExtensions(const QByteArrayList &extensions)
(since 6.5) void setPipelineCacheLoadFile(const QString &filename)
(since 6.5) void setPipelineCacheSaveFile(const QString &filename)
(since 6.5) void setPreferSoftwareDevice(bool enable)
(since 6.6) void setTimestamps(bool enable)
(since 6.6) bool timestampsEnabled() const

Miembros públicos estáticos

(since 6.1) QByteArrayList preferredInstanceExtensions()

Descripción detallada

La clase `QQuickGraphicsConfiguration` es un contenedor de ajustes gráficos de bajo nivel que pueden afectar a la forma en que la API gráfica subyacente, como Vulkan, es inicializada por el grafo de escena de ` Qt Quick `. También puede controlar ciertos aspectos del renderizador del grafo de escena.

Nota: La configuración de un objeto `QQuickGraphicsConfiguration` en un ` QQuickWindow ` debe realizarse con suficiente antelación, antes de que se inicialice el grafo de escena por primera vez para esa ventana. En el caso de las ventanas en pantalla, esto significa que la llamada debe realizarse antes de invocar `show()` en ` QQuickWindow ` o ` QQuickView`. En el caso de ` QQuickRenderControl `, la configuración debe estar finalizada antes de llamar a ` initialize()`.

Configuración para motores de renderizado externos o API XR

Al crear y mostrar un « QQuickWindow » que utiliza Vulkan para el renderizado, se inicializan a través de la API de Vulkan una instancia de Vulkan (VkInstance), un dispositivo físico (VkPhysicalDevice), un dispositivo (VkDevice) y los objetos asociados (colas, grupos). Lo mismo ocurre, en gran medida, cuando se utiliza QQuickRenderControl para redirigir el renderizado a un destino de renderizado personalizado, como una textura. Aunque la construcción de QVulkanInstance queda entonces bajo el control de la aplicación, la inicialización de otros objetos gráficos se realiza de la misma manera en QQuickRenderControl::initialize() que con un QQuickWindow en pantalla.

Para la mayoría de las aplicaciones no se necesita ninguna configuración adicional, ya que Qt Quick proporciona valores predeterminados razonables para muchos ajustes gráficos de bajo nivel, como, por ejemplo, qué extensiones de dispositivo habilitar.

Sin embargo, esto no siempre será suficiente. En casos de uso avanzados, al integrar contenido directo de Vulkan u otras API gráficas, o al integrarse con un motor 3D o de realidad virtual externo, como OpenXR, la aplicación querrá especificar su propio conjunto de ajustes en lo que respecta a detalles como qué extensiones de dispositivo habilitar.

Eso es lo que permite esta clase. Permite especificar, por ejemplo, una lista de extensiones de dispositivo que luego es recogida por el grafo de escena al utilizar Vulkan, o por las API gráficas en las que el concepto sea aplicable. Cuando algunos conceptos no sean aplicables, los ajustes relacionados simplemente se ignoran.

Algunos ejemplos de funciones de esta categoría son setDeviceExtensions() y preferredInstanceExtensions(). Esta última resulta útil cuando la aplicación gestiona su propio « QVulkanInstance », que luego se asocia con el « QQuickWindow » mediante QWindow::setVulkanInstance().

Qt Quick Configuración del renderizador del grafo de escena

Otro tipo de ajustes está relacionado con el renderizador del grafo de escena. En algunos casos, las aplicaciones pueden querer controlar determinados comportamientos, como el uso del búfer de profundidad al renderizar contenido 2D. En Qt 5, estos ajustes o bien no se podían controlar en absoluto, o bien se gestionaban mediante variables de entorno. En Qt 6, QQuickGraphicsConfiguration ofrece un nuevo espacio para estos ajustes, al tiempo que mantiene la compatibilidad con las variables de entorno heredadas, cuando sea aplicable.

Un ejemplo de esta categoría es ` setDepthBufferFor2D()`.

Configuración del dispositivo gráfico

Cuando Qt crea los objetos de instancia y dispositivo gráficos (por ejemplo, VkInstance y VkDevice con Vulkan, ID3D11Device con Direct 3D, etc.) al inicializar un QQuickWindow, hay ajustes que las aplicaciones o bibliotecas querrán controlar en determinadas circunstancias.

Antes de Qt 6.5, algunos de estos ajustes se podían controlar mediante variables de entorno. Por ejemplo, ` QSG_RHI_DEBUG_LAYER ` o ` QSG_RHI_PREFER_SOFTWARE_RENDERER`. Estas siguen estando disponibles y funcionan como antes. Además, `QQuickGraphicsConfiguration` proporciona métodos de configuración en C++.

Por ejemplo, la siguiente función `main()` abre un ` QQuickView ` al tiempo que especifica que deben habilitarse la validación de Vulkan o la capa de depuración de Direct3D:

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQuickGraphicsConfiguration config;
    config.setDebugLayer(true);

    QQuickView *view = new QQuickView;
    view->setGraphicsConfiguration(config);

    view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
    view->show();
    return app.exec();
}

Guardado y carga de la caché del pipeline

Qt Quick permite almacenar en disco la caché del pipeline gráfico/computacional y volver a cargarla en ejecuciones posteriores de una aplicación. El contenido exacto de la caché del pipeline, el funcionamiento de las consultas y qué es lo que se acelera exactamente dependen del backend de Qt RHI y de la API gráfica nativa subyacente que se utilice en tiempo de ejecución. Las distintas API 3D tienen conceptos diferentes en lo que respecta a los shaders, los programas y los objetos de estado del pipeline, así como a los mecanismos de caché correspondientes. El concepto de alto nivel de caché del pipeline que aquí se presenta abstrae todo esto en el almacenamiento y la recuperación de un único blob binario desde y hacia un archivo.

Nota: Almacenar la caché en disco puede suponer mejoras, a veces significativas, en ejecuciones posteriores de la aplicación.

Cuando se encuentra el mismo programa de sombreador y/o estado de canalización que en una ejecución anterior, es probable que se omitan varias operaciones, lo que se traduce en tiempos de inicialización de sombreadores y materiales más rápidos, lo que significa que el arranque puede ser más rápido y que los retrasos y los «tirones» durante el renderizado pueden reducirse o evitarse.

Cuando se ejecuta con una API gráfica en la que la recuperación y recarga de la caché del pipeline (o de los binarios de shaders/programas) no es aplicable o no está soportada, intentar utilizar un archivo para guardar y cargar la caché no tiene ningún efecto.

Nota: En muchos casos, los datos recuperados dependen y están vinculados al controlador gráfico (y, posiblemente, a su versión exacta). Qt realiza las comprobaciones necesarias de forma automática, almacenando metadatos adicionales en el archivo de caché del pipeline. Si los datos del archivo no coinciden con el dispositivo gráfico y la versión del controlador en tiempo de ejecución, el contenido se ignorará de forma transparente para la aplicación. Por lo tanto, es seguro hacer referencia a una caché generada en otro dispositivo o con otro controlador.

Existen excepciones al problema de la dependencia del controlador, entre las que destaca Direct 3D 11, donde la «caché de pipeline» se utiliza únicamente para almacenar los resultados de la compilación en tiempo de ejecución de HLSL a DXBC y, por lo tanto, es independiente del dispositivo y del fabricante.

En algunos casos, puede resultar conveniente mejorar la primera ejecución de la aplicación «prellenando» la caché. Esto es posible si se incluye el archivo de caché guardado de una ejecución anterior y se hace referencia a él en otra máquina o dispositivo. De este modo, la aplicación o el dispositivo dispone ya, durante su primera ejecución, de los programas de sombreado o las canalizaciones que ya se habían encontrado en la ejecución en la que se guardó el archivo de caché. El envío y la implementación del archivo de caché solo tienen sentido si el dispositivo y los controladores gráficos son los mismos en el sistema de destino; de lo contrario, el archivo de caché se ignora si la versión del dispositivo o del controlador no coincide (con la excepción de D3D11), tal y como se ha descrito anteriormente.

Una vez cargado el contenido de la caché, sigue existiendo la posibilidad de que la aplicación cree pipelines gráficos y de cálculo que no se hayan encontrado en ejecuciones anteriores. En estos casos, la caché se amplía, añadiéndose a ella los pipelines y programas de sombreado. Si la aplicación también opta por guardar el contenido (quizá incluso en el mismo archivo), se almacenarán tanto los flujos de trabajo antiguos como los nuevos. Cargar desde el mismo archivo y guardar en él en cada ejecución permite disponer de una caché en constante crecimiento que almacena todos los flujos de trabajo y programas de sombreado encontrados.

En la práctica, cabe esperar que la caché de pipelines de Qt se corresponda con las siguientes características de la API gráfica nativa:

  • Vulkan - VkPipelineCache - Al guardar la caché de pipelines, se almacena efectivamente el blob obtenido mediante vkGetPipelineCacheData, junto con metadatos adicionales para identificar de forma segura el dispositivo y el controlador, ya que el blob de la caché de pipelines depende del controlador concreto.
  • Metal - MTLBinaryArchive - Con el guardado de la caché de pipelines activado, Qt almacena todas las pipelines de renderizado y computación encontradas en un MTLBinaryArchive. Al guardar la caché de pipelines, se almacena el blob obtenido de MTLBinaryArchive, junto con metadatos adicionales para identificar el dispositivo. Nota: actualmente, el uso de MTLBinaryArchive está desactivado en macOS e iOS debido a diversos problemas en algunos tipos de hardware y versiones del sistema operativo.
  • OpenGL: no existe un concepto nativo de pipelines; la «caché de pipeline» almacena una colección de binarios de programa recuperados mediante glGetProgramBinary. Los binarios de programa se empaquetan en un único blob, con metadatos adicionales para identificar el dispositivo, el controlador y la versión de este desde la que se recuperaron los binarios. El almacenamiento en caché persistente de los binarios de programa no es una novedad en Qt: Qt 5 ya contaba con una funcionalidad similar en QOpenGLShaderProgram; véase, por ejemplo, addCacheableShaderFromSourceCode(). De hecho, ese mecanismo también está siempre activo en Qt 6 cuando se utiliza Qt Quick con OpenGL. Sin embargo, al utilizar la nueva abstracción de caché de canalización independiente de la API gráfica que se proporciona aquí, la caché de binarios de programa de la era de Qt 5 se desactiva automáticamente, ya que ahora el mismo contenido se agrupa en la «caché de canalización».
  • Direct 3D 11: no existe un concepto nativo de «pipelines» ni de recuperación de binarios para la segunda fase de compilación (en la que el bytecode intermedio, independiente del proveedor, se compila en el conjunto de instrucciones específico del dispositivo). Los controladores suelen emplear su propio sistema de almacenamiento en caché a ese nivel. En su lugar, se utiliza la «caché de pipeline» de Qt Quick para acelerar aquellos casos en los que los shaders contienen código fuente HLSL que debe compilarse primero al formato de bytecode intermedio. Esto puede suponer mejoras significativas de rendimiento en aplicaciones y bibliotecas que generan código de shader en tiempo de ejecución, ya que en ejecuciones posteriores se pueden evitar las llamadas a D3DCompile(), potencialmente costosas y no almacenadas en caché, si el bytecode ya está disponible para el shader HLSL encontrado. Un buen ejemplo es Qt Quick 3D, donde los shaders generados en tiempo de ejecución para los materiales implican tener que gestionar código fuente HLSL. Guardar y recargar la caché de canalización de Qt Quick puede, por lo tanto, aportar mejoras considerables en escenas que contengan uno o más elementos de View3D. Un contraejemplo podría ser el propio « Qt Quick »: dado que la mayoría de los shaders integrados para contenido 2D se suministran con bytecode de DirectX generado en el momento de la compilación, la caché no va a aportar ninguna mejora significativa.

Todo esto es independiente del procesamiento de sombreadores realizado por el módulo Qt Shader Tools y sus herramientas de línea de comandos, como qsb. Tomemos como ejemplo Vulkan. Es recomendable compilar el código fuente GLSL compatible con Vulkan a SPIR-V, ya sea de forma offline o en el momento de la compilación (directamente a través de qsb o CMake), ya que así se evita la costosa compilación a partir del código fuente en tiempo de ejecución. Sin embargo, SPIR-V es un formato intermedio independiente del proveedor. En tiempo de ejecución, al construir canalizaciones gráficas o de cálculo, es probable que se produzca otra ronda de compilación, esta vez del formato intermedio al conjunto de instrucciones específico del fabricante de la GPU (y esto puede depender también de cierto estado de la canalización gráfica y de los objetivos de renderizado). La caché de la canalización ayuda en esta última fase.

Nota: Muchas implementaciones de API gráficas emplean su propia caché de disco persistente de forma transparente para las aplicaciones. El uso de la función de caché de canalización de Qt Quick probablemente proporcionará mejoras en este caso, pero las ventajas podrían ser menores.

Llama a ` setPipelineCacheSaveFile()` y a ` setPipelineCacheLoadFile()` para controlar en qué archivos guarda y carga la caché de la canalización un ` QQuickWindow ` o un ` QQuickView `.

Para hacerse una idea de los efectos de habilitar el almacenamiento en disco de la caché de la canalización, active los registros más importantes del grafo de escena y de gráficos, ya sea a través de la variable de entorno QSG_INFO=1, o bien mediante las categorías de registro qt.scenegraph.general y qt.rhi.general. Al cerrar el QQuickWindow, aparecerá un mensaje de registro similar al siguiente:

Total time spent on pipeline creation during the lifetime of the QRhi was 123 ms

Esto ofrece una idea aproximada del tiempo dedicado a la creación de gráficos y del canal de procesamiento (que puede incluir diversas etapas de compilación de sombreadores) durante el tiempo de vida de la ventana.

Cuando está habilitada la carga desde un archivo de caché de canalización, esto se confirma con un mensaje:

Attempting to seed pipeline cache from 'filename'

Del mismo modo, para comprobar si el guardado de la caché se ha habilitado correctamente, busca un mensaje como este:

Writing pipeline cache contents to 'filename'

La caché automática de canalizaciones

Cuando no se proporciona ningún nombre de archivo para guardar y cargar, se utiliza la estrategia de caché automática de canalizaciones. Esto implica almacenar los datos en la ubicación de caché específica de la aplicación del sistema (QStandardPaths::CacheLocation).

Esto se puede desactivar de una de las siguientes formas:

  • Establecer el atributo de aplicación Qt::AA_DisableShaderDiskCache. (desactiva por completo el almacenamiento automático)
  • Establecer la variable de entorno QT_DISABLE_SHADER_DISK_CACHE en un valor distinto de cero. (desactiva por completo el almacenamiento automático)
  • Establecer la variable de entorno QSG_RHI_DISABLE_SHADER_DISK_CACHE en un valor distinto de cero. (desactiva completamente el almacenamiento automático)
  • Llama a setAutomaticPiplineCache() con el argumento «enable» establecido en «false». (desactiva por completo el almacenamiento automático)
  • Establece un nombre de archivo llamando a ` setPipelineCacheLoadFile()`. (solo desactiva la carga desde el almacenamiento automático, dando prioridad al archivo especificado)
  • Establece un nombre de archivo llamando a ` setPipelineCacheSaveFile()`. (solo desactiva la escritura en el almacenamiento automático, dando preferencia al archivo especificado)

Los dos primeros son mecanismos ya existentes que se utilizan desde Qt 5.9 para controlar la caché binaria del programa OpenGL. Por motivos de compatibilidad y familiaridad, se admiten el mismo atributo y la misma variable de entorno para la caché de pipeline mejorada de Qt 6.

La caché automática de pipeline utiliza un único archivo por aplicación, pero uno diferente para cada backend RHI (API gráfica). Esto significa que cambiar a otra API gráfica en la siguiente ejecución de la aplicación no supondrá la pérdida de la caché de pipeline generada en la ejecución anterior. Sin embargo, es posible que las aplicaciones con varias instancias de « QQuickWindow » mostradas simultáneamente no se beneficien al 100 %, ya que la caché automática solo puede almacenar los datos recopilados de un objeto RHI a la vez. (Y con el bucle de renderizado predeterminado threaded, cada ventana tiene su propio RHI, ya que el renderizado se realiza de forma independiente en subprocesos dedicados). Para aprovechar al máximo la caché de disco en aplicaciones con varias ventanas, es recomendable establecer el nombre de archivo de forma explícita, por ventana, mediante ` setPipelineCacheSaveFile()` ().

Véase también QQuickWindow::setGraphicsConfiguration(), QQuickWindow y QQuickRenderControl.

Documentación de las funciones de miembro

QQuickGraphicsConfiguration::QQuickGraphicsConfiguration()

Crea una instancia predeterminada de `QQuickGraphicsConfiguration` que no especifica ninguna configuración adicional que el grafo de escena deba tener en cuenta.

[noexcept] QQuickGraphicsConfiguration::~QQuickGraphicsConfiguration()

Destructor.

QByteArrayList QQuickGraphicsConfiguration::deviceExtensions() const

Devuelve la lista de las extensiones adicionales del dispositivo solicitadas.

Véase también setDeviceExtensions().

[since 6.5] bool QQuickGraphicsConfiguration::isAutomaticPipelineCacheEnabled() const

Devuelve «true» si la caché automática del pipeline está activada.

Por defecto, el valor es «true», a menos que se hayan configurado determinados atributos de la aplicación o variables de entorno. Para obtener más información, consulta The Automatic Pipeline Cache.

Esta función se introdujo en Qt 6.5.

Véase también setAutomaticPipelineCache().

bool QQuickGraphicsConfiguration::isDebugLayerEnabled() const

Devuelve «true» si se deben habilitar las capas de depuración y validación.

Por defecto, el valor es false.

Véase también setDebugLayer().

bool QQuickGraphicsConfiguration::isDebugMarkersEnabled() const

Devuelve «true» si los marcadores de depuración están activados.

Por defecto, el valor es false.

Véase también setDebugMarkers().

bool QQuickGraphicsConfiguration::isDepthBufferEnabledFor2D() const

Devuelve «true» si está habilitado el uso del búfer de profundidad para contenido 2D.

Por defecto, el valor es «true», a menos que se haya establecido la variable de entorno « QSG_NO_DEPTH_BUFFER ».

QString QQuickGraphicsConfiguration::pipelineCacheLoadFile() const

Devuelve el nombre de archivo establecido actualmente para cargar la caché del pipeline.

Por defecto, el valor es una cadena vacía.

Véase también setPipelineCacheLoadFile().

QString QQuickGraphicsConfiguration::pipelineCacheSaveFile() const

Devuelve el nombre de archivo establecido actualmente para almacenar la caché del pipeline.

Por defecto, el valor es una cadena vacía.

Véase también setPipelineCacheSaveFile().

[static, since 6.1] QByteArrayList QQuickGraphicsConfiguration::preferredInstanceExtensions()

Devuelve la lista de extensiones de instancia de Vulkan que Qt Quick prefiere tener activadas en la VkInstance.

En la mayoría de los casos, Qt Quick se encarga de crear un ` QVulkanInstance`. En ese caso, esta función no es relevante. Por otro lado, cuando se utiliza QQuickRenderControl en combinación con el renderizado basado en Vulkan, es responsabilidad de la aplicación crear un QVulkanInstance y asociarlo con el QQuickWindow(fuera de pantalla). En este caso, se espera que la aplicación consulte la lista de extensiones de instancia que se deben habilitar y las pase a QVulkanInstance::setExtensions() antes de llamar a QVulkanInstance::create().

Esta función se introdujo en Qt 6.1.

bool QQuickGraphicsConfiguration::prefersSoftwareDevice() const

Devuelve «true» si se da prioridad a un dispositivo gráfico basado en un rasterizador de software.

Por defecto, el valor es «false».

Véase también ` setPreferSoftwareDevice()`.

[since 6.5] void QQuickGraphicsConfiguration::setAutomaticPipelineCache(bool enable)

Modifica el uso de la caché automática del pipeline según lo descrito en enable.

El valor por defecto es «true», a menos que se hayan establecido determinados atributos de la aplicación o variables de entorno. Consulte The Automatic Pipeline Cache para obtener más información.

Esta función se introdujo en Qt 6.5.

Véase también isAutomaticPipelineCacheEnabled().

[since 6.5] void QQuickGraphicsConfiguration::setDebugLayer(bool enable)

Habilita las capas de depuración o validación de la implementación de la API gráfica, si están disponibles.

En la práctica, esto es compatible con Vulkan y Direct 3D 11, siempre que el soporte necesario (capas de validación, SDK de Windows) esté instalado y disponible en tiempo de ejecución. Cuando enable es verdadero, Qt intentará habilitar la capa de validación estándar en la VkInstance o establecerá D3D11_CREATE_DEVICE_DEBUG en el dispositivo gráfico.

Para Metal en macOS, configura la variable de entorno METAL_DEVICE_WRAPPER_TYPE=1 antes de iniciar la aplicación.

Llamar a esta función con enable establecido en true equivale a establecer la variable de entorno QSG_RHI_DEBUG_LAYER en un valor distinto de cero.

El valor por defecto es «false».

Nota: Habilitar las capas de depuración o validación puede tener un impacto no desdeñable en el rendimiento. Se desaconseja encarecidamente lanzar aplicaciones a producción con este indicador activado.

Nota: Ten en cuenta que, debido a las diferencias en el diseño de las API gráficas subyacentes, esta configuración no siempre puede ser específica de cada `QQuickWindow `, aunque cada ` QQuickWindow ` tenga su propio ` QQuickGraphicsConfiguration`. En el caso concreto de Vulkan, el objeto de instancia (VkInstance) solo se crea una vez y luego lo utilizan todas las ventanas de la aplicación. Por lo tanto, habilitar la capa de validación es algo que afecta a todas las ventanas. Esto también significa que intentar habilitar la validación a través de una ventana que solo se muestra después de que otras ventanas ya hayan comenzado a renderizarse no tiene ningún efecto con Vulkan. Otras API, como D3D11, exponen el concepto de capa de depuración como una configuración por dispositivo (ID3D11Device), por lo que se controla realmente por ventana (suponiendo que el bucle de renderizado del grafo de escena utilice un dispositivo o contexto gráfico dedicado para cada QQuickWindow).

Esta función se introdujo en Qt 6.5.

Véase también isDebugLayerEnabled().

[since 6.5] void QQuickGraphicsConfiguration::setDebugMarkers(bool enable)

Cuando procede, « enable » controla la inserción de marcadores de depuración y nombres de objetos en el flujo de comandos gráficos.

Algunos marcos de trabajo, como Qt Quick 3D, tienen la capacidad de anotar los objetos gráficos que crean (búferes, texturas) con nombres y también de indicar el inicio y el final de las pasadas de renderizado en el búfer de comandos. Estos datos quedan visibles en las capturas de fotogramas realizadas con herramientas como RenderDoc o XCode.

Las API gráficas en las que cabe esperar que esto sea compatible son Vulkan (si está disponible VK_EXT_debug_utils), Direct 3D 11 y Metal.

Llamar a esta función con ` enable ` establecido en `true` equivale a establecer la variable de entorno ` QSG_RHI_PROFILE ` en un valor distinto de cero.

El valor por defecto es «false».

Nota: Habilitar los marcadores de depuración puede afectar al rendimiento. No se recomienda lanzar aplicaciones a producción con este indicador activado.

Esta función se introdujo en Qt 6.5.

Véase también isDebugMarkersEnabled().

void QQuickGraphicsConfiguration::setDepthBufferFor2D(bool enable)

Establece el uso del búfer de profundidad para el contenido 2D en « enable ». Cuando está desactivado, el grafo de escena « Qt Quick » nunca escribe en el búfer de profundidad.

Por defecto, el valor es «true», a menos que se haya establecido la variable de entorno « QSG_NO_DEPTH_BUFFER ».

El valor por defecto «true» es la configuración más óptima para la gran mayoría de las escenas. Desactivar el uso del búfer de profundidad reduce la eficiencia del procesamiento por lotes del grafo de escena.

Sin embargo, hay casos en los que permitir que el contenido 2D escriba en el búfer de profundidad no es lo ideal. Imagina una escena 3D como una «superposición» sobre la escena 2D, renderizada mediante Qt Quick 3D utilizando un View3D con renderMode establecido en Overlay. En este caso, que el búfer de profundidad se llene con contenido 2D puede provocar resultados inesperados. Esto se debe a que la forma en que el renderizador del grafo de escena 2D genera y gestiona los valores de profundidad no es necesariamente compatible con el funcionamiento de una escena 3D. Esto puede dar lugar a conflictos en los valores de profundidad, colisiones y fallos inesperados en las pruebas de profundidad. Por lo tanto, el enfoque más seguro en este caso es llamar a esta función con enable establecido en false y desactivar las escrituras en el búfer de profundidad para el contenido 2D en QQuickWindow.

Nota: Este indicador no es totalmente idéntico a la configuración de la variable de entorno « QSG_NO_DEPTH_BUFFER ». Este indicador no controla la presencia de los búferes de profundidad y estencil. Es más bien relevante para el proceso de renderizado. Para forzar que no haya ningún anexo de profundidad/estencil, configura « QSG_NO_DEPTH_BUFFER » y « QSG_NO_STENCIL_BUFFER ». Sin embargo, ten en cuenta que dicho ` QQuickWindow`, y cualquier capa de elementos que contenga, puede volverse incompatible con elementos como ` View3D ` en determinados modos de funcionamiento, ya que el contenido 3D requiere un búfer de profundidad. Llamar a esta función siempre es seguro, pero puede suponer que se creen recursos, como los búferes de profundidad, aunque no se utilicen de forma activa.

void QQuickGraphicsConfiguration::setDeviceExtensions(const QByteArrayList &extensions)

Establece la lista de funciones de « extensions » adicionales que se deben habilitar en el dispositivo gráfico (como, por ejemplo, « VkDevice »).

Al renderizar con una API gráfica en la que este concepto no sea aplicable, « extensions » se ignorará.

Nota: La lista especifica extensiones adicionales. Qt Quick siempre habilita las extensiones que requiere el grafo de escena.

Véase también deviceExtensions().

[since 6.5] void QQuickGraphicsConfiguration::setPipelineCacheLoadFile(const QString &filename)

Establece la dirección filename desde la que se espera que el QQuickWindow cargue el contenido inicial de la caché de su canal de procesamiento gráfico/computacional. El valor por defecto está vacío, lo que significa que la carga de la caché del canal está desactivada.

Consulte Pipeline Cache Save and Load para obtener más información sobre las cachés de canalización.

El almacenamiento persistente de la caché del canal puede suponer una mejora del rendimiento en futuras ejecuciones de la aplicación, ya que permite evitar los costosos pasos de compilación de shaders y construcción del canal.

No está definido si se cargará el contenido del archivo ni cuándo se hará, salvo que ocurrirá en algún momento durante la inicialización del grafo de escena de QQuickWindow. Por lo tanto, el archivo debe seguir existiendo tras llamar a esta función. QQuickGraphicsConfiguration solo almacena el nombre del archivo; no puede realizar por sí misma ninguna operación real de E/S ni de gráficos. El trabajo real se llevará a cabo más adelante, posiblemente en otro hilo.

Cuando se ejecuta con una API gráfica en la que la recuperación y recarga de la caché del pipeline (o de los binarios de shaders/programas) no es aplicable o no está soportada, llamar a esta función no tiene ningún efecto.

La llamada a esta función equivale, en gran medida, a establecer la variable de entorno ` QSG_RHI_PIPELINE_CACHE_LOAD ` en ` filename`, con una diferencia importante: esta función controla el almacenamiento de la caché del pipeline únicamente para el ` QQuickWindow ` asociado. Por lo tanto, las aplicaciones con múltiples instancias de ` QQuickWindow ` o ` QQuickView ` pueden almacenar y recargar posteriormente el contenido de la caché a través de archivos dedicados a cada ventana. La variable de entorno no permite esto.

Nota: Si los datos del archivo no coinciden con el dispositivo gráfico y la versión del controlador en tiempo de ejecución, el contenido se ignorará, de forma transparente para la aplicación. Esto se aplica a varias API gráficas, y Qt se encarga de realizar las comprobaciones necesarias. Existen excepciones, entre las que destaca Direct 3D 11, donde la «caché de canalización» se utiliza únicamente para almacenar los resultados de la compilación en tiempo de ejecución de HLSL a DXBC y, por lo tanto, es independiente del dispositivo y del proveedor.

Advertencia: Se da por supuesto quelos datos serializados de la caché de pipeline son de confianza. Se recomienda a los desarrolladores de aplicaciones que nunca pasen datos procedentes de fuentes no fiables.

Esta función se introdujo en Qt 6.5.

Véase también pipelineCacheLoadFile() y setPipelineCacheSaveFile().

[since 6.5] void QQuickGraphicsConfiguration::setPipelineCacheSaveFile(const QString &filename)

Establece la dirección de la caché de canalización ( filename ) en la que se espera que el motor de renderizado ( QQuickWindow ) almacene el contenido de la caché de la canalización gráfica y de cálculo. El valor por defecto está vacío, lo que significa que la carga de la caché de canalización está desactivada.

Consulte Pipeline Cache Save and Load para obtener más información sobre las cachés de canalización.

El almacenamiento persistente de la caché del canal puede suponer mejoras de rendimiento en futuras ejecuciones de la aplicación, ya que se pueden evitar los costosos pasos de compilación de shaders y construcción del canal.

No está definido si se producirá la escritura del archivo ni cuándo. Probablemente tendrá lugar en algún momento durante el desmontaje del grafo de escena debido al cierre de la ventana. Por lo tanto, las aplicaciones no deben dar por sentada la disponibilidad del archivo hasta que el objeto « QQuickWindow » se haya desmontado por completo. « QQuickGraphicsConfiguration » solo almacena el nombre del archivo; no realiza por sí mismo ninguna operación real de E/S ni de gráficos.

Cuando se ejecuta con una API gráfica en la que la recuperación de la caché del pipeline (o de los binarios de shaders/programas) no es aplicable o no está soportada, llamar a esta función no tiene ningún efecto.

La llamada a esta función equivale, en gran medida, a establecer la variable de entorno QSG_RHI_PIPELINE_CACHE_SAVE en filename, con una diferencia importante: esta función controla el almacenamiento de la caché del pipeline únicamente para el QQuickWindow asociado. Por lo tanto, las aplicaciones con múltiples instancias de QQuickWindow o QQuickView pueden almacenar y recargar posteriormente el contenido de la caché a través de archivos dedicados a cada ventana. La variable de entorno no permite esto.

Esta función se introdujo en Qt 6.5.

Véase también pipelineCacheLoadFile() y pipelineCacheSaveFile().

[since 6.5] void QQuickGraphicsConfiguration::setPreferSoftwareDevice(bool enable)

Solicita que se elija un adaptador o un dispositivo físico que utilice rasterización basada en software. Solo es aplicable cuando la API subyacente admite la enumeración de adaptadores (por ejemplo, Direct 3D o Vulkan); en caso contrario, se ignora.

Si la implementación de la API gráfica no dispone de dicho adaptador gráfico o dispositivo físico, la solicitud se ignora. Con Direct 3D cabe esperar que siempre haya disponible un rasterizador basado en WARP. Con Vulkan, el indicador solo surte efecto si está disponible el lavapipe de Mesa, o algún otro dispositivo físico que informe de VK_PHYSICAL_DEVICE_TYPE_CPU.

Llamar a esta función con enable establecido en true equivale a establecer la variable de entorno QSG_RHI_PREFER_SOFTWARE_RENDERER en un valor distinto de cero.

El valor por defecto es «false».

Esta función se introdujo en Qt 6.5.

Véase también prefersSoftwareDevice().

[since 6.6] void QQuickGraphicsConfiguration::setTimestamps(bool enable)

Cuando está habilitado, se recopilan datos de sincronización de la GPU a partir de los búferes de comandos en aquellas plataformas y API 3D que lo admitan. A continuación, estos datos se registran en los registros del renderizador, que pueden habilitarse mediante la variable de entorno ` QSG_RENDER_TIMING ` o categorías de registro como ` qt.scenegraph.time.renderloop`, y también pueden hacerse visibles para otros módulos, como el elemento ` DebugView ` de ` Qt Quick 3D`.

Por defecto, esta función está desactivada, ya que la recopilación de datos puede implicar trabajo adicional, como la inserción de consultas de marca de tiempo en el flujo de comandos, dependiendo de la API gráfica subyacente. Para activarla, llame a esta función con ` enable ` establecido en `true`, o bien establezca la variable de entorno ` QSG_RHI_PROFILE ` en un valor distinto de cero.

Las API gráficas en las que cabe esperar que esto sea compatible son Direct 3D 11, Direct 3D 12, Vulkan (siempre que la implementación subyacente de Vulkan admita consultas de marcas de tiempo), Metal y OpenGL con un contexto de perfil básico o de compatibilidad para la versión 3.3 o posterior. Las marcas de tiempo no son compatibles con OpenGL ES.

Esta función se introdujo en Qt 6.6.

Véase también timestampsEnabled() y setDebugMarkers().

[since 6.6] bool QQuickGraphicsConfiguration::timestampsEnabled() const

Devuelve «true» si está habilitada la recopilación de datos de rendimiento de la GPU.

Por defecto, el valor es «false».

Esta función se introdujo en Qt 6.6.

Véase también setTimestamps().

© 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.