Model QML Type
Permet de charger les données d'un modèle 3D. Plus d'informations...
| 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
- 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 la façon dont il est ombré, en lui ajoutant des matériaux. Pour qu'un modèle puisse être rendu, il faut au moins un maillage et un matériau.
Format du maillage et primitives intégrées
Le modèle peut charger des maillages statiques à partir du stockage ou de l'un des types de primitives intégrés. Le format de maillage utilisé est un format d'exécution natif du moteur, mais d'autres formats sont pris en charge par l'outil d'importation de ressources Balsam.
Les primitives intégrées peuvent être chargées en définissant la propriété source avec l'une des valeurs suivantes : #Rectangle, #Sphere, #Cube, #Cylinder or #Cone.
Model { source: "#Sphere" }
Le tableau ci-dessous décrit les maillages intégrés plus en détail.
| Nom | Description | Nombre de faces |
|---|---|---|
| #Cône | Un cône d'une hauteur et d'un diamètre de 100. La base est à l'origine et le cône pointe vers le haut dans la direction y. | 78 |
| #Cube | Un cube centré à l'origine avec 100 longs côtés le long de x, y et z. | 12 |
| #Cylindre | Un cylindre de 100 hauteur et de diamètre centré sur l'origine et se développant dans la direction y. | 316 |
| #Rectangle | Un rectangle de 100 largeur et hauteur centré sur l'origine et situé dans le plan xy. | 2 |
| #Sphère | Une sphère de 100 diamètre centrée sur l'origine. | 4900 |
Géométrie personnalisée
Outre l'utilisation de maillages statiques, vous pouvez implémenter un fournisseur custom geometry qui fournit au modèle des données de vertex personnalisées au moment de l'exécution. Voir l'exemple de géométrie personnalisée pour un exemple de création et d'utilisation d'un matériau personnalisé avec votre modèle.
Matériaux
Un modèle peut être composé de plusieurs sous-mailles, chacune d'entre elles 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-mailles, le dernier matériau de la liste est utilisé pour les sous-mailles suivantes. Ceci est démontré dans l'exemple de la sous-maille.
Vous pouvez utiliser les matériaux suivants avec l'élément de modèle : PrincipledMaterial, DefaultMaterial, et CustomMaterial.
Prélèvement
Lasélection consiste à envoyer un rayon dans la scène à partir d'une position de départ afin de déterminer les modèles qui croisent le rayon. Dans Qt Quick 3D, le rayon est normalement envoyé à partir de la vue en utilisant des coordonnées 2D résultant d'un événement tactile ou de la souris. Si un modèle a été touché par le rayon, pickResult sera renvoyé avec une poignée vers le modèle et des informations sur l'endroit où le rayon a touché le modèle. Pour les modèles qui utilisent custom geometry, la sélection est moins précise que pour les données de maillage statiques, car la sélection se fait uniquement par rapport au modèle bounding volume. Si le rayon traverse plus d'un modèle, le modèle pickable le plus proche est sélectionné.
Notez que pour que les modèles soient pickable, leur propriété pickable doit être réglée sur true. Pour plus d'informations, voir Qt Quick 3D - Exemple de sélection.
Documentation sur les propriétés
bakedLightmap : BakedLightmap
Lorsque cette propriété est associée à un objet BakedLightmap valide et activé, le modèle obtient une carte lumineuse générée lors de la cuisson de l'éclairage, la carte lumineuse étant ensuite stockée de manière persistante. Lors du rendu, le modèle chargera et utilisera la carte lumineuse associée. La valeur par défaut est null.
Remarque : Lorsque l'intention est de générer une carte lumineuse stockée de manière persistante pour un modèle, bakedLightmap et usedInBakedLighting doivent être définis, afin d'indiquer que le modèle ne participe pas seulement à la scène lumineuse, mais qu'il souhaite également qu'une carte lumineuse complète soit cuite et stockée.
Pour plus d'informations sur la cuisson des lightmaps, voir la documentation Lightmapper.
Cette propriété est pertinente à la fois pour la cuisson et pour l'utilisation des lightmaps. Il est essentiel que l'état soit cohérent entre l'exécution de la cuisson et les exécutions suivantes qui utilisent les données générées. Par exemple, si l'on change la clé de la carte lumineuse, il sera impossible de charger les données générées précédemment. Une exception est enabled, qui peut être utilisé pour basculer dynamiquement l'utilisation des lightmaps (en dehors du cycle de cuisson), mais soyez conscient que les résultats rendus dépendront des paramètres de Lights'bakeMode dans la scène.
Voir également usedInBakedLighting et Lightmapper.
bounds : Bounds [read-only]
Les limites du modèle décrivent l'étendue du volume délimité autour du modèle.
Remarque : les limites peuvent ne pas être disponibles immédiatement 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 peut être vu dans les réflexions.
Cette propriété a été introduite dans Qt 6.4.
castsShadows : bool
Lorsque cette propriété vaut true, la géométrie de ce modèle est utilisée lors du rendu des cartes d'ombres et génère également des ombres dans l'éclairage cuit.
La valeur par défaut est true.
depthBias : real
Indique le biais de profondeur du modèle. Le biais de profondeur est ajouté à la distance de l'objet par rapport à la caméra lors du tri des objets. Il peut être utilisé pour forcer l'ordre de rendu entre des objets proches les uns des autres, qui pourraient autrement être rendus dans un ordre différent dans des images différentes. Les valeurs négatives rapprochent la valeur de tri de la caméra, tandis que les valeurs positives l'éloignent de la caméra.
geometry : Geometry
Spécifier une géométrie personnalisée pour le modèle. Le site Model::source doit être vide lorsque la géométrie personnalisée est utilisée.
instanceRoot : QtQuick3D::Node
Cette propriété définit l'origine du système de coordonnées de l'instance.
Voir la documentation générale pour 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 rendu normalement. Au lieu de cela, un certain nombre d'instances du modèle seront rendues, comme défini par la table d'instance.
Voir aussi Instancing.
instancingLodMax : real
Définit la distance maximale de la caméra à laquelle une instance de ce modèle est affichée. Utilisé pour la mise en œuvre d'un niveau de détail.
instancingLodMin : real
Définit la distance minimale de la caméra à laquelle une instance de ce modèle est affichée. Utilisé pour la mise en œuvre d'un niveau de détail.
inverseBindPoses : List<matrix4x4>
Cette propriété contient une liste de matrices Inverse Bind Pose utilisées pour l'animation du squelette. Chaque matrice inverseBindPose correspond à l'inverse de la transformation globale de l'image Joint::index dans skeleton, qui sera utilisée initialement.
Remarque : cette propriété n'est utilisée que si le site Model::skeleton est valide.
Remarque : si certaines des 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é modifie 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 maille de niveau de détail générée contient une valeur de taille idéale pour chaque niveau, qui correspond à la proportion de la scène rendue que représente cette maille. Un modèle qui ne représente que quelques pixels à l'écran n'aura pas besoin de la géométrie complète pour avoir un aspect correct, de sorte qu'un maillage de niveau de détail inférieur sera utilisé dans ce cas. Cette valeur est un biais par rapport à la valeur idéale, de sorte qu'une valeur inférieure à 1.0 nécessitera un rendu encore plus petit avant de passer à un niveau de détail inférieur. Les valeurs supérieures à 1.0 permettront d'utiliser plus rapidement des niveaux de détail inférieurs. Une valeur de 0.0 désactive complètement l'utilisation des niveaux de détail.
La valeur par défaut est 1.0
Remarque : Cette propriété n'a 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 aussi Camera::levelOfDetailBias.
materials : List<QtQuick3D::Material>
Cette propriété contient une liste de matériaux utilisés pour le rendu de la géométrie fournie. Pour effectuer un rendu, il doit y avoir au moins un matériau. Normalement, il devrait y avoir un matériau pour chaque sous-maille incluse 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 de MorphTargets utilisés pour le rendu de la géométrie fournie. Les maillages doivent avoir au moins un attribut parmi les positions, les normales, les tangentes, les binormales, les coordonnées de texture et les couleurs de vertex pour les cibles de morphisme.
Voir également MorphTarget.
motionVectorEnabled : bool [default: true, since 6.11]
Spécifie 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 à la mémoire tampon du vecteur de mouvement. Ces informations sont utilisées par l'anticrénelage temporel (TAA) et d'autres effets qui s'appuient sur des données de mouvement par pixel.
Lorsqu'il vaut false, le modèle est exclu de la génération de vecteurs de mouvement.
Cette propriété a été introduite dans Qt 6.11.
Voir aussi 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 exagèrent les vecteurs de mouvement et les valeurs inférieures à 1.0 les réduisent. Cela peut être utile pour les effets stylisés ou pour 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 aussi Model::motionVectorEnabled.
pickable : bool
Cette propriété détermine si le modèle est sélectionnable 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 prennent en compte la contribution des réflexions provenant d'une sonde de réflexion. Si le modèle se trouve à l'intérieur de plus d'une sonde de réflexion en même temps, la sonde de réflexion la plus proche 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 générées par les lumières qui projettent des ombres.
Remarque : lorsque la cartographie de la lumière est activée pour ce modèle, les lumières entièrement cuites avec Light::bakeMode réglé sur Light.BakeModeAll génèrent toujours des ombres (cuites) 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é avec inverseBindPoses pour l'habillage.
Remarque : les mailles du modèle doivent avoir des attributs d'articulation et de poids.
Remarque : Si cette propriété est définie, l'animation de l'habillage est activée. Cela signifie que Model est transformé sur la base de Skeleton en ignorant la transformation globale du modèle.
Voir également Model::inverseBindPoses et Qt Quick 3D - Exemple de skinning simple.
skin : Skin
Contient le squelette du modèle. Le squelette est utilisé pour l'habillage.
Remarque : les mailles du modèle doivent avoir des attributs de poids et d'articulation.
Remarque : Si cette propriété est définie, l'animation de l'habillage est activée. Cela signifie que Model sera transformé en fonction de Skin::joints et que la transformation globale du modèle sera ignorée.
Remarque : si un modèle possède à la fois un squelette et 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 énumérés ci-dessous, tel que décrit à l'adresse Mesh format and built-in primitives.
- "#Rectangle"
- "#Sphere"
- "#Cube"
- "#Cone"
- "#Cylindre"
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 cuisson de la carte lumineuse.
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 cuit, tel que les lightmaps, par exemple sous la forme d'ombres portées ou de lumière indirecte. Ce paramètre est indépendant du contrôle de la génération de lightmaps pour le modèle, utilisez bakedLightmap pour cela.
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, modèle par modèle, si l'objet est apte à participer à l'éclairage cuit.
Attention : Les modèles dont les propriétés changent dynamiquement, par exemple la position animée, la rotation ou d'autres propriétés, ne conviennent pas pour participer à l'éclairage cuit.
Pour plus d'informations sur la cuisson des lightmaps, voir la documentation Lightmapper.
Cette propriété n'est pertinente que lors de la création de lightmaps. Elle n'a aucun effet par la suite, lors de l'utilisation des lightmaps générées pendant le rendu.
Voir également Light::bakeMode, bakedLightmap, Lightmapper, et 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.
