Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
QSGTexture Class Referenceabstract

\inmodule QtQuick More...

#include <qsgtexture.h>

+ Inheritance diagram for QSGTexture:
+ Collaboration diagram for QSGTexture:

Public Types

enum  WrapMode { Repeat , ClampToEdge , MirroredRepeat }
 Specifies how the sampler should treat texture coordinates. More...
 
enum  Filtering { None , Nearest , Linear }
 Specifies how sampling of texels should filter when texture coordinates are not pixel aligned. More...
 
enum  AnisotropyLevel {
  AnisotropyNone , Anisotropy2x , Anisotropy4x , Anisotropy8x ,
  Anisotropy16x
}
 Specifies the anisotropic filtering level to be used when the texture is not screen aligned. More...
 

Public Member Functions

 QSGTexture ()
 Constructs the QSGTexture base class.
 
 ~QSGTexture () override
 Destroys the QSGTexture.
 
virtual qint64 comparisonKey () const =0
 Returns a key suitable for comparing textures.
 
virtual QRhiTexturerhiTexture () const
 
virtual QSize textureSize () const =0
 Returns the size of the texture in pixels.
 
virtual bool hasAlphaChannel () const =0
 Returns true if the texture data contains an alpha channel.
 
virtual bool hasMipmaps () const =0
 Returns true if the texture data contains mipmap levels.
 
virtual QRectF normalizedTextureSubRect () const
 Returns the rectangle inside textureSize() that this texture represents in normalized coordinates.
 
virtual bool isAtlasTexture () const
 Returns whether this texture is part of an atlas or not.
 
virtual QSGTextureremovedFromAtlas (QRhiResourceUpdateBatch *resourceUpdates=nullptr) const
 This function returns a copy of the current texture which is removed from its atlas.
 
virtual void commitTextureOperations (QRhi *rhi, QRhiResourceUpdateBatch *resourceUpdates)
 Call this function to enqueue image upload operations to resourceUpdates, in case there are any pending ones.
 
void setMipmapFiltering (Filtering filter)
 Sets the mipmap sampling mode to filter.
 
QSGTexture::Filtering mipmapFiltering () const
 Returns whether mipmapping should be used when sampling from this texture.
 
void setFiltering (Filtering filter)
 Sets the sampling mode to filter.
 
QSGTexture::Filtering filtering () const
 Returns the sampling mode to be used for this texture.
 
void setAnisotropyLevel (AnisotropyLevel level)
 Sets the level of anisotropic filtering to level.
 
QSGTexture::AnisotropyLevel anisotropyLevel () const
 Returns the anisotropy level in use for filtering this texture.
 
void setHorizontalWrapMode (WrapMode hwrap)
 Sets the horizontal wrap mode to hwrap.
 
QSGTexture::WrapMode horizontalWrapMode () const
 Returns the horizontal wrap mode to be used for this texture.
 
void setVerticalWrapMode (WrapMode vwrap)
 Sets the vertical wrap mode to vwrap.
 
QSGTexture::WrapMode verticalWrapMode () const
 Returns the vertical wrap mode to be used for this texture.
 
QRectF convertToNormalizedSourceRect (const QRectF &rect) const
 Returns rect converted to normalized coordinates.
 
- Public Member Functions inherited from QObject
Q_INVOKABLE QObject (QObject *parent=nullptr)
 Constructs an object with parent object parent.
 
virtual ~QObject ()
 Destroys the object, deleting all its child objects.
 
virtual bool event (QEvent *event)
 This virtual function receives events to an object and should return true if the event e was recognized and processed.
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 Filters events if this object has been installed as an event filter for the watched object.
 
QString objectName () const
 
Q_WEAK_OVERLOAD void setObjectName (const QString &name)
 Sets the object's name to name.
 
void setObjectName (QAnyStringView name)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
QBindable< QStringbindableObjectName ()
 
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false.
 
bool isWindowType () const
 Returns true if the object is a window; otherwise returns false.
 
bool isQuickItemType () const
 Returns true if the object is a QQuickItem; otherwise returns false.
 
bool signalsBlocked () const noexcept
 Returns true if signals are blocked; otherwise returns false.
 
bool blockSignals (bool b) noexcept
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
 
QThreadthread () const
 Returns the thread in which the object lives.
 
bool moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
 Changes the thread affinity for this object and its children and returns true on success.
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
 
int startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
 
void killTimer (int id)
 Kills the timer with timer identifier, id.
 
void killTimer (Qt::TimerId id)
 
template<typename T >
findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
 
template<typename T >
QList< T > findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
 
template<typename T >
findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<typename T >
QList< T > findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
const QObjectListchildren () const
 Returns a list of child objects.
 
void setParent (QObject *parent)
 Makes the object a child of parent.
 
void installEventFilter (QObject *filterObj)
 Installs an event filter filterObj on this object.
 
void removeEventFilter (QObject *obj)
 Removes an event filter object obj from this object.
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
 
bool disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
 
bool disconnect (const QObject *receiver, const char *member=nullptr) const
 
void dumpObjectTree () const
 Dumps a tree of children to the debug output.
 
void dumpObjectInfo () const
 Dumps information about signal connections, etc.
 
bool setProperty (const char *name, const QVariant &value)
 Sets the value of the object's name property to value.
 
bool setProperty (const char *name, QVariant &&value)
 
QVariant property (const char *name) const
 Returns the value of the object's name property.
 
QList< QByteArraydynamicPropertyNames () const
 
QBindingStoragebindingStorage ()
 
const QBindingStoragebindingStorage () const
 
QObjectparent () const
 Returns a pointer to the parent object.
 
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.
 

Protected Member Functions

 QSGTexture (QSGTexturePrivate &dd)
 
- Protected Member Functions inherited from QObject
QObjectsender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
 
int senderSignalIndex () const
 
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal.
 
bool isSignalConnected (const QMetaMethod &signal) const
 
virtual void timerEvent (QTimerEvent *event)
 This event handler can be reimplemented in a subclass to receive timer events for the object.
 
virtual void childEvent (QChildEvent *event)
 This event handler can be reimplemented in a subclass to receive child events.
 
virtual void customEvent (QEvent *event)
 This event handler can be reimplemented in a subclass to receive custom events.
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
 QObject (QObjectPrivate &dd, QObject *parent=nullptr)
 

Additional Inherited Members

- Public Slots inherited from QObject
void deleteLater ()
 \threadsafe
 
- Signals inherited from QObject
void destroyed (QObject *=nullptr)
 This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
 
void objectNameChanged (const QString &objectName, QPrivateSignal)
 This signal is emitted after the object's name has been changed.
 
- Static Public Member Functions inherited from QObject
static QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 \threadsafe
 
static QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)
 
template<typename Func1 , typename Func2 >
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
 
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 \threadsafe
 
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
 
static bool disconnect (const QMetaObject::Connection &)
 Disconnect a connection.
 
template<typename Func1 , typename Func2 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
 
template<typename Func1 >
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
 
- Protected Attributes inherited from QObject
QScopedPointer< QObjectDatad_ptr
 
- Properties inherited from QObject
QString objectName
 the name of this object
 

Detailed Description

\inmodule QtQuick

The QSGTexture class is the base class 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 provides a default implementation for RGBA textures.The default implementation is not instantiated directly, rather they are constructed via factory functions, such as QQuickWindow::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.

\l{QSGMaterial}{Materials} that work with textures reimplement \l{QSGMaterialShader::updateSampledImage()}{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.

Definition at line 19 of file qsgtexture.h.

Member Enumeration Documentation

◆ AnisotropyLevel

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

\value AnisotropyNone No anisotropic filtering.

\value Anisotropy2x 2x anisotropic filtering.

\value Anisotropy4x 4x anisotropic filtering.

\value Anisotropy8x 8x anisotropic filtering.

\value Anisotropy16x 16x anisotropic filtering.

Since
5.9
Enumerator
AnisotropyNone 
Anisotropy2x 
Anisotropy4x 
Anisotropy8x 
Anisotropy16x 

Definition at line 40 of file qsgtexture.h.

◆ Filtering

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

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

\value Nearest Sampling returns the nearest texel.

\value Linear Sampling returns a linear interpolation of the neighboring texels.

Enumerator
None 
Nearest 
Linear 

Definition at line 34 of file qsgtexture.h.

◆ WrapMode

Specifies how the sampler should treat texture coordinates.

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

\value ClampToEdge Values above 1 are clamped to 1 and values below 0 are clamped to 0.

\value 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.

Enumerator
Repeat 
ClampToEdge 
MirroredRepeat 

Definition at line 28 of file qsgtexture.h.

Constructor & Destructor Documentation

◆ QSGTexture() [1/2]

QSGTexture::QSGTexture ( )

Constructs the QSGTexture base class.

Definition at line 304 of file qsgtexture.cpp.

References qt_debug_add_texture().

+ Here is the call graph for this function:

◆ ~QSGTexture()

QSGTexture::~QSGTexture ( )
override

Destroys the QSGTexture.

Definition at line 334 of file qsgtexture.cpp.

References qt_debug_remove_texture().

+ Here is the call graph for this function:

◆ QSGTexture() [2/2]

QSGTexture::QSGTexture ( QSGTexturePrivate & dd)
protected

Definition at line 319 of file qsgtexture.cpp.

References qt_debug_add_texture().

+ Here is the call graph for this function:

Member Function Documentation

◆ anisotropyLevel()

QSGTexture::AnisotropyLevel QSGTexture::anisotropyLevel ( ) const

Returns the anisotropy level in use for filtering this texture.

Since
5.9

Definition at line 521 of file qsgtexture.cpp.

◆ commitTextureOperations()

void QSGTexture::commitTextureOperations ( QRhi * rhi,
QRhiResourceUpdateBatch * resourceUpdates )
virtual

Call this function to enqueue image upload operations to resourceUpdates, in case there are any pending ones.

When there is no new data (for example, because there was no setImage() since the last call to this function), the function does nothing.

Materials involving rhi textures are expected to call this function from their \l{QSGMaterialShader::updateSampledImage()}{updateSampledImage()} implementation, typically without any conditions, passing {state.rhi()} and {state.resourceUpdateBatch()} from the QSGMaterialShader::RenderState.

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

Reimplemented in QSGCompressedTexture, QSGRhiLayer, QSGPainterTexture, QSGPlainTexture, and QSGRhiAtlasTexture::TextureBase.

Definition at line 605 of file qsgtexture.cpp.

References Q_UNUSED.

Referenced by SpriteMaterialRhiShader::updateSampledImage(), and QSGRhiShaderEffectMaterialShader::updateSampledImage().

+ Here is the caller graph for this function:

◆ comparisonKey()

qint64 QSGTexture::comparisonKey ( ) const
pure virtual

Returns a key suitable for comparing textures.

Typically used in QSGMaterial::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.
Since
5.14

Implemented in QSGOpenVGLayer, QSGOpenVGTexture, QSGSoftwareLayer, QSGSoftwarePixmapTexture, QSGCompressedTexture, QSGRhiLayer, QSGPlainTexture, QSGRhiAtlasTexture::TextureBase, and QSGVideoTexture.

Referenced by QSGOpaqueTextureMaterial::compare(), QSGOpenVGInternalImageNode::render(), QSGOpenVGImageNode::render(), and QSGOpenVGNinePatchNode::render().

+ Here is the caller graph for this function:

◆ convertToNormalizedSourceRect()

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

Returns rect converted to normalized coordinates.

See also
normalizedTextureSubRect()

Definition at line 85 of file qsgtexture.h.

References normalizedTextureSubRect(), rect, and textureSize().

+ Here is the call graph for this function:

◆ filtering()

QSGTexture::Filtering QSGTexture::filtering ( ) const

Returns the sampling mode to be used for this texture.

Definition at line 492 of file qsgtexture.cpp.

Referenced by QSGCompressedAtlasTexture::Texture::removedFromAtlas(), and QSGRhiAtlasTexture::Texture::removedFromAtlas().

+ Here is the caller graph for this function:

◆ hasAlphaChannel()

bool QSGTexture::hasAlphaChannel ( ) const
pure virtual

Returns true if the texture data contains an alpha channel.

Implemented in QSGOpenVGLayer, QSGOpenVGTexture, QSGSoftwareLayer, QSGSoftwarePixmapTexture, QSGCompressedAtlasTexture::Texture, QSGCompressedTexture, QSGRhiLayer, QSGPlainTexture, QSGRhiAtlasTexture::Texture, and QSGVideoTexture.

Referenced by QSGOpaqueTextureMaterial::setTexture(), and QSGSoftwareRenderableNode::update().

+ Here is the caller graph for this function:

◆ hasMipmaps()

bool QSGTexture::hasMipmaps ( ) const
pure virtual

◆ horizontalWrapMode()

QSGTexture::WrapMode QSGTexture::horizontalWrapMode ( ) const

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

Definition at line 544 of file qsgtexture.cpp.

Referenced by QSGPlainTexture::commitTextureOperations().

+ Here is the caller graph for this function:

◆ isAtlasTexture()

bool QSGTexture::isAtlasTexture ( ) const
virtual

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

The default implementation returns false.

Reimplemented in QSGRhiAtlasTexture::TextureBase.

Definition at line 391 of file qsgtexture.cpp.

Referenced by removedFromAtlas().

+ Here is the caller graph for this function:

◆ mipmapFiltering()

QSGTexture::Filtering QSGTexture::mipmapFiltering ( ) const

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

Definition at line 471 of file qsgtexture.cpp.

Referenced by QSGPlainTexture::commitTextureOperations(), QSGVideoTexture::hasMipmaps(), QSGCompressedAtlasTexture::Texture::removedFromAtlas(), and QSGRhiAtlasTexture::Texture::removedFromAtlas().

+ Here is the caller graph for this function:

◆ normalizedTextureSubRect()

QRectF QSGTexture::normalizedTextureSubRect ( ) const
virtual

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.

Reimplemented in QSGCompressedAtlasTexture::Texture, QSGRhiLayer, and QSGRhiAtlasTexture::Texture.

Definition at line 434 of file qsgtexture.cpp.

Referenced by convertToNormalizedSourceRect().

+ Here is the caller graph for this function:

◆ removedFromAtlas()

QSGTexture * QSGTexture::removedFromAtlas ( QRhiResourceUpdateBatch * resourceUpdates = nullptr) const
virtual

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.

resourceUpdates is an optional resource update batch, on which texture operations, if any, are enqueued. Materials can retrieve an instance from QSGMaterialShader::RenderState. When null, the removedFromAtlas() implementation creates its own batch and submit it right away. However, when a valid instance is specified, this function will not submit the update batch.

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

Reimplemented in QSGCompressedAtlasTexture::Texture, and QSGRhiAtlasTexture::Texture.

Definition at line 379 of file qsgtexture.cpp.

References isAtlasTexture(), Q_ASSERT_X, and Q_UNUSED.

Referenced by QSGRhiShaderEffectMaterialShader::updateSampledImage().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ rhiTexture()

QRhiTexture * QSGTexture::rhiTexture ( ) const
virtual
Returns
the QRhiTexture for this QSGTexture or null if there is none (either because a valid texture has not been created internally yet, or because the concept is not applicable to the scenegraph backend in use).

This function is not expected to create a new QRhiTexture in case there is none. It should return null in that case. The expectation towards the renderer is that a null texture leads to using a transparent, dummy texture instead.

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

Reimplemented in QSGCompressedTexture, QSGRhiLayer, QSGPlainTexture, QSGRhiAtlasTexture::TextureBase, and QSGVideoTexture.

Definition at line 585 of file qsgtexture.cpp.

◆ setAnisotropyLevel()

void QSGTexture::setAnisotropyLevel ( AnisotropyLevel level)

Sets the level of anisotropic filtering to level.

The default value is QSGTexture::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.
Since
5.9

Definition at line 507 of file qsgtexture.cpp.

References d.

◆ setFiltering()

◆ setHorizontalWrapMode()

void QSGTexture::setHorizontalWrapMode ( WrapMode hwrap)

Sets the horizontal wrap mode to hwrap.

Definition at line 532 of file qsgtexture.cpp.

References d.

Referenced by QSGGradientCache::get(), and QQuickImageTextureProvider::texture().

+ Here is the caller graph for this function:

◆ setMipmapFiltering()

void QSGTexture::setMipmapFiltering ( Filtering filter)

Sets the mipmap sampling mode to filter.

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

See also
hasMipmaps()

Definition at line 459 of file qsgtexture.cpp.

References d.

Referenced by QSGPlainTexture::commitTextureOperations(), QSGCompressedAtlasTexture::Texture::removedFromAtlas(), QSGRhiAtlasTexture::Texture::removedFromAtlas(), QQuickImageTextureProvider::texture(), and QQuickShaderEffectSourceTextureProvider::texture().

+ Here is the caller graph for this function:

◆ setVerticalWrapMode()

void QSGTexture::setVerticalWrapMode ( WrapMode vwrap)

Sets the vertical wrap mode to vwrap.

Definition at line 554 of file qsgtexture.cpp.

References d.

Referenced by QSGGradientCache::get(), and QQuickImageTextureProvider::texture().

+ Here is the caller graph for this function:

◆ textureSize()

QSize QSGTexture::textureSize ( ) const
pure virtual

Returns the size of the texture in pixels.

Implemented in QSGOpenVGLayer, QSGOpenVGTexture, QSGSoftwareLayer, QSGSoftwarePixmapTexture, QSGCompressedAtlasTexture::Texture, QSGCompressedTexture, QSGRhiLayer, QSGPlainTexture, QSGRhiAtlasTexture::Texture, and QSGVideoTexture.

Referenced by convertToNormalizedSourceRect(), QSGBasicInternalImageNode::preprocess(), QSGOpenVGInternalImageNode::render(), and QSGOpenVGNinePatchNode::render().

+ Here is the caller graph for this function:

◆ verticalWrapMode()

QSGTexture::WrapMode QSGTexture::verticalWrapMode ( ) const

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

Definition at line 566 of file qsgtexture.cpp.

Referenced by QSGPlainTexture::commitTextureOperations().

+ Here is the caller graph for this function:

The documentation for this class was generated from the following files: