// Copyright (C) 2023 The Qt Company Ltd.

// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only

// Qt-Security score:significant reason:default

#include "qrhi_p.h"

#include <qmath.h>

#include <QLoggingCategory>

#include "private/qloggingregistry_p.h"

#include "qrhinull_p.h"

#ifndef QT_NO_OPENGL

#include "qrhigles2_p.h"

#endif

#if QT_CONFIG(vulkan)

#include "qrhivulkan_p.h"

#endif

#ifdef Q_OS_WIN

#include "qrhid3d11_p.h"

#include "qrhid3d12_p.h"

#endif

#if QT_CONFIG(metal)

#include "qrhimetal_p.h"

#endif

#include <limits>

#include <memory>

QT_BEGIN_NAMESPACE

// Play nice with QSG_INFO since that is still the most commonly used

// way to get graphics info printed from Qt Quick apps, and the Quick

// scenegraph is our primary user.

Q_LOGGING_CATEGORY_WITH_ENV_OVERRIDE(QRHI_LOG_INFO, "QSG_INFO", "qt.rhi.general")

Q_LOGGING_CATEGORY(QRHI_LOG_RUB, "qt.rhi.rub")

/*!

    \class QRhi

    \ingroup painting-3D

    \inmodule QtGuiPrivate

    \inheaderfile rhi/qrhi.h

    \since 6.6

    \brief Accelerated 2D/3D graphics API abstraction.

    The Qt Rendering Hardware Interface is an abstraction for hardware accelerated

    graphics APIs, such as, \l{https://www.khronos.org/opengl/}{OpenGL},

    \l{https://www.khronos.org/opengles/}{OpenGL ES},

    \l{https://docs.microsoft.com/en-us/windows/desktop/direct3d}{Direct3D},

    \l{https://developer.apple.com/metal/}{Metal}, and

    \l{https://www.khronos.org/vulkan/}{Vulkan}.

    \warning The QRhi family of classes in the Qt Gui module, including QShader

    and QShaderDescription, offer limited compatibility guarantees. There are

    no source or binary compatibility guarantees for these classes, meaning the

    API is only guaranteed to work with the Qt version the application was

    developed against. Source incompatible changes are however aimed to be kept

    at a minimum and will only be made in minor releases (6.7, 6.8, and so on).

    To use these classes in an application, link to

    \c{Qt::GuiPrivate} (if using CMake), and include the headers with the \c

    rhi prefix, for example \c{#include <rhi/qrhi.h>}.

    Each QRhi instance is backed by a backend for a specific graphics API. The

    selection of the backend is a run time choice and is up to the application

    or library that creates the QRhi instance. Some backends are available on

    multiple platforms (OpenGL, Vulkan, Null), while APIs specific to a given

    platform are only available when running on the platform in question (Metal

    on macOS/iOS, Direct3D on Windows).

    The available backends currently are:

    \list

    \li OpenGL 2.1 / OpenGL ES 2.0 or newer. Some extensions and newer core

    specification features are utilized when present, for example to enable

    multisample framebuffers or compute shaders. Operating in core profile

    contexts is supported as well. If necessary, applications can query the

    \l{QRhi::Feature}{feature flags} at runtime to check for features that are

    not supported in the OpenGL context backing the QRhi. The OpenGL backend

    builds on QOpenGLContext, QOpenGLFunctions, and the related cross-platform

    infrastructure of the Qt GUI module.

    \li Direct3D 11.2 and newer (with DXGI 1.3 and newer), using Shader Model

    5.0 or newer. When the D3D runtime has no support for 11.2 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 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

    features.

    \li Null, a "dummy" backend that issues no graphics calls at all.

    \endlist

    In order to allow shader code to be written once in Qt applications and

    libraries, all shaders are expected to be written in a single language

    which is then compiled into SPIR-V. Versions for various shading language

    are then generated from that, together with reflection information (inputs,

    outputs, shader resources). This is then packed into easily and efficiently

    serializable QShader instances. The compilers and tools to generate such

    shaders are not part of QRhi and the Qt GUI module, but the core classes

    for using such shaders, QShader and QShaderDescription, are. The APIs and

    tools for performing compilation and translation are part of the Qt Shader

    Tools module.

    See the \l{RHI Window Example} for an introductory example of creating a

    portable, cross-platform application that performs accelerated 3D rendering

    onto a QWindow using QRhi.

    \section1 An Impression of the API

    To provide a quick look at the API with a short yet complete example that

    does not involve window-related setup, the following is a complete,

    runnable cross-platform application that renders 20 frames off-screen, and

    then saves the generated images to files after reading back the texture

    contents from the GPU. For an example that renders on-screen, which then

    involves setting up a QWindow and a swapchain, refer to the

    \l{RHI Window Example}.

    For brevity, the initialization of the QRhi is done based on the platform:

    the sample code here chooses Direct 3D 12 on Windows, Metal on macOS and

    iOS, and Vulkan otherwise. OpenGL and Direct 3D 11 are never used by this

    application, but support for those could be introduced with a few

    additional lines.

    \snippet rhioffscreen/main.cpp 0

    The result of the application is 20 \c PNG images (frame0.png -

    frame19.png). These contain a rotating triangle with varying opacity over a

    green background.

    The vertex and fragment shaders are expected to be processed and packaged

    into \c{.qsb} files. The Vulkan-compatible GLSL source code is the

    following:

    \e color.vert

    \snippet rhioffscreen/color.vert 0

    \e color.frag

    \snippet rhioffscreen/color.frag 0

    To manually compile and transpile these shaders to a number of targets

    (SPIR-V, HLSL, MSL, GLSL) and generate the \c{.qsb} files the application

    loads at run time, run \c{qsb --qt6 color.vert -o color.vert.qsb} and

    \c{qsb --qt6 color.frag -o color.frag.qsb}. Alternatively, the Qt Shader

    Tools module offers build system integration for CMake, the

    \c qt_add_shaders() CMake function, that can achieve the same at build time.

    \section1 Security Considerations

    All data consumed by QRhi and related classes such as QShader are considered

    trusted content.

    \warning Application developers are advised to carefully consider the

    potential implications before allowing the feeding of user-provided content

    that is not part of the application and is not under the developers'

    control. (this includes all vertex/index data, shaders, pipeline and draw

    call parameters, etc.)

    \section1 Design Fundamentals

    A QRhi cannot be instantiated directly. Instead, use the create()

    function. Delete the QRhi instance normally to release the graphics device.

    \section2 Resources

    Instances of classes deriving from QRhiResource, such as, QRhiBuffer,

    QRhiTexture, etc., encapsulate zero, one, or more native graphics

    resources. Instances of such classes are always created via the \c new

    functions of the QRhi, such as, newBuffer(), newTexture(),

    newTextureRenderTarget(), newSwapChain().

    \code

        QRhiBuffer *vbuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData));

        if (!vbuf->create()) { error(); }

        // ...

        delete vbuf;

    \endcode

    \list

    \li The returned value from functions like newBuffer() is always owned by

    the caller.

    \li Just creating an instance of a QRhiResource subclass never allocates or

    initializes any native resources. That is only done when calling the

    \c create() function of a subclass, for example, QRhiBuffer::create() or

    QRhiTexture::create().

    \li The exceptions are

    QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor(),

    QRhiSwapChain::newCompatibleRenderPassDescriptor(), and

    QRhiRenderPassDescriptor::newCompatibleRenderPassDescriptor(). There is no

    \c create() operation for these and the returned object is immediately

    active.

    \li The resource objects themselves are treated as immutable: once a

    resource has create() called, changing any parameters via the setters, such as,

    QRhiTexture::setPixelSize(), has no effect, unless the underlying native

    resource is released and \c create() is called again. See more about resource

    reuse in the sections below.

    \li The underlying native resources are scheduled for releasing by the

    QRhiResource destructor, or by calling QRhiResource::destroy(). Backends

    often queue release requests and defer executing them to an unspecified

    time, this is hidden from the applications. This way applications do not

    have to worry about releasing native resources that may still be in use by

    an in-flight frame.

    \li Note that this does not mean that a QRhiResource can freely be

    destroy()'ed or deleted within a frame (that is, in a

    \l{QRhi::beginFrame()}{beginFrame()} - \l{QRhi::endFrame()}{endFrame()}

    section). As a general rule, all referenced QRhiResource objects must stay

    unchanged until the frame is submitted by calling

    \l{QRhi::endFrame()}{endFrame()}. To ease this,

    QRhiResource::deleteLater() is provided as a convenience.

    \endlist

    \section2 Command buffers and deferred command execution

    Regardless of the design and capabilities of the underlying graphics API,

    all QRhi backends implement some level of command buffers. No

    QRhiCommandBuffer function issues any native bind or draw command (such as,

    \c glDrawElements) directly. Commands are always recorded in a queue,

    either native or provided by the QRhi backend. The command buffer is

    submitted, and so execution starts only upon QRhi::endFrame() or

    QRhi::finish().

    The deferred nature has consequences for some types of objects. For example,

    writing to a dynamic buffer multiple times within a frame, in case such

    buffers are backed by host-visible memory, will result in making the

    results of all writes are visible to all draw calls in the command buffer

    of the frame, regardless of when the dynamic buffer update was recorded

    relative to a draw call.

    Furthermore, instances of QRhiResource subclasses must be treated immutable

    within a frame in which they are referenced in any way. Create

    all resources upfront, before starting to record commands for the next

    frame. Reusing a QRhiResource instance within a frame (by calling \c create()

    then referencing it again in the same \c{beginFrame - endFrame} section)

    should be avoided as it may lead to unexpected results, depending on the

    backend.

    As a general rule, all referenced QRhiResource objects must stay valid and

    unmodified until the frame is submitted by calling

    \l{QRhi::endFrame()}{endFrame()}. On the other hand, calling

    \l{QRhiResource::destroy()}{destroy()} or deleting the QRhiResource are

    always safe once the frame is submitted, regardless of the status of the

    underlying native resources (which may still be in use by the GPU - but

    that is taken care of internally).

    Unlike APIs like OpenGL, upload and copy type of commands cannot be mixed

    with draw commands. The typical renderer will involve a sequence similar to

    the following:

    \list

    \li (re)create resources

    \li begin frame

    \li record/issue uploads and copies

    \li start recording a render pass

    \li record draw calls

    \li end render pass

    \li end frame

    \endlist

    Recording copy type of operations happens via QRhiResourceUpdateBatch. Such

    operations are committed typically on

    \l{QRhiCommandBuffer::beginPass()}{beginPass()}.

    When working with legacy rendering engines designed for OpenGL, the

    migration to QRhi often involves redesigning from having a single \c render

    step (that performs copies and uploads, clears buffers, and issues draw

    calls, all mixed together) to a clearly separated, two phase \c prepare -

    \c render setup where the \c render step only starts a renderpass and

    records draw calls, while all resource creation and queuing of updates,

    uploads and copies happens beforehand, in the \c prepare step.

    QRhi does not at the moment allow freely creating and submitting command

    buffers. This may be lifted in the future to some extent, in particular if

    compute support is introduced, but the model of well defined

    \c{frame-start} and \c{frame-end} points, combined with a dedicated,

    "frame" command buffer, where \c{frame-end} implies presenting, is going to

    remain the primary way of operating since this is what fits Qt's various UI

    technologies best.

    \section2 Threading

    A QRhi instance and the associated resources can be created and used on any

    thread but all usage must be limited to that one single thread. When

    rendering to multiple QWindows in an application, having a dedicated thread

    and QRhi instance for each window is often advisable, as this can eliminate

    issues with unexpected throttling caused by presenting to multiple windows.

    Conceptually that is then the same as how Qt Quick scene graph's threaded

    render loop operates when working directly with OpenGL: one thread for each

    window, one QOpenGLContext for each thread. When moving onto QRhi,

    QOpenGLContext is replaced by QRhi, making the migration straightforward.

    When it comes to externally created native objects, such as OpenGL contexts

    passed in via QRhiGles2NativeHandles, it is up to the application to ensure

    they are not misused by other threads.

    Resources are not shareable between QRhi instances. This is an intentional

    choice since QRhi hides most queue, command buffer, and resource

    synchronization related tasks, and provides no API for them. Safe and

    efficient concurrent use of graphics resources from multiple threads is

    tied to those concepts, however, and is thus a topic that is currently out

    of scope, but may be introduced in the future.

    \note The Metal backend requires that an autorelease pool is available on

    the rendering thread, ideally wrapping each iteration of the render loop.

    This needs no action from the users of QRhi when rendering on the main

    (gui) thread, but becomes important when a separate, dedicated render

    thread is used.

    \section2 Resource synchronization

    QRhi does not expose APIs for resource barriers or image layout

    transitions. Such synchronization is done implicitly by the backends, where

    applicable (for example, Vulkan), by tracking resource usage as necessary.

    Buffer and image barriers are inserted before render or compute passes

    transparently to the application.

    \note Resources within a render or compute pass are expected to be bound to

    a single usage during that pass. For example, a buffer can be used as

    vertex, index, uniform, or storage buffer, but not a combination of them

    within a single pass. However, it is perfectly fine to use a buffer as a

    storage buffer in a compute pass, and then as a vertex buffer in a render

    pass, for example, assuming the buffer declared both usages upon creation.

    \note Textures have this rule relaxed in certain cases, because using two

    subresources (typically two different mip levels) of the same texture for

    different access (one for load, one for store) is supported even within the

    same pass.

    \section2 Resource reuse

    From the user's point of view a QRhiResource is reusable immediately after

    calling QRhiResource::destroy(). With the exception of swapchains, calling

    \c create() on an already created object does an implicit \c destroy(). This

    provides a handy shortcut to reuse a QRhiResource instance with different

    parameters, with a new native graphics object underneath.

    The importance of reusing the same object lies in the fact that some

    objects reference other objects: for example, a QRhiShaderResourceBindings

    can reference QRhiBuffer, QRhiTexture, and QRhiSampler instances. If in a

    later frame one of these buffers need to be resized or a sampler parameter

    needs changing, destroying and creating a whole new QRhiBuffer or

    QRhiSampler would invalidate all references to the old instance. By just

    changing the appropriate parameters via QRhiBuffer::setSize() or similar

    and then calling QRhiBuffer::create(), everything works as expected and

    there is no need to touch the QRhiShaderResourceBindings at all, even

    though there is a good chance that under the hood the QRhiBuffer is now

    backed by a whole new native buffer.

    \code

        QRhiBuffer *ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 256);

        ubuf->create();

        QRhiShaderResourceBindings *srb = rhi->newShaderResourceBindings()

        srb->setBindings({

            QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage, ubuf)

        });

        srb->create();

        // ...

        // now in a later frame we need to grow the buffer to a larger size

        ubuf->setSize(512);

        ubuf->create(); // same as ubuf->destroy(); ubuf->create();

        // srb needs no changes whatsoever, any references in it to ubuf

        // stay valid. When it comes to internal details, such as that

        // ubuf may now be backed by a completely different native buffer

        // resource, that is is recognized and handled automatically by the

        // next setShaderResources().

    \endcode

    QRhiTextureRenderTarget offers the same contract: calling

    QRhiCommandBuffer::beginPass() is safe even when one of the render target's

    associated textures or renderbuffers has been rebuilt (by calling \c

    create() on it) since the creation of the render target object. This allows

    the application to resize a texture by setting a new pixel size on the

    QRhiTexture and calling create(), thus creating a whole new native texture

    resource underneath, without having to update the QRhiTextureRenderTarget

    as that will be done implicitly in beginPass().

    \section2 Pooled objects

    In addition to resources, there are pooled objects as well, such as,

    QRhiResourceUpdateBatch. An instance is retrieved via a \c next function,

    such as, nextResourceUpdateBatch(). The caller does not own the returned

    instance in this case. The only valid way of operating here is calling

    functions on the QRhiResourceUpdateBatch and then passing it to

    QRhiCommandBuffer::beginPass() or QRhiCommandBuffer::endPass(). These

    functions take care of returning the batch to the pool. Alternatively, a

    batch can be "canceled" and returned to the pool without processing by

    calling QRhiResourceUpdateBatch::release().

    A typical pattern is thus:

    \code

        QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();

        // ...

        resUpdates->updateDynamicBuffer(ubuf, 0, 64, mvp.constData());

        if (!image.isNull()) {

            resUpdates->uploadTexture(texture, image);

            image = QImage();

        }

        // ...

        QRhiCommandBuffer *cb = m_sc->currentFrameCommandBuffer();

        // note the last argument

        cb->beginPass(swapchain->currentFrameRenderTarget(), clearCol, clearDs, resUpdates);

    \endcode

    \section2 Swapchain specifics

    QRhiSwapChain features some special semantics due to the peculiar nature of

    swapchains.

    \list

    \li It has no \c create() but rather a QRhiSwapChain::createOrResize().

    Repeatedly calling this function is \b not the same as calling

    QRhiSwapChain::destroy() followed by QRhiSwapChain::createOrResize(). This

    is because swapchains often have ways to handle the case where buffers need

    to be resized in a manner that is more efficient than a brute force

    destroying and recreating from scratch.

    \li An active QRhiSwapChain must be released by calling

    \l{QRhiSwapChain::destroy()}{destroy()}, or by destroying the object, before

    the QWindow's underlying QPlatformWindow, and so the associated native

    window object, is destroyed. It should not be postponed because releasing

    the swapchain may become problematic (and with some APIs, like Vulkan, is

    explicitly disallowed) when the native window is not around anymore, for

    example because the QPlatformWindow got destroyed upon getting a

    QWindow::close(). Therefore, releasing the swapchain must happen whenever

    the targeted QWindow sends the

    QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed event. If the event does

    not arrive before the destruction of the QWindow - this can happen when

    using QCoreApplication::quit() -, then check QWindow::handle() after the

    event loop exits and invoke the swapchain release when non-null (meaning

    the underlying native window is still around).

    \endlist

    \section2 Ownership

    The general rule is no ownership transfer. Creating a QRhi with an already

    existing graphics device does not mean the QRhi takes ownership of the

    device object. Similarly, ownership is not given away when a device or

    texture object is "exported" via QRhi::nativeHandles() or

    QRhiTexture::nativeTexture(). Most importantly, passing pointers in structs

    and via setters does not transfer ownership.

    \section1 Troubleshooting and Profiling

    \section2 Error reporting

    Functions such as \l QRhi::create() and the resource classes' \c create()

    member functions (e.g., \l QRhiBuffer::create()) indicate failure with the

    return value (\nullptr or

    \c false, respectively). When working with QShader, \l QShader::fromSerialized()

    returns an invalid QShader (for which \l{QShader::isValid()}{isValid()} returns

    \c false) when the data passed to the function cannot be successfully deserialized.

    Some functions, beginFrame() in particular, may also sometimes report "soft failures",

    such as \l FrameOpSwapChainOutOfDate, which do not indicate an unrecoverable error,

    but rather should be seen as a "try again later" response.

    Warnings and errors may get printed at any time to the debug output via

    qWarning(). It is therefore always advisable to inspect the output of the

    application.

    Additional debug messages can be enabled via the following logging

    categories. Messages from these categories are not printed by default

    unless explicitly enabled via QLoggingCategory or the \c QT_LOGGING_RULES

    environment variable. For better interoperation with Qt Quick, the

    environment variable \c{QSG_INFO} also enables these debug prints.

    \list

    \li \c{qt.rhi.general}

    \endlist

    Additionally, applications can query the \l{QRhi::backendName()}{QRhi

    backend name} and

    \l{QRhi::driverInfo()}{graphics device information} from a successfully

    initialized QRhi. This can then be printed to the user or stored in the

    application logs even in production builds, if desired.

    \section2 Investigating rendering problems

    When the rendering results are not as expected, or the application is

    experiencing problems, always consider checking with the native 3D

    APIs' debug and validation facilities. QRhi itself features limited error

    checking since replicating the already existing, vast amount of

    functionality in the underlying layers is not reasonable.

    \list

    \li For Vulkan, controlling the

    \l{https://github.com/KhronosGroup/Vulkan-ValidationLayers}{Vulkan

    Validation Layers} is not in the scope of the QRhi, but rather can be

    achieved by configuring the \l QVulkanInstance with the appropriate layers.

    For example, call \c{instance.setLayers({ "VK_LAYER_KHRONOS_validation" });}

    before invoking \l{QVulkanInstance::create()}{create()} on the QVulkanInstance.

    (note that this assumes that the validation layers are actually installed

    and available, e.g. from the Vulkan SDK) By default, QVulkanInstance conveniently

    redirects the Vulkan debug messages to qDebug, meaning the validation messages get

    printed just like other Qt warnings.

    \li With Direct 3D 11 and 12, a graphics device with the debug layer

    enabled can be requested by toggling the \c enableDebugLayer flag in the

    appropriate \l{QRhiD3D11InitParams}{init params struct}. The messages appear on the

    debug output, which is visible in Qt Creator's messages panel or via a tool

    such as \l{https://learn.microsoft.com/en-us/sysinternals/downloads/debugview}{DebugView}.

    \li For Metal, controlling Metal Validation is outside of QRhi's scope.

    Rather, to enable validation, run the application with the environment

    variable \c{METAL_DEVICE_WRAPPER_TYPE=1} set, or run the application within

    XCode. There may also be further settings and environment variable in modern

    XCode and macOS versions. See for instance

    \l{https://developer.apple.com/documentation/metal/diagnosing_metal_programming_issues_early}{this

    page}.

    \endlist

    \section2 Frame captures and performance profiling

    A Qt application rendering with QRhi to a window while relying on a 3D API

    under the hood, is, from the windowing and graphics pipeline perspective at

    least, no different from any other (non-Qt) applications using the same 3D

    API. This means that tools and practices for debugging and profiling

    applications involving 3D graphics, such as games, all apply to such a Qt

    application as well.

    A few examples of tools that can provide insights into the rendering

    internals of Qt applications that use QRhi, which includes Qt Quick and Qt

    Quick 3D based projects as well:

    \list

    \li \l{https://renderdoc.org/}{RenderDoc} allows taking frame captures and

    introspecting the recorded commands and pipeline state on Windows and Linux

    for applications using OpenGL, Vulkan, D3D11, or D3D12. When trying to

    figure out why some parts of the 3D scene do not show up as expected,

    RenderDoc is often a fast and efficient way to check the pipeline stages

    and the related state and discover the missing or incorrect value. It is

    also a tool that is actively used when developing Qt itself.

    \li For NVIDIA-based systems,

    \l{https://developer.nvidia.com/nsight-graphics}{Nsight Graphics} provides

    a graphics debugger tool on Windows and Linux. In addition to investigating the commands

    in the frame and the pipeline, the vendor-specific tools allow looking at timings and

    hardware performance information, which is not something simple frame captures can provide.

    \li For AMD-based systems, the \l{https://gpuopen.com/rgp/}{Radeon GPU

    Profiler} can be used to gain deeper insights into the application's

    rendering and its performance.

    \li Overlays showing live performance information can be highly useful as well, and

    are often preferable to implementing simple frames-per-second counters within the

    application itself, since they are more reliable and show more information. An example

    is \l{https://game.intel.com/us/intel-presentmon/}{PresentMon}, which supports

    graphics hardware from multiple vendors.

    \li As QRhi supports Direct 3D 12, using

    \l{https://devblogs.microsoft.com/pix/download/}{PIX}, a performance tuning

    and debugging tool for DirectX 12 games on Windows is an option as well.

    \li On macOS,

    \l{https://developer.apple.com/documentation/metal/debugging_tools/viewing_your_gpu_workload_with_the_metal_debugger}{the

    XCode Metal debugger} can be used to take and introspect frame

    captures, to investigate performance details, and debug shaders. In macOS 13 it is also possible

    to enable an overlay that displays frame rate and other information for any Metal-based window by

    setting the environment variable \c{MTL_HUD_ENABLED=1}.

    \endlist

    On mobile and embedded platforms, there may be vendor and platform-specific

    tools, provided by the GPU or SoC vendor, available to perform performance

    profiling of application using OpenGL ES or Vulkan.

    When capturing frames, remember that objects and groups of commands can be

    named via debug markers, as long as \l{QRhi::EnableDebugMarkers}{debug

    markers were enabled} for the QRhi, and the graphics API in use supports

    this. To annotate the command stream, call

    \l{QRhiCommandBuffer::debugMarkBegin()}{debugMarkBegin()},

    \l{QRhiCommandBuffer::debugMarkEnd()}{debugMarkEnd()} and/or

    \l{QRhiCommandBuffer::debugMarkMsg()}{debugMarkMsg()}.

    This can be particularly useful in larger frames with multiple render passes.

    Resources are named by calling \l{QRhiResource::setName()}{setName()} before create().

    To perform basic timing measurements on the CPU and GPU side within the

    application, \l QElapsedTimer and

    \l QRhiCommandBuffer::lastCompletedGpuTime() can be used. The latter is

    only available with select graphics APIs at the moment and requires opting

    in via the \l QRhi::EnableTimestamps flag.

    \section2 Resource leak checking

    When destroying a QRhi object without properly destroying all buffers,

    textures, and other resources created from it, warnings about this are

    printed to the debug output whenever the application is a debug build, or

    when the \c QT_RHI_LEAK_CHECK environment variable is set to a non-zero

    value. This is a simple way to discover design issues around resource

    handling within the application rendering logic. Note however that some

    platforms and underlying graphics APIs may perform their own allocation and

    resource leak detection as well, over which Qt will have no direct control.

    For example, when using Vulkan, the memory allocator may raise failing

    assertions in debug builds when resources that own graphics memory

    allocations are not destroyed before the QRhi. In addition, the Vulkan

    validation layer, when enabled, will issue warnings about native graphics

    resources that were not released. Similarly, with Direct 3D warnings may

    get printed about unreleased COM objects when the application does not

    destroy the QRhi and its resources in the correct order.

    \sa {RHI Window Example}, QRhiCommandBuffer, QRhiResourceUpdateBatch,

    QRhiShaderResourceBindings, QShader, QRhiBuffer, QRhiTexture,

    QRhiRenderBuffer, QRhiSampler, QRhiTextureRenderTarget,

    QRhiGraphicsPipeline, QRhiComputePipeline, QRhiSwapChain

 */

/*!

    \enum QRhi::Implementation

    Describes which graphics API-specific backend gets used by a QRhi instance.

    \value Null

    \value Vulkan

    \value OpenGLES2

    \value D3D11

    \value D3D12

    \value Metal

 */

/*!

    \enum QRhi::Flag

    Describes what special features to enable.

    \value EnableDebugMarkers Enables debug marker groups. Without this frame

    debugging features like making debug groups and custom resource name

    visible in external GPU debugging tools will not be available and functions

    like QRhiCommandBuffer::debugMarkBegin() will become no-ops. Avoid enabling

    in production builds as it may involve a small performance impact. Has no

    effect when the QRhi::DebugMarkers feature is not reported as supported.

    \value EnableTimestamps Enables GPU timestamp collection. When not set,

    QRhiCommandBuffer::lastCompletedGpuTime() always returns 0. Enable this

    only when needed since there may be a small amount of extra work involved

    (e.g. timestamp queries), depending on the underlying graphics API. Has no

    effect when the QRhi::Timestamps feature is not reported as supported.

    \value PreferSoftwareRenderer Indicates that backends should prefer

    choosing an adapter or physical device that renders in software on the CPU.

    For example, with Direct3D there is typically a "Basic Render Driver"

    adapter available with \c{DXGI_ADAPTER_FLAG_SOFTWARE}. Setting this flag

    requests the backend to choose that adapter over any other, as long as no

    specific adapter was forced by other backend-specific means. With Vulkan

    this maps to preferring physical devices with

    \c{VK_PHYSICAL_DEVICE_TYPE_CPU}. When not available, or when it is not

    possible to decide if an adapter/device is software-based, this flag is

    ignored. It may also be ignored with graphics APIs that have no concept and

    means of enumerating adapters/devices.

    \value EnablePipelineCacheDataSave Enables retrieving the pipeline cache

    contents, where applicable. When not set, pipelineCacheData() will return

    an empty blob always. With backends where retrieving and restoring the

    pipeline cache contents is not supported, the flag has no effect and the

    serialized cache data is always empty. The flag provides an opt-in

    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 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

    that come with HLSL source instead of offline pre-compiled bytecode. This

    can provide a huge boost in startup and load times, if there is a lot of

    HLSL source compilation happening. With OpenGL the "pipeline cache" is

    simulated by retrieving and loading shader program binaries (if supported

    by the driver). With OpenGL there are additional, disk-based caching

    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.

 */

/*!

    \enum QRhi::FrameOpResult

    Describes the result of operations that can have a soft failure.

    \value FrameOpSuccess Success

    \value FrameOpError Unspecified error

    \value FrameOpSwapChainOutOfDate The swapchain is in an inconsistent state

    internally. This can be recoverable by attempting to repeat the operation

    (such as, beginFrame()) later.

    \value FrameOpDeviceLost The graphics device was lost. This can be

    recoverable by attempting to repeat the operation (such as, beginFrame())

    after releasing and reinitializing all objects backed by native graphics

    resources. See isDeviceLost().

 */

/*!

    \enum QRhi::Feature

    Flag values to indicate what features are supported by the backend currently in use.

    \value MultisampleTexture Indicates that textures with a sample count larger

    than 1 are supported. In practice this feature will be unsupported with

    OpenGL ES versions older than 3.1, and OpenGL older than 3.0.

    \value MultisampleRenderBuffer Indicates that renderbuffers with a sample

    count larger than 1 are supported. In practice this feature will be

    unsupported with OpenGL ES 2.0, and may also be unsupported with OpenGL 2.x

    unless the relevant extensions are present.

    \value DebugMarkers Indicates that debug marker groups (and so

    QRhiCommandBuffer::debugMarkBegin()) are supported.

    \value Timestamps Indicates that command buffer timestamps are supported.

    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

    3.2 or older.

    \value CustomInstanceStepRate Indicates that instance step rates other

    than 1 are supported. In practice this feature will always be unsupported

    with OpenGL. In addition, running with Vulkan 1.0 without

    VK_EXT_vertex_attribute_divisor will also lead to reporting false for this

    feature.

    \value PrimitiveRestart Indicates that restarting the assembly of

    primitives when encountering an index value of 0xFFFF

    (\l{QRhiCommandBuffer::IndexUInt16}{IndexUInt16}) or 0xFFFFFFFF

    (\l{QRhiCommandBuffer::IndexUInt32}{IndexUInt32}) is enabled, for certain

    primitive topologies at least. QRhi will try to enable this with all

    backends, but in some cases it will not be supported. Dynamically

    controlling primitive restart is not possible since with some APIs

    primitive restart with a fixed index is always on. Applications must assume

    that whenever this feature is reported as supported, the above mentioned

    index values \c may be treated specially, depending on the topology. The

    only two topologies where primitive restart is guaranteed to behave

    identically across backends, as long as this feature is reported as

    supported, are \l{QRhiGraphicsPipeline::LineStrip}{LineStrip} and

    \l{QRhiGraphicsPipeline::TriangleStrip}{TriangleStrip}.

    \value NonDynamicUniformBuffers Indicates that creating buffers with the

    usage \l{QRhiBuffer::UniformBuffer}{UniformBuffer} and the types

    \l{QRhiBuffer::Immutable}{Immutable} or \l{QRhiBuffer::Static}{Static} is

    supported. When reported as unsupported, uniform (constant) buffers must be

    created as \l{QRhiBuffer::Dynamic}{Dynamic}. (which is recommended

    regardless)

    \value NonFourAlignedEffectiveIndexBufferOffset Indicates that effective

    index buffer offsets (\c{indexOffset + firstIndex * indexComponentSize})

    that are not 4 byte aligned are supported. When not supported, attempting

    to issue a \l{QRhiCommandBuffer::drawIndexed()}{drawIndexed()} with a

    non-aligned effective offset may lead to unspecified behavior. Relevant in

    particular for Metal, where this will be reported as unsupported.

    \value NPOTTextureRepeat Indicates that the

    \l{QRhiSampler::Repeat}{Repeat} wrap mode and mipmap filtering modes are

    supported for textures with a non-power-of-two size. In practice this can

    only be false with OpenGL ES 2.0 implementations without

    \c{GL_OES_texture_npot}.

    \value RedOrAlpha8IsRed Indicates that the

    \l{QRhiTexture::RED_OR_ALPHA8}{RED_OR_ALPHA8} format maps to a one

    component 8-bit \c red format. This is the case for all backends except

    OpenGL when using either OpenGL ES or a non-core profile context. There

    \c{GL_ALPHA}, a one component 8-bit \c alpha format, is used

    instead. Using the special texture format allows having a single code

    path for creating textures, leaving it up to the backend to decide the

    actual format, while the feature flag can be used to pick the

    appropriate shader variant for sampling the texture.

    \value ElementIndexUint Indicates that 32-bit unsigned integer elements are

    supported in the index buffer. In practice this is true everywhere except

    when running on plain OpenGL ES 2.0 implementations without the necessary

    extension. When false, only 16-bit unsigned elements are supported in the

    index buffer.

    \value Compute Indicates that compute shaders, image load/store, and

    storage buffers are supported. OpenGL older than 4.3 and OpenGL ES older

    than 3.1 have no compute support.

    \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, D3D12, Metal). With Vulkan, the value depends on the

    implementation. With OpenGL, wide lines are not supported in core profile

    contexts.

    \value VertexShaderPointSize Indicates that the size of rasterized points

    set via \c{gl_PointSize} in the vertex shader is taken into account. When

    reported as not supported, drawing points with a size other than 1 is not

    supported. Setting \c{gl_PointSize} in the shader is still valid then, but

    is ignored. (for example, when generating HLSL, the assignment is silently

    dropped from the generated code) Note that some APIs (Metal, Vulkan)

    require the point size to be set in the shader explicitly whenever drawing

    points, even when the size is 1, as they do not automatically default to 1.

    \value BaseVertex Indicates that

    \l{QRhiCommandBuffer::drawIndexed()}{drawIndexed()} supports the \c

    vertexOffset argument. When reported as not supported, the vertexOffset

    value in an indexed draw is ignored. In practice this feature will be

    unsupported with OpenGL and OpenGL ES versions lower than 3.2, and with

    Metal on older iOS devices, including the iOS Simulator.

    \value BaseInstance Indicates that instanced draw commands support the \c

    firstInstance argument. When reported as not supported, the firstInstance

    value is ignored and the instance ID starts from 0. In practice this feature

    will be unsupported with Metal on older iOS devices, including the iOS

    Simulator, and all versions of OpenGL. The latter is due to OpenGL ES not

    supporting draw calls with a base instance at all. Currently QRhi's OpenGL

    backend does not implement the functionality for OpenGL (non-ES) either,

    because portable applications cannot rely on a non-zero base instance in

    practice due to GLES. If the application still chooses to do so, it should

    be aware of the InstanceIndexIncludesBaseInstance feature as well.

    \value TriangleFanTopology Indicates that QRhiGraphicsPipeline::setTopology()

    supports QRhiGraphicsPipeline::TriangleFan. In practice this feature will be

    unsupported with Metal and Direct 3D 11/12.

    \value ReadBackNonUniformBuffer Indicates that

    \l{QRhiResourceUpdateBatch::readBackBuffer()}{reading buffer contents} is

    supported for QRhiBuffer instances with a usage different than

    UniformBuffer. In practice this feature will be unsupported with OpenGL ES

    2.0.

    \value ReadBackNonBaseMipLevel Indicates that specifying a mip level other

    than 0 is supported when reading back texture contents. When not supported,

    specifying a non-zero level in QRhiReadbackDescription leads to returning

    an all-zero image. In practice this feature will be unsupported with OpenGL

    ES 2.0.

    \value TexelFetch Indicates that texelFetch() and textureLod() are available

    in shaders. In practice this will be reported as unsupported with OpenGL ES

    2.0 and OpenGL 2.x contexts, because GLSL 100 es and versions before 130 do

    not support these functions.

    \value RenderToNonBaseMipLevel Indicates that specifying a mip level other

    than 0 is supported when creating a QRhiTextureRenderTarget with a

    QRhiTexture as its color attachment. When not supported, create() will fail

    whenever the target mip level is not zero. In practice this feature will be

    unsupported with OpenGL ES 2.0.

    \value IntAttributes Indicates that specifying input attributes with

    signed and unsigned integer types for a shader pipeline is supported. When

    not supported,

    \l{QRhiGraphicsPipeline::create()}{QRhiGraphicsPipeline::create()} will

    succeed but show a warning message and the values of the target attributes

    will be broken. In practice this feature will be unsupported with OpenGL ES

    2.0 and OpenGL 2.x.

    \value ScreenSpaceDerivatives Indicates that functions such as dFdx(),

    dFdy(), and fwidth() are supported in shaders. In practice this feature will

    be unsupported with OpenGL ES 2.0 without the GL_OES_standard_derivatives

    extension.

    \value ReadBackAnyTextureFormat Indicates that reading back texture

    contents can be expected to work for any QRhiTexture::Format. Backends

    other than OpenGL can be expected to return true for this feature. When

    reported as false, which will typically happen with OpenGL, only the

    formats QRhiTexture::RGBA8 and QRhiTexture::BGRA8 are guaranteed to be

    supported for readbacks. In addition, with OpenGL, but not OpenGL ES,

    reading back the 1 byte per component formats QRhiTexture::R8 and

    QRhiTexture::RED_OR_ALPHA8 are supported as well. Reading back floating

    point formats QRhiTexture::RGBA16F and RGBA32F may work too with OpenGL, as

    long as the implementation provides support for these, but QRhi can give no

    guarantees, as indicated by this flag.

    \value PipelineCacheDataLoadSave Indicates that the pipelineCacheData() and

    setPipelineCacheData() functions are functional. When not supported, the

    functions will not perform any action, the retrieved blob is always empty,

    and thus no benefits can be expected from retrieving and, during a

    subsequent run of the application, reloading the pipeline cache content.

    \value ImageDataStride Indicates that specifying a custom stride (row

    length) for raw image data in texture uploads is supported. When not

    supported (which can happen when the underlying API is OpenGL ES 2.0 without

    support for GL_UNPACK_ROW_LENGTH),

    QRhiTextureSubresourceUploadDescription::setDataStride() must not be used.

    \value RenderBufferImport Indicates that QRhiRenderBuffer::createFrom() is

    supported. For most graphics APIs this is not sensible because

    QRhiRenderBuffer encapsulates texture objects internally, just like

    QRhiTexture. With OpenGL however, renderbuffer object exist as a separate

    object type in the API, and in certain environments (for example, where one

    may want to associated a renderbuffer object with an EGLImage object) it is

    important to allow wrapping an existing OpenGL renderbuffer object with a

    QRhiRenderBuffer.

    \value ThreeDimensionalTextures Indicates that 3D textures are supported.

    In practice this feature will be unsupported with OpenGL and OpenGL ES

    versions lower than 3.0.

    \value RenderTo3DTextureSlice Indicates that rendering to a slice in a 3D

    texture is supported. This can be unsupported with Vulkan 1.0 due to

    relying on VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT which is a Vulkan 1.1

    feature.

    \value TextureArrays Indicates that texture arrays are supported and

    QRhi::newTextureArray() is functional. Note that even when texture arrays

    are not supported, arrays of textures are still available as those are two

    independent features.

    \value Tessellation Indicates that the tessellation control and evaluation

    stages are supported. When reported as supported, the topology of a

    QRhiGraphicsPipeline can be set to

    \l{QRhiGraphicsPipeline::Patches}{Patches}, the number of control points

    can be set via

    \l{QRhiGraphicsPipeline::setPatchControlPointCount()}{setPatchControlPointCount()},

    and shaders for tessellation control and evaluation can be specified in the

    QRhiShaderStage list. Tessellation shaders have portability issues between

    APIs (for example, translating GLSL/SPIR-V to HLSL is problematic due to

    the way hull shaders are structured, whereas Metal uses a somewhat

    different tessellation pipeline than others), and therefore unexpected

    issues may still arise, even though basic functionality is implemented

    across all the underlying APIs. For Direct 3D in particular, handwritten

    HLSL hull and domain shaders must be injected into each QShader for the

    tessellation control and evaluation stages, respectively, since qsb cannot

    generate these from SPIR-V. Note that isoline tessellation should be

    avoided as it will not be supported by all backends. The maximum patch

    control point count portable between backends is 32.

    \value GeometryShader Indicates that the geometry shader stage is supported.

    When supported, a geometry shader can be specified in the QRhiShaderStage

    list. Geometry Shaders are considered an experimental feature in QRhi and

    can only be expected to be supported with Vulkan, Direct 3D 11 and 12,

    OpenGL (3.2+) and OpenGL ES (3.2+), assuming the implementation reports it

    as supported at run time. Starting with Qt 6.11 geometry shaders are

    automatically translated to HLSL, and therefore no injection of handwritten

    HLSL geometry shaders is necessary anymore (but note that gl_in and

    expressions such as gl_in[0].gl_Position are not supported; rather, pass the

    position as an output variable from the vertex shader). Geometry shaders are

    not supported with Metal.

    \value TextureArrayRange Indicates that for

    \l{QRhi::newTextureArray()}{texture arrays} it is possible to specify a

    range that is exposed to the shaders. Normally all array layers are exposed

    and it is up to the shader to select the layer (via the third coordinate

    passed to texture() when sampling the \c sampler2DArray). When supported,

    calling QRhiTexture::setArrayRangeStart() and

    QRhiTexture::setArrayRangeLength() before

    \l{QRhiTexture::create()}{building} or

    \l{QRhiTexture::createFrom()}{importing} the native texture has an effect,

    and leads to selecting only the specified range from the array. This will

    be necessary in special cases, such as when working with accelerated video

    decoding and Direct 3D 11, because a texture array with both

    \c{D3D11_BIND_DECODER} and \c{D3D11_BIND_SHADER_RESOURCE} on it is only

    usable as a shader resource if a single array layer is selected. Note that

    all this is applicable only when the texture is used as a

    QRhiShaderResourceBinding::SampledTexture or

    QRhiShaderResourceBinding::Texture shader resource, and is not compatible

    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/12 and Vulkan.

    \value NonFillPolygonMode Indicates that setting a PolygonMode other than

    the default Fill is supported for QRhiGraphicsPipeline. A common use case

    for changing the mode to Line is to get wireframe rendering. This however

    is not available as a core OpenGL ES feature, and is optional with Vulkan

    as well as some mobile GPUs may not offer the feature.

    \value OneDimensionalTextures Indicates that 1D textures are supported.

    In practice this feature will be unsupported on OpenGL ES.

    \value OneDimensionalTextureMipmaps Indicates that generating 1D texture

    mipmaps is supported. In practice this feature will be unsupported on

    backends that do not report support for

    \l{OneDimensionalTextures}, Metal, and Direct 3D 12.

    \value HalfAttributes Indicates that specifying input attributes with half

    precision (16bit) floating point types for a shader pipeline is supported.

    When not supported,

    \l{QRhiGraphicsPipeline::create()}{QRhiGraphicsPipeline::create()} will

    succeed but 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 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.

    \value RenderToOneDimensionalTexture Indicates that 1D texture render

    targets are supported. In practice this feature will be unsupported on

    backends that do not report support for

    \l{OneDimensionalTextures}, and Metal.

    \value ThreeDimensionalTextureMipmaps Indicates that generating 3D texture

    mipmaps is supported. This is typically supported with all backends starting

    with Qt 6.10.

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

    \value VariableRateShading Indicates that per-draw (per-pipeline) variable

    rate shading is supported. When reported as supported, \l

    QRhiCommandBuffer::setShadingRate() is functional and has an effect for

    QRhiGraphicsPipeline objects that declared \l

    QRhiGraphicsPipeline::UsesShadingRate in their flags. Call \l

    QRhi::supportedShadingRates() to check which rates are supported. (1x1 is

    always supported, other typical values are 2x2, 1x2, 2x1, 2x4, 4x2, 4x4).

    This feature can be expected to be supported with Direct 3D 12 and Vulkan,

    assuming the implementation and GPU used at run time supports VRS. This enum

    value has been introduced in Qt 6.9.

    \value VariableRateShadingMap Indicates that image-based specification of

    the shading rate is possible. The "image" is not necessarily a texture, it

    may be a native 3D API object, depending on the underlying backend and

    graphics API at run time. In practice this feature can be expected to be

    supported with Direct 3D 12, Vulkan, and Metal, assuming the GPU is modern

    enough to support VRS. To check if D3D12/Vulkan-style image-based VRS is

    supported, use VariableRateShadingMapWithTexture instead. When this feature

    is reported as supported, there are two possibilities: when

    VariableRateShadingMapWithTexture is also true, then QRhiShadingRateMap

    consumes QRhiTexture objects via the createFrom() overload taking a

    QRhiTexture argument. When VariableRateShadingMapWithTexture is false, then

    QRhiShadingRateMap consumes some other type of native objects, for example

    an MTLRasterizationRateMap in case of Metal. Use the createFrom() overload

    taking a NativeShadingRateMap in this case. This enum value has been

    introduced in Qt 6.9.

    \value VariableRateShadingMapWithTexture Indicates that image-based

    specification of the shading rate is supported via regular textures. In

    practice this may be supported with Direct 3D 12 and Vulkan. This enum value

    has been introduced in Qt 6.9.

    \value PerRenderTargetBlending Indicates that per rendertarget blending is

    supported i.e. different render targets in MRT framebuffer can have different

    blending modes. In practice this can be expected to be supported everywhere

    except OpenGL ES, where it is only available with GLES 3.2 implementations.

    This enum value has been introduced in Qt 6.9.

    \value SampleVariables Indicates that gl_SampleID, gl_SamplePosition,

    gl_SampleMaskIn and gl_SampleMask variables are available in fragment shaders.

    In practice this can be expected to be supported everywhere except OpenGL ES,

    where it is only available with GLES 3.2 implementations.

    This enum value has been introduced in Qt 6.9.

    \value InstanceIndexIncludesBaseInstance Indicates that \c gl_InstanceIndex

    includes the base instance (the \c firstInstance argument in draw calls) in

    its value. When this feature is unsupported, but BaseInstance is, it

    indicates that \c gl_InstanceIndex always starts at 0, not the base value.

    In practice this will be the case for Direct 3D 11 and 12 at the moment.

    With Vulkan and Metal this feature is expected to be reported as supported

    always. This enum value has been introduced in Qt 6.11.

    \value [since 6.11] DepthClamp Indicates that enabling depth clamping is

    supported. When reported as unsupported, which will be the case with OpenGL

    ES, OpenGL versions before 3.2 without the relevant extension present, and

    Metal on the iOS Simulator, calling \l{QRhiGraphicsPipeline::setDepthClamp()}

    with an argument of \c true has no effect.

    \value [since 6.12] DrawIndirect Indicates that the

    \l{QRhiCommandBuffer::drawIndirect()}{drawIndirect()}

    and \l{QRhiCommandBuffer::drawIndexedIndirect()}{drawIndexedIndirect()}

    functions are available.

    In practice this can be expected to be supported everywhere except on

    OpenGL ES < 3.1.

    \value [since 6.12] DrawIndirectMulti Indicates that a drawCount > 1 is natively