Texture QML Type

Defines a texture for use in 3D scenes. More...

Import Statement:	import QtQuick3D
Inherits:	Object3D

• List of all members, including inherited members

Properties

• autoOrientation : bool
• flipU : bool
• flipV : bool
• generateMipmaps : bool
• indexUV : int
• magFilter : enumeration
• mappingMode : enumeration
• minFilter : enumeration
• mipFilter : enumeration
• pivotU : float
• pivotV : float
• positionU : float
• positionV : float
• rotationUV : float
• scaleU : float
• scaleV : float
• source : url
• sourceItem : Item
• textureData : TextureData
• tilingModeHorizontal : enumeration
• tilingModeVertical : enumeration

Detailed Description

A texture is technically any array of pixels (1D, 2D or 3D) and its related settings, such as minification and magnification filters, scaling and UV transformations.

The Texture type in Qt Quick 3D represents a two-dimensional image. Its use is typically to map onto / wrap around three-dimensional geometry to emulate additional detail which cannot be efficiently modelled in 3D. It can also be used to emulate other lighting effects, such as reflections.

When the geometry is being rendered, each location on its surface will be transformed to a corresponding location in the texture by transforming and interpolating the UV coordinates (texture coordinate) that have been set for the mesh's vertexes. The fragment shader program that is being used to render the active material will then typically sample the material's texture(s) at the given coordinates and use the sampled data in its light calculations.

Texture objects can source image data from:

• an image or texture file by using the source property,
• a Qt Quick Item by using the sourceItem property,
• or by setting the textureData property to a TextureData item subclass for defining the custom texture contents.

The following example maps the image "madewithqt.png" onto the default sphere mesh, and scales the UV coordinates to tile the image on the sphere surface.

Model {
    source: "#Sphere"
    materials: [ PrincipledMaterial {
            baseColorMap: Texture {
                source: "madewithqt.png"
                scaleU: 4.0
                scaleV: 4.0
            }
        }
    ]
}

The result looks as follows:

Original image	Mapped onto a sphere

See also Qt Quick 3D - Dynamic Texture Example and Qt Quick 3D - Procedural Texture Example.

Property Documentation

[since 6.2] autoOrientation : bool

This property determines if a texture transformation, such as flipping the V texture coordinate, is applied automatically for textures where this is typically relevant.

By default, this property is set to true.

Certain type of texture data, such as compressed textures loaded via the source property from a .ktx or .pkm file, or textures generated by rendering a Qt Quick scene via the sourceItem property, often have a different Y axis orientation when compared to textures loaded from image files, such as, .png or .jpg. Therefore, such a Texture would appear "upside down" compared to a Texture with its source set to a regular image file. To remedy this, any qualifying Texture gets an implicit UV transformation as if the flipV property was set to true. If this is not desired, set this property to false.

This property was introduced in Qt 6.2.

See also flipV.

flipU : bool

This property sets the use of the horizontally flipped texture coordinates.

The default is false.

See also flipV.

flipV : bool

This property sets the use of the vertically flipped texture coordinates.

The default is false.

See also flipU.

generateMipmaps : bool

This property determines if mipmaps are generated for textures that do not provide mipmap levels themselves. Using mipmaps along with mip filtering gives better visual quality when viewing textures at a distance compared rendering without them, but it may come at a performance cost (both when initializing the image and during rendering).

By default, this property is set to false.

See also mipFilter.

indexUV : int

This property sets the UV coordinate index used by this texture. Since QtQuick3D supports 2 UV sets(0 or 1) for now, the value will be saturated to the range.

The default is 0.

magFilter : enumeration

This property determines how the texture is sampled when a texel covers more than one pixel.

The default value is Texture.Linear.

Constant	Description
Texture.Nearest	uses the value of the closest texel.
Texture.Linear	takes the four closest texels and bilinearly interpolates them.

See also minFilter and mipFilter.

mappingMode : enumeration

This property defines which method of mapping to use when sampling this texture.

Constant	Description
Texture.UV	The default value. Suitable for base color, diffuse, opacity, and most other texture maps. Performs standard UV mapping. The same portion of the image will always appear on the same vertex, unless the UV coordinates are transformed and animated.
Texture.Environment	Used for specular reflection, this causes the image to be projected onto the material as though it was being reflected. Using this mode for other type of texture maps provides a mirror effect.
Texture.LightProbe	The default for HDRI sphere maps used by light probes. This mode does not need to be manually set for Texture objects associated with the lightProbe property, because it is implied automatically.

minFilter : enumeration

This property determines how the texture is sampled when a texel covers more than one pixel.

The default value is Texture.Linear.

Constant	Description
Texture.Nearest	uses the value of the closest texel.
Texture.Linear	takes the four closest texels and bilinearly interpolates them.

See also magFilter and mipFilter.

mipFilter : enumeration

This property determines how the texture mipmaps are sampled when a texel covers less than one pixel.

The default value is Texture.None.

Constant	Description
Texture.None	disables the usage of mipmap sampling.
Texture.Nearest	uses mipmapping and samples the value of the closest texel.
Texture.Linear	uses mipmapping and interpolates between multiple texel values.

See also minFilter and magFilter.

pivotU : float

This property sets the pivot U position which is used when applying a rotationUV.

The default is 0.0.

See also rotationUV.

pivotV : float

This property sets the pivot V position which is used when applying a rotationUV.

The default is 0.0.

See also pivotU and rotationUV.

positionU : float

This property offsets the U coordinate mapping from left to right.

The default is 0.0.

See also positionV.

positionV : float

This property offsets the V coordinate mapping from bottom to top.

The default is 0.0.

See also positionU.

rotationUV : float

This property rotates the texture around the pivot point. This is defined using euler angles and for a positive value rotation is clockwise.

The default is 0.0.

See also pivotU and pivotV.

scaleU : float

This property defines how to scale the U texture coordinate when mapping to a mesh's UV coordinates.

Scaling the U value when using horizontal tiling will define how many times the texture is repeated from left to right.

The default is 1.0.

See also tilingModeHorizontal.

scaleV : float

This property defines how to scale the V texture coordinate when mapping to a mesh's UV coordinates.

Scaling the V value when using vertical tiling will define how many times a texture is repeated from bottom to top.

The default is 1.0.

See also tilingModeVertical.

source : url

This property holds the location of an image or texture file containing the data used by the texture.

The property is a URL, with the same rules as other source properties, such as Image.source. With Texture, only the qrc and file schemes are supported. When no scheme is present and the value is a relative path, it is assumed to be relative to the component's (i.e. the .qml file's) location.

The source file can have any conventional image file format supported by Qt. In addition, Texture supports the same compressed texture file types as QtQuick::Image.

See also sourceItem, textureData, autoOrientation, and flipV.

sourceItem : Item

This property defines a Item to be used as the source of the texture. Using this property allows any 2D Qt Quick content to be used as a texture source by rendering that item as an offscreen layer.

If the item is a texture provider, no additional texture is used.

If this property is set, then the value of source will be ignored. A Texture should use one method to provide image data, and set only one of source, sourceItem, or textureData.

See also source, textureData, and autoOrientation.

textureData : TextureData

This property holds a reference to a TextureData component which defines the contents and properties of raw texture data.

If this property is used, then the value of source will be ignored. A Texture should use one method to provide image data, and set only one of source, sourceItem, or textureData.

See also source, sourceItem, and Qt Quick 3D - Procedural Texture Example.

tilingModeHorizontal : enumeration

Controls how the texture is mapped when the U scaling value is greater than 1.

By default, this property is set to Texture.Repeat.

Constant	Description
Texture.ClampToEdge	Texture is not tiled, but the value on the edge is used instead.
Texture.MirroredRepeat	Texture is repeated and mirrored over the X axis.
Texture.Repeat	Texture is repeated over the X axis.

See also scaleU.

tilingModeVertical : enumeration

This property controls how the texture is mapped when the V scaling value is greater than 1.

By default, this property is set to Texture.Repeat.

Constant	Description
Texture.ClampToEdge	Texture is not tiled, but the value on the edge is used instead.
Texture.MirroredRepeat	Texture is repeated and mirrored over the Y axis.
Texture.Repeat	Texture is repeated over the Y axis.

See also scaleV.