QSGTexture

The QSGTexture class is the base class for textures used in the scene graph. More

Inheritance diagram of PySide6.QtQuick.QSGTexture

Inherited by: QSGDynamicTexture

Synopsis

Functions

Virtual functions

Detailed Description

Users can freely implement their own texture classes to support arbitrary input textures, such as YUV video frames or 8 bit alpha masks. The scene graph provides a default implementation for RGBA textures.The default implementation is not instantiated directly, rather they are constructed via factory functions, such as createTextureFromImage() .

With the default implementation, each QSGTexture is backed by a QRhiTexture, which in turn contains a native texture object, such as an OpenGL texture or a Vulkan image.

The size in pixels is given by textureSize() . hasAlphaChannel() reports if the texture contains opacity values and hasMipmaps() reports if the texture contains mipmap levels.

Materials that work with textures reimplement updateSampledImage() to provide logic that decides which QSGTexture ‘s underlying native texture should be exposed at a given shader resource binding point.

QSGTexture does not separate image (texture) and sampler objects. The parameters for filtering and wrapping can be specified with setMipmapFiltering() , setFiltering() , setHorizontalWrapMode() and setVerticalWrapMode() . The scene graph and Qt’s graphics abstraction takes care of creating separate sampler objects, when applicable.

Texture Atlases

Some scene graph backends use texture atlasses, grouping multiple small textures into one large texture. If this is the case, the function isAtlasTexture() will return true. Atlases are used to aid the rendering algorithm to do better sorting which increases performance. Atlases are also essential for batching (merging together geometry to reduce the number of draw calls), because two instances of the same material using two different QSGTextures are not batchable, whereas if both QSGTextures refer to the same atlas, batching can happen, assuming the materials are otherwise compatible.

The location of the texture inside the atlas is given with the normalizedTextureSubRect() function.

If the texture is used in such a way that atlas is not preferable, the function removedFromAtlas() can be used to extract a non-atlased copy.

Note

All classes with QSG prefix should be used solely on the scene graph’s rendering thread. See Scene Graph and Rendering for more information.

See also

Scene Graph - Rendering FBOs

class PySide6.QtQuick.QSGTexture

Constructs the QSGTexture base class.

PySide6.QtQuick.QSGTexture.WrapMode

Specifies how the sampler should treat texture coordinates.

Constant

Description

QSGTexture.Repeat

Only the fractional part of the texture coordinate is used, causing values above 1 and below 0 to repeat.

QSGTexture.ClampToEdge

Values above 1 are clamped to 1 and values below 0 are clamped to 0.

QSGTexture.MirroredRepeat

When the texture coordinate is even, only the fractional part is used. When odd, the texture coordinate is set to 1 - fractional part. This value has been introduced in Qt 5.10.

PySide6.QtQuick.QSGTexture.Filtering

Specifies how sampling of texels should filter when texture coordinates are not pixel aligned.

Constant

Description

QSGTexture.None

No filtering should occur. This value is only used together with setMipmapFiltering() .

QSGTexture.Nearest

Sampling returns the nearest texel.

QSGTexture.Linear

Sampling returns a linear interpolation of the neighboring texels.

PySide6.QtQuick.QSGTexture.AnisotropyLevel

Specifies the anisotropic filtering level to be used when the texture is not screen aligned.

Constant

Description

QSGTexture.AnisotropyNone

No anisotropic filtering.

QSGTexture.Anisotropy2x

2x anisotropic filtering.

QSGTexture.Anisotropy4x

4x anisotropic filtering.

QSGTexture.Anisotropy8x

8x anisotropic filtering.

QSGTexture.Anisotropy16x

16x anisotropic filtering.

New in version 5.9.

PySide6.QtQuick.QSGTexture.anisotropyLevel()
Return type

AnisotropyLevel

Returns the anisotropy level in use for filtering this texture.

PySide6.QtQuick.QSGTexture.comparisonKey()
Return type

int

Returns a key suitable for comparing textures. Typically used in compare() implementations.

Just comparing QSGTexture pointers is not always sufficient because two QSGTexture instances that refer to the same native texture object underneath should also be considered equal. Hence the need for this function.

Implementations of this function are not expected to, and should not create any graphics resources (native texture objects) in case there are none yet.

A QSGTexture that does not have a native texture object underneath is typically not equal to any other QSGTexture , so the return value has to be crafted accordingly. There are exceptions to this, in particular when atlasing is used (where multiple textures share the same atlas texture under the hood), that is then up to the subclass implementations to deal with as appropriate.

Warning

This function can only be called from the rendering thread.

PySide6.QtQuick.QSGTexture.convertToNormalizedSourceRect(rect)
Parameters

rectPySide6.QtCore.QRectF

Return type

PySide6.QtCore.QRectF

Returns rect converted to normalized coordinates.

PySide6.QtQuick.QSGTexture.filtering()
Return type

Filtering

Returns the sampling mode to be used for this texture.

See also

setFiltering()

PySide6.QtQuick.QSGTexture.hasAlphaChannel()
Return type

bool

Returns true if the texture data contains an alpha channel.

PySide6.QtQuick.QSGTexture.hasMipmaps()
Return type

bool

Returns true if the texture data contains mipmap levels.

PySide6.QtQuick.QSGTexture.horizontalWrapMode()
Return type

WrapMode

Returns the horizontal wrap mode to be used for this texture.

PySide6.QtQuick.QSGTexture.isAtlasTexture()
Return type

bool

Returns whether this texture is part of an atlas or not.

The default implementation returns false.

PySide6.QtQuick.QSGTexture.mipmapFiltering()
Return type

Filtering

Returns whether mipmapping should be used when sampling from this texture.

PySide6.QtQuick.QSGTexture.normalizedTextureSubRect()
Return type

PySide6.QtCore.QRectF

Returns the rectangle inside textureSize() that this texture represents in normalized coordinates.

The default implementation returns a rect at position (0, 0) with width and height of 1.

PySide6.QtQuick.QSGTexture.setAnisotropyLevel(level)
Parameters

levelAnisotropyLevel

Sets the level of anisotropic filtering to level. The default value is AnisotropyNone , which means no anisotropic filtering is enabled.

Note

The request may be ignored depending on the graphics API in use. There is no guarantee anisotropic filtering is supported at run time.

PySide6.QtQuick.QSGTexture.setFiltering(filter)
Parameters

filterFiltering

Sets the sampling mode to filter.

See also

filtering()

PySide6.QtQuick.QSGTexture.setHorizontalWrapMode(hwrap)
Parameters

hwrapWrapMode

Sets the horizontal wrap mode to hwrap

PySide6.QtQuick.QSGTexture.setMipmapFiltering(filter)
Parameters

filterFiltering

Sets the mipmap sampling mode to filter.

Setting the mipmap filtering has no effect it the texture does not have mipmaps.

PySide6.QtQuick.QSGTexture.setVerticalWrapMode(vwrap)
Parameters

vwrapWrapMode

Sets the vertical wrap mode to vwrap

PySide6.QtQuick.QSGTexture.textureSize()
Return type

PySide6.QtCore.QSize

Returns the size of the texture.

PySide6.QtQuick.QSGTexture.verticalWrapMode()
Return type

WrapMode

Returns the vertical wrap mode to be used for this texture.