diff options
Diffstat (limited to 'src/gui/rhi/qrhi.cpp')
| -rw-r--r-- | src/gui/rhi/qrhi.cpp | 905 |
1 files changed, 777 insertions, 128 deletions
diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp index 58bbc34941..a39709c726 100644 --- a/src/gui/rhi/qrhi.cpp +++ b/src/gui/rhi/qrhi.cpp @@ -16,7 +16,7 @@ #include "qrhid3d11_p.h" #include "qrhid3d12_p.h" #endif -#if defined(Q_OS_MACOS) || defined(Q_OS_IOS) +#if QT_CONFIG(metal) #include "qrhimetal_p.h" #endif @@ -29,7 +29,8 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") /*! \class QRhi \ingroup painting-3D - \inmodule QtGui + \inmodule QtGuiPrivate + \inheaderfile rhi/qrhi.h \since 6.6 \brief Accelerated 2D/3D graphics API abstraction. @@ -71,19 +72,22 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") builds on QOpenGLContext, QOpenGLFunctions, and the related cross-platform infrastructure of the Qt GUI module. - \li Direct3D 11.1 or newer, with Shader Model 5.0 or newer . When the D3D + \li Direct3D 11.1 or newer, with Shader Model 5.0 or newer. When the D3D runtime has no support for 11.1 features or Shader Model 5.0, initialization using an accelerated graphics device will fail, but using the \l{https://learn.microsoft.com/en-us/windows/win32/direct3darticles/directx-warp}{software adapter} is still an option. - \li Direct3D 12.0 or newer. The D3D12 device is by default created with - specifying a minimum feature level of \c{D3D_FEATURE_LEVEL_11_0}. + \li Direct3D 12 on Windows 10 version 1703 and newer, with Shader Model 5.0 + or newer. Qt requires ID3D12Device2 to be present, hence the requirement + for at least version 1703 of Windows 10. The D3D12 device is by default + created with specifying a minimum feature level of + \c{D3D_FEATURE_LEVEL_11_0}. \li Metal 1.2 or newer. - \li Vulkan 1.0 or newer , optionally utilizing some Vulkan 1.1 level + \li Vulkan 1.0 or newer, optionally utilizing some Vulkan 1.1 level features. \li Null, a "dummy" backend that issues no graphics calls at all. @@ -650,7 +654,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") mechanism because the cost of maintaining the related data structures is not insignificant with some backends. With Vulkan this feature maps directly to VkPipelineCache, vkGetPipelineCacheData and - VkPipelineCacheCreateInfo::pInitialData. With D3D11 there is no real + VkPipelineCacheCreateInfo::pInitialData. With Direct3D 11 there is no real pipline cache, but the results of HLSL->DXBC compilations are stored and can be serialized/deserialized via this mechanism. This allows skipping the time consuming D3DCompile() in future runs of the applications for shaders @@ -662,6 +666,17 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") mechanisms for shader/program binaries provided by Qt. Writing to those may get disabled whenever this flag is set since storing program binaries to multiple caches is not sensible. + + \value SuppressSmokeTestWarnings Indicates that, with backends where this + is relevant, certain, non-fatal QRhi::create() failures should not + produce qWarning() calls. For example, with D3D11, passing this flag + makes a number of warning messages (that appear due to QRhi::create() + failing) to become categorized debug prints instead under the commonly used + \c{qt.rhi.general} logging category. This can be used by engines, such as + Qt Quick, that feature fallback logic, i.e. they retry calling create() + with a different set of flags (such as, \l PreferSoftwareRenderer), in order + to hide the unconditional warnings from the output that would be printed + when the first create() attempt had failed. */ /*! @@ -699,9 +714,12 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") QRhiCommandBuffer::debugMarkBegin()) are supported. \value Timestamps Indicates that command buffer timestamps are supported. - Relevant for QRhiCommandBuffer::lastCompletedGpuTime(). Can be expected to - be supported on Metal, Vulkan, and Direct 3D, assuming the underlying - implementation supports timestamp queries or similar. + Relevant for QRhiCommandBuffer::lastCompletedGpuTime(). This can be + expected to be supported on Metal, Vulkan, Direct 3D 11 and 12, and OpenGL + contexts of version 3.3 or newer. However, with some of these APIs support + for timestamp queries is technically optional, and therefore it cannot be + guaranteed that this feature is always supported with every implementation + of them. \value Instancing Indicates that instanced drawing is supported. In practice this feature will be unsupported with OpenGL ES 2.0 and OpenGL @@ -771,7 +789,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") \value WideLines Indicates that lines with a width other than 1 are supported. When reported as not supported, the line width set on the graphics pipeline state is ignored. This can always be false with some - backends (D3D11, Metal). With Vulkan, the value depends on the + backends (D3D11, D3D12, Metal). With Vulkan, the value depends on the implementation. With OpenGL, wide lines are not supported in core profile contexts. @@ -932,7 +950,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") with image load/store. This feature is only available with some backends as it does not map well to all graphics APIs, and it is only meant to provide support for special cases anyhow. In practice the feature can be expected to - be supported with Direct3D 11 and Vulkan. + be supported with Direct3D 11/12 and Vulkan. \value NonFillPolygonMode Indicates that setting a PolygonMode other than the default Fill is supported for QRhiGraphicsPipeline. A common use case @@ -953,8 +971,8 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") When not supported, build() will succeed but just show a warning message and the values of the target attributes will be broken. In practice this feature will be unsupported in some OpenGL ES 2.0 and OpenGL 2.x - implementations. Note that while D3D does support half precision input - attributes, it does not support the half3 type. The D3D backends pass + implementations. Note that while Direct3D 11/12 does support half precision + input attributes, it does not support the half3 type. The D3D backends pass half3 attributes as half4. To ensure cross platform compatibility, half3 inputs should be padded to 8 bytes. @@ -966,6 +984,58 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") \value ThreeDimensionalTextureMipmaps Indicates that generating 3D texture mipmaps are supported. In practice this feature will be unsupported with Direct 3D 12. + + \value MultiView Indicates that multiview, see e.g. + \l{https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_multiview.html}{VK_KHR_multiview} + is supported. With OpenGL ES 2.0, Direct 3D 11, and OpenGL (ES) + implementations without \c{GL_OVR_multiview2} this feature will not be + supported. With Vulkan 1.1 and newer, and Direct 3D 12 multiview is + typically supported. When reported as supported, creating a + QRhiTextureRenderTarget with a QRhiColorAttachment that references a texture + array and has \l{QRhiColorAttachment::setMultiViewCount()}{multiViewCount} + set enables recording a render pass that uses multiview rendering. In addition, + any QRhiGraphicsPipeline used in that render pass must have + \l{QRhiGraphicsPipeline::setMultiViewCount()}{the same view count set}. Note that + multiview is only available in combination with 2D texture arrays. It cannot + be used to optimize the rendering into individual textures (e.g. two, for + the left and right eyes). Rather, the target of a multiview render pass is + always a texture array, automatically rendering to the layer (array element) + corresponding to each view. Therefore this feature implies \l TextureArrays + as well. Multiview rendering is not supported in combination with + tessellation or geometry shaders. See QRhiColorAttachment::setMultiViewCount() + for further details on multiview rendering. This enum value has been introduced in Qt 6.7. + + \value TextureViewFormat Indicates that setting a + \l{QRhiTexture::setWriteViewFormat()}{view format} on a QRhiTexture is + effective. When reported as supported, setting the read (sampling) or write + (render target / image load-store) view mode changes the texture's viewing + format. When unsupported, setting a view format has no effect. Note that Qt + has no knowledge or control over format compatibility or resource view rules + in the underlying 3D API and its implementation. Passing in unsuitable, + incompatible formats may lead to errors and unspecified behavior. This is + provided mainly to allow "casting" rendering into a texture created with an + sRGB format to non-sRGB to avoid the unwanted linear->sRGB conversion on + shader writes. Other types of casting may or may not be functional, + depending on the underlying API. Currently implemented for Vulkan and Direct + 3D 12. With D3D12 the feature is available only if + \c CastingFullyTypedFormatSupported is supported, see + \l{https://microsoft.github.io/DirectX-Specs/d3d/RelaxedCasting.html} (and + note that QRhi always uses fully typed formats for textures.) This enum + value has been introduced in Qt 6.8. + + \value ResolveDepthStencil Indicates that resolving a multisample depth or + depth-stencil texture is supported. Otherwise, + \l{QRhiTextureRenderTargetDescription::setDepthResolveTexture()}{setting a + depth resolve texture} is not functional and must be avoided. Direct 3D 11 + and 12 have no support for resolving depth/depth-stencil formats, and + therefore this feature will never be supported with those. Vulkan 1.0 has no + API to request resolving a depth-stencil attachment. Therefore, with Vulkan + this feature will only be supported with Vulkan 1.2 and up, and on 1.1 + implementations with the appropriate extensions present. This feature is + provided for the rare case when resolving into a non-multisample depth + texture becomes necessary, for example when rendering into an + OpenXR-provided depth texture (XR_KHR_composition_layer_depth). This enum + value has been introduced in Qt 6.8. */ /*! @@ -1083,7 +1153,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") Contains fields that are relevant to all backends. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -1093,7 +1163,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general") \since 6.6 \brief Specifies clear values for a depth or stencil buffer. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -1188,7 +1258,7 @@ QDebug operator<<(QDebug dbg, const QRhiDepthStencilClearValue &v) // ... \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiCommandBuffer::setViewport(), QRhi::clipSpaceCorrMatrix(), QRhiScissor @@ -1308,7 +1378,7 @@ QDebug operator<<(QDebug dbg, const QRhiViewport &v) appropriate. Therefore, any rendering logic targeting OpenGL can feed scissor rectangles into QRhiScissor as-is, without any adaptation. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiCommandBuffer::setScissor(), QRhiViewport @@ -1436,7 +1506,7 @@ QDebug operator<<(QDebug dbg, const QRhiScissor &s) \note the stride must always be a multiple of 4. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiCommandBuffer::setVertexInput() @@ -1605,7 +1675,7 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b) cb->setVertexInput(0, 1, &vbufBinding); \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiCommandBuffer::setVertexInput() @@ -1634,12 +1704,22 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b) \value Half3 Three component half precision (16 bit) float vector \value Half2 Two component half precision (16 bit) float vector \value Half Half precision (16 bit) float + \value UShort4 Four component unsigned short (16 bit) integer vector + \value UShort3 Three component unsigned short (16 bit) integer vector + \value UShort2 Two component unsigned short (16 bit) integer vector + \value UShort Unsigned short (16 bit) integer + \value SShort4 Four component signed short (16 bit) integer vector + \value SShort3 Three component signed short (16 bit) integer vector + \value SShort2 Two component signed short (16 bit) integer vector + \value SShort Signed short (16 bit) integer \note Support for half precision floating point attributes is indicated at - run time by the QRhi::Feature::HalfAttributes feature flag. Note that D3D - supports half input attributes, but does not support the Half3 type. The - D3D backends pass through Half3 as Half4. To ensure cross platform - compatibility, Half3 inputs should be padded to 8 bytes. + run time by the QRhi::Feature::HalfAttributes feature flag. + + \note Direct3D 11/12 supports 16 bit input attributes, but does not support + the Half3, UShort3 or SShort3 types. The D3D backends pass through Half3 as + Half4, UShort3 as UShort4, and SShort3 as SShort4. To ensure cross platform + compatibility, 16 bit inputs should be padded to 8 bytes. */ /*! @@ -1851,6 +1931,24 @@ quint32 QRhiImplementation::byteSizePerVertexForVertexInputFormat(QRhiVertexInpu case QRhiVertexInputAttribute::Half: return sizeof(qfloat16); + case QRhiVertexInputAttribute::UShort4: + return 4 * sizeof(quint16); + case QRhiVertexInputAttribute::UShort3: + return 4 * sizeof(quint16); // ivec3 still takes 8 bytes + case QRhiVertexInputAttribute::UShort2: + return 2 * sizeof(quint16); + case QRhiVertexInputAttribute::UShort: + return sizeof(quint16); + + case QRhiVertexInputAttribute::SShort4: + return 4 * sizeof(qint16); + case QRhiVertexInputAttribute::SShort3: + return 4 * sizeof(qint16); // uvec3 still takes 8 bytes + case QRhiVertexInputAttribute::SShort2: + return 2 * sizeof(qint16); + case QRhiVertexInputAttribute::SShort: + return sizeof(qint16); + default: Q_UNREACHABLE_RETURN(1); } @@ -1883,7 +1981,7 @@ quint32 QRhiImplementation::byteSizePerVertexForVertexInputFormat(QRhiVertexInpu }); \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -2006,9 +2104,7 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputLayout &v) QShader getShader(const QString &name) { QFile f(name); - if (f.open(QIODevice::ReadOnly)) - return QShader::fromSerialized(f.readAll()); - return QShader(); + return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader(); } QShader vs = getShader("material.vert.qsb"); @@ -2019,7 +2115,7 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputLayout &v) }); \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -2169,7 +2265,7 @@ QDebug operator<<(QDebug dbg, const QRhiShaderStage &s) out at all. This means that the multisample texture() must not be used afterwards with shaders for sampling when resolveTexture() is set. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiTextureRenderTargetDescription @@ -2263,16 +2359,40 @@ QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer) \nullptr if there is none. Setting a non-null resolve texture is applicable when the attachment - references a multisample, color renderbuffer. (i.e., renderBuffer() is set) - The QRhiTexture in the resolveTexture() is then a regular, 2D, - non-multisample texture with the same size (but a sample count of 1). The - multisample content is automatically resolved into this texture at the end - of each render pass. + references a multisample texture or renderbuffer. The QRhiTexture in the + resolveTexture() is then a non-multisample 2D texture (or texture array) + with the same size (but a sample count of 1). The multisample content is + automatically resolved into this texture at the end of each render pass. */ /*! \fn void QRhiColorAttachment::setResolveTexture(QRhiTexture *tex) + Sets the resolve texture \a tex. + + \a tex is expected to be a 2D texture or a 2D texture array. In either + case, resolving targets a single mip level of a single layer (array + element) of \a tex. The mip level and array layer are specified by + resolveLevel() and resolveLayer(). + + An exception is \l{setMultiViewCount()}{multiview}: when the color + attachment is associated with a texture array and multiview is enabled, the + resolve texture must also be a texture array with sufficient elements for + all views. In this case all elements that correspond to views are resolved + automatically; the behavior is similar to the following pseudo-code: + \badcode + for (i = 0; i < multiViewCount(); ++i) + resolve texture's layer() + i into resolveTexture's resolveLayer() + i + \endcode + + Setting a non-multisample texture to resolve a multisample texture or + renderbuffer automatically at the end of the render pass is often + preferable to working with multisample textures (and not setting a resolve + texture), because it avoids the need for writing dedicated fragment shaders + that work exclusively with multisample textures (\c sampler2DMS, \c + texelFetch, etc.), and rather allows using the same shader as one would if + the attachment's texture was not multisampled to begin with. This comes at + the expense of an additional resource (the non-multisample \a tex). */ /*! @@ -2296,6 +2416,71 @@ QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer) */ /*! + \fn int QRhiColorAttachment::multiViewCount() const + + \return the currently set number of views. Defaults to 0 which indicates + the render target with this color attachment is not going to be used with + multiview rendering. + + \since 6.7 + */ + +/*! + \fn void QRhiColorAttachment::setMultiViewCount(int count) + + Sets the view \a count. Setting a value larger than 1 indicates that the + render target with this color attachment is going to be used with multiview + rendering. The default value is 0. Values smaller than 2 indicate no + multiview rendering. + + When \a count is set to \c 2 or greater, the color attachment must be + associated with a 2D texture array. layer() and multiViewCount() together + define the range of texture array elements that are targeted during + multiview rendering. + + For example, if \c layer is \c 0 and \c multiViewCount is \c 2, the texture + array must have 2 (or more) elements, and the multiview rendering will + target elements 0 and 1. The \c{gl_ViewIndex} variable in the shaders has a + value of \c 0 or \c 1 then, where view \c 0 corresponds to the texture array + element \c 0, and view \c 1 to the array element \c 1. + + \note Setting a \a count larger than 1, using a texture array as texture(), + and calling \l{QRhiCommandBuffer::beginPass()}{beginPass()} on a + QRhiTextureRenderTarget with this color attachment implies multiview + rendering for the entire render pass. multiViewCount() should not be set + unless multiview rendering is wanted. Multiview cannot be used with texture + types other than 2D texture arrays. (although 3D textures may work, + depending on the graphics API and backend; applications are nonetheless + advised not to rely on that and only use 2D texture arrays as the render + targets of multiview rendering) + + See + \l{https://registry.khronos.org/OpenGL/extensions/OVR/OVR_multiview.txt}{GL_OVR_multiview} + for more details regarding multiview rendering. Do note that Qt requires + \l{https://registry.khronos.org/OpenGL/extensions/OVR/OVR_multiview2.txt}{GL_OVR_multiview2} + as well, when running on OpenGL (ES). + + Multiview rendering is available only when the + \l{QRhi::MultiView}{MultiView} feature is reported as supported from + \l{QRhi::isFeatureSupported()}{isFeatureSupported()}. + + \note For portability, be aware of limitations that exist for multiview + rendering with some of the graphics APIs. It is recommended that multiview + render passes do not rely on any of the features that + \l{https://registry.khronos.org/OpenGL/extensions/OVR/OVR_multiview.txt}{GL_OVR_multiview} + declares as unsupported. The one exception is shader stage outputs other + than \c{gl_Position} depending on \c{gl_ViewIndex}: that can be relied on + (even with OpenGL) because QRhi never reports multiview as supported without + \c{GL_OVR_multiview2} also being present. + + \note Multiview rendering is not supported in combination with tessellation + or geometry shaders, even though some implementations of some graphics APIs + may allow this. + + \since 6.7 + */ + +/*! \class QRhiTextureRenderTargetDescription \inmodule QtGui \since 6.6 @@ -2371,7 +2556,26 @@ QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer) QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt, depthStencil }); \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note when multisample resolving is enabled, the multisample data may not be + written out at all. This means that the multisample texture in a color + attachment must not be used afterwards with shaders for sampling (or other + purposes) whenever a resolve texture is set, since the multisample color + buffer is merely an intermediate storage then that gets no data written back + on some GPU architectures at all. See + \l{QRhiTextureRenderTarget::Flag}{PreserveColorContents} for more details. + + \note When using setDepthTexture(), not setDepthStencilBuffer(), and the + depth (stencil) data is not of interest afterwards, set the + DoNotStoreDepthStencilContents flag on the QRhiTextureRenderTarget. This + allows indicating to the underlying 3D API that the depth/stencil data can + be discarded, leading potentially to better performance with tiled GPU + architectures. When the depth-stencil buffer is a QRhiRenderBuffer (and also + for the multisample color texture, see previous note) this is implicit, but + with a depth (stencil) QRhiTexture the intention needs to be declared + explicitly. By default QRhi assumes that the data is of interest (e.g., the + depth texture is sampled in a shader afterwards). + + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiColorAttachment, QRhiTextureRenderTarget @@ -2464,6 +2668,16 @@ QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRh \note depthStencilBuffer() and depthTexture() cannot be both set (cannot be non-null at the same time). + + Using a QRhiRenderBuffer over a 2D QRhiTexture as the depth or + depth/stencil buffer is very common, and is the recommended approach for + applications. Using a QRhiTexture, and so setDepthTexture() becomes + relevant if the depth data is meant to be accessed (e.g. sampled in a + shader) afterwards, or when + \l{QRhiColorAttachment::setMultiViewCount()}{multiview rendering} is + involved (because then the depth texture must be a texture array). + + \sa setDepthTexture() */ /*! @@ -2480,6 +2694,49 @@ QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRh \note depthStencilBuffer() and depthTexture() cannot be both set (cannot be non-null at the same time). + + \a texture can either be a 2D texture or a 2D texture array (when texture + arrays are supported). Specifying a texture array is relevant in particular + with + \l{QRhiColorAttachment::setMultiViewCount()}{multiview rendering}. + + \note If \a texture is a format with a stencil component, such as + \l QRhiTexture::D24S8, it will serve as the stencil buffer as well. + + \sa setDepthStencilBuffer() + */ + +/*! + \fn QRhiTexture *QRhiTextureRenderTargetDescription::depthResolveTexture() const + + \return the texture to which a multisample depth (or depth-stencil) texture + (or texture array) is resolved to. \nullptr if there is none, which is the + most common case. + + \since 6.8 + \sa QRhiColorAttachment::resolveTexture(), depthTexture() + */ + +/*! + \fn void QRhiTextureRenderTargetDescription::setDepthResolveTexture(QRhiTexture *tex) + + Sets the depth (or depth-stencil) resolve texture \a tex. + + \a tex is expected to be a 2D texture or a 2D texture array with a format + matching the texture set via setDepthTexture(). + + \note Resolving depth (or depth-stencil) data is only functional when the + \l ResolveDepthStencil feature is reported as supported at run time. Support + for depth-stencil resolve is not universally available among the graphics + APIs. Designs assuming unconditional availability of depth-stencil resolve + are therefore non-portable, and should be avoided. + + \note As an additional limitation for OpenGL ES in particular, setting a + depth resolve texture may only be functional in combination with + setDepthTexture(), not with setDepthStencilBuffer(). + + \since 6.8 + \sa QRhiColorAttachment::setResolveTexture(), setDepthTexture() */ /*! @@ -2543,7 +2800,7 @@ QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRh caller is strongly encouraged to call QImage::detach() on the image before passing it to uploadTexture(). - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiTextureUploadDescription @@ -2606,6 +2863,7 @@ QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription \fn void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image) Sets \a image. + Upon textures loading, the image data will be read as is, with no formats conversions. \note image() and data() cannot be both set at the same time. */ @@ -2698,7 +2956,7 @@ QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription \brief Describes one layer (face for cubemaps, slice for 3D textures, element for texture arrays) in a texture upload operation. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -2838,7 +3096,7 @@ QRhiTextureUploadEntry::QRhiTextureUploadEntry(int layer, int level, resourceUpdates->uploadTexture(texture, desc); \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiResourceUpdateBatch @@ -2927,7 +3185,7 @@ QRhiTextureUploadDescription::QRhiTextureUploadDescription(std::initializer_list differ, but the size and position must be carefully controlled to avoid out of bounds copies, in which case the behavior is undefined. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -3033,7 +3291,7 @@ QRhiTextureUploadDescription::QRhiTextureUploadDescription(std::initializer_list \note Multisample textures cannot be read back. Readbacks are supported for multisample swapchain buffers however. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -3124,7 +3382,7 @@ QRhiReadbackDescription::QRhiReadbackDescription(QRhiTexture *texture) available. \l format and \l pixelSize are set upon completion together with \l data. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -3162,7 +3420,7 @@ QRhiReadbackDescription::QRhiReadbackDescription(QRhiTexture *texture) \since 6.6 \brief Base class for classes exposing backend-specific collections of native resource objects. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -3172,7 +3430,7 @@ QRhiReadbackDescription::QRhiReadbackDescription(QRhiTexture *texture) \since 6.6 \brief Base class for classes encapsulating native resource objects. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -3353,7 +3611,7 @@ QRhi *QRhiResource::rhi() const \since 6.6 \brief Vertex, index, or uniform (constant) buffer resource. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. A QRhiBuffer encapsulates zero, one, or more native buffer objects (such as @@ -3460,7 +3718,7 @@ QRhi *QRhiResource::rhi() const QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch(); for (int i = 0; i < N; ++i) { batch->updateDynamicBuffer(ubuf, i * ONE_UBUF_SIZE, 64, matrix.constData()); - updates->updateDynamicBuffer(ubuf, i * ONE_UBUF_SIZE + 64, 4, &opacity); + batch->updateDynamicBuffer(ubuf, i * ONE_UBUF_SIZE + 64, 4, &opacity); } // ... // beginPass(), set pipeline, etc., and then: @@ -3541,10 +3799,13 @@ QRhi *QRhiResource::rhi() const objects array are pointers to a GLuint. With Vulkan, the native handle is a VkBuffer, so the elements of the array are pointers to a VkBuffer. With Direct3D 11 and Metal the elements are pointers to a ID3D11Buffer or - MTLBuffer pointer, respectively. + MTLBuffer pointer, respectively. With Direct3D 12, the elements are + pointers to a ID3D12Resource. \note Pay attention to the fact that the elements are always pointers to the native buffer handle type, even if the native type itself is a pointer. + (so the elements are \c{VkBuffer *} on Vulkan, even though VkBuffer itself + is a pointer on 64-bit architectures). */ /*! @@ -3748,7 +4009,7 @@ void QRhiBuffer::endFullDynamicBufferUpdateForCurrentFrame() means calling setPixelSize() and create() are not necessary for such renderbuffers. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -3973,7 +4234,7 @@ bool QRhiRenderBuffer::createFrom(NativeRenderBuffer src) // continue using texture, fill it with new data \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiResourceUpdateBatch, QRhi, QRhiTextureRenderTarget @@ -4140,9 +4401,10 @@ bool QRhiRenderBuffer::createFrom(NativeRenderBuffer src) \brief 64-bit integer containing the native object handle. With OpenGL, the native handle is a GLuint value, so \c object can then be - cast to a GLuint. With Vulkan, the native handle is a VkImage, so \c - object can be cast to a VkImage. With Direct3D 11 and Metal \c - object contains a ID3D11Texture2D or MTLTexture pointer, respectively. + cast to a GLuint. With Vulkan, the native handle is a VkImage, so \c object + can be cast to a VkImage. With Direct3D 11 and Metal \c object contains a + ID3D11Texture2D or MTLTexture pointer, respectively. With Direct3D 12 + \c object contains a ID3D12Resource pointer. */ /*! @@ -4359,12 +4621,93 @@ void QRhiTexture::setNativeLayout(int layout) */ /*! + \struct QRhiTexture::ViewFormat + \inmodule QtGui + \since 6.8 + \brief Specifies the view format for reading or writing from or to the texture. + + \note This is a RHI API with limited compatibility guarantees, see \l QRhi + for details. + */ + +/*! + \variable QRhiTexture::ViewFormat::format + */ + +/*! + \variable QRhiTexture::ViewFormat::srgb + */ + +/*! + \fn QRhiTexture::ViewFormat QRhiTexture::readViewFormat() const + \since 6.8 + \return the view format used when sampling the texture. When not called, the view + format is assumed to be the same as format(). + */ + +/*! + \fn void QRhiTexture::setReadViewFormat(const ViewFormat &fmt) + \since 6.8 + + Sets the shader resource view format (or the format of the view used for + sampling the texture) to \a 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. + + \note This functionality is provided to allow "casting" between + non-sRGB and sRGB in order to get the shader reads perform, or not perform, + the implicit sRGB conversions. Other types of casting may or may not be + functional. + */ + +/*! + \fn QRhiTexture::ViewFormat QRhiTexture::writeViewFormat() const + \since 6.8 + \return the view format used when writing to the texture and when using it + with image load/store. When not called, the view format is assumed to be the + same as format(). + */ + +/*! + \fn void QRhiTexture::setWriteViewFormat(const ViewFormat &fmt) + \since 6.8 + + Sets the render target view format to \a 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 \c srgb set to + \c false). + + This setting is only taken into account when the \l TextureViewFormat + feature is reported as supported. + + \note This functionality is provided to allow "casting" between + non-sRGB and sRGB in order to get the shader write not perform, or perform, + the implicit sRGB conversions. Other types of casting may or may not be + functional. + */ + +/*! \class QRhiSampler \inmodule QtGui \since 6.6 \brief Sampler resource. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -4505,7 +4848,7 @@ QRhiResource::Type QRhiSampler::resourceType() const a collection of attachments (color, depth, stencil) and describes how those attachments are used. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -4624,7 +4967,7 @@ const QRhiNativeHandles *QRhiRenderPassDescriptor::nativeHandles() QRhiSwapChain returns when calling \l{QRhiSwapChain::currentFrameRenderTarget()}{currentFrameRenderTarget()}. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiSwapChainRenderTarget, QRhiTextureRenderTarget @@ -4703,7 +5046,7 @@ QRhiSwapChainRenderTarget::QRhiSwapChainRenderTarget(QRhiImplementation *rhi, QR QRhiSwapChainRenderTarget. This is what QRhiSwapChain::currentFrameRenderTarget() returns. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiSwapChain @@ -4752,7 +5095,7 @@ QRhiResource::Type QRhiSwapChainRenderTarget::resourceType() const // rt can now be used with beginPass() \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -4768,7 +5111,19 @@ QRhiResource::Type QRhiSwapChainRenderTarget::resourceType() const \value PreserveColorContents Indicates that the contents of the color attachments is to be loaded when starting a render pass, instead of clearing. This is potentially more expensive, especially on mobile (tiled) - GPUs, but allows preserving the existing contents between passes. + GPUs, but allows preserving the existing contents between passes. When doing + multisample rendering with a resolve texture set, setting this flag also + requests the multisample color data to be stored (written out) to the + multisample texture or render buffer. (for non-multisample rendering the + color data is always stored, but for MSAA storing the multisample data + decreases efficiency for certain GPU architectures, hence defaulting to not + writing it out) Note however that this is non-portable: in some cases there + is no intermediate multisample texture on the graphics API level, e.g. when + using OpenGL ES's \c{GL_EXT_multisampled_render_to_texture} as it is all + implicit, handled by the OpenGL ES implementation. In that case, + PreserveColorContents will likely have no effect. Therefore, avoid relying + on this flag when using multisample rendering and the color attachment is + using a multisample QRhiTexture (not QRhiRenderBuffer). \value PreserveDepthStencilContents Indicates that the contents of the depth texture is to be loaded when starting a render pass, instead @@ -4776,6 +5131,13 @@ QRhiResource::Type QRhiSwapChainRenderTarget::resourceType() const (QRhiTextureRenderTargetDescription::depthTexture() is set) because depth/stencil renderbuffers may not have any physical backing and data may not be written out in the first place. + + \value DoNotStoreDepthStencilContents Indicates that the contents of the + depth texture does not need to be written out. Relevant only when a + QRhiTexture, not QRhiRenderBuffer, is used as the depth-stencil buffer, + because for QRhiRenderBuffer this is implicit. When a depthResolveTexture is + set, the flag is not relevant, because the behavior is then as if the flag + was set. This enum value is introduced in Qt 6.8. */ /*! @@ -4933,11 +5295,19 @@ QRhiResource::Type QRhiTextureRenderTarget::resourceType() const cb->setShaderResources(srb2); // binds srb2 \endcode - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ /*! + \typedef QRhiShaderResourceBindingSet + \relates QRhi + \since 6.7 + + Synonym for QRhiShaderResourceBindings. +*/ + +/*! \internal */ QRhiShaderResourceBindings::QRhiShaderResourceBindings(QRhiImplementation *rhi) @@ -5064,7 +5434,7 @@ void QRhiImplementation::updateLayoutDesc(QRhiShaderResourceBindings *srb) static functions such as uniformBuffer() or sampledTexture() to get an instance. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -6085,7 +6455,7 @@ QDebug operator<<(QDebug dbg, const QRhiShaderResourceBindings &srb) four channels, depth test/write are disabled, stencil operations are disabled. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiCommandBuffer, QRhi @@ -6258,7 +6628,7 @@ QDebug operator<<(QDebug dbg, const QRhiShaderResourceBindings &srb) mode Qt Quick uses, it is enough to set the \c enable flag to true while leaving other values at their defaults. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -6308,7 +6678,7 @@ QDebug operator<<(QDebug dbg, const QRhiShaderResourceBindings &srb) \li compareOp \l Always \endlist - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -6688,6 +7058,29 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const */ /*! + \fn int QRhiGraphicsPipeline::multiViewCount() const + \return the view count. The default is 0, indicating no multiview rendering. + \since 6.7 + */ + +/*! + \fn void QRhiGraphicsPipeline::setMultiViewCount(int count) + Sets the view \a count for multiview rendering. The default is 0, + indicating no multiview rendering. + \a count must be 2 or larger to trigger multiview rendering. + + Multiview is only available when the \l{QRhi::MultiView}{MultiView feature} + is reported as supported. The render target must be a 2D texture array, and + the color attachment for the render target must have the same \a count set. + + See QRhiColorAttachment::setMultiViewCount() for further details on + multiview rendering. + + \since 6.7 + \sa QRhi::MultiView, QRhiColorAttachment::setMultiViewCount() + */ + +/*! \class QRhiSwapChain \inmodule QtGui \since 6.6 @@ -6825,7 +7218,7 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const appropriate sample count also via QSurfaceFormat, by calling QSurfaceFormat::setDefaultFormat() before initializing the QRhi. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -6885,6 +7278,14 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const \enum QRhiSwapChain::Format Describes the swapchain format. The default format is SDR. + This enum is used with + \l{QRhiSwapChain::isFormatSupported()}{isFormatSupported()} to check + upfront if creating the swapchain with the given format is supported by the + platform and the window's associated screen, and with + \l{QRhiSwapChain::setFormat()}{setFormat()} + to set the requested format in the swapchain before calling + \l{QRhiSwapChain::createOrResize()}{createOrResize()} for the first time. + \value SDR 8-bit RGBA or BGRA, depending on the backend and platform. With OpenGL ES in particular, it could happen that the platform provides less than 8 bits (e.g. due to EGL and the QSurfaceFormat choosing a 565 or 444 @@ -6896,10 +7297,14 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const (same as SDR/sRGB) and linear colors. Conversion to the display's native color space (such as, HDR10) is performed by the windowing system. On Windows this is the canonical color space of the system compositor, and is - the recommended format for HDR swapchains in general. + the recommended format for HDR swapchains in general on desktop platforms. \value HDR10 10-bit unsigned int RGB or BGR with 2 bit alpha, high dynamic range, HDR10 (Rec. 2020) color space with an ST2084 PQ transfer function. + + \value HDRExtendedDisplayP3Linear 16-bit float RGBA, high dynamic range, + extended linear Display P3 color space. The primary choice for HDR on + platforms such as iOS and VisionOS. */ /*! @@ -6993,6 +7398,21 @@ QRhiResource::Type QRhiSwapChain::resourceType() const time. If the result is true for a HDR format, then creating the swapchain with that format is expected to succeed as long as the window is not moved to another screen in the meantime. + + The main use of this function is to call it before the first + createOrResize() after the window is already set. This allow the QRhi + backends to perform platform or windowing system specific queries to + determine if the window (and the screen it is on) is capable of true HDR + output with the specified format. + + When the format is reported as supported, call setFormat() to set the + requested format and call createOrResize(). Be aware of the consequences + however: successfully requesting a HDR format will involve having to deal + with a different color space, possibly doing white level correction for + non-HDR-aware content, adjusting tonemapping methods, adjusting offscreen + render target settings, etc. + + \sa setFormat() */ /*! @@ -7041,10 +7461,9 @@ QRhiResource::Type QRhiSwapChain::resourceType() const is backed by two color buffers, one for each eye, instead of just one. When stereoscopic rendering is not supported, the return value will be - the default target. For the time being the only backend and 3D API where traditional - stereoscopic rendering is supported is OpenGL (excluding OpenGL ES), in + the default target. It is supported by all hardware backends except for Metal, in combination with \l QSurfaceFormat::StereoBuffers, assuming it is supported - by the graphics and display driver stack at run time. All other backends + by the graphics and display driver stack at run time. Metal and Null backends are going to return the default render target from this overload. \note the value must not be cached and reused between frames @@ -7111,6 +7530,15 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar /*! \fn void QRhiSwapChain::setFormat(Format f) Sets the format \a f. + + Avoid setting formats that are reported as unsupported from + isFormatSupported(). Note that support for a given format may depend on the + screen the swapchain's associated window is opened on. On some platforms, + such as Windows and macOS, for HDR output to work it is necessary to have + HDR output enabled in the display settings. + + See isFormatSupported(), \l QRhiSwapChainHdrInfo, and \l Format for more + information on high dynamic range output. */ /*! @@ -7172,11 +7600,12 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar \brief Describes the high dynamic range related information of the swapchain's associated output. - To perform tonemapping, one often needs to know the maximum luminance of - the display the swapchain's window is associated with. While this is often - made user-configurable, it can be highly useful to set defaults based on - the values reported by the display itself, thus providing a decent starting - point. + To perform HDR-compatible tonemapping, where the target range is not [0,1], + one often needs to know the maximum luminance of the display the + swapchain's window is associated with. While this is often made + user-configurable (think brightness, gamma and similar settings in games), + it can be highly useful to set defaults based on the values reported by the + display itself, thus providing a decent starting point. There are some problems however: the information is exposed in different forms on different platforms, whereas with cross-platform graphics APIs @@ -7184,11 +7613,6 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar information is not in the scope of the API (and may rather be retrievable via other platform-specific means, if any). - The struct returned from QRhiSwapChain::hdrInfo() contains either some - hard-coded defaults, indicated by the \c isHardCodedDefaults field, or real - values received from an API such as DXGI (IDXGIOutput6) or Cocoa - (NSScreen). The default is 1000 nits for maximum luminance. - With Metal on macOS/iOS, there is no luminance values exposed in the platform APIs. Instead, the maximum color component value, that would be 1.0 in a non-HDR setup, is provided. The \c limitsType field indicates what @@ -7197,10 +7621,23 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar fit. With an API like Vulkan, where there is no way to get such information, the - values are always the built-in defaults and \c isHardCodedDefaults is - always true. - - \note This a RHI API with limited compatibility guarantees, see \l QRhi + values are always the built-in defaults. + + Therefore, the struct returned from QRhiSwapChain::hdrInfo() contains + either some hard-coded defaults or real values received from an API such as + DXGI (IDXGIOutput6) or Cocoa (NSScreen). When no platform queries are + available (or needs using platform facilities out of scope for QRhi), the + hard-coded defaults are a maximum luminance of 1000 nits and an SDR white + level of 200. + + The struct also exposes the presumed luminance behavior of the platform and + its compositor, to indicate what a color component value of 1.0 is treated + as in a HDR color buffer. In some cases it will be necessary to perform + color correction of non-HDR content composited with HDR content. To enable + this, the SDR white level is queried from the system on some platforms + (Windows) and exposed here. + + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhiSwapChain::hdrInfo() @@ -7217,16 +7654,20 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar */ /*! - \variable QRhiSwapChainHdrInfo::isHardCodedDefaults + \enum QRhiSwapChainHdrInfo::LuminanceBehavior - Set to true when the data in the QRhiSwapChainHdrInfo consists entirely of - the hard-coded default values, for example because there is no way to query - the relevant information with a given graphics API or platform. (or because - querying it can be achieved only by means, e.g. platform APIs in some other - area, that are out of scope for the QRhi layer of the Qt graphics stack to - handle) + \value SceneReferred Indicates that the color value of 1.0 is interpreted + as 80 nits. This is the behavior of HDR-enabled windows with the Windows + compositor. See + \l{https://learn.microsoft.com/en-us/windows/win32/direct3darticles/high-dynamic-range}{this + page} for more information on HDR on Windows. - \sa QRhiSwapChain::hdrInfo() + \value DisplayReferred Indicates that the color value of 1.0 is interpreted + as the value of the SDR white. (which can be e.g. 200 nits, but will vary + depending on screen brightness) This is the behavior of HDR-enabled windows + on Apple platforms. See + \l{https://developer.apple.com/documentation/metal/hdr_content/displaying_hdr_content_in_a_metal_layer}{this + page} for more information on Apple's EDR system. */ /*! @@ -7256,23 +7697,92 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar } luminanceInNits; \endcode - Whereas for macOS/iOS, the maximum color component value (e.g. supposedly - something larger than 1.0f) is provided: + On Windows the minimum and maximum luminance depends on the screen + brightness. While not relevant for desktops, on laptops the screen + brightness may change at any time. Increasing brightness implies decreased + maximum luminance. In addition, the results may also be dependent on the + HDR Content Brightness set in Windows Settings' System/Display/HDR view, + if there is such a setting. + + Note however that the changes made to the laptop screen's brightness or in + the system settings while the application is running are not necessarily + reflected in the returned values, meaning calling hdrInfo() again may still + return the same luminance range as before for the rest of the process' + lifetime. The exact behavior is up to DXGI and Qt has no control over it. + + \note The Windows compositor works in scene-referred mode for HDR content. + A color component value of 1.0 corresponds to a luminance of 80 nits. When + rendering non-HDR content (e.g. 2D UI elements), the correction of the + white level is often necessary. (e.g., outputting the fragment color (1, 1, + 1) will likely lead to showing a shade of white that is too dim on-screen) + See \l sdrWhiteLevel. + + For macOS/iOS, the current maximum and potential maximum color + component values are provided: \code struct { float maxColorComponentValue; + float maxPotentialColorComponentValue; } colorComponentValue; \endcode + The value may depend on the screen brightness, which on laptops means that + the result may change in the next call to hdrInfo() if the brightness was + changed in the meantime. The maximum screen brightness implies a maximum + color value of 1.0. + + \note Apple's EDR is display-referred. 1.0 corresponds to a luminance level + of SDR white (e.g. 200 nits), the value of which varies based on the screen + brightness and possibly other settings. The exact luminance value for that, + or the maximum luminance of the display, are not exposed to the + applications. + + \note It has been observed that the color component values are not set to + the correct larger-than-1 value right away on startup on some macOS + systems, but the values tend to change during or after the first frame. + \sa QRhiSwapChain::hdrInfo() */ /*! + \variable QRhiSwapChainHdrInfo::luminanceBehavior + + Describes the platform's presumed behavior with regards to color values. + + \sa sdrWhiteLevel + */ + +/*! + \variable QRhiSwapChainHdrInfo::sdrWhiteLevel + + On Windows this is the dynamic SDR white level in nits. The value is + dependent on the screen brightness (on laptops), and the SDR or HDR Content + Brightness settings in the Windows settings' System/Display/HDR view. + + To perform white level correction for non-HDR (SDR) content, such as 2D UI + elemenents, multiply the final color with sdrWhiteLevel / 80.0 whenever + \l luminanceBehavior is SceneReferred. (assuming Windows and a linear + extended sRGB (scRGB) color space) + + On other platforms the value is always a pre-defined value, 200. This may + not match the system's actual SDR white level, but the value of this + variable is not relevant in practice when the \l luminanceBehavior is + DisplayReferred, because then the color component value of 1.0 refers to + the SDR white by default. + + \sa luminanceBehavior +*/ + +/*! \return the HDR information for the associated display. - The returned struct is always the default one if createOrResize() has not - been successfully called yet. + Do not assume that this is a cheap operation. Depending on the platform, + this function makes various platform queries which may have a performance + impact. + + \note Can be called before createOrResize() as long as the window is + \l{setWindow()}{set}. \note What happens when moving a window with an initialized swapchain between displays (HDR to HDR with different characteristics, HDR to SDR, @@ -7287,10 +7797,11 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar QRhiSwapChainHdrInfo QRhiSwapChain::hdrInfo() { QRhiSwapChainHdrInfo info; - info.isHardCodedDefaults = true; info.limitsType = QRhiSwapChainHdrInfo::LuminanceInNits; info.limits.luminanceInNits.minLuminance = 0.0f; info.limits.luminanceInNits.maxLuminance = 1000.0f; + info.luminanceBehavior = QRhiSwapChainHdrInfo::SceneReferred; + info.sdrWhiteLevel = 200.0f; return info; } @@ -7298,7 +7809,7 @@ QRhiSwapChainHdrInfo QRhiSwapChain::hdrInfo() QDebug operator<<(QDebug dbg, const QRhiSwapChainHdrInfo &info) { QDebugStateSaver saver(dbg); - dbg.nospace() << "QRhiSwapChainHdrInfo(" << (info.isHardCodedDefaults ? "with hard-coded defaults" : "queried from system"); + dbg.nospace() << "QRhiSwapChainHdrInfo("; switch (info.limitsType) { case QRhiSwapChainHdrInfo::LuminanceInNits: dbg.nospace() << " minLuminance=" << info.limits.luminanceInNits.minLuminance @@ -7306,6 +7817,15 @@ QDebug operator<<(QDebug dbg, const QRhiSwapChainHdrInfo &info) break; case QRhiSwapChainHdrInfo::ColorComponentValue: dbg.nospace() << " maxColorComponentValue=" << info.limits.colorComponentValue.maxColorComponentValue; + dbg.nospace() << " maxPotentialColorComponentValue=" << info.limits.colorComponentValue.maxPotentialColorComponentValue; + break; + } + switch (info.luminanceBehavior) { + case QRhiSwapChainHdrInfo::SceneReferred: + dbg.nospace() << " scene-referred, SDR white level=" << info.sdrWhiteLevel; + break; + case QRhiSwapChainHdrInfo::DisplayReferred: + dbg.nospace() << " display-referred"; break; } dbg.nospace() << ')'; @@ -7325,7 +7845,7 @@ QDebug operator<<(QDebug dbg, const QRhiSwapChainHdrInfo &info) \note Setting the shader is mandatory. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -7407,7 +7927,7 @@ QRhiComputePipeline::QRhiComputePipeline(QRhiImplementation *rhi) QRhiSwapChain::currentFrameCommandBuffer(), or, in case of rendering completely offscreen, initializing one via QRhi::beginOffscreenFrame(). - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -7733,6 +8253,17 @@ void QRhiImplementation::textureFormatInfo(QRhiTexture::Format format, const QSi *bytesPerPixel = bpc; } +bool QRhiImplementation::isStencilSupportingFormat(QRhiTexture::Format format) const +{ + switch (format) { + case QRhiTexture::D24S8: + return true; + default: + break; + } + return false; +} + bool QRhiImplementation::sanityCheckGraphicsPipeline(QRhiGraphicsPipeline *ps) { if (ps->cbeginShaderStages() == ps->cendShaderStages()) { @@ -7852,6 +8383,41 @@ bool QRhiImplementation::sanityCheckShaderResourceBindings(QRhiShaderResourceBin return true; } +int QRhiImplementation::effectiveSampleCount(int sampleCount) const +{ + // Stay compatible with QSurfaceFormat and friends where samples == 0 means the same as 1. + const int s = qBound(1, sampleCount, 64); + const QList<int> supported = supportedSampleCounts(); + int result = 1; + + // Stay compatible with Qt 5 in that requesting an unsupported sample count + // is not an error (although we still do a categorized debug print about + // this), and rather a supported value, preferably a close one, not just 1, + // is used instead. This is actually deviating from Qt 5 as that performs a + // clamping only and does not handle cases such as when sample count 2 is + // not supported but 4 is. (OpenGL handles things like that gracefully, + // other APIs may not, so improve this by picking the next largest, or in + // absence of that, the largest value; this with the goal to not reduce + // quality by rather picking a larger-than-requested value than a smaller one) + + for (int i = 0, ie = supported.count(); i != ie; ++i) { + // assumes the 'supported' list is sorted + if (supported[i] >= s) { + result = supported[i]; + break; + } + } + + if (result != s) { + if (result == 1 && !supported.isEmpty()) + result = supported.last(); + qCDebug(QRHI_LOG_INFO, "Attempted to set unsupported sample count %d, using %d instead", + sampleCount, result); + } + + return result; +} + /*! \internal */ @@ -7867,11 +8433,11 @@ QRhi::~QRhi() if (!d) return; + runCleanup(); + qDeleteAll(d->pendingDeleteResources); d->pendingDeleteResources.clear(); - runCleanup(); - d->destroy(); delete d; } @@ -7959,7 +8525,7 @@ QRhi *QRhi::create(Implementation impl, QRhiInitParams *params, Flags flags, QRh break; #endif case Metal: -#if defined(Q_OS_MACOS) || defined(Q_OS_IOS) +#if QT_CONFIG(metal) r->d = new QRhiMetal(static_cast<QRhiMetalInitParams *>(params), static_cast<QRhiMetalNativeHandles *>(importDevice)); break; @@ -7969,10 +8535,18 @@ QRhi *QRhi::create(Implementation impl, QRhiInitParams *params, Flags flags, QRh #endif case D3D12: #ifdef Q_OS_WIN +#ifdef QRHI_D3D12_AVAILABLE r->d = new QRhiD3D12(static_cast<QRhiD3D12InitParams *>(params), static_cast<QRhiD3D12NativeHandles *>(importDevice)); break; #else + qWarning("Qt was built without Direct3D 12 support. " + "This is likely due to having ancient SDK headers (such as d3d12.h) in the Qt build environment. " + "Rebuild Qt with an SDK supporting D3D12 features introduced in Windows 10 version 1703, " + "or use an MSVC build as those typically are built with more up-to-date SDKs."); + break; +#endif +#else qWarning("This platform has no Direct3D 12 support"); break; #endif @@ -8010,7 +8584,7 @@ bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params) // create() and then drop the result. if (impl == Metal) { -#if defined(Q_OS_MACOS) || defined(Q_OS_IOS) +#if QT_CONFIG(metal) ok = QRhiMetal::probe(static_cast<QRhiMetalInitParams *>(params)); #endif } else { @@ -8028,7 +8602,7 @@ bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params) \brief Opaque data describing native objects needed to set up a swapchain. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. \sa QRhi::updateSwapChainProxyData() @@ -8061,7 +8635,7 @@ bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params) */ QRhiSwapChainProxyData QRhi::updateSwapChainProxyData(QRhi::Implementation impl, QWindow *window) { -#if defined(Q_OS_MACOS) || defined(Q_OS_IOS) +#if QT_CONFIG(metal) if (impl == Metal) return QRhiMetal::updateSwapChainProxyData(window); #else @@ -8113,9 +8687,11 @@ const char *QRhi::backendName() const /*! \enum QRhiDriverInfo::DeviceType - Specifies the graphics device's type, when the information is available. In - practice this is only applicable with Vulkan and Metal. With others the - value will always be UnknownDevice. + Specifies the graphics device's type, when the information is available. + + In practice this is only applicable with Vulkan and Metal. With Direct 3D + 11 and 12, using an adapter with the software flag set leads to the value + \c CpuDevice. Otherwise, and with OpenGL, the value is always UnknownDevice. \value UnknownDevice \value IntegratedDevice @@ -8141,7 +8717,7 @@ const char *QRhi::backendName() const for OpenGL and Metal. deviceType is always UnknownDevice for OpenGL and Direct 3D. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -8236,6 +8812,33 @@ void QRhi::addCleanupCallback(const CleanupCallback &callback) } /*! + \overload + + Registers \a callback to be invoked either when the QRhi is destroyed or + when runCleanup() is called. This overload takes an opaque pointer, \a key, + that is used to ensure that a given callback is registered (and so called) + only once. + + \sa removeCleanupCallback() + */ +void QRhi::addCleanupCallback(const void *key, const CleanupCallback &callback) +{ + d->addCleanupCallback(key, callback); +} + +/*! + Deregisters the callback with \a key. If no cleanup callback was registered + with \a key, the function does nothing. Callbacks registered without a key + cannot be removed. + + \sa addCleanupCallback() + */ +void QRhi::removeCleanupCallback(const void *key) +{ + d->removeCleanupCallback(key); +} + +/*! Invokes all registered cleanup functions. The list of cleanup callbacks it then cleared. Normally destroying the QRhi does this automatically, but sometimes it can be useful to trigger cleanup in order to release all @@ -8249,6 +8852,11 @@ void QRhi::runCleanup() f(this); d->cleanupCallbacks.clear(); + + for (auto it = d->keyedCleanupCallbacks.cbegin(), end = d->keyedCleanupCallbacks.cend(); it != end; ++it) + it.value()(this); + + d->keyedCleanupCallbacks.clear(); } /*! @@ -8271,7 +8879,7 @@ void QRhi::runCleanup() To get an available, empty batch from the pool, call QRhi::nextResourceUpdateBatch(). - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -8412,6 +9020,8 @@ void QRhiResourceUpdateBatch::uploadStaticBuffer(QRhiBuffer *buf, quint32 offset } /*! + \overload + Enqueues updating the entire QRhiBuffer \a buf created with the type QRhiBuffer::Immutable or QRhiBuffer::Static. */ @@ -9267,9 +9877,9 @@ const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles() called when the pass recording was started with specifying QRhiCommandBuffer::ExternalContent. - With Vulkan or Metal one can query the native command buffer or encoder - objects via nativeHandles() and enqueue commands to them. With OpenGL or - Direct3D 11 the (device) context can be retrieved from + With Vulkan, Metal, or Direct3D 12 one can query the native command buffer + or encoder objects via nativeHandles() and enqueue commands to them. With + OpenGL or Direct3D 11 the (device) context can be retrieved from QRhi::nativeHandles(). However, this must never be done without ensuring the QRhiCommandBuffer's state stays up-to-date. Hence the requirement for wrapping any externally added command recording between beginExternal() and @@ -9317,8 +9927,17 @@ void QRhiCommandBuffer::endExternal() } /*! - \return the last available timestamp, in seconds. The value indicates the - elapsed time on the GPU during the last completed frame. + \return the last available timestamp, in seconds, when + \l QRhi::EnableTimestamps was enabled when creating the QRhi. The value + indicates the elapsed time on the GPU during the last completed frame. + + \note Do not expect results other than 0 when the QRhi::Timestamps feature + is not reported as supported, or when QRhi::EnableTimestamps was not passed + to QRhi::create(). There are exceptions to this, because with some graphics + APIs (Metal) timings are available without having to perform extra + operations (timestamp queries), but portable applications should always + consciously opt-in to timestamp collection when they know it is needed, and + call this function accordingly. Care must be exercised with the interpretation of the value, as its precision and granularity is often not controlled by Qt, and depends on the @@ -9326,25 +9945,47 @@ void QRhiCommandBuffer::endExternal() the values between different graphics APIs and hardware is discouraged and may be meaningless. - The timing values may become available asynchronously. The returned value - may therefore be 0 or the last known value referring to some previous - frame. The value my also become 0 again under certain conditions, such as - when resizing the window. It can be expected that the most up-to-date - available value is retrieved in beginFrame() and becomes queriable via this - function once beginFrame() returns. + When the frame was recorded with \l{QRhi::beginFrame()}{beginFrame()} and + \l{QRhi::endFrame()}{endFrame()}, i.e., with a swapchain, the timing values + will likely become available asynchronously. The returned value may + therefore be 0 (e.g., for the first 1-2 frames) or the last known value + referring to some previous frame. The value my also + become 0 again under certain conditions, such as when resizing the window. + It can be expected that the most up-to-date available value is retrieved in + beginFrame() and becomes queriable via this function once beginFrame() + returns. \note Do not assume that the value refers to the previous (\c{currently_recorded - 1}) frame. It may refer to \c{currently_recorded - 2} or \c{currently_recorded - 3} as well. The exact behavior may depend on the graphics API and its implementation. - \note The result is always 0 when the QRhi::Timestamps feature is not - reported as supported, or when QRhi::EnableTimestamps was not passed to - QRhi::create(). There are exceptions to the latter, because with some - graphics APIs timings are available without having to perform extra - operations, but portable applications should always consciously opt-in to - timestamp collection when they know it is needed, and call this function - accordingly. + On the other hand, with offscreen frames the returned value is up-to-date + once \l{QRhi::endOffscreenFrame()}{endOffscreenFrame()} returns, because + offscreen frames reduce GPU pipelining and wait the the commands to be + complete. + + \note This means that, unlike with swapchain frames, with offscreen frames + the returned value is guaranteed to refer to the frame that has just been + submitted and completed. (assuming this function is called after + endOffscreenFrame() but before the next beginOffscreenFrame()) + + Watch out for the consequences of GPU frequency scaling and GPU clock + changes, depending on the platform. For example, on Windows the returned + timing may vary in a quite wide range between frames with modern graphics + cards, even when submitting frames with a similar, or the same workload. + This is out of scope for Qt to control and solve, generally speaking. + However, the D3D12 backend automatically calls + \l{https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12device-setstablepowerstate}{ID3D12Device::SetStablePowerState()} + whenever the environment variable \c QT_D3D_STABLE_POWER_STATE is set to a + non-zero value. This can greatly stabilize the result. It can also have a + non-insignificant effect on the CPU-side timings measured via QElapsedTimer + for example, especially when offscreen frames are involved. + + \note Do not and never ship applications to production with + \c QT_D3D_STABLE_POWER_STATE set. See the Windows API documentation for details. + + \sa QRhi::Timestamps, QRhi::EnableTimestamps */ double QRhiCommandBuffer::lastCompletedGpuTime() { @@ -9693,7 +10334,7 @@ void QRhi::setPipelineCacheData(const QByteArray &data) \brief Statistics provided from the underlying memory allocator. - \note This a RHI API with limited compatibility guarantees, see \l QRhi + \note This is a RHI API with limited compatibility guarantees, see \l QRhi for details. */ @@ -10011,6 +10652,14 @@ QRhiTexture *QRhi::newTextureArray(QRhiTexture::Format format, minification filter \a minFilter, mipmapping mode \a mipmapMode, and the addressing (wrap) modes \a addressU, \a addressV, and \a addressW. + \note Setting \a mipmapMode to a value other than \c None implies that + images for all relevant mip levels will be provided either via + \l{QRhiResourceUpdateBatch::uploadTexture()}{texture uploads} or by calling + \l{QRhiResourceUpdateBatch::generateMips()}{generateMips()} on the texture + that is used with this sampler. Attempting to use the sampler with a + texture that has no data for all relevant mip levels will lead to rendering + errors, with the exact behavior dependent on the underlying graphics API. + \sa QRhiResource::destroy() */ QRhiSampler *QRhi::newSampler(QRhiSampler::Filter magFilter, |