QSGTexture Class | Qt Quick 5.9

Qt 5.9 | Qt Quick | C++ Classes | QSGTexture

Qt 5.9.3 Reference Documentation

# QSGTexture Class

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

Header: | #include <QSGTexture>
qmake: | QT += quick
Inherited By: | QSGDynamicTexture

- List of all members, including inherited members

## Public Types

enum | AnisotropyLevel { AnisotropyNone, Anisotropy2x, Anisotropy4x, Anisotropy8x, Anisotropy16x }
enum | Filtering { None, Nearest, Linear }
enum | WrapMode { Repeat, ClampToEdge }

## Public Functions

| QSGTexture()
| ~QSGTexture()
QSGTexture::AnisotropyLevel | anisotropyLevel() const
virtual void | bind() = 0
QRectF | convertToNormalizedSourceRect(const QRectF &rect) const
QSGTexture::Filtering | filtering() const
virtual bool | hasAlphaChannel() const = 0
virtual bool | hasMipmaps() const = 0
QSGTexture::WrapMode | horizontalWrapMode() const
virtual bool | isAtlasTexture() const
QSGTexture::Filtering | mipmapFiltering() const
virtual QRectF | normalizedTextureSubRect() const
virtual QSGTexture * | removedFromAtlas() const
void | setAnisotropyLevel(AnisotropyLevel level)
void | setFiltering(Filtering filter)
void | setHorizontalWrapMode(WrapMode hwrap)
void | setMipmapFiltering(Filtering filter)
void | setVerticalWrapMode(WrapMode vwrap)
virtual int | textureId() const = 0
virtual QSize | textureSize() const = 0
void | updateBindOptions(bool force = false)
QSGTexture::WrapMode | verticalWrapMode() const

## Detailed Description

The QSGTexture class is a baseclass for textures used in the scene graph.

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 backend provides a default implementation of normal color textures. As the implementation of these may be hardware specific, they are constructed via the factory function QQuickWindow::createTextureFromImage().

The texture is a wrapper around an OpenGL texture, which texture id is given by textureId() and which size in pixels is given by textureSize(). hasAlphaChannel() reports if the texture contains opacity values and hasMipmaps() reports if the texture contains mipmap levels.

To use a texture, call the bind() function. The texture parameters specifying how the texture is bound, can be specified with setMipmapFiltering(), setFiltering(), setHorizontalWrapMode() and setVerticalWrapMode(). The texture will internally try to store these values to minimize the OpenGL state changes when the texture is bound.

### Texture Atlasses

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. Atlasses are used to aid the rendering algorithm to do better sorting which increases performance. 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-atlassed 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 and Scene Graph - Rendering FBOs in a thread.

## Member Type Documentation

### enum QSGTexture::AnisotropyLevel

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

Constant | Value | Description
--- | --- | ---
`QSGTexture::AnisotropyNone` | `0` | No anisotropic filtering.
`QSGTexture::Anisotropy2x` | `1` | 2x anisotropic filtering.
`QSGTexture::Anisotropy4x` | `2` | 4x anisotropic filtering.
`QSGTexture::Anisotropy8x` | `3` | 8x anisotropic filtering.
`QSGTexture::Anisotropy16x` | `4` | 16x anisotropic filtering.

This enum was introduced or modified in Qt 5.9.

### enum QSGTexture::Filtering

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

Constant | Value | Description
--- | --- | ---
`QSGTexture::None` | `0` | No filtering should occur. This value is only used together with setMipmapFiltering().
`QSGTexture::Nearest` | `1` | Sampling returns the nearest texel.
`QSGTexture::Linear` | `2` | Sampling returns a linear interpolation of the neighboring texels.

### enum QSGTexture::WrapMode

Specifies how the texture should treat texture coordinates.

Constant | Value | Description
--- | --- | ---
`QSGTexture::Repeat` | `0` | Only the factional part of the texture coordiante is used, causing values above 1 and below 0 to repeat.
`QSGTexture::ClampToEdge` | `1` | Values above 1 are clamped to 1 and values below 0 are clamped to 0.

## Member Function Documentation

### QSGTexture::QSGTexture()

Constructs the QSGTexture base class.

### QSGTexture::~QSGTexture()

Destroys the QSGTexture.

### QSGTexture::AnisotropyLevel QSGTexture::anisotropyLevel() const

Returns the anisotropy level in use for filtering this texture.

This function was introduced in Qt 5.9.

See also setAnisotropyLevel().

### `[pure virtual]` void QSGTexture::bind()

Call this function to bind this texture to the current texture target.

Binding a texture may also include uploading the texture data from a previously set QImage.

Warning: This function can only be called from the rendering thread.

### QRectF QSGTexture::convertToNormalizedSourceRect(const QRectF &rect) const

Returns rect converted to normalized coordinates.

See also normalizedTextureSubRect().

### QSGTexture::Filtering QSGTexture::filtering() const

Returns the sampling mode to be used for this texture.

See also setFiltering().

### `[pure virtual]` bool QSGTexture::hasAlphaChannel() const

Returns true if the texture data contains an alpha channel.

### `[pure virtual]` bool QSGTexture::hasMipmaps() const

Returns true if the texture data contains mipmap levels.

### QSGTexture::WrapMode QSGTexture::horizontalWrapMode() const

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

See also setHorizontalWrapMode().

### `[virtual]` bool QSGTexture::isAtlasTexture() const

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

The default implementation returns false.

### QSGTexture::Filtering QSGTexture::mipmapFiltering() const

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

See also setMipmapFiltering().

### `[virtual]` QRectF QSGTexture::normalizedTextureSubRect() const

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.

### `[virtual]` QSGTexture *QSGTexture::removedFromAtlas() const

This function returns a copy of the current texture which is removed from its atlas.

The current texture remains unchanged, so texture coordinates do not need to be updated.

Removing a texture from an atlas is primarily useful when passing it to a shader that operates on the texture coordinates 0-1 instead of the texture subrect inside the atlas.

If the texture is not part of a texture atlas, this function returns 0.

Implementations of this function are recommended to return the same instance for multiple calls to limit memory usage.

Warning: This function can only be called from the rendering thread.

### void QSGTexture::setAnisotropyLevel(AnisotropyLevel level)

Sets the level of anisotropic filtering to be used for the upcoming bind() call to level. The default value is QSGTexture::AnisotropyNone, which means no anisotropic filtering is enabled.

This function was introduced in Qt 5.9.

See also anisotropyLevel().

### void QSGTexture::setFiltering(Filtering filter)

Sets the sampling mode to be used for the upcoming bind() call to filter.

See also filtering().

### void QSGTexture::setHorizontalWrapMode(WrapMode hwrap)

Sets the horizontal wrap mode to be used for the upcoming bind() call to hwrap

See also horizontalWrapMode().

### void QSGTexture::setMipmapFiltering(Filtering filter)

Sets the mipmap sampling mode to be used for the upcoming bind() call to filter.

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

See also mipmapFiltering() and hasMipmaps().

### void QSGTexture::setVerticalWrapMode(WrapMode vwrap)

Sets the vertical wrap mode to be used for the upcoming bind() call to vwrap

See also verticalWrapMode().

### `[pure virtual]` int QSGTexture::textureId() const

Returns the OpenGL texture id for this texture.

The default value is 0, indicating that it is an invalid texture id.

The function should at all times return the correct texture id.

Warning: This function can only be called from the rendering thread.

### `[pure virtual]` QSize QSGTexture::textureSize() const

Returns the size of the texture.

### void QSGTexture::updateBindOptions(bool force = false)

Update the texture state to match the filtering, mipmap and wrap options currently set.

If force is true, all properties will be updated regardless of weither they have changed or not.

### QSGTexture::WrapMode QSGTexture::verticalWrapMode() const

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

See also setVerticalWrapMode().