Qt Documentation

Qt 6.0
Qt Quick 3D
QML Types
Texture QML Type

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

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.

Note: A Material may use multiple textures to give the desired interaction with light in the 3D scene. It can represent the color of each texel on the geometry surface, but also other attributes of the surface. For instance, a "normal map" can represent the deviation from the geometry normals for each texel on the surface, emulating light interaction with finer details on the surface, such as cracks or bumps. See the principled material example for a demonstration of a material with multiple texture maps.

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

Property Documentation

flipV : bool

This property sets the use of the vertically flipped coordinates.

The default is false.

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.

Note: It is necessary to set a mipFilter mode for the generated mipmaps to be be used.

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.

Note: Using Texture.None here will default to Texture.Linear instead.

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 for diffuse and opacity maps, this causes the image to be stuck to the mesh. The same portion of the image will always appear on the same vertex (unless the UV properties are animated).
`Texture.Environment`	The default for specular reflection, this causes the image to be ‘projected’ onto the material as though it is being reflected. Using Environmental Mapping for diffuse maps provides a mirror effect.
`Texture.LightProbe`	The default for HDRI sphere maps used by light probes. Normally this does not need to be set when using a light probe, but may need to be set explicitly when using environment maps.

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.

Note: Using Texture.None here will default to Texture.Linear instead.

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.

Note: This property will have no effect on Textures that do not have mipmaps.

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 rotationUV.

positionU : float

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

The default is 0.0.

positionV : float

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

The default is 0.0.

Note: Qt Quick 3D uses OpenGL-style vertex data, regardless of the graphics API used at run time. The UV position (0, 0) is therefore referring to the bottom-left corner of the image data.

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.

Note: As Quick has the Y axis pointing downwards, while in Qt Quick 3D it points upwards, the orientation of textures may appear different by default. The flipV property may be used to change the orientation.

See also sourceItem, textureData, 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.

Note: Currently there is no way to forward input events to the Item used as a texture source.

Note: Using this property in a Texture that is referenced from multiple windows is strongly discouraged. This includes usage via View3D::importScene. As the source texture created by this property is only accessible by one render thread, attempting to share it between multiple QQuickWindow instances is going to fail, unless the basic render loop of Qt Quick is used instead of the default threaded one. See Qt Quick Scene Graph on more information about the Qt Quick render loops.

See also source and textureData.

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.

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.

© 2021 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.

Qt Documentation

Contents

Texture QML Type

Properties

Detailed Description

Property Documentation