Texture QML Type
Définit une texture destinée à être utilisée dans des scènes 3D. En savoir plus...
| Import Statement: | import QtQuick3D |
| Inherits: | |
| Inherited By: |
Propriétés
- autoOrientation : bool
(since 6.2) - flipU : bool
- flipV : bool
- generateMipmaps : bool
- indexUV : int
- magFilter : enumeration
- mappingMode : enumeration
- minFilter : enumeration
- mipFilter : enumeration
- pivotU : real
- pivotV : real
- positionU : real
- positionV : real
- rotationUV : real
- scaleU : real
- scaleV : real
- source : url
- sourceItem : Item
- textureData : TextureData
- textureProvider : RenderExtension
(since 6.7) - tilingModeDepth : enumeration
- tilingModeHorizontal : enumeration
- tilingModeVertical : enumeration
Description détaillée
Techniquement, une texture correspond à tout tableau de pixels (1D, 2D ou 3D) et à ses paramètres associés, tels que les filtres de réduction et d'agrandissement, la mise à l'échelle et les transformations UV.
Le type « Texture » dans « Qt Quick 3D » représente une image bidimensionnelle. Il sert généralement à se superposer à une géométrie tridimensionnelle ou à l’envelopper afin de simuler des détails supplémentaires qui ne peuvent pas être modélisés efficacement en 3D. Il peut également être utilisé pour simuler d’autres effets d’éclairage, tels que les reflets.
Bien que la classe `Texture` elle-même représente toujours une texture 2D, d’autres types de textures sont également disponibles via des sous-classes de `Texture`. Par exemple, pour créer une texture de type « cube map » à 6 faces, utilisez le type ` CubeMapTexture `.
Lors du rendu de la géométrie, chaque point de sa surface sera converti en un emplacement correspondant dans la texture par transformation et interpolation des coordonnées UV (coordonnées de texture) définies pour les sommets du maillage. Le programme de shader de fragment utilisé pour le rendu du matériau actif échantillonnera alors généralement la ou les textures du matériau aux coordonnées données et utilisera les données échantillonnées dans ses calculs d’éclairage.
Remarque : un matériau peut utiliser plusieurs textures pour obtenir l’interaction souhaitée avec la lumière dans la scène 3D. Il peut représenter la couleur de chaque texel sur la surface de la géométrie, mais aussi d’autres attributs de la surface. Par exemple, une « carte de normales » peut représenter l’écart par rapport aux normales de la géométrie pour chaque texel de la surface, simulant ainsi l’interaction de la lumière avec les détails les plus fins de la surface, tels que les fissures ou les irrégularités. Consultez l’exemple de matériau « Principled » pour une démonstration d’un matériau comportant plusieurs cartes de texture.
Les objets de texture peuvent provenir de :
- un fichier d’image ou de texture à l’aide de la propriété ` source `,
- un objet « Qt Quick » ( Item ) à l’aide de la propriété « sourceItem »,
- ou en définissant la propriété ` textureData ` sur une sous-classe de l'élément ` TextureData ` afin de définir le contenu de la texture personnalisée.
L'exemple suivant applique l'image « madewithqt.png » au maillage sphérique par défaut et redimensionne les coordonnées UV pour que l'image s'affiche en mosaïque sur la surface de la sphère.
Model {
source: "#Sphere"
materials: [ PrincipledMaterial {
baseColorMap: Texture {
source: "madewithqt.png"
scaleU: 4.0
scaleV: 4.0
}
}
]
}Le résultat se présente comme suit :
| Image d’origine | Mappée sur une sphère |
|---|---|
|
|
Voir également Qt Quick 3D - Exemple de texture procédurale.
Documentation sur les propriétés
autoOrientation : bool [since 6.2]
Cette propriété détermine si une transformation de texture, telle que l'inversion de la coordonnée de texture V, est appliquée automatiquement aux textures pour lesquelles cela s'avère généralement pertinent.
Par défaut, cette propriété est définie sur « true ».
Certains types de données de texture, tels que les textures compressées chargées via la propriété ` source ` à partir d’un fichier .ktx ou .pkm, ou les textures générées par le rendu d’une scène Qt Quick via la propriété ` sourceItem `, présentent souvent une orientation de l’axe Y différente de celle des textures chargées à partir de fichiers image, tels que .png ou .jpg. Par conséquent, une telle texture apparaîtrait « à l’envers » par rapport à une texture dont la source est définie sur un fichier image standard. Pour remédier à cela, toute texture concernée subit une transformation UV implicite, comme si la propriété flipV était définie sur true. Si ce comportement n’est pas souhaité, définissez cette propriété sur false.
Remarque : cette propriété s’applique lorsque la texture est utilisée en combinaison avec un `DefaultMaterial` ou un ` PrincipledMaterial`. Les ` Custom materials ` fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et doivent être implémentées par le code de shader fourni par l’application.
Cette propriété a été introduite dans Qt 6.2.
Voir également flipV.
flipU : bool
Cette propriété définit l'utilisation des coordonnées de texture inversées horizontalement.
La valeur par défaut est « false ».
Remarque : cette propriété est effective lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou un PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et doivent être implémentées par le code de shader fourni par l'application.
Voir également flipV.
flipV : bool
Cette propriété définit l'utilisation des coordonnées de texture inversées verticalement.
La valeur par défaut est « false ».
Remarque : cette propriété est effective lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou un PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et leur implémentation relève du code de shader fourni par l'application.
Voir également flipU.
generateMipmaps : bool
Cette propriété détermine si des mipmaps sont générées pour les textures qui ne fournissent pas elles-mêmes de niveaux de mipmap. L'utilisation de mipmaps associée au filtrage mip offre une meilleure qualité visuelle lors de l'affichage des textures à distance par rapport à un rendu sans mipmaps, mais cela peut entraîner une perte de performances (tant lors de l'initialisation de l'image que pendant le rendu).
Par défaut, cette propriété est définie sur « false ».
Remarque : il est nécessaire de définir un mode « mipFilter » pour que les mipmaps générées puissent être utilisées.
Remarque : cette propriété ne s’applique pas lorsque le contenu de la texture est basé sur un élément d’ Qt Quick référencé par la propriété ` sourceItem `. La génération de mipmaps pour les textures dynamiques n’est pas réalisable en raison de l’impact sur les performances. Par conséquent, la valeur de cette propriété est ignorée pour ces textures.
Voir également mipFilter.
indexUV : int
Cette propriété définit l'index des coordonnées UV utilisé par cette texture. Étant donné qu'QtQuick3D prend actuellement en charge deux jeux de coordonnées UV (0 ou 1), la valeur sera limitée à cette plage.
La valeur par défaut est 0.
magFilter : enumeration
Cette propriété détermine la manière dont la texture est échantillonnée lorsqu'elle est « agrandie », c'est-à-dire lorsqu'un texel couvre plus d'un pixel dans l'espace écran.
La valeur par défaut est « Texture.Linear ».
| Constante | Description |
|---|---|
Texture.Nearest | utilise la valeur du texel le plus proche. |
Texture.Linear | prend les quatre texels les plus proches et les interpole de manière bilinéaire. Remarque : sivous utilisez « |
Voir également minFilter et mipFilter.
mappingMode : enumeration
Cette propriété définit la méthode de mappage à utiliser lors de l'échantillonnage de cette texture.
| Constante | Description |
|---|---|
Texture.UV | Valeur par défaut. Convient à la couleur de base, à la diffusion, à l’opacité et à la plupart des autres textures. Effectue un mappage UV standard. La même partie de l’image apparaîtra toujours sur le même sommet, à moins que les coordonnées UV ne soient transformées et animées. |
Texture.Environment | Utilisé pour les « specular reflection », ce mode projette l’image sur le matériau comme si elle était réfléchie. L’utilisation de ce mode pour d’autres types de textures produit un effet miroir. |
Texture.LightProbe | C'est le réglage par défaut pour les cartes sphériques HDRI utilisées par les sondes de lumière. Ce mode n'a pas besoin d'être défini manuellement pour les objets de texture associés à la propriété « lightProbe », car il est automatiquement impliqué. |
minFilter : enumeration
Cette propriété détermine la manière dont la texture est échantillonnée lorsqu'elle est « réduite », c'est-à-dire lorsqu'un texel couvre moins d'un pixel dans l'espace écran.
La valeur par défaut est « Texture.Linear ».
| Constante | Description |
|---|---|
Texture.Nearest | utilise la valeur du texel le plus proche. |
Texture.Linear | prend les quatre texels les plus proches et les interpole de manière bilinéaire. Remarque : sivous utilisez « |
Voir également magFilter et mipFilter.
mipFilter : enumeration
Cette propriété détermine la manière dont les mipmaps de texture sont échantillonnées lorsqu'un texel couvre moins d'un pixel.
La valeur par défaut est « Texture.None ».
| Constante | Description |
|---|---|
Texture.None | désactive l'échantillonnage des mipmaps. |
Texture.Nearest | utilise le mipmapping et échantillonne la valeur du texel le plus proche. |
Texture.Linear | utilise le mipmapping et effectue une interpolation entre plusieurs valeurs de texels. Remarque : cette propriété n’aura aucun effet sur les textures qui ne disposent pas de mipmaps. |
Voir également minFilter et magFilter.
pivotU : real
Cette propriété définit la position U du pivot utilisée lors de l'application d'une transformation de type « rotationUV ».
La valeur par défaut est 0,0.
Remarque : cette propriété prend effet lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou une PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et doivent être implémentées par le code de shader fourni par l’application.
Voir également rotationUV.
pivotV : real
Cette propriété définit la position V du pivot utilisée lors de l'application d'une opération de « rotationUV ».
La valeur par défaut est 0,0.
Remarque : cette propriété est effective lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou un PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et leur implémentation relève du code de shader fourni par l’application.
Voir également pivotU et rotationUV.
positionU : real
Cette propriété décale la correspondance des coordonnées U de gauche à droite.
La valeur par défaut est 0,0.
Remarque : cette propriété s'applique lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou un PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et doivent être implémentées par le code de shader fourni par l'application.
Voir également positionV.
positionV : real
Cette propriété décale la correspondance de la coordonnée V du bas vers le haut.
La valeur par défaut est 0,0.
Remarque : Qt Quick 3D utilise des données de sommets de type OpenGL, quelle que soit l’API graphique utilisée lors de l’exécution. L’ (0, 0) de la position UV fait donc référence au coin inférieur gauche des données d’image.
Remarque : cette propriété est effective lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou un PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et doivent être implémentées par le code de shader fourni par l’application.
Voir également positionU.
rotationUV : real
Cette propriété permet de faire pivoter la texture autour du point de pivot. Elle est définie à l'aide des angles d'Euler ; une valeur positive correspond à une rotation dans le sens des aiguilles d'une montre.
La valeur par défaut est 0,0.
Remarque : cette propriété est effective lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou un PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et leur implémentation dépend du code de shader fourni par l'application.
Voir également « pivotU » et « pivotV ».
scaleU : real
Cette propriété définit comment mettre à l'échelle la coordonnée de texture U lors du mappage sur les coordonnées UV d'un maillage.
La mise à l'échelle de la valeur U lors de l'utilisation d'un mosaïquage horizontal détermine le nombre de fois où la texture est répétée de gauche à droite.
La valeur par défaut est 1,0.
Remarque : cette propriété s'applique lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou un PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et doivent être implémentées par le code de shader fourni par l'application.
Voir également tilingModeHorizontal.
scaleV : real
Cette propriété définit comment mettre à l'échelle la coordonnée de texture V lors du mappage vers les coordonnées UV d'un maillage.
La mise à l'échelle de la valeur V lors de l'utilisation du mosaïquage vertical définit le nombre de fois où une texture est répétée de bas en haut.
La valeur par défaut est 1,0.
Remarque : cette propriété s'applique lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou un PrincipledMaterial. Les Custom materials fournissent leur propre code de shader ; par conséquent, les transformations telles que celle configurée par cette propriété sont ignorées et doivent être implémentées par le code de shader fourni par l'application.
Voir également tilingModeVertical.
source : url
Cette propriété indique l'emplacement d'un fichier image ou de texture contenant les données utilisées par la texture.
Cette propriété est une URL, soumise aux mêmes règles que les autres propriétés source, telles que Image.source. Avec Texture, seuls les schémas qrc et file sont pris en charge. En l’absence de schéma et si la valeur est un chemin relatif, celui-ci est considéré comme relatif à l’emplacement du composant (c’est-à-dire du fichier .qml ).
Le fichier source peut être au format d’image conventionnel de son choix supported by Qt. De plus, Texture prend en charge les mêmes schémas de compressed texture file types que QtQuick::Image.
Remarque : la lecture des donnéesde texture à partir de fichiers image tels que .png ou .jpg implique le stockage des lignes de pixels au sein de la texture selon un ordre défini par le moteur de rendu 3D d'Qt Quick. Lorsque le fichier source est un conteneur de données de texture (éventuellement compressées), de telles transformations ne peuvent pas avoir lieu au niveau des données de pixels. C'est le cas, par exemple, des fichiers .ktx ou .pkm. À la place, la texture active implicitement une inversion verticale dans le code du shader de fragment afin d'obtenir des résultats identiques à l'écran. Ce comportement est contrôlé par la propriété autoOrientation et peut être désactivé si nécessaire.
Remarque : certains outils de compression de textures peuvent appliquer automatiquement une symétrie verticale (retournement) aux données d’image. Dans les outils modernes, il s’agit souvent d’un paramètre activable. Il est important de connaître les paramètres utilisés dans le pipeline de préparation des ressources, car une texture inversée de manière inattendue, et donc un texturage incorrect des objets, peut trouver sa cause première dans la ressource elle-même, hors du contrôle de l’application et du moteur de rendu. Lorsque la ressource l’exige, les applications peuvent toujours définir elles-mêmes la propriété ` flipV `.
Voir également sourceItem, textureData, autoOrientation et flipV.
sourceItem : Item
Cette propriété définit un élément qui servira de source à la texture. Elle permet d’utiliser n’importe quel contenu d’ Qt Quick 2D comme source de texture en affichant cet élément sous forme de calque hors écran.
Si l'élément est une image « texture provider », aucune texture supplémentaire n'est utilisée.
Si cette propriété est définie, la valeur de ` source ` sera ignorée. Une texture doit utiliser une seule méthode pour fournir des données d'image et définir uniquement l'une des propriétés suivantes : `source`, `sourceItem` ou ` textureData`.
Remarque : actuellement , les événements d’entrée ne sont transmis à l’élément utilisé comme source de texture que si l’utilisateur est limité à interagir avec une seule instance de « sourceItem » à la fois. En d’autres termes : vous pouvez partager le même « Item » entre plusieurs textures, mais vous ne pouvez alors pas avoir d’interaction multitouch avec le même élément sur plusieurs textures en même temps. Il est donc préférable d’utiliser une instance de sous-scène 2D distincte pour chaque instance de texture, si vous prévoyez de manipuler des éléments interactifs à l’intérieur.
Remarque : l’utilisation de cette propriété dans une texture référencée par plusieurs fenêtres est fortement déconseillée. Cela inclut l’utilisation via View3D::importScene. Comme la texture source créée par cette propriété n’est accessible que par un seul thread de rendu, toute tentative de la partager entre plusieurs instances d’ QQuickWindow échouera, à moins d’utiliser la boucle de rendu basic de Qt Quick à la place de la boucle par défaut threaded. Consultez la section « Qt Quick Scene Graph » pour plus d’informations sur les boucles de rendu Qt Quick.
Remarque : une texture contenant les résultats d’un passage de rendu hors écran ( Qt Quick ) aura en effet une orientation de l’axe Y différente de celle utilisée par une texture recevant son contenu via la propriété source. Lorsqu’elle est utilisée en combinaison avec `DefaultMaterial` ou ` PrincipledMaterial`, tout cela est transparent pour l’application, car les transformations UV nécessaires sont appliquées automatiquement tant que la propriété ` autoOrientation ` est définie sur `true` ; aucune action supplémentaire n’est donc requise, quelle que soit la manière dont la texture a été obtenue. Toutefois, lors du développement d’ custom materials, l’auteur du code du shader doit garder cela à l’esprit lors de l’échantillonnage de la texture et du traitement des coordonnées UV.
Voir également source, textureData et autoOrientation.
textureData : TextureData
Cette propriété contient une référence à un composant « TextureData » qui définit le contenu et les propriétés des données de texture brutes.
Si cette propriété est utilisée, la valeur de ` source ` sera ignorée. Une texture doit utiliser une seule méthode pour fournir des données d'image et ne définir qu'une seule des propriétés suivantes : `source`, ` sourceItem` ou `textureData`.
Voir également « source », « sourceItem » et « Qt Quick 3D - Exemple de texture procédurale ».
textureProvider : RenderExtension [since 6.7]
Cette propriété contient l'RenderExtension qui fournira l'QRhiTexture qui sera utilisée par cet élément.
Remarque : la texture créée par RenderExtension doit être mise à disposition via registering avec le moteur.
Cette propriété a été introduite dans Qt 6.7.
Voir également TextureProviderExtension, RenderExtension et QSSGRenderExtensionHelpers.
tilingModeDepth : enumeration
Cette propriété détermine la manière dont la texture est mappée lorsque la valeur de mise à l'échelle Z est supérieure à 1.
Par défaut, cette propriété est définie sur « Texture.Repeat ».
| Constante | Description |
|---|---|
Texture.ClampToEdge | La texture n’est pas mise en mosaïque ; la valeur située au bord est utilisée à la place. |
Texture.MirroredRepeat | La texture est répétée et reflétée selon l’axe Z. |
Texture.Repeat | La texture est répétée le long de l'axe Z. |
tilingModeHorizontal : enumeration
Détermine la manière dont la texture est mappée lorsque la valeur d'échelle U est supérieure à 1.
Par défaut, cette propriété est définie sur « Texture.Repeat ».
| Constante | Description |
|---|---|
Texture.ClampToEdge | La texture n’est pas mise en mosaïque ; la valeur située au bord est utilisée à la place. |
Texture.MirroredRepeat | La texture est répétée et reflétée par rapport à l’axe X. |
Texture.Repeat | La texture est répétée le long de l’axe X. |
Voir aussi scaleU.
tilingModeVertical : enumeration
Cette propriété détermine la manière dont la texture est mappée lorsque la valeur de mise à l'échelle V est supérieure à 1.
Par défaut, cette propriété est définie sur « Texture.Repeat ».
| Constante | Description |
|---|---|
Texture.ClampToEdge | La texture n’est pas mise en mosaïque ; la valeur située au bord est utilisée à la place. |
Texture.MirroredRepeat | La texture est répétée et reflétée par rapport à l’axe Y. |
Texture.Repeat | La texture est répétée le long de l’axe Y. |
Voir aussi scaleV.
© 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.
