The QSGTexture class is the base class for textures used in the scene graph. 更多...
| 头： | #include <QSGTexture> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
| 继承： | QObject |
| 继承者： |
| enum | AnisotropyLevel { AnisotropyNone, Anisotropy2x, Anisotropy4x, Anisotropy8x, Anisotropy16x } |
| enum | 过滤 { None, Nearest, Linear } |
| enum | WrapMode { Repeat, ClampToEdge, MirroredRepeat } |
| QSGTexture () | |
| virtual | ~QSGTexture () override |
| QSGTexture::AnisotropyLevel | anisotropyLevel () const |
(从 6.0 起)
virtual void
|
commitTextureOperations (QRhi * rhi , QRhiResourceUpdateBatch * resourceUpdates ) |
| virtual qint64 | comparisonKey () const = 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 |
| QNativeInterface * | nativeInterface () const |
| virtual QRectF | normalizedTextureSubRect () const |
| virtual QSGTexture * | removedFromAtlas (QRhiResourceUpdateBatch * resourceUpdates = nullptr) const |
(从 6.0 起)
virtual QRhiTexture *
|
rhiTexture () const |
| void | setAnisotropyLevel (QSGTexture::AnisotropyLevel level ) |
| void | setFiltering (QSGTexture::Filtering filter ) |
| void | setHorizontalWrapMode (QSGTexture::WrapMode hwrap ) |
| void | setMipmapFiltering (QSGTexture::Filtering filter ) |
| void | setVerticalWrapMode (QSGTexture::WrapMode vwrap ) |
| virtual QSize | textureSize () const = 0 |
| QSGTexture::WrapMode | verticalWrapMode () const |
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.
材质 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 () 和 setVerticalWrapMode (). The scene graph and Qt's graphics abstraction takes care of creating separate sampler objects, when applicable.
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 () 函数。
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.
注意： 所有带有 QSG 前缀的类只应用于场景图形渲染线程。见 场景图形和渲染 了解更多信息。
Specifies the anisotropic filtering level to be used when the texture is not screen aligned.
| 常量 | 值 | 描述 |
|---|---|---|
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. |
Specifies how sampling of texels should filter when texture coordinates are not pixel aligned.
| 常量 | 值 | 描述 |
|---|---|---|
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. |
Specifies how the sampler should treat texture coordinates.
| 常量 | 值 | 描述 |
|---|---|---|
QSGTexture::Repeat
|
0
|
Only the fractional part of the texture coordinate 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. |
QSGTexture::MirroredRepeat
|
2
|
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.
|
Constructs the QSGTexture base class.
[override virtual noexcept]
QSGTexture::
~QSGTexture
()
销毁 QSGTexture .
Returns the anisotropy level in use for filtering this texture.
另请参阅 setAnisotropyLevel ().
[virtual, since 6.0]
void
QSGTexture::
commitTextureOperations
(
QRhi
*
rhi
,
QRhiResourceUpdateBatch
*
resourceUpdates
)
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
updateSampledImage
() implementation, typically without any conditions, passing
state.rhi()
and
state.resourceUpdateBatch()
从
QSGMaterialShader::RenderState
.
警告： This function can only be called from the rendering thread.
该函数在 Qt 6.0 引入。
[pure virtual]
qint64
QSGTexture::
comparisonKey
() const
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.
警告： This function can only be called from the rendering thread.
返回 rect converted to normalized coordinates.
另请参阅 normalizedTextureSubRect ().
Returns the sampling mode to be used for this texture.
另请参阅 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.
Returns the horizontal wrap mode to be used for this texture.
另请参阅 setHorizontalWrapMode ().
[虚拟]
bool
QSGTexture::
isAtlasTexture
() const
Returns whether this texture is part of an atlas or not.
默认实现返回 false。
Returns whether mipmapping should be used when sampling from this texture.
另请参阅 setMipmapFiltering ().
Returns a native interface of the given type for the texture.
此函数提供对平台特定功能的访问为 QSGTexture , as declared in the QNativeInterface 名称空间：
| 提供对 Direct3D 11 纹理对象的访问和启用采纳 | |
| Provides access to and enables adopting Direct3D 12 texture objects | |
| 提供对 Metal 纹理对象的访问和启用采纳 | |
| 提供对 OpenGL 纹理对象的访问和启用采纳 | |
| 提供对 Vulkan 图像对象的访问和启用采纳 |
This allows accessing the underlying native texture object, such as, the
GLuint
texture ID with OpenGL, or the
VkImage
handle with Vulkan.
若请求接口不可用
nullptr
被返回。
[虚拟]
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.
[虚拟]
QSGTexture
*QSGTexture::
removedFromAtlas
(
QRhiResourceUpdateBatch
*
resourceUpdates
= nullptr) 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.
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.
警告： This function can only be called from the rendering thread.
[virtual, since 6.0]
QRhiTexture
*QSGTexture::
rhiTexture
() const
返回 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.
警告： This function can only be called from the rendering thread.
该函数在 Qt 6.0 引入。
Sets the level of anisotropic filtering to level 。默认值为 QSGTexture::AnisotropyNone , which means no anisotropic filtering is enabled.
注意： The request may be ignored depending on the graphics API in use. There is no guarantee anisotropic filtering is supported at run time.
另请参阅 anisotropyLevel ().
Sets the sampling mode to filter .
另请参阅 filtering ().
Sets the horizontal wrap mode to hwrap
另请参阅 horizontalWrapMode ().
Sets the mipmap sampling mode to filter .
Setting the mipmap filtering has no effect it the texture does not have mipmaps.
另请参阅 mipmapFiltering () 和 hasMipmaps ().
Sets the vertical wrap mode to vwrap
另请参阅 verticalWrapMode ().
[pure virtual]
QSize
QSGTexture::
textureSize
() const
Returns the size of the texture in pixels.
Returns the vertical wrap mode to be used for this texture.
另请参阅 setVerticalWrapMode ().