Portage d'Qt 3D s vers Qt Quick 3D : guide de migration

Ce guide s'adresse aux développeurs qui utilisent actuellement Qt 3D et qui souhaitent migrer vers Qt Quick 3D.

Différences de périmètre

Alors que Qt 3D et Qt Quick 3D peuvent sembler similaires puisqu’ils fournissent tous deux des API 3D, ils sont conçus selon des approches fondamentalement différentes.

Qt 3D est une API flexible permettant de mettre en œuvre des moteurs de rendu 3D personnalisés, offrant des abstractions de bas niveau pour les différents aspects du processus de rendu. Par conséquent, Qt 3D fournit des API à la fois pour C++ et QML.

En revanche, Qt Quick 3D est une API de haut niveau axée sur le rendu de contenu 3D et conçue comme une extension de Qt Quick. Par conséquent, la majorité de ses API sont basées sur QML. Ainsi, si votre application Qt 3D actuelle repose largement sur le C++, la migration vers Qt Quick 3D nécessitera une transition vers QML.

Différences architecturales

Qt 3D et Qt Quick 3D présentent des différences architecturales significatives. Qt Quick 3D suit les mêmes modèles de conception que Qt Quick, en étendant ses capacités pour prendre en charge le rendu 3D.

La première différence majeure réside dans l’utilisation des modèles de conception. Qt 3D utilise un modèle de système entité-composant (ECS). Dans ce système, on utilise une classe d’entité générique, qui peut être spécialisée en ajoutant divers composants à l’entité, selon un modèle de composition. À l’inverse, Qt Quick 3D utilise une API basée sur l’héritage qui s’aligne sur le framework Qt au sens large, où les nœuds spécialisés sont des sous-classes d’une classe de base commune. En raison de ces différences fondamentales, il n’existe pas de correspondance directe 1:1 entre les deux API.

Une autre différence notable réside dans les modèles de multithreading. Qt 3D introduit le concept d’aspects, qui fournissent différents points d’entrée pour divers types de composants associés aux entités. Chaque aspect peut créer des tâches traitées par un pool de threads, en suivant une arborescence de fournisseurs et de dépendances afin d’accomplir tout le travail nécessaire au rendu d’une image. En revanche, Qt Quick 3D utilise le même modèle de gestion des threads que Qt Quick. Il dispose d’une API frontale, accessible depuis le thread principal de l’interface graphique pour gérer l’état de la scène, et d’une API dorsale sur le thread de rendu. Bien que le thread de rendu puisse utiliser des threads supplémentaires pour certaines tâches, le modèle conceptuel du point de vue de l’utilisateur ne comporte que deux threads. Il n’existe pas de concept distinct d’« aspects » dans Qt Quick 3D, bien qu’une grande partie des fonctionnalités fournies par les aspects de Qt 3D soit toujours disponible.

Du point de vue du rendu, Qt 3D propose une approche hautement personnalisable, permettant la création de pipelines de rendu sur mesure. Cependant, cette flexibilité s’accompagne d’une certaine complexité ; par défaut, Qt 3D ne fournit pas de pipeline de rendu préconfiguré. À l’inverse, Qt Quick 3D est conçu pour être plus convivial, avec un pipeline de rendu prêt à l’emploi qui s’adapte automatiquement aux besoins de la scène. Par exemple, si une lumière directionnelle dans Qt Quick 3D est configurée pour projeter des ombres, le pipeline de rendu inclura automatiquement une passe de génération de carte d’ombres, qui sera ensuite utilisée par les matériaux de la scène. Dans Qt 3D, une telle fonctionnalité nécessiterait une configuration manuelle du graphe de trame et une extension des matériaux pour prendre en charge la passe de carte d’ombres. De plus, pour différents types de lumières, tels que les lumières ponctuelles ou les projecteurs, des modifications supplémentaires du graphe de trame et des définitions de matériaux seraient nécessaires. Bien qu’ Qt 3D offre de puissantes options de personnalisation pour les techniques de cartographie d’ombres, cela peut entraîner une surcharge importante par rapport à Qt Quick 3D, où l’activation des ombres se résume à définir une seule propriété sur une lumière.

Détails par module

Qt 3D Noyau

Le module « Core » d’ Qt 3D fournit les primitives fondamentales sur lesquelles reposent les autres modules d’ Qt 3D. La plupart des classes du module « Core » d’ Qt 3D ont des composants équivalents dans Qt Quick 3D, à l’exception des classes qui prennent spécifiquement en charge l’architecture Entity-Component-System (ECS). Qt Quick 3D propose des composants préassemblés correspondant aux combinaisons entité-composant couramment utilisées dans Qt 3D, ce qui simplifie le processus de développement.

À titre d’exemple, voici la configuration d’une entité rendable dans Qt3D :

PhongMaterial {
    id: material
}

TorusMesh {
    id: torusMesh
    radius: 5
    minorRadius: 1
    rings: 100
    slices: 20
}

Transform {
    id: torusTransform
    scale3D: Qt.vector3d(1.5, 1, 0.5)
    rotation: fromAxisAndAngle(Qt.vector3d(1, 0, 0), 45)
}

Entity {
    id: torusEntity
    components: [ torusMesh, material, torusTransform ]
}

Dans le code ci-dessus, vous pouvez voir que l’entité est composée d’un maillage, d’un matériau et d’une transformation. Dans Qt Quick 3D, le code équivalent ressemblerait à ceci :

Model {
    id: torusModel
    scale: Qt.vector3d(1.5, 1, 0.5)
    eulerRotation.x: 45
    geometry: TorusGeometry {
        radius: 5
        tubeRadius: 1
        rings: 100
        segments: 20
    }
    materials: [
        PrincipledMaterial {
            id: material
    ]
}

Dans cet exemple, l’entité est remplacée par un « Model », qui est une sous-classe du composant « Node » héritant de l’équivalent du composant « Transform » de Qt 3D. De plus, toute sous-classe de « Node » fera partie d’un graphe de scène, avec des relations parent-enfant. Le composant Model est une entité rendable pouvant comporter une géométrie et un ou plusieurs matériaux. Dans ce cas, nous utilisons la propriété geometry pour correspondre à l’API procédurale utilisée par le code Qt 3D, mais il est également possible de spécifier une géométrie à partir d’un fichier statique à l’aide de la propriété source. La propriété materials du composant Model est une liste de matériaux à utiliser pour l’ombrage de la géométrie. Il s’agit d’une liste car les géométries peuvent contenir plusieurs sous-ensembles, chacun pouvant utiliser un matériau distinct. Le composant « PrincipledMaterial » est un matériau PBR (Physically Based Rendering) qui utilise le workflow « Metallic-Roughness » et, dans le cas de cet exemple, remplace le « PhongMaterial » utilisé par l’extrait de code « Qt 3D ».

Qt 3D Input

Qt 3D fournit une gamme de classes d’entrée via son propre système d’entrée personnalisé. En revanche, Qt Quick 3D réutilise principalement les classes d’entrée de Qt Quick. Pour interagir avec une scène 3D, Qt Quick 3D fournit des API supplémentaires permettant d’effectuer du ray casting et la sélection d’objets.

View3D est la classe principale chargée de gérer les opérations de sélection dans Qt Quick 3D ; elle propose à la fois des méthodes de sélection explicites et implicites. L’API de sélection explicite vous permet de sélectionner directement depuis l’espace 2D en spécifiant les coordonnées x et y dans View3D. Cette opération renvoie une valeur pickResult contenant des détails sur l’objet touché et l’emplacement de la collision. L’API est synchrone, ce qui signifie que le résultat est disponible immédiatement après le lancer du rayon. De plus, il est possible de lancer des rayons depuis n’importe quel point de la scène. Les méthodes de sélection explicite et implicite peuvent toutes deux renvoyer une liste de toutes les collisions, et pas seulement la première.

import QtQuick
import QtQuick.Controls
import QtQuick3D

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    View3D {
        id: view
        anchors.fill: parent

        PerspectiveCamera {
            z: 200
        }

        DirectionalLight {

        }

        PrincipledMaterial {
            id: material
            baseColor: "red"
        }
        PrincipledMaterial {
            id: selectedMaterial
            baseColor: "blue"
        }

        Model {
            id: sphereModel
            source: "#Sphere"
            pickable: true
            materials: [
                material
            ]
        }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: (mouse) => {
            let result = view.pick(mouse.x, mouse.y)
            if (result.hitType == PickResult.Model) {
                if (result.objectHit == sphereModel) {
                    // toggle selection
                    if (sphereModel.materials[0] == material)
                        sphereModel.materials[0] = selectedMaterial
                    else
                        sphereModel.materials[0] = material
                }
            } else {
                // deselect
                sphereModel.materials[0] = material
            }
        }
    }
}

Dans cet extrait de code d’exemple, une scène simple est créée avec un modèle de sphère. Le modèle de sphère est défini comme « pickable », ce qui signifie que lorsqu’un rayon est projeté dans la scène, ce modèle sera pris en compte pour la sélection. Au-dessus de l’ View3D se trouve une MouseArea qui détecte les clics. Lorsqu’un clic est détecté, la méthode ` pick ` est appelée avec les coordonnées x et y du clic. Le résultat de l’opération de sélection est ensuite utilisé pour déterminer si le modèle de sphère a été touché. Si c’est le cas, le matériau du modèle de sphère bascule entre les matériaux rouge et bleu.

import QtQuick
import QtQuick.Controls
import QtQuick3D

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    View3D {
        id: view
        anchors.fill: parent

        Node {
            eulerRotation.y: 45
            PerspectiveCamera {
                z: 200

            }
        }

        DirectionalLight {

        }

        Node {
            id: anchorItem
            Item {
                anchors.centerIn: parent
                width: 250
                height: 250
                Button {
                    anchors.centerIn: parent
                    text: "Click Me"
                }

            }
        }
    }
}

Dans cet extrait de code, une scène simple est créée avec une « Button » au centre de l’écran. Le bouton est un élément 2D, mais comme son parent est un « Node », il sera projeté dans l’espace 3D. Ces composants peuvent être manipulés de la même manière que dans l’espace 2D. « View3D » se chargera automatiquement de projeter des rayons dans la scène et de transmettre les événements d’entrée à tous les éléments 2D faisant partie de la scène.

import QtQuick
import QtQuick.Controls
import QtQuick3D

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    View3D {
        id: view
        anchors.fill: parent

        Node {
            eulerRotation.y: 25
            PerspectiveCamera {
                z: 200

            }
            DirectionalLight {

            }
        }

        Model {
            source: "#Cube"
            pickable: true
            materials: [
                PrincipledMaterial {
                    baseColorMap: Texture {
                        sourceItem: Pane {
                            width: 250
                            height: 250
                            Button {
                                anchors.centerIn: parent
                                text: "Click Me"
                            }
                        }
                    }
                }
            ]
        }
    }
}

De même, dans l’extrait de code ci-dessus, un cube Model est créé avec une texture qui est un Pane contenant un Button. Dans ce cas, une image de 250 × 250 pixels Texture est créée en rendant un composant Pane contenant un Button. Normalement, cette texture serait non interactive, mais en définissant pickable sur true dans le Model, le même mécanisme de sélection implicite qui transmettait les événements d’entrée au Button dans l’exemple précédent sera utilisé pour transmettre les événements d’entrée au Button dans cet exemple. Dans le cas du cube Model, chaque face du cube sera désormais interactive avec le Button.

La plupart des classes d’entrée de Qt 3D ne sont pas directement transposables vers Qt Quick 3D ; un certain travail de portage est donc nécessaire, mais le mécanisme de sélection implicite de Qt Quick 3D facilite l’interaction avec des éléments 2D dans une scène 3D.

Qt 3D Logique

Le module « Logic » d’ Qt 3D contient un composant unique qui fournit un rappel pour chaque image rendue. Dans Qt Quick 3D, l’approche équivalente consiste à utiliser le composant « FrameAnimation », un composant d’ Qt Quick s général qui fournit des informations de synchronisation et un mécanisme de rappel pour chaque image rendue.

FrameAnimation {
    running: true
    onTriggered: {
        console.log(`currentFrame: ${currentFrame}, frameTime: ${frameTime}`)
    }
}

Ce composant peut être utilisé n'importe où dans votre scène, y compris en tant qu'enfant d'un objet sur lequel vous souhaitez effectuer une action à chaque image.

Il convient toutefois de noter que ce modèle n’est nécessaire que lorsque vous souhaitez effectuer une action à chaque image. Bien que « FrameAnimation » permette de recréer le comportement d’interrogation dans certains moteurs de jeu, il est également possible d’utiliser les mêmes modèles pilotés par les événements dans « Qt Quick 3D » que dans « Qt Quick ».

Qt 3D Rendu

Le module Render de Qt 3D contient la plupart des classes essentielles nécessaires au rendu. Dans Qt Quick 3D, la plupart des fonctionnalités équivalentes sont fournies sous forme de détails d’implémentation internes qui ne sont pas directement exposés à l’utilisateur. Il existe toutefois certaines classes qui sont exposées à l’utilisateur sous forme d’API pouvant être utilisées pour étendre et personnaliser les fonctionnalités de Qt Quick 3D.

Géométrie

Dans Qt 3D, les données de géométrie ou de maillage sont représentées par la classe ` QGeometryRenderer ` ou le composant ` GeometryRenderer `. Dans Qt Quick 3D, les équivalents sont la classe ` QQuick3DGeometry ` et le composant ` ProceduralMesh `. Dans Qt 3D, la classe ` QGeometryRenderer ` est de niveau inférieur et attend de l’utilisateur qu’il fournisse les structures d’attributs de sommets dans le cadre des données de géométrie. Dans Qt Quick 3D, vous pouvez choisir les attributs de sommet intégrés à utiliser, mais la disposition des tampons est gérée en interne en tant que détails d’implémentation.

Pour plus de détails sur la manière dont cela fonctionne, consultez l’exemple de géométrie 3D personnalisée «Qt Quick ».

Textures

Dans Qt 3D, les textures sont représentées par les sous-classes de QAbstractTexture. Dans Qt Quick 3D, l’équivalent est le composant Texture, qui constitue la représentation frontale d’une texture et d’un échantillonneur. Les données utilisées par le composant de texture peuvent toutefois provenir de diverses sources. La méthode la plus simple consiste à définir la propriété source sur un fichier image, qui sera alors chargé sur le GPU en tant que données de texture. Il est également possible de générer de manière procédurale des données de texture lors de l’exécution, soit en utilisant du contenu QML 2D comme source, soit en créant une sous-classe de ` QQuick3DTextureData `, soit en utilisant le composant ` ProceduralTextureData `. Ces types vous permettent de spécifier les données de texture en indiquant la taille, le format et les données d’image brutes. Il est également possible de créer des textures sur le GPU à l’aide de ` render extensions`.

Pour plus de détails sur la manière de procéder, consultez l’exemple de texture procédurale 3D disponible à l’adresse Qt Quick .

Matériaux

Bien qu’il fût possible d’utiliser certains matériaux intégrés dans Qt 3D, cette utilisation vous limitait aux framegraphs intégrés avec lesquels ils pouvaient fonctionner. Qt Quick 3D présente une situation similaire dans la mesure où il fournit une sélection de matériaux intégrés compatibles avec la stratégie de rendu interne. Cependant, tant pour Qt 3D que pour Qt Quick 3D, il est possible de créer des matériaux personnalisés.

Dans Qt 3D, il s’agissait d’un processus assez complexe impliquant une arborescence composée de QMaterial, QEffect, QTechnique, QRenderPass et QShaderProgram. Dans Qt Quick 3D, ce processus est simplifié pour les matériaux et se résume à un seul composant CustomMaterial. Ce composant vous permet de spécifier un code de shader personnalisé pour le matériau, le reste de la configuration étant pris en charge par le moteur de rendu. Il existe deux modes pour CustomMaterial: « shaded » (avec ombrage) et « unshaded » (sans ombrage). En mode « shaded », l’API de code de shader personnalisé vous permet de personnaliser le shader intégré « PrincipledMaterial », tandis qu’en mode « unshaded », vous pouvez écrire votre propre code de shader à partir de zéro. Dans les deux cas, le langage de shader utilisé est le GLSL, avec quelques extensions de mots-clés spécifiques à Qt pour faciliter l’intégration avec le reste de l’API Qt Quick 3D.

Pour plus de détails sur la manière de procéder, consultez les exemples « Mode ombré » et « Mode non ombré », ainsi que cette présentation générale de l’utilisation du langage de shader GLSL personnalisé d’ Qt Quick 3D.

Effets

Du point de vue de Qt3D, il n’y a pas de différence entre le rendu d’une scène 3D et le rendu d’effets de post-traitement, ce qui est correct d’un point de vue de bas niveau. Cependant, Qt Quick 3D établit une distinction. Models partie d’une scène 3D contiendra une liste d’ materials, qui sont rendus lors des passes principales. Le résultat de ces passes principales est le contenu 3D rendu soit directement sur la surface d’une fenêtre, soit sur une texture. Effects La différence réside dans le fait que, dans Qt Quick 3D, ces passes font référence à des effets de post-traitement où chaque pass finit par être un quad unique couvrant l’intégralité de la cible de rendu. La texture résultant du passage de couleur principal est ensuite transmise au premier passage d’effet sous forme de texture, et le résultat de ce passage est à son tour transmis au passage d’ Effect s suivant sous forme de texture, et ainsi de suite. Le passage final est ensuite rendu vers la cible de rendu de sortie, qui est généralement la surface de la fenêtre. Certaines Effects nécessitent des « buffers s » créées au cours des passages principaux, comme la texture de profondeur, tandis que d’autres nécessiteront des étapes intermédiaires ; toutes ces étapes peuvent être définies à l’aide des API d’effets d’ Qt Quick 3D.

Qt Quick 3D optimise cette chaîne d’effets de post-traitement grâce à des API qui vous permettent de définir autant de passes de rendu que nécessaire pour obtenir l’effet souhaité.

Pour plus de détails sur la manière de procéder, consultez l’exemple de post-traitement 3D «Qt Quick ».

Tampons d’instance

Dans Qt 3D, l’utilisation de l’instanciation et des tampons d’instance est assez basique ; leur utilisation dépendra donc du cas d’utilisation spécifique. Dans Qt Quick 3D, les matériaux intégrés possèdent certaines propriétés d’instanciation fixes qui peuvent être définies, mais pour ce faire, vous devez fournir les données d’instance sous forme de tampon. Il existe plusieurs façons de fournir ces données et, une fois celles-ci fournies, il suffit de définir la propriété « instancing » du composant « Model » pour associer les données du tampon d’instance à ce que vous souhaitez instancier.

Pour plus de détails, consultez cet article consacré à l’instanciation dans Qt Quick 3D.

Extensions de rendu

L'objectif de Qt 3D est de fournir un moyen puissant de définir une solution de rendu personnalisée pour votre application. Qt Quick 3D n'offre pas ce niveau de personnalisation, car il vise à être facile à utiliser plutôt qu'à personnaliser, mais il propose tout de même plusieurs moyens d'étendre le pipeline de rendu en plus de toutes les méthodes énumérées ci-dessus. Pour ce faire, il suffit d’implémenter des « render extensions », qui vous permettent d’ajouter des passes de rendu personnalisées au moteur de rendu en utilisant les mêmes données que celui-ci. Il s’agit d’une API de bas niveau qui nécessite une bonne compréhension du pipeline de rendu 3D d’ Qt Quick, ainsi que de l’API RHI ( Qt Rendering Hardware Interface ).

Pour voir un exemple de mise en œuvre, consultez l’exemple d’extension « Stencil Outline »

Qt 3D Extras

Le module « Extras » d’ Qt 3D fournit divers utilitaires pour faciliter une expérience « prête à l’emploi », tels que des matériaux, des générateurs de géométrie et des contrôleurs de caméra. Il inclut également un graphe de trame pour le moteur de rendu direct. Dans Qt Quick 3D, vous n’avez pas besoin de définir explicitement un graphe de trame ; celui-ci est généré automatiquement en fonction des exigences de la scène.

Matériaux intégrés

Dans Qt Quick 3D, les matériaux sont fournis soit via PrincipledMaterial ou SpecularGlossyMaterial, soit en définissant un « CustomMaterial » avec un code de shader personnalisé. Le « PrincipledMaterial » est un shader PBR (Physically Based Rendering) qui utilise le workflow « Metallic-Roughness ». La complexité du shader généré augmente en fonction des propriétés définies par l’utilisateur et du contenu de la scène. Par exemple, si une lumière projette des ombres, le shader généré inclura du code pour la réception des ombres ; si une sonde d’éclairage ou une sonde de réflexion est présente, le shader intégrera ces informations d’éclairage. Cette adaptation dynamique s’applique également aux « CustomMaterial » en mode ombré. En revanche, les shaders « CustomMaterial » non ombrés ne prennent pas automatiquement en compte les informations de la scène, telles que l’éclairage.

Aides à la géométrie

À l’instar d’ Qt 3D, Qt Quick 3D fournit également de nombreuses primitives géométriques intégrées, ainsi que de nombreux générateurs de géométrie procédurale.

Le tableau suivant présente une correspondance entre les classes de géométrie d’ Qt 3D et leurs équivalents dans Qt Quick 3D :

Contrôleurs de caméra

Pour le contrôle des caméras, Qt Quick 3D propose des options comparables à celles de OrbitCameraController et WasdController. Le contrôleur de caméra ( WasdController ) est similaire au contrôleur de caméra ( FirstPersonCameraController ) de Qt3D, mais il permet de contrôler n'importe quel élément de la scène, et pas seulement les caméras.

Qt 3D Animation

Le module Animation d’ Qt 3D définit la manière dont les différents types d’animations sont gérés en 3D. Dans Qt Quick 3D, les fonctionnalités équivalentes sont réparties entre plusieurs modules, qui s’appuient souvent sur les classes existantes de Qt Quick lorsque cela est possible. Par exemple, vous pouvez utiliser les différentes classes d’animation de l’import QtQuick pour animer les propriétés des nœuds 3D.

Lors de l’importation d’animations à partir d’outils de création de contenu 3D, celles-ci sont généralement définies à l’aide de lignes de temps. Le Qt Quick Timeline module fournit les classes nécessaires à la définition de ces animations, et tout contenu importé comportant des animations aura besoin de ce module pour fonctionner.

Outre les transformations de base (telles que la translation, la rotation et la mise à l’échelle) des éléments d’une scène, Qt Quick 3D prend en charge les animations basées sur un armature, dans lesquelles vous animez les os d’un squelette, ce qui affecte les sommets associés à chaque articulation ou os. Ceci est rendu possible grâce au composant Skin, qui relie les objets Node représentant les os de la scène aux poids d’os correspondants dans une géométrie Model's. Dans ce cas, l’animation du squelette s’effectue en animant les os à l’aide de transformations.

Qt Quick 3D prend également en charge les animations de cibles de morphing, qui permettent d’animer directement les modifications de la géométrie d’un modèle. Les cibles de morphing sont des instantanés prédéfinis de la géométrie d’un modèle, et vous pouvez créer des animations entre celles-ci à l’aide du composant « MorphTarget ».

Pour combiner plusieurs animations ou les fusionner, on utilise les composants du module « Timeline Blend Trees » d’ Qt Quick. Ce module vous permet de définir des arborescences complexes pour gérer la manière dont les différentes animations interagissent. La plupart de ces classes d’animation génériques ne sont pas spécifiques à Qt Quick 3D, mais font partie du framework plus large d’ Qt Quick, qui exploite les fonctionnalités existantes plutôt que d’introduire de nouvelles méthodes.

Qt 3D Scene2D

Dans Qt 3D, le composant Scene2D sert à convertir des scènes Qt Quick en 2D en textures pouvant être utilisées au sein d’une scène 3D. Dans Qt Quick 3D, cela s’effectue à l’aide de la propriété ` sourceItem ` du composant ` Texture `. La propriété `sourceItem` peut faire référence à un élément ` Item ` existant ou définir un élément en ligne. L’élément de niveau supérieur détermine la taille de la texture, et la scène ` Qt Quick ` est rendue dans un calque qui est mappé sur le composant ` Texture `.

De plus, il est possible d’utiliser des composants Item-based directement au sein d’une scène 3D, où ils sont projetés dans l’espace 3D sans nécessiter de texture.