QQuickGraphicsConfiguration Class

Description détaillée

La classe QQuickGraphicsConfiguration est un conteneur pour les paramètres graphiques de bas niveau qui peuvent affecter la façon dont l'API graphique sous-jacente, telle que Vulkan, est initialisée par le graphe de scène Qt Quick. Elle peut également contrôler certains aspects du moteur de rendu du graphe de scène.

Configuration pour les moteurs de rendu externes ou les API XR

Lors de la construction et de la présentation d'un site QQuickWindow qui utilise Vulkan pour le rendu, une instance Vulkan (VkInstance), un périphérique physique (VkPhysicalDevice), un périphérique (VkDevice) et les objets associés (files d'attente, pools) sont initialisés par l'intermédiaire de l'API Vulkan. Il en va de même lorsque l'on utilise QQuickRenderControl pour rediriger le rendu vers une cible de rendu personnalisée, telle qu'une texture. Alors que la construction de QVulkanInstance est sous le contrôle de l'application, l'initialisation d'autres objets graphiques se produit de la même manière dans QQuickRenderControl::initialize() qu'avec une QQuickWindow à l'écran.

Pour la majorité des applications, aucune configuration supplémentaire n'est nécessaire car Qt Quick fournit des valeurs par défaut raisonnables pour de nombreux paramètres graphiques de bas niveau, par exemple les extensions de périphériques à activer.

Cependant, cela ne sera pas toujours suffisant. Dans les cas d'utilisation avancés, lors de l'intégration directe de Vulkan ou d'autres contenus d'API graphiques, ou lors de l'intégration avec un moteur 3D ou VR externe, comme OpenXR, l'application voudra spécifier son propre ensemble de paramètres lorsqu'il s'agit de détails, tels que les extensions de périphériques à activer.

C'est ce que permet cette classe. Elle permet de spécifier, par exemple, une liste d'extensions de périphériques qui est ensuite reprise par le graphe de scène lors de l'utilisation de Vulkan ou d'API graphiques lorsque le concept est applicable. Lorsque certains concepts ne sont pas applicables, les paramètres correspondants sont simplement ignorés.

Des exemples de fonctions dans cette catégorie sont setDeviceExtensions() et preferredInstanceExtensions(). Cette dernière est utile lorsque l'application gère son propre QVulkanInstance qui est ensuite associé au QQuickWindow via QWindow::setVulkanInstance().

Qt Quick Configuration du moteur de rendu du graphe de scène

Une autre catégorie de paramètres est liée au moteur de rendu du graphe de scène. Dans certains cas, les applications peuvent vouloir contrôler un certain comportement, comme l'utilisation du tampon de profondeur lors du rendu d'un contenu 2D. Dans Qt 5, ces paramètres n'étaient pas contrôlables du tout ou étaient gérés par des variables d'environnement. Dans Qt 6, QQuickGraphicsConfiguration fournit un nouvel emplacement pour ces paramètres, tout en conservant la prise en charge des anciennes variables d'environnement, le cas échéant.

Un exemple dans cette catégorie est setDepthBufferFor2D().

Configuration des périphériques graphiques

Lorsque les objets instance graphique et périphérique (par exemple, les objets VkInstance et VkDevice avec Vulkan, ID3D11Device avec Direct 3D, etc.) sont créés par Qt lors de l'initialisation d'un site QQuickWindow, il existe des paramètres que les applications ou les bibliothèques voudront contrôler dans certaines circonstances.

Avant Qt 6.5, certains de ces paramètres pouvaient être contrôlés par des variables d'environnement. Par exemple, QSG_RHI_DEBUG_LAYER ou QSG_RHI_PREFER_SOFTWARE_RENDERER sont toujours disponibles et continuent à fonctionner comme avant. QQuickGraphicsConfiguration fournit en outre des paramètres C++.

Par exemple, la fonction main() suivante ouvre une page QQuickView tout en spécifiant que la validation Vulkan ou la couche de débogage Direct3D doit être activée :

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();
}

Sauvegarde et chargement du cache du pipeline

Qt Quick prend en charge le stockage du cache du pipeline graphique/de calcul sur le disque et son rechargement lors des exécutions ultérieures d'une application. Le contenu exact du cache du pipeline, la manière dont les consultations fonctionnent et ce qui est accéléré dépendent tous du backend Qt RHI et de l'API graphique native sous-jacente utilisée au moment de l'exécution. Les différentes API 3D ont des concepts différents en ce qui concerne les shaders, les programmes et les objets d'état de pipeline, ainsi que les mécanismes de cache correspondants. Le concept de cache de haut niveau du pipeline fait abstraction de tout cela pour stocker et récupérer un seul blob binaire dans un fichier.

Lorsque le même programme de shader et/ou le même état de pipeline est rencontré lors d'une exécution précédente, un certain nombre d'opérations sont probablement ignorées, ce qui permet d'accélérer les temps d'initialisation des shaders et des matériaux, ce qui signifie que le démarrage peut devenir plus rapide et que les décalages et les "janks" pendant le rendu peuvent être réduits ou évités.

Si vous utilisez une API graphique dans laquelle la récupération et le rechargement du cache du pipeline (ou des binaires de shaders/programmes) ne sont pas applicables ou ne sont pas pris en charge, la tentative d'utilisation d'un fichier pour enregistrer et charger le cache n'a pas d'effet.

Il existe des exceptions au problème de dépendance vis-à-vis du pilote, notamment Direct 3D 11, où le "pipeline cache" n'est utilisé que pour stocker les résultats de la compilation HLSL->DXBC au moment de l'exécution et est donc indépendant du périphérique et du fournisseur.

Dans certains cas, il peut être souhaitable d'améliorer la toute première exécution de l'application en "pré-ensemençant" le cache. Cela est possible en expédiant le fichier de cache sauvegardé lors d'une exécution précédente et en le référençant sur une autre machine ou un autre appareil. De cette manière, l'application ou le périphérique dispose des programmes/pipelines de shaders qui ont été rencontrés auparavant lors de l'exécution qui a sauvegardé le fichier de cache, et ce dès sa première exécution. L'envoi et le déploiement du fichier cache n'ont de sens que si le périphérique et les pilotes graphiques sont les mêmes sur le système cible, sinon le fichier cache est ignoré si la version du périphérique ou du pilote ne correspond pas (à l'exception de D3D11), comme décrit ci-dessus.

Une fois le contenu du cache chargé, il est toujours possible que l'application construise des pipelines graphiques et de calcul qui n'ont pas été rencontrés lors des exécutions précédentes. Dans ce cas, le cache est agrandi et les pipelines/programmes de shaders y sont ajoutés. Si l'application choisit également de sauvegarder le contenu (peut-être même dans le même fichier), les anciens et les nouveaux pipelines seront stockés. Le fait de charger et de sauvegarder dans le même fichier à chaque exécution permet d'avoir un cache toujours plus grand qui stocke tous les pipelines et programmes de shaders rencontrés.

En pratique, on peut s'attendre à ce que le cache de pipeline de Qt corresponde aux fonctionnalités des API graphiques natives suivantes :

• Vulkan - VkPipelineCache - L'enregistrement du cache de pipeline stocke effectivement le blob récupéré à partir de vkGetPipelineCacheData, avec des métadonnées supplémentaires pour identifier en toute sécurité le périphérique et le pilote puisque le blob du cache de pipeline dépend du pilote exact.
• Metal - MTLBinaryArchive - Lorsque la sauvegarde du cache de pipeline est activée, Qt stocke tous les pipelines de rendu et de calcul rencontrés dans un MTLBinaryArchive. La sauvegarde du cache de pipeline stocke le blob récupéré dans l'archive, avec des métadonnées supplémentaires pour identifier le périphérique. Note : actuellement, l'utilisation de MTLBinaryArchive est désactivée sur macOS et iOS en raison de divers problèmes sur certains matériels et versions de systèmes d'exploitation.
• OpenGL - Il n'y a pas de concept natif de pipeline, le "pipeline cache" stocke une collection de programmes binaires récupérés via glGetProgramBinary. Les binaires de programme sont empaquetés dans un seul blob, avec des métadonnées supplémentaires pour identifier le périphérique, le pilote, et sa version à partir de laquelle les binaires ont été récupérés. La mise en cache permanente des programmes binaires n'est pas une nouveauté dans Qt : Qt 5 disposait déjà d'une fonctionnalité similaire dans QOpenGLShaderProgram, voir addCacheableShaderFromSourceCode() par exemple. En fait, ce mécanisme est toujours actif dans Qt 6 lorsque l'on utilise Qt Quick avec OpenGL. Cependant, lors de l'utilisation de la nouvelle abstraction de cache de pipeline indépendante de l'API graphique fournie ici, le cache binaire du programme de l'ère Qt 5 est automatiquement désactivé, puisque le même contenu est désormais emballé dans le "cache de pipeline".
• Direct 3D 11 - Il n'y a pas de concept natif de pipeline ou de récupération de binaires pour la deuxième phase de compilation (où le bytecode intermédiaire indépendant du fournisseur est compilé dans le jeu d'instructions spécifique au périphérique). Les pilotes emploient généralement leur propre système de cache à ce niveau. En revanche, le "pipeline cache" de Qt Quick est utilisé pour accélérer les cas où les shaders contiennent du code source HLSL qui doit d'abord être compilé dans le format de bytecode intermédiaire. Cela peut améliorer considérablement les performances des applications et des bibliothèques qui composent le code des nuanceurs au moment de l'exécution, car lors des exécutions suivantes, les appels potentiellement coûteux et non mis en cache à D3DCompile() peuvent être évités si le bytecode est déjà disponible pour le nuanceur HLSL rencontré. Un bon exemple est Qt Quick 3D, où les shaders générés en cours d'exécution pour les matériaux impliquent d'avoir à traiter le code source HLSL. Sauvegarder et recharger le cache du pipeline Qt Quick peut donc apporter des améliorations considérables dans les scènes contenant un ou plusieurs éléments View3D. Un contre-exemple peut être Qt Quick lui-même : comme la plupart des shaders intégrés pour le contenu 2D sont livrés avec le bytecode DirectX généré au moment de la construction, le cache ne va pas apporter d'améliorations significatives.

Tout cela est indépendant du traitement des shaders effectué par le module Qt Shader Tools et ses outils en ligne de commande tels que qsb. Prenons l'exemple de Vulkan. Le fait que le code source GLSL compatible avec Vulkan soit compilé dans SPIR-V soit hors ligne, soit au moment de la compilation (directement via qsb ou CMake) est une bonne chose, car la compilation coûteuse à partir de la forme source est évitée au moment de l'exécution. SPIR-V est cependant un format intermédiaire indépendant du fournisseur. Au moment de l'exécution, lors de la construction de pipelines graphiques ou de calcul, il est probable qu'un autre cycle de compilation se produise, cette fois du format intermédiaire au jeu d'instructions spécifique au fournisseur du GPU (et cela peut également dépendre de certains états dans le pipeline graphique et les cibles de rendu). Le cache du pipeline contribue à cette dernière phase.

Appelez setPipelineCacheSaveFile() et setPipelineCacheLoadFile() pour contrôler les fichiers dans lesquels QQuickWindow ou QQuickView enregistre et charge le cache pipeline.

Pour avoir une idée des effets de l'activation du stockage sur disque du cache du pipeline, activez les journaux de scènes et de graphiques les plus importants via la variable d'environnement QSG_INFO=1 ou les catégories de journaux qt.scenegraph.general et qt.rhi.general. Lorsque vous fermez le site QQuickWindow, un message de journalisation s'affiche comme suit :

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

Cela donne une idée approximative du temps passé à créer des graphiques et des pipelines de calcul (ce qui peut inclure différentes étapes de la compilation des shaders) pendant la durée de vie de la fenêtre.

Lorsque le chargement à partir d'un fichier de cache de pipeline est activé, cela est confirmé par un message :

Attempting to seed pipeline cache from 'filename'

De même, pour vérifier si la sauvegarde du cache est activée avec succès, recherchez un message tel que celui-ci :

Writing pipeline cache contents to 'filename'

Le cache automatique du pipeline

Lorsqu'aucun nom de fichier n'est fourni pour l'enregistrement et le chargement, la stratégie de mise en cache automatique du pipeline est utilisée. Cette stratégie consiste à stocker les données dans l'emplacement du cache spécifique à l'application du système (QStandardPaths::CacheLocation).

Cette stratégie peut être désactivée de l'une des manières suivantes :

• Définir l'attribut d'application Qt::AA_DisableShaderDiskCache. (désactive complètement le stockage automatique)
• Définir la variable d'environnement QT_DISABLE_SHADER_DISK_CACHE à une valeur non nulle. (désactive complètement le stockage automatique)
• Attribuez une valeur non nulle à la variable d'environnement QSG_RHI_DISABLE_SHADER_DISK_CACHE. (désactive complètement le stockage automatique)
• Appeler setAutomaticPiplineCache() avec l'argument enable à false. (désactive complètement le stockage automatique)
• Définir un nom de fichier en appelant setPipelineCacheLoadFile(). (désactive uniquement le chargement à partir du stockage automatique, en préférant le fichier spécifié à la place)
• Définir un nom de fichier en appelant setPipelineCacheSaveFile(). (désactive uniquement l'écriture dans le stockage automatique, préférant le fichier spécifié à la place)

Les deux premiers sont des mécanismes existants qui sont utilisés depuis Qt 5.9 pour contrôler le cache binaire du programme OpenGL. Pour des raisons de compatibilité et de familiarité, le même attribut et la même variable d'environnement sont pris en charge pour le cache de pipeline amélioré de Qt 6.

Le cache de pipeline automatique utilise un seul fichier par application, mais un fichier différent pour chaque RHI backend (API graphique). Cela signifie que le passage à une autre API graphique lors de l'exécution suivante de l'application n'entraînera pas la perte du cache de pipeline généré lors de l'exécution précédente. Les applications avec plusieurs instances QQuickWindow affichées simultanément peuvent cependant ne pas en bénéficier à 100 % puisque le cache automatique ne peut stocker les données collectées qu'à partir d'un seul objet RHI à la fois. (et avec la boucle de rendu par défaut threaded, chaque fenêtre dispose de son propre RHI car le rendu s'effectue indépendamment sur des threads dédiés). Pour profiter pleinement du cache disque dans une application avec plusieurs fenêtres, il est préférable de définir le nom de fichier explicitement, par fenêtre, via setPipelineCacheSaveFile().