Model QML Type
Permet de charger les données d'un modèle 3D. En savoir plus...
| Import Statement: | import QtQuick3D |
| Inherits: | |
| Inherited By: |
Propriétés
- bakedLightmap : BakedLightmap
- bounds : Bounds
- castsReflections : bool
(since 6.4) - castsShadows : bool
- depthBias : real
- geometry : Geometry
- instanceRoot : QtQuick3D::Node
- instancing : QtQuick3D::Instancing
- instancingLodFactor : real
(since 6.12) - instancingLodMax : real
- instancingLodMin : real
- inverseBindPoses : List<matrix4x4>
- levelOfDetailBias : real
(since 6.5) - materials : List<QtQuick3D::Material>
- morphTargets : List<QtQuick3D::MorphTarget>
- motionVectorEnabled : bool
(since 6.11) - motionVectorScale : real
(since 6.11) - pickable : bool
- receivesReflections : bool
- receivesShadows : bool
- skeleton : Skeleton
- skin : Skin
- source : url
- texelsPerUnit : real
(since 6.10) - usedInBakedLighting : bool
Description détaillée
L'élément « Modèle » permet de charger un maillage et de modifier son rendu en y ajoutant des matériaux. Pour qu'un modèle puisse être rendu, il doit comporter au moins un maillage et un matériau.
Format de maillage et primitives intégrées
Le modèle peut charger des maillages statiques à partir du stockage ou l’un des types de primitives intégrées. Le format de maillage utilisé est un format d’exécution natif du moteur, mais d’autres formats sont pris en charge via l’outil d’importation de ressources Balsam.
Les primitives intégrées peuvent être chargées en définissant la propriété « source » sur l’une des valeurs suivantes : #Rectangle, #Sphere, #Cube, #Cylinder or #Cone.
Model {
source: "#Sphere"
}Le tableau ci-dessous décrit plus en détail les maillages intégrés.
| Nom | Description | Nb. de faces |
|---|---|---|
| #Cone | Un cône dont la hauteur et le diamètre sont respectivement de 100. La base se trouve à l'origine et le cône est orienté vers le haut dans la direction y. | 78 |
| #Cube | Un cube centré à l'origine, dont les arêtes mesurent 100 le long des axes x, y et z. | 12 |
| #Cylindre | Un cylindre de hauteur et de diamètre égaux à 100, centré à l'origine et s'étendant selon l'axe y. | 316 |
| #Rectangle | Un rectangle de largeur et de haut 100 s, centré à l'origine et situé dans le plan xy. | 2 |
| #Sphère | Une sphère de diamètre 100, centrée à l’origine. | 4900 |
Géométrie personnalisée
En plus d’utiliser des maillages statiques, vous pouvez implémenter un fournisseur d’ custom geometry s qui fournit au modèle des données de sommets personnalisées lors de l’exécution. Consultez l’exemple de géométrie personnalisée pour découvrir comment créer et utiliser un matériau personnalisé avec votre modèle.
Matériaux
Un modèle peut être composé de plusieurs sous-maillages, chacun pouvant avoir son propre matériau. Le sous-maillage utilise un matériau de la liste materials, correspondant à son index. Si le nombre de matériaux est inférieur au nombre de sous-maillages, le dernier matériau de la liste est utilisé pour les sous-maillages suivants. Ceci est illustré dans l’exemple « Sous-maillage ».
Vous pouvez utiliser les matériaux suivants avec l'élément de modèle : PrincipledMaterial, DefaultMaterial et CustomMaterial.
Sélection
La détection par rayons consiste à envoyer un rayon à travers la scène depuis une position de départ afin de déterminer quels modèles intersectent ce rayon. Dans Qt Quick 3D, le rayon est généralement émis depuis la vue à l’aide de coordonnées 2D résultant d’un événement tactile ou d’un événement de souris. Si un modèle est touché par le rayon, la méthode ` pickResult ` renvoie un descripteur vers le modèle ainsi que des informations sur le point d’impact du rayon sur le modèle. Pour les modèles utilisant des données de maillage dynamique ( custom geometry), le picking est moins précis que pour les données de maillage statique, car il s’effectue uniquement par rapport à la surface d’impact ( bounding volume) du modèle. Si le rayon traverse plusieurs modèles, c’est le modèle le plus proche ( pickable ) qui est sélectionné.
Notez que pour que les modèles soient « pickable », leur propriété « pickable » doit être définie sur « true ». Pour plus d’informations, consultez l’exemple de sélection 3D surQt Quick.
Documentation sur les propriétés
bakedLightmap : BakedLightmap
Lorsque cette propriété est définie sur un objet ` BakedLightmap ` valide et activé, le modèle se voit attribuer une carte d'éclairage générée lors du « baking » de l'éclairage ; cette carte d'éclairage est ensuite stockée de manière persistante. Lors du rendu, le modèle chargera et utilisera la carte d'éclairage associée. La valeur par défaut est `null`.
Remarque : lorsque l’on souhaite générer une carte d’éclairage stockée de manière persistante pour un modèle, les propriétés `bakedLightmap` et ` usedInBakedLighting ` doivent toutes deux être définies sur celui-ci, afin d’indiquer que le modèle participe non seulement à la scène avec carte d’éclairage, mais qu’il souhaite également qu’une carte d’éclairage complète soit calculée et stockée.
Pour plus d’informations sur la cuisson des lightmaps, consultez la documentation relative à la fonction ` Lightmapper `.
Cette propriété s’applique aussi bien lors du calcul que lors de l’utilisation des lightmaps. Il est essentiel de garantir la cohérence entre le cycle de calcul et les cycles suivants qui utilisent les données générées. Par exemple, modifier la clé de la carte d’éclairage rendra impossible le chargement des données générées précédemment. Une exception est la propriété « enabled », qui peut être utilisée pour activer ou désactiver dynamiquement l’utilisation des cartes d’éclairage (en dehors du cycle de cuisson), mais sachez que les résultats du rendu dépendront des paramètres « bakeMode » des lumières dans la scène.
Voir également usedInBakedLighting et Lightmapper.
bounds : Bounds [read-only]
Les limites du modèle décrivent l'étendue du volume englobant le modèle.
Remarque : les limites peuvent ne pas être immédiatement disponibles si le modèle doit d'abord être chargé.
castsReflections : bool [since 6.4]
Lorsque cette propriété est définie sur « true », le modèle est rendu par des sondes de réflexion et apparaît dans les reflets.
Cette propriété a été introduite dans Qt 6.4.
castsShadows : bool
Lorsque cette propriété est définie sur « true », la géométrie de ce modèle est utilisée lors du rendu des cartes d'ombres et sert également à générer des ombres dans l'éclairage cuit.
La valeur par défaut est « true ».
depthBias : real
Stocke le décalage de profondeur du modèle. Le décalage de profondeur est ajouté à la distance de l'objet par rapport à la caméra lors du tri des objets. Cela permet de forcer l'ordre de rendu entre des objets proches les uns des autres, qui, sans cela, pourraient être rendus dans un ordre différent d'une image à l'autre. Les valeurs négatives rapprochent l'objet de la caméra, tandis que les valeurs positives l'éloignent de celle-ci.
geometry : Geometry
Spécifiez une géométrie personnalisée pour le modèle. Le fichier « Model::source » doit être vide lorsque vous utilisez une géométrie personnalisée.
instanceRoot : QtQuick3D::Node
Cette propriété définit l'origine du système de coordonnées de l'instance.
Consultez la documentation générale pour obtenir une explication détaillée.
Voir également instancing et Instancing.
instancing : QtQuick3D::Instancing
Si cette propriété est définie, le modèle ne sera pas affiché normalement. À la place, plusieurs instances du modèle seront affichées, conformément à la définition du tableau des instances.
Voir également Instancing.
instancingLodFactor : real [default: 0.0, since 6.12]
Cette propriété permet de définir manuellement le niveau de détail (LOD) pour certains niveaux de modèles instanciés.
Lorsqu’une scène contient plusieurs niveaux de LOD pour de grandes tables d’instances, il est nécessaire de sélectionner manuellement le niveau de détail le plus approprié. Cela s’avère indispensable car la gestion automatique du LOD ne peut pas calculer correctement le niveau de détail des instances individuelles, leurs données de transformation n’étant disponibles qu’au moment du rendu GPU.
Pour réduire la charge géométrique à certains niveaux de LOD, vous pouvez spécifier manuellement la valeur instancingLodFactor. Plus cette valeur est proche de 1.0, moins la géométrie de l’objet sera rendue. Une valeur de 0.0 signifie que l’intégralité de la géométrie sera chargée/rendue avec un niveau de détail maximal.
Remarque : cette propriété est spécifiquement utilisée pour remplacer le calcul automatique du LOD lorsque la proximité des instances individuelles par rapport à la caméra n’est pas prédéterminée.
Cette propriété a été introduite dans Qt 6.12.
Voir également levelOfDetailBias.
instancingLodMax : real
Définit la distance maximale par rapport à la caméra à laquelle une instance de ce modèle est affichée. Utilisé pour la mise en œuvre du niveau de détail.
instancingLodMin : real
Définit la distance minimale par rapport à la caméra à partir de laquelle une instance de ce modèle est affichée. Utilisé pour la mise en œuvre du niveau de détail.
inverseBindPoses : List<matrix4x4>
Cette propriété contient une liste de matrices « inverseBindPose » utilisées pour l'animation squelettique. Chaque matrice « inverseBindPose » correspond à l'inverse de la transformation globale de l'Joint::index correspondante dans « skeleton », qui sera utilisée initialement.
Remarque : cette propriété n'est utilisée que si l'Model::skeleton est valide.
Remarque : si certaines matrices ne sont pas définies, les valeurs d'identité seront utilisées.
Voir également Joint::index.
levelOfDetailBias : real [since 6.5]
Cette propriété détermine la taille que doit avoir le modèle lors du rendu avant que les maillages de niveau de détail automatiques ne soient utilisés. Chaque maillage de niveau de détail généré contient une valeur de taille idéale correspondant à la proportion de la scène rendue que ce maillage doit représenter. Un modèle qui ne représente que quelques pixels à l'écran ne nécessite pas la géométrie complète pour s'afficher correctement ; dans ce cas, un maillage de niveau de détail inférieur sera donc utilisé à la place. Cette valeur constitue un décalage par rapport à la valeur idéale : ainsi, une valeur inférieure à 1.0 exigera une taille de rendu encore plus petite avant le passage à un niveau de détail inférieur. Des valeurs supérieures à 1.0 entraîneront l’utilisation plus précoce de niveaux de détail inférieurs. Une valeur de 0.0 désactivera complètement l’utilisation des niveaux de détail.
La valeur par défaut est 1.0
Remarque : cette propriété n’aura d’effet que si la géométrie du modèle contient des niveaux de détail.
Cette propriété a été introduite dans Qt 6.5.
Voir également Camera::levelOfDetailBias.
materials : List<QtQuick3D::Material>
Cette propriété contient une liste des matériaux utilisés pour le rendu de la géométrie fournie. Pour pouvoir effectuer un rendu, il faut qu'il y ait au moins un matériau. En principe, il devrait y avoir un matériau pour chaque sous-maillage inclus dans la géométrie source.
Voir également Qt Quick 3D - Exemple de sous-maillage.
morphTargets : List<QtQuick3D::MorphTarget>
Cette propriété contient une liste d'MorphTargets utilisées pour le rendu de la géométrie fournie. Les maillages doivent comporter au moins un attribut parmi les suivants : positions, normales, tangentes, binormales, coordonnées de texture et couleurs de sommets pour les cibles de morphing.
Voir également MorphTarget.
motionVectorEnabled : bool [default: true, since 6.11]
Indique si le modèle participe au passage du vecteur de mouvement.
Lorsque cette propriété est définie sur « true », le modèle fournit ses informations de mouvement au tampon de vecteurs de mouvement. Ces informations sont utilisées par l'anti-aliasing temporel (TAA) et d'autres effets qui s'appuient sur des données de mouvement par pixel.
Lorsqu’elle est définie sur « false », le modèle est exclu de la génération des vecteurs de mouvement.
Cette propriété a été introduite dans Qt 6.11.
Voir également Model::motionVectorScale.
motionVectorScale : real [default: 1.0, since 6.11]
Spécifie un facteur d'échelle appliqué aux vecteurs de mouvement générés par le modèle.
Une valeur de 1.0 préserve le mouvement réel du modèle, tandis que les valeurs supérieures à 1.0 amplifient les vecteurs de mouvement et celles inférieures à 1.0 les réduisent. Cela peut s'avérer utile pour créer des effets stylisés ou affiner le comportement visuel dans les effets qui s'appuient sur le tampon de vecteurs de mouvement.
Cette propriété a été introduite dans Qt 6.11.
Voir également Model::motionVectorEnabled.
pickable : bool
Cette propriété détermine si le modèle peut être sélectionné ou non. Définissez cette propriété sur « true » pour rendre le modèle sélectionnable. Par défaut, les modèles ne sont pas sélectionnables.
Voir également View3D::pick.
receivesReflections : bool
Lorsque cette propriété est définie sur « true », les matériaux du modèle tiennent compte des reflets provenant d'une sonde de réflexion. Si le modèle se trouve simultanément à l'intérieur de plusieurs sondes de réflexion, c'est la sonde de réflexion la plus proche qui est prise en compte.
receivesShadows : bool
Lorsque cette propriété est définie sur « true », les matériaux du modèle prennent en compte la contribution des ombres projetées par les lumières.
Remarque : lorsque le lightmapping est activé pour ce modèle, les lumières entièrement calculées (baked) dont la propriété « Light::bakeMode » est définie sur « Light.BakeModeAll » génèrent toujours des ombres (calculées) sur le modèle, quelle que soit la valeur de cette propriété.
La valeur par défaut est « true ».
skeleton : Skeleton
Contient le squelette du modèle. Le squelette est utilisé conjointement avec inverseBindPoses pour le skinning.
Remarque : les maillages du modèle doivent comporter à la fois des attributs de joints et de poids.
Remarque : si cette propriété est définie, l'animation par skinning est activée. Cela signifie que Model est transformé en fonction de Skeleton, en ignorant la transformation globale du modèle.
Voir également Model::inverseBindPoses et Qt Quick 3D - Exemple simple de skinning.
skin : Skin
Contient le squelette du modèle. Le squelette est utilisé pour le skinning.
Remarque : les maillages du modèle doivent comporter à la fois des attributs de joints et de poids.
Remarque : si cette propriété est définie, l'animation par skinning est activée. Cela signifie que l'Model sera transformée en fonction de l'Skin::joints, et que la transformation globale du modèle sera ignorée.
Remarque : si un modèle dispose à la fois d’un squelette et d’une peau, c’est la peau qui sera utilisée.
Voir aussi Qt Quick 3D - Simple Skinning Example.
source : url
Cette propriété définit l'emplacement du fichier de maillage contenant la géométrie de ce modèle ou l'un des maillages primitifs intégrés répertoriés ci-dessous, comme décrit à l'adresse Mesh format and built-in primitives.
- « #Rectangle »
- « #Sphere »
- « #Cube »
- « #Cone »
- « #Cylinder »
texelsPerUnit : real [default: 0.0, since 6.10]
Une valeur supérieure à zéro signifie que cette valeur remplacera la valeur « Lightmapper::texelsPerUnit » pour ce modèle spécifique lors de la création de la carte d’éclairage.
Cette propriété a été introduite dans Qt 6.10.
Voir également Lightmapper::texelsPerUnit.
usedInBakedLighting : bool
Lorsque cette propriété est définie sur « true », le modèle contribue à l'éclairage précalculé, tel que les lightmaps, par exemple sous forme d'ombres portées ou de lumière indirecte. Ce paramètre est indépendant du contrôle de la génération des lightmaps pour le modèle ; utilisez « bakedLightmap » à cette fin.
La valeur par défaut est « false ».
Remarque : la valeur par défaut est « false », car les concepteurs et les développeurs doivent toujours évaluer au cas par cas, pour chaque modèle, si l'objet est adapté pour participer à l'éclairage cuit.
Avertissement : les modèles dont les propriétés changent de manière dynamique, par exemple la position, la rotation ou d’autres propriétés animées, ne sont pas adaptés à l’éclairage cuit.
Pour plus d’informations sur la manière de cuire des lightmaps, consultez la documentation sur l’ Lightmapper.
Cette propriété n’est pertinente que lors du « baking » des lightmaps. Elle n’a aucun effet par la suite, lorsque les lightmaps générées sont utilisées lors du rendu.
Voir également Light::bakeMode, bakedLightmap, Lightmapper, ainsi que « Lightmaps and Global Illumination ».
© 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.
