Texture QML Type
Define una textura para su uso en escenas 3D. Más...
| Import Statement: | import QtQuick3D |
| Inherits: | |
| Inherited By: |
Propiedades
- 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
Descripción detallada
Una textura es técnicamente cualquier matriz de píxeles (1D, 2D o 3D) y sus configuraciones relacionadas, como filtros de reducción y aumento, escalado y transformaciones UV.
El tipo de textura en Qt Quick 3D representa una imagen bidimensional. Se utiliza normalmente para mapear/envolver geometría tridimensional para emular detalles adicionales que no pueden modelarse eficazmente en 3D. También se puede utilizar para emular otros efectos de iluminación, como los reflejos.
Mientras que la textura en sí siempre representa una textura 2D, otros tipos de texturas también están disponibles a través de subclases de Textura. Por ejemplo, para crear una textura de mapa cúbico con 6 caras, utilice el tipo CubeMapTexture.
Cuando la geometría está siendo renderizada, cada localización en su superficie será transformada a una localización correspondiente en la textura transformando e interpolando las coordenadas UV (coordenadas de textura) que han sido establecidas para los vértices de la malla. El programa fragment shader que está siendo usado para renderizar el material activo típicamente muestreará la(s) textura(s) del material en las coordenadas dadas y usará los datos muestreados en sus cálculos de luz.
Nota: Un Material puede utilizar múltiples texturas para dar la interacción deseada con la luz en la escena 3D. Puede representar el color de cada texel en la superficie de la geometría, pero también otros atributos de la superficie. Por ejemplo, un "mapa normal" puede representar la desviación de las normales de la geometría para cada texel de la superficie, emulando la interacción de la luz con detalles más finos de la superficie, como grietas o protuberancias. Consulte el ejemplo de material basado en principios para ver una demostración de un material con varios mapas de textura.
Los objetos de textura pueden obtener datos de imagen de
- un archivo de imagen o textura utilizando la propiedad source,
- un Qt Quick Item utilizando la propiedad sourceItem,
- o estableciendo la propiedad textureData a una subclase de elemento TextureData para definir el contenido de la textura personalizada.
El siguiente ejemplo mapea la imagen "madewithqt.png" en la malla de la esfera por defecto, y escala las coordenadas UV para mosaico de la imagen en la superficie de la esfera.
Model { source: "#Sphere" materials: [ PrincipledMaterial { baseColorMap: Texture { source: "madewithqt.png" scaleU: 4.0 scaleV: 4.0 } } ] }
El resultado es el siguiente:
| Imagen original | Mapeada en una esfera |
|---|---|
|
|
Véase también Qt Quick 3D - Procedural Texture Example.
Documentación de propiedades
autoOrientation : bool [since 6.2]
Esta propiedad determina si una transformación de textura, como voltear la coordenada V de la textura, se aplica automáticamente a las texturas en las que esto suele ser relevante.
Por defecto, esta propiedad está establecida en true.
Ciertos tipos de datos de textura, como las texturas comprimidas cargadas a través de la propiedad source desde un archivo .ktx o .pkm, o las texturas generadas al renderizar una escena Qt Quick a través de la propiedad sourceItem, a menudo tienen una orientación del eje Y diferente cuando se comparan con texturas cargadas desde archivos de imagen, como .png o .jpg. Por lo tanto, una textura de este tipo aparecerá "al revés" en comparación con una textura cuyo origen sea un archivo de imagen normal. Para remediar esto, cualquier Textura calificada obtiene una transformación UV implícita como si la propiedad flipV estuviera establecida a true. Si no se desea esto, establezca esta propiedad a false.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporciona su propio código shader, por lo que transformaciones como la configurada por esta propiedad son ignoradas y dependen del código shader proporcionado por la aplicación para ser implementadas.
Esta propiedad se introdujo en Qt 6.2.
Véase también flipV.
flipU : bool
Esta propiedad establece el uso de las coordenadas de textura volteadas horizontalmente.
Por defecto es false.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporcionan su propio código shader, por lo que transformaciones como la configurada por esta propiedad son ignoradas y depende del código shader proporcionado por la aplicación implementarlas.
Véase también flipV.
flipV : bool
Esta propiedad establece el uso de las coordenadas de textura volteadas verticalmente.
Por defecto es false.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporcionan su propio código shader, por lo que transformaciones como la configurada por esta propiedad son ignoradas y depende del código shader proporcionado por la aplicación implementarlas.
Véase también flipU.
generateMipmaps : bool
Esta propiedad determina si se generan mipmaps para las texturas que no proporcionan niveles de mipmap por sí mismas. El uso de mipmaps junto con el filtrado mip proporciona una mejor calidad visual cuando se visualizan texturas a distancia en comparación con el renderizado sin ellos, pero puede tener un coste de rendimiento (tanto al inicializar la imagen como durante el renderizado).
Por defecto, esta propiedad está establecida en false.
Nota: Es necesario establecer un modo mipFilter para que se utilicen los mipmaps generados.
Nota: Esta propiedad no es aplicable cuando el contenido de la textura se basa en un elemento Qt Quick referenciado por la propiedad sourceItem. La generación de mipmaps para texturas dinámicas no es factible debido a las implicaciones de rendimiento. Por lo tanto, el valor de esta propiedad se ignora para dichas texturas.
Véase también mipFilter.
indexUV : int
Esta propiedad establece el índice de coordenadas UV utilizado por esta textura. Dado que QtQuick3D soporta 2 conjuntos UV(0 o 1) por ahora, el valor será saturado al rango.
El valor por defecto es 0.
magFilter : enumeration
Esta propiedad determina cómo se muestrea la textura cuando está "ampliada", es decir, cuando un texel cubre más de un píxel en el espacio de la pantalla.
El valor por defecto es Texture.Linear.
| Constante | Descripción |
|---|---|
Texture.Nearest | utiliza el valor del texel más cercano. |
Texture.Linear | toma los cuatro texels más cercanos y los interpola bilinealmente. |
Nota: Si se utiliza Texture.None se utilizará por defecto Texture.Linear.
Véase también minFilter y mipFilter.
mappingMode : enumeration
Esta propiedad define qué método de mapeado utilizar al muestrear esta textura.
| Constante | Descripción |
|---|---|
Texture.UV | El valor por defecto. Adecuado para color base, difuso, opacidad, y la mayoría de otros mapas de textura. Realiza un mapeado UV estándar. La misma porción de la imagen siempre aparecerá en el mismo vértice, a menos que las coordenadas UV sean transformadas y animadas. |
Texture.Environment | Utilizado para specular reflection, esto hace que la imagen se proyecte sobre el material como si estuviera siendo reflejada. El uso de este modo para otro tipo de mapas de textura proporciona un efecto espejo. |
Texture.LightProbe | Es el modo por defecto para los mapas de esfera HDRI utilizados por las sondas de luz. Este modo no necesita ser configurado manualmente para objetos de Textura asociados con la propiedad lightProbe, porque se implica automáticamente. |
minFilter : enumeration
Esta propiedad determina cómo se muestrea la textura cuando está "minimizada", es decir, cuando un texel cubre menos de un píxel en el espacio de la pantalla.
El valor por defecto es Texture.Linear.
| Constante | Descripción |
|---|---|
Texture.Nearest | utiliza el valor del texel más cercano. |
Texture.Linear | toma los cuatro texels más cercanos y los interpola bilinealmente. |
Nota: Si se utiliza Texture.None se utilizará por defecto Texture.Linear.
Véase también magFilter y mipFilter.
mipFilter : enumeration
Esta propiedad determina cómo se muestrean los mipmaps de textura cuando un texel cubre menos de un píxel.
El valor por defecto es Texture.None.
| Constante | Descripción |
|---|---|
Texture.None | desactiva el uso de muestreo mipmap. |
Texture.Nearest | utiliza mipmapping y muestrea el valor del texel más cercano. |
Texture.Linear | utiliza mipmapping e interpola entre múltiples valores de texel. |
Nota: Esta propiedad no tendrá efecto en Texturas que no tengan mipmaps.
Ver también minFilter y magFilter.
pivotU : real
Esta propiedad establece la posición U del pivote que se utiliza al aplicar un rotationUV.
El valor por defecto es 0.0.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporcionan su propio código de sombreado, por lo que transformaciones como la configurada por esta propiedad son ignoradas y depende del código de sombreado proporcionado por la aplicación implementarlas.
Véase también rotationUV.
pivotV : real
Esta propiedad establece la posición V del pivote que se utiliza al aplicar un rotationUV.
El valor por defecto es 0.0.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporcionan su propio código de sombreado, por lo que transformaciones como la configurada por esta propiedad son ignoradas y depende del código de sombreado proporcionado por la aplicación implementarlas.
Véase también pivotU y rotationUV.
positionU : real
Esta propiedad desplaza la asignación de coordenadas U de izquierda a derecha.
El valor por defecto es 0.0.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporciona su propio código de sombreado, por lo que las transformaciones como la configurada por esta propiedad se ignoran y dependen del código de sombreado proporcionado por la aplicación para su implementación.
Véase también positionV.
positionV : real
Esta propiedad desplaza el mapeado de coordenadas V de abajo a arriba.
El valor por defecto es 0.0.
Nota: Qt Quick 3D utiliza datos de vértices al estilo OpenGL, independientemente de la API gráfica utilizada en tiempo de ejecución. Por lo tanto, la posición UV (0, 0) se refiere a la esquina inferior izquierda de los datos de la imagen.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporcionan su propio código shader, por lo que transformaciones como la configurada por esta propiedad son ignoradas y depende del código shader proporcionado por la aplicación implementarlas.
Véase también positionU.
rotationUV : real
Esta propiedad rota la textura alrededor del punto de pivote. Esto se define usando ángulos de Euler y para un valor positivo la rotación es en el sentido de las agujas del reloj.
El valor por defecto es 0.0.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporcionan su propio código shader, por lo que transformaciones como la configurada por esta propiedad son ignoradas y dependen del código shader proporcionado por la aplicación para ser implementadas.
Véase también pivotU y pivotV.
scaleU : real
Esta propiedad define como escalar la coordenada U de la textura cuando se mapea a las coordenadas UV de una malla.
Escalar el valor de U cuando se utiliza mosaico horizontal definirá cuántas veces se repite la textura de izquierda a derecha.
El valor por defecto es 1.0.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporcionan su propio código shader, por lo que transformaciones como la configurada por esta propiedad son ignoradas y dependen del código shader proporcionado por la aplicación para ser implementadas.
Véase también tilingModeHorizontal.
scaleV : real
Esta propiedad define como escalar la coordenada V de la textura cuando se mapea a las coordenadas UV de una malla.
Escalar el valor de V cuando se utiliza mosaico vertical definirá cuántas veces se repite una textura de abajo a arriba.
El valor por defecto es 1.0.
Nota: Esta propiedad es efectiva cuando la Textura se utiliza en combinación con un DefaultMaterial o PrincipledMaterial. Custom materials proporcionan su propio código shader, por lo que transformaciones como la configurada por esta propiedad son ignoradas y dependen del código shader proporcionado por la aplicación para ser implementadas.
Véase también tilingModeVertical.
source : url
Esta propiedad contiene la ubicación de un archivo de imagen o textura que contiene los datos utilizados por la textura.
La propiedad es una URL, con las mismas reglas que otras propiedades de origen, como Image.source. Con Texture, sólo se admiten los esquemas qrc y file. Cuando no hay ningún esquema presente y el valor es una ruta relativa, se asume que es relativa a la ubicación del componente (es decir, del archivo .qml ).
El archivo fuente puede tener cualquier formato de archivo de imagen convencional supported by Qt. Además, Texture soporta el mismo compressed texture file types que QtQuick::Image.
Nota: Los datos de textura leídos desde archivos de imagen como .png o .jpg implican almacenar las filas de píxeles dentro de la textura en un orden definido el motor de renderizado 3D Qt Quick. Cuando el archivo fuente es un contenedor de datos de textura, posiblemente comprimidos, estas transformaciones no pueden producirse en el nivel de los datos de píxel. Ejemplos de ello son los archivos .ktx o .pkm. En su lugar, la Textura implícitamente habilita el volteo vertical en el código del fragment shader para obtener resultados idénticos en pantalla. Esto se controla mediante la propiedad autoOrientation y puede desactivarse, si se desea.
Nota: Algunas herramientas de compresión de texturas pueden aplicar reflejo vertical automático (flipping) en los datos de la imagen. En las herramientas modernas esto es a menudo un ajuste opcional. Es importante ser consciente de los ajustes utilizados en el proceso de acondicionamiento de los recursos, porque una textura invertida inesperadamente, y por lo tanto una texturización incorrecta de los objetos, puede tener su causa en el propio recurso, fuera del control de la aplicación y del motor de renderizado. Cuando el activo lo requiera, las aplicaciones siempre pueden establecer ellas mismas la propiedad flipV.
Ver también sourceItem, textureData, autoOrientation, y flipV.
sourceItem : Item
Esta propiedad define un Item para ser usado como fuente de la textura. El uso de esta propiedad permite utilizar cualquier contenido 2D de Qt Quick como fuente de textura, renderizando ese elemento como una capa fuera de pantalla.
Si el ítem es un texture provider, no se utiliza ninguna textura adicional.
Si esta propiedad está establecida, entonces el valor de source será ignorado. Una textura debe utilizar un método para proporcionar datos de imagen, y establecer sólo uno de source, sourceItem, o textureData.
Nota: Actualmente los eventos de entrada son reenviados al Item usado como fuente de la textura sólo si el usuario está limitado a interactuar con una instancia de sourceItem a la vez. En otras palabras: puedes compartir el mismo Item entre múltiples Texturas, pero entonces no puedes tener interacción multitáctil con el mismo item en múltiples texturas al mismo tiempo. Así que es mejor usar una instancia de subescena 2D separada para cada instancia de Textura, si esperas manipular ítems interactivos dentro.
Nota: Se desaconseja encarecidamente utilizar esta propiedad en una textura a la que se haga referencia desde varias ventanas. Esto incluye el uso a través de View3D::importScene. Como la textura fuente creada por esta propiedad sólo es accesible por un hilo de renderizado, intentar compartirla entre múltiples instancias de QQuickWindow va a fallar, a menos que se utilice el bucle de renderizado basic de Qt Quick en lugar del predeterminado threaded. Ver Qt Quick Scene Graph para más información sobre los bucles de render Qt Quick.
Nota: Una Textura que contiene los resultados de un pase de renderizado fuera de pantalla de Qt Quick tendrá, en efecto, una orientación del eje Y diferente de la que utiliza una Textura que recibe su contenido a través de la propiedad source. Cuando se utiliza en combinación con DefaultMaterial o PrincipledMaterial, todo esto es transparente para la aplicación, ya que las transformaciones UV necesarias se aplican automáticamente siempre que la propiedad autoOrientation tenga el valor true, por lo que no es necesaria ninguna otra acción, independientemente de cómo se haya obtenido la textura. Sin embargo, al desarrollar custom materials el autor del código del shader debe tener esto en cuenta al muestrear la textura y trabajar con coordenadas UV.
Ver también source, textureData, y autoOrientation.
textureData : TextureData
Esta propiedad contiene una referencia a un componente TextureData que define el contenido y las propiedades de los datos de textura sin procesar.
Si se utiliza esta propiedad, el valor de source será ignorado. Una Textura debería utilizar un método para proporcionar datos de imagen, y establecer sólo uno de source, sourceItem, o textureData.
Ver también source, sourceItem, y Qt Quick 3D - Ejemplo de Textura Procedimental.
textureProvider : RenderExtension [since 6.7]
Esta propiedad contiene el RenderExtension que proporcionará el QRhiTexture que será utilizado por este elemento.
Nota: La textura creada por RenderExtension necesita estar disponible en registering con el motor.
Esta propiedad fue introducida en Qt 6.7.
Ver también TextureProviderExtension, RenderExtension, y QSSGRenderExtensionHelpers.
tilingModeDepth : enumeration
Esta propiedad controla cómo se mapea la textura cuando el valor de escala Z es mayor que 1.
Por defecto, esta propiedad se establece en Texture.Repeat.
| Constante | Descripción |
|---|---|
Texture.ClampToEdge | La textura no se mosaico, pero el valor en el borde se utiliza en su lugar. |
Texture.MirroredRepeat | La textura se repite y refleja sobre el eje Z. |
Texture.Repeat | La textura se repite sobre el eje Z. |
tilingModeHorizontal : enumeration
Controla cómo se mapea la textura cuando el valor de escala U es mayor que 1.
Por defecto, esta propiedad se establece en Texture.Repeat.
| Constante | Descripción |
|---|---|
Texture.ClampToEdge | La textura no se mosaico, pero el valor en el borde se utiliza en su lugar. |
Texture.MirroredRepeat | La textura se repite y refleja sobre el eje X. |
Texture.Repeat | La textura se repite sobre el eje X. |
Véase también scaleU.
tilingModeVertical : enumeration
Esta propiedad controla cómo se mapea la textura cuando el valor de escala V es mayor que 1.
Por defecto, esta propiedad se establece en Texture.Repeat.
| Constante | Descripción |
|---|---|
Texture.ClampToEdge | La textura no se mosaico, pero el valor en el borde se utiliza en su lugar. |
Texture.MirroredRepeat | La textura se repite y refleja sobre el eje Y. |
Texture.Repeat | La textura se repite sobre el eje Y. |
Véase también 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.
