Texture QML Type
Définit une texture à utiliser dans les scènes 3D. Plus d'informations...
| 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
Une texture est techniquement un tableau de pixels (1D, 2D ou 3D) et ses paramètres connexes, tels que les filtres de minimisation et d'agrandissement, la mise à l'échelle et les transformations UV.
Le type Texture dans Qt Quick 3D représente une image bidimensionnelle. Elle est généralement utilisée pour recouvrir ou envelopper une géométrie tridimensionnelle afin d'émuler des détails supplémentaires qui ne peuvent pas être modélisés efficacement en 3D. Elle peut également être utilisée pour émuler d'autres effets d'éclairage, tels que les réflexions.
Bien que la 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 carte cubique à 6 faces, utilisez le type CubeMapTexture.
Lors du rendu de la géométrie, chaque emplacement de sa surface sera transformé en un emplacement correspondant dans la texture en transformant et en interpolant les coordonnées UV (coordonnées de texture) qui ont été définies pour les sommets de la maille. Le programme de nuanceur de fragments utilisé pour effectuer le rendu du matériau actif échantillonne alors la ou les textures du matériau aux coordonnées données et utilise les données échantillonnées dans ses calculs de lumière.
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 de la surface géométrique, mais aussi d'autres attributs de la surface. Par exemple, une "carte des normales" peut représenter l'écart par rapport aux normales de la géométrie pour chaque texel de la surface, émulant l'interaction de la lumière avec les détails les plus fins de la surface, tels que les fissures ou les bosses. Voir l'exemple d' un matériau à principes pour une démonstration d'un matériau avec plusieurs cartes de texture.
Les objets de texture peuvent s'approvisionner en données d'image à partir
- un fichier image ou texture en utilisant la propriété source,
- un Qt Quick Item en utilisant la propriété sourceItem,
- ou en attribuant la propriété textureData à une sous-classe d'élément TextureData pour définir le contenu personnalisé de la texture.
L'exemple suivant fait correspondre l'image "madewithqt.png" au maillage de la sphère par défaut et met à l'échelle les coordonnées UV afin de recouvrir l'image 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 est le suivant :
| Image originale | Mappée sur une sphère |
|---|---|
|
|
Voir aussi 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 la texture, telle que l'inversion de la coordonnée V de la texture, est appliquée automatiquement pour les textures où cela est généralement pertinent.
Par défaut, cette propriété est définie sur true (vrai).
Certains types de données de texture, comme 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, ont souvent une orientation différente de l'axe Y par rapport aux textures chargées à partir de fichiers d'images tels que .png ou .jpg. Par conséquent, une telle texture apparaîtrait "à l'envers" par rapport à une texture dont la source est un fichier image normal. Pour remédier à ce problème, toute texture qualifiée bénéficie d'une transformation UV implicite, comme si la propriété flipV était définie sur true. Si vous ne le souhaitez pas, réglez cette propriété sur false (faux).
Remarque : cette propriété est efficace lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou PrincipledMaterial. Custom materials fournit son propre code de shader, et donc les transformations telles que celle configurée par cette propriété sont ignorées et relèvent du code de shader fourni par l'application à mettre en œuvre.
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 retourné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 PrincipledMaterial. Custom materials fournit son propre code de shader, et donc les transformations telles que celle configurée par cette propriété sont ignorées et relèvent du code de shader fourni par l'application à mettre en œuvre.
Voir également flipV.
flipV : bool
Cette propriété définit l'utilisation des coordonnées de texture retourné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 PrincipledMaterial. Custom materials fournit son propre code de shader, et donc les transformations telles que celle configurée par cette propriété sont ignorées et relèvent du code de shader fourni par l'application à mettre en œuvre.
Voir également flipU.
generateMipmaps : bool
Cette propriété détermine si des mipmaps sont générés pour les textures qui ne fournissent pas elles-mêmes de niveaux de mipmap. L'utilisation des mipmaps avec le filtrage mip permet d'obtenir une meilleure qualité visuelle lors de l'affichage des textures à distance par rapport à un rendu sans mipmap, mais cela peut avoir un coût en termes de performances (à la fois lors de l'initialisation de l'image et pendant le rendu).
Par défaut, cette propriété est fixée à false.
Note : Il est nécessaire de définir un mode mipFilter pour que les mipmaps générées soient utilisées.
Remarque : cette propriété n'est pas applicable lorsque le contenu de la texture est basé sur un élément Qt Quick référencé par la propriété sourceItem. La génération de mipmaps pour les textures dynamiques n'est pas possible en raison des implications en termes de 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'indice de coordonnées UV utilisé par cette texture. Comme QtQuick3D supporte pour l'instant 2 jeux d'UV (0 ou 1), la valeur sera saturée dans l'intervalle.
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 à l'é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 : l'utilisation de Texture.None ici entraîne l'utilisation par défaut de Texture.Linear.
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 cartes de texture. 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 specular reflection, ce mode permet de projeter l'image sur le matériau comme si elle était réfléchie. L'utilisation de ce mode pour d'autres types de cartes de texture permet d'obtenir un effet miroir. |
Texture.LightProbe | Ce mode est utilisé par défaut pour les cartes de sphères HDRI utilisées par les sondes lumineuses. Il n'est pas nécessaire de définir manuellement ce mode pour les objets Texture associés à la propriété lightProbe, car il est implicite automatiquement. |
minFilter : enumeration
Cette propriété détermine la manière dont la texture est échantillonnée lorsqu'elle est "minimisée", c'est-à-dire lorsqu'un texel couvre moins d 'un pixel à l'é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 : l'utilisation de Texture.None ici entraîne l'utilisation par défaut de Texture.Linear.
Voir également magFilter et mipFilter.
mipFilter : enumeration
Cette propriété détermine la manière dont les mipmaps de texture sont échantillonnés lorsqu'un texel couvre moins d'un pixel.
La valeur par défaut est Texture.None.
| Constante | Description |
|---|---|
Texture.None | désactive l'utilisation de l'échantillonnage de la mipmap. |
Texture.Nearest | utilise le mipmapping et échantillonne la valeur du texel le plus proche. |
Texture.Linear | utilise le mipmapping et interpole entre plusieurs valeurs de texel. |
Remarque : cette propriété n'a aucun effet sur les textures qui n'ont pas de mipmap.
Voir également minFilter et magFilter.
pivotU : real
Cette propriété définit la position du pivot U qui est utilisée lors de l'application d'un 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 PrincipledMaterial. Custom materials fournit son propre code de shader, et les transformations telles que celle configurée par cette propriété sont donc ignorées et doivent être mises en œuvre par le code de shader fourni par l'application.
Voir également rotationUV.
pivotV : real
Cette propriété définit la position du pivot V qui est utilisée lors de l'application d'un 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 PrincipledMaterial. Custom materials fournit son propre code de shader, et les transformations telles que celle configurée par cette propriété sont donc ignorées et doivent être mises en œuvre par le code de shader fourni par l'application.
Voir également pivotU et rotationUV.
positionU : real
Cette propriété décale la cartographie des coordonnées U de gauche à droite.
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 PrincipledMaterial. Custom materials fournit son propre code de shader, et les transformations telles que celle configurée par cette propriété sont donc ignorées et doivent être mises en œuvre par le code de shader fourni par l'application.
Voir également positionV.
positionV : real
Cette propriété décale la cartographie des coordonnées V de bas en haut.
La valeur par défaut est 0,0.
Remarque : Qt Quick 3D utilise des données de vertex de type OpenGL, quelle que soit l'API graphique utilisée au moment de l'exécution. La position UV (0, 0) se réfère donc 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 PrincipledMaterial. Custom materials fournissent leur propre code de shader, et donc les transformations telles que celle configurée par cette propriété sont ignorées et relèvent du code de shader fourni par l'application à mettre en œuvre.
Voir également positionU.
rotationUV : real
Cette propriété permet de faire pivoter la texture autour du point pivot. Elle est définie à l'aide des angles d'Euler et, pour une valeur positive, la rotation s'effectue 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 PrincipledMaterial. Custom materials fournit son propre code de shader, et donc les transformations telles que celle configurée par cette propriété sont ignorées et relèvent du code de shader fourni par l'application à mettre en œuvre.
Voir également pivotU et pivotV.
scaleU : real
Cette propriété définit comment mettre à l'échelle la coordonnée U de la texture lors de la mise en correspondance avec les coordonnées UV d'un maillage.
La mise à l'échelle de la valeur U lors de l'utilisation de la tuile horizontale définit le nombre de fois que la texture est répétée de gauche à droite.
La valeur par défaut est 1.0.
Remarque : cette propriété est effective lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou PrincipledMaterial. Custom materials fournit son propre code de shader, et donc les transformations telles que celle configurée par cette propriété sont ignorées et relèvent du code de shader fourni par l'application à mettre en œuvre.
Voir également tilingModeHorizontal.
scaleV : real
Cette propriété définit comment mettre à l'échelle la coordonnée V de la texture lors de la mise en correspondance avec les coordonnées UV d'un maillage.
La mise à l'échelle de la valeur V lors de l'utilisation de la tuile verticale définit le nombre de fois qu'une texture est répétée de bas en haut.
La valeur par défaut est 1,0.
Remarque : cette propriété est effective lorsque la texture est utilisée en combinaison avec un DefaultMaterial ou PrincipledMaterial. Custom materials fournit son propre code de shader, et donc les transformations telles que celle configurée par cette propriété sont ignorées et relèvent du code de shader fourni par l'application à mettre en œuvre.
Voir également tilingModeVertical.
source : url
Cette propriété indique l'emplacement d'un fichier d'image ou de texture contenant les données utilisées par la texture.
La propriété est une URL, avec les mêmes règles que les autres propriétés de source, telles que Image.source. Avec Texture, seuls les schémas qrc et file sont pris en charge. Lorsqu'aucun schéma n'est présent et que la valeur est un chemin relatif, elle est supposée être relative à l'emplacement du composant (c'est-à-dire du fichier .qml ).
Le fichier source peut avoir n'importe quel format de fichier image conventionnel supported by Qt. De plus, Texture supporte les mêmes compressed texture file types que QtQuick::Image.
Remarque : les données de texture lues à partir de fichiers image tels que .png ou .jpg impliquent le stockage des rangées de pixels dans la texture dans un ordre défini par le moteur de rendu 3D de Qt Quick. Lorsque le fichier source est un conteneur de données de texture - éventuellement compressées - de telles transformations ne peuvent pas se produire au niveau des données de pixels. Les fichiers .ktx ou .pkm en sont des exemples. Au lieu de cela, la texture active implicitement le retournement vertical dans le code du nuanceur de fragment afin d'obtenir des résultats identiques à l'écran. Cette fonction est contrôlée par la propriété autoOrientation et peut être désactivée si vous le souhaitez.
Remarque : certains outils de compression de textures peuvent appliquer un miroir vertical automatique (retournement) aux données de l'image. Dans les outils modernes, il s'agit souvent d'un paramètre optionnel. Il est important de connaître les paramètres utilisés dans le pipeline de conditionnement des ressources, car une texture retournée de manière inattendue, et donc une texturation incorrecte des objets, peut avoir sa cause première dans la ressource elle-même, en dehors 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 à utiliser comme source de la texture. L'utilisation de cette propriété permet d'utiliser n'importe quel contenu 2D Qt Quick comme source de texture en rendant cet élément comme une couche hors écran.
Si l'élément est un texture provider, aucune texture supplémentaire n'est utilisée.
Si cette propriété est définie, la valeur de source est ignorée. Une texture ne doit utiliser qu'une seule méthode pour fournir des données d'image et n'en définir qu'une seule parmi source, sourceItem ou textureData.
Remarque : actuellement, les événements d'entrée sont transmis à l'élément utilisé comme source de texture uniquement si l'utilisateur ne peut interagir qu'avec une instance de sourceItem à la fois. En d'autres termes, vous pouvez partager le même élément entre plusieurs textures, mais vous ne pouvez pas avoir d'interaction tactile 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 comptez manipuler des éléments interactifs à l'intérieur.
Remarque : il est fortement déconseillé d'utiliser cette propriété dans une texture référencée par plusieurs fenêtres. Ceci 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 partage entre plusieurs instances QQuickWindow échouera, à moins que la boucle de rendu basic de Qt Quick ne soit utilisée au lieu de la boucle par défaut threaded. Voir Qt Quick Scene Graph pour plus d'informations sur les boucles de rendu Qt Quick.
Remarque : une texture contenant les résultats d'une passe de rendu hors écran Qt Quick aura en fait une orientation de l'axe Y différente de celle d'une texture recevant son contenu par l'intermédiaire de la propriété source. Lorsqu'il est utilisé 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, et aucune autre action n'est donc nécessaire, quelle que soit la manière dont la texture a été obtenue. Cependant, lors du développement de custom materials, l'auteur du code de shader doit garder cela à l'esprit lorsqu'il échantillonne la texture et travaille avec les 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 ne doit utiliser qu'une seule méthode pour fournir des données d'image et n'en définir qu'une seule parmi 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 le RenderExtension qui fournira le QRhiTexture qui sera utilisé par cet élément.
Remarque : la texture créée par RenderExtension doit être mise à disposition par registering avec le moteur.
Cette propriété a été introduite dans Qt 6.7.
Voir aussi TextureProviderExtension, RenderExtension, et QSSGRenderExtensionHelpers.
tilingModeDepth : enumeration
Cette propriété contrôle la manière dont la texture est mappée lorsque la valeur de 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 carreaux, mais la valeur sur le bord est utilisée à la place. |
Texture.MirroredRepeat | La texture est répétée et reflétée sur l'axe Z. |
Texture.Repeat | La texture est répétée sur l'axe Z. |
tilingModeHorizontal : enumeration
Contrôle la manière dont la texture est mappée lorsque la valeur de l'é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 carreaux, mais la valeur sur le bord est utilisée à la place. |
Texture.MirroredRepeat | La texture est répétée et reflétée sur l'axe X. |
Texture.Repeat | La texture est répétée sur l'axe X. |
Voir également scaleU.
tilingModeVertical : enumeration
Cette propriété contrôle la manière dont la texture est mappée lorsque la valeur de 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 carreaux, mais la valeur sur le bord est utilisée à la place. |
Texture.MirroredRepeat | La texture est répétée et reflétée sur l'axe Y. |
Texture.Repeat | La texture est répétée sur l'axe Y. |
Voir également 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.
