 |
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>.
|
|
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>.
|
\inmodule QtGui More...
#include <qrhi.h>
Inheritance diagram for QRhiTexture: Collaboration diagram for QRhiTexture:Classes | |
| struct | NativeTexture |
| \inmodule QtGui More... | |
| struct | ViewFormat |
| \inmodule QtGui More... | |
Public Member Functions | |
| QRhiResource::Type | resourceType () const override |
| Format | format () const |
| void | setFormat (Format fmt) |
| Sets the requested texture format to fmt. | |
| QSize | pixelSize () const |
| void | setPixelSize (const QSize &sz) |
| Sets the texture size, specified in pixels, to sz. | |
| int | depth () const |
| void | setDepth (int depth) |
| Sets the depth for a 3D texture. | |
| int | arraySize () const |
| void | setArraySize (int arraySize) |
| Sets the texture arraySize. | |
| int | arrayRangeStart () const |
| int | arrayRangeLength () const |
| void | setArrayRange (int startIndex, int count) |
Normally all array layers are exposed and it is up to the shader to select the layer via the third coordinate passed to the sampler2DArray. | |
| Flags | flags () const |
| void | setFlags (Flags f) |
| Sets the texture flags to f. | |
| int | sampleCount () const |
| void | setSampleCount (int s) |
| Sets the sample count to s. | |
| ViewFormat | readViewFormat () const |
| \variable QRhiTexture::ViewFormat::format | |
| void | setReadViewFormat (const ViewFormat &fmt) |
| ViewFormat | writeViewFormat () const |
| void | setWriteViewFormat (const ViewFormat &fmt) |
| virtual bool | create ()=0 |
| Creates the corresponding native graphics resources. | |
| virtual NativeTexture | nativeTexture () |
| virtual bool | createFrom (NativeTexture src) |
| Similar to create(), except that no new native textures are created. | |
| virtual void | setNativeLayout (int layout) |
| With some graphics APIs, such as Vulkan, integrating custom rendering code that uses the graphics API directly needs special care when it comes to image layouts. | |
| Public Member Functions inherited from QRhiResource | |
| virtual | ~QRhiResource () |
| Destructor. | |
| virtual void | destroy ()=0 |
| Releases (or requests deferred releasing of) the underlying native graphics resources. | |
| void | deleteLater () |
| When called without a frame being recorded, this function is equivalent to deleting the object. | |
| QByteArray | name () const |
| void | setName (const QByteArray &name) |
| Sets a name for the object. | |
| quint64 | globalResourceId () const |
| QRhi * | rhi () const |
Protected Member Functions | |
| QRhiTexture (QRhiImplementation *rhi, Format format_, const QSize &pixelSize_, int depth_, int arraySize_, int sampleCount_, Flags flags_) | |
| \variable QRhiTexture::NativeTexture::object | |
| Protected Member Functions inherited from QRhiResource | |
| QRhiResource (QRhiImplementation *rhi) | |
Protected Attributes | |
| Format | m_format |
| QSize | m_pixelSize |
| int | m_depth |
| int | m_arraySize |
| int | m_sampleCount |
| Flags | m_flags |
| int | m_arrayRangeStart = -1 |
| int | m_arrayRangeLength = -1 |
| ViewFormat | m_readViewFormat = { UnknownFormat, false } |
| ViewFormat | m_writeViewFormat = { UnknownFormat, false } |
| Protected Attributes inherited from QRhiResource | |
| QRhiImplementation * | m_rhi = nullptr |
| quint64 | m_id |
| QByteArray | m_objectName |
\inmodule QtGui
Texture resource.
A QRhiTexture encapsulates a native texture object, such as a VkImage or MTLTexture.
A QRhiTexture instance is always created by calling \l{QRhi::newTexture()}{the QRhi's newTexture() function}. This creates no native graphics resources. To do that, call create() after setting the appropriate options, such as the format and size, although in most cases these are already set based on the arguments passed to \l{QRhi::newTexture()}{newTexture()}.
Setting the \l{QRhiTexture::Flags}{flags} correctly is essential, otherwise various errors can occur depending on the underlying QRhi backend and graphics API. For example, when a texture will be rendered into from a render pass via QRhiTextureRenderTarget, the texture must be created with the \l RenderTarget flag set. Similarly, when the texture is going to be \l{QRhiResourceUpdateBatch::readBackTexture()}{read back}, the \l UsedAsTransferSource flag must be set upfront. Mipmapped textures must have the MipMapped flag set. And so on. It is not possible to change the flags once create() has succeeded. To release the existing and create a new native texture object with the changed settings, call the setters and call create() again. This then might be a potentially expensive operation.
| enum QRhiTexture::Flag |
Flag values to specify how the texture is going to be used.
Not honoring the flags set before create() and attempting to use the texture in ways that was not declared upfront can lead to unspecified behavior or decreased performance depending on the backend and the underlying graphics API.
\value RenderTarget The texture going to be used in combination with QRhiTextureRenderTarget.
\value CubeMap The texture is a cubemap. Such textures have 6 layers, one for each face in the order of +X, -X, +Y, -Y, +Z, -Z. Cubemap textures cannot be multisample.
\value MipMapped The texture has mipmaps. The appropriate mip count is calculated automatically and can also be retrieved via QRhi::mipLevelsForSize(). The images for the mip levels have to be provided in the texture uploaded or generated via QRhiResourceUpdateBatch::generateMips(). Multisample textures cannot have mipmaps.
\value sRGB Use an sRGB format.
\value UsedAsTransferSource The texture is used as the source of a texture copy or readback, meaning the texture is given as the source in QRhiResourceUpdateBatch::copyTexture() or QRhiResourceUpdateBatch::readBackTexture().
\value UsedWithGenerateMips The texture is going to be used with QRhiResourceUpdateBatch::generateMips().
\value UsedWithLoadStore The texture is going to be used with image load/store operations, for example, in a compute shader.
\value UsedAsCompressedAtlas The texture has a compressed format and the dimensions of subresource uploads may not match the texture size.
\value ExternalOES The texture should use the GL_TEXTURE_EXTERNAL_OES target with OpenGL. This flag is ignored with other graphics APIs.
\value ThreeDimensional The texture is a 3D texture. Such textures should be created with the QRhi::newTexture() overload taking a depth in addition to width and height. A 3D texture can have mipmaps but cannot be multisample. When rendering into, or uploading data to a 3D texture, the layer specified in the render target's color attachment or the upload description refers to a single slice in range [0..depth-1]. The underlying graphics API may not support 3D textures at run time. Support is indicated by the QRhi::ThreeDimensionalTextures feature.
\value TextureRectangleGL The texture should use the GL_TEXTURE_RECTANGLE target with OpenGL. This flag is ignored with other graphics APIs. Just like ExternalOES, this flag is useful when working with platform APIs where native OpenGL texture objects received from the platform are wrapped in a QRhiTexture, and the platform can only provide textures for a non-2D texture target.
\value TextureArray The texture is a texture array, i.e. a single texture object that is a homogeneous array of 2D textures. Texture arrays are created with QRhi::newTextureArray(). The underlying graphics API may not support texture array objects at run time. Support is indicated by the QRhi::TextureArrays feature. When rendering into, or uploading data to a texture array, the layer specified in the render target's color attachment or the upload description selects a single element in the array.
\value OneDimensional The texture is a 1D texture. Such textures can be created by passing a 0 height and depth to QRhi::newTexture(). Note that there can be limitations on one dimensional textures depending on the underlying graphics API. For example, rendering to them or using them with mipmap-based filtering may be unsupported. This is indicated by the QRhi::OneDimensionalTextures and QRhi::OneDimensionalTextureMipmaps feature flags.
| enum QRhiTexture::Format |
Specifies the texture format.
See also QRhi::isTextureFormatSupported() and note that flags() can modify the format when QRhiTexture::sRGB is set.
\value UnknownFormat Not a valid format. This cannot be passed to setFormat().
\value RGBA8 Four component, unsigned normalized 8 bit per component. Always supported.
\value BGRA8 Four component, unsigned normalized 8 bit per component.
\value R8 One component, unsigned normalized 8 bit.
\value RG8 Two components, unsigned normalized 8 bit.
\value R16 One component, unsigned normalized 16 bit.
\value RG16 Two component, unsigned normalized 16 bit.
\value RED_OR_ALPHA8 Either same as R8, or is a similar format with the component swizzled to alpha, depending on \l{QRhi::RedOrAlpha8IsRed}{RedOrAlpha8IsRed}.
\value RGBA16F Four components, 16-bit float per component.
\value RGBA32F Four components, 32-bit float per component.
\value R16F One component, 16-bit float.
\value R32F One component, 32-bit float.
\value RGB10A2 Four components, unsigned normalized 10 bit R, G, and B, 2-bit alpha. This is a packed format so native endianness applies. Note that there is no BGR10A2. This is because RGB10A2 maps to DXGI_FORMAT_R10G10B10A2_UNORM with D3D, MTLPixelFormatRGB10A2Unorm with Metal, VK_FORMAT_A2B10G10R10_UNORM_PACK32 with Vulkan, and GL_RGB10_A2/GL_RGB/GL_UNSIGNED_INT_2_10_10_10_REV on OpenGL (ES). This is the only universally supported RGB30 option. The corresponding QImage formats are QImage::Format_BGR30 and QImage::Format_A2BGR30_Premultiplied.
\value D16 16-bit depth (normalized unsigned integer)
\value D24 24-bit depth (normalized unsigned integer)
\value D24S8 24-bit depth (normalized unsigned integer), 8 bit stencil
\value D32F 32-bit depth (32-bit float)
\value BC1 \value BC2 \value BC3 \value BC4 \value BC5 \value BC6H \value BC7
\value ETC2_RGB8 \value ETC2_RGB8A1 \value ETC2_RGBA8
\value ASTC_4x4 \value ASTC_5x4 \value ASTC_5x5 \value ASTC_6x5 \value ASTC_6x6 \value ASTC_8x5 \value ASTC_8x6 \value ASTC_8x8 \value ASTC_10x5 \value ASTC_10x6 \value ASTC_10x8 \value ASTC_10x10 \value ASTC_12x10 \value ASTC_12x12
|
protected |
\variable QRhiTexture::NativeTexture::object
64-bit integer containing the native object handle.
With OpenGL, the native handle is a GLuint value, so object can then be cast to a GLuint. With Vulkan, the native handle is a VkImage, so object can be cast to a VkImage. With Direct3D 11 and Metal object contains a ID3D11Texture2D or MTLTexture pointer, respectively. With Direct3D 12 object contains a ID3D12Resource pointer.
\variable QRhiTexture::NativeTexture::layout
Specifies the current image layout for APIs like Vulkan.
For Vulkan, layout contains a VkImageLayout value.
|
inline |
|
inline |
|
inline |
Definition at line 981 of file qrhi.h.
Referenced by QRhiMetal::beginPass(), QRhiVulkan::createOffscreenRenderPass(), QOpenXRGraphicsOpenGL::renderTarget(), QOpenXRGraphicsOpenGLES::renderTarget(), and QOpenXRGraphicsVulkan::renderTarget().
Here is the caller graph for this function:
|
pure virtual |
Creates the corresponding native graphics resources.
If there are already resources present due to an earlier create() with no corresponding destroy(), then destroy() is called implicitly first.
true when successful, false when a graphics operation failed. Regardless of the return value, calling destroy() is always safe. Implemented in QD3D11Texture, QGles2Texture, QMetalTexture, QNullTexture, and QVkTexture.
Referenced by QSGCompressedTexture::commitTextureOperations(), QSGPlainTexture::commitTextureOperations(), QRhiWidgetPrivate::ensureTexture(), QSGCompressedAtlasTexture::Atlas::generateTexture(), QSGRhiAtlasTexture::Atlas::generateTexture(), QSSGParticleRenderer::prepareParticlesForModel(), QSSGParticleRenderer::rhiPrepareRenderable(), QQuickRhiItemNode::sync(), and QQuick3DSceneRenderer::synchronize().
Here is the caller graph for this function:
|
virtual |
Similar to create(), except that no new native textures are created.
Instead, the native texture resources specified by src is used.
This allows importing an existing native texture object (which must belong to the same device or sharing context, depending on the graphics API) from an external graphics engine.
The opposite of this operation, exposing a QRhiTexture-created native texture object to a foreign engine, is possible via nativeTexture().
Reimplemented in QD3D11Texture, QGles2Texture, QMetalTexture, QNullTexture, and QVkTexture.
Definition at line 4487 of file qrhi.cpp.
References Q_UNUSED.
Referenced by QOpenXRGraphicsOpenGL::renderTarget(), QOpenXRGraphicsOpenGLES::renderTarget(), QOpenXRGraphicsVulkan::renderTarget(), and QSGPlainTexture::setTextureFromNativeTexture().
Here is the caller graph for this function:
|
inline |
|
inline |
Definition at line 992 of file qrhi.h.
Referenced by addOpaqueDepthPrePassBindings(), QSGPlainTexture::commitTextureOperations(), QRhiD3D11::enqueueResourceUpdates(), RenderHelpers::rhiPrepareRenderable(), QSSGCustomMaterialSystem::rhiPrepareRenderable(), and QSSGParticleRenderer::rhiPrepareRenderable().
Here is the caller graph for this function:
|
inline |
Definition at line 972 of file qrhi.h.
Referenced by QRhiWidgetPrivate::ensureTexture(), QSGRhiAtlasTexture::Texture::removedFromAtlas(), QOpenXRGraphicsOpenGL::renderTarget(), QOpenXRGraphicsOpenGLES::renderTarget(), QOpenXRGraphicsVulkan::renderTarget(), QSGRhiTextureGlyphCache::resizeTextureData(), QRhiNull::resourceUpdate(), QQuickRhiItemNode::sync(), and QQuick3DSceneRenderer::synchronize().
Here is the caller graph for this function:
|
virtual |
Reimplemented in QD3D11Texture, QGles2Texture, QMetalTexture, and QVkTexture.
|
inline |
Definition at line 975 of file qrhi.h.
Referenced by QSGPlainTexture::commitTextureOperations(), QNullTextureRenderTarget::create(), createRhiRenderTargetWithDepthTexture(), QRhiWidgetPrivate::ensureTexture(), ExampleRhiWidget::initialize(), QRhiWidgetPrivate::invokeInitialize(), ExampleRhiWidget::render(), QSSGReflectionMapEntry::renderMips(), QOpenXRGraphicsOpenGL::renderTarget(), QOpenXRGraphicsOpenGLES::renderTarget(), QOpenXRGraphicsVulkan::renderTarget(), QSGRhiTextureGlyphCache::resizeTextureData(), RenderHelpers::rhiRenderAoTexture(), and QQuickRhiItemNode::sync().
Here is the caller graph for this function:
|
inline |
\variable QRhiTexture::ViewFormat::format
\variable QRhiTexture::ViewFormat::srgb
|
overridevirtual |
Implements QRhiResource.
Definition at line 4431 of file qrhi.cpp.
References QRhiResource::Texture.
|
inline |
Definition at line 995 of file qrhi.h.
Referenced by createRhiRenderTargetWithDepthTexture(), QRhiWidgetPrivate::ensureTexture(), and QQuickRhiItemNode::sync().
Here is the caller graph for this function:
|
inline |
Normally all array layers are exposed and it is up to the shader to select the layer via the third coordinate passed to the {texture()} GLSL function when sampling the sampler2DArray.
When QRhi::TextureArrayRange is reported as supported, calling setArrayRange() before create() or createFrom() requests selecting only the specified range, count elements starting from startIndex. The shader logic can then be written with this in mind.
|
inline |
|
inline |
Sets the texture flags to f.
Definition at line 993 of file qrhi.h.
Referenced by QSGPlainTexture::commitTextureOperations().
Here is the caller graph for this function:
|
inline |
Sets the requested texture format to fmt.
Definition at line 973 of file qrhi.h.
References fmt.
Referenced by QQuick3DSceneRenderer::synchronize().
Here is the caller graph for this function:
|
virtual |
With some graphics APIs, such as Vulkan, integrating custom rendering code that uses the graphics API directly needs special care when it comes to image layouts.
This function allows communicating the expected layout the image backing the QRhiTexture is in after the native rendering commands.
For example, consider rendering into a QRhiTexture's VkImage directly with Vulkan in a code block enclosed by QRhiCommandBuffer::beginExternal() and QRhiCommandBuffer::endExternal(), followed by using the image for texture sampling in a QRhi-based render pass. To avoid potentially incorrect image layout transitions, this function can be used to indicate what the image layout will be once the commands recorded in said code block complete.
Calling this function makes sense only after QRhiCommandBuffer::endExternal() and before a subsequent QRhiCommandBuffer::beginPass().
This function has no effect with QRhi backends where the underlying graphics API does not expose a concept of image layouts.
VkImageLayout. With Direct 3D 12 layout is a value composed of the bits from D3D12_RESOURCE_STATES. Reimplemented in QVkTexture.
Sets the texture size, specified in pixels, to sz.
Definition at line 976 of file qrhi.h.
Referenced by QSGPlainTexture::commitTextureOperations(), QVkRenderBuffer::create(), QOpenGLWidgetPrivate::ensureRhiDependentResources(), QRhiWidgetPrivate::ensureTexture(), QSSGParticleRenderer::prepareParticlesForModel(), RenderHelpers::rhiPrepareAoTexture(), RenderHelpers::rhiPrepareDepthTexture(), QSSGParticleRenderer::rhiPrepareRenderable(), RenderHelpers::rhiPrepareScreenTexture(), QQuickRhiItemNode::sync(), and QQuick3DSceneRenderer::synchronize().
Here is the caller graph for this function:
|
inline |
Sets the shader resource view format (or the format of the view used for sampling the texture) to fmt. By default the same format (and sRGB-ness) is used as the texture itself, and in most cases this function does not need to be called.
This setting is only taken into account when the \l TextureViewFormat feature is reported as supported.
Definition at line 1003 of file qrhi.h.
References fmt.
|
inline |
Sets the sample count to s.
Definition at line 996 of file qrhi.h.
Referenced by QVkRenderBuffer::create().
Here is the caller graph for this function:
|
inline |
Sets the render target view format to fmt. By default the same format (and sRGB-ness) is used as the texture itself, and in most cases this function does not need to be called.
One common use case for providing a write view format is working with externally provided textures that, outside of our control, use an sRGB format with 3D APIs such as Vulkan or Direct 3D, but the rendering engine is already prepared to handle linearization and conversion to sRGB at the end of its shading pipeline. In this case what is wanted when rendering into such a texture is a render target view (e.g. VkImageView) that has the same, but non-sRGB format. (if e.g. from an OpenXR implementation one gets a VK_FORMAT_R8G8B8A8_SRGB texture, it is likely that rendering into it should be done using a VK_FORMAT_R8G8B8A8_UNORM view, if that is what the rendering engine's pipeline requires; in this example one would call this function with a ViewFormat that has a format of QRhiTexture::RGBA8 and srgb set to false).
This setting is only taken into account when the \l TextureViewFormat feature is reported as supported.
Definition at line 1005 of file qrhi.h.
References fmt.
|
inline |
|
protected |
Definition at line 1022 of file qrhi.h.
Referenced by QD3D11Texture::finishCreate(), and QVkTexture::finishCreate().
|
protected |
Definition at line 1021 of file qrhi.h.
Referenced by QD3D11Texture::finishCreate(), and QVkTexture::finishCreate().
|
protected |
Definition at line 1018 of file qrhi.h.
Referenced by QD3D11Texture::create(), QGles2Texture::create(), QMetalTexture::create(), QNullTexture::create(), QVkTexture::create(), QD3D11Texture::finishCreate(), QVkTexture::finishCreate(), QVkTexture::perLevelImageViewForLoadStore(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), QVkTexture::prepareCreate(), and QD3D11Texture::unorderedAccessViewForLevel().
|
protected |
Definition at line 1017 of file qrhi.h.
Referenced by QD3D11Texture::create(), QGles2Texture::create(), QMetalTexture::create(), QNullTexture::create(), QVkTexture::create(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), and QVkTexture::prepareCreate().
|
protected |
Definition at line 1020 of file qrhi.h.
Referenced by QD3D11Texture::create(), QGles2Texture::create(), QMetalTexture::create(), QNullTexture::create(), QVkTexture::create(), QD3D11Texture::createFrom(), QD3D11Texture::finishCreate(), QVkTexture::finishCreate(), QVkTexture::perLevelImageViewForLoadStore(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), QVkTexture::prepareCreate(), and QD3D11Texture::unorderedAccessViewForLevel().
|
protected |
Definition at line 1015 of file qrhi.h.
Referenced by QD3D11Texture::create(), QGles2Texture::create(), QNullTexture::create(), QVkTexture::create(), QD3D11Texture::finishCreate(), QVkTexture::finishCreate(), QVkTexture::perLevelImageViewForLoadStore(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), and QVkTexture::prepareCreate().
|
protected |
Definition at line 1016 of file qrhi.h.
Referenced by QNullTexture::create(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), and QVkTexture::prepareCreate().
|
protected |
Definition at line 1023 of file qrhi.h.
Referenced by QVkTexture::prepareCreate().
|
protected |
Definition at line 1019 of file qrhi.h.
Referenced by QGles2Texture::create(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), and QVkTexture::prepareCreate().
|
protected |
Definition at line 1024 of file qrhi.h.
Referenced by QVkTexture::prepareCreate().
1.10.0