 |
Qt 6.x
The Qt SDK
|
|
Qt 6.x
The Qt SDK
|
\inmodule QtGui More...
#include <qrhi.h>
Inheritance diagram for QRhiTexture: Collaboration diagram for QRhiTexture:Classes | |
| struct | NativeTexture |
| \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. | |
| 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 Type | resourceType () const =0 |
| 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 |
| 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 |
Definition at line 973 of file qrhi.h.
Referenced by QD3D11TextureRenderTarget::create().
Here is the caller graph for this function:
|
inline |
Definition at line 972 of file qrhi.h.
Referenced by QD3D11TextureRenderTarget::create().
Here is the caller graph for this function:
|
inline |
Definition at line 969 of file qrhi.h.
Referenced by QD3D11TextureRenderTarget::create().
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(), QSGCompressedAtlasTexture::Atlas::generateTexture(), QSGRhiAtlasTexture::Atlas::generateTexture(), QSSGParticleRenderer::prepareParticlesForModel(), QSGRhiAtlasTexture::Texture::removedFromAtlas(), renderToKTXFileInternal(), RenderHelpers::rhiPrepareAoTexture(), RenderHelpers::rhiPrepareDepthTexture(), QSSGParticleRenderer::rhiPrepareRenderable(), RenderHelpers::rhiPrepareScreenTexture(), 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 4361 of file qrhi.cpp.
References Q_UNUSED.
Referenced by QSGPlainTexture::setTextureFromNativeTexture().
Here is the caller graph for this function:
|
inline |
|
inline |
Definition at line 980 of file qrhi.h.
Referenced by addOpaqueDepthPrePassBindings(), QSGPlainTexture::commitTextureOperations(), QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QMetalTextureRenderTarget::create(), QVkTextureRenderTarget::create(), QRhiD3D11::enqueueResourceUpdates(), QRhiGles2::enqueueSubresUpload(), RenderHelpers::rhiPrepareRenderable(), QSSGCustomMaterialSystem::rhiPrepareRenderable(), and QSSGParticleRenderer::rhiPrepareRenderable().
Here is the caller graph for this function:
|
inline |
Definition at line 960 of file qrhi.h.
Referenced by QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QMetalTextureRenderTarget::create(), QRhiVulkan::createOffscreenRenderPass(), QSGRhiAtlasTexture::Texture::removedFromAtlas(), QSGRhiTextureGlyphCache::resizeTextureData(), QRhiNull::resourceUpdate(), RenderHelpers::rhiPrepareDepthTexture(), and QQuick3DSceneRenderer::synchronize().
Here is the caller graph for this function:
|
virtual |
Reimplemented in QD3D11Texture, QGles2Texture, QMetalTexture, and QVkTexture.
|
inline |
Definition at line 963 of file qrhi.h.
Referenced by QSSGRenderReflectionMap::addReflectionMapEntry(), QSSGRenderShadowMap::addShadowMapEntry(), QSGPlainTexture::commitTextureOperations(), QD3D11TextureRenderTarget::create(), QGles2TextureRenderTarget::create(), QMetalTextureRenderTarget::create(), QNullTextureRenderTarget::create(), QVkTextureRenderTarget::create(), QRhiGles2::endPass(), QBackingStoreDefaultCompositor::flush(), QSSGReflectionMapEntry::renderMips(), QQuick3DSceneRenderer::renderToRhiTexture(), QSGRhiTextureGlyphCache::resizeTextureData(), QRhiNull::resourceUpdate(), RenderHelpers::rhiPrepareAoTexture(), RenderHelpers::rhiPrepareDepthTexture(), RenderHelpers::rhiPrepareScreenTexture(), RenderHelpers::rhiRenderAoTexture(), RenderHelpers::rhiRenderReflectionMap(), RenderHelpers::rhiRenderShadowMap(), QRhiNull::simulateTextureCopy(), QRhiNull::simulateTextureGenMips(), and QRhiNull::simulateTextureUpload().
Here is the caller graph for this function:
|
overridevirtual |
Implements QRhiResource.
Definition at line 4305 of file qrhi.cpp.
References QRhiResource::Texture.
|
inline |
|
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 981 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 961 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 964 of file qrhi.h.
Referenced by QSGPlainTexture::commitTextureOperations(), QVkRenderBuffer::create(), QOpenGLWidgetPrivate::ensureRhiDependentResources(), QSSGParticleRenderer::prepareParticlesForModel(), RenderHelpers::rhiPrepareAoTexture(), RenderHelpers::rhiPrepareDepthTexture(), QSSGParticleRenderer::rhiPrepareRenderable(), RenderHelpers::rhiPrepareScreenTexture(), and QQuick3DSceneRenderer::synchronize().
Here is the caller graph for this function:
|
inline |
Sets the sample count to s.
Definition at line 984 of file qrhi.h.
Referenced by QVkRenderBuffer::create().
Here is the caller graph for this function:
|
protected |
Definition at line 1001 of file qrhi.h.
Referenced by QD3D11Texture::finishCreate(), and QVkTexture::finishCreate().
|
protected |
Definition at line 1000 of file qrhi.h.
Referenced by QD3D11Texture::finishCreate(), and QVkTexture::finishCreate().
|
protected |
Definition at line 997 of file qrhi.h.
Referenced by QD3D11Texture::create(), QGles2Texture::create(), QMetalTexture::create(), QNullTexture::create(), QVkTexture::create(), QRhiVulkan::enqueueResourceUpdates(), QRhiGles2::enqueueSubresUpload(), QD3D11Texture::finishCreate(), QVkTexture::finishCreate(), QVkTexture::imageViewForLevel(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), QVkTexture::prepareCreate(), and QD3D11Texture::unorderedAccessViewForLevel().
|
protected |
Definition at line 996 of file qrhi.h.
Referenced by QD3D11Texture::create(), QGles2Texture::create(), QMetalTexture::create(), QNullTexture::create(), QVkTexture::create(), QRhiVulkan::enqueueResourceUpdates(), QRhiGles2::enqueueSubresUpload(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), and QVkTexture::prepareCreate().
|
protected |
Definition at line 999 of file qrhi.h.
Referenced by QRhiGles2::bindShaderResources(), QD3D11Texture::create(), QGles2Texture::create(), QMetalTexture::create(), QNullTexture::create(), QVkTexture::create(), QD3D11Texture::createFrom(), QRhiGles2::endPass(), QRhiD3D11::enqueueResourceUpdates(), QRhiGles2::enqueueResourceUpdates(), QRhiVulkan::enqueueResourceUpdates(), QRhiD3D11::enqueueSubresUpload(), QRhiGles2::enqueueSubresUpload(), QRhiMetal::enqueueSubresUpload(), QD3D11Texture::finishCreate(), QVkTexture::finishCreate(), QVkTexture::imageViewForLevel(), QSSGBufferManager::loadRenderImage(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), QVkTexture::prepareCreate(), QRhiVulkan::prepareUploadSubres(), QRhiVulkan::setShaderResources(), QRhiGles2::trackedImageBarrier(), and QD3D11Texture::unorderedAccessViewForLevel().
|
protected |
Definition at line 994 of file qrhi.h.
Referenced by QD3D11Texture::create(), QGles2Texture::create(), QNullTexture::create(), QVkTexture::create(), QRhiD3D11::enqueueResourceUpdates(), QRhiGles2::enqueueResourceUpdates(), QRhiVulkan::enqueueResourceUpdates(), QRhiD3D11::enqueueSubresUpload(), QRhiGles2::enqueueSubresUpload(), QRhiMetal::enqueueSubresUpload(), QD3D11Texture::finishCreate(), QVkTexture::finishCreate(), QVkTexture::imageViewForLevel(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), QVkTexture::prepareCreate(), QRhiVulkan::prepareUploadSubres(), QRhiVulkan::recordTransitionPassResources(), and QRhiVulkan::trackedImageBarrier().
|
protected |
Definition at line 995 of file qrhi.h.
Referenced by QNullTexture::create(), QRhiD3D11::endPass(), QRhiD3D11::enqueueResourceUpdates(), QRhiGles2::enqueueResourceUpdates(), QRhiVulkan::enqueueResourceUpdates(), QRhiD3D11::enqueueSubresUpload(), QRhiGles2::enqueueSubresUpload(), QRhiMetal::enqueueSubresUpload(), QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), QVkTexture::prepareCreate(), and QRhiVulkan::prepareUploadSubres().
|
protected |
Definition at line 998 of file qrhi.h.
Referenced by QD3D11Texture::prepareCreate(), QGles2Texture::prepareCreate(), QMetalTexture::prepareCreate(), and QVkTexture::prepareCreate().
1.9.7