En esta página

Texture QML Type

Define una textura para su uso en escenas 3D. Más información...

Import Statement: import QtQuick3D
Inherits:

Object3D

Inherited By:

CubeMapTexture

Propiedades

Descripción detallada

Una textura es, técnicamente, cualquier matriz de píxeles (1D, 2D o 3D) y sus ajustes relacionados, como los filtros de reducción y ampliación, el escalado y las transformaciones UV.

El tipo «Texture» en « Qt Quick » 3D representa una imagen bidimensional. Su uso habitual consiste en aplicarla o envolverla alrededor de una geometría tridimensional para emular detalles adicionales que no pueden modelarse de forma eficiente en 3D. También puede utilizarse para emular otros efectos de iluminación, como los reflejos.

Aunque «Texture» en sí misma siempre representa una textura 2D, también hay disponibles otros tipos de texturas a través de subclases de «Texture». Por ejemplo, para crear una textura de mapa cúbico con 6 caras, utiliza el tipo « CubeMapTexture ».

Cuando se renderiza la geometría, cada punto de su superficie se transforma en un punto correspondiente de la textura mediante la transformación e interpolación de las coordenadas UV (coordenadas de textura) que se han establecido para los vértices de la malla. El programa de sombreado de fragmentos que se utiliza para renderizar el material activo suele, a continuación, muestrear la(s) textura(s) del material en las coordenadas dadas y utilizar los datos muestreados en sus cálculos de luz.

Nota: Un material puede utilizar varias texturas para proporcionar la interacción deseada con la luz en la escena 3D. Puede representar el color de cada texel de la superficie de la geometría, pero también otros atributos de la superficie. Por ejemplo, un «mapa de normales» puede representar la desviación respecto a 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. Consulta el ejemplo de material «principled» 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 mediante la propiedad ` source `,
  • un objeto « Qt Quick » ( Item ) mediante la propiedad « sourceItem »,
  • o estableciendo la propiedad « textureData » en una subclase de « TextureData » para definir el contenido personalizado de la textura.

El siguiente ejemplo asigna la imagen «madewithqt.png» a la malla esférica predeterminada y escala las coordenadas UV para repetir 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 originalAplicada a una esfera

Logotipo «Creado con Qt»

Esfera con el logotipo de Qt como mapa de texturas

Véase también Qt Quick 3D - Ejemplo de textura procedural.

Documentación de propiedades

autoOrientation : bool [since 6.2]

Esta propiedad determina si se aplica automáticamente una transformación de textura —como invertir la coordenada de textura V— a aquellas texturas en las que suele ser pertinente.

Por defecto, esta propiedad está establecida en «true».

Ciertos tipos de datos de textura, como las texturas comprimidas cargadas mediante la propiedad « source » desde un archivo .ktx o .pkm, o las texturas generadas al renderizar una escena « Qt Quick » mediante la propiedad « sourceItem », suelen tener una orientación del eje Y diferente en comparación con las texturas cargadas desde archivos de imagen, como .png o .jpg. Por lo tanto, dicha textura aparecería «al revés» en comparación con una textura cuya fuente sea un archivo de imagen normal. Para solucionar esto, cualquier textura que cumpla los requisitos recibe una transformación UV implícita, como si la propiedad flipV estuviera establecida en «true». Si no se desea que esto ocurra, establezca esta propiedad en «false».

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de shader, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de shader proporcionado por la aplicación.

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 invertidas horizontalmente.

El valor predeterminado es «false».

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de sombreado, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de sombreado proporcionado por la aplicación.

Véase también « flipV ».

flipV : bool

Esta propiedad establece si se utilizan las coordenadas de textura invertidas verticalmente.

El valor predeterminado es «false».

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de sombreador, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de sombreador proporcionado por la aplicación.

Véase también « flipU ».

generateMipmaps : bool

Esta propiedad determina si se generan mipmaps para las texturas que no proporcionan sus propios niveles de mipmap. El uso de mipmaps junto con el filtrado mip ofrece una mejor calidad visual al visualizar texturas a distancia en comparación con el renderizado sin ellos, pero puede suponer un coste en cuanto al 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 de « Qt Quick » al que hace referencia la propiedad « sourceItem ». La generación de mipmaps para texturas dinámicas no es viable debido a las implicaciones en el 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 que utiliza esta textura. Dado que « QtQuick3D » admite por ahora dos conjuntos de UV (0 o 1), el valor se limitará a ese rango.

El valor por defecto es 0.

magFilter : enumeration

Esta propiedad determina cómo se muestrea la textura cuando se «amplía», es decir, cuando un texel abarca más de un píxel en el espacio de la pantalla.

El valor por defecto es « Texture.Linear ».

ConstanteDescripción
Texture.Nearestutiliza el valor del texel más cercano.
Texture.Lineartoma los cuatro texeles más cercanos y los interpola de forma bilineal.

Nota: Si se utiliza « Texture.None » aquí, se establecerá por defecto « Texture.Linear » en su lugar.

Véase también minFilter y mipFilter.

mappingMode : enumeration

Esta propiedad define qué método de mapeo se debe utilizar al muestrear esta textura.

ConstanteDescripción
Texture.UVEl valor por defecto. Adecuado para el color base, la difusión, la opacidad y la mayoría de los demás mapas de textura. Realiza un mapeado UV estándar. La misma parte de la imagen aparecerá siempre en el mismo vértice, a menos que se transformen y animen las coordenadas UV.
Texture.EnvironmentCuando se utiliza para « specular reflection », esto hace que la imagen se proyecte sobre el material como si se reflejara. El uso de este modo para otros tipos de mapas de textura proporciona un efecto de espejo.
Texture.LightProbeEs el valor por defecto para los mapas esféricos HDRI utilizados por las sondas de luz. No es necesario configurar manualmente este modo para los objetos de textura asociados a la propiedad « lightProbe », ya que se aplica automáticamente.

minFilter : enumeration

Esta propiedad determina cómo se muestrea la textura cuando está «minimizada», es decir, cuando un texel ocupa menos de un píxel en el espacio de la pantalla.

El valor por defecto es « Texture.Linear ».

ConstanteDescripción
Texture.Nearestutiliza el valor del texel más cercano.
Texture.Lineartoma los cuatro texeles más cercanos y los interpola de forma bilineal.

Nota: Sise utiliza « Texture.None » aquí, el valor por defecto será « Texture.Linear ».

Véase también magFilter y mipFilter.

mipFilter : enumeration

Esta propiedad determina cómo se muestrean los mipmaps de la textura cuando un texel ocupa menos de un píxel.

El valor por defecto es « Texture.None ».

ConstanteDescripción
Texture.Nonedesactiva el muestreo de mipmaps.
Texture.Nearestutiliza mipmapping y muestrea el valor del texel más cercano.
Texture.Linearutiliza mipmapping e interpola entre varios valores de texel.

Nota: Esta propiedad no tendrá ningún efecto en las texturas que no cuenten con mipmaps.

Véase también minFilter y magFilter.

pivotU : real

Esta propiedad establece la posición del punto de pivote U que se utiliza al aplicar un « rotationUV ».

El valor por defecto es 0,0.

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de sombreador, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de sombreador proporcionado por la aplicación.

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 surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de sombreador, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de sombreador proporcionado por la aplicación.

Véase también « pivotU » y « rotationUV ».

positionU : real

Esta propiedad desplaza la correspondencia de la coordenada U de izquierda a derecha.

El valor por defecto es 0,0.

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de shader, por lo que las transformaciones como la que configura esta propiedad se ignoran y su implementación depende del código de shader proporcionado por la aplicación.

Véase también « positionV ».

positionV : real

Esta propiedad desplaza la asignación de la coordenada V de abajo hacia arriba.

El valor por defecto es 0,0.

Nota: « Qt Quick 3D» utiliza datos de vértices al estilo de OpenGL, independientemente de la API gráfica utilizada en tiempo de ejecución. Por lo tanto, la posición UV (0, 0) hace referencia a la esquina inferior izquierda de los datos de la imagen.

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un DefaultMaterial o un PrincipledMaterial. Custom materials proporcionan su propio código de shader, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de shader proporcionado por la aplicación.

Véase también « positionU ».

rotationUV : real

Esta propiedad gira la textura alrededor del punto de pivote. Se define mediante ángulos de Euler y, si el valor es positivo, la rotación se realiza en el sentido de las agujas del reloj.

El valor por defecto es 0,0.

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de sombreado, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de sombreado proporcionado por la aplicación.

Véase también « pivotU » y « pivotV ».

scaleU : real

Esta propiedad define cómo escalar la coordenada U de la textura al asignarla a las coordenadas UV de una malla.

El escalado del valor U al utilizar el mosaico horizontal definirá cuántas veces se repite la textura de izquierda a derecha.

El valor predeterminado es 1,0.

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de sombreador, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de sombreador proporcionado por la aplicación.

Véase también tilingModeHorizontal.

scaleV : real

Esta propiedad define cómo escalar la coordenada de textura V al asignarla a las coordenadas UV de una malla.

El escalado del valor V al utilizar el mosaico vertical definirá cuántas veces se repite una textura de abajo hacia arriba.

El valor predeterminado es 1,0.

Nota: Esta propiedad surte efecto cuando la textura se utiliza en combinación con un «DefaultMaterial» o un « PrincipledMaterial ». Los « Custom materials » proporcionan su propio código de sombreado, por lo que las transformaciones como la configurada por esta propiedad se ignoran y su implementación depende del código de sombreado proporcionado por la aplicación.

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, solo se admiten los esquemas qrc y file. Cuando no hay ningún esquema y el valor es una ruta relativa, se supone que es relativa a la ubicación del componente (es decir, del archivo .qml ).

El archivo de origen puede tener cualquier formato de archivo de imagen convencional supported by Qt. Además, `Texture` admite los mismos esquemas compressed texture file types que `QtQuick::Image`.

Nota: Los datosde textura leídos de archivos de imagen como .png o .jpg implican almacenar las filas de píxeles dentro de la textura en un orden definido por el motor de renderizado 3D Qt Quick. Cuando el archivo de origen es un contenedor de datos de textura —posiblemente comprimidos—, dichas transformaciones no pueden realizarse a nivel de los datos de píxeles. Ejemplos de ello son los archivos .ktx o .pkm. En su lugar, la textura habilita implícitamente el volteo vertical en el código del sombreador de fragmentos 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 un reflejo vertical automático a los datos de la imagen. En las herramientas modernas, esto suele ser una configuración opcional. Es importante tener en cuenta la configuración utilizada en el proceso de acondicionamiento de recursos, ya que una textura volteada de forma inesperada —y, por lo tanto, un texturizado incorrecto de los objetos— puede tener su causa principal en el propio recurso, fuera del control de la aplicación y del motor de renderizado. Cuando el recurso lo requiera, las aplicaciones siempre pueden establecer ellas mismas la propiedad flipV.

Véase también sourceItem, textureData, autoOrientation y flipV.

sourceItem : Item

Esta propiedad define un elemento que se utilizará como fuente de la textura. El uso de esta propiedad permite utilizar cualquier contenido 2D de Qt Quick como fuente de textura, representando dicho elemento como una capa fuera de pantalla.

Si el elemento es un ` texture provider`, no se utiliza ninguna textura adicional.

Si se establece esta propiedad, se ignorará el valor de ` source `. Una textura debe utilizar un único método para proporcionar datos de imagen y establecer únicamente una de las siguientes opciones: `source`, `sourceItem` o ` textureData`.

Nota: Actualmente , los eventos de entrada se reenvían al elemento utilizado como fuente de textura solo si el usuario está limitado a interactuar con una única instancia de «sourceItem» a la vez. En otras palabras: puedes compartir el mismo «Item» entre varias texturas, pero en ese caso no podrás tener una interacción multitáctil con el mismo «Item» en varias texturas al mismo tiempo. Por lo tanto, es mejor utilizar una instancia de subescena 2D independiente para cada instancia de «Textura», si tienes previsto manipular elementos interactivos en su interior.

Nota: Se desaconseja encarecidamenteel uso de esta propiedad en una textura a la que se hace referencia desde varias ventanas. Esto incluye el uso a través de View3D::importScene. Dado que solo un hilo de renderizado puede acceder a la textura fuente creada por esta propiedad, cualquier intento de compartirla entre varias instancias de QQuickWindow fracasará, a menos que se utilice el bucle de renderizado basic de Qt Quick en lugar del predeterminado threaded. Consulta «Qt Quick SceneGraph» para obtener más información sobre los bucles de renderizado Qt Quick.

Nota: Una textura que contenga los resultados de una pasada de renderizado fuera de pantalla de Qt Quick tendrá, en la práctica, una orientación del eje Y diferente a 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 resulta transparente para la aplicación, ya que las transformaciones UV necesarias se aplican automáticamente siempre que la propiedad « autoOrientation » esté establecida en «true», por lo que no se necesita ninguna acción adicional, independientemente de cómo se haya obtenido la textura. Sin embargo, al desarrollar custom materials, el autor del código del sombreador debe tener esto en cuenta a la hora de muestrear la textura y trabajar con coordenadas UV.

Véase 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, se ignorará el valor de « source ». Una textura debe utilizar un único método para proporcionar los datos de imagen y establecer únicamente uno de los siguientes: «source», « sourceItem » o «textureData».

Véase también « source» , « sourceItem » y «Qt Quick 3D - Ejemplo de textura procedural».

textureProvider : RenderExtension [since 6.7]

Esta propiedad contiene el RenderExtension que proporcionará el QRhiTexture que utilizará este elemento.

Nota: La textura creada por RenderExtension debe ponerse a disposición del motor mediante registering.

Esta propiedad se introdujo en Qt 6.7.

Véase también TextureProviderExtension, RenderExtension y QSSGRenderExtensionHelpers.

tilingModeDepth : enumeration

Esta propiedad controla cómo se asigna la textura cuando el valor de escalado Z es superior a 1.

Por defecto, esta propiedad está establecida en « Texture.Repeat ».

ConstanteDescripción
Texture.ClampToEdgeLa textura no se repite, sino que se utiliza el valor del borde.
Texture.MirroredRepeatLa textura se repite y se refleja a lo largo del eje Z.
Texture.RepeatLa textura se repite a lo largo del eje Z.

tilingModeHorizontal : enumeration

Determina cómo se asigna la textura cuando el valor de escalado U es superior a 1.

Por defecto, esta propiedad está establecida en « Texture.Repeat ».

ConstanteDescripción
Texture.ClampToEdgeLa textura no se repite, sino que se utiliza el valor del borde.
Texture.MirroredRepeatLa textura se repite y se refleja sobre el eje X.
Texture.RepeatLa textura se repite a lo largo del eje X.

Véase también scaleU.

tilingModeVertical : enumeration

Esta propiedad controla cómo se asigna la textura cuando el valor de escalado V es superior a 1.

Por defecto, esta propiedad está establecida en « Texture.Repeat ».

ConstanteDescripción
Texture.ClampToEdgeLa textura no se repite, sino que se utiliza el valor del borde.
Texture.MirroredRepeatLa textura se repite y se refleja sobre el eje Y.
Texture.RepeatLa textura se repite a lo largo del 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.