Portage de Qt 3D vers Qt Quick 3D : Guide de migration

Ce guide est destiné aux développeurs qui utilisent actuellement Qt 3D qui souhaitent migrer vers Qt Quick 3D.

Différences de portée

Bien que Qt 3D et Qt Quick 3D peuvent sembler similaires car ils fournissent tous deux des API 3D, ils sont conçus avec des approches fondamentalement différentes.

Qt 3D L'API 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 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. Par conséquent, si votre application Qt 3D actuelle repose fortement sur C++, la migration vers Qt Quick 3D nécessitera une transition vers QML.

Différences architecturales

Qt 3D et Qt Quick 3D diffèrent de manière significative au niveau de leur architecture. 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 de modèles de conception. Qt 3D utilise un modèle de système entité-composant (ECS). Dans ce système, une classe d'entité générique est utilisée, qui peut être spécialisée en ajoutant divers composants à l'entité, en suivant un modèle de composition. En revanche, Qt Quick 3D utilise une API basée sur l'héritage qui s'aligne sur le cadre plus large de Qt 3D, 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 importante réside dans les modèles de threading. Qt 3D introduit le concept d'aspects, qui fournit différents points d'entrée pour divers types de composants attachés à des entités. Chaque aspect peut créer des tâches qui sont traitées par un pool de threads, en suivant un arbre de fournisseurs et de dépendances pour effectuer tout le travail nécessaire au rendu d'une image. D'autre part, Qt Quick 3D utilise le même modèle de threading que Qt Quick. Il dispose d'une API frontale, accessible à partir du 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 n'implique que deux threads. Il n'y a pas de concept distinct d'aspects dans Qt Quick 3D, bien qu'une grande partie de la fonctionnalité fournie par les aspects de Qt 3D soit toujours disponible.

Du point de vue du rendu, Qt 3D offre 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é. En revanche, 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 graphique de trame et une extension des matériaux pour prendre en charge la passe de cartographie des ombres. En outre, pour les différents types de lumière, tels que les lumières ponctuelles ou les projecteurs, d'autres modifications du graphique de trame et des définitions des matériaux seraient nécessaires. Bien que Qt 3D offre de puissantes options de personnalisation pour les techniques de mappage des ombres, cela peut entraîner une surcharge importante par rapport à Qt Quick 3D, où l'activation des ombres est aussi simple que le réglage d'une seule propriété sur une lumière.

Détails par module

Qt 3D Module de base

Le module Qt 3D Core fournit les primitives fondamentales sur lesquelles les autres modules Qt 3D sont construits. La plupart des classes de Qt 3D Core 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 offre des composants pré-assemblés qui correspondent aux combinaisons entité-composant couramment utilisées dans Qt 3D, ce qui simplifie le processus de développement.

A titre d'exemple, voici la configuration d'une entité de rendu 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 qui hérite de l'équivalent du composant Transform de Qt 3D. En outre, toute sous-classe de nœud fera partie d'un graphe de scène, avec des relations parent-enfant. Le composant Modèle est une entité pouvant être rendue, qui peut avoir 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 la géométrie à partir d'un fichier statique en utilisant la propriété source. La propriété materials du composant Model est une liste de matériaux à utiliser pour ombrer la géométrie. Il s'agit d'une liste car les géométries peuvent contenir plusieurs sous-ensembles, chacun d'entre eux pouvant utiliser un matériau distinct. Le composant PrincipledMaterial est un matériau PBR (Physically Based Rendering) qui utilise le flux de travail Metallic-Roughness et qui, dans le cas de cet exemple, remplace le matériau PhongMaterial utilisé par l'extrait Qt 3D.

Qt 3D Input

Qt 3D fournit une gamme de classes d'entrée par le biais de 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 pour effectuer le lancer de rayons et le prélèvement d'objets.

View3D est la classe principale pour gérer les opérations de prélèvement dans Qt Quick 3D, offrant à la fois des méthodes de prélèvement explicites et implicites. L'API de prélèvement explicite vous permet de prélever directement dans l'espace 2D en spécifiant les coordonnées x et y dans le champ View3D. Cette opération renvoie une valeur pickResult qui contient des détails sur l'objet touché et l'emplacement de la touche. L'API est synchrone, ce qui signifie que le résultat est disponible immédiatement après le lancement du rayon. En outre, il est possible de lancer des rayons à partir de n'importe quel point de la scène. Les méthodes de prélèvement explicites et implicites peuvent renvoyer une liste de toutes les occurrences, et pas seulement de 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 exemple de code, une scène simple est créée avec un modèle de sphère. Le modèle de sphère est défini comme étant 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 View3D se trouve MouseArea qui écoute 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 prélèvement 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 est basculé 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 exemple de code, une scène simple est créée avec un 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. Il est possible d'interagir avec de tels composants 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 qui font 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, un Texture de 250 x 250 pixels est créé par le rendu d'un composant Pane contenant un Button. Normalement, cette texture serait non interactive, mais en fixant pickable à true sur le Model, le même mécanisme de sélection implicite qui a transmis 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 Button.

La plupart des classes d'entrée de Qt 3D ne sont pas directement transposables à Qt Quick 3D, ce qui nécessite un certain effort de portage, mais le mécanisme de sélection implicite de Qt Quick 3D permet d'interagir facilement avec des éléments 2D dans une scène 3D.

Qt 3D Logique

Le module Qt 3D Logic contient un seul composant qui fournit un rappel pour chaque image rendue. Dans Qt Quick 3D, l'approche équivalente consiste à utiliser le composant FrameAnimation, un composant général Qt Quick 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 pour 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 de pilotage d'événements dans Qt Quick 3D que dans Qt Quick.

Qt 3D Rendu

Le module Qt 3D Render contient la plupart des classes essentielles au rendu. Dans Qt Quick 3D, la plupart des fonctionnalités équivalentes sont fournies en tant que détails d'implémentation internes qui ne sont pas directement exposés à l'utilisateur. Cependant, certaines classes sont exposées à l'utilisateur en tant qu'API qui peuvent être utilisées pour étendre et personnaliser les fonctionnalités de Qt Quick 3D.

Géométrie

Les données de géométrie ou de maillage dans Qt 3D 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 la disposition des attributs des sommets dans le cadre des données géométriques. Dans Qt Quick 3D, vous avez le contrôle sur les attributs de vertex 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, consultez l'exemple de géométrie personnalisée deQt Quick 3D.

Textures

Les textures dans Qt 3D sont représentées par les sous-classes de QAbstractTexture. Dans Qt Quick 3D, l'équivalent est le composant Texture, qui est la représentation frontale d'une texture et d'un échantillonneur. Les données utilisées par le composant texture peuvent provenir de différentes sources. Le plus simple est de définir la propriété source sur un fichier image, qui sera téléchargé sur le GPU en tant que données de texture. Il est également possible de générer des données de texture de manière procédurale au moment de l'exécution, soit en utilisant un contenu qml 2D comme source, soit en sous-classant QQuick3DTextureData ou 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 brutes de l'image. Il est également possible de créer des textures sur le GPU en utilisant render extensions.

Pour plus de détails sur la manière de procéder, consultez l'exemple de texture procédurale 3D surQt Quick .

Matériaux

Bien qu'il soit possible d'utiliser certains matériaux intégrés dans Qt 3D, vous êtes alors limité aux matériaux intégrés dans framegraphs avec lesquels vous pouvez travailler. Qt Quick La situation est similaire dans 3D, qui fournit une sélection de matériaux intégrés fonctionnant avec la stratégie de rendu interne. Cependant, pour Qt 3D et 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 de QMaterial, QEffect, QTechnique, QRenderPass et QShaderProgram. Dans Qt Quick 3D, pour les matériaux, ce processus est simplifié à un seul composant CustomMaterial. Ce composant vous permet de spécifier un code de shader personnalisé pour le matériau, et le reste de la configuration est effectué par le moteur de rendu. Il existe deux modes pour CustomMaterial: ombré et non ombré. En mode ombré, l'API de code de nuanceur personnalisé vous permet de personnaliser le nuanceur PrincipledMaterial intégré, et en mode non ombré, vous pouvez écrire votre propre code de nuanceur à partir de zéro. Dans les deux cas, le langage de shader est GLSL, avec quelques extensions de mots-clés spécifiques à Qt 3D pour faciliter l'intégration avec le reste de l'API 3D de Qt Quick.

Pour plus de détails sur la façon de procéder, consultez les exemples du mode ombré et du mode non ombré, ainsi que cet aperçu de l'utilisation du langage d'ombrage GLSL personnalisé de 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, et d'un point de vue bas niveau, c'est correct. Cependant, Qt Quick 3D fait une distinction. Models partie d'une scène 3D contiendra une liste de materials, et ceux-ci seront rendus pendant les passes principales. Le résultat de ces passes principales est le contenu 3D rendu soit directement sur une surface de fenêtre, soit sur une texture. Effects est différent dans la mesure où, dans Qt Quick 3D, il fait référence à des effets de post-traitement dans lesquels chaque pass finit par être un quadruple qui couvre l'ensemble de la cible de rendu. La texture résultante de la passe de couleur principale est ensuite transmise à la première passe d'effet en tant que texture, et le résultat de cette passe est ensuite transmis à la passe Effect suivante en tant que texture, et ainsi de suite. La dernière passe est ensuite rendue à la cible de rendu de sortie, qui est généralement la surface de la fenêtre. Certaines pages Effects nécessitent buffers créées pendant les passes principales, comme la texture de profondeur, et d'autres nécessitent des étapes intermédiaires, qui peuvent toutes être définies à l'aide des API d'effets dans Qt Quick 3D.

Qt Quick 3D spécialise cette chaîne d'effets de post-traitement avec des API qui vous permettent de définir autant de passes de rendu que nécessaire pour obtenir l'effet désiré.

Pour plus de détails sur la façon de procéder, consultez l'exemple de post-traitement deQt Quick 3D.

Tampons d'instance

Dans Qt 3D, l'utilisation de l'instanciation et des tampons d'instance est de niveau assez bas, et son utilisation dépend donc du cas d'utilisation spécifique. Dans Qt Quick 3D, les matériaux intégrés ont des 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 qu'elles sont fournies, il suffit de définir la propriété instancing sur le composant Model pour associer les données du tampon d'instance à ce que vous voulez mettre en instance.

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

Extensions du moteur 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 ne fournit pas ce niveau de personnalisation, puisqu'il vise à être facile à utiliser plutôt qu'à personnaliser, mais il fournit quelques moyens d'étendre le pipeline de rendu en plus de tous les moyens énumérés ci-dessus. Cela se fait en implémentant render extensions, qui vous permet d'ajouter des passes de rendu personnalisées au moteur de rendu en utilisant les mêmes données que le moteur de rendu. Il s'agit d'une API de bas niveau qui nécessite une bonne compréhension du pipeline de rendu 3D Qt Quick, ainsi que de l'API Qt Rendering Hardware Interface (RHI).

Pour voir comment procéder, consultez l'exemple d'extension du contour du pochoir.

Qt 3D Extras

Le module Extras de 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 comprend également un graphique de trame de rendu avancé. Dans Qt Quick 3D, vous n'avez pas besoin de définir explicitement un graphique de trame ; au lieu de cela, un graphique de trame 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 en utilisant PrincipledMaterial ou SpecularGlossyMaterial, soit en définissant un CustomMaterial avec un code de nuanceur personnalisé. Le PrincipledMaterial est un nuanceur PBR (Physically Based Rendering) qui utilise le flux de travail 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 lumineuse ou une sonde de réflexion est présente, le shader incorporera ces informations d'éclairage. Cette adaptation dynamique s'applique également à CustomMaterial en mode ombré. Cependant, 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

Comme 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 fournit une correspondance entre les classes géométriques de Qt 3D et leurs équivalents dans Qt Quick 3D :

Contrôleurs de caméra

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

Qt 3D Animation

Le module Qt 3D Animation définit la manière dont les différents types d'animation sont gérés en 3D. Dans Qt Quick 3D, des fonctionnalités équivalentes sont réparties entre plusieurs modules, en s'appuyant souvent sur des classes existantes de Qt Quick lorsque cela est possible. Par exemple, vous pouvez utiliser les différentes classes d'animation de l'importation 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 module Qt Quick Timeline fournit les classes nécessaires à la définition de ces animations, et tout contenu importé comportant des animations nécessitera ce module pour fonctionner.

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

Qt Quick 3D prend également en charge les animations de cibles de morphes, qui permettent d'animer directement les modifications de la géométrie d'un modèle. Les cibles de morphes sont des instantanés prédéfinis de la géométrie d'un modèle, et vous pouvez animer entre eux à l'aide du composant MorphTarget.

Pour combiner plusieurs animations ou les mélanger, les composants du module Qt Quick Timeline Blend Trees sont utilisés. Ce module vous permet de définir des arbres complexes pour gérer l'interaction des différentes animations. La plupart de ces classes d'animation génériques ne sont pas spécifiques à Qt Quick 3D mais font partie du cadre plus large de Qt Quick, tirant parti de la fonctionnalité existante au lieu d'introduire de nouvelles méthodes.

Qt 3D Scene2D

Dans Qt 3D, le composant Scene2D est utilisé pour rendre des scènes 2D Qt Quick en textures qui peuvent être utilisées dans une scène 3D. Dans Qt Quick 3D, cela se fait à l'aide de la propriété sourceItem du composant Texture. La propriété sourceItem peut faire référence à un élément existant Item 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 sur une couche qui s'applique au composant Texture.

En outre, il est possible d'utiliser les composants Item-based directement dans une scène 3D, où ils sont projetés dans l'espace 3D sans avoir besoin d'une texture.