rhi: Make it a QPA-style private but semi-public API

qrhi.h, qshader.h, qshaderdescription.h (and qshaderbaker.h from
shadertools; done separately) become "RHI APIs", following the concept
of QPA APIs.

Mirror completely what is done for QPA headers, but using the "rhi"
prefix for the headers. This involves updating syncqt to handle the
new category of headers. (a note on the regex: matching everything
starting with "qrhi" is not acceptable due to incorrectly matching
existing and future headers, hence specifying the four header names
explicitly)

There is going to be one difference to QPA: the documentation for
everything RHI is going to be public and part of the regular docs, not
hidden with \internal.

In addition to the header renaming and adding the comments and
documentation notes and warnings, there is one significant change
here: there is no longer a need to do API-specific includes, such as
qrhid3d11[_p].h, qrhivulkan[_p].h, etc. These are simply merged into a
single header that is then included from qrhi.h. This means that users
within Qt, and any future applications can just do #include
<rhi/qrhi.h> (or rhi/qshader.h if the QRhi stuff is not relevant), no
other headers are needed.

There are no changes to functionality in this patch. Only the
documentation is expanded, quite a lot, to eliminate all qdoc warnings
and make the generated API docs complete. An example, with a quite
extensive doc page is added as well.

Task-number: QTBUG-113331
Change-Id: I91c749826348f14320cb335b1c83e9d1ea2b1d8b
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>

97 files changed, 13336 insertions, 8928 deletions

diff --git a/cmake/QtFrameworkHelpers.cmake b/cmake/QtFrameworkHelpers.cmake
index e8db635963..6d67bc4a11 100644
--- a/cmake/QtFrameworkHelpers.cmake
+++ b/cmake/QtFrameworkHelpers.cmake
@@ -72,7 +72,7 @@ function(qt_copy_framework_headers target)
 
     set(options)
     set(oneValueArgs)
-    set(multiValueArgs PUBLIC PRIVATE QPA)
+    set(multiValueArgs PUBLIC PRIVATE QPA RHI)
     cmake_parse_arguments(arg "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
     qt_internal_get_framework_info(fw ${target})
@@ -80,10 +80,11 @@ function(qt_copy_framework_headers target)
     set(output_dir_PUBLIC "${output_dir}/${fw_versioned_header_dir}")
     set(output_dir_PRIVATE "${output_dir}/${fw_private_module_header_dir}/private")
     set(output_dir_QPA "${output_dir}/${fw_private_module_header_dir}/qpa")
+    set(output_dir_RHI "${output_dir}/${fw_private_module_header_dir}/rhi")
 
 
     set(out_files)
-    foreach(type IN ITEMS PUBLIC PRIVATE QPA)
+    foreach(type IN ITEMS PUBLIC PRIVATE QPA RHI)
         set(fw_output_header_dir "${output_dir_${type}}")
         foreach(hdr IN LISTS arg_${type})
             get_filename_component(in_file_path ${hdr} ABSOLUTE)
diff --git a/cmake/QtModuleHelpers.cmake b/cmake/QtModuleHelpers.cmake
index d907214e09..e4dccd7f32 100644
--- a/cmake/QtModuleHelpers.cmake
+++ b/cmake/QtModuleHelpers.cmake
@@ -30,6 +30,7 @@ macro(qt_internal_get_internal_add_module_keywords option_args single_args multi
         EXTERNAL_HEADERS_DIR
         PRIVATE_HEADER_FILTERS
         QPA_HEADER_FILTERS
+        RHI_HEADER_FILTERS
         HEADER_SYNC_SOURCE_DIRECTORY
         ${__default_target_info_args}
     )
@@ -115,6 +116,10 @@ endfunction()
 #     The regular expressions that filter QPA header files out of target sources.
 #     The value must use the following format 'regex1|regex2|regex3'.
 #
+#   RHI_HEADER_FILTERS
+#     The regular expressions that filter RHI header files out of target sources.
+#     The value must use the following format 'regex1|regex2|regex3'.
+#
 #   HEADER_SYNC_SOURCE_DIRECTORY
 #     The source directory for header sync procedure. Header files outside this directory will be
 #     ignored by syncqt. The specifying this directory allows to skip the parsing of the whole
@@ -447,6 +452,13 @@ function(qt_internal_add_module target)
         set_target_properties(${target}
             PROPERTIES _qt_module_qpa_headers_filter_regex "${qpa_filter_regex}")
 
+        set(rhi_filter_regex "")
+        if(arg_RHI_HEADER_FILTERS)
+            set(rhi_filter_regex "${arg_RHI_HEADER_FILTERS}")
+        endif()
+        set_target_properties(${target}
+            PROPERTIES _qt_module_rhi_headers_filter_regex "${rhi_filter_regex}")
+
         set(private_filter_regex ".+_p(ch)?\\.h")
         if(arg_PRIVATE_HEADER_FILTERS)
             set(private_filter_regex "${private_filter_regex}|${arg_PRIVATE_HEADER_FILTERS}")
@@ -892,6 +904,7 @@ function(qt_finalize_module target)
         PUBLIC ${module_headers_public} "${module_depends_header}"
         PRIVATE ${module_headers_private}
         QPA ${module_headers_qpa}
+        RHI ${module_headers_rhi}
     )
 
     qt_finalize_framework_headers_copy(${target})
@@ -924,6 +937,7 @@ endfunction()
 #  * foo_versioned_inner_include_dir with the value "QtCore/6.2.0/QtCore"
 #  * foo_private_include_dir with the value "QtCore/6.2.0/QtCore/private"
 #  * foo_qpa_include_dir with the value "QtCore/6.2.0/QtCore/qpa"
+#  * foo_rhi_include_dir with the value "QtCore/6.2.0/QtCore/rhi"
 #  * foo_interface_name the interface name of the module stored in _qt_module_interface_name
 #    property, e.g. Core.
 #
@@ -946,6 +960,9 @@ endfunction()
 #  * foo_<build|install>_qpa_include_dir with
 #    qtbase_build_dir/include/QtCore/6.2.0/QtCore/qpa for build interface and
 #    include/QtCore/6.2.0/QtCore/qpa for install interface.
+#  * foo_<build|install>_rhi_include_dir with
+#    qtbase_build_dir/include/QtCore/6.2.0/QtCore/rhi for build interface and
+#    include/QtCore/6.2.0/QtCore/rhi for install interface.
 # The following values are set by the function and might be useful in caller's scope:
 #  * repo_install_interface_include_dir contains path to the top-level repository include directory,
 #    e.g. qtbase_build_dir/include
@@ -980,6 +997,8 @@ the different base name for the module info variables.")
         "${${result}_versioned_inner_include_dir}/private")
     set("${result}_qpa_include_dir"
         "${${result}_versioned_inner_include_dir}/qpa")
+    set("${result}_rhi_include_dir"
+        "${${result}_versioned_inner_include_dir}/rhi")
 
     # Module build interface directories
     set(repo_build_interface_include_dir "${QT_BUILD_DIR}/include")
@@ -993,6 +1012,8 @@ the different base name for the module info variables.")
         "${repo_build_interface_include_dir}/${${result}_private_include_dir}")
     set("${result}_build_interface_qpa_include_dir"
         "${repo_build_interface_include_dir}/${${result}_qpa_include_dir}")
+    set("${result}_build_interface_rhi_include_dir"
+        "${repo_build_interface_include_dir}/${${result}_rhi_include_dir}")
 
     # Module install interface directories
     set(repo_install_interface_include_dir "${INSTALL_INCLUDEDIR}")
@@ -1006,6 +1027,8 @@ the different base name for the module info variables.")
         "${repo_install_interface_include_dir}/${${result}_private_include_dir}")
     set("${result}_install_interface_qpa_include_dir"
         "${repo_install_interface_include_dir}/${${result}_qpa_include_dir}")
+    set("${result}_install_interface_rhi_include_dir"
+        "${repo_install_interface_include_dir}/${${result}_rhi_include_dir}")
 
     set("${result}" "${module}" PARENT_SCOPE)
     set("${result}_versioned" "${module_versioned}" PARENT_SCOPE)
@@ -1019,6 +1042,7 @@ the different base name for the module info variables.")
         "${${result}_versioned_inner_include_dir}" PARENT_SCOPE)
     set("${result}_private_include_dir" "${${result}_private_include_dir}" PARENT_SCOPE)
     set("${result}_qpa_include_dir" "${${result}_qpa_include_dir}" PARENT_SCOPE)
+    set("${result}_rhi_include_dir" "${${result}_rhi_include_dir}" PARENT_SCOPE)
     set("${result}_interface_name" "${module_interface_name}" PARENT_SCOPE)
 
     # Setting module build interface directories in parent scope
@@ -1033,6 +1057,8 @@ the different base name for the module info variables.")
         "${${result}_build_interface_private_include_dir}" PARENT_SCOPE)
     set("${result}_build_interface_qpa_include_dir"
         "${${result}_build_interface_qpa_include_dir}" PARENT_SCOPE)
+    set("${result}_build_interface_rhi_include_dir"
+        "${${result}_build_interface_rhi_include_dir}" PARENT_SCOPE)
 
     # Setting module install interface directories in parent scope
     set(repo_install_interface_include_dir "${repo_install_interface_include_dir}" PARENT_SCOPE)
@@ -1046,6 +1072,8 @@ the different base name for the module info variables.")
         "${${result}_install_interface_private_include_dir}" PARENT_SCOPE)
     set("${result}_install_interface_qpa_include_dir"
         "${${result}_install_interface_qpa_include_dir}" PARENT_SCOPE)
+    set("${result}_install_interface_rhi_include_dir"
+        "${${result}_install_interface_rhi_include_dir}" PARENT_SCOPE)
 endfunction()
 
 function(qt_internal_list_to_json_array out_var list_var)
@@ -1153,7 +1181,7 @@ endfunction()
 function(qt_internal_install_module_headers target)
     set(options)
     set(one_value_args)
-    set(multi_value_args PUBLIC PRIVATE QPA)
+    set(multi_value_args PUBLIC PRIVATE QPA RHI)
     cmake_parse_arguments(arg "${options}" "${one_value_args}" "${multi_value_args}" ${ARGN})
 
     qt_internal_module_info(module ${target})
@@ -1178,6 +1206,7 @@ function(qt_internal_install_module_headers target)
             PUBLIC ${arg_PUBLIC}
             PRIVATE ${arg_PRIVATE}
             QPA ${arg_QPA}
+            RHI ${arg_RHI}
         )
     else()
         if(arg_PUBLIC)
@@ -1191,6 +1220,9 @@ function(qt_internal_install_module_headers target)
         if(arg_QPA)
             qt_install(FILES ${arg_QPA} DESTINATION "${module_install_interface_qpa_include_dir}")
         endif()
+        if(arg_RHI)
+            qt_install(FILES ${arg_RHI} DESTINATION "${module_install_interface_rhi_include_dir}")
+        endif()
     endif()
 endfunction()
 
@@ -1198,6 +1230,7 @@ function(qt_internal_collect_module_headers out_var target)
     set(${out_var}_public "")
     set(${out_var}_private "")
     set(${out_var}_qpa "")
+    set(${out_var}_rhi "")
     set(${out_var}_all "")
 
     qt_internal_get_target_sources(sources ${target})
@@ -1215,6 +1248,7 @@ function(qt_internal_collect_module_headers out_var target)
     get_target_property(public_filter ${target} _qt_module_public_headers_filter_regex)
     get_target_property(private_filter ${target} _qt_module_private_headers_filter_regex)
     get_target_property(qpa_filter ${target} _qt_module_qpa_headers_filter_regex)
+    get_target_property(rhi_filter ${target} _qt_module_rhi_headers_filter_regex)
 
     set(condition_independent_headers_warning "")
     foreach(file_path IN LISTS sources)
@@ -1259,6 +1293,8 @@ function(qt_internal_collect_module_headers out_var target)
         list(APPEND ${out_var}_all "${file_path}")
         if(qpa_filter AND file_name MATCHES "${qpa_filter}")
             list(APPEND ${out_var}_qpa "${file_path}")
+        elseif(rhi_filter AND file_name MATCHES "${rhi_filter}")
+            list(APPEND ${out_var}_rhi "${file_path}")
         elseif(private_filter AND file_name MATCHES "${private_filter}")
             list(APPEND ${out_var}_private "${file_path}")
         elseif((NOT public_filter OR file_name MATCHES "${public_filter}")
@@ -1282,7 +1318,7 @@ function(qt_internal_collect_module_headers out_var target)
     endif()
 
 
-    set(header_types public private qpa)
+    set(header_types public private qpa rhi)
     set(has_header_types_properties "")
     foreach(header_type IN LISTS header_types)
         get_target_property(current_propety_value ${target} _qt_module_has_${header_type}_headers)
@@ -1304,5 +1340,6 @@ function(qt_internal_collect_module_headers out_var target)
             _qt_module_has_public_headers
             _qt_module_has_private_headers
             _qt_module_has_qpa_headers
+            _qt_module_has_rhi_headers
     )
 endfunction()
diff --git a/cmake/QtQmakeHelpers.cmake b/cmake/QtQmakeHelpers.cmake
index 8154661953..89284b0990 100644
--- a/cmake/QtQmakeHelpers.cmake
+++ b/cmake/QtQmakeHelpers.cmake
@@ -211,6 +211,7 @@ function(qt_get_qmake_module_name result module)
     string(REGEX REPLACE "^Qt6" "" module "${module}")
     string(REGEX REPLACE "Private$" "_private" module "${module}")
     string(REGEX REPLACE "Qpa$" "_qpa_lib_private" module "${module}")
+    string(REGEX REPLACE "Rhi$" "_rhi_lib_private" module "${module}")
     string(TOLOWER "${module}" module)
     set(${result} ${module} PARENT_SCOPE)
 endfunction()
diff --git a/cmake/QtSyncQtHelpers.cmake b/cmake/QtSyncQtHelpers.cmake
index 9fe18a2d50..1b0caed4d1 100644
--- a/cmake/QtSyncQtHelpers.cmake
+++ b/cmake/QtSyncQtHelpers.cmake
@@ -79,6 +79,7 @@ function(qt_internal_target_sync_headers target module_headers module_headers_ge
     endif()
 
     get_target_property(qpa_filter_regex ${target} _qt_module_qpa_headers_filter_regex)
+    get_target_property(rhi_filter_regex ${target} _qt_module_rhi_headers_filter_regex)
     get_target_property(private_filter_regex ${target} _qt_module_private_headers_filter_regex)
 
     # We need to use the real paths since otherwise it may lead to the invalid work of the
@@ -96,6 +97,12 @@ function(qt_internal_target_sync_headers target module_headers module_headers_ge
         )
     endif()
 
+    if(rhi_filter_regex)
+        set(rhi_filter_argument
+            -rhiHeadersFilter "${rhi_filter_regex}"
+        )
+    endif()
+
     set(common_syncqt_arguments
         -module "${module}"
         -sourceDir "${source_dir_real}"
@@ -104,8 +111,10 @@ function(qt_internal_target_sync_headers target module_headers module_headers_ge
         -includeDir "${module_build_interface_include_dir}"
         -privateIncludeDir "${module_build_interface_private_include_dir}"
         -qpaIncludeDir "${module_build_interface_qpa_include_dir}"
+        -rhiIncludeDir "${module_build_interface_rhi_include_dir}"
         -generatedHeaders ${module_headers_generated}
         ${qpa_filter_argument}
+        ${rhi_filter_argument}
         ${public_namespaces_filter}
         ${non_qt_module_argument}
         ${internal_module_argument}
diff --git a/examples/gui/CMakeLists.txt b/examples/gui/CMakeLists.txt
index 8eb3981a2f..8eda006a11 100644
--- a/examples/gui/CMakeLists.txt
+++ b/examples/gui/CMakeLists.txt
@@ -5,3 +5,4 @@ if(NOT TARGET Qt6::Gui)
     return()
 endif()
 qt_internal_add_example(rasterwindow)
+qt_internal_add_example(rhiwindow)
diff --git a/examples/gui/doc/images/rhiwindow_example.jpg b/examples/gui/doc/images/rhiwindow_example.jpg
new file mode 100644
index 0000000000..ca1e44bada
--- /dev/null
+++ b/examples/gui/doc/images/rhiwindow_example.jpg
diff --git a/examples/gui/doc/src/rhiwindow.qdoc b/examples/gui/doc/src/rhiwindow.qdoc
new file mode 100644
index 0000000000..478ac8a1b4
--- /dev/null
+++ b/examples/gui/doc/src/rhiwindow.qdoc
@@ -0,0 +1,439 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \example rhiwindow
+    \title RHI Window Example
+
+    \brief This example shows how to create a minimal QWindow-based
+    application using QRhi.
+
+    \image rhiwindow_example.jpg
+
+    Qt 6.6 starts offering its accelerated 3D API and shader abstraction layer
+    for application use as well. Applications can now use the same 3D graphics
+    classes Qt itself uses to implement the Qt Quick scenegraph or the Qt Quick
+    3D engine. In earlier Qt versions QRhi and the related classes were all
+    private APIs. From 6.6 on these classes are in a similar category as QPA
+    family of classes: neither fully public nor private, but something
+    in-between, with a more limited compatibility promise compared to public
+    APIs. On the other hand, QRhi and the related classes now come with full
+    documentation similarly to public APIs.
+
+    There are multiple ways to use QRhi, the example here shows the most
+    low-level approach: targeting a QWindow, while not using Qt Quick, Qt Quick
+    3D, or Widgets in any form, and setting up all the rendering and windowing
+    infrastructure in the application.
+
+    In contrast, when writing a QML application with Qt Quick or Qt Quick 3D,
+    and wanting to add QRhi-based rendering to it, such an application is going
+    to rely on the window and rendering infrastructure Qt Quick has already
+    initialized, and it is likely going to query an existing QRhi instance from
+    the QQuickWindow. There dealing with QRhi::create(), platform/API specifics
+    such as \l{QVulkanInstance}{Vulkan instances}, or correctly handling
+    \l{QExposeEvent}{expose} and resize events for the window are all managed
+    by Qt Quick. Whereas in this example, all that is managed and taken care
+    of by the application itself.
+
+    \note For QWidget-based applications in particular, it should be noted that
+    QWidget::createWindowContainer() allows embedding a QWindow (backed by a
+    native window) into the widget-based user interface. Therefore, the \c
+    HelloWindow class from this example is reusable in QWidget-based
+    applications, assuming the necessary initialization from \c main() is in
+    place as well.
+
+    \section1 3D API Support
+
+    The application supports all the current \l{QRhi::Implementation}{QRhi
+    backends}. When no command-line arguments are specified, platform-specific
+    defaults are used: Direct 3D 11 on Windows, OpenGL on Linux, Metal on
+    macOS/iOS.
+
+    Running with \c{--help} shows the available command-line options:
+
+    \list
+    \li -d or --d3d11 for Direct 3D 11
+    \li -D or --d3d12 for Direct 3D 12
+    \li -m or --metal for Metal
+    \li -v or --vulkan for Vulkan
+    \li -g or --opengl for OpenGL or OpenGL ES
+    \li -n or --null for the \l{QRhi::Null}{Null backend}
+    \endlist
+
+    \section1 Build System Notes
+
+    This application relies solely on the Qt GUI module. It does not use Qt
+    Widgets or Qt Quick.
+
+    In order to access the RHI APIs, which are available to all Qt applications
+    but come with a limited compatibility promise, the \c target_link_libraries
+    CMake command lists \c{Qt6::GuiPrivate}. This is what enables the
+    \c{#include <rhi/qrhi.h>} include statement to compile successfully.
+
+    \section1 Features
+
+    The application features:
+
+    \list
+
+    \li A resizable QWindow,
+
+    \li a swapchain and depth-stencil buffer that properly follows the size of
+    the window,
+
+    \li logic to initialize, render, and tear down at the appropriate time
+    based on events such as \l QExposeEvent and \l QPlatformSurfaceEvent,
+
+    \li rendering a fullscreen textured quad, using a texture the contents of
+    which is generated in a QImage via QPainter (using the raster paint engine,
+    i.e. the generating of the image's pixel data is all CPU-based, that data
+    is then uploaded into a GPU texture),
+
+    \li rendering a triangle with blending and depth testing enabled, using a
+    perspective projection, while applying a model transform that changes on
+    every frame,
+
+    \li an efficient, cross-platform render loop using
+    \l{QWindow::requestUpdate()}{requestUpdate()}.
+
+    \endlist
+
+    \section1 Shaders
+
+    The application uses two sets of vertex and fragment shader pairs:
+
+    \list
+
+    \li one for the fullscreen quad, which uses no vertex inputs and the
+    fragment shader samples a texture (\c quad.vert, \c quad.frag),
+
+    \li and another pair for the triangle, where vertex positions and colors
+    are provided in a vertex buffer and a modelview-projection matrix is
+    provided in a uniform buffer (\c color.vert, \c color.frag).
+
+    \endlist
+
+    The shaders are written as Vulkan-compatible GLSL source code.
+
+    Due to being a Qt GUI module example, this example cannot have a dependency
+    on the \l{Qt Shader Tools} module. This means that CMake helper functions
+    such as \c{qt_add_shaders} are not available for use. Therefore, the
+    example has the pre-processed \c{.qsb} files included in the
+    \c{shaders/prebuilt} folder, and they are simply included within the
+    executable via \c{qt_add_resources}. This approach is not generally
+    recommended for applications, consider rather using \l{Qt Shader Tools
+    Build System Integration}{qt_add_shaders}, which avoids the need to
+    manually generate and manage the \c{.qsb} files.
+
+    To generate the \c{.qsb} files for this example, the command \c{qsb --qt6
+    color.vert -o prebuilt/color.vert.qsb} etc. was used. This leads to
+    compiling to \l{https://www.khronos.org/spir/}{SPIR-V} and than transpiling
+    into GLSL (\c{100 es} and \c 120), HLSL (5.0), and MSL (1.2). All the
+    shader versions are then packed together into a QShader and serialized to
+    disk.
+
+    \section1 API-specific Initialization
+
+    For some of the 3D APIs the main() function has to perform the appropriate
+    API-specific initialiation, e.g. to create a QVulkanInstance when using
+    Vulkan. For OpenGL we have to ensure a depth buffer is available, this is
+    done via QSurfaceFormat. These steps are not in the scope of QRhi since
+    QRhi backends for OpenGL or Vulkan build on the existing Qt facilities such
+    as QOpenGLContext or QVulkanInstance.
+
+    \snippet rhiwindow/main.cpp api-setup
+
+    \note For Vulkan, note how
+    QRhiVulkanInitParams::preferredInstanceExtensions() is taken into account
+    to ensure the appropriate extensions are enabled.
+
+    \c HelloWindow is a subclass of \c RhiWindow, which in turn is a QWindow.
+    \c RhiWindow contains everything needed to manage a resizable window with
+    a\ swapchain (and depth-stencil buffer), and is potentially reusable in
+    other applications as well. \c HelloWindow contains the rendering logic
+    specific to this particular example application.
+
+    In the QWindow subclass constructor the surface type is set based on the
+    selected 3D API.
+
+    \snippet rhiwindow/rhiwindow.cpp rhiwindow-ctor
+
+    Creating and initializing a QRhi object is implemented in
+    RhiWindow::init(). Note that this is invoked only when the window is
+    \c renderable, which is indicated by an \l{QExposeEvent}{expose event}.
+
+    Depending on which 3D API we use, the appropriate InitParams struct needs
+    to be passed to QRhi::create(). With OpenGL for example, a
+    QOffscreenSurface (or some other QSurface) must be created by the
+    application and provided for use to the QRhi. With Vulkan, a successfully
+    initialized QVulkanInstance is required. Others, such as Direct 3D or Metal
+    need no additional information to be able to initialize.
+
+    \snippet rhiwindow/rhiwindow.cpp rhi-init
+
+    Apart from this, everything else, all the rendering code, is fully
+    cross-platform and has no branching or conditions specific to any of the 3D
+    API.
+
+    \section1 Expose Events
+
+    What \c renderable exactly means is platform-specific. For example, on
+    macOS a window that is fully obscured (fully behind some other window) is
+    not renderable, whereas on Windows obscuring has no significance.
+    Fortunately, the application needs no special knowledge about this: Qt's
+    platform plugins abstract the differences behind the expose event. However,
+    the \l{QWindow::exposeEvent()}{exposeEvent()} reimplementation also needs
+    to be aware that an empty output size (e.g. width and height of 0) is also
+    something that should be treated as a non-renderable situation. On Windows
+    for example, this is what is going to happen when minimizing the window.
+    Hence the check based on QRhiSwapChain::surfacePixelSize().
+
+    This implementation of expose event handling attempts to be robust, safe,
+    and portable. Qt Quick itself also implements a very similar logic in its
+    render loops.
+
+    \snippet rhiwindow/rhiwindow.cpp expose
+
+    In RhiWindow::render(), which is invoked in response to the
+    \l{QEvent::UpdateRequest}{UpdateRequest} event generated by
+    \l{QWindow::requestUpdate()}{requestUpdate()}, the following check is in
+    place, to prevent attempting to render when the swapchain initialization
+    failed, or when the window became non-renderable.
+
+    \snippet rhiwindow/rhiwindow.cpp render-precheck
+
+    \section1 Swapchain, Depth-Stencil buffer, and Resizing
+
+    To render to the QWindow, a QRhiSwapChain is needed. In addition, a
+    QRhiRenderBuffer acting as the depth-stencil buffer is created as well
+    since the application demonstrates how depth testing can be enabled in a
+    graphics pipeline. With some legacy 3D APIs managing the depth/stencil
+    buffer for a window is part of the corresponding windowing system interface
+    API (EGL, WGL, GLX, etc., meaning the depth/stencil buffer is implicitly
+    managed together with the \c{window surface}), whereas with modern APIs
+    managing the depth-stencil buffer for a window-based render target is no
+    different from offscreen render targets. QRhi abstracts this, but for best
+    performance it still needs to be indicated that the QRhiRenderBuffer is
+    \l{QRhiRenderBuffer::UsedWithSwapChainOnly}{used with together with a
+    QRhiSwapChain}.
+
+    The QRhiSwapChain is associated with the QWindow and the depth/stencil
+    buffer.
+
+    \snippet rhiwindow/rhiwindow.cpp swapchain-data
+
+    \snippet rhiwindow/rhiwindow.cpp swapchain-init
+
+    When the window size changes, the swapchain needs to be resized as well.
+    This is implemented in resizeSwapChain().
+
+    \snippet rhiwindow/rhiwindow.cpp swapchain-resize
+
+    Unlike other QRhiResource subclasses, QRhiSwapChain features slightly
+    different semantics when it comes to its create-function. As the name,
+    \l{QRhiSwapChain::createOrResize()}{createOrResize()}, suggests, this needs
+    to be called whenever it is known that the output window size may be out of
+    sync with what the swapchain was last initialized. The associated
+    QRhiRenderBuffer for depth-stencil gets its
+    \l{QRhiRenderBuffer::pixelSize()}{size} set automatically, and
+    \l{QRhiRenderBuffer::create()}{create()} is called on it implicitly from the
+    swapchain's createOrResize().
+
+    This is also a convenient place to (re)calculate the projection and view
+    matrices since the perspective projection we set up depends on the output
+    aspect ratio.
+
+    \note To eliminate coordinate system differences, the
+    \l{QRhi::clipSpaceCorrMatrix()}{a backend/API-specific "correction" matrix}
+    is queried from QRhi and baked in to the projection matrix. This is what
+    allows the application to work with OpenGL-style vertex data, assuming a
+    coordinate system with the origin at the bottom-left.
+
+    The resizeSwapChain() function is called from RhiWindow::render() when it
+    is discovered that the currently reported size is not the same anymore as
+    what the swapchain was last initialized with.
+
+    See QRhiSwapChain::currentPixelSize() and QRhiSwapChain::surfacePixelSize()
+    for further details.
+
+    High DPI support is built-in: the sizes, as the naming indicates, are
+    always in pixels, taking the window-specific
+    \l{QWindow::devicePixelRatio()}{scale factor} into account. On the QRhi
+    (and 3D API) level there is no concept of high DPI scaling, everything is
+    always in pixels. This means that a QWindow with a size() of 1280x720 and
+    a devicePixelRatio() of 2 is a render target (swapchain) with a (pixel) size
+    of 2560x1440.
+
+    \snippet rhiwindow/rhiwindow.cpp render-resize
+
+    \section1 Render Loop
+
+    The application renders continuously, throttled by the presentation rate
+    (vsync). This is ensured by calling
+    \l{QWindow::requestUpdate()}{requestUpdate()} from RhiWindow::render() when
+    the currently recorded frame has been submitted.
+
+    \snippet rhiwindow/rhiwindow.cpp request-update
+
+    This eventually leads to getting a \l{QEvent::UpdateRequest}{UpdateRequest}
+    event. This is handled in the reimplementation of event().
+
+    \snippet rhiwindow/rhiwindow.cpp event
+
+    \section1 Resource and Pipeline Setup
+
+    The application records a single render pass that issues two draw calls,
+    with two different graphics pipelines. One is the "background", with the
+    texture containing the QPainter-generated image, then a single triangle is
+    rendered on top with blending enabled.
+
+    The vertex and uniform buffer used with the triangle is created like this.
+    The size of the uniform buffer is 68 bytes since the shader specific a \c
+    mat4 and a \c float member in the uniform block. Watch out for the
+    \l{https://registry.khronos.org/OpenGL/specs/gl/glspec45.core.pdf#page=159}{std140
+    layout rules}. This presents no surprises in this example since the \c
+    float member that follows the \c mat4 has the correct alignment without any
+    additional padding, but it may become relevant in other applications,
+    especially when working with types such as \c vec2 or \c vec3. When in
+    doubt, consider checking the QShaderDescription for the
+    \l{QShader::description()}{QShader}, or, what is often more convenient, run
+    the \c qsb tool on the \c{.qsb} file with the \c{-d} argument to inspect
+    the metadata in human-readable form. The printed information includes,
+    among other things, the uniform block member offsets, sizes, and the total
+    size in bytes of each uniform block.
+
+    \snippet rhiwindow/rhiwindow.cpp render-init-1
+
+    The vertex and fragment shaders both need a uniform buffer at binding point
+    0. This is ensured by the QRhiShaderResourceBindings object. The graphics
+    pipeline is then setup with the shaders and a number of additional
+    information. The example also relies on a number of convenient defaults,
+    e.g. the primitive topology is
+    \l{QRhiGraphicsPipeline::Triangles}{Triangles}, but that is the default,
+    and therefore it is not explicitly set. See QRhiGraphicsPipeline for
+    further details.
+
+    In addition to specifying the topology and various state, the pipeline must
+    also be associated with:
+
+    \list
+
+    \li The vertex input layout in form of a QRhiVertexInputLayout. This
+    specifies the type and component count for each vertex input location, the
+    total stride in bytes per vertex, and other related data.
+    QRhiVertexInputLayout only holds data, not actual native resources, and is
+    copiable.
+
+    \li A valid and successfully initialized QRhiShaderResourceBindings object.
+    This describes the layout of the resource bindings (uniform buffers,
+    textures, samplers) the shaders expect. This must either by the
+    QRhiShaderResourceBindings used when recording the draw calls, or another
+    that is
+    \l{QRhiShaderResourceBindings::isLayoutCompatible()}{layout-compatible with it}.
+    This simple application takes the former approach.
+
+    \li A valid QRhiRenderPassDescriptor object. This must be retrieved from,
+    or \l{QRhiRenderPassDescriptor::isCompatible()}{be compatible with} the
+    render target. The example uses the former, by creating a
+    QRhiRenderPassDescriptor object via
+    QRhiSwapChain::newCompatibleRenderPassDescriptor().
+
+    \endlist
+
+    \snippet rhiwindow/rhiwindow.cpp render-init-2
+
+    getShader() is a helper function that loads a \c{.qsb} file and
+    deserializes a QShader from it.
+
+    \snippet rhiwindow/rhiwindow.cpp getshader
+
+    The \c{color.vert} shader specifies the following as the vertex inputs:
+
+    \badcode
+        layout(location = 0) in vec4 position;
+        layout(location = 1) in vec3 color;
+    \endcode
+
+    The C++ code however provides vertex data as 2 floats for position, with 3
+    floats for the color interleaved. (\c x, \c y, \c r, \c g, \c b for each
+    vertex) This is why the stride is \c{5 * sizeof(float)} and the inputs for
+    locations 0 and 1 are specified as \c Float2 and \c Float3, respectively.
+    This is valid, and the \c z and \c w of the \c vec4 position will get set
+    automatically.
+
+    \section1 Rendering
+
+    Recording a frame is started by calling \l{QRhi::beginFrame()} and finished
+    by calling \l{QRhi::endFrame()}.
+
+    \snippet rhiwindow/rhiwindow.cpp beginframe
+
+    Some of the resources (buffers, textures) have static data in the
+    application, meaning the content never changes. The vertex buffer's content
+    is provided in the initialization step for example, and is not changed
+    afterwards. These data update operations are recorded in \c
+    m_initialUpdates. When not yet done, the commands on this resource update
+    batch are merged into the per-frame batch.
+
+    \snippet rhiwindow/rhiwindow.cpp render-1
+
+    Having a per-frame resource update batch is necessary since the uniform
+    buffer contents with the modelview-projection matrix and the opacity
+    changes on every frame.
+
+    \snippet rhiwindow/rhiwindow.cpp render-rotation
+
+    \snippet rhiwindow/rhiwindow.cpp render-opacity
+
+    To begin recording the render pass, a QRhiCommandBuffer is queried, and the
+    output size is determined, which will be useful for setting up the viewport
+    and resizing our fullscreen texture, if needed.
+
+    \snippet rhiwindow/rhiwindow.cpp render-cb
+
+    Starting a render pass implies clearing the render target's color and
+    depth-stencil buffers (unless the render target flags indicate otherwise,
+    but that is only an option for texture-based render targets). Here we
+    specify black for color, 1.0f for depth, and 0 for stencil (unused). The
+    last argument, \c resourceUpdates, is what ensures that the data update
+    commands recorded on the batch get committed. Alternatively, we could have
+    used QRhiCommandBuffer::resourceUpdate() instead. The render pass targets a
+    swapchain, hence calling
+    \l{QRhiSwapChain::currentFrameRenderTarget()}{currentFrameRenderTarget()}
+    to get a valid QRhiRenderTarget.
+
+    \snippet rhiwindow/rhiwindow.cpp render-pass
+
+    Recording the draw call for the triangle is straightforward: set the
+    pipeline, set the shader resources, set the vertex/index buffer(s), and
+    record the draw call. Here we use a non-indexed draw with just 3 vertices.
+
+    \snippet rhiwindow/rhiwindow.cpp render-pass-record
+
+    The \l{QRhiCommandBuffer::setShaderResources()}{setShaderResources()} call
+    has no arguments given, which implies using \c m_colorTriSrb since that was
+    associated with the active QRhiGraphicsPipeline (\c m_colorPipeline).
+
+    We will not dive into the details of the rendering of the fullscreen
+    background image. See the example source code for that. It is however worth
+    noting a common pattern for "resizing" a texture or buffer resource. There
+    is no such thing as changing the size of an existing native resource, so
+    changing a texture or buffer size must be followed by a call to create(),
+    to release and recreate the underlying native resources. To ensure that the
+    QRhiTexture always has the required size, the application implements the
+    following logic. Note that \c m_texture stays valid for the entire lifetime
+    of the window, which means object references to it, e.g. in a
+    QRhiShaderResourceBindings, continue to be valid all the time. It is only
+    the underlying native resources that come and go over time.
+
+    \snippet rhiwindow/rhiwindow.cpp ensure-texture
+
+    Once a QImage is generated and the QPainter-based drawing into it has
+    finished, we use
+    \l{QRhiResourceUpdateBatch::uploadTexture()}{uploadTexture()} to record a
+    texture upload on the resource update batch:
+
+    \snippet rhiwindow/rhiwindow.cpp ensure-texture-2
+
+    \sa QRhi, QRhiSwapChain, QWindow, QRhiCommandBuffer, QRhiResourceUpdateBatch, QRhiBuffer, QRhiTexture
+  */
diff --git a/examples/gui/gui.pro b/examples/gui/gui.pro
index 2afb8bbfc7..0696458db1 100644
--- a/examples/gui/gui.pro
+++ b/examples/gui/gui.pro
@@ -4,4 +4,5 @@ TEMPLATE     = subdirs
 QT_FOR_CONFIG += gui
 CONFIG += no_docs_target
 
-SUBDIRS += rasterwindow
+SUBDIRS += rasterwindow \
+           rhiwindow
diff --git a/examples/gui/rhiwindow/CMakeLists.txt b/examples/gui/rhiwindow/CMakeLists.txt
new file mode 100644
index 0000000000..3c50add134
--- /dev/null
+++ b/examples/gui/rhiwindow/CMakeLists.txt
@@ -0,0 +1,59 @@
+# Copyright (C) 2023 The Qt Company Ltd.
+# SPDX-License-Identifier: BSD-3-Clause
+
+cmake_minimum_required(VERSION 3.16)
+project(rhiwindow LANGUAGES CXX)
+
+if(NOT DEFINED INSTALL_EXAMPLESDIR)
+    set(INSTALL_EXAMPLESDIR "examples")
+endif()
+
+set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/gui/rhiwindow")
+
+find_package(Qt6 REQUIRED COMPONENTS Core Gui)
+
+qt_standard_project_setup()
+
+qt_add_executable(rhiwindow
+    main.cpp
+    rhiwindow.cpp rhiwindow.h
+)
+
+set_target_properties(rhiwindow PROPERTIES
+    WIN32_EXECUTABLE TRUE
+    MACOSX_BUNDLE TRUE
+)
+
+target_link_libraries(rhiwindow PRIVATE
+    Qt6::Core
+    Qt6::Gui
+    Qt6::GuiPrivate
+)
+
+set_source_files_properties("shaders/prebuilt/color.vert.qsb"
+    PROPERTIES QT_RESOURCE_ALIAS "color.vert.qsb"
+)
+set_source_files_properties("shaders/prebuilt/color.frag.qsb"
+    PROPERTIES QT_RESOURCE_ALIAS "color.frag.qsb"
+)
+set_source_files_properties("shaders/prebuilt/quad.vert.qsb"
+    PROPERTIES QT_RESOURCE_ALIAS "quad.vert.qsb"
+)
+set_source_files_properties("shaders/prebuilt/quad.frag.qsb"
+    PROPERTIES QT_RESOURCE_ALIAS "quad.frag.qsb"
+)
+qt_add_resources(rhiwindow "rhiwindow"
+    PREFIX
+        "/"
+    FILES
+        "shaders/prebuilt/color.vert.qsb"
+        "shaders/prebuilt/color.frag.qsb"
+        "shaders/prebuilt/quad.vert.qsb"
+        "shaders/prebuilt/quad.frag.qsb"
+)
+
+install(TARGETS rhiwindow
+    RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
+    BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
+    LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
+)
diff --git a/examples/gui/rhiwindow/main.cpp b/examples/gui/rhiwindow/main.cpp
new file mode 100644
index 0000000000..c6d9ce5669
--- /dev/null
+++ b/examples/gui/rhiwindow/main.cpp
@@ -0,0 +1,100 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+#include <QGuiApplication>
+#include <QCommandLineParser>
+#include "rhiwindow.h"
+
+int main(int argc, char **argv)
+{
+    QGuiApplication app(argc, argv);
+
+    QRhi::Implementation graphicsApi;
+
+    // Use platform-specific defaults when no command-line arguments given.
+#if defined(Q_OS_WIN)
+    graphicsApi = QRhi::D3D11;
+#elif defined(Q_OS_MACOS) || defined(Q_OS_IOS)
+    graphicsApi = QRhi::Metal;
+#elif QT_CONFIG(vulkan)
+    graphicsApi = QRhi::Vulkan;
+#else
+    graphicsApi = QRhi::OpenGLES2;
+#endif
+
+    QCommandLineParser cmdLineParser;
+    cmdLineParser.addHelpOption();
+    QCommandLineOption nullOption({ "n", "null" }, QLatin1String("Null"));
+    cmdLineParser.addOption(nullOption);
+    QCommandLineOption glOption({ "g", "opengl" }, QLatin1String("OpenGL"));
+    cmdLineParser.addOption(glOption);
+    QCommandLineOption vkOption({ "v", "vulkan" }, QLatin1String("Vulkan"));
+    cmdLineParser.addOption(vkOption);
+    QCommandLineOption d3d11Option({ "d", "d3d11" }, QLatin1String("Direct3D 11"));
+    cmdLineParser.addOption(d3d11Option);
+    QCommandLineOption d3d12Option({ "D", "d3d12" }, QLatin1String("Direct3D 12"));
+    cmdLineParser.addOption(d3d12Option);
+    QCommandLineOption mtlOption({ "m", "metal" }, QLatin1String("Metal"));
+    cmdLineParser.addOption(mtlOption);
+
+    cmdLineParser.process(app);
+    if (cmdLineParser.isSet(nullOption))
+        graphicsApi = QRhi::Null;
+    if (cmdLineParser.isSet(glOption))
+        graphicsApi = QRhi::OpenGLES2;
+    if (cmdLineParser.isSet(vkOption))
+        graphicsApi = QRhi::Vulkan;
+    if (cmdLineParser.isSet(d3d11Option))
+        graphicsApi = QRhi::D3D11;
+    if (cmdLineParser.isSet(d3d12Option))
+        graphicsApi = QRhi::D3D12;
+    if (cmdLineParser.isSet(mtlOption))
+        graphicsApi = QRhi::Metal;
+
+ //! [api-setup]
+    // For OpenGL.
+    QSurfaceFormat fmt;
+    fmt.setDepthBufferSize(24);
+    fmt.setStencilBufferSize(8);
+    QSurfaceFormat::setDefaultFormat(fmt);
+
+    // For Vulkan.
+#if QT_CONFIG(vulkan)
+    QVulkanInstance inst;
+    if (graphicsApi == QRhi::Vulkan) {
+        // Request validation, if available. This is completely optional
+        // and has a performance impact, and should be avoided in production use.
+        inst.setLayers({ "VK_LAYER_KHRONOS_validation" });
+        // Play nice with QRhi.
+        inst.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
+        if (!inst.create()) {
+            qWarning("Failed to create Vulkan instance, switching to OpenGL");
+            graphicsApi = QRhi::OpenGLES2;
+        }
+    }
+#endif
+//! [api-setup]
+
+    HelloWindow window(graphicsApi);
+
+#if QT_CONFIG(vulkan)
+    if (graphicsApi == QRhi::Vulkan)
+        window.setVulkanInstance(&inst);
+#endif
+    window.resize(1280, 720);
+    window.setTitle(QCoreApplication::applicationName() + QLatin1String(" - ") + window.graphicsApiName());
+    window.show();
+
+    int ret = app.exec();
+
+    // RhiWindow::event() will not get invoked when the
+    // PlatformSurfaceAboutToBeDestroyed event is sent during the QWindow
+    // destruction. That happens only when exiting via app::quit() instead of
+    // the more common QWindow::close(). Take care of it: if the QPlatformWindow
+    // is still around (there was no close() yet), get rid of the swapchain
+    // while it's not too late.
+    if (window.handle())
+        window.releaseSwapChain();
+
+    return ret;
+}
diff --git a/examples/gui/rhiwindow/rhiwindow.cpp b/examples/gui/rhiwindow/rhiwindow.cpp
new file mode 100644
index 0000000000..5022244b86
--- /dev/null
+++ b/examples/gui/rhiwindow/rhiwindow.cpp
@@ -0,0 +1,435 @@
+// Copyright (C) 2020 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+#include "rhiwindow.h"
+#include <QPlatformSurfaceEvent>
+#include <QPainter>
+#include <QFile>
+#include <rhi/qshader.h>
+
+//! [rhiwindow-ctor]
+RhiWindow::RhiWindow(QRhi::Implementation graphicsApi)
+    : m_graphicsApi(graphicsApi)
+{
+    switch (graphicsApi) {
+    case QRhi::OpenGLES2:
+        setSurfaceType(OpenGLSurface);
+        break;
+    case QRhi::Vulkan:
+        setSurfaceType(VulkanSurface);
+        break;
+    case QRhi::D3D11:
+    case QRhi::D3D12:
+        setSurfaceType(Direct3DSurface);
+        break;
+    case QRhi::Metal:
+        setSurfaceType(MetalSurface);
+        break;
+    case QRhi::Null:
+        break; // RasterSurface
+    }
+}
+//! [rhiwindow-ctor]
+
+QString RhiWindow::graphicsApiName() const
+{
+    switch (m_graphicsApi) {
+    case QRhi::Null:
+        return QLatin1String("Null (no output)");
+    case QRhi::OpenGLES2:
+        return QLatin1String("OpenGL");
+    case QRhi::Vulkan:
+        return QLatin1String("Vulkan");
+    case QRhi::D3D11:
+        return QLatin1String("Direct3D 11");
+    case QRhi::D3D12:
+        return QLatin1String("Direct3D 12");
+    case QRhi::Metal:
+        return QLatin1String("Metal");
+    }
+    return QString();
+}
+
+//! [expose]
+void RhiWindow::exposeEvent(QExposeEvent *)
+{
+    // initialize and start rendering when the window becomes usable for graphics purposes
+    if (isExposed() && !m_initialized) {
+        init();
+        resizeSwapChain();
+        m_initialized = true;
+    }
+
+    const QSize surfaceSize = m_hasSwapChain ? m_sc->surfacePixelSize() : QSize();
+
+    // stop pushing frames when not exposed (or size is 0)
+    if ((!isExposed() || (m_hasSwapChain && surfaceSize.isEmpty())) && m_initialized && !m_notExposed)
+        m_notExposed = true;
+
+    // Continue when exposed again and the surface has a valid size. Note that
+    // surfaceSize can be (0, 0) even though size() reports a valid one, hence
+    // trusting surfacePixelSize() and not QWindow.
+    if (isExposed() && m_initialized && m_notExposed && !surfaceSize.isEmpty()) {
+        m_notExposed = false;
+        m_newlyExposed = true;
+    }
+
+    // always render a frame on exposeEvent() (when exposed) in order to update
+    // immediately on window resize.
+    if (isExposed() && !surfaceSize.isEmpty())
+        render();
+}
+//! [expose]
+
+//! [event]
+bool RhiWindow::event(QEvent *e)
+{
+    switch (e->type()) {
+    case QEvent::UpdateRequest:
+        render();
+        break;
+
+    case QEvent::PlatformSurface:
+        // this is the proper time to tear down the swapchain (while the native window and surface are still around)
+        if (static_cast<QPlatformSurfaceEvent *>(e)->surfaceEventType() == QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed)
+            releaseSwapChain();
+        break;
+
+    default:
+        break;
+    }
+
+    return QWindow::event(e);
+}
+//! [event]
+
+//! [rhi-init]
+void RhiWindow::init()
+{
+    if (m_graphicsApi == QRhi::Null) {
+        QRhiNullInitParams params;
+        m_rhi.reset(QRhi::create(QRhi::Null, &params));
+    }
+
+#if QT_CONFIG(opengl)
+    if (m_graphicsApi == QRhi::OpenGLES2) {
+        m_fallbackSurface.reset(QRhiGles2InitParams::newFallbackSurface());
+        QRhiGles2InitParams params;
+        params.fallbackSurface = m_fallbackSurface.get();
+        params.window = this;
+        m_rhi.reset(QRhi::create(QRhi::OpenGLES2, &params));
+    }
+#endif
+
+#if QT_CONFIG(vulkan)
+    if (m_graphicsApi == QRhi::Vulkan) {
+        QRhiVulkanInitParams params;
+        params.inst = vulkanInstance();
+        params.window = this;
+        m_rhi.reset(QRhi::create(QRhi::Vulkan, &params));
+    }
+#endif
+
+#ifdef Q_OS_WIN
+    if (m_graphicsApi == QRhi::D3D11) {
+        QRhiD3D11InitParams params;
+        // Enable the debug layer, if available. This is optional
+        // and should be avoided in production builds.
+        params.enableDebugLayer = true;
+        m_rhi.reset(QRhi::create(QRhi::D3D11, &params));
+    } else if (m_graphicsApi == QRhi::D3D12) {
+        QRhiD3D12InitParams params;
+        // Enable the debug layer, if available. This is optional
+        // and should be avoided in production builds.
+        params.enableDebugLayer = true;
+        m_rhi.reset(QRhi::create(QRhi::D3D12, &params));
+    }
+#endif
+
+#if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
+    if (m_graphicsApi == QRhi::Metal) {
+        QRhiMetalInitParams params;
+        m_rhi.reset(QRhi::create(QRhi::Metal, &params));
+    }
+#endif
+
+    if (!m_rhi)
+        qFatal("Failed to create RHI backend");
+//! [rhi-init]
+
+//! [swapchain-init]
+    m_sc.reset(m_rhi->newSwapChain());
+    m_ds.reset(m_rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil,
+                                      QSize(), // no need to set the size here, due to UsedWithSwapChainOnly
+                                      1,
+                                      QRhiRenderBuffer::UsedWithSwapChainOnly));
+    m_sc->setWindow(this);
+    m_sc->setDepthStencil(m_ds.get());
+    m_rp.reset(m_sc->newCompatibleRenderPassDescriptor());
+    m_sc->setRenderPassDescriptor(m_rp.get());
+//! [swapchain-init]
+
+    customInit();
+}
+
+//! [swapchain-resize]
+void RhiWindow::resizeSwapChain()
+{
+    m_hasSwapChain = m_sc->createOrResize(); // also handles m_ds
+
+    const QSize outputSize = m_sc->currentPixelSize();
+    m_viewProjection = m_rhi->clipSpaceCorrMatrix();
+    m_viewProjection.perspective(45.0f, outputSize.width() / (float) outputSize.height(), 0.01f, 1000.0f);
+    m_viewProjection.translate(0, 0, -4);
+}
+//! [swapchain-resize]
+
+void RhiWindow::releaseSwapChain()
+{
+    if (m_hasSwapChain) {
+        m_hasSwapChain = false;
+        m_sc->destroy();
+    }
+}
+
+//! [render-precheck]
+void RhiWindow::render()
+{
+    if (!m_hasSwapChain || m_notExposed)
+        return;
+//! [render-precheck]
+
+//! [render-resize]
+    // If the window got resized or newly exposed, resize the swapchain. (the
+    // newly-exposed case is not actually required by some platforms, but is
+    // here for robustness and portability)
+    //
+    // This (exposeEvent + the logic here) is the only safe way to perform
+    // resize handling. Note the usage of the RHI's surfacePixelSize(), and
+    // never QWindow::size(). (the two may or may not be the same under the hood,
+    // depending on the backend and platform)
+    //
+    if (m_sc->currentPixelSize() != m_sc->surfacePixelSize() || m_newlyExposed) {
+        resizeSwapChain();
+        if (!m_hasSwapChain)
+            return;
+        m_newlyExposed = false;
+    }
+//! [render-resize]
+
+//! [beginframe]
+    QRhi::FrameOpResult result = m_rhi->beginFrame(m_sc.get());
+    if (result == QRhi::FrameOpSwapChainOutOfDate) {
+        resizeSwapChain();
+        if (!m_hasSwapChain)
+            return;
+        result = m_rhi->beginFrame(m_sc.get());
+    }
+    if (result != QRhi::FrameOpSuccess) {
+        qWarning("beginFrame failed with %d, will retry", result);
+        requestUpdate();
+        return;
+    }
+
+    customRender();
+//! [beginframe]
+
+//! [request-update]
+    m_rhi->endFrame(m_sc.get());
+
+    // Always request the next frame via requestUpdate(). On some platforms this is backed
+    // by a platform-specific solution, e.g. CVDisplayLink on macOS, which is potentially
+    // more efficient than a timer, queued metacalls, etc.
+    requestUpdate();
+}
+//! [request-update]
+
+static float vertexData[] = {
+    // Y up (note clipSpaceCorrMatrix in m_viewProjection), CCW
+     0.0f,   0.5f,   1.0f, 0.0f, 0.0f,
+    -0.5f,  -0.5f,   0.0f, 1.0f, 0.0f,
+     0.5f,  -0.5f,   0.0f, 0.0f, 1.0f,
+};
+
+//! [getshader]
+static QShader getShader(const QString &name)
+{
+    QFile f(name);
+    if (f.open(QIODevice::ReadOnly))
+        return QShader::fromSerialized(f.readAll());
+
+    return QShader();
+}
+//! [getshader]
+
+HelloWindow::HelloWindow(QRhi::Implementation graphicsApi)
+    : RhiWindow(graphicsApi)
+{
+}
+
+//! [ensure-texture]
+void HelloWindow::ensureFullscreenTexture(const QSize &pixelSize, QRhiResourceUpdateBatch *u)
+{
+    if (m_texture && m_texture->pixelSize() == pixelSize)
+        return;
+
+    if (!m_texture)
+        m_texture.reset(m_rhi->newTexture(QRhiTexture::RGBA8, pixelSize));
+    else
+        m_texture->setPixelSize(pixelSize);
+
+    m_texture->create();
+
+    QImage image(pixelSize, QImage::Format_RGBA8888_Premultiplied);
+//! [ensure-texture]
+    QPainter painter(&image);
+    painter.fillRect(QRectF(QPointF(0, 0), pixelSize), QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f));
+    painter.setPen(Qt::transparent);
+    painter.setBrush({ QGradient(QGradient::DeepBlue) });
+    painter.drawRoundedRect(QRectF(QPointF(20, 20), pixelSize - QSize(40, 40)), 16, 16);
+    painter.setPen(Qt::black);
+    QFont font;
+    font.setPixelSize(0.05 * qMin(pixelSize.width(), pixelSize.height()));
+    painter.setFont(font);
+    painter.drawText(QRectF(QPointF(60, 60), pixelSize - QSize(120, 120)), 0,
+                     QLatin1String("Rendering with QRhi to a resizable QWindow.\nThe 3D API is %1.\nUse the command-line options to choose a different API.")
+                     .arg(graphicsApiName()));
+    painter.end();
+
+    if (m_rhi->isYUpInNDC())
+        image = image.mirrored();
+
+//! [ensure-texture-2]
+    u->uploadTexture(m_texture.get(), image);
+//! [ensure-texture-2]
+}
+
+//! [render-init-1]
+void HelloWindow::customInit()
+{
+    m_initialUpdates = m_rhi->nextResourceUpdateBatch();
+
+    m_vbuf.reset(m_rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData)));
+    m_vbuf->create();
+    m_initialUpdates->uploadStaticBuffer(m_vbuf.get(), vertexData);
+
+    static const quint32 UBUF_SIZE = 68;
+    m_ubuf.reset(m_rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, UBUF_SIZE));
+    m_ubuf->create();
+//! [render-init-1]
+
+    ensureFullscreenTexture(m_sc->surfacePixelSize(), m_initialUpdates);
+
+    m_sampler.reset(m_rhi->newSampler(QRhiSampler::Linear, QRhiSampler::Linear, QRhiSampler::None,
+                                      QRhiSampler::ClampToEdge, QRhiSampler::ClampToEdge));
+    m_sampler->create();
+
+ //! [render-init-2]
+    m_colorTriSrb.reset(m_rhi->newShaderResourceBindings());
+    static const QRhiShaderResourceBinding::StageFlags visibility =
+            QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage;
+    m_colorTriSrb->setBindings({
+            QRhiShaderResourceBinding::uniformBuffer(0, visibility, m_ubuf.get())
+    });
+    m_colorTriSrb->create();
+
+    m_colorPipeline.reset(m_rhi->newGraphicsPipeline());
+    // Enable depth testing; not quite needed for a simple triangle, but we
+    // have a depth-stencil buffer so why not.
+    m_colorPipeline->setDepthTest(true);
+    m_colorPipeline->setDepthWrite(true);
+    // Blend factors default to One, OneOneMinusSrcAlpha, which is convenient.
+    QRhiGraphicsPipeline::TargetBlend premulAlphaBlend;
+    premulAlphaBlend.enable = true;
+    m_colorPipeline->setTargetBlends({ premulAlphaBlend });
+    m_colorPipeline->setShaderStages({
+        { QRhiShaderStage::Vertex, getShader(QLatin1String(":/color.vert.qsb")) },
+        { QRhiShaderStage::Fragment, getShader(QLatin1String(":/color.frag.qsb")) }
+    });
+    QRhiVertexInputLayout inputLayout;
+    inputLayout.setBindings({
+        { 5 * sizeof(float) }
+    });
+    inputLayout.setAttributes({
+        { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
+        { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
+    });
+    m_colorPipeline->setVertexInputLayout(inputLayout);
+    m_colorPipeline->setShaderResourceBindings(m_colorTriSrb.get());
+    m_colorPipeline->setRenderPassDescriptor(m_rp.get());
+    m_colorPipeline->create();
+//! [render-init-2]
+
+    m_fullscreenQuadSrb.reset(m_rhi->newShaderResourceBindings());
+    m_fullscreenQuadSrb->setBindings({
+            QRhiShaderResourceBinding::sampledTexture(0, QRhiShaderResourceBinding::FragmentStage,
+                                       m_texture.get(), m_sampler.get())
+    });
+    m_fullscreenQuadSrb->create();
+
+    m_fullscreenQuadPipeline.reset(m_rhi->newGraphicsPipeline());
+    m_fullscreenQuadPipeline->setShaderStages({
+        { QRhiShaderStage::Vertex, getShader(QLatin1String(":/quad.vert.qsb")) },
+        { QRhiShaderStage::Fragment, getShader(QLatin1String(":/quad.frag.qsb")) }
+    });
+    m_fullscreenQuadPipeline->setVertexInputLayout({});
+    m_fullscreenQuadPipeline->setShaderResourceBindings(m_fullscreenQuadSrb.get());
+    m_fullscreenQuadPipeline->setRenderPassDescriptor(m_rp.get());
+    m_fullscreenQuadPipeline->create();
+}
+
+//! [render-1]
+void HelloWindow::customRender()
+{
+    QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
+
+    if (m_initialUpdates) {
+        resourceUpdates->merge(m_initialUpdates);
+        m_initialUpdates->release();
+        m_initialUpdates = nullptr;
+    }
+//! [render-1]
+
+//! [render-rotation]
+    m_rotation += 1.0f;
+    QMatrix4x4 modelViewProjection = m_viewProjection;
+    modelViewProjection.rotate(m_rotation, 0, 1, 0);
+    resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData());
+//! [render-rotation]
+
+//! [render-opacity]
+    m_opacity += m_opacityDir * 0.005f;
+    if (m_opacity < 0.0f || m_opacity > 1.0f) {
+        m_opacityDir *= -1;
+        m_opacity = qBound(0.0f, m_opacity, 1.0f);
+    }
+    resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 64, 4, &m_opacity);
+//! [render-opacity]
+
+//! [render-cb]
+    QRhiCommandBuffer *cb = m_sc->currentFrameCommandBuffer();
+    const QSize outputSizeInPixels = m_sc->currentPixelSize();
+//! [render-cb]
+
+    // (re)create the texture with a size matching the output surface size, when necessary.
+    ensureFullscreenTexture(outputSizeInPixels, resourceUpdates);
+
+//! [render-pass]
+    cb->beginPass(m_sc->currentFrameRenderTarget(), Qt::black, { 1.0f, 0 }, resourceUpdates);
+//! [render-pass]
+
+    cb->setGraphicsPipeline(m_fullscreenQuadPipeline.get());
+    cb->setViewport({ 0, 0, float(outputSizeInPixels.width()), float(outputSizeInPixels.height()) });
+    cb->setShaderResources();
+    cb->draw(3);
+
+//! [render-pass-record]
+    cb->setGraphicsPipeline(m_colorPipeline.get());
+    cb->setShaderResources();
+    const QRhiCommandBuffer::VertexInput vbufBinding(m_vbuf.get(), 0);
+    cb->setVertexInput(0, 1, &vbufBinding);
+    cb->draw(3);
+
+    cb->endPass();
+//! [render-pass-record]
+}
diff --git a/examples/gui/rhiwindow/rhiwindow.h b/examples/gui/rhiwindow/rhiwindow.h
new file mode 100644
index 0000000000..520c3e8c0a
--- /dev/null
+++ b/examples/gui/rhiwindow/rhiwindow.h
@@ -0,0 +1,78 @@
+// Copyright (C) 2020 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+#ifndef WINDOW_H
+#define WINDOW_H
+
+#include <QWindow>
+#include <QOffscreenSurface>
+#include <rhi/qrhi.h>
+
+class RhiWindow : public QWindow
+{
+public:
+    RhiWindow(QRhi::Implementation graphicsApi);
+    QString graphicsApiName() const;
+    void releaseSwapChain();
+
+protected:
+    virtual void customInit() = 0;
+    virtual void customRender() = 0;
+
+    // destruction order matters to a certain degree: the fallbackSurface must
+    // outlive the rhi, the rhi must outlive all other resources.  The resources
+    // need no special order when destroying.
+#if QT_CONFIG(opengl)
+    std::unique_ptr<QOffscreenSurface> m_fallbackSurface;
+#endif
+    std::unique_ptr<QRhi> m_rhi;
+//! [swapchain-data]
+    std::unique_ptr<QRhiSwapChain> m_sc;
+    std::unique_ptr<QRhiRenderBuffer> m_ds;
+    std::unique_ptr<QRhiRenderPassDescriptor> m_rp;
+//! [swapchain-data]
+    bool m_hasSwapChain = false;
+    QMatrix4x4 m_viewProjection;
+
+private:
+    void init();
+    void resizeSwapChain();
+    void render();
+
+    void exposeEvent(QExposeEvent *) override;
+    bool event(QEvent *) override;
+
+    QRhi::Implementation m_graphicsApi;
+    bool m_initialized = false;
+    bool m_notExposed = false;
+    bool m_newlyExposed = false;
+};
+
+class HelloWindow : public RhiWindow
+{
+public:
+    HelloWindow(QRhi::Implementation graphicsApi);
+
+    void customInit() override;
+    void customRender() override;
+
+private:
+    void ensureFullscreenTexture(const QSize &pixelSize, QRhiResourceUpdateBatch *u);
+
+    std::unique_ptr<QRhiBuffer> m_vbuf;
+    std::unique_ptr<QRhiBuffer> m_ubuf;
+    std::unique_ptr<QRhiTexture> m_texture;
+    std::unique_ptr<QRhiSampler> m_sampler;
+    std::unique_ptr<QRhiShaderResourceBindings> m_colorTriSrb;
+    std::unique_ptr<QRhiGraphicsPipeline> m_colorPipeline;
+    std::unique_ptr<QRhiShaderResourceBindings> m_fullscreenQuadSrb;
+    std::unique_ptr<QRhiGraphicsPipeline> m_fullscreenQuadPipeline;
+
+    QRhiResourceUpdateBatch *m_initialUpdates = nullptr;
+
+    float m_rotation = 0;
+    float m_opacity = 1;
+    int m_opacityDir = -1;
+};
+
+#endif
diff --git a/examples/gui/rhiwindow/rhiwindow.pri b/examples/gui/rhiwindow/rhiwindow.pri
new file mode 100644
index 0000000000..d0ef7a2699
--- /dev/null
+++ b/examples/gui/rhiwindow/rhiwindow.pri
@@ -0,0 +1,4 @@
+INCLUDEPATH += $$PWD
+SOURCES += $$PWD/rhiwindow.cpp
+HEADERS += $$PWD/rhiwindow.h
+RESOURCES += $$PWD/rhiwindow.qrc
diff --git a/examples/gui/rhiwindow/rhiwindow.pro b/examples/gui/rhiwindow/rhiwindow.pro
new file mode 100644
index 0000000000..18f259aaf6
--- /dev/null
+++ b/examples/gui/rhiwindow/rhiwindow.pro
@@ -0,0 +1,9 @@
+include(rhiwindow.pri)
+
+QT += gui-private
+
+SOURCES += \
+    main.cpp
+
+target.path = $$[QT_INSTALL_EXAMPLES]/gui/rhiwindow
+INSTALLS += target
diff --git a/examples/gui/rhiwindow/rhiwindow.qrc b/examples/gui/rhiwindow/rhiwindow.qrc
new file mode 100644
index 0000000000..1009ec5dda
--- /dev/null
+++ b/examples/gui/rhiwindow/rhiwindow.qrc
@@ -0,0 +1,8 @@
+<!DOCTYPE RCC><RCC version="1.0">
+<qresource>
+  <file alias="color.vert.qsb">shaders/prebuilt/color.vert.qsb</file>
+  <file alias="color.frag.qsb">shaders/prebuilt/color.frag.qsb</file>
+  <file alias="quad.vert.qsb">shaders/prebuilt/quad.vert.qsb</file>
+  <file alias="quad.frag.qsb">shaders/prebuilt/quad.frag.qsb</file>
+</qresource>
+</RCC>
diff --git a/examples/gui/rhiwindow/shaders/color.frag b/examples/gui/rhiwindow/shaders/color.frag
new file mode 100644
index 0000000000..6e0a3bc91f
--- /dev/null
+++ b/examples/gui/rhiwindow/shaders/color.frag
@@ -0,0 +1,15 @@
+#version 440
+
+layout(location = 0) in vec3 v_color;
+
+layout(location = 0) out vec4 fragColor;
+
+layout(std140, binding = 0) uniform buf {
+    mat4 mvp;
+    float opacity;
+};
+
+void main()
+{
+    fragColor = vec4(v_color * opacity, opacity);
+}
diff --git a/examples/gui/rhiwindow/shaders/color.vert b/examples/gui/rhiwindow/shaders/color.vert
new file mode 100644
index 0000000000..70852ab86c
--- /dev/null
+++ b/examples/gui/rhiwindow/shaders/color.vert
@@ -0,0 +1,17 @@
+#version 440
+
+layout(location = 0) in vec4 position;
+layout(location = 1) in vec3 color;
+
+layout(location = 0) out vec3 v_color;
+
+layout(std140, binding = 0) uniform buf {
+    mat4 mvp;
+    float opacity;
+};
+
+void main()
+{
+    v_color = color;
+    gl_Position = mvp * position;
+}
diff --git a/examples/gui/rhiwindow/shaders/prebuilt/color.frag.qsb b/examples/gui/rhiwindow/shaders/prebuilt/color.frag.qsb
new file mode 100644
index 0000000000..b4db470e5b
--- /dev/null
+++ b/examples/gui/rhiwindow/shaders/prebuilt/color.frag.qsb
diff --git a/examples/gui/rhiwindow/shaders/prebuilt/color.vert.qsb b/examples/gui/rhiwindow/shaders/prebuilt/color.vert.qsb
new file mode 100644
index 0000000000..ab046b77f8
--- /dev/null
+++ b/examples/gui/rhiwindow/shaders/prebuilt/color.vert.qsb
diff --git a/examples/gui/rhiwindow/shaders/prebuilt/quad.frag.qsb b/examples/gui/rhiwindow/shaders/prebuilt/quad.frag.qsb
new file mode 100644
index 0000000000..c2ea3cf251
--- /dev/null
+++ b/examples/gui/rhiwindow/shaders/prebuilt/quad.frag.qsb
diff --git a/examples/gui/rhiwindow/shaders/prebuilt/quad.vert.qsb b/examples/gui/rhiwindow/shaders/prebuilt/quad.vert.qsb
new file mode 100644
index 0000000000..f0b64f7500
--- /dev/null
+++ b/examples/gui/rhiwindow/shaders/prebuilt/quad.vert.qsb
diff --git a/examples/gui/rhiwindow/shaders/quad.frag b/examples/gui/rhiwindow/shaders/quad.frag
new file mode 100644
index 0000000000..65882a4292
--- /dev/null
+++ b/examples/gui/rhiwindow/shaders/quad.frag
@@ -0,0 +1,11 @@
+#version 440
+
+layout(location = 0) in vec2 v_uv;
+layout(location = 0) out vec4 fragColor;
+layout(binding = 0) uniform sampler2D tex;
+
+void main()
+{
+    vec4 c = texture(tex, v_uv);
+    fragColor = vec4(c.rgb * c.a, c.a);
+}
diff --git a/examples/gui/rhiwindow/shaders/quad.vert b/examples/gui/rhiwindow/shaders/quad.vert
new file mode 100644
index 0000000000..359896d080
--- /dev/null
+++ b/examples/gui/rhiwindow/shaders/quad.vert
@@ -0,0 +1,10 @@
+#version 440
+
+layout (location = 0) out vec2 v_uv;
+
+void main()
+{
+    // https://www.saschawillems.de/blog/2016/08/13/vulkan-tutorial-on-rendering-a-fullscreen-quad-without-buffers/
+    v_uv = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+    gl_Position = vec4(v_uv * 2.0 - 1.0, 0.0, 1.0);
+}
diff --git a/src/gui/CMakeLists.txt b/src/gui/CMakeLists.txt
index d2fad5d305..1b182d971d 100644
--- a/src/gui/CMakeLists.txt
+++ b/src/gui/CMakeLists.txt
@@ -212,14 +212,10 @@ qt_internal_add_module(Gui
         painting/qtriangulatingstroker.cpp painting/qtriangulatingstroker_p.h
         painting/qtriangulator.cpp painting/qtriangulator_p.h
         painting/qvectorpath_p.h
-        rhi/qrhi.cpp rhi/qrhi_p.h
-        rhi/qrhi_p_p.h
+        rhi/qrhi.cpp rhi/qrhi.h rhi/qrhi_platform.h rhi/qrhi_p.h
         rhi/qrhinull.cpp rhi/qrhinull_p.h
-        rhi/qrhinull_p_p.h
-        rhi/qshader.cpp rhi/qshader_p.h
-        rhi/qshader_p_p.h
-        rhi/qshaderdescription.cpp rhi/qshaderdescription_p.h
-        rhi/qshaderdescription_p_p.h
+        rhi/qshader.cpp rhi/qshader.h rhi/qshader_p.h
+        rhi/qshaderdescription.cpp rhi/qshaderdescription.h rhi/qshaderdescription_p.h
         text/qabstracttextdocumentlayout.cpp text/qabstracttextdocumentlayout.h text/qabstracttextdocumentlayout_p.h
         text/qdistancefield.cpp text/qdistancefield_p.h
         text/qfont.cpp text/qfont.h text/qfont_p.h
@@ -283,6 +279,8 @@ qt_internal_add_module(Gui
     GENERATE_CPP_EXPORTS
     QPA_HEADER_FILTERS
         "(^|/)qplatform.+\\.h$|(^|/)qwindowsystem.+\\.h$"
+    RHI_HEADER_FILTERS
+        "(^|/)qrhi\\.h$|(^|/)qrhi_platform\\.h$|(^|/)qshader\\.h$|(^|/)qshaderdescription\\.h$"
 )
 
 # Resources:
@@ -358,7 +356,6 @@ qt_internal_extend_target(Gui CONDITION QT_FEATURE_opengl
         opengl/qopenglfunctions.cpp
         opengl/qopenglprogrambinarycache.cpp opengl/qopenglprogrambinarycache_p.h
         rhi/qrhigles2.cpp rhi/qrhigles2_p.h
-        rhi/qrhigles2_p_p.h
 )
 
 qt_internal_extend_target(Gui CONDITION MACOS
@@ -409,10 +406,8 @@ qt_internal_extend_target(Gui CONDITION WIN32
         platform/windows/qwindowsmimeconverter.h platform/windows/qwindowsmimeconverter.cpp
         platform/windows/qwindowsnativeinterface.cpp
         rhi/qrhid3d11.cpp rhi/qrhid3d11_p.h
-        rhi/qrhid3d11_p_p.h
         rhi/vs_test_p.h
         rhi/qrhid3d12.cpp rhi/qrhid3d12_p.h
-        rhi/qrhid3d12_p_p.h
         rhi/cs_mipmap_p.h
         ../3rdparty/D3D12MemoryAllocator/D3D12MemAlloc.h
         ../3rdparty/D3D12MemoryAllocator/D3D12MemAlloc.cpp
@@ -832,8 +827,7 @@ qt_internal_extend_target(Gui CONDITION QT_FEATURE_filesystemmodel
 
 qt_internal_extend_target(Gui CONDITION QT_FEATURE_vulkan
     SOURCES
-        rhi/qrhivulkan.cpp rhi/qrhivulkan_p.h
-        rhi/qrhivulkanext_p.h
+        rhi/qrhivulkan.cpp rhi/qrhivulkan_p.h rhi/qrhivulkanext_p.h
         vulkan/qbasicvulkanplatforminstance.cpp vulkan/qbasicvulkanplatforminstance_p.h
         vulkan/qplatformvulkaninstance.cpp vulkan/qplatformvulkaninstance.h
         vulkan/qvulkandefaultinstance.cpp vulkan/qvulkandefaultinstance_p.h
@@ -969,7 +963,6 @@ qt_internal_extend_target(Gui CONDITION QT_FEATURE_xkbcommon AND UNIX
 qt_internal_extend_target(Gui CONDITION IOS OR MACOS
     SOURCES
         rhi/qrhimetal.mm rhi/qrhimetal_p.h
-        rhi/qrhimetal_p_p.h
     PUBLIC_LIBRARIES
         ${FWMetal}
 )
diff --git a/src/gui/doc/includes/QtGuiDoc b/src/gui/doc/includes/QtGuiDoc
index 80292141e2..e8fa73786e 100644
--- a/src/gui/doc/includes/QtGuiDoc
+++ b/src/gui/doc/includes/QtGuiDoc
@@ -16,3 +16,8 @@
 #include <QtGui/qpa/qplatformscreen_p.h>
 #include <QtGui/private/qguiapplication_p.h>
 #include <QtGui/private/qkeymapper_p.h>
+
+// rhi
+#include <QtGui/rhi/qrhi.h>
+#include <QtGui/rhi/qshader.h>
+#include <QtGui/rhi/qshaderdescription.h>
diff --git a/src/gui/doc/snippets/rhioffscreen/color.frag b/src/gui/doc/snippets/rhioffscreen/color.frag
new file mode 100644
index 0000000000..ad9d953d02
--- /dev/null
+++ b/src/gui/doc/snippets/rhioffscreen/color.frag
@@ -0,0 +1,16 @@
+//! [0]
+#version 440
+
+layout(location = 0) in vec3 v_color;
+layout(location = 0) out vec4 fragColor;
+
+layout(std140, binding = 0) uniform buf {
+    mat4 mvp;
+    float opacity;
+};
+
+void main()
+{
+    fragColor = vec4(v_color * opacity, opacity);
+}
+//! [0]
diff --git a/src/gui/doc/snippets/rhioffscreen/color.vert b/src/gui/doc/snippets/rhioffscreen/color.vert
new file mode 100644
index 0000000000..0010e55561
--- /dev/null
+++ b/src/gui/doc/snippets/rhioffscreen/color.vert
@@ -0,0 +1,18 @@
+//! [0]
+#version 440
+
+layout(location = 0) in vec4 position;
+layout(location = 1) in vec3 color;
+layout(location = 0) out vec3 v_color;
+
+layout(std140, binding = 0) uniform buf {
+    mat4 mvp;
+    float opacity;
+};
+
+void main()
+{
+    v_color = color;
+    gl_Position = mvp * position;
+}
+//! [0]
diff --git a/src/gui/doc/snippets/rhioffscreen/main.cpp b/src/gui/doc/snippets/rhioffscreen/main.cpp
new file mode 100644
index 0000000000..b3fac4b520
--- /dev/null
+++ b/src/gui/doc/snippets/rhioffscreen/main.cpp
@@ -0,0 +1,151 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+//! [0]
+#include <QGuiApplication>
+#include <QImage>
+#include <QFile>
+#include <rhi/qrhi.h>
+
+int main(int argc, char **argv)
+{
+    QGuiApplication app(argc, argv);
+
+    std::unique_ptr<QRhi> rhi;
+#if defined(Q_OS_WIN)
+    QRhiD3D12InitParams params;
+    rhi.reset(QRhi::create(QRhi::D3D12, &params));
+#elif defined(Q_OS_MACOS) || defined(Q_OS_IOS)
+    QRhiMetalInitParams params;
+    rhi.reset(QRhi::create(QRhi::Metal, &params));
+#elif QT_CONFIG(vulkan)
+    QVulkanInstance inst;
+    inst.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
+    if (inst.create()) {
+        QRhiVulkanInitParams params;
+        params.inst = &inst;
+        rhi.reset(QRhi::create(QRhi::Vulkan, &params));
+    } else {
+        qFatal("Failed to create Vulkan instance");
+    }
+#endif
+    if (rhi)
+        qDebug() << rhi->backendName() << rhi->driverInfo();
+    else
+        qFatal("Failed to initialize RHI");
+
+    float rotation = 0.0f;
+    float opacity = 1.0f;
+    int opacityDir = 1;
+
+    std::unique_ptr<QRhiTexture> tex(rhi->newTexture(QRhiTexture::RGBA8,
+                                                     QSize(1280, 720),
+                                                     1,
+                                                     QRhiTexture::RenderTarget | QRhiTexture::UsedAsTransferSource));
+    tex->create();
+    std::unique_ptr<QRhiTextureRenderTarget> rt(rhi->newTextureRenderTarget({ tex.get() }));
+    std::unique_ptr<QRhiRenderPassDescriptor> rp(rt->newCompatibleRenderPassDescriptor());
+    rt->setRenderPassDescriptor(rp.get());
+    rt->create();
+
+    QMatrix4x4 viewProjection = rhi->clipSpaceCorrMatrix();
+    viewProjection.perspective(45.0f, 1280 / 720.f, 0.01f, 1000.0f);
+    viewProjection.translate(0, 0, -4);
+
+    static float vertexData[] = { // Y up, CCW
+        0.0f,   0.5f,     1.0f, 0.0f, 0.0f,
+        -0.5f, -0.5f,     0.0f, 1.0f, 0.0f,
+        0.5f,  -0.5f,     0.0f, 0.0f, 1.0f,
+    };
+
+    std::unique_ptr<QRhiBuffer> vbuf(rhi->newBuffer(QRhiBuffer::Immutable,
+                                                    QRhiBuffer::VertexBuffer,
+                                                    sizeof(vertexData)));
+    vbuf->create();
+
+    std::unique_ptr<QRhiBuffer> ubuf(rhi->newBuffer(QRhiBuffer::Dynamic,
+                                                    QRhiBuffer::UniformBuffer,
+                                                    64 + 4));
+    ubuf->create();
+
+    std::unique_ptr<QRhiShaderResourceBindings> srb(rhi->newShaderResourceBindings());
+    srb->setBindings({
+        QRhiShaderResourceBinding::uniformBuffer(0,
+                                                 QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage,
+                                                 ubuf.get())
+    });
+    srb->create();
+
+    std::unique_ptr<QRhiGraphicsPipeline> ps(rhi->newGraphicsPipeline());
+    QRhiGraphicsPipeline::TargetBlend premulAlphaBlend;
+    premulAlphaBlend.enable = true;
+    ps->setTargetBlends({ premulAlphaBlend });
+    static auto getShader = [](const QString &name) {
+        QFile f(name);
+        if (f.open(QIODevice::ReadOnly))
+            return QShader::fromSerialized(f.readAll());
+        return QShader();
+    };
+    ps->setShaderStages({
+        { QRhiShaderStage::Vertex, getShader(QLatin1String("color.vert.qsb")) },
+        { QRhiShaderStage::Fragment, getShader(QLatin1String("color.frag.qsb")) }
+    });
+    QRhiVertexInputLayout inputLayout;
+    inputLayout.setBindings({
+        { 5 * sizeof(float) }
+    });
+    inputLayout.setAttributes({
+        { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
+        { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
+    });
+    ps->setVertexInputLayout(inputLayout);
+    ps->setShaderResourceBindings(srb.get());
+    ps->setRenderPassDescriptor(rp.get());
+    ps->create();
+
+    QRhiCommandBuffer *cb;
+    for (int frame = 0; frame < 20; ++frame) {
+        rhi->beginOffscreenFrame(&cb);
+
+        QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
+        if (frame == 0)
+            u->uploadStaticBuffer(vbuf.get(), vertexData);
+
+        QMatrix4x4 mvp = viewProjection;
+        mvp.rotate(rotation, 0, 1, 0);
+        u->updateDynamicBuffer(ubuf.get(), 0, 64, mvp.constData());
+        rotation += 5.0f;
+
+        u->updateDynamicBuffer(ubuf.get(), 64, 4, &opacity);
+        opacity += opacityDir * 0.2f;
+        if (opacity < 0.0f || opacity > 1.0f) {
+            opacityDir *= -1;
+            opacity = qBound(0.0f, opacity, 1.0f);
+        }
+
+        cb->beginPass(rt.get(), Qt::green, { 1.0f, 0 }, u);
+        cb->setGraphicsPipeline(ps.get());
+        cb->setViewport({ 0, 0, 1280, 720 });
+        cb->setShaderResources();
+        const QRhiCommandBuffer::VertexInput vbufBinding(vbuf.get(), 0);
+        cb->setVertexInput(0, 1, &vbufBinding);
+        cb->draw(3);
+        QRhiReadbackResult readbackResult;
+        u = rhi->nextResourceUpdateBatch();
+        u->readBackTexture({ tex.get() }, &readbackResult);
+        cb->endPass(u);
+
+        rhi->endOffscreenFrame();
+
+        QImage image(reinterpret_cast<const uchar *>(readbackResult.data.constData()),
+                     readbackResult.pixelSize.width(),
+                     readbackResult.pixelSize.height(),
+                     QImage::Format_RGBA8888_Premultiplied);
+        if (rhi->isYUpInFramebuffer())
+            image = image.mirrored();
+        image.save(QString::asprintf("frame%d.png", frame));
+    }
+
+    return 0;
+}
+//! [0]
diff --git a/src/gui/doc/src/qtgui-overview.qdoc b/src/gui/doc/src/qtgui-overview.qdoc
index e4052db5c8..8ba191d7f0 100644
--- a/src/gui/doc/src/qtgui-overview.qdoc
+++ b/src/gui/doc/src/qtgui-overview.qdoc
@@ -51,6 +51,56 @@
     that prefer more low-level APIs to text and font handling can use classes
     like QRawFont and QGlyphRun.
 
+    \section1 RHI Graphics
+
+    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}.
+
+    As an alternative to using OpenGL or Vulkan directly to render to a
+    QWindow, \l QRhi and the related classes provide a portable, cross-platform
+    3D graphics and compute API complemented by a shader conditioning and
+    transpiling pipeline. This way applications can avoid directly depending on
+    a single, and, in some cases, vendor or platform-specific 3D API.
+
+    Below is a list of the main RHI-related classes. These are complemented by
+    a number of additional classes and structs.
+
+    \list
+        \li QRhi
+        \li QShader
+        \li QShaderDescription
+        \li QRhiCommandBuffer
+        \li QRhiResourceUpdateBatch
+        \li QRhiBuffer
+        \li QRhiRenderBuffer
+        \li QRhiTexture
+        \li QRhiSampler
+        \li QRhiTextureRenderTarget
+        \li QRhiShaderResourceBindings
+        \li QRhiGraphicsPipeline
+        \li QRhiComputePipeline
+        \li QRhiSwapChain
+    \endlist
+
+    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.
+
+    \note The RHI family of APIs are currently offered with a limited
+    compatibility guarantee, as opposed to regular Qt public APIs. See \l QRhi
+    for details.
+
+    \section1 3D Matrix and Vector Math
+
+    The Qt GUI module also contains a few math classes to aid with the most
+    common mathematical operations related to 3D graphics. These classes
+    include \l {QMatrix4x4}, \l {QVector2D}, \l {QVector3D}, \l {QVector4D},
+    and \l {QQuaternion}.
+
     \section1 OpenGL and OpenGL ES Integration
 
     QWindow supports rendering using OpenGL and OpenGL ES, depending on what the
@@ -86,10 +136,6 @@
 
     For more information, see the \l {OpenGL Window Example}.
 
-    The Qt GUI module also contains a few math classes to aid with the most
-    common mathematical operations related to 3D graphics. These classes include
-    \l {QMatrix4x4}, \l {QVector4D}, and \l {QQuaternion}.
-
     A \l {QWindow} created with the \l {QSurface::OpenGLSurface} can be used in
     combination with \l QPainter and \l QOpenGLPaintDevice to have OpenGL
     hardware-accelerated 2D graphics by sacrificing some of the visual quality.
@@ -104,18 +150,21 @@
 
     On Android, Vulkan headers were added in API level 24 of the NDK.
 
-    Relevant classes:
+    The main relevant classes for low-level Vulkan support are:
 
     \list
-        \li QVulkanDeviceFunctions
-        \li QVulkanExtension
-        \li QVulkanFunctions
-        \li QVulkanInfoVector
         \li QVulkanInstance
-        \li QVulkanWindow
-        \li QVulkanWindowRenderer
+        \li QVulkanFunctions
+        \li QVulkanDeviceFunctions
     \endlist
 
+    In addition, \l QVulkanWindow provides a convenience subclass of QWindow
+    that makes it easier to get started with implementing Vulkan-based
+    rendering targeting a QWindow. Using this helper class is completely
+    optional; applications with more advanced Vulkan-based renderers may
+    instead want to use a QWindow with the \l {QSurface::VulkanSurface} type
+    directly.
+
     For more information, see the \l{Hello Vulkan Widget Example}
     and the \l {Hello Vulkan Triangle Example}.
 
diff --git a/src/gui/doc/src/qtgui.qdoc b/src/gui/doc/src/qtgui.qdoc
index d39fa72221..4ea352323a 100644
--- a/src/gui/doc/src/qtgui.qdoc
+++ b/src/gui/doc/src/qtgui.qdoc
@@ -54,6 +54,8 @@
         \list
             \li \l {Application Windows} {Qt GUI Application Windows}
             \li \l {2D Graphics} {Qt GUI 2D Graphics}
+            \li \l {RHI Graphics} {Qt GUI Accelerated 2D and 3D Graphics using the Qt RHI}
+            \li \l {3D Matrix and Vector Math} {Qt GUI Matrix and Vector Math}
             \li \l {OpenGL and OpenGL ES Integration}
                    {Qt GUI OpenGL and OpenGL ES Integration}
             \li \l {Vulkan Integration} {Qt GUI Vulkan Integration}
diff --git a/src/gui/kernel/qopenglcontext.cpp b/src/gui/kernel/qopenglcontext.cpp
index a018f86763..1dab68e579 100644
--- a/src/gui/kernel/qopenglcontext.cpp
+++ b/src/gui/kernel/qopenglcontext.cpp
@@ -69,6 +69,7 @@ QOpenGLContext *qt_gl_global_share_context()
 
 /*!
     \class QOpenGLContext
+    \ingroup painting-3D
     \inmodule QtGui
     \since 5.0
     \brief The QOpenGLContext class represents a native OpenGL context, enabling
diff --git a/src/gui/opengl/qopenglprogrambinarycache_p.h b/src/gui/opengl/qopenglprogrambinarycache_p.h
index 0237c81fc5..c3850bdee3 100644
--- a/src/gui/opengl/qopenglprogrambinarycache_p.h
+++ b/src/gui/opengl/qopenglprogrambinarycache_p.h
@@ -20,7 +20,7 @@
 #include <QtCore/qmutex.h>
 #include <QtCore/QLoggingCategory>
 #include <QtGui/private/qopenglcontext_p.h>
-#include <QtGui/private/qshader_p.h>
+#include <rhi/qshader.h>
 
 QT_BEGIN_NAMESPACE
 
diff --git a/src/gui/painting/qbackingstoredefaultcompositor_p.h b/src/gui/painting/qbackingstoredefaultcompositor_p.h
index d69c17f98f..839fa61c73 100644
--- a/src/gui/painting/qbackingstoredefaultcompositor_p.h
+++ b/src/gui/painting/qbackingstoredefaultcompositor_p.h
@@ -16,7 +16,7 @@
 //
 
 #include <qpa/qplatformbackingstore.h>
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 
 QT_BEGIN_NAMESPACE
 
diff --git a/src/gui/painting/qbackingstorerhisupport.cpp b/src/gui/painting/qbackingstorerhisupport.cpp
index 05329d61c5..15fea26d16 100644
--- a/src/gui/painting/qbackingstorerhisupport.cpp
+++ b/src/gui/painting/qbackingstorerhisupport.cpp
@@ -8,20 +8,9 @@
 #if QT_CONFIG(opengl)
 #include <QtGui/qoffscreensurface.h>
 #include <QtGui/private/qopenglcontext_p.h>
-#include <QtGui/private/qrhigles2_p.h>
-#endif
-
-#ifdef Q_OS_WIN
-#include <QtGui/private/qrhid3d11_p.h>
-#include <QtGui/private/qrhid3d12_p.h>
-#endif
-
-#if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
-#include <QtGui/private/qrhimetal_p.h>
 #endif
 
 #if QT_CONFIG(vulkan)
-#include <QtGui/private/qrhivulkan_p.h>
 #include <QtGui/private/qvulkandefaultinstance_p.h>
 #endif
 
diff --git a/src/gui/painting/qbackingstorerhisupport_p.h b/src/gui/painting/qbackingstorerhisupport_p.h
index c8aa8f46ea..39ce36c680 100644
--- a/src/gui/painting/qbackingstorerhisupport_p.h
+++ b/src/gui/painting/qbackingstorerhisupport_p.h
@@ -19,7 +19,7 @@
 #include <QtGui/qwindow.h>
 #include <QtGui/qsurfaceformat.h>
 #include <QtGui/qoffscreensurface.h>
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 #include <qpa/qplatformbackingstore.h>
 
 QT_BEGIN_NAMESPACE
diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 7b5acf80b0..506c85dfb5 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -1,23 +1,23 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#include "qrhi_p_p.h"
+#include "qrhi_p.h"
 #include <qmath.h>
 #include <QLoggingCategory>
 
-#include "qrhinull_p_p.h"
+#include "qrhinull_p.h"
 #ifndef QT_NO_OPENGL
-#include "qrhigles2_p_p.h"
+#include "qrhigles2_p.h"
 #endif
 #if QT_CONFIG(vulkan)
-#include "qrhivulkan_p_p.h"
+#include "qrhivulkan_p.h"
 #endif
 #ifdef Q_OS_WIN
-#include "qrhid3d11_p_p.h"
-#include "qrhid3d12_p_p.h"
+#include "qrhid3d11_p.h"
+#include "qrhid3d12_p.h"
 #endif
 #if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
-#include "qrhimetal_p_p.h"
+#include "qrhimetal_p.h"
 #endif
 
 #include <memory>
@@ -28,8 +28,9 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
 
 /*!
     \class QRhi
-    \internal
+    \ingroup painting-3D
     \inmodule QtGui
+    \since 6.6
 
     \brief Accelerated 2D/3D graphics API abstraction.
 
@@ -40,52 +41,52 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     \l{https://developer.apple.com/metal/}{Metal}, and
     \l{https://www.khronos.org/vulkan/}{Vulkan}.
 
-    Some of the main design goals are:
-
-    \list
-
-    \li Simple, minimal, understandable, extensible. Follow the proven path of the
-    Qt Quick scenegraph.
-
-    \li Aim to be a product - and in the bigger picture, part of a product (Qt) -
-    that is usable out of the box both by internal (such as, Qt Quick) and,
-    eventually, external users.
-
-    \li Not a complete 1:1 wrapper for any of the underlying APIs. The feature set
-    is tuned towards the needs of Qt's 2D and 3D offering (QPainter, Qt Quick, Qt
-    3D Studio). Iterate and evolve in a sustainable manner.
-
-    \li Intrinsically cross-platform, without reinventing: abstracting
-    cross-platform aspects of certain APIs (such as, OpenGL context creation and
-    windowing system interfaces, Vulkan instance and surface management) is not in
-    scope here. These are delegated to the existing QtGui facilities (QWindow,
-    QOpenGLContext, QVulkanInstance) and its backing QPA architecture.
-
-    \endlist
+    \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/tvOS, Direct3D on Windows).
+    on macOS/iOS, Direct3D on Windows).
 
     The available backends currently are:
 
     \list
 
-    \li OpenGL 2.1 or OpenGL ES 2.0 or newer. Some extensions are utilized when
-    present, for example to enable multisample framebuffers.
+    \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.1
+    \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
+    \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 Metal
+    \li Metal 1.2 or newer.
 
-    \li Vulkan 1.0, optionally with some extensions that are part of Vulkan 1.1
+    \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.
+    \li Null, a "dummy" backend that issues no graphics calls at all.
 
     \endlist
 
@@ -95,15 +96,60 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     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, but the core classes for using such shaders,
-    QShader and QShaderDescription, are.
+    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.
 
-    \section2 Design Fundamentals
+    \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 Design Fundamentals
 
     A QRhi cannot be instantiated directly. Instead, use the create()
     function. Delete the QRhi instance normally to release the graphics device.
 
-    \section3 Resources
+    \section2 Resources
 
     Instances of classes deriving from QRhiResource, such as, QRhiBuffer,
     QRhiTexture, etc., encapsulate zero, one, or more native graphics
@@ -111,10 +157,10 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     functions of the QRhi, such as, newBuffer(), newTexture(),
     newTextureRenderTarget(), newSwapChain().
 
-    \badcode
-        vbuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData));
-        if (!vbuf->create()) { error }
-        ...
+    \code
+        QRhiBuffer *vbuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData));
+        if (!vbuf->create()) { error(); }
+        // ...
         delete vbuf;
     \endcode
 
@@ -123,9 +169,10 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     \li The returned value from functions like newBuffer() is always owned by
     the caller.
 
-    \li Just creating 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 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(),
@@ -149,15 +196,15 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
 
     \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{QRhiCommandBuffer::beginFrame()}{beginFrame()} -
-    \l{QRhiCommandBuffer::endFrame()}{endFrame()} section). As a general rule,
-    all referenced QRhiResource objects must stay unchanged until the frame is
-    submitted by calling \l{QRhiCommandBuffer::endFrame()}{endFrame()}. To ease
-    this, QRhiResource::deleteLater() is provided as a convenience.
+    \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
 
-    \section3 Command buffers and deferred command execution
+    \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
@@ -184,7 +231,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
 
     As a general rule, all referenced QRhiResource objects must stay valid and
     unmodified until the frame is submitted by calling
-    \l{QRhiCommandBuffer::endFrame()}{endFrame()}. On the other hand, 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
@@ -192,10 +239,20 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
 
     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: \c{(re)create resources} - \c{begin frame} - \c{record
-    uploads and copies} - \c{start renderpass} - \c{record draw calls} - \c{end
-    renderpass} - \c{end frame}. Recording copy type of operations happens via
-    QRhiResourceUpdateBatch. Such operations are committed typically on
+    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
@@ -214,7 +271,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     remain the primary way of operating since this is what fits Qt's various UI
     technologies best.
 
-    \section3 Threading
+    \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
@@ -243,7 +300,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     (gui) thread, but becomes important when a separate, dedicated render
     thread is used.
 
-    \section3 Resource synchronization
+    \section2 Resource synchronization
 
     QRhi does not expose APIs for resource barriers or image layout
     transitions. Such synchronization is done implicitly by the backends, where
@@ -263,7 +320,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     different access (one for load, one for store) is supported even within the
     same pass.
 
-    \section3 Resource reuse
+    \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
@@ -283,24 +340,24 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     though there is a good chance that under the hood the QRhiBuffer is now
     backed by a whole new native buffer.
 
-    \badcode
-        ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 256);
+    \code
+        QRhiBuffer *ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 256);
         ubuf->create();
 
-        srb = rhi->newShaderResourceBindings()
+        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();
 
-        // That's it, srb needs no changes whatsoever, any references in it to
-        // ubuf stay valid. When it comes to internal details, such as that
+        // 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().
@@ -315,7 +372,7 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     resource underneath, without having to update the QRhiTextureRenderTarget
     as that will be done implicitly in beginPass().
 
-    \section3 Pooled objects
+    \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,
@@ -325,24 +382,25 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
     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::destroy().
+    calling QRhiResourceUpdateBatch::release().
 
     A typical pattern is thus:
 
-    \badcode
+    \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
 
-    \section3 Swapchain specifics
+    \section2 Swapchain specifics
 
     QRhiSwapChain features some special semantics due to the peculiar nature of
     swapchains.
@@ -373,30 +431,174 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
 
     \endlist
 
-    \section3 Ownership
+    \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::nativeHandles(). Most importantly, passing pointers in structs
+    QRhiTexture::nativeTexture(). Most importantly, passing pointers in structs
     and via setters does not transfer ownership.
 
-    \section2 Troubleshooting
+    \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.
 
-    Errors are printed to the output via qWarning(). 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.
+    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
 
-    It is strongly advised to inspect the output with the logging categories
-    (\c{qt.rhi.*}) enabled whenever a QRhi-based application is not behaving as
-    expected. For better interoperation with Qt Quick, the environment variable
-    \c{QSG_INFO} also enables these debug prints.
+    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 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 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
  */
 
 /*!
@@ -875,22 +1077,28 @@ Q_LOGGING_CATEGORY(QRHI_LOG_INFO, "qt.rhi.general")
 
 /*!
     \class QRhiInitParams
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Base class for backend-specific initialization parameters.
 
     Contains fields that are relevant to all backends.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
     \class QRhiDepthStencilClearValue
-    \internal
     \inmodule QtGui
+    \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
+    for details.
  */
 
 /*!
-    \fn QRhiDepthStencilClearValue::QRhiDepthStencilClearValue()
+    \fn QRhiDepthStencilClearValue::QRhiDepthStencilClearValue() = default
 
     Constructs a depth/stencil clear value with depth clear value 1.0f and
     stencil clear value 0.
@@ -907,6 +1115,26 @@ QRhiDepthStencilClearValue::QRhiDepthStencilClearValue(float d, quint32 s)
 }
 
 /*!
+    \fn float QRhiDepthStencilClearValue::depthClearValue() const
+    \return the depth clear value. In most cases this is 1.0f.
+ */
+
+/*!
+    \fn void QRhiDepthStencilClearValue::setDepthClearValue(float d)
+    Sets the depth clear value to \a d.
+ */
+
+/*!
+    \fn quint32 QRhiDepthStencilClearValue::stencilClearValue() const
+    \return the stencil clear value. In most cases this is 0.
+ */
+
+/*!
+    \fn void QRhiDepthStencilClearValue::setStencilClearValue(quint32 s)
+    Sets the stencil clear value to \a s.
+ */
+
+/*!
     \fn bool QRhiDepthStencilClearValue::operator==(const QRhiDepthStencilClearValue &a, const QRhiDepthStencilClearValue &b) noexcept
 
     \return \c true if the values in the two QRhiDepthStencilClearValue objects
@@ -940,8 +1168,8 @@ QDebug operator<<(QDebug dbg, const QRhiDepthStencilClearValue &v)
 
 /*!
     \class QRhiViewport
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Specifies a viewport rectangle.
 
     Used with QRhiCommandBuffer::setViewport().
@@ -951,20 +1179,23 @@ QDebug operator<<(QDebug dbg, const QRhiDepthStencilClearValue &v)
 
     Typical usage is like the following:
 
-    \badcode
+    \code
       const QSize outputSizeInPixels = swapchain->currentPixelSize();
       const QRhiViewport viewport(0, 0, outputSizeInPixels.width(), outputSizeInPixels.height());
-      cb->beginPass(swapchain->currentFrameRenderTarget(), { 0, 0, 0, 1 }, { 1, 0 });
+      cb->beginPass(swapchain->currentFrameRenderTarget(), Qt::black, { 1.0f, 0 });
       cb->setGraphicsPipeline(ps);
       cb->setViewport(viewport);
-      ...
+      // ...
     \endcode
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     \sa QRhiCommandBuffer::setViewport(), QRhi::clipSpaceCorrMatrix(), QRhiScissor
  */
 
 /*!
-    \fn QRhiViewport::QRhiViewport()
+    \fn QRhiViewport::QRhiViewport() = default
 
     Constructs a viewport description with an empty rectangle and a depth range
     of 0.0f - 1.0f.
@@ -990,6 +1221,41 @@ QRhiViewport::QRhiViewport(float x, float y, float w, float h, float minDepth, f
 }
 
 /*!
+    \fn std::array<float, 4> QRhiViewport::viewport() const
+    \return the viewport x, y, width, and height.
+ */
+
+/*!
+    \fn void QRhiViewport::setViewport(float x, float y, float w, float h)
+    Sets the viewport's position and size to \a x, \a y, \a w, and \a h.
+
+    \note Viewports are specified in a coordinate system that has its origin in
+    the bottom-left.
+ */
+
+/*!
+    \fn float QRhiViewport::minDepth() const
+    \return the minDepth value of the depth range of the viewport.
+ */
+
+/*!
+    \fn void QRhiViewport::setMinDepth(float minDepth)
+    Sets the \a minDepth of the depth range of the viewport.
+    By default this is set to 0.0f.
+ */
+
+/*!
+    \fn float QRhiViewport::maxDepth() const
+    \return the maxDepth value of the depth range of the viewport.
+ */
+
+/*!
+    \fn void QRhiViewport::setMaxDepth(float maxDepth)
+    Sets the \a maxDepth of the depth range of the viewport.
+    By default this is set to 1.0f.
+ */
+
+/*!
     \fn bool QRhiViewport::operator==(const QRhiViewport &a, const QRhiViewport &b) noexcept
 
     \return \c true if the values in the two QRhiViewport objects
@@ -1027,8 +1293,8 @@ QDebug operator<<(QDebug dbg, const QRhiViewport &v)
 
 /*!
     \class QRhiScissor
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Specifies a scissor rectangle.
 
     Used with QRhiCommandBuffer::setScissor(). Setting a scissor rectangle is
@@ -1042,11 +1308,14 @@ 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
+    for details.
+
     \sa QRhiCommandBuffer::setScissor(), QRhiViewport
  */
 
 /*!
-    \fn QRhiScissor::QRhiScissor()
+    \fn QRhiScissor::QRhiScissor() = default
 
     Constructs an empty scissor.
  */
@@ -1067,6 +1336,19 @@ QRhiScissor::QRhiScissor(int x, int y, int w, int h)
 }
 
 /*!
+    \fn std::array<int, 4> QRhiScissor::scissor() const
+    \return the scissor position and size.
+ */
+
+/*!
+    \fn void QRhiScissor::setScissor(int x, int y, int w, int h)
+    Sets the scissor position and size to \a x, \a y, \a w, \a h.
+
+    \note The position is always expected to be specified in a coordinate
+    system that has its origin in the bottom-left corner, like OpenGL.
+ */
+
+/*!
     \fn bool QRhiScissor::operator==(const QRhiScissor &a, const QRhiScissor &b) noexcept
 
     \return \c true if the values in the two QRhiScissor objects
@@ -1102,8 +1384,8 @@ QDebug operator<<(QDebug dbg, const QRhiScissor &s)
 
 /*!
     \class QRhiVertexInputBinding
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes a vertex input binding.
 
     Specifies the stride (in bytes, must be a multiple of 4), the
@@ -1121,7 +1403,7 @@ QDebug operator<<(QDebug dbg, const QRhiScissor &s)
     format in a buffer (or separate buffers even). Defining two bindings
     could then be done like this:
 
-    \badcode
+    \code
         QRhiVertexInputLayout inputLayout;
         inputLayout.setBindings({
             { 3 * sizeof(float) },
@@ -1138,7 +1420,7 @@ QDebug operator<<(QDebug dbg, const QRhiScissor &s)
     vertices, assuming we have a single buffer with first the positions and
     then the texture coordinates:
 
-    \badcode
+    \code
         const QRhiCommandBuffer::VertexInput vbufBindings[] = {
             { cubeBuf, 0 },
             { cubeBuf, 36 * 3 * sizeof(float) }
@@ -1154,6 +1436,9 @@ 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
+    for details.
+
     \sa QRhiCommandBuffer::setVertexInput()
  */
 
@@ -1166,7 +1451,7 @@ QDebug operator<<(QDebug dbg, const QRhiScissor &s)
  */
 
 /*!
-    \fn QRhiVertexInputBinding::QRhiVertexInputBinding()
+    \fn QRhiVertexInputBinding::QRhiVertexInputBinding() = default
 
     Constructs a default vertex input binding description.
  */
@@ -1186,6 +1471,36 @@ QRhiVertexInputBinding::QRhiVertexInputBinding(quint32 stride, Classification cl
 }
 
 /*!
+    \fn quint32 QRhiVertexInputBinding::stride() const
+    \return the stride in bytes.
+ */
+
+/*!
+    \fn void QRhiVertexInputBinding::setStride(quint32 s)
+    Sets the stride to \a s.
+ */
+
+/*!
+    \fn QRhiVertexInputBinding::Classification QRhiVertexInputBinding::classification() const
+    \return the input data classification.
+ */
+
+/*!
+    \fn void QRhiVertexInputBinding::setClassification(Classification c)
+    Sets the input data classification \a c. By default this is set to PerVertex.
+ */
+
+/*!
+    \fn quint32 QRhiVertexInputBinding::instanceStepRate() const
+    \return the instance step rate.
+ */
+
+/*!
+    \fn void QRhiVertexInputBinding::setInstanceStepRate(quint32 rate)
+    Sets the instance step \a rate. By default this is set to 1.
+ */
+
+/*!
     \fn bool QRhiVertexInputBinding::operator==(const QRhiVertexInputBinding &a, const QRhiVertexInputBinding &b) noexcept
 
     \return \c true if the values in the two QRhiVertexInputBinding objects
@@ -1219,14 +1534,15 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b)
 
 /*!
     \class QRhiVertexInputAttribute
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes a single vertex input element.
 
     The members specify the binding number, location, format, and offset for a
     single vertex input element.
 
-    \note For HLSL it is assumed that the vertex shader uses
+    \note For HLSL it is assumed that the vertex shader translated from SPIR-V
+    uses
     \c{TEXCOORD<location>} as the semantic for each input. Hence no separate
     semantic name and index.
 
@@ -1242,7 +1558,7 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b)
     non-interleaved format in a buffer (or separate buffers even). Once two
     bindings are defined, the attributes could be specified as:
 
-    \badcode
+    \code
         QRhiVertexInputLayout inputLayout;
         inputLayout.setBindings({
             { 3 * sizeof(float) },
@@ -1259,7 +1575,7 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b)
     vertices, assuming we have a single buffer with first the positions and
     then the texture coordinates:
 
-    \badcode
+    \code
         const QRhiCommandBuffer::VertexInput vbufBindings[] = {
             { cubeBuf, 0 },
             { cubeBuf, 36 * 3 * sizeof(float) }
@@ -1271,7 +1587,7 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b)
     binding, with multiple attributes referring to that same buffer binding
     point:
 
-    \badcode
+    \code
         QRhiVertexInputLayout inputLayout;
         inputLayout.setBindings({
             { 5 * sizeof(float) }
@@ -1284,11 +1600,14 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b)
 
     and then:
 
-    \badcode
+    \code
         const QRhiCommandBuffer::VertexInput vbufBinding(interleavedCubeBuf, 0);
         cb->setVertexInput(0, 1, &vbufBinding);
     \endcode
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     \sa QRhiCommandBuffer::setVertexInput()
  */
 
@@ -1311,10 +1630,10 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b)
     \value SInt3 Three component signed integer vector
     \value SInt2 Two component signed integer vector
     \value SInt Signed integer
-    \value Half4 Four component half precision (16bit) float vector
-    \value Half3 Three component half precision (16bit) float vector
-    \value Half2 Two component half precision (16bit) float vector
-    \value Half half precision (16bit) float
+    \value Half4 Four component half precision (16 bit) float vector
+    \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
 
     \note Support for half precision floating point attributes is indicated at
     run time by the QRhi::Feature::HalfAttributes feature flag. Note that D3D
@@ -1324,7 +1643,7 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputBinding &b)
  */
 
 /*!
-    \fn QRhiVertexInputAttribute::QRhiVertexInputAttribute()
+    \fn QRhiVertexInputAttribute::QRhiVertexInputAttribute() = default
 
     Constructs a default vertex input attribute description.
  */
@@ -1349,6 +1668,67 @@ QRhiVertexInputAttribute::QRhiVertexInputAttribute(int binding, int location, Fo
 }
 
 /*!
+    \fn int QRhiVertexInputAttribute::binding() const
+    \return the binding point index.
+ */
+
+/*!
+    \fn void QRhiVertexInputAttribute::setBinding(int b)
+    Sets the binding point index to \a b.
+    By default this is set to 0.
+ */
+
+/*!
+    \fn int QRhiVertexInputAttribute::location() const
+    \return the location of the vertex input element.
+ */
+
+/*!
+    \fn void QRhiVertexInputAttribute::setLocation(int loc)
+    Sets the location of the vertex input element to \a loc.
+    By default this is set to 0.
+ */
+
+/*!
+    \fn QRhiVertexInputAttribute::Format QRhiVertexInputAttribute::format() const
+    \return the format of the vertex input element.
+ */
+
+/*!
+    \fn void QRhiVertexInputAttribute::setFormat(Format f)
+    Sets the format of the vertex input element to \a f.
+    By default this is set to Float4.
+ */
+
+/*!
+    \fn quint32 QRhiVertexInputAttribute::offset() const
+    \return the byte offset for the input element.
+ */
+
+/*!
+    \fn void QRhiVertexInputAttribute::setOffset(quint32 ofs)
+    Sets the byte offset for the input element to \a ofs.
+ */
+
+/*!
+    \fn int QRhiVertexInputAttribute::matrixSlice() const
+
+    \return the matrix slice if the input element corresponds to a row or
+    column of a matrix, or -1 if not relevant.
+ */
+
+/*!
+    \fn void QRhiVertexInputAttribute::setMatrixSlice(int slice)
+
+    Sets the matrix \a slice. By default this is set to -1, and should be set
+    to a >= 0 value only when this attribute corresponds to a row or column of
+    a matrix (for example, a 4x4 matrix becomes 4 vec4s, consuming 4
+    consecutive vertex input locations), in which case it is the index of the
+    row or column. \c{location - matrixSlice} must always be equal to the \c
+    location for the first row or column of the unrolled matrix.
+ */
+
+/*!
     \fn bool QRhiVertexInputAttribute::operator==(const QRhiVertexInputAttribute &a, const QRhiVertexInputAttribute &b) noexcept
 
     \return \c true if the values in the two QRhiVertexInputAttribute objects
@@ -1478,21 +1858,102 @@ quint32 QRhiImplementation::byteSizePerVertexForVertexInputFormat(QRhiVertexInpu
 
 /*!
     \class QRhiVertexInputLayout
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes the layout of vertex inputs consumed by a vertex shader.
 
     The vertex input layout is defined by the collections of
     QRhiVertexInputBinding and QRhiVertexInputAttribute.
+
+    As an example, let's assume that we have a single buffer with 3 component
+    vertex positions and 2 component UV coordinates interleaved (\c x, \c y, \c
+    z, \c u, \c v), that the position and UV are expected at input locations 0
+    and 1 by the vertex shader, and that the vertex buffer will be bound at
+    binding point 0 using
+    \l{QRhiCommandBuffer::setVertexInput()}{setVertexInput()} later on:
+
+    \code
+        QRhiVertexInputLayout inputLayout;
+        inputLayout.setBindings({
+            { 5 * sizeof(float) }
+        });
+        inputLayout.setAttributes({
+            { 0, 0, QRhiVertexInputAttribute::Float3, 0 },
+            { 0, 1, QRhiVertexInputAttribute::Float2, 3 * sizeof(float) }
+        });
+    \endcode
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
-    \fn QRhiVertexInputLayout::QRhiVertexInputLayout()
+    \fn QRhiVertexInputLayout::QRhiVertexInputLayout() = default
 
     Constructs an empty vertex input layout description.
  */
 
 /*!
+    \fn void QRhiVertexInputLayout::setBindings(std::initializer_list<QRhiVertexInputBinding> list)
+    Sets the bindings from the specified \a list.
+ */
+
+/*!
+    \fn template<typename InputIterator> void QRhiVertexInputLayout::setBindings(InputIterator first, InputIterator last)
+    Sets the bindings using the iterators \a first and \a last.
+ */
+
+/*!
+    \fn const QRhiVertexInputBinding *QRhiVertexInputLayout::cbeginBindings() const
+    \return a const iterator pointing to the first item in the binding list.
+ */
+
+/*!
+    \fn const QRhiVertexInputBinding *QRhiVertexInputLayout::cendBindings() const
+    \return a const iterator pointing just after the last item in the binding list.
+ */
+
+/*!
+    \fn const QRhiVertexInputBinding *QRhiVertexInputLayout::bindingAt(qsizetype index) const
+    \return the binding at the given \a index.
+ */
+
+/*!
+    \fn qsizetype QRhiVertexInputLayout::bindingCount() const
+    \return the number of bindings.
+ */
+
+/*!
+    \fn void QRhiVertexInputLayout::setAttributes(std::initializer_list<QRhiVertexInputAttribute> list)
+    Sets the attributes from the specified \a list.
+ */
+
+/*!
+    \fn template<typename InputIterator> void QRhiVertexInputLayout::setAttributes(InputIterator first, InputIterator last)
+    Sets the attributes using the iterators \a first and \a last.
+ */
+
+/*!
+    \fn const QRhiVertexInputAttribute *QRhiVertexInputLayout::cbeginAttributes() const
+    \return a const iterator pointing to the first item in the attribute list.
+ */
+
+/*!
+    \fn const QRhiVertexInputAttribute *QRhiVertexInputLayout::cendAttributes() const
+    \return a const iterator pointing just after the last item in the attribute list.
+ */
+
+/*!
+    \fn const QRhiVertexInputAttribute *QRhiVertexInputLayout::attributeAt(qsizetype index) const
+    \return the attribute at the given \a index.
+ */
+
+/*!
+    \fn qsizetype QRhiVertexInputLayout::attributeCount() const
+    \return the number of attributes.
+ */
+
+/*!
     \fn bool QRhiVertexInputLayout::operator==(const QRhiVertexInputLayout &a, const QRhiVertexInputLayout &b) noexcept
 
     \return \c true if the values in the two QRhiVertexInputLayout objects
@@ -1525,9 +1986,41 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputLayout &v)
 
 /*!
     \class QRhiShaderStage
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Specifies the type and the shader code for a shader stage in the pipeline.
+
+    When setting up a QRhiGraphicsPipeline, a collection of shader stages are
+    specified. The QRhiShaderStage contains a QShader and some associated
+    metadata, such as the graphics pipeline stage, and the
+    \l{QShader::Variant}{shader variant} to select. There is no need to specify
+    the shader language or version because the QRhi backend in use at runtime
+    will take care of choosing the appropriate shader version from the
+    collection within the QShader.
+
+    The typical usage is in combination with
+    QRhiGraphicsPipeline::setShaderStages(), shown here with a simple approach
+    to load the QShader from \c{.qsb} files generated offline or at build time:
+
+    \code
+        QShader getShader(const QString &name)
+        {
+            QFile f(name);
+            if (f.open(QIODevice::ReadOnly))
+                return QShader::fromSerialized(f.readAll());
+            return QShader();
+        }
+
+        QShader vs = getShader("material.vert.qsb");
+        QShader fs = getShader("material.frag.qsb");
+        pipeline->setShaderStages({
+            { QRhiShaderStage::Vertex, vs },
+            { QRhiShaderStage::Fragment, fs }
+        });
+    \endcode
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
@@ -1552,13 +2045,46 @@ QDebug operator<<(QDebug dbg, const QRhiVertexInputLayout &v)
  */
 
 /*!
-    \fn QRhiShaderStage::QRhiShaderStage()
+    \fn QRhiShaderStage::QRhiShaderStage() = default
 
     Constructs a shader stage description for the vertex stage with an empty
     QShader.
  */
 
 /*!
+    \fn QRhiShaderStage::Type QRhiShaderStage::type() const
+    \return the type of the stage.
+ */
+
+/*!
+    \fn void QRhiShaderStage::setType(Type t)
+
+    Sets the type of the stage to \a t. Setters should rarely be needed in
+    pratice. Most applications will likely use the QRhiShaderStage constructor
+    in most cases.
+ */
+
+/*!
+    \fn QShader QRhiShaderStage::shader() const
+    \return the QShader to be used for this stage in the graphics pipeline.
+ */
+
+/*!
+    \fn void QRhiShaderStage::setShader(const QShader &s)
+    Sets the shader collection \a s.
+ */
+
+/*!
+    \fn QShader::Variant QRhiShaderStage::shaderVariant() const
+    \return the requested shader variant.
+ */
+
+/*!
+    \fn void QRhiShaderStage::setShaderVariant(QShader::Variant v)
+    Sets the requested shader variant \a v.
+ */
+
+/*!
     Constructs a shader stage description with the \a type of the stage and the
     \a shader.
 
@@ -1608,12 +2134,14 @@ QDebug operator<<(QDebug dbg, const QRhiShaderStage &s)
 
 /*!
     \class QRhiColorAttachment
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes the a single color attachment of a render target.
 
     A color attachment is either a QRhiTexture or a QRhiRenderBuffer. The
-    former, when texture() is set, is used in most cases.
+    former, i.e. when texture() is set, is used in most cases.
+    QRhiColorAttachment is commonly used in combination with
+    QRhiTextureRenderTargetDescription.
 
     \note texture() and renderBuffer() cannot be both set (be non-null at the
     same time).
@@ -1640,10 +2168,15 @@ QDebug operator<<(QDebug dbg, const QRhiShaderStage &s)
     \note when resolving is enabled, the multisample data may not be written
     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
+    for details.
+
+    \sa QRhiTextureRenderTargetDescription
  */
 
 /*!
-    \fn QRhiColorAttachment::QRhiColorAttachment()
+    \fn QRhiColorAttachment::QRhiColorAttachment() = default
 
     Constructs an empty color attachment description.
  */
@@ -1667,9 +2200,105 @@ QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer)
 }
 
 /*!
+    \fn QRhiTexture *QRhiColorAttachment::texture() const
+
+    \return the texture this attachment description references, or \nullptr if
+    there is none.
+ */
+
+/*!
+    \fn void QRhiColorAttachment::setTexture(QRhiTexture *tex)
+
+    Sets the texture \a tex.
+
+    \note texture() and renderBuffer() cannot be both set (be non-null at the
+    same time).
+ */
+
+/*!
+    \fn QRhiRenderBuffer *QRhiColorAttachment::renderBuffer() const
+
+    \return the renderbuffer this attachment description references, or
+    \nullptr if there is none.
+
+    In practice associating a QRhiRenderBuffer with a QRhiColorAttachment makes
+    the most sense when setting up multisample rendering via a multisample
+    \l{QRhiRenderBuffer::Type}{color} renderbuffer that is then resolved into a
+    non-multisample texture at the end of the render pass.
+ */
+
+/*!
+    \fn void QRhiColorAttachment::setRenderBuffer(QRhiRenderBuffer *rb)
+
+    Sets the renderbuffer \a rb.
+
+    \note texture() and renderBuffer() cannot be both set (be non-null at the
+    same time).
+ */
+
+/*!
+    \fn int QRhiColorAttachment::layer() const
+    \return the layer index (cubemap face or array layer). 0 by default.
+ */
+
+/*!
+    \fn void QRhiColorAttachment::setLayer(int layer)
+    Sets the \a layer index.
+ */
+
+/*!
+    \fn int QRhiColorAttachment::level() const
+    \return the mip level. 0 by default.
+ */
+
+/*!
+    \fn void QRhiColorAttachment::setLevel(int level)
+    Sets the mip \a level.
+ */
+
+/*!
+    \fn QRhiTexture *QRhiColorAttachment::resolveTexture() const
+
+    \return the resolve texture this attachment description references, or
+    \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.
+ */
+
+/*!
+    \fn void QRhiColorAttachment::setResolveTexture(QRhiTexture *tex)
+    Sets the resolve texture \a tex.
+ */
+
+/*!
+    \fn int QRhiColorAttachment::resolveLayer() const
+    \return the currently set resolve texture layer. Defaults to 0.
+ */
+
+/*!
+    \fn void QRhiColorAttachment::setResolveLayer(int layer)
+    Sets the resolve texture \a layer to use.
+ */
+
+/*!
+    \fn int QRhiColorAttachment::resolveLevel() const
+    \return the currently set resolve texture mip level. Defaults to 0.
+ */
+
+/*!
+    \fn void QRhiColorAttachment::setResolveLevel(int level)
+    Sets the resolve texture mip \a level to use.
+ */
+
+/*!
     \class QRhiTextureRenderTargetDescription
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes the color and depth or depth/stencil attachments of a render target.
 
     A texture render target has zero or more textures as color attachments,
@@ -1678,10 +2307,78 @@ QRhiColorAttachment::QRhiColorAttachment(QRhiRenderBuffer *renderBuffer)
 
     \note depthStencilBuffer() and depthTexture() cannot be both set (cannot be
     non-null at the same time).
+
+    Let's look at some example usages in combination with
+    QRhiTextureRenderTarget.
+
+    Due to the constructors, the targeting a texture (and no depth/stencil
+    buffer) is simple:
+
+    \code
+        QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256), 1, QRhiTexture::RenderTarget);
+        texture->create();
+        QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture }));
+    \endcode
+
+    The following creates a texture render target that is set up to target mip
+    level #2 of a texture:
+
+    \code
+        QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget | QRhiTexture::MipMapped);
+        texture->create();
+        QRhiColorAttachment colorAtt(texture);
+        colorAtt.setLevel(2);
+        QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt });
+    \endcode
+
+    Another example, this time to render into a depth texture:
+
+    \code
+        QRhiTexture *shadowMap = rhi->newTexture(QRhiTexture::D32F, QSize(1024, 1024), 1, QRhiTexture::RenderTarget);
+        shadowMap->create();
+        QRhiTextureRenderTargetDescription rtDesc;
+        rtDesc.setDepthTexture(shadowMap);
+        QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);
+    \endcode
+
+    A very common case, having a texture as the color attachment and a
+    renderbuffer as depth/stencil to enable depth testing:
+
+    \code
+        QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1. QRhiTexture::RenderTarget);
+        texture->create();
+        QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512));
+        depthStencil->create();
+        QRhiTextureRenderTargetDescription rtDesc({ texture }, depthStencil);
+        QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget(rtDesc);
+    \endcode
+
+    Finally, to enable multisample rendering in a portable manner (so also
+    supporting OpenGL ES 3.0), using a QRhiRenderBuffer as the (multisample)
+    color buffer and then resolving into a regular (non-multisample) 2D
+    texture. To enable depth testing, a depth-stencil buffer, which also must
+    use the same sample count, is used as well:
+
+    \code
+        QRhiRenderBuffer *colorBuffer = rhi->newRenderBuffer(QRhiRenderBuffer::Color, QSize(512, 512), 4); // 4x MSAA
+        colorBuffer->create();
+        QRhiRenderBuffer *depthStencil = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(512, 512), 4);
+        depthStencil->create();
+        QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512), 1, QRhiTexture::RenderTarget);
+        texture->create();
+        QRhiColorAttachment colorAtt(colorBuffer);
+        colorAtt.setResolveTexture(texture);
+        QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ colorAtt, depthStencil });
+    \endcode
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
+    \sa QRhiColorAttachment, QRhiTextureRenderTarget
  */
 
 /*!
-    \fn QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription()
+    \fn QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription() = default
 
     Constructs an empty texture render target description.
  */
@@ -1723,9 +2420,72 @@ QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRh
 }
 
 /*!
+    \fn void QRhiTextureRenderTargetDescription::setColorAttachments(std::initializer_list<QRhiColorAttachment> list)
+    Sets the \a list of color attachments.
+ */
+
+/*!
+    \fn template<typename InputIterator> void QRhiTextureRenderTargetDescription::setColorAttachments(InputIterator first, InputIterator last)
+    Sets the list of color attachments via the iterators \a first and \a last.
+ */
+
+/*!
+    \fn const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cbeginColorAttachments() const
+    \return a const iterator pointing to the first item in the attachment list.
+ */
+
+/*!
+    \fn const QRhiColorAttachment *QRhiTextureRenderTargetDescription::cendColorAttachments() const
+    \return a const iterator pointing just after the last item in the attachment list.
+ */
+
+/*!
+    \fn const QRhiColorAttachment *QRhiTextureRenderTargetDescription::colorAttachmentAt(qsizetype index) const
+    \return the color attachment at the specified \a index.
+ */
+
+/*!
+    \fn qsizetype QRhiTextureRenderTargetDescription::colorAttachmentCount() const
+    \return the number of currently set color attachments.
+ */
+
+/*!
+    \fn QRhiRenderBuffer *QRhiTextureRenderTargetDescription::depthStencilBuffer() const
+    \return the renderbuffer used as depth-stencil buffer, or \nullptr if none was set.
+ */
+
+/*!
+    \fn void QRhiTextureRenderTargetDescription::setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer)
+
+    Sets the \a renderBuffer for depth-stencil. Not mandatory, e.g. when no
+    depth test/write or stencil-related features are used within any graphics
+    pipelines in any of the render passes for this render target, it can be
+    left set to \nullptr.
+
+    \note depthStencilBuffer() and depthTexture() cannot be both set (cannot be
+    non-null at the same time).
+ */
+
+/*!
+    \fn QRhiTexture *QRhiTextureRenderTargetDescription::depthTexture() const
+    \return the currently referenced depth texture, or \nullptr if none was set.
+ */
+
+/*!
+    \fn void QRhiTextureRenderTargetDescription::setDepthTexture(QRhiTexture *texture)
+
+    Sets the \a texture for depth-stencil. This is an alternative to
+    setDepthStencilBuffer(), where instead of a QRhiRenderBuffer a QRhiTexture
+    with a suitable type (e.g., QRhiTexture::D32F) is provided.
+
+    \note depthStencilBuffer() and depthTexture() cannot be both set (cannot be
+    non-null at the same time).
+ */
+
+/*!
     \class QRhiTextureSubresourceUploadDescription
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes the source for one mip level in a layer in a texture upload operation.
 
     The source content is specified either as a QImage or as a raw blob. The
@@ -1782,10 +2542,15 @@ QRhiTextureRenderTargetDescription::QRhiTextureRenderTargetDescription(const QRh
     in order to be portable across all backends) If this cannot be ensured, the
     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
+    for details.
+
+    \sa QRhiTextureUploadDescription
  */
 
 /*!
-    \fn QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription()
+    \fn QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription() = default
 
     Constructs an empty subresource description.
 
@@ -1833,12 +2598,108 @@ QRhiTextureSubresourceUploadDescription::QRhiTextureSubresourceUploadDescription
 }
 
 /*!
+    \fn QImage QRhiTextureSubresourceUploadDescription::image() const
+    \return the currently set QImage.
+ */
+
+/*!
+    \fn void QRhiTextureSubresourceUploadDescription::setImage(const QImage &image)
+
+    Sets \a image.
+
+    \note image() and data() cannot be both set at the same time.
+ */
+
+/*!
+    \fn QByteArray QRhiTextureSubresourceUploadDescription::data() const
+    \return the currently set raw pixel data.
+ */
+
+/*!
+    \fn void QRhiTextureSubresourceUploadDescription::setData(const QByteArray &data)
+
+    Sets \a data.
+
+    \note image() and data() cannot be both set at the same time.
+ */
+
+/*!
+    \fn quint32 QRhiTextureSubresourceUploadDescription::dataStride() const
+    \return the currently set data stride.
+ */
+
+/*!
+    \fn void QRhiTextureSubresourceUploadDescription::setDataStride(quint32 stride)
+
+    Sets the data \a stride in bytes. By default this is 0 and not always
+    relevant. When providing raw data(), and the stride is not specified via
+    setDataStride(), the stride (row pitch, row length in bytes) of the
+    provided data must be equal to \c{width * pixelSize} where \c pixelSize is
+    the number of bytes used for one pixel, and there must be no additional
+    padding between rows. Otherwise, if there is additional space between the
+    lines, set a non-zero \a stride. All this is applicable only when raw image
+    data is provided, and is not necessary when working QImage since that has
+    its own \l{QImage::bytesPerLine()}{stride} value.
+
+    \note Setting the stride via setDataStride() is only functional when
+    QRhi::ImageDataStride is reported as
+    \l{QRhi::isFeatureSupported()}{supported}.
+
+    \note When a QImage is given, the stride returned from
+    QImage::bytesPerLine() is taken into account automatically and therefore
+    there is no need to set the data stride manually.
+ */
+
+/*!
+    \fn QPoint QRhiTextureSubresourceUploadDescription::destinationTopLeft() const
+    \return the currently set destination top-left position. Defaults to (0, 0).
+ */
+
+/*!
+    \fn void QRhiTextureSubresourceUploadDescription::setDestinationTopLeft(const QPoint &p)
+    Sets the destination top-left position \a p.
+ */
+
+/*!
+    \fn QSize QRhiTextureSubresourceUploadDescription::sourceSize() const
+
+    \return the source size in pixels. Defaults to a default-constructed QSize,
+    which indicates the entire subresource.
+ */
+
+/*!
+    \fn void QRhiTextureSubresourceUploadDescription::setSourceSize(const QSize &size)
+
+    Sets the source \a size in pixels.
+
+    \note Setting sourceSize() or sourceTopLeft() may trigger a QImage copy
+    internally, depending on the format and the backend.
+ */
+
+/*!
+    \fn QPoint QRhiTextureSubresourceUploadDescription::sourceTopLeft() const
+    \return the currently set source top-left position. Defaults to (0, 0).
+ */
+
+/*!
+    \fn void QRhiTextureSubresourceUploadDescription::setSourceTopLeft(const QPoint &p)
+
+    Sets the source top-left position \a p.
+
+    \note Setting sourceSize() or sourceTopLeft() may trigger a QImage copy
+    internally, depending on the format and the backend.
+ */
+
+/*!
     \class QRhiTextureUploadEntry
-    \internal
     \inmodule QtGui
+    \since 6.6
 
     \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
+    for details.
  */
 
 /*!
@@ -1864,18 +2725,61 @@ QRhiTextureUploadEntry::QRhiTextureUploadEntry(int layer, int level,
 }
 
 /*!
+    \fn int QRhiTextureUploadEntry::layer() const
+    \return the currently set layer index (cubemap face, array layer). Defaults to 0.
+ */
+
+/*!
+    \fn void QRhiTextureUploadEntry::setLayer(int layer)
+    Sets the \a layer.
+ */
+
+/*!
+    \fn int QRhiTextureUploadEntry::level() const
+    \return the currently set mip level. Defaults to 0.
+ */
+
+/*!
+    \fn void QRhiTextureUploadEntry::setLevel(int level)
+    Sets the mip \a level.
+ */
+
+/*!
+    \fn QRhiTextureSubresourceUploadDescription QRhiTextureUploadEntry::description() const
+    \return the currently set subresource description.
+ */
+
+/*!
+    \fn void QRhiTextureUploadEntry::setDescription(const QRhiTextureSubresourceUploadDescription &desc)
+    Sets the subresource description \a desc.
+ */
+
+/*!
     \class QRhiTextureUploadDescription
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes a texture upload operation.
 
     Used with QRhiResourceUpdateBatch::uploadTexture(). That function has two
     variants: one taking a QImage and one taking a
     QRhiTextureUploadDescription. The former is a convenience version,
     internally creating a QRhiTextureUploadDescription with a single image
-    targeting level 0 for layer 0. However, when cubemaps, pre-generated mip
-    images, or compressed textures are involved, applications will have to work
-    directly with this class instead.
+    targeting level 0 for layer 0.
+
+    An example of the the common, simple case of wanting to upload the contents
+    of a QImage to a QRhiTexture with a matching pixel size:
+
+    \code
+        QImage image(256, 256, QImage::Format_RGBA8888);
+        image.fill(Qt::green); // or could use a QPainter targeting image
+        QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(256, 256));
+        texture->create();
+        QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
+        u->uploadTexture(texture, image);
+    \endcode
+
+    When cubemaps, pre-generated mip images, compressed textures, or partial
+    uploads are involved, applications will have to use this class instead.
 
     QRhiTextureUploadDescription also enables specifying batched uploads, which
     are useful for example when generating an atlas or glyph cache texture:
@@ -1891,10 +2795,10 @@ QRhiTextureUploadEntry::QRhiTextureUploadEntry(int layer, int level,
 
     For example, specifying the faces of a cubemap could look like the following:
 
-    \badcode
+    \code
         QImage faces[6];
-        ...
-        QList<QRhiTextureUploadEntry> entries;
+        // ...
+        QVarLengthArray<QRhiTextureUploadEntry, 6> entries;
         for (int i = 0; i < 6; ++i)
           entries.append(QRhiTextureUploadEntry(i, 0, faces[i]));
         QRhiTextureUploadDescription desc;
@@ -1904,7 +2808,7 @@ QRhiTextureUploadEntry::QRhiTextureUploadEntry(int layer, int level,
 
     Another example that specifies mip images for a compressed texture:
 
-    \badcode
+    \code
         QList<QRhiTextureUploadEntry> entries;
         const int mipCount = rhi->mipLevelsForSize(compressedTexture->pixelSize());
         for (int level = 0; level < mipCount; ++level) {
@@ -1919,7 +2823,7 @@ QRhiTextureUploadEntry::QRhiTextureUploadEntry(int layer, int level,
     With partial uploads targeting the same subresource, it is recommended to
     batch them into a single upload request, whenever possible:
 
-    \badcode
+    \code
       QRhiTextureSubresourceUploadDescription subresDesc(image);
       subresDesc.setSourceSize(QSize(10, 10));
       subResDesc.setDestinationTopLeft(QPoint(50, 40));
@@ -1933,6 +2837,11 @@ QRhiTextureUploadEntry::QRhiTextureUploadEntry(int layer, int level,
       QRhiTextureUploadDescription desc({ entry, entry2});
       resourceUpdates->uploadTexture(texture, desc);
     \endcode
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
+    \sa QRhiResourceUpdateBatch
  */
 
 /*!
@@ -1965,9 +2874,39 @@ QRhiTextureUploadDescription::QRhiTextureUploadDescription(std::initializer_list
 }
 
 /*!
+    \fn void QRhiTextureUploadDescription::setEntries(std::initializer_list<QRhiTextureUploadEntry> list)
+    Sets the \a list of entries.
+ */
+
+/*!
+    \fn template<typename InputIterator> void QRhiTextureUploadDescription::setEntries(InputIterator first, InputIterator last)
+    Sets the list of entries using the iterators \a first and \a last.
+ */
+
+/*!
+    \fn const QRhiTextureUploadEntry *QRhiTextureUploadDescription::cbeginEntries() const
+    \return a const iterator pointing to the first item in the entry list.
+ */
+
+/*!
+    \fn const QRhiTextureUploadEntry *QRhiTextureUploadDescription::cendEntries() const
+    \return a const iterator pointing just after the last item in the entry list.
+ */
+
+/*!
+    \fn const QRhiTextureUploadEntry *QRhiTextureUploadDescription::entryAt(qsizetype index) const
+    \return the entry at \a index.
+ */
+
+/*!
+    \fn qsizetype QRhiTextureUploadDescription::entryCount() const
+    \return the number of entries.
+ */
+
+/*!
     \class QRhiTextureCopyDescription
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes a texture-to-texture copy operation.
 
     An empty pixelSize() indicates that the entire subresource is to be copied.
@@ -1987,6 +2926,9 @@ QRhiTextureUploadDescription::QRhiTextureUploadDescription(std::initializer_list
     copied at a time. The source and destination layer and mip level indices can
     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
+    for details.
  */
 
 /*!
@@ -1996,9 +2938,83 @@ QRhiTextureUploadDescription::QRhiTextureUploadDescription(std::initializer_list
  */
 
 /*!
+    \fn QSize QRhiTextureCopyDescription::pixelSize() const
+    \return the size of the region to copy.
+
+    \note An empty pixelSize() indicates that the entire subresource is to be
+    copied. A default constructed copy description therefore leads to copying
+    the entire subresource at level 0 of layer 0.
+ */
+
+/*!
+    \fn void QRhiTextureCopyDescription::setPixelSize(const QSize &sz)
+    Sets the size of the region to copy to \a sz.
+ */
+
+/*!
+    \fn int QRhiTextureCopyDescription::sourceLayer() const
+    \return the source array layer (cubemap face or array layer index). Defaults to 0.
+ */
+
+/*!
+    \fn void QRhiTextureCopyDescription::setSourceLayer(int layer)
+    Sets the source array \a layer.
+ */
+
+/*!
+    \fn int QRhiTextureCopyDescription::sourceLevel() const
+    \return the source mip level. Defaults to 0.
+ */
+
+/*!
+    \fn void QRhiTextureCopyDescription::setSourceLevel(int level)
+    Sets the source mip \a level.
+ */
+
+/*!
+    \fn QPoint QRhiTextureCopyDescription::sourceTopLeft() const
+    \return the source top-left position (in pixels). Defaults to (0, 0).
+ */
+
+/*!
+    \fn void QRhiTextureCopyDescription::setSourceTopLeft(const QPoint &p)
+    Sets the source top-left position to \a p.
+ */
+
+/*!
+    \fn int QRhiTextureCopyDescription::destinationLayer() const
+    \return the destination array layer (cubemap face or array layer index). Default to 0.
+ */
+
+/*!
+    \fn void QRhiTextureCopyDescription::setDestinationLayer(int layer)
+    Sets the destination array \a layer.
+ */
+
+/*!
+    \fn int QRhiTextureCopyDescription::destinationLevel() const
+    \return the destionation mip level. Defaults to 0.
+ */
+
+/*!
+    \fn void QRhiTextureCopyDescription::setDestinationLevel(int level)
+    Sets the destination mip \a level.
+ */
+
+/*!
+    \fn QPoint QRhiTextureCopyDescription::destinationTopLeft() const
+    \return the destionation top-left position in pixels. Defaults to (0, 0).
+ */
+
+/*!
+    \fn void QRhiTextureCopyDescription::setDestinationTopLeft(const QPoint &p)
+    Sets the destination top-left position \a p.
+ */
+
+/*!
     \class QRhiReadbackDescription
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes a readback (reading back texture contents from possibly GPU-only memory) operation.
 
     The source of the readback operation is either a QRhiTexture or the
@@ -2016,10 +3032,13 @@ 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
+    for details.
  */
 
 /*!
-    \fn QRhiReadbackDescription::QRhiReadbackDescription()
+    \fn QRhiReadbackDescription::QRhiReadbackDescription() = default
 
     Constructs an empty texture readback description.
 
@@ -2043,32 +3062,140 @@ QRhiReadbackDescription::QRhiReadbackDescription(QRhiTexture *texture)
 }
 
 /*!
+    \fn QRhiTexture *QRhiReadbackDescription::texture() const
+
+    \return the QRhiTexture that is read back. Can be left set to \nullptr
+    which indicates that the backbuffer of the current swapchain is to be used
+    instead.
+ */
+
+/*!
+    \fn void QRhiReadbackDescription::setTexture(QRhiTexture *tex)
+
+    Sets the texture \a tex as the source of the readback operation.
+
+    Setting \nullptr is valid too, in which case the current swapchain's
+    current backbuffer is used. (but then the readback cannot be issued in a
+    non-swapchain-based frame)
+
+    \note Multisample textures cannot be read back. Readbacks are supported for
+    multisample swapchain buffers however.
+
+    \note Textures used in readbacks must be created with
+    QRhiTexture::UsedAsTransferSource.
+
+    \note Swapchains used in readbacks must be created with
+    QRhiSwapChain::UsedAsTransferSource.
+ */
+
+/*!
+    \fn int QRhiReadbackDescription::layer() const
+
+    \return the currently set array layer (cubemap face, array index). Defaults to 0.
+
+    Applicable only when the source of the readback is a QRhiTexture.
+ */
+
+/*!
+    \fn void QRhiReadbackDescription::setLayer(int layer)
+    Sets the array \a layer to read back.
+ */
+
+/*!
+    \fn int QRhiReadbackDescription::level() const
+
+    \return the currently set mip level. Defaults to 0.
+
+    Applicable only when the source of the readback is a QRhiTexture.
+ */
+
+/*!
+    \fn void QRhiReadbackDescription::setLevel(int level)
+    Sets the mip \a level to read back.
+ */
+
+/*!
     \class QRhiReadbackResult
-    \internal
     \inmodule QtGui
-    \brief Describes the results of a potentially asynchronous readback operation.
+    \since 6.6
+    \brief Describes the results of a potentially asynchronous buffer or texture readback operation.
 
     When \l completed is set, the function is invoked when the \l data is
     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
+    for details.
  */
 
 /*!
+    \variable QRhiReadbackResult::completed
+
+    Callback that is invoked upon completion, on the thread the QRhi operates
+    on. Can be left set to \nullptr, in which case no callback is invoked.
+ */
+
+/*!
+    \variable QRhiReadbackResult::format
+
+    Valid only for textures, the texture format.
+ */
+
+/*!
+    \variable QRhiReadbackResult::pixelSize
+
+    Valid only for textures, the size in pixels.
+ */
+
+/*!
+    \variable QRhiReadbackResult::data
+
+    The buffer or image data.
+
+    \sa QRhiResourceUpdateBatch::readBackTexture(), QRhiResourceUpdateBatch::readBackBuffer()
+ */
+
+
+/*!
     \class QRhiNativeHandles
-    \internal
     \inmodule QtGui
+    \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
+    for details.
  */
 
 /*!
     \class QRhiResource
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Base class for classes encapsulating native resource objects.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
-    \fn QRhiResource::Type QRhiResource::resourceType() const
+    \enum QRhiResource::Type
+    Specifies type of the resource.
+
+    \value Buffer
+    \value Texture
+    \value Sampler
+    \value RenderBuffer
+    \value RenderPassDescriptor
+    \value SwapChainRenderTarget
+    \value TextureRenderTarget
+    \value ShaderResourceBindings
+    \value GraphicsPipeline
+    \value SwapChain
+    \value ComputePipeline
+    \value CommandBuffer
+ */
+
+/*!
+    \fn virtual QRhiResource::Type QRhiResource::resourceType() const = 0
 
     \return the type of the resource.
  */
@@ -2100,7 +3227,7 @@ QRhiResource::~QRhiResource()
 }
 
 /*!
-    \fn void QRhiResource::destroy()
+    \fn virtual void QRhiResource::destroy() = 0
 
     Releases (or requests deferred releasing of) the underlying native graphics
     resources. Safe to call multiple times, subsequent invocations will be a
@@ -2114,7 +3241,7 @@ QRhiResource::~QRhiResource()
     released until the frame is submitted by QRhi::endFrame().
 
     The QRhiResource destructor also performs the same task, so calling this
-    function is not necessary before destroying a QRhiResource.
+    function is not necessary before deleting a QRhiResource.
 
     \sa deleteLater()
  */
@@ -2139,16 +3266,19 @@ QRhiResource::~QRhiResource()
     frame.
 
     The following example shows a convenient way of creating a throwaway buffer
-    that is only used in one frame and gets automatically released (both the
-    underlying native objects and the C++ QRhiBuffer object) in endFrame():
+    that is only used in one frame and gets automatically released in
+    endFrame(). (when it comes to the underlying native buffer(s), the usual
+    guarantee applies: the QRhi backend defers the releasing of those until it
+    is guaranteed that the frame in which the buffer is accessed by the GPU has
+    completed)
 
-    \badcode
+    \code
         rhi->beginFrame(swapchain);
-        buf = rhi->newBuffer(...);
+        QRhiBuffer *buf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, 256);
         buf->deleteLater(); // !
         u = rhi->nextResourceUpdateBatch();
         u->uploadStaticBuffer(buf, data);
-        ... // draw with buf
+        // ... draw with buf
         rhi->endFrame();
     \endcode
 
@@ -2173,7 +3303,7 @@ QByteArray QRhiResource::name() const
 /*!
     Sets a \a name for the object.
 
-    This has two uses: to get descriptive names for the native graphics
+    This allows getting descriptive names for the native graphics
     resources visible in graphics debugging tools, such as
     \l{https://renderdoc.org/}{RenderDoc} and
     \l{https://developer.apple.com/xcode/}{XCode}.
@@ -2219,9 +3349,129 @@ QRhi *QRhiResource::rhi() const
 
 /*!
     \class QRhiBuffer
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Vertex, index, or uniform (constant) buffer resource.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
+    A QRhiBuffer encapsulates zero, one, or more native buffer objects (such as
+    a \c VkBuffer or \c MTLBuffer). With some graphics APIs and backends
+    certain types of buffers may not use a native buffer object at all (e.g.
+    OpenGL if uniform buffer objects are not used), but this is transparent to
+    the user of the QRhiBuffer API. Similarly, the fact that some types of
+    buffers may use two or three native buffers underneath, in order to allow
+    efficient per-frame content update without stalling the GPU pipeline, is
+    mostly invisible to the applications and libraries.
+
+    A QRhiBuffer instance is always created by calling
+    \l{QRhi::newBuffer()}{the QRhi's newBuffer() function}. This creates no
+    native graphics resources. To do that, call create() after setting the
+    appropriate options, such as the type, usage flags, size, although in most cases these
+    are already set based on the arguments passed to
+    \l{QRhi::newBuffer()}{newBuffer()}.
+
+    \section2 Example usage
+
+    To create a uniform buffer for a shader where the GLSL uniform block
+    contains a single \c mat4 member, and update the contents:
+
+    \code
+        QRhiBuffer *ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 64);
+        if (!ubuf->create()) { error(); }
+        QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
+        QMatrix4x4 mvp;
+        // ... set up the modelview-projection matrix
+        batch->updateDynamicBuffer(ubuf, 0, 64, mvp.constData());
+        // ...
+        commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call
+    \endcode
+
+    An example of creating a buffer with vertex data:
+
+    \code
+        const float vertices[] = { -1.0f, -1.0f, 1.0f, -1.0f, 0.0f, 1.0f };
+        QRhiBuffer *vbuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertices));
+        if (!vbuf->create()) { error(); }
+        QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
+        batch->uploadStaticBuffer(vbuf, vertices);
+        // ...
+        commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call
+    \endcode
+
+    An index buffer:
+
+    \code
+        static const quint16 indices[] = { 0, 1, 2 };
+        QRhiBuffer *ibuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::IndexBuffer, sizeof(indices));
+        if (!ibuf->create()) { error(); }
+        QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
+        batch->uploadStaticBuffer(ibuf, indices);
+        // ...
+        commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call
+    \endcode
+
+    \section2 Common patterns
+
+    A call to create() destroys any existing native resources if create() was
+    successfully called before. If those native resources are still in use by
+    an in-flight frame (i.e., there's a chance they are still read by the GPU),
+    the destroying of those resources is deferred automatically. Thus a very
+    common and convenient pattern to safely increase the size of an already
+    initialized buffer is the following. In practice this drops and creates a
+    whole new set of native resources underneath, so it is not necessarily a
+    cheap operation, but is more convenient and still faster than the
+    alternatives, because by not destroying the \c buf object itself, all
+    references to it stay valid in other data structures (e.g., in any
+    QRhiShaderResourceBinding the QRhiBuffer is referenced from).
+
+    \code
+        if (buf->size() < newSize) {
+            buf->setSize(newSize);
+            if (!buf->create()) { error(); }
+        }
+        // continue using buf, fill it with new data
+    \endcode
+
+    When working with uniform buffers, it will sometimes be necessary to
+    combine data for multiple draw calls into a single buffer for efficiency
+    reasons. Be aware of the aligment requirements: with some graphics APIs
+    offsets for a uniform buffer must be aligned to 256 bytes. This applies
+    both to QRhiShaderResourceBinding and to the dynamic offsets passed to
+    \l{QRhiCommandBuffer::setShaderResources()}{setShaderResources()}. Use the
+    \l{QRhi::ubufAlignment()}{ubufAlignment()} and
+    \l{QRhi::ubufAligned()}{ubufAligned()} functions to create portable code.
+    As an example, the following is an outline for issuing multiple (\c N) draw
+    calls with the same pipeline and geometry, but with a different data in the
+    uniform buffers exposed at binding point 0. This assumes the buffer is
+    exposed via
+    \l{QRhiShaderResourceBinding::uniformBufferWithDynamicOffset()}{uniformBufferWithDynamicOffset()}
+    which allows passing a QRhiCommandBuffer::DynamicOffset list to
+    \l{QRhiCommandBuffer::setShaderResources()}{setShaderResources()}.
+
+    \code
+        const int N = 2;
+        const int UB_SIZE = 64 + 4; // assuming a uniform block with { mat4 matrix; float opacity; }
+        const int ONE_UBUF_SIZE = rhi->ubufAligned(UB_SIZE);
+        const int TOTAL_UBUF_SIZE = N * ONE_UBUF_SIZE;
+        QRhiBuffer *ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, TOTAL_UBUF_SIZE);
+        if (!ubuf->create()) { error(); }
+        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);
+        }
+        // ...
+        // beginPass(), set pipeline, etc., and then:
+        for (int i = 0; i < N; ++i) {
+            QRhiCommandBuffer::DynamicOffset dynOfs[] = { { 0, i * ONE_UBUF_SIZE } };
+            cb->setShaderResources(srb, 1, dynOfs);
+            cb->draw(36);
+        }
+    \endcode
+
+    \sa QRhiResourceUpdateBatch, QRhi, QRhiCommandBuffer
  */
 
 /*!
@@ -2257,14 +3507,14 @@ QRhi *QRhiResource::rhi() const
     Flag values to specify how the buffer is going to be used.
 
     \value VertexBuffer Vertex buffer. This allows the QRhiBuffer to be used in
-    \l{setVertexInput()}{QRhiCommandBuffer::setVertexInput()}.
+    \l{QRhiCommandBuffer::setVertexInput()}{setVertexInput()}.
 
     \value IndexBuffer Index buffer. This allows the QRhiBuffer to be used in
-    \l{setVertexInput()}{QRhiCommandBuffer::setVertexInput()}.
+    \l{QRhiCommandBuffer::setVertexInput()}{setVertexInput()}.
 
     \value UniformBuffer Uniform buffer (also called constant buffer). This
     allows the QRhiBuffer to be used in combination with
-    \l{UniformBuffer}{QRhiShaderResourceBinding::UniformBuffer}. When
+    \l{QRhiShaderResourceBinding::UniformBuffer}{UniformBuffer}. When
     \l{QRhi::NonDynamicUniformBuffers}{NonDynamicUniformBuffers} is reported as
     not supported, this usage can only be combined with the type Dynamic.
 
@@ -2278,20 +3528,6 @@ QRhi *QRhiResource::rhi() const
  */
 
 /*!
-    \fn void QRhiBuffer::setSize(int sz)
-
-    Sets the size of the buffer in bytes. The size is normally specified in
-    QRhi::newBuffer() so this function is only used when the size has to be
-    changed. As with other setters, the size only takes effect when calling
-    create(), and for already created buffers this involves releasing the previous
-    native resource and creating new ones under the hood.
-
-    Backends may choose to allocate buffers bigger than \a sz in order to
-    fulfill alignment requirements. This is hidden from the applications and
-    size() will always report the size requested in \a sz.
- */
-
-/*!
     \class QRhiBuffer::NativeBuffer
     \brief Contains information about the underlying native resources of a buffer.
  */
@@ -2343,7 +3579,7 @@ QRhiResource::Type QRhiBuffer::resourceType() const
 }
 
 /*!
-    \fn bool QRhiBuffer::create()
+    \fn virtual bool QRhiBuffer::create() = 0
 
     Creates the corresponding native graphics resources. If there are already
     resources present due to an earlier create() with no corresponding
@@ -2354,6 +3590,50 @@ QRhiResource::Type QRhiBuffer::resourceType() const
  */
 
 /*!
+    \fn QRhiBuffer::Type QRhiBuffer::type() const
+    \return the buffer type.
+ */
+
+/*!
+    \fn void QRhiBuffer::setType(Type t)
+    Sets the buffer's type to \a t.
+ */
+
+/*!
+    \fn QRhiBuffer::UsageFlags QRhiBuffer::usage() const
+    \return the buffer's usage flags.
+ */
+
+/*!
+    \fn void setUsage(UsageFlags u)
+    Sets the buffer's usage flags to \a u.
+ */
+
+/*!
+    \fn quint32 QRhiBuffer::size() const
+
+    \return the buffer's size in bytes.
+
+    This is always the value that was passed to setSize() or QRhi::newBuffer().
+    Internally, the native buffers may be bigger if that is required by the
+    underlying graphics API.
+ */
+
+/*!
+    \fn void QRhiBuffer::setSize(quint32 sz)
+
+    Sets the size of the buffer in bytes. The size is normally specified in
+    QRhi::newBuffer() so this function is only used when the size has to be
+    changed. As with other setters, the size only takes effect when calling
+    create(), and for already created buffers this involves releasing the previous
+    native resource and creating new ones under the hood.
+
+    Backends may choose to allocate buffers bigger than \a sz in order to
+    fulfill alignment requirements. This is hidden from the applications and
+    size() will always report the size requested in \a sz.
+ */
+
+/*!
     \return the underlying native resources for this buffer. The returned value
     will be empty if exposing the underlying native resources is not supported by
     the backend.
@@ -2441,18 +3721,18 @@ void QRhiBuffer::endFullDynamicBufferUpdateForCurrentFrame()
 
 /*!
     \class QRhiRenderBuffer
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Renderbuffer resource.
 
     Renderbuffers cannot be sampled or read but have some benefits over
     textures in some cases:
 
-    A DepthStencil renderbuffer may be lazily allocated and be backed by
+    A \l DepthStencil renderbuffer may be lazily allocated and be backed by
     transient memory with some APIs. On some platforms this may mean the
     depth/stencil buffer uses no physical backing at all.
 
-    Color renderbuffers are useful since QRhi::MultisampleRenderBuffer may be
+    \l Color renderbuffers are useful since QRhi::MultisampleRenderBuffer may be
     supported even when QRhi::MultisampleTexture is not.
 
     How the renderbuffer is implemented by a backend is not exposed to the
@@ -2466,6 +3746,9 @@ void QRhiBuffer::endFullDynamicBufferUpdateForCurrentFrame()
     QRhi provides automatic sizing behavior to match the color buffers, which
     means calling setPixelSize() and create() are not necessary for such
     renderbuffers.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
@@ -2477,6 +3760,21 @@ void QRhiBuffer::endFullDynamicBufferUpdateForCurrentFrame()
  */
 
 /*!
+    \struct QRhiRenderBuffer::NativeRenderBuffer
+    \brief Wraps a native renderbuffer object.
+ */
+
+/*!
+    \variable QRhiRenderBuffer::NativeRenderBuffer::object
+    \brief 64-bit integer containing the native object handle.
+
+    Used with QRhiRenderBuffer::createFrom().
+
+    With OpenGL the native handle is a GLuint value. \c object is expected to
+    be a valid OpenGL renderbuffer object ID.
+ */
+
+/*!
     \enum QRhiRenderBuffer::Flag
     Flag values for flags() and setFlags()
 
@@ -2513,7 +3811,7 @@ QRhiResource::Type QRhiRenderBuffer::resourceType() const
 }
 
 /*!
-    \fn bool QRhiRenderBuffer::create()
+    \fn virtual bool QRhiRenderBuffer::create() = 0
 
     Creates the corresponding native graphics resources. If there are already
     resources present due to an earlier create() with no corresponding
@@ -2562,16 +3860,121 @@ bool QRhiRenderBuffer::createFrom(NativeRenderBuffer src)
 }
 
 /*!
-    \fn QRhiTexture::Format QRhiRenderBuffer::backingFormat() const
+    \fn QRhiRenderBuffer::Type QRhiRenderBuffer::type() const
+    \return the renderbuffer type.
+ */
+
+/*!
+    \fn void QRhiRenderBuffer::setType(Type t)
+    Sets the type to \a t.
+ */
+
+/*!
+    \fn QSize QRhiRenderBuffer::pixelSize() const
+    \return the pixel size.
+ */
+
+/*!
+    \fn void QRhiRenderBuffer::setPixelSize(const QSize &sz)
+    Sets the size (in pixels) to \a sz.
+ */
+
+/*!
+    \fn int QRhiRenderBuffer::sampleCount() const
+    \return the sample count. 1 means no multisample antialiasing.
+ */
+
+/*!
+    \fn void QRhiRenderBuffer::setSampleCount(int s)
+    Sets the sample count to \a s.
+ */
+
+/*!
+    \fn QRhiRenderBuffer::Flags QRhiRenderBuffer::flags() const
+    \return the flags.
+ */
+
+/*!
+    \fn void QRhiRenderBuffer::setFlags(Flags f)
+    Sets the flags to \a f.
+ */
+
+/*!
+    \fn virtual QRhiTexture::Format QRhiRenderBuffer::backingFormat() const = 0
 
     \internal
  */
 
 /*!
     \class QRhiTexture
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Texture resource.
+
+    A QRhiTexture encapsulates a native texture object, such as a \c VkImage or
+    \c MTLTexture.
+
+    A QRhiTexture instance is always created by calling
+    \l{QRhi::newTexture()}{the QRhi's newTexture() function}. This creates no
+    native graphics resources. To do that, call create() after setting the
+    appropriate options, such as the format and size, although in most cases
+    these are already set based on the arguments passed to
+    \l{QRhi::newTexture()}{newTexture()}.
+
+    Setting the \l{QRhiTexture::Flags}{flags} correctly is essential, otherwise
+    various errors can occur depending on the underlying QRhi backend and
+    graphics API. For example, when a texture will be rendered into from a
+    render pass via QRhiTextureRenderTarget, the texture must be created with
+    the \l RenderTarget flag set. Similarly, when the texture is going to be
+    \l{QRhiResourceUpdateBatch::readBackTexture()}{read back}, the \l
+    UsedAsTransferSource flag must be set upfront. Mipmapped textures must have
+    the MipMapped flag set. And so on. It is not possible to change the flags
+    once create() has succeeded. To release the existing and create a new
+    native texture object with the changed settings, call the setters and call
+    create() again. This then might be a potentially expensive operation.
+
+    \section2 Example usage
+
+    To create a 2D texture with a size of 512x512 pixels and set its contents to all green:
+
+    \code
+        QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, QSize(512, 512));
+        if (!texture->create()) { error(); }
+        QRhiResourceUpdateBatch *batch = rhi->nextResourceUpdateBatch();
+        QImage image(512, 512, QImage::Format_RGBA8888);
+        image.fill(Qt::green);
+        batch->uploadTexture(texture, image);
+        // ...
+        commandBuffer->resourceUpdate(batch); // or, alternatively, pass 'batch' to a beginPass() call
+    \endcode
+
+    \section2 Common patterns
+
+    A call to create() destroys any existing native resources if create() was
+    successfully called before. If those native resources are still in use by
+    an in-flight frame (i.e., there's a chance they are still read by the GPU),
+    the destroying of those resources is deferred automatically. Thus a very
+    common and convenient pattern to safely change the size of an already
+    existing texture is the following. In practice this drops and creates a
+    whole new native texture resource underneath, so it is not necessarily a
+    cheap operation, but is more convenient and still faster than the
+    alternatives, because by not destroying the \c texture object itself, all
+    references to it stay valid in other data structures (e.g., in any
+    QShaderResourceBinding the QRhiTexture is referenced from).
+
+    \code
+        // determine newSize, e.g. based on the swapchain's output size or other factors
+        if (texture->pixelSize() != newSize) {
+            texture->setPixelSize(newSize);
+            if (!texture->create()) { error(); }
+        }
+        // continue using texture, fill it with new data
+    \endcode
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
+    \sa QRhiResourceUpdateBatch, QRhi, QRhiTextureRenderTarget
  */
 
 /*!
@@ -2725,7 +4128,7 @@ bool QRhiRenderBuffer::createFrom(NativeRenderBuffer src)
  */
 
 /*!
-    \class QRhiTexture::NativeTexture
+    \struct QRhiTexture::NativeTexture
     \brief Contains information about the underlying native resources of a texture.
  */
 
@@ -2766,7 +4169,7 @@ QRhiResource::Type QRhiTexture::resourceType() const
 }
 
 /*!
-    \fn bool QRhiTexture::create()
+    \fn virtual bool QRhiTexture::create() = 0
 
     Creates the corresponding native graphics resources. If there are already
     resources present due to an earlier create() with no corresponding
@@ -2789,13 +4192,16 @@ QRhiTexture::NativeTexture QRhiTexture::nativeTexture()
 }
 
 /*!
-    Similar to create() except that no new native textures are created. Instead,
-    the native texture resources specified by \a src is used.
+    Similar to create(), except that no new native textures are created.
+    Instead, the native texture resources specified by \a src is used.
 
     This allows importing an existing native texture object (which must belong
     to the same device or sharing context, depending on the graphics API) from
     an external graphics engine.
 
+    \return true if the specified existing native texture object has been
+    successfully wrapped as a non-owning QRhiTexture.
+
     \note format(), pixelSize(), sampleCount(), and flags() must still be set
     correctly. Passing incorrect sizes and other values to QRhi::newTexture()
     and then following it with a createFrom() expecting that the native texture
@@ -2848,10 +4254,115 @@ void QRhiTexture::setNativeLayout(int layout)
 }
 
 /*!
+    \fn QRhiTexture::Format QRhiTexture::format() const
+    \return the texture format.
+ */
+
+/*!
+    \fn void QRhiTexture::setFormat(QRhiTexture::Format fmt)
+
+    Sets the requested texture format to \a fmt.
+
+    \note The value set is only taken into account upon the next call to
+    create(), i.e. when the underlying graphics resource are (re)created.
+    Setting a new value is futile otherwise and must be avoided since it can
+    lead to inconsistent state.
+ */
+
+/*!
+    \fn QSize QRhiTexture::pixelSize() const
+    \return the size in pixels.
+ */
+
+/*!
+    \fn void QRhiTexture::setPixelSize(const QSize &sz)
+
+    Sets the texture size, specified in pixels, to \a sz.
+
+    \note The value set is only taken into account upon the next call to
+    create(), i.e. when the underlying graphics resource are (re)created.
+    Setting a new value is futile otherwise and must be avoided since it can
+    lead to inconsistent state. The same applies to all other setters as well.
+ */
+
+/*!
+    \fn int QRhiTexture::depth() const
+    \return the depth for 3D textures.
+ */
+
+/*!
+    \fn void QRhiTexture::setDepth(int depth)
+    Sets the \a depth for a 3D texture.
+ */
+
+/*!
+    \fn int QRhiTexture::arraySize() const
+    \return the texture array size.
+ */
+
+/*!
+    \fn void QRhiTexture::setArraySize(int arraySize)
+    Sets the texture \a arraySize.
+ */
+
+/*!
+    \fn int QRhiTexture::arrayRangeStart() const
+
+    \return the first array layer when setArrayRange() was called.
+
+    \sa setArrayRange()
+ */
+
+/*!
+    \fn int QRhiTexture::arrayRangeLength() const
+
+    \return the exposed array range size when setArrayRange() was called.
+
+    \sa setArrayRange()
+*/
+
+/*!
+    \fn void QRhiTexture::setArrayRange(int startIndex, int count)
+
+    Normally all array layers are exposed and it is up to the shader to select
+    the layer via the third coordinate passed to the \c{texture()} GLSL
+    function when sampling the \c sampler2DArray. When QRhi::TextureArrayRange
+    is reported as supported, calling setArrayRange() before create() or
+    createFrom() requests selecting only the specified range, \a count elements
+    starting from \a startIndex. The shader logic can then be written with this
+    in mind.
+
+    \sa QRhi::TextureArrayRange
+ */
+
+/*!
+    \fn Flags QRhiTexture::flags() const
+    \return the texture flags.
+ */
+
+/*!
+    \fn void QRhiTexture::setFlags(Flags f)
+    Sets the texture flags to \a f.
+ */
+
+/*!
+    \fn int QRhiTexture::sampleCount() const
+    \return the sample count. 1 means no multisample antialiasing.
+ */
+
+/*!
+    \fn void QRhiTexture::setSampleCount(int s)
+    Sets the sample count to \a s.
+ */
+
+/*!
     \class QRhiSampler
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Sampler resource.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
@@ -2908,14 +4419,91 @@ QRhiResource::Type QRhiSampler::resourceType() const
 }
 
 /*!
+    \fn QRhiSampler::Filter QRhiSampler::magFilter() const
+    \return the magnification filter mode.
+ */
+
+/*!
+    \fn void QRhiSampler::setMagFilter(Filter f)
+    Sets the magnification filter mode to \a f.
+ */
+
+/*!
+    \fn QRhiSampler::Filter QRhiSampler::minFilter() const
+    \return the minification filter mode.
+ */
+
+/*!
+    \fn void QRhiSampler::setMinFilter(Filter f)
+    Sets the minification filter mode to \a f.
+ */
+
+/*!
+    \fn QRhiSampler::Filter QRhiSampler::mipmapMode() const
+    \return the mipmap filter mode.
+ */
+
+/*!
+    \fn void QRhiSampler::setMipmapMode(Filter f)
+
+    Sets the mipmap filter mode to \a f.
+
+    Leave this set to None when the texture has no mip levels, or when the mip
+    levels are not to be taken into account.
+ */
+
+/*!
+    \fn QRhiSampler::AddressMode QRhiSampler::addressU() const
+    \return the horizontal wrap mode.
+ */
+
+/*!
+    \fn void QRhiSampler::setAddressU(AddressMode mode)
+    Sets the horizontal wrap \a mode.
+ */
+
+/*!
+    \fn QRhiSampler::AddressMode QRhiSampler::addressV() const
+    \return the vertical wrap mode.
+ */
+
+/*!
+    \fn void QRhiSampler::setAddressV(AddressMode mode)
+    Sets the vertical wrap \a mode.
+ */
+
+/*!
+    \fn QRhiSampler::AddressMode QRhiSampler::addressW() const
+    \return the depth wrap mode.
+ */
+
+/*!
+    \fn void QRhiSampler::setAddressW(AddressMode mode)
+    Sets the depth wrap \a mode.
+ */
+
+/*!
+    \fn QRhiSampler::CompareOp QRhiSampler::textureCompareOp() const
+    \return the texture comparison function.
+ */
+
+/*!
+    \fn void QRhiSampler::setTextureCompareOp(CompareOp op)
+    Sets the texture comparison function \a op.
+ */
+
+/*!
     \class QRhiRenderPassDescriptor
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Render pass resource.
 
     A render pass, if such a concept exists in the underlying graphics API, is
     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
+    for details.
  */
 
 /*!
@@ -2935,7 +4523,7 @@ QRhiResource::Type QRhiRenderPassDescriptor::resourceType() const
 }
 
 /*!
-    \fn bool QRhiRenderPassDescriptor::isCompatible(const QRhiRenderPassDescriptor *other) const
+    \fn virtual bool QRhiRenderPassDescriptor::isCompatible(const QRhiRenderPassDescriptor *other) const = 0
 
     \return true if the \a other QRhiRenderPassDescriptor is compatible with
     this one, meaning \c this and \a other can be used interchangebly in
@@ -2970,7 +4558,7 @@ QRhiResource::Type QRhiRenderPassDescriptor::resourceType() const
  */
 
 /*!
-    \fn QRhiRenderPassDescriptor *QRhiRenderPassDescriptor::newCompatibleRenderPassDescriptor() const
+    \fn virtual QRhiRenderPassDescriptor *QRhiRenderPassDescriptor::newCompatibleRenderPassDescriptor() const = 0
 
     \return a new QRhiRenderPassDescriptor that is
     \l{isCompatible()}{compatible} with this one.
@@ -2991,7 +4579,7 @@ QRhiResource::Type QRhiRenderPassDescriptor::resourceType() const
  */
 
 /*!
-    \fn QVector<quint32> QRhiRenderPassDescriptor::serializedFormat() const
+    \fn virtual QVector<quint32> QRhiRenderPassDescriptor::serializedFormat() const = 0
 
     \return a vector of integers containing an opaque blob describing the data
     relevant for \l{isCompatible()}{compatibility}.
@@ -3022,10 +4610,20 @@ const QRhiNativeHandles *QRhiRenderPassDescriptor::nativeHandles()
 
 /*!
     \class QRhiRenderTarget
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Represents an onscreen (swapchain) or offscreen (texture) render target.
 
+    Applications do not create an instance of this class directly. Rather, it
+    is the subclass QRhiTextureRenderTarget that is instantiable by clients of
+    the API via \l{QRhi::newTextureRenderTarget()}{newTextureRenderTarget()}.
+    The other subclass is QRhiSwapChainRenderTarget, which is the type
+    QRhiSwapChain returns when calling
+    \l{QRhiSwapChain::currentFrameRenderTarget()}{currentFrameRenderTarget()}.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     \sa QRhiSwapChainRenderTarget, QRhiTextureRenderTarget
  */
 
@@ -3038,7 +4636,7 @@ QRhiRenderTarget::QRhiRenderTarget(QRhiImplementation *rhi)
 }
 
 /*!
-    \fn QSize QRhiRenderTarget::pixelSize() const
+    \fn virtual QSize QRhiRenderTarget::pixelSize() const = 0
 
     \return the size in pixels.
 
@@ -3056,7 +4654,7 @@ QRhiRenderTarget::QRhiRenderTarget(QRhiImplementation *rhi)
  */
 
 /*!
-    \fn float QRhiRenderTarget::devicePixelRatio() const
+    \fn virtual float QRhiRenderTarget::devicePixelRatio() const = 0
 
     \return the device pixel ratio. For QRhiTextureRenderTarget this is always
     1. For targets retrieved from a QRhiSwapChain the value reflects the
@@ -3065,6 +4663,25 @@ QRhiRenderTarget::QRhiRenderTarget(QRhiImplementation *rhi)
  */
 
 /*!
+    \fn virtual int QRhiRenderTarget::sampleCount() const = 0
+
+    \return the sample count or 1 if multisample antialiasing is not relevant for
+    this render target.
+ */
+
+/*!
+    \fn QRhiRenderPassDescriptor *QRhiRenderTarget::renderPassDescriptor() const
+
+    \return the associated QRhiRenderPassDescriptor.
+ */
+
+/*!
+    \fn void QRhiRenderTarget::setRenderPassDescriptor(QRhiRenderPassDescriptor *desc)
+
+    Sets the QRhiRenderPassDescriptor \a desc for use with this render target.
+ */
+
+/*!
     \internal
  */
 QRhiSwapChainRenderTarget::QRhiSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain_)
@@ -3075,14 +4692,17 @@ QRhiSwapChainRenderTarget::QRhiSwapChainRenderTarget(QRhiImplementation *rhi, QR
 
 /*!
     \class QRhiSwapChainRenderTarget
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Swapchain render target resource.
 
     When targeting the color buffers of a swapchain, active render target is a
     QRhiSwapChainRenderTarget. This is what
     QRhiSwapChain::currentFrameRenderTarget() returns.
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     \sa QRhiSwapChain
  */
 
@@ -3102,8 +4722,8 @@ QRhiResource::Type QRhiSwapChainRenderTarget::resourceType() const
 
 /*!
     \class QRhiTextureRenderTarget
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Texture render target resource.
 
     A texture render target allows rendering into one or more textures,
@@ -3119,15 +4739,18 @@ QRhiResource::Type QRhiSwapChainRenderTarget::resourceType() const
     The simplest example of creating a render target with a texture as its
     single color attachment:
 
-    \badcode
-        texture = rhi->newTexture(QRhiTexture::RGBA8, size, 1, QRhiTexture::RenderTarget);
+    \code
+        QRhiTexture *texture = rhi->newTexture(QRhiTexture::RGBA8, size, 1, QRhiTexture::RenderTarget);
         texture->create();
-        rt = rhi->newTextureRenderTarget({ texture });
+        QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ texture });
         rp = rt->newCompatibleRenderPassDescriptor();
         rt->setRenderPassDescriptor(rt);
         rt->create();
         // rt can now be used with beginPass()
     \endcode
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
@@ -3173,7 +4796,7 @@ QRhiResource::Type QRhiTextureRenderTarget::resourceType() const
 }
 
 /*!
-    \fn QRhiRenderPassDescriptor *QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor()
+    \fn virtual QRhiRenderPassDescriptor *QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor() = 0
 
     \return a new QRhiRenderPassDescriptor that is compatible with this render
     target.
@@ -3183,7 +4806,8 @@ QRhiResource::Type QRhiTextureRenderTarget::resourceType() const
     QRhiGraphicsPipeline::setRenderPassDescriptor(). A render pass descriptor
     describes the attachments (color, depth/stencil) and the load/store
     behavior that can be affected by flags(). A QRhiGraphicsPipeline can only
-    be used in combination with a render target that has the same
+    be used in combination with a render target that has a
+    \l{QRhiRenderPassDescriptor::isCompatible()}{compatible}
     QRhiRenderPassDescriptor set.
 
     Two QRhiTextureRenderTarget instances can share the same render pass
@@ -3199,7 +4823,7 @@ QRhiResource::Type QRhiTextureRenderTarget::resourceType() const
  */
 
 /*!
-    \fn bool QRhiTextureRenderTarget::create()
+    \fn virtual bool QRhiTextureRenderTarget::create() = 0
 
     Creates the corresponding native graphics resources. If there are already
     resources present due to an earlier create() with no corresponding
@@ -3223,9 +4847,29 @@ QRhiResource::Type QRhiTextureRenderTarget::resourceType() const
  */
 
 /*!
+    \fn QRhiTextureRenderTargetDescription QRhiTextureRenderTarget::description() const
+    \return the render target description.
+ */
+
+/*!
+    \fn void QRhiTextureRenderTarget::setDescription(const QRhiTextureRenderTargetDescription &desc)
+    Sets the render target description \a desc.
+ */
+
+/*!
+    \fn QRhiTextureRenderTarget::Flags QRhiTextureRenderTarget::flags() const
+    \return the currently set flags.
+ */
+
+/*!
+    \fn void QRhiTextureRenderTarget::setFlags(Flags f)
+    Sets the flags to \a f.
+ */
+
+/*!
     \class QRhiShaderResourceBindings
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Encapsulates resources for making buffer, texture, sampler resources visible to shaders.
 
     A QRhiShaderResourceBindings is a collection of QRhiShaderResourceBinding
@@ -3246,19 +4890,19 @@ QRhiResource::Type QRhiTextureRenderTarget::resourceType() const
     QRhiShaderResourceBindings could be created and then passed to
     QRhiGraphicsPipeline::setShaderResourceBindings():
 
-    \badcode
-        srb = rhi->newShaderResourceBindings();
+    \code
+        QRhiShaderResourceBindings *srb = rhi->newShaderResourceBindings();
         srb->setBindings({
             QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage, ubuf),
             QRhiShaderResourceBinding::sampledTexture(1, QRhiShaderResourceBinding::FragmentStage, texture, sampler)
         });
         srb->create();
-        ...
-        ps = rhi->newGraphicsPipeline();
-        ...
+        // ...
+        QRhiGraphicsPipeline *ps = rhi->newGraphicsPipeline();
+        // ...
         ps->setShaderResourceBindings(srb);
         ps->create();
-        ...
+        // ...
         cb->setGraphicsPipeline(ps);
         cb->setShaderResources(); // binds srb
     \endcode
@@ -3277,14 +4921,17 @@ QRhiResource::Type QRhiTextureRenderTarget::resourceType() const
     srb argument. As long as the layouts (so the number of bindings and the
     binding points) match between two QRhiShaderResourceBindings, they can both
     be used with the same pipeline, assuming the pipeline was created with one of
-    them in the first place.
+    them in the first place. See isLayoutCompatible() for more details.
 
-    \badcode
-        srb2 = rhi->newShaderResourceBindings();
-        ...
+    \code
+        QRhiShaderResourceBindings *srb2 = rhi->newShaderResourceBindings();
+        // ...
         cb->setGraphicsPipeline(ps);
         cb->setShaderResources(srb2); // binds srb2
     \endcode
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
@@ -3350,7 +4997,7 @@ bool QRhiShaderResourceBindings::isLayoutCompatible(const QRhiShaderResourceBind
     \l{isLayoutCompatible()}{layout compatibility tests}.
 
     Given two objects \c srb1 and \c srb2, if the data returned from this
-    function is identical, then \c{srb1->isLayoutCompatible(srb2), and vice
+    function is identical, then \c{srb1->isLayoutCompatible(srb2)}, and vice
     versa hold true as well.
 
     \note The returned data is meant to be used for storing in memory and
@@ -3375,14 +5022,47 @@ void QRhiImplementation::updateLayoutDesc(QRhiShaderResourceBindings *srb)
 }
 
 /*!
+    \fn void QRhiShaderResourceBindings::setBindings(std::initializer_list<QRhiShaderResourceBinding> list)
+    Sets the \a list of bindings.
+ */
+
+/*!
+    \fn template<typename InputIterator> void QRhiShaderResourceBindings::setBindings(InputIterator first, InputIterator last)
+    Sets the list of bindings from the iterators \a first and \a last.
+ */
+
+/*!
+    \fn const QRhiShaderResourceBinding *QRhiShaderResourceBindings::cbeginBindings() const
+    \return a const iterator pointing to the first item in the binding list.
+ */
+
+/*!
+    \fn const QRhiShaderResourceBinding *QRhiShaderResourceBindings::cendBindings() const
+    \return a const iterator pointing just after the last item in the binding list.
+ */
+
+/*!
+    \fn const QRhiShaderResourceBinding *QRhiShaderResourceBindings::bindingAt(qsizetype index) const
+    \return the binding at the specified \a index.
+ */
+
+/*!
+    \fn qsizetype QRhiShaderResourceBindings::bindingCount() const
+    \return the number of bindings.
+ */
+
+/*!
     \class QRhiShaderResourceBinding
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Describes the shader resource for a single binding point.
 
     A QRhiShaderResourceBinding cannot be constructed directly. Instead, use the
     static functions such as uniformBuffer() or sampledTexture() to get an
     instance.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
@@ -3439,7 +5119,7 @@ void QRhiImplementation::updateLayoutDesc(QRhiShaderResourceBindings *srb)
 
     For example, \c a and \c b below are not equal, but are compatible layout-wise:
 
-    \badcode
+    \code
         auto a = QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, buffer);
         auto b = QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, someOtherBuffer, 256);
     \endcode
@@ -4313,18 +5993,44 @@ QDebug operator<<(QDebug dbg, const QRhiShaderResourceBindings &srb)
 
 /*!
     \class QRhiGraphicsPipeline
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Graphics pipeline state resource.
 
+    Represents a graphics pipeline. What exactly this map to in the underlying
+    native graphics API, varies. Where there is a concept of pipeline objects,
+    for example with Vulkan, the QRhi backend will create such an object upon
+    calling create(). Elsewhere, for example with OpenGL, the
+    QRhiGraphicsPipeline may merely collect the various state, and create()'s
+    main task is to set up the corresponding shader program, but deferring
+    looking at any of the requested state to a later point.
+
+    As with all QRhiResource subclasses, the two-phased initialization pattern
+    applies: setting any values via the setters, for example setDepthTest(), is
+    only effective after calling create(). Avoid changing any values once the
+    QRhiGraphicsPipeline has been initialized via create(). To change some
+    state, set the new value and call create() again. However, that will
+    effectively release all underlying native resources and create new ones. As
+    a result, it may be a heavy, expensive operation. Rather, prefer creating
+    multiple pipelines with the different states, and
+    \l{QRhiCommandBuffer::setGraphicsPipeline()}{switch between them} when
+    recording the render pass.
+
     \note Setting the shader stages is mandatory. There must be at least one
     stage, and there must be a vertex stage.
 
     \note Setting the shader resource bindings is mandatory. The referenced
     QRhiShaderResourceBindings must already have create() called on it by the
     time create() is called. Associating with a QRhiShaderResourceBindings that
-    has no bindings is also valid, as long as no shader in any stage expects
-    any resources.
+    has no bindings is also valid, as long as no shader in any stage expects any
+    resources. Using a QRhiShaderResourceBindings object that does not specify
+    any actual resources (i.e., the buffers, textures, etc. for the binding
+    points are set to \nullptr) is valid as well, as long as a
+    \l{QRhiShaderResourceBindings::isLayoutCompatible()}{layout-compatible}
+    QRhiShaderResourceBindings, that specifies resources for all the bindings,
+    is going to be set via
+    \l{QRhiCommandBuffer::setShaderResources()}{setShaderResources()} when
+    recording the render pass.
 
     \note Setting the render pass descriptor is mandatory. To obtain a
     QRhiRenderPassDescriptor that can be passed to setRenderPassDescriptor(),
@@ -4337,10 +6043,49 @@ QDebug operator<<(QDebug dbg, const QRhiShaderResourceBindings &srb)
     render target's color and depth stencil attachments.
 
     \note The depth test, depth write, and stencil test are disabled by
-    default.
+    default. The face culling mode defaults to no culling.
 
     \note stencilReadMask() and stencilWriteMask() apply to both faces. They
     both default to 0xFF.
+
+    \section2 Example usage
+
+    All settings of a graphics pipeline have defaults which might be suitable
+    to many applications. Therefore a minimal example of creating a graphics
+    pipeline could be the following. This assumes that the vertex shader takes
+    a single \c{vec3 position} input at the input location 0. With the
+    QRhiShaderResourceBindings and QRhiRenderPassDescriptor objects, plus the
+    QShader collections for the vertex and fragment stages, a pipeline could be
+    created like this:
+
+    \code
+        QRhiShaderResourceBindings *srb;
+        QRhiRenderPassDescriptor *rpDesc;
+        QShader vs, fs;
+        // ...
+
+        QRhiVertexInputLayout inputLayout;
+        inputLayout.setBindings({ { 3 * sizeof(float) } });
+        inputLayout.setAttributes({ { 0, 0, QRhiVertexInputAttribute::Float3, 0 } });
+
+        QRhiGraphicsPipeline *ps = rhi->newGraphicsPipeline();
+        ps->setShaderStages({ { QRhiShaderStage::Vertex, vs }, { QRhiShaderStage::Fragment, fs } });
+        ps->setVertexInputLayout(inputLayout);
+        ps->setShaderResourceBindings(srb);
+        ps->setRenderPassDescriptor(rpDesc);
+        if (!ps->create()) { error(); }
+    \endcode
+
+    The above code creates a pipeline object that uses the defaults for many
+    settings and states. For example, it will use a \l Triangles topology, no
+    backface culling, blending is disabled but color write is enabled for all
+    four channels, depth test/write are disabled, stencil operations are
+    disabled.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
+    \sa QRhiCommandBuffer, QRhi
  */
 
 /*!
@@ -4509,21 +6254,85 @@ QDebug operator<<(QDebug dbg, const QRhiShaderResourceBindings &srb)
  */
 
 /*!
-    \class QRhiGraphicsPipeline::TargetBlend
-    \internal
+    \struct QRhiGraphicsPipeline::TargetBlend
     \inmodule QtGui
+    \since 6.6
     \brief Describes the blend state for one color attachment.
 
     Defaults to color write enabled, blending disabled. The blend values are
     set up for pre-multiplied alpha (One, OneMinusSrcAlpha, One,
-    OneMinusSrcAlpha) by default.
+    OneMinusSrcAlpha) by default. This means that to get the alpha blending
+    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
+    for details.
  */
 
 /*!
-    \class QRhiGraphicsPipeline::StencilOpState
-    \internal
+    \variable QRhiGraphicsPipeline::TargetBlend::colorWrite
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::TargetBlend::enable
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::TargetBlend::srcColor
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::TargetBlend::dstColor
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::TargetBlend::opColor
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::TargetBlend::srcAlpha
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::TargetBlend::dstAlpha
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::TargetBlend::opAlpha
+ */
+
+/*!
+    \struct QRhiGraphicsPipeline::StencilOpState
     \inmodule QtGui
+    \since 6.6
     \brief Describes the stencil operation state.
+
+    The default-constructed StencilOpState has the following set:
+    \list
+    \li failOp - \l Keep
+    \li depthFailOp - \l Keep
+    \li passOp - \l Keep
+    \li compareOp \l Always
+    \endlist
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::StencilOpState::failOp
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::StencilOpState::depthFailOp
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::StencilOpState::passOp
+ */
+
+/*!
+    \variable QRhiGraphicsPipeline::StencilOpState::compareOp
  */
 
 /*!
@@ -4543,7 +6352,7 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const
 }
 
 /*!
-    \fn bool QRhiGraphicsPipeline::create()
+    \fn virtual bool QRhiGraphicsPipeline::create() = 0
 
     Creates the corresponding native graphics resources. If there are already
     resources present due to an earlier create() with no corresponding
@@ -4551,23 +6360,132 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const
 
     \return \c true when successful, \c false when a graphics operation failed.
     Regardless of the return value, calling destroy() is always safe.
+
+    \note This may be, depending on the underlying graphics API, an expensive
+    operation, especially when shaders get compiled/optimized from source or
+    from an intermediate bytecode format to the GPU's own instruction set.
+    Where applicable, the QRhi backend automatically sets up the relevant
+    non-persistent facilities to accelerate this, for example the Vulkan
+    backend automatically creates a \c VkPipelineCache to improve data reuse
+    during the lifetime of the application.
+
+    \note Drivers may also employ various persistent (disk-based) caching
+    strategies for shader and pipeline data, which is hidden to and is outside
+    of Qt's control. In some cases, depending on the graphics API and the QRhi
+    backend, there are facilities within QRhi for manually managing such a
+    cache, allowing the retrieval of a serializable blob that can then be
+    reloaded in the future runs of the application to ensure faster pipeline
+    creation times. See QRhi::pipelineCacheData() and
+    QRhi::setPipelineCacheData() for details. Note also that when working with
+    a QRhi instance managed by a higher level Qt framework, such as Qt Quick,
+    it is possible that such disk-based caching is taken care of automatically,
+    for example QQuickWindow uses a disk-based pipeline cache by default (which
+    comes in addition to any driver-level caching).
+ */
+
+/*!
+    \fn QRhiGraphicsPipeline::Flags QRhiGraphicsPipeline::flags() const
+    \return the currently set flags.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setFlags(Flags f)
+    Sets the flags \a f.
+ */
+
+/*!
+    \fn QRhiGraphicsPipeline::Topology QRhiGraphicsPipeline::topology() const
+    \return the currently set primitive topology.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setTopology(Topology t)
+    Sets the primitive topology \a t.
+ */
+
+/*!
+    \fn QRhiGraphicsPipeline::CullMode QRhiGraphicsPipeline::cullMode() const
+    \return the currently set face culling mode.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setCullMode(CullMode mode)
+    Sets the specified face culling \a mode.
+ */
+
+/*!
+    \fn QRhiGraphicsPipeline::FrontFace QRhiGraphicsPipeline::frontFace() const
+    \return the currently set front face mode.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setFrontFace(FrontFace f)
+    Sets the front face mode \a f.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setTargetBlends(std::initializer_list<TargetBlend> list)
+
+    Sets the \a list of render target blend settings. This is a list because
+    when multiple render targets are used (i.e., a QRhiTextureRenderTarget with
+    more than one QRhiColorAttachment), there needs to be a TargetBlend
+    structure per render target (color attachment).
+
+    By default there is one default-constructed TargetBlend set.
+
+    \sa QRhi::MaxColorAttachments
+ */
+
+/*!
+    \fn template<typename InputIterator> void QRhiGraphicsPipeline::setTargetBlends(InputIterator first, InputIterator last)
+    Sets the list of render target blend settings from the iterators \a first and \a last.
+ */
+
+/*!
+    \fn const QRhiGraphicsPipeline::TargetBlend *QRhiGraphicsPipeline::cbeginTargetBlends() const
+    \return a const iterator pointing to the first item in the render target blend setting list.
+ */
+
+/*!
+    \fn const QRhiGraphicsPipeline::TargetBlend *QRhiGraphicsPipeline::cendTargetBlends() const
+    \return a const iterator pointing just after the last item in the render target blend setting list.
+ */
+
+/*!
+    \fn const QRhiGraphicsPipeline::TargetBlend *QRhiGraphicsPipeline::targetBlendAt(qsizetype index) const
+    \return the render target blend setting at the specified \a index.
+ */
+
+/*!
+    \fn qsizetype QRhiGraphicsPipeline::targetBlendCount() const
+    \return the number of render target blend settings.
+ */
+
+/*!
+    \fn bool QRhiGraphicsPipeline::hasDepthTest() const
+    \return true if depth testing is enabled.
  */
 
 /*!
     \fn void QRhiGraphicsPipeline::setDepthTest(bool enable)
 
-    Enables or disables depth testing. Both depth test and the writing out of
-    depth data are disabled by default.
+    Enables or disables depth testing based on \a enable. Both depth test and
+    the writing out of depth data are disabled by default.
 
     \sa setDepthWrite()
  */
 
 /*!
+    \fn bool QRhiGraphicsPipeline::hasDepthWrite() const
+    \return true if depth write is enabled.
+ */
+
+/*!
     \fn void QRhiGraphicsPipeline::setDepthWrite(bool enable)
 
-    Controls the writing out of depth data into the depth buffer. By default
-    this is disabled. Depth write is typically enabled together with the depth
-    test.
+    Controls the writing out of depth data into the depth buffer based on
+    \a enable. By default this is disabled. Depth write is typically enabled
+    together with the depth test.
 
     \note Enabling depth write without having depth testing enabled may not
     lead to the desired result, and should be avoided.
@@ -4576,9 +6494,210 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const
  */
 
 /*!
+    \fn QRhiGraphicsPipeline::CompareOp QRhiGraphicsPipeline::depthOp() const
+    \return the depth comparison function.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setDepthOp(CompareOp op)
+    Sets the depth comparison function \a op.
+ */
+
+/*!
+    \fn bool QRhiGraphicsPipeline::hasStencilTest() const
+    \return true if stencil testing is enabled.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setStencilTest(bool enable)
+    Enables or disables stencil tests based on \a enable.
+    By default this is disabled.
+ */
+
+/*!
+    \fn QRhiGraphicsPipeline::StencilOpState QRhiGraphicsPipeline::stencilFront() const
+    \return the current stencil test state for front faces.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setStencilFront(const StencilOpState &state)
+    Sets the stencil test \a state for front faces.
+ */
+
+/*!
+    \fn QRhiGraphicsPipeline::StencilOpState QRhiGraphicsPipeline::stencilBack() const
+    \return the current stencil test state for back faces.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setStencilBack(const StencilOpState &state)
+    Sets the stencil test \a state for back faces.
+ */
+
+/*!
+    \fn quint32 QRhiGraphicsPipeline::stencilReadMask() const
+    \return the currrent stencil read mask.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setStencilReadMask(quint32 mask)
+    Sets the stencil read \a mask. The default value is 0xFF.
+ */
+
+/*!
+    \fn quint32 QRhiGraphicsPipeline::stencilWriteMask() const
+    \return the current stencil write mask.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setStencilWriteMask(quint32 mask)
+    Sets the stencil write \a mask. The default value is 0xFF.
+ */
+
+/*!
+    \fn int QRhiGraphicsPipeline::sampleCount() const
+    \return the currently set sample count. 1 means no multisample antialiasing.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setSampleCount(int s)
+
+    Sets the sample count. Typical values for \a s are 1, 4, or 8. The pipeline
+    must always be compatible with the render target, i.e. the sample counts
+    must match.
+
+    \sa QRhi::supportedSampleCounts()
+ */
+
+/*!
+    \fn float QRhiGraphicsPipeline::lineWidth() const
+    \return the currently set line width. The default is 1.0f.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setLineWidth(float width)
+
+    Sets the line \a width. If the QRhi::WideLines feature is reported as
+    unsupported at runtime, values other than 1.0f are ignored.
+ */
+
+/*!
+    \fn int QRhiGraphicsPipeline::depthBias() const
+    \return the currently set depth bias.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setDepthBias(int bias)
+    Sets the depth \a bias. The default value is 0.
+ */
+
+/*!
+    \fn float QRhiGraphicsPipeline::slopeScaledDepthBias() const
+    \return the currently set slope scaled depth bias.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setSlopeScaledDepthBias(float bias)
+    Sets the slope scaled depth \a bias. The default value is 0.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setShaderStages(std::initializer_list<QRhiShaderStage> list)
+    Sets the \a list of shader stages.
+ */
+
+/*!
+    \fn template<typename InputIterator> void QRhiGraphicsPipeline::setShaderStages(InputIterator first, InputIterator last)
+    Sets the list of shader stages from the iterators \a first and \a last.
+ */
+
+/*!
+    \fn const QRhiShaderStage *QRhiGraphicsPipeline::cbeginShaderStages() const
+    \return a const iterator pointing to the first item in the shader stage list.
+ */
+
+/*!
+    \fn const QRhiShaderStage *QRhiGraphicsPipeline::cendShaderStages() const
+    \return a const iterator pointing just after the last item in the shader stage list.
+ */
+
+/*!
+    \fn const QRhiShaderStage *QRhiGraphicsPipeline::shaderStageAt(qsizetype index) const
+    \return the shader stage at the specified \a index.
+ */
+
+/*!
+    \fn qsizetype QRhiGraphicsPipeline::shaderStageCount() const
+    \return the number of shader stages in this pipeline.
+ */
+
+/*!
+    \fn QRhiVertexInputLayout QRhiGraphicsPipeline::vertexInputLayout() const
+    \return the currently set vertex input layout specification.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setVertexInputLayout(const QRhiVertexInputLayout &layout)
+    Specifies the vertex input \a layout.
+ */
+
+/*!
+    \fn QRhiShaderResourceBindings *QRhiGraphicsPipeline::shaderResourceBindings() const
+    \return the currently associated QRhiShaderResourceBindings object.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setShaderResourceBindings(QRhiShaderResourceBindings *srb)
+
+    Associates with \a srb describing the resource binding layout and the
+    resources (QRhiBuffer, QRhiTexture) themselves. The latter is optional,
+    because only the layout matters during pipeline creation. Therefore, the \a
+    srb passed in here can leave the actual buffer or texture objects
+    unspecified (\nullptr) as long as there is another,
+    \l{QRhiShaderResourceBindings::isLayoutCompatible()}{layout-compatible}
+    QRhiShaderResourceBindings bound via
+    \l{QRhiCommandBuffer::setShaderResources()}{setShaderResources()} before
+    recording the draw calls.
+ */
+
+/*!
+    \fn QRhiRenderPassDescriptor *QRhiGraphicsPipeline::renderPassDescriptor() const
+    \return the currently set QRhiRenderPassDescriptor.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setRenderPassDescriptor(QRhiRenderPassDescriptor *desc)
+    Associates with the specified QRhiRenderPassDescriptor \a desc.
+ */
+
+/*!
+    \fn int QRhiGraphicsPipeline::patchControlPointCount() const
+    \return the currently set patch control point count.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setPatchControlPointCount(int count)
+
+    Sets the number of patch control points to \a count. The default value is
+    3. This is used only when the topology is set to \l Patches.
+ */
+
+/*!
+    \fn QRhiGraphicsPipeline::PolygonMode QRhiGraphicsPipeline::polygonMode() const
+    \return the polygon mode.
+ */
+
+/*!
+    \fn void QRhiGraphicsPipeline::setPolygonMode(PolygonMode mode)
+    Sets the polygon \a mode. The default is Fill.
+
+    \sa QRhi::NonFillPolygonMode
+ */
+
+/*!
     \class QRhiSwapChain
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Swapchain resource.
 
     A swapchain enables presenting rendering results to a surface. A swapchain
@@ -4588,7 +6707,7 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const
     Below is a typical pattern for creating and managing a swapchain and some
     associated resources in order to render onto a QWindow:
 
-    \badcode
+    \code
       void init()
       {
           sc = rhi->newSwapChain();
@@ -4634,7 +6753,7 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const
     Releasing the swapchain must happen while the QWindow and the underlying
     native window is fully up and running. Building on the previous example:
 
-    \badcode
+    \code
         void releaseSwapChain()
         {
             if (hasSwapChain) {
@@ -4666,7 +6785,7 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const
     events. QExposeEvent is a loosely specified event that is sent whenever a
     window gets mapped, obscured, and resized, depending on the platform.
 
-    \badcode
+    \code
         void Window::exposeEvent(QExposeEvent *)
         {
             // initialize and start rendering when the window becomes usable for graphics purposes
@@ -4712,6 +6831,9 @@ QRhiResource::Type QRhiGraphicsPipeline::resourceType() const
     command at the end of a frame. For OpenGL, it is necessary to request the
     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
+    for details.
  */
 
 /*!
@@ -4830,7 +6952,7 @@ QRhiResource::Type QRhiSwapChain::resourceType() const
   */
 
 /*!
-    \fn QSize QRhiSwapChain::surfacePixelSize()
+    \fn virtual QSize QRhiSwapChain::surfacePixelSize() = 0
 
     \return The size of the window's associated surface or layer.
 
@@ -4838,13 +6960,13 @@ QRhiResource::Type QRhiSwapChain::resourceType() const
     QWindow::devicePixelRatio()}. With some graphics APIs and windowing system
     interfaces (for example, Vulkan) there is a theoretical possibility for a
     surface to assume a size different from the associated window. To support
-    these cases, rendering logic must always base size-derived calculations
+    these cases, \b{rendering logic must always base size-derived calculations
     (such as, viewports) on the size reported from QRhiSwapChain, and never on
-    the size queried from QWindow.
+    the size queried from QWindow}.
 
-    \note Can also be called before createOrResize(), if at least window() is
-    already set) This in combination with currentPixelSize() allows to detect
-    when a swapchain needs to be resized. However, watch out for the fact that
+    \note \b{Can also be called before createOrResize(), if at least window() is
+    already set. This in combination with currentPixelSize() allows to detect
+    when a swapchain needs to be resized.} However, watch out for the fact that
     the size of the underlying native object (surface, layer, or similar) is
     "live", so whenever this function is called, it returns the latest value
     reported by the underlying implementation, without any atomicity guarantee.
@@ -4865,7 +6987,7 @@ QRhiResource::Type QRhiSwapChain::resourceType() const
   */
 
 /*!
-    \fn bool QRhiSwapChain::isFormatSuported(Format f)
+    \fn virtual bool QRhiSwapChain::isFormatSuported(Format f) = 0
 
     \return true if the given swapchain format is supported. SDR is always
     supported.
@@ -4881,7 +7003,7 @@ QRhiResource::Type QRhiSwapChain::resourceType() const
  */
 
 /*!
-    \fn QRhiCommandBuffer *QRhiSwapChain::currentFrameCommandBuffer()
+    \fn virtual QRhiCommandBuffer *QRhiSwapChain::currentFrameCommandBuffer() = 0
 
     \return a command buffer on which rendering commands and resource updates
     can be recorded within a \l{QRhi::beginFrame()}{beginFrame} -
@@ -4901,7 +7023,7 @@ QRhiResource::Type QRhiSwapChain::resourceType() const
 */
 
 /*!
-    \fn QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget()
+    \fn virtual QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget() = 0
 
     \return a render target that can used with beginPass() in order to render
     the swapchain's current backbuffer. Only valid within a
@@ -4941,7 +7063,7 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar
 }
 
 /*!
-    \fn bool QRhiSwapChain::createOrResize()
+    \fn virtual bool QRhiSwapChain::createOrResize() = 0
 
     Creates the swapchain if not already done and resizes the swapchain buffers
     to match the current size of the targeted surface. Call this whenever the
@@ -4957,9 +7079,102 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar
  */
 
 /*!
+    \fn QWindow *QRhiSwapChain::window() const
+    \return the currently set window.
+ */
+
+/*!
+    \fn void QRhiSwapChain::setWindow(QWindow *window)
+    Sets the \a window.
+ */
+
+/*!
+    \fn QRhiSwapChainProxyData QRhiSwapChain::proxyData() const
+    \return the currently set proxy data.
+ */
+
+/*!
+    \fn void QRhiSwapChain::setProxyData(const QRhiSwapChainProxyData &d)
+    Sets the proxy data \a d.
+
+    \sa QRhi::updateSwapChainProxyData()
+ */
+
+/*!
+    \fn QRhiSwapChain::Flags QRhiSwapChain::flags() const
+    \return the currently set flags.
+ */
+
+/*!
+    \fn void QRhiSwapChain::setFlags(Flags f)
+    Sets the flags \a f.
+ */
+
+/*!
+    \fn QRhiSwapChain::Format QRhiSwapChain::format() const
+    \return the currently set format.
+ */
+
+/*!
+    \fn void QRhiSwapChain::setFormat(Format f)
+    Sets the format \a f.
+ */
+
+/*!
+    \fn QRhiRenderBuffer *QRhiSwapChain::depthStencil() const
+    \return the currently associated renderbuffer for depth-stencil.
+ */
+
+/*!
+    \fn void QRhiSwapChain::setDepthStencil(QRhiRenderBuffer *ds)
+    Sets the renderbuffer \a ds for use as a depth-stencil buffer.
+ */
+
+/*!
+    \fn int QRhiSwapChain::sampleCount() const
+    \return the currently set sample count. 1 means no multisample antialiasing.
+ */
+
+/*!
+    \fn void QRhiSwapChain::setSampleCount(int samples)
+
+    Sets the sample count. Common values for \a samples are 1 (no MSAA), 4 (4x
+    MSAA), or 8 (8x MSAA).
+
+    \sa QRhi::supportedSampleCounts()
+ */
+
+/*!
+    \fn QRhiRenderPassDescriptor *QRhiSwapChain::renderPassDescriptor() const
+    \return the currently associated QRhiRenderPassDescriptor object.
+ */
+
+/*!
+    \fn void QRhiSwapChain::setRenderPassDescriptor(QRhiRenderPassDescriptor *desc)
+    Associates with the QRhiRenderPassDescriptor \a desc.
+ */
+
+/*!
+    \fn virtual QRhiRenderPassDescriptor *QRhiSwapChain::newCompatibleRenderPassDescriptor() = 0;
+
+    \return a new QRhiRenderPassDescriptor that is compatible with this swapchain.
+
+    The returned value is used in two ways: it can be passed to
+    setRenderPassDescriptor() and
+    QRhiGraphicsPipeline::setRenderPassDescriptor(). A render pass descriptor
+    describes the attachments (color, depth/stencil) and the load/store
+    behavior that can be affected by flags(). A QRhiGraphicsPipeline can only
+    be used in combination with a swapchain that has a
+    \l{QRhiRenderPassDescriptor::isCompatible()}{compatible}
+    QRhiRenderPassDescriptor set.
+
+    \sa createOrResize()
+ */
+
+/*!
     \struct QRhiSwapChainHdrInfo
-    \internal
     \inmodule QtGui
+    \since 6.6
 
     \brief Describes the high dynamic range related information of the
     swapchain's associated output.
@@ -4992,10 +7207,75 @@ QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(StereoTargetBuffer tar
     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
+    for details.
+
     \sa QRhiSwapChain::hdrInfo()
  */
 
 /*!
+    \enum QRhiSwapChainHdrInfo::LimitsType
+
+    \value LuminanceInNits Indicates that the \l limits union has its
+    \c luminanceInNits struct set
+
+    \value ColorComponentValue Indicates that the \l limits union has its
+    \c colorComponentValue struct set
+*/
+
+/*!
+    \variable QRhiSwapChainHdrInfo::isHardCodedDefaults
+
+    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)
+
+    \sa QRhiSwapChain::hdrInfo()
+*/
+
+/*!
+    \variable QRhiSwapChainHdrInfo::limitsType
+
+    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. This value indicates what kind of
+    information is available in \l limits.
+
+    \sa QRhiSwapChain::hdrInfo()
+*/
+
+/*!
+    \variable QRhiSwapChainHdrInfo::limits
+
+    Contains the actual values queried from the graphics API or the platform.
+    The type of data is indicated by \l limitsType. This is therefore a union.
+    There are currently two options:
+
+    Luminance values in nits:
+
+    \code
+        struct {
+            float minLuminance;
+            float maxLuminance;
+        } luminanceInNits;
+    \endcode
+
+    Whereas for macOS/iOS, the maximum color component value (e.g. supposedly
+    something larger than 1.0f) is provided:
+
+    \code
+        struct {
+            float maxColorComponentValue;
+        } colorComponentValue;
+    \endcode
+
+    \sa QRhiSwapChain::hdrInfo()
+*/
+
+/*!
     \return the HDR information for the associated display.
 
     The returned struct is always the default one if createOrResize() has not
@@ -5042,8 +7322,8 @@ QDebug operator<<(QDebug dbg, const QRhiSwapChainHdrInfo &info)
 
 /*!
     \class QRhiComputePipeline
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Compute pipeline state resource.
 
     \note Setting the shader resource bindings is mandatory. The referenced
@@ -5051,6 +7331,9 @@ QDebug operator<<(QDebug dbg, const QRhiSwapChainHdrInfo &info)
     time create() is called.
 
     \note Setting the shader is mandatory.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
@@ -5080,15 +7363,59 @@ QRhiComputePipeline::QRhiComputePipeline(QRhiImplementation *rhi)
 }
 
 /*!
+    \fn QRhiComputePipeline::Flags QRhiComputePipeline::flags() const
+    \return the currently set flags.
+ */
+
+/*!
+    \fn void QRhiComputePipeline::setFlags(Flags f)
+    Sets the flags \a f.
+ */
+
+/*!
+    \fn QRhiShaderStage QRhiComputePipeline::shaderStage() const
+    \return the currently set shader.
+ */
+
+/*!
+    \fn void QRhiComputePipeline::setShaderStage(const QRhiShaderStage &stage)
+
+    Sets the shader to use. \a stage can only refer to the
+    \l{QRhiShaderStage::Compute}{compute stage}.
+ */
+
+/*!
+    \fn QRhiShaderResourceBindings *QRhiComputePipeline::shaderResourceBindings() const
+    \return the currently associated QRhiShaderResourceBindings object.
+ */
+
+/*!
+    \fn void QRhiComputePipeline::setShaderResourceBindings(QRhiShaderResourceBindings *srb)
+
+    Associates with \a srb describing the resource binding layout and the
+    resources (QRhiBuffer, QRhiTexture) themselves. The latter is optional. As
+    with graphics pipelines, the \a srb passed in here can leave the actual
+    buffer or texture objects unspecified (\nullptr) as long as there is
+    another,
+    \l{QRhiShaderResourceBindings::isLayoutCompatible()}{layout-compatible}
+    QRhiShaderResourceBindings bound via
+    \l{QRhiCommandBuffer::setShaderResources()}{setShaderResources()} before
+    recording the dispatch call.
+ */
+
+/*!
     \class QRhiCommandBuffer
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Command buffer resource.
 
     Not creatable by applications at the moment. The only ways to obtain a
     valid QRhiCommandBuffer are to get it from the targeted swapchain via
     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
+    for details.
  */
 
 /*!
@@ -5703,8 +8030,15 @@ bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params)
 
 /*!
     \struct QRhiSwapChainProxyData
-    \internal
     \inmodule QtGui
+    \since 6.6
+
+    \brief Opaque data describing native objects needed to set up a swapchain.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
+    \sa QRhi::updateSwapChainProxyData()
  */
 
 /*!
@@ -5800,8 +8134,8 @@ const char *QRhi::backendName() const
 
 /*!
     \struct QRhiDriverInfo
-    \internal
     \inmodule QtGui
+    \since 6.6
 
     \brief Describes the physical device, adapter, or graphics API
     implementation that is used by an initialized QRhi.
@@ -5813,8 +8147,35 @@ const char *QRhi::backendName() const
     \c{GL_VERSION}. The deviceId is always 0 for OpenGL. vendorId is always 0
     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
+    for details.
  */
 
+/*!
+    \variable QRhiDriverInfo::deviceName
+
+    \sa QRhi::driverInfo()
+*/
+
+/*!
+    \variable QRhiDriverInfo::deviceId
+
+    \sa QRhi::driverInfo()
+*/
+
+/*!
+    \variable QRhiDriverInfo::vendorId
+
+    \sa QRhi::driverInfo()
+*/
+
+/*!
+    \variable QRhiDriverInfo::deviceType
+
+    \sa QRhi::driverInfo(), QRhiDriverInfo::DeviceType
+*/
+
 #ifndef QT_NO_DEBUG_STREAM
 static inline const char *deviceTypeStr(QRhiDriverInfo::DeviceType type)
 {
@@ -5899,8 +8260,8 @@ void QRhi::runCleanup()
 
 /*!
     \class QRhiResourceUpdateBatch
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Records upload and copy type of operations.
 
     With QRhi it is no longer possible to perform copy type of operations at
@@ -5916,6 +8277,9 @@ 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
+    for details.
  */
 
 /*!
@@ -5959,29 +8323,26 @@ void QRhiResourceUpdateBatch::release()
     that is then merged into another when starting to first render pass later
     on:
 
-    \badcode
-    void init()
-    {
-        ...
-        initialUpdates = rhi->nextResourceUpdateBatch();
-        initialUpdates->uploadStaticBuffer(vbuf, vertexData);
-        initialUpdates->uploadStaticBuffer(ibuf, indexData);
-        ...
-    }
+    \code
+        void init()
+        {
+            initialUpdates = rhi->nextResourceUpdateBatch();
+            initialUpdates->uploadStaticBuffer(vbuf, vertexData);
+            initialUpdates->uploadStaticBuffer(ibuf, indexData);
+            // ...
+        }
 
-    void render()
-    {
-        ...
-        QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();
-        if (initialUpdates) {
-            resUpdates->merge(initialUpdates);
-            initialUpdates->release();
-            initialUpdates = nullptr;
+        void render()
+        {
+            QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();
+            if (initialUpdates) {
+                resUpdates->merge(initialUpdates);
+                initialUpdates->release();
+                initialUpdates = nullptr;
+            }
+            // resUpdates->updateDynamicBuffer(...);
+            cb->beginPass(rt, clearCol, clearDs, resUpdates);
         }
-        resUpdates->updateDynamicBuffer(...);
-        ...
-        cb->beginPass(rt, clearCol, clearDs, resUpdates);
-    }
     \endcode
  */
 void QRhiResourceUpdateBatch::merge(QRhiResourceUpdateBatch *other)
@@ -6023,8 +8384,8 @@ bool QRhiResourceUpdateBatch::hasOptimalCapacity() const
 
     \note QRhi transparently manages double buffering in order to prevent
     stalling the graphics pipeline. The fact that a QRhiBuffer may have
-    multiple native underneath can be safely ignored when using the QRhi and
-    QRhiResourceUpdateBatch.
+    multiple native buffer objects underneath can be safely ignored when using
+    the QRhi and QRhiResourceUpdateBatch.
  */
 void QRhiResourceUpdateBatch::updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
 {
@@ -6170,10 +8531,10 @@ void QRhiResourceUpdateBatch::copyTexture(QRhiTexture *dst, QRhiTexture *src, co
    application. Therefore, \a result provides not just the data but also a
    callback as operations on the batch are asynchronous by nature:
 
-   \badcode
-      beginFrame(sc);
-      beginPass
-      ...
+   \code
+      rhi->beginFrame(swapchain);
+      cb->beginPass(swapchain->currentFrameRenderTarget(), colorClear, dsClear);
+      // ...
       QRhiReadbackResult *rbResult = new QRhiReadbackResult;
       rbResult->completed = [rbResult] {
           {
@@ -6184,11 +8545,11 @@ void QRhiResourceUpdateBatch::copyTexture(QRhiTexture *dst, QRhiTexture *src, co
           }
           delete rbResult;
       };
-      u = nextResourceUpdateBatch();
+      QRhiResourceUpdateBatch *u = nextResourceUpdateBatch();
       QRhiReadbackDescription rb; // no texture -> uses the current backbuffer of sc
       u->readBackTexture(rb, rbResult);
-      endPass(u);
-      endFrame(sc);
+      cb->endPass(u);
+      rhi->endFrame(swapchain);
    \endcode
 
    \note The texture must be created with QRhiTexture::UsedAsTransferSource.
@@ -6268,16 +8629,16 @@ void QRhiResourceUpdateBatch::generateMips(QRhiTexture *tex)
    Due to not being tied to a frame being recorded, the following sequence is
    valid for example:
 
-   \badcode
+   \code
       rhi->beginFrame(swapchain);
-      u = rhi->nextResourceUpdateBatch();
+      QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
       u->uploadStaticBuffer(buf, data);
-      ... // does not commit the batch
+      // ... do not commit the batch
       rhi->endFrame();
       // u stays valid (assuming buf stays valid as well)
       rhi->beginFrame(swapchain);
       swapchain->currentFrameCommandBuffer()->resourceUpdate(u);
-      ... // draw with buf
+      // ... draw with buf
       rhi->endFrame();
    \endcode
 
@@ -6461,13 +8822,13 @@ void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)
     made on \a rt. Therefore, if \a rt has a QRhiTexture color attachment \c
     texture, and one needs to make the texture a different size, the following
     is then valid:
-    \badcode
-      rt = rhi->newTextureRenderTarget({ { texture } });
+    \code
+      QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ { texture } });
       rt->create();
-      ...
+      // ...
       texture->setPixelSize(new_size);
       texture->create();
-      cb->beginPass(rt, ...); // this is ok, no explicit rt->create() is required before
+      cb->beginPass(rt, colorClear, dsClear); // this is ok, no explicit rt->create() is required before
     \endcode
 
     \a flags allow controlling certain advanced functionality. One commonly used
@@ -6612,7 +8973,7 @@ void QRhiCommandBuffer::setShaderResources(QRhiShaderResourceBindings *srb,
     floats for position (so 5 floats per vertex: x, y, r, g, b). A QRhiGraphicsPipeline for
     this shader can then be created using the input layout:
 
-    \badcode
+    \code
         QRhiVertexInputLayout inputLayout;
         inputLayout.setBindings({
             { 5 * sizeof(float) }
@@ -6625,11 +8986,10 @@ void QRhiCommandBuffer::setShaderResources(QRhiShaderResourceBindings *srb,
 
     Here there is one buffer binding (binding number 0), with two inputs
     referencing it. When recording the pass, once the pipeline is set, the
-    vertex bindings can be specified simply like the following (using C++11
-    initializer syntax), assuming vbuf is the QRhiBuffer with all the
-    interleaved position+color data:
+    vertex bindings can be specified simply like the following, assuming vbuf
+    is the QRhiBuffer with all the interleaved position+color data:
 
-    \badcode
+    \code
         const QRhiCommandBuffer::VertexInput vbufBinding(vbuf, 0);
         cb->setVertexInput(0, 1, &vbufBinding);
     \endcode
@@ -7134,7 +9494,8 @@ int QRhi::resourceLimit(ResourceLimit limit) const
     for the device, context, and similar concepts used by the backend.
 
     Cast to QRhiVulkanNativeHandles, QRhiD3D11NativeHandles,
-    QRhiGles2NativeHandles, QRhiMetalNativeHandles as appropriate.
+    QRhiD3D12NativeHandles, QRhiGles2NativeHandles, or QRhiMetalNativeHandles
+    as appropriate.
 
     \note No ownership is transferred, neither for the returned pointer nor for
     any native objects.
@@ -7334,12 +9695,70 @@ void QRhi::setPipelineCacheData(const QByteArray &data)
 
 /*!
     \struct QRhiStats
-    \internal
     \inmodule QtGui
+    \since 6.6
 
     \brief Statistics provided from the underlying memory allocator.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
+/*!
+    \variable QRhiStats::totalPipelineCreationTime
+
+    The total time in milliseconds spent in graphics and compute pipeline
+    creation, which usually involves shader compilation or cache lookups, and
+    potentially expensive processing.
+
+    \note The value should not be compared between different backends since the
+    concept of "pipelines" and what exactly happens under the hood during, for
+    instance, a call to QRhiGraphicsPipeline::create(), differ greatly between
+    graphics APIs and their implementations.
+
+    \sa QRhi::statistics()
+*/
+
+/*!
+    \variable QRhiStats::blockCount
+
+    Statistic reported from the Vulkan or D3D12 memory allocator.
+
+    \sa QRhi::statistics()
+*/
+
+/*!
+    \variable QRhiStats::allocCount
+
+    Statistic reported from the Vulkan or D3D12 memory allocator.
+
+    \sa QRhi::statistics()
+*/
+
+/*!
+    \variable QRhiStats::usedBytes
+
+    Statistic reported from the Vulkan or D3D12 memory allocator.
+
+    \sa QRhi::statistics()
+*/
+
+/*!
+    \variable QRhiStats::unusedBytes
+
+    Statistic reported from the Vulkan or D3D12 memory allocator.
+
+    \sa QRhi::statistics()
+*/
+
+/*!
+    \variable QRhiStats::totalUsageBytes
+
+    Valid only with D3D12 currently. Matches IDXGIAdapter3::QueryVideoMemoryInfo().
+
+    \sa QRhi::statistics()
+*/
+
 #ifndef QT_NO_DEBUG_STREAM
 QDebug operator<<(QDebug dbg, const QRhiStats &info)
 {
@@ -7802,26 +10221,29 @@ int QRhi::currentFrameSlot() const
     beginOffscreenFrame, endOffscreenFrame, beginFrame, ...) is possible too
     but it does reduce parallelism so it should be done only infrequently.
 
-    Offscreen frames do not let the CPU - potentially - generate another frame
+    Offscreen frames do not let the CPU potentially generate another frame
     while the GPU is still processing the previous one. This has the side
     effect that if readbacks are scheduled, the results are guaranteed to be
     available once endOffscreenFrame() returns. That is not the case with
-    frames targeting a swapchain.
+    frames targeting a swapchain: there the GPU is potentially better utilized,
+    but working with readback operations needs more care from the application
+    because endFrame(), unlike endOffscreenFrame(), does not guarantee that the
+    results from the readback are available at that point.
 
     The skeleton of rendering a frame without a swapchain and then reading the
     frame contents back could look like the following:
 
-    \badcode
-          QRhiReadbackResult rbResult;
-          QRhiCommandBuffer *cb;
-          beginOffscreenFrame(&cb);
-          beginPass
-          ...
-          u = nextResourceUpdateBatch();
-          u->readBackTexture(rb, &rbResult);
-          endPass(u);
-          endOffscreenFrame();
-          // image data available in rbResult
+    \code
+        QRhiReadbackResult rbResult;
+        QRhiCommandBuffer *cb;
+        rhi->beginOffscreenFrame(&cb);
+        cb->beginPass(rt, colorClear, dsClear);
+        // ...
+        u = nextResourceUpdateBatch();
+        u->readBackTexture(rb, &rbResult);
+        cb->endPass(u);
+        rhi->endOffscreenFrame();
+        // image data available in rbResult
    \endcode
 
    \sa endOffscreenFrame(), beginFrame()
@@ -7882,6 +10304,9 @@ QRhi::FrameOpResult QRhi::finish()
     With some backend this list of supported values is fixed in advance, while
     with some others the (physical) device properties indicate what is
     supported at run time.
+
+    \sa QRhiRenderBuffer::setSampleCount(), QRhiTexture::setSampleCount(),
+    QRhiGraphicsPipeline::setSampleCount(), QRhiSwapChain::setSampleCount()
  */
 QList<int> QRhi::supportedSampleCounts() const
 {
diff --git a/src/gui/rhi/qrhi.h b/src/gui/rhi/qrhi.h
new file mode 100644
index 0000000000..8ec6630acf
--- /dev/null
+++ b/src/gui/rhi/qrhi.h
@@ -0,0 +1,1974 @@
+// 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
+
+#ifndef QRHI_H
+#define QRHI_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is part of the RHI API, with limited compatibility guarantees.
+// Usage of this API may make your code source and binary incompatible with
+// future versions of Qt.
+//
+
+#include <QtGui/qtguiglobal.h>
+#include <QtCore/qsize.h>
+#include <QtCore/qlist.h>
+#include <QtCore/qvarlengtharray.h>
+#include <QtCore/qthread.h>
+#include <QtGui/qmatrix4x4.h>
+#include <QtGui/qcolor.h>
+#include <QtGui/qimage.h>
+#include <functional>
+#include <array>
+
+#include <rhi/qshader.h>
+
+QT_BEGIN_NAMESPACE
+
+class QWindow;
+class QRhi;
+class QRhiImplementation;
+class QRhiBuffer;
+class QRhiRenderBuffer;
+class QRhiTexture;
+class QRhiSampler;
+class QRhiCommandBuffer;
+class QRhiResourceUpdateBatch;
+class QRhiResourceUpdateBatchPrivate;
+class QRhiSwapChain;
+
+class Q_GUI_EXPORT QRhiDepthStencilClearValue
+{
+public:
+    QRhiDepthStencilClearValue() = default;
+    QRhiDepthStencilClearValue(float d, quint32 s);
+
+    float depthClearValue() const { return m_d; }
+    void setDepthClearValue(float d) { m_d = d; }
+
+    quint32 stencilClearValue() const { return m_s; }
+    void setStencilClearValue(quint32 s) { m_s = s; }
+
+private:
+    float m_d = 1.0f;
+    quint32 m_s = 0;
+
+    friend bool operator==(const QRhiDepthStencilClearValue &a, const QRhiDepthStencilClearValue &b) noexcept
+    {
+        return a.m_d == b.m_d && a.m_s == b.m_s;
+    }
+
+    friend bool operator!=(const QRhiDepthStencilClearValue &a, const QRhiDepthStencilClearValue &b) noexcept
+    {
+        return !(a == b);
+    }
+
+    friend size_t qHash(const QRhiDepthStencilClearValue &v, size_t seed = 0) noexcept
+    {
+        QtPrivate::QHashCombine hash;
+        seed = hash(seed, v.m_d);
+        seed = hash(seed, v.m_s);
+        return seed;
+    }
+};
+
+Q_DECLARE_TYPEINFO(QRhiDepthStencilClearValue, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiDepthStencilClearValue &);
+#endif
+
+class Q_GUI_EXPORT QRhiViewport
+{
+public:
+    QRhiViewport() = default;
+    QRhiViewport(float x, float y, float w, float h, float minDepth = 0.0f, float maxDepth = 1.0f);
+
+    std::array<float, 4> viewport() const { return m_rect; }
+    void setViewport(float x, float y, float w, float h) {
+        m_rect[0] = x; m_rect[1] = y; m_rect[2] = w; m_rect[3] = h;
+    }
+
+    float minDepth() const { return m_minDepth; }
+    void setMinDepth(float minDepth) { m_minDepth = minDepth; }
+
+    float maxDepth() const { return m_maxDepth; }
+    void setMaxDepth(float maxDepth) { m_maxDepth = maxDepth; }
+
+private:
+    std::array<float, 4> m_rect { { 0.0f, 0.0f, 0.0f, 0.0f } };
+    float m_minDepth = 0.0f;
+    float m_maxDepth = 1.0f;
+
+    friend bool operator==(const QRhiViewport &a, const QRhiViewport &b) noexcept
+    {
+        return a.m_rect == b.m_rect
+                && a.m_minDepth == b.m_minDepth
+                && a.m_maxDepth == b.m_maxDepth;
+    }
+
+    friend bool operator!=(const QRhiViewport &a, const QRhiViewport &b) noexcept
+    {
+        return !(a == b);
+    }
+
+    friend size_t qHash(const QRhiViewport &v, size_t seed = 0) noexcept
+    {
+        QtPrivate::QHashCombine hash;
+        seed = hash(seed, v.m_rect[0]);
+        seed = hash(seed, v.m_rect[1]);
+        seed = hash(seed, v.m_rect[2]);
+        seed = hash(seed, v.m_rect[3]);
+        seed = hash(seed, v.m_minDepth);
+        seed = hash(seed, v.m_maxDepth);
+        return seed;
+    }
+};
+
+Q_DECLARE_TYPEINFO(QRhiViewport, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiViewport &);
+#endif
+
+class Q_GUI_EXPORT QRhiScissor
+{
+public:
+    QRhiScissor() = default;
+    QRhiScissor(int x, int y, int w, int h);
+
+    std::array<int, 4> scissor() const { return m_rect; }
+    void setScissor(int x, int y, int w, int h) {
+        m_rect[0] = x; m_rect[1] = y; m_rect[2] = w; m_rect[3] = h;
+    }
+
+private:
+    std::array<int, 4> m_rect { { 0, 0, 0, 0 } };
+
+    friend bool operator==(const QRhiScissor &a, const QRhiScissor &b) noexcept
+    {
+        return a.m_rect == b.m_rect;
+    }
+
+    friend bool operator!=(const QRhiScissor &a, const QRhiScissor &b) noexcept
+    {
+        return !(a == b);
+    }
+
+    friend size_t qHash(const QRhiScissor &v, size_t seed = 0) noexcept
+    {
+        QtPrivate::QHashCombine hash;
+        seed = hash(seed, v.m_rect[0]);
+        seed = hash(seed, v.m_rect[1]);
+        seed = hash(seed, v.m_rect[2]);
+        seed = hash(seed, v.m_rect[3]);
+        return seed;
+    }
+};
+
+Q_DECLARE_TYPEINFO(QRhiScissor, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiScissor &);
+#endif
+
+class Q_GUI_EXPORT QRhiVertexInputBinding
+{
+public:
+    enum Classification {
+        PerVertex,
+        PerInstance
+    };
+
+    QRhiVertexInputBinding() = default;
+    QRhiVertexInputBinding(quint32 stride, Classification cls = PerVertex, quint32 stepRate = 1);
+
+    quint32 stride() const { return m_stride; }
+    void setStride(quint32 s) { m_stride = s; }
+
+    Classification classification() const { return m_classification; }
+    void setClassification(Classification c) { m_classification = c; }
+
+    quint32 instanceStepRate() const { return m_instanceStepRate; }
+    void setInstanceStepRate(quint32 rate) { m_instanceStepRate = rate; }
+
+private:
+    quint32 m_stride = 0;
+    Classification m_classification = PerVertex;
+    quint32 m_instanceStepRate = 1;
+
+    friend bool operator==(const QRhiVertexInputBinding &a, const QRhiVertexInputBinding &b) noexcept
+    {
+        return a.m_stride == b.m_stride
+                && a.m_classification == b.m_classification
+                && a.m_instanceStepRate == b.m_instanceStepRate;
+    }
+
+    friend bool operator!=(const QRhiVertexInputBinding &a, const QRhiVertexInputBinding &b) noexcept
+    {
+        return !(a == b);
+    }
+
+    friend size_t qHash(const QRhiVertexInputBinding &v, size_t seed = 0) noexcept
+    {
+        QtPrivate::QHashCombine hash;
+        seed = hash(seed, v.m_stride);
+        seed = hash(seed, v.m_classification);
+        seed = hash(seed, v.m_instanceStepRate);
+        return seed;
+    }
+};
+
+Q_DECLARE_TYPEINFO(QRhiVertexInputBinding, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiVertexInputBinding &);
+#endif
+
+class Q_GUI_EXPORT QRhiVertexInputAttribute
+{
+public:
+    enum Format {
+        Float4,
+        Float3,
+        Float2,
+        Float,
+        UNormByte4,
+        UNormByte2,
+        UNormByte,
+        UInt4,
+        UInt3,
+        UInt2,
+        UInt,
+        SInt4,
+        SInt3,
+        SInt2,
+        SInt,
+        Half4,
+        Half3,
+        Half2,
+        Half
+    };
+
+    QRhiVertexInputAttribute() = default;
+    QRhiVertexInputAttribute(int binding, int location, Format format, quint32 offset, int matrixSlice = -1);
+
+    int binding() const { return m_binding; }
+    void setBinding(int b) { m_binding = b; }
+
+    int location() const { return m_location; }
+    void setLocation(int loc) { m_location = loc; }
+
+    Format format() const { return m_format; }
+    void setFormat(Format f) { m_format = f; }
+
+    quint32 offset() const { return m_offset; }
+    void setOffset(quint32 ofs) { m_offset = ofs; }
+
+    int matrixSlice() const { return m_matrixSlice; }
+    void setMatrixSlice(int slice) { m_matrixSlice = slice; }
+
+private:
+    int m_binding = 0;
+    int m_location = 0;
+    Format m_format = Float4;
+    quint32 m_offset = 0;
+    int m_matrixSlice = -1;
+
+    friend bool operator==(const QRhiVertexInputAttribute &a, const QRhiVertexInputAttribute &b) noexcept
+    {
+        return a.m_binding == b.m_binding
+                && a.m_location == b.m_location
+                && a.m_format == b.m_format
+                && a.m_offset == b.m_offset;
+        // matrixSlice excluded intentionally
+    }
+
+    friend bool operator!=(const QRhiVertexInputAttribute &a, const QRhiVertexInputAttribute &b) noexcept
+    {
+        return !(a == b);
+    }
+
+    friend size_t qHash(const QRhiVertexInputAttribute &v, size_t seed = 0) noexcept
+    {
+        QtPrivate::QHashCombine hash;
+        seed = hash(seed, v.m_binding);
+        seed = hash(seed, v.m_location);
+        seed = hash(seed, v.m_format);
+        seed = hash(seed, v.m_offset);
+        return seed;
+    }
+};
+
+Q_DECLARE_TYPEINFO(QRhiVertexInputAttribute, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiVertexInputAttribute &);
+#endif
+
+class Q_GUI_EXPORT QRhiVertexInputLayout
+{
+public:
+    QRhiVertexInputLayout() = default;
+
+    void setBindings(std::initializer_list<QRhiVertexInputBinding> list) { m_bindings = list; }
+    template<typename InputIterator>
+    void setBindings(InputIterator first, InputIterator last)
+    {
+        m_bindings.clear();
+        std::copy(first, last, std::back_inserter(m_bindings));
+    }
+    const QRhiVertexInputBinding *cbeginBindings() const { return m_bindings.cbegin(); }
+    const QRhiVertexInputBinding *cendBindings() const { return m_bindings.cend(); }
+    const QRhiVertexInputBinding *bindingAt(qsizetype index) const { return &m_bindings.at(index); }
+    qsizetype bindingCount() const { return m_bindings.count(); }
+
+    void setAttributes(std::initializer_list<QRhiVertexInputAttribute> list) { m_attributes = list; }
+    template<typename InputIterator>
+    void setAttributes(InputIterator first, InputIterator last)
+    {
+        m_attributes.clear();
+        std::copy(first, last, std::back_inserter(m_attributes));
+    }
+    const QRhiVertexInputAttribute *cbeginAttributes() const { return m_attributes.cbegin(); }
+    const QRhiVertexInputAttribute *cendAttributes() const { return m_attributes.cend(); }
+    const QRhiVertexInputAttribute *attributeAt(qsizetype index) const { return &m_attributes.at(index); }
+    qsizetype attributeCount() const { return m_attributes.count(); }
+
+private:
+    QVarLengthArray<QRhiVertexInputBinding, 8> m_bindings;
+    QVarLengthArray<QRhiVertexInputAttribute, 8> m_attributes;
+
+    friend bool operator==(const QRhiVertexInputLayout &a, const QRhiVertexInputLayout &b) noexcept
+    {
+        return a.m_bindings == b.m_bindings && a.m_attributes == b.m_attributes;
+    }
+
+    friend bool operator!=(const QRhiVertexInputLayout &a, const QRhiVertexInputLayout &b) noexcept
+    {
+        return !(a == b);
+    }
+
+    friend size_t qHash(const QRhiVertexInputLayout &v, size_t seed = 0) noexcept
+    {
+        QtPrivate::QHashCombine hash;
+        seed = hash(seed, v.m_bindings);
+        seed = hash(seed, v.m_attributes);
+        return seed;
+    }
+
+    friend Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiVertexInputLayout &);
+};
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiVertexInputLayout &);
+#endif
+
+class Q_GUI_EXPORT QRhiShaderStage
+{
+public:
+    enum Type {
+        Vertex,
+        TessellationControl,
+        TessellationEvaluation,
+        Geometry,
+        Fragment,
+        Compute
+    };
+
+    QRhiShaderStage() = default;
+    QRhiShaderStage(Type type, const QShader &shader,
+                    QShader::Variant v = QShader::StandardShader);
+
+    Type type() const { return m_type; }
+    void setType(Type t) { m_type = t; }
+
+    QShader shader() const { return m_shader; }
+    void setShader(const QShader &s) { m_shader = s; }
+
+    QShader::Variant shaderVariant() const { return m_shaderVariant; }
+    void setShaderVariant(QShader::Variant v) { m_shaderVariant = v; }
+
+private:
+    Type m_type = Vertex;
+    QShader m_shader;
+    QShader::Variant m_shaderVariant = QShader::StandardShader;
+
+    friend bool operator==(const QRhiShaderStage &a, const QRhiShaderStage &b) noexcept
+    {
+        return a.m_type == b.m_type
+                && a.m_shader == b.m_shader
+                && a.m_shaderVariant == b.m_shaderVariant;
+    }
+
+    friend bool operator!=(const QRhiShaderStage &a, const QRhiShaderStage &b) noexcept
+    {
+        return !(a == b);
+    }
+
+    friend size_t qHash(const QRhiShaderStage &v, size_t seed = 0) noexcept
+    {
+        QtPrivate::QHashCombine hash;
+        seed = hash(seed, v.m_type);
+        seed = hash(seed, v.m_shader);
+        seed = hash(seed, v.m_shaderVariant);
+        return seed;
+    }
+};
+
+Q_DECLARE_TYPEINFO(QRhiShaderStage, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiShaderStage &);
+#endif
+
+using QRhiGraphicsShaderStage = QRhiShaderStage;
+
+class Q_GUI_EXPORT QRhiShaderResourceBinding
+{
+public:
+    enum Type {
+        UniformBuffer,
+        SampledTexture,
+        Texture,
+        Sampler,
+        ImageLoad,
+        ImageStore,
+        ImageLoadStore,
+        BufferLoad,
+        BufferStore,
+        BufferLoadStore
+    };
+
+    enum StageFlag {
+        VertexStage = 1 << 0,
+        TessellationControlStage = 1 << 1,
+        TessellationEvaluationStage = 1 << 2,
+        GeometryStage = 1 << 3,
+        FragmentStage = 1 << 4,
+        ComputeStage = 1 << 5
+    };
+    Q_DECLARE_FLAGS(StageFlags, StageFlag)
+
+    QRhiShaderResourceBinding() = default;
+
+    bool isLayoutCompatible(const QRhiShaderResourceBinding &other) const;
+
+    static QRhiShaderResourceBinding uniformBuffer(int binding, StageFlags stage, QRhiBuffer *buf);
+    static QRhiShaderResourceBinding uniformBuffer(int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size);
+    static QRhiShaderResourceBinding uniformBufferWithDynamicOffset(int binding, StageFlags stage, QRhiBuffer *buf, quint32 size);
+
+    static QRhiShaderResourceBinding sampledTexture(int binding, StageFlags stage, QRhiTexture *tex, QRhiSampler *sampler);
+
+    struct TextureAndSampler {
+        QRhiTexture *tex;
+        QRhiSampler *sampler;
+    };
+    static QRhiShaderResourceBinding sampledTextures(int binding, StageFlags stage, int count, const TextureAndSampler *texSamplers);
+
+    static QRhiShaderResourceBinding texture(int binding, StageFlags stage, QRhiTexture *tex);
+    static QRhiShaderResourceBinding textures(int binding, StageFlags stage, int count, QRhiTexture **tex);
+    static QRhiShaderResourceBinding sampler(int binding, StageFlags stage, QRhiSampler *sampler);
+
+    static QRhiShaderResourceBinding imageLoad(int binding, StageFlags stage, QRhiTexture *tex, int level);
+    static QRhiShaderResourceBinding imageStore(int binding, StageFlags stage, QRhiTexture *tex, int level);
+    static QRhiShaderResourceBinding imageLoadStore(int binding, StageFlags stage, QRhiTexture *tex, int level);
+
+    static QRhiShaderResourceBinding bufferLoad(int binding, StageFlags stage, QRhiBuffer *buf);
+    static QRhiShaderResourceBinding bufferLoad(int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size);
+    static QRhiShaderResourceBinding bufferStore(int binding, StageFlags stage, QRhiBuffer *buf);
+    static QRhiShaderResourceBinding bufferStore(int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size);
+    static QRhiShaderResourceBinding bufferLoadStore(int binding, StageFlags stage, QRhiBuffer *buf);
+    static QRhiShaderResourceBinding bufferLoadStore(int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size);
+
+    struct Data
+    {
+        int binding;
+        QRhiShaderResourceBinding::StageFlags stage;
+        QRhiShaderResourceBinding::Type type;
+        struct UniformBufferData {
+            QRhiBuffer *buf;
+            quint32 offset;
+            quint32 maybeSize;
+            bool hasDynamicOffset;
+        };
+        static const int MAX_TEX_SAMPLER_ARRAY_SIZE = 16;
+        struct TextureAndOrSamplerData {
+            int count;
+            TextureAndSampler texSamplers[MAX_TEX_SAMPLER_ARRAY_SIZE];
+        };
+        struct StorageImageData {
+            QRhiTexture *tex;
+            int level;
+        };
+        struct StorageBufferData {
+            QRhiBuffer *buf;
+            quint32 offset;
+            quint32 maybeSize;
+        };
+        union {
+            UniformBufferData ubuf;
+            TextureAndOrSamplerData stex;
+            StorageImageData simage;
+            StorageBufferData sbuf;
+        } u;
+
+        int arraySize() const
+        {
+            return type == QRhiShaderResourceBinding::SampledTexture || type == QRhiShaderResourceBinding::Texture
+                    ? u.stex.count
+                    : 1;
+        }
+
+        template<typename Output>
+        Output serialize(Output dst) const
+        {
+            // must write out exactly LAYOUT_DESC_ENTRIES_PER_BINDING elements here
+            *dst++ = quint32(binding);
+            *dst++ = quint32(stage);
+            *dst++ = quint32(type);
+            *dst++ = quint32(arraySize());
+            return dst;
+        }
+    };
+
+    static const int LAYOUT_DESC_ENTRIES_PER_BINDING = 4;
+
+    template<typename Output>
+    static void serializeLayoutDescription(const QRhiShaderResourceBinding *first,
+                                           const QRhiShaderResourceBinding *last,
+                                           Output dst)
+    {
+        while (first != last) {
+            dst = first->d.serialize(dst);
+            ++first;
+        }
+    }
+
+private:
+    Data d;
+    friend class QRhiImplementation;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiShaderResourceBinding::StageFlags)
+
+Q_DECLARE_TYPEINFO(QRhiShaderResourceBinding, Q_PRIMITIVE_TYPE);
+
+Q_GUI_EXPORT bool operator==(const QRhiShaderResourceBinding &a, const QRhiShaderResourceBinding &b) noexcept;
+Q_GUI_EXPORT bool operator!=(const QRhiShaderResourceBinding &a, const QRhiShaderResourceBinding &b) noexcept;
+Q_GUI_EXPORT size_t qHash(const QRhiShaderResourceBinding &b, size_t seed = 0) noexcept;
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiShaderResourceBinding &);
+#endif
+
+class Q_GUI_EXPORT QRhiColorAttachment
+{
+public:
+    QRhiColorAttachment() = default;
+    QRhiColorAttachment(QRhiTexture *texture);
+    QRhiColorAttachment(QRhiRenderBuffer *renderBuffer);
+
+    QRhiTexture *texture() const { return m_texture; }
+    void setTexture(QRhiTexture *tex) { m_texture = tex; }
+
+    QRhiRenderBuffer *renderBuffer() const { return m_renderBuffer; }
+    void setRenderBuffer(QRhiRenderBuffer *rb) { m_renderBuffer = rb; }
+
+    int layer() const { return m_layer; }
+    void setLayer(int layer) { m_layer = layer; }
+
+    int level() const { return m_level; }
+    void setLevel(int level) { m_level = level; }
+
+    QRhiTexture *resolveTexture() const { return m_resolveTexture; }
+    void setResolveTexture(QRhiTexture *tex) { m_resolveTexture = tex; }
+
+    int resolveLayer() const { return m_resolveLayer; }
+    void setResolveLayer(int layer) { m_resolveLayer = layer; }
+
+    int resolveLevel() const { return m_resolveLevel; }
+    void setResolveLevel(int level) { m_resolveLevel = level; }
+
+private:
+    QRhiTexture *m_texture = nullptr;
+    QRhiRenderBuffer *m_renderBuffer = nullptr;
+    int m_layer = 0;
+    int m_level = 0;
+    QRhiTexture *m_resolveTexture = nullptr;
+    int m_resolveLayer = 0;
+    int m_resolveLevel = 0;
+};
+
+Q_DECLARE_TYPEINFO(QRhiColorAttachment, Q_RELOCATABLE_TYPE);
+
+class Q_GUI_EXPORT QRhiTextureRenderTargetDescription
+{
+public:
+    QRhiTextureRenderTargetDescription() = default;
+    QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment);
+    QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer);
+    QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture);
+
+    void setColorAttachments(std::initializer_list<QRhiColorAttachment> list) { m_colorAttachments = list; }
+    template<typename InputIterator>
+    void setColorAttachments(InputIterator first, InputIterator last)
+    {
+        m_colorAttachments.clear();
+        std::copy(first, last, std::back_inserter(m_colorAttachments));
+    }
+    const QRhiColorAttachment *cbeginColorAttachments() const { return m_colorAttachments.cbegin(); }
+    const QRhiColorAttachment *cendColorAttachments() const { return m_colorAttachments.cend(); }
+    const QRhiColorAttachment *colorAttachmentAt(qsizetype index) const { return &m_colorAttachments.at(index); }
+    qsizetype colorAttachmentCount() const { return m_colorAttachments.count(); }
+
+    QRhiRenderBuffer *depthStencilBuffer() const { return m_depthStencilBuffer; }
+    void setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer) { m_depthStencilBuffer = renderBuffer; }
+
+    QRhiTexture *depthTexture() const { return m_depthTexture; }
+    void setDepthTexture(QRhiTexture *texture) { m_depthTexture = texture; }
+
+private:
+    QVarLengthArray<QRhiColorAttachment, 8> m_colorAttachments;
+    QRhiRenderBuffer *m_depthStencilBuffer = nullptr;
+    QRhiTexture *m_depthTexture = nullptr;
+};
+
+class Q_GUI_EXPORT QRhiTextureSubresourceUploadDescription
+{
+public:
+    QRhiTextureSubresourceUploadDescription() = default;
+    explicit QRhiTextureSubresourceUploadDescription(const QImage &image);
+    QRhiTextureSubresourceUploadDescription(const void *data, quint32 size);
+    explicit QRhiTextureSubresourceUploadDescription(const QByteArray &data);
+
+    QImage image() const { return m_image; }
+    void setImage(const QImage &image) { m_image = image; }
+
+    QByteArray data() const { return m_data; }
+    void setData(const QByteArray &data) { m_data = data; }
+
+    quint32 dataStride() const { return m_dataStride; }
+    void setDataStride(quint32 stride) { m_dataStride = stride; }
+
+    QPoint destinationTopLeft() const { return m_destinationTopLeft; }
+    void setDestinationTopLeft(const QPoint &p) { m_destinationTopLeft = p; }
+
+    QSize sourceSize() const { return m_sourceSize; }
+    void setSourceSize(const QSize &size) { m_sourceSize = size; }
+
+    QPoint sourceTopLeft() const { return m_sourceTopLeft; }
+    void setSourceTopLeft(const QPoint &p) { m_sourceTopLeft = p; }
+
+private:
+    QImage m_image;
+    QByteArray m_data;
+    quint32 m_dataStride = 0;
+    QPoint m_destinationTopLeft;
+    QSize m_sourceSize;
+    QPoint m_sourceTopLeft;
+};
+
+Q_DECLARE_TYPEINFO(QRhiTextureSubresourceUploadDescription, Q_RELOCATABLE_TYPE);
+
+class Q_GUI_EXPORT QRhiTextureUploadEntry
+{
+public:
+    QRhiTextureUploadEntry() = default;
+    QRhiTextureUploadEntry(int layer, int level, const QRhiTextureSubresourceUploadDescription &desc);
+
+    int layer() const { return m_layer; }
+    void setLayer(int layer) { m_layer = layer; }
+
+    int level() const { return m_level; }
+    void setLevel(int level) { m_level = level; }
+
+    QRhiTextureSubresourceUploadDescription description() const { return m_desc; }
+    void setDescription(const QRhiTextureSubresourceUploadDescription &desc) { m_desc = desc; }
+
+private:
+    int m_layer = 0;
+    int m_level = 0;
+    QRhiTextureSubresourceUploadDescription m_desc;
+};
+
+Q_DECLARE_TYPEINFO(QRhiTextureUploadEntry, Q_RELOCATABLE_TYPE);
+
+class Q_GUI_EXPORT QRhiTextureUploadDescription
+{
+public:
+    QRhiTextureUploadDescription() = default;
+    QRhiTextureUploadDescription(const QRhiTextureUploadEntry &entry);
+    QRhiTextureUploadDescription(std::initializer_list<QRhiTextureUploadEntry> list);
+
+    void setEntries(std::initializer_list<QRhiTextureUploadEntry> list) { m_entries = list; }
+    template<typename InputIterator>
+    void setEntries(InputIterator first, InputIterator last)
+    {
+        m_entries.clear();
+        std::copy(first, last, std::back_inserter(m_entries));
+    }
+    const QRhiTextureUploadEntry *cbeginEntries() const { return m_entries.cbegin(); }
+    const QRhiTextureUploadEntry *cendEntries() const { return m_entries.cend(); }
+    const QRhiTextureUploadEntry *entryAt(qsizetype index) const { return &m_entries.at(index); }
+    qsizetype entryCount() const { return m_entries.count(); }
+
+private:
+    QVarLengthArray<QRhiTextureUploadEntry, 16> m_entries;
+};
+
+class Q_GUI_EXPORT QRhiTextureCopyDescription
+{
+public:
+    QRhiTextureCopyDescription() = default;
+
+    QSize pixelSize() const { return m_pixelSize; }
+    void setPixelSize(const QSize &sz) { m_pixelSize = sz; }
+
+    int sourceLayer() const { return m_sourceLayer; }
+    void setSourceLayer(int layer) { m_sourceLayer = layer; }
+
+    int sourceLevel() const { return m_sourceLevel; }
+    void setSourceLevel(int level) { m_sourceLevel = level; }
+
+    QPoint sourceTopLeft() const { return m_sourceTopLeft; }
+    void setSourceTopLeft(const QPoint &p) { m_sourceTopLeft = p; }
+
+    int destinationLayer() const { return m_destinationLayer; }
+    void setDestinationLayer(int layer) { m_destinationLayer = layer; }
+
+    int destinationLevel() const { return m_destinationLevel; }
+    void setDestinationLevel(int level) { m_destinationLevel = level; }
+
+    QPoint destinationTopLeft() const { return m_destinationTopLeft; }
+    void setDestinationTopLeft(const QPoint &p) { m_destinationTopLeft = p; }
+
+private:
+    QSize m_pixelSize;
+    int m_sourceLayer = 0;
+    int m_sourceLevel = 0;
+    QPoint m_sourceTopLeft;
+    int m_destinationLayer = 0;
+    int m_destinationLevel = 0;
+    QPoint m_destinationTopLeft;
+};
+
+Q_DECLARE_TYPEINFO(QRhiTextureCopyDescription, Q_RELOCATABLE_TYPE);
+
+class Q_GUI_EXPORT QRhiReadbackDescription
+{
+public:
+    QRhiReadbackDescription() = default;
+    QRhiReadbackDescription(QRhiTexture *texture);
+
+    QRhiTexture *texture() const { return m_texture; }
+    void setTexture(QRhiTexture *tex) { m_texture = tex; }
+
+    int layer() const { return m_layer; }
+    void setLayer(int layer) { m_layer = layer; }
+
+    int level() const { return m_level; }
+    void setLevel(int level) { m_level = level; }
+
+private:
+    QRhiTexture *m_texture = nullptr;
+    int m_layer = 0;
+    int m_level = 0;
+};
+
+Q_DECLARE_TYPEINFO(QRhiReadbackDescription, Q_RELOCATABLE_TYPE);
+
+struct Q_GUI_EXPORT QRhiNativeHandles
+{
+};
+
+class Q_GUI_EXPORT QRhiResource
+{
+public:
+    enum Type {
+        Buffer,
+        Texture,
+        Sampler,
+        RenderBuffer,
+        RenderPassDescriptor,
+        SwapChainRenderTarget,
+        TextureRenderTarget,
+        ShaderResourceBindings,
+        GraphicsPipeline,
+        SwapChain,
+        ComputePipeline,
+        CommandBuffer
+    };
+
+    virtual ~QRhiResource();
+
+    virtual Type resourceType() const = 0;
+
+    virtual void destroy() = 0;
+
+    void deleteLater();
+
+    QByteArray name() const;
+    void setName(const QByteArray &name);
+
+    quint64 globalResourceId() const;
+
+    QRhi *rhi() const;
+
+protected:
+    QRhiResource(QRhiImplementation *rhi);
+    Q_DISABLE_COPY(QRhiResource)
+    friend class QRhiImplementation;
+    QRhiImplementation *m_rhi = nullptr;
+    quint64 m_id;
+    QByteArray m_objectName;
+};
+
+class Q_GUI_EXPORT QRhiBuffer : public QRhiResource
+{
+public:
+    enum Type {
+        Immutable,
+        Static,
+        Dynamic
+    };
+
+    enum UsageFlag {
+        VertexBuffer = 1 << 0,
+        IndexBuffer = 1 << 1,
+        UniformBuffer = 1 << 2,
+        StorageBuffer = 1 << 3
+    };
+    Q_DECLARE_FLAGS(UsageFlags, UsageFlag)
+
+    struct NativeBuffer {
+        const void *objects[3];
+        int slotCount;
+    };
+
+    QRhiResource::Type resourceType() const override;
+
+    Type type() const { return m_type; }
+    void setType(Type t) { m_type = t; }
+
+    UsageFlags usage() const { return m_usage; }
+    void setUsage(UsageFlags u) { m_usage = u; }
+
+    quint32 size() const { return m_size; }
+    void setSize(quint32 sz) { m_size = sz; }
+
+    virtual bool create() = 0;
+
+    virtual NativeBuffer nativeBuffer();
+
+    virtual char *beginFullDynamicBufferUpdateForCurrentFrame();
+    virtual void endFullDynamicBufferUpdateForCurrentFrame();
+
+protected:
+    QRhiBuffer(QRhiImplementation *rhi, Type type_, UsageFlags usage_, quint32 size_);
+    Type m_type;
+    UsageFlags m_usage;
+    quint32 m_size;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiBuffer::UsageFlags)
+
+class Q_GUI_EXPORT QRhiTexture : public QRhiResource
+{
+public:
+    enum Flag {
+        RenderTarget = 1 << 0,
+        CubeMap = 1 << 2,
+        MipMapped = 1 << 3,
+        sRGB = 1 << 4,
+        UsedAsTransferSource = 1 << 5,
+        UsedWithGenerateMips = 1 << 6,
+        UsedWithLoadStore = 1 << 7,
+        UsedAsCompressedAtlas = 1 << 8,
+        ExternalOES = 1 << 9,
+        ThreeDimensional = 1 << 10,
+        TextureRectangleGL = 1 << 11,
+        TextureArray = 1 << 12,
+        OneDimensional = 1 << 13
+    };
+    Q_DECLARE_FLAGS(Flags, Flag)
+
+    enum Format {
+        UnknownFormat,
+
+        RGBA8,
+        BGRA8,
+        R8,
+        RG8,
+        R16,
+        RG16,
+        RED_OR_ALPHA8,
+
+        RGBA16F,
+        RGBA32F,
+        R16F,
+        R32F,
+
+        RGB10A2,
+
+        D16,
+        D24,
+        D24S8,
+        D32F,
+
+        BC1,
+        BC2,
+        BC3,
+        BC4,
+        BC5,
+        BC6H,
+        BC7,
+
+        ETC2_RGB8,
+        ETC2_RGB8A1,
+        ETC2_RGBA8,
+
+        ASTC_4x4,
+        ASTC_5x4,
+        ASTC_5x5,
+        ASTC_6x5,
+        ASTC_6x6,
+        ASTC_8x5,
+        ASTC_8x6,
+        ASTC_8x8,
+        ASTC_10x5,
+        ASTC_10x6,
+        ASTC_10x8,
+        ASTC_10x10,
+        ASTC_12x10,
+        ASTC_12x12
+    };
+
+    struct NativeTexture {
+        quint64 object;
+        int layout; // or state
+    };
+
+    QRhiResource::Type resourceType() const override;
+
+    Format format() const { return m_format; }
+    void setFormat(Format fmt) { m_format = fmt; }
+
+    QSize pixelSize() const { return m_pixelSize; }
+    void setPixelSize(const QSize &sz) { m_pixelSize = sz; }
+
+    int depth() const { return m_depth; }
+    void setDepth(int depth) { m_depth = depth; }
+
+    int arraySize() const { return m_arraySize; }
+    void setArraySize(int arraySize) { m_arraySize = arraySize; }
+
+    int arrayRangeStart() const { return m_arrayRangeStart; }
+    int arrayRangeLength() const { return m_arrayRangeLength; }
+    void setArrayRange(int startIndex, int count)
+    {
+        m_arrayRangeStart = startIndex;
+        m_arrayRangeLength = count;
+    }
+
+    Flags flags() const { return m_flags; }
+    void setFlags(Flags f) { m_flags = f; }
+
+    int sampleCount() const { return m_sampleCount; }
+    void setSampleCount(int s) { m_sampleCount = s; }
+
+    virtual bool create() = 0;
+    virtual NativeTexture nativeTexture();
+    virtual bool createFrom(NativeTexture src);
+    virtual void setNativeLayout(int layout);
+
+protected:
+    QRhiTexture(QRhiImplementation *rhi, Format format_, const QSize &pixelSize_, int depth_,
+                int arraySize_, int sampleCount_, Flags flags_);
+    Format m_format;
+    QSize m_pixelSize;
+    int m_depth;
+    int m_arraySize;
+    int m_sampleCount;
+    Flags m_flags;
+    int m_arrayRangeStart = -1;
+    int m_arrayRangeLength = -1;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiTexture::Flags)
+
+class Q_GUI_EXPORT QRhiSampler : public QRhiResource
+{
+public:
+    enum Filter {
+        None,
+        Nearest,
+        Linear
+    };
+
+    enum AddressMode {
+        Repeat,
+        ClampToEdge,
+        Mirror,
+    };
+
+    enum CompareOp {
+        Never,
+        Less,
+        Equal,
+        LessOrEqual,
+        Greater,
+        NotEqual,
+        GreaterOrEqual,
+        Always
+    };
+
+    QRhiResource::Type resourceType() const override;
+
+    Filter magFilter() const { return m_magFilter; }
+    void setMagFilter(Filter f) { m_magFilter = f; }
+
+    Filter minFilter() const { return m_minFilter; }
+    void setMinFilter(Filter f) { m_minFilter = f; }
+
+    Filter mipmapMode() const { return m_mipmapMode; }
+    void setMipmapMode(Filter f) { m_mipmapMode = f; }
+
+    AddressMode addressU() const { return m_addressU; }
+    void setAddressU(AddressMode mode) { m_addressU = mode; }
+
+    AddressMode addressV() const { return m_addressV; }
+    void setAddressV(AddressMode mode) { m_addressV = mode; }
+
+    AddressMode addressW() const { return m_addressW; }
+    void setAddressW(AddressMode mode) { m_addressW = mode; }
+
+    CompareOp textureCompareOp() const { return m_compareOp; }
+    void setTextureCompareOp(CompareOp op) { m_compareOp = op; }
+
+    virtual bool create() = 0;
+
+protected:
+    QRhiSampler(QRhiImplementation *rhi,
+                Filter magFilter_, Filter minFilter_, Filter mipmapMode_,
+                AddressMode u_, AddressMode v_, AddressMode w_);
+    Filter m_magFilter;
+    Filter m_minFilter;
+    Filter m_mipmapMode;
+    AddressMode m_addressU;
+    AddressMode m_addressV;
+    AddressMode m_addressW;
+    CompareOp m_compareOp;
+};
+
+class Q_GUI_EXPORT QRhiRenderBuffer : public QRhiResource
+{
+public:
+    enum Type {
+        DepthStencil,
+        Color
+    };
+
+    enum Flag {
+        UsedWithSwapChainOnly = 1 << 0
+    };
+    Q_DECLARE_FLAGS(Flags, Flag)
+
+    struct NativeRenderBuffer {
+        quint64 object;
+    };
+
+    QRhiResource::Type resourceType() const override;
+
+    Type type() const { return m_type; }
+    void setType(Type t) { m_type = t; }
+
+    QSize pixelSize() const { return m_pixelSize; }
+    void setPixelSize(const QSize &sz) { m_pixelSize = sz; }
+
+    int sampleCount() const { return m_sampleCount; }
+    void setSampleCount(int s) { m_sampleCount = s; }
+
+    Flags flags() const { return m_flags; }
+    void setFlags(Flags f) { m_flags = f; }
+
+    virtual bool create() = 0;
+    virtual bool createFrom(NativeRenderBuffer src);
+
+    virtual QRhiTexture::Format backingFormat() const = 0;
+
+protected:
+    QRhiRenderBuffer(QRhiImplementation *rhi, Type type_, const QSize &pixelSize_,
+                     int sampleCount_, Flags flags_, QRhiTexture::Format backingFormatHint_);
+    Type m_type;
+    QSize m_pixelSize;
+    int m_sampleCount;
+    Flags m_flags;
+    QRhiTexture::Format m_backingFormatHint;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiRenderBuffer::Flags)
+
+class Q_GUI_EXPORT QRhiRenderPassDescriptor : public QRhiResource
+{
+public:
+    QRhiResource::Type resourceType() const override;
+
+    virtual bool isCompatible(const QRhiRenderPassDescriptor *other) const = 0;
+    virtual const QRhiNativeHandles *nativeHandles();
+
+    virtual QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const = 0;
+
+    virtual QVector<quint32> serializedFormat() const = 0;
+
+protected:
+    QRhiRenderPassDescriptor(QRhiImplementation *rhi);
+};
+
+class Q_GUI_EXPORT QRhiRenderTarget : public QRhiResource
+{
+public:
+    virtual QSize pixelSize() const = 0;
+    virtual float devicePixelRatio() const = 0;
+    virtual int sampleCount() const = 0;
+
+    QRhiRenderPassDescriptor *renderPassDescriptor() const { return m_renderPassDesc; }
+    void setRenderPassDescriptor(QRhiRenderPassDescriptor *desc) { m_renderPassDesc = desc; }
+
+protected:
+    QRhiRenderTarget(QRhiImplementation *rhi);
+    QRhiRenderPassDescriptor *m_renderPassDesc = nullptr;
+};
+
+class Q_GUI_EXPORT QRhiSwapChainRenderTarget : public QRhiRenderTarget
+{
+public:
+    QRhiResource::Type resourceType() const override;
+    QRhiSwapChain *swapChain() const { return m_swapchain; }
+
+protected:
+    QRhiSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain_);
+    QRhiSwapChain *m_swapchain;
+};
+
+class Q_GUI_EXPORT QRhiTextureRenderTarget : public QRhiRenderTarget
+{
+public:
+    enum Flag {
+        PreserveColorContents = 1 << 0,
+        PreserveDepthStencilContents = 1 << 1
+    };
+    Q_DECLARE_FLAGS(Flags, Flag)
+
+    QRhiResource::Type resourceType() const override;
+
+    QRhiTextureRenderTargetDescription description() const { return m_desc; }
+    void setDescription(const QRhiTextureRenderTargetDescription &desc) { m_desc = desc; }
+
+    Flags flags() const { return m_flags; }
+    void setFlags(Flags f) { m_flags = f; }
+
+    virtual QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() = 0;
+
+    virtual bool create() = 0;
+
+protected:
+    QRhiTextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc_, Flags flags_);
+    QRhiTextureRenderTargetDescription m_desc;
+    Flags m_flags;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiTextureRenderTarget::Flags)
+
+class Q_GUI_EXPORT QRhiShaderResourceBindings : public QRhiResource
+{
+public:
+    QRhiResource::Type resourceType() const override;
+
+    void setBindings(std::initializer_list<QRhiShaderResourceBinding> list) { m_bindings = list; }
+    template<typename InputIterator>
+    void setBindings(InputIterator first, InputIterator last)
+    {
+        m_bindings.clear();
+        std::copy(first, last, std::back_inserter(m_bindings));
+    }
+    const QRhiShaderResourceBinding *cbeginBindings() const { return m_bindings.cbegin(); }
+    const QRhiShaderResourceBinding *cendBindings() const { return m_bindings.cend(); }
+    const QRhiShaderResourceBinding *bindingAt(qsizetype index) const { return &m_bindings.at(index); }
+    qsizetype bindingCount() const { return m_bindings.count(); }
+
+    bool isLayoutCompatible(const QRhiShaderResourceBindings *other) const;
+
+    QVector<quint32> serializedLayoutDescription() const { return m_layoutDesc; }
+
+    virtual bool create() = 0;
+
+    enum UpdateFlag {
+        BindingsAreSorted = 0x01
+    };
+    Q_DECLARE_FLAGS(UpdateFlags, UpdateFlag)
+
+    virtual void updateResources(UpdateFlags flags = {}) = 0;
+
+protected:
+    static const int BINDING_PREALLOC = 12;
+    QRhiShaderResourceBindings(QRhiImplementation *rhi);
+    QVarLengthArray<QRhiShaderResourceBinding, BINDING_PREALLOC> m_bindings;
+    size_t m_layoutDescHash = 0;
+    // Intentionally not using QVLA for m_layoutDesc: clients like Qt Quick are much
+    // better served with an implicitly shared container here, because they will likely
+    // throw this directly into structs serving as cache keys.
+    QVector<quint32> m_layoutDesc;
+    friend class QRhiImplementation;
+#ifndef QT_NO_DEBUG_STREAM
+    friend Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiShaderResourceBindings &);
+#endif
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiShaderResourceBindings::UpdateFlags)
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiShaderResourceBindings &);
+#endif
+
+class Q_GUI_EXPORT QRhiGraphicsPipeline : public QRhiResource
+{
+public:
+    enum Flag {
+        UsesBlendConstants = 1 << 0,
+        UsesStencilRef = 1 << 1,
+        UsesScissor = 1 << 2,
+        CompileShadersWithDebugInfo = 1 << 3
+    };
+    Q_DECLARE_FLAGS(Flags, Flag)
+
+    enum Topology {
+        Triangles,
+        TriangleStrip,
+        TriangleFan,
+        Lines,
+        LineStrip,
+        Points,
+        Patches
+    };
+
+    enum CullMode {
+        None,
+        Front,
+        Back
+    };
+
+    enum FrontFace {
+        CCW,
+        CW
+    };
+
+    enum ColorMaskComponent {
+        R = 1 << 0,
+        G = 1 << 1,
+        B = 1 << 2,
+        A = 1 << 3
+    };
+    Q_DECLARE_FLAGS(ColorMask, ColorMaskComponent)
+
+    enum BlendFactor {
+        Zero,
+        One,
+        SrcColor,
+        OneMinusSrcColor,
+        DstColor,
+        OneMinusDstColor,
+        SrcAlpha,
+        OneMinusSrcAlpha,
+        DstAlpha,
+        OneMinusDstAlpha,
+        ConstantColor,
+        OneMinusConstantColor,
+        ConstantAlpha,
+        OneMinusConstantAlpha,
+        SrcAlphaSaturate,
+        Src1Color,
+        OneMinusSrc1Color,
+        Src1Alpha,
+        OneMinusSrc1Alpha
+    };
+
+    enum BlendOp {
+        Add,
+        Subtract,
+        ReverseSubtract,
+        Min,
+        Max
+    };
+
+    struct TargetBlend {
+        ColorMask colorWrite = ColorMask(0xF); // R | G | B | A
+        bool enable = false;
+        BlendFactor srcColor = One;
+        BlendFactor dstColor = OneMinusSrcAlpha;
+        BlendOp opColor = Add;
+        BlendFactor srcAlpha = One;
+        BlendFactor dstAlpha = OneMinusSrcAlpha;
+        BlendOp opAlpha = Add;
+    };
+
+    enum CompareOp {
+        Never,
+        Less,
+        Equal,
+        LessOrEqual,
+        Greater,
+        NotEqual,
+        GreaterOrEqual,
+        Always
+    };
+
+    enum StencilOp {
+        StencilZero,
+        Keep,
+        Replace,
+        IncrementAndClamp,
+        DecrementAndClamp,
+        Invert,
+        IncrementAndWrap,
+        DecrementAndWrap
+    };
+
+    struct StencilOpState {
+        StencilOp failOp = Keep;
+        StencilOp depthFailOp = Keep;
+        StencilOp passOp = Keep;
+        CompareOp compareOp = Always;
+    };
+
+    enum PolygonMode {
+        Fill,
+        Line
+    };
+
+    QRhiResource::Type resourceType() const override;
+
+    Flags flags() const { return m_flags; }
+    void setFlags(Flags f) { m_flags = f; }
+
+    Topology topology() const { return m_topology; }
+    void setTopology(Topology t) { m_topology = t; }
+
+    CullMode cullMode() const { return m_cullMode; }
+    void setCullMode(CullMode mode) { m_cullMode = mode; }
+
+    FrontFace frontFace() const { return m_frontFace; }
+    void setFrontFace(FrontFace f) { m_frontFace = f; }
+
+    void setTargetBlends(std::initializer_list<TargetBlend> list) { m_targetBlends = list; }
+    template<typename InputIterator>
+    void setTargetBlends(InputIterator first, InputIterator last)
+    {
+        m_targetBlends.clear();
+        std::copy(first, last, std::back_inserter(m_targetBlends));
+    }
+    const TargetBlend *cbeginTargetBlends() const { return m_targetBlends.cbegin(); }
+    const TargetBlend *cendTargetBlends() const { return m_targetBlends.cend(); }
+    const TargetBlend *targetBlendAt(qsizetype index) const { return &m_targetBlends.at(index); }
+    qsizetype targetBlendCount() const { return m_targetBlends.count(); }
+
+    bool hasDepthTest() const { return m_depthTest; }
+    void setDepthTest(bool enable) { m_depthTest = enable; }
+
+    bool hasDepthWrite() const { return m_depthWrite; }
+    void setDepthWrite(bool enable) { m_depthWrite = enable; }
+
+    CompareOp depthOp() const { return m_depthOp; }
+    void setDepthOp(CompareOp op) { m_depthOp = op; }
+
+    bool hasStencilTest() const { return m_stencilTest; }
+    void setStencilTest(bool enable) { m_stencilTest = enable; }
+
+    StencilOpState stencilFront() const { return m_stencilFront; }
+    void setStencilFront(const StencilOpState &state) { m_stencilFront = state; }
+
+    StencilOpState stencilBack() const { return m_stencilBack; }
+    void setStencilBack(const StencilOpState &state) { m_stencilBack = state; }
+
+    quint32 stencilReadMask() const { return m_stencilReadMask; }
+    void setStencilReadMask(quint32 mask) { m_stencilReadMask = mask; }
+
+    quint32 stencilWriteMask() const { return m_stencilWriteMask; }
+    void setStencilWriteMask(quint32 mask) { m_stencilWriteMask = mask; }
+
+    int sampleCount() const { return m_sampleCount; }
+    void setSampleCount(int s) { m_sampleCount = s; }
+
+    float lineWidth() const { return m_lineWidth; }
+    void setLineWidth(float width) { m_lineWidth = width; }
+
+    int depthBias() const { return m_depthBias; }
+    void setDepthBias(int bias) { m_depthBias = bias; }
+
+    float slopeScaledDepthBias() const { return m_slopeScaledDepthBias; }
+    void setSlopeScaledDepthBias(float bias) { m_slopeScaledDepthBias = bias; }
+
+    void setShaderStages(std::initializer_list<QRhiShaderStage> list) { m_shaderStages = list; }
+    template<typename InputIterator>
+    void setShaderStages(InputIterator first, InputIterator last)
+    {
+        m_shaderStages.clear();
+        std::copy(first, last, std::back_inserter(m_shaderStages));
+    }
+    const QRhiShaderStage *cbeginShaderStages() const { return m_shaderStages.cbegin(); }
+    const QRhiShaderStage *cendShaderStages() const { return m_shaderStages.cend(); }
+    const QRhiShaderStage *shaderStageAt(qsizetype index) const { return &m_shaderStages.at(index); }
+    qsizetype shaderStageCount() const { return m_shaderStages.count(); }
+
+    QRhiVertexInputLayout vertexInputLayout() const { return m_vertexInputLayout; }
+    void setVertexInputLayout(const QRhiVertexInputLayout &layout) { m_vertexInputLayout = layout; }
+
+    QRhiShaderResourceBindings *shaderResourceBindings() const { return m_shaderResourceBindings; }
+    void setShaderResourceBindings(QRhiShaderResourceBindings *srb) { m_shaderResourceBindings = srb; }
+
+    QRhiRenderPassDescriptor *renderPassDescriptor() const { return m_renderPassDesc; }
+    void setRenderPassDescriptor(QRhiRenderPassDescriptor *desc) { m_renderPassDesc = desc; }
+
+    int patchControlPointCount() const { return m_patchControlPointCount; }
+    void setPatchControlPointCount(int count) { m_patchControlPointCount = count; }
+
+    PolygonMode polygonMode() const {return m_polygonMode; }
+    void setPolygonMode(PolygonMode mode) {m_polygonMode = mode; }
+
+    virtual bool create() = 0;
+
+protected:
+    QRhiGraphicsPipeline(QRhiImplementation *rhi);
+    Flags m_flags;
+    Topology m_topology = Triangles;
+    CullMode m_cullMode = None;
+    FrontFace m_frontFace = CCW;
+    QVarLengthArray<TargetBlend, 8> m_targetBlends;
+    bool m_depthTest = false;
+    bool m_depthWrite = false;
+    CompareOp m_depthOp = Less;
+    bool m_stencilTest = false;
+    StencilOpState m_stencilFront;
+    StencilOpState m_stencilBack;
+    quint32 m_stencilReadMask = 0xFF;
+    quint32 m_stencilWriteMask = 0xFF;
+    int m_sampleCount = 1;
+    float m_lineWidth = 1.0f;
+    int m_depthBias = 0;
+    float m_slopeScaledDepthBias = 0.0f;
+    int m_patchControlPointCount = 3;
+    PolygonMode m_polygonMode = Fill;
+    QVarLengthArray<QRhiShaderStage, 4> m_shaderStages;
+    QRhiVertexInputLayout m_vertexInputLayout;
+    QRhiShaderResourceBindings *m_shaderResourceBindings = nullptr;
+    QRhiRenderPassDescriptor *m_renderPassDesc = nullptr;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiGraphicsPipeline::Flags)
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiGraphicsPipeline::ColorMask)
+Q_DECLARE_TYPEINFO(QRhiGraphicsPipeline::TargetBlend, Q_RELOCATABLE_TYPE);
+
+struct QRhiSwapChainHdrInfo
+{
+    bool isHardCodedDefaults;
+    enum LimitsType {
+        LuminanceInNits,
+        ColorComponentValue
+    };
+    LimitsType limitsType;
+    union {
+        struct {
+            float minLuminance;
+            float maxLuminance;
+        } luminanceInNits;
+        struct {
+            float maxColorComponentValue;
+        } colorComponentValue;
+    } limits;
+};
+
+Q_DECLARE_TYPEINFO(QRhiSwapChainHdrInfo, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiSwapChainHdrInfo &);
+#endif
+
+struct QRhiSwapChainProxyData
+{
+    void *reserved[2] = {};
+};
+
+class Q_GUI_EXPORT QRhiSwapChain : public QRhiResource
+{
+public:
+    enum Flag {
+        SurfaceHasPreMulAlpha = 1 << 0,
+        SurfaceHasNonPreMulAlpha = 1 << 1,
+        sRGB = 1 << 2,
+        UsedAsTransferSource = 1 << 3,
+        NoVSync = 1 << 4,
+        MinimalBufferCount = 1 << 5
+    };
+    Q_DECLARE_FLAGS(Flags, Flag)
+
+    enum Format {
+        SDR,
+        HDRExtendedSrgbLinear,
+        HDR10
+    };
+
+    enum StereoTargetBuffer {
+        LeftBuffer,
+        RightBuffer
+    };
+
+    QRhiResource::Type resourceType() const override;
+
+    QWindow *window() const { return m_window; }
+    void setWindow(QWindow *window) { m_window = window; }
+
+    QRhiSwapChainProxyData proxyData() const { return m_proxyData; }
+    void setProxyData(const QRhiSwapChainProxyData &d) { m_proxyData = d; }
+
+    Flags flags() const { return m_flags; }
+    void setFlags(Flags f) { m_flags = f; }
+
+    Format format() const { return m_format; }
+    void setFormat(Format f) { m_format = f; }
+
+    QRhiRenderBuffer *depthStencil() const { return m_depthStencil; }
+    void setDepthStencil(QRhiRenderBuffer *ds) { m_depthStencil = ds; }
+
+    int sampleCount() const { return m_sampleCount; }
+    void setSampleCount(int samples) { m_sampleCount = samples; }
+
+    QRhiRenderPassDescriptor *renderPassDescriptor() const { return m_renderPassDesc; }
+    void setRenderPassDescriptor(QRhiRenderPassDescriptor *desc) { m_renderPassDesc = desc; }
+
+    QSize currentPixelSize() const { return m_currentPixelSize; }
+
+    virtual QRhiCommandBuffer *currentFrameCommandBuffer() = 0;
+    virtual QRhiRenderTarget *currentFrameRenderTarget() = 0;
+    virtual QRhiRenderTarget *currentFrameRenderTarget(StereoTargetBuffer targetBuffer);
+    virtual QSize surfacePixelSize() = 0;
+    virtual bool isFormatSupported(Format f) = 0;
+    virtual QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() = 0;
+    virtual bool createOrResize() = 0;
+    virtual QRhiSwapChainHdrInfo hdrInfo();
+
+protected:
+    QRhiSwapChain(QRhiImplementation *rhi);
+    QWindow *m_window = nullptr;
+    Flags m_flags;
+    Format m_format = SDR;
+    QRhiRenderBuffer *m_depthStencil = nullptr;
+    int m_sampleCount = 1;
+    QRhiRenderPassDescriptor *m_renderPassDesc = nullptr;
+    QSize m_currentPixelSize;
+    QRhiSwapChainProxyData m_proxyData;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiSwapChain::Flags)
+
+class Q_GUI_EXPORT QRhiComputePipeline : public QRhiResource
+{
+public:
+    enum Flag {
+        CompileShadersWithDebugInfo = 1 << 0
+    };
+    Q_DECLARE_FLAGS(Flags, Flag)
+
+    QRhiResource::Type resourceType() const override;
+    virtual bool create() = 0;
+
+    Flags flags() const { return m_flags; }
+    void setFlags(Flags f) { m_flags = f; }
+
+    QRhiShaderStage shaderStage() const { return m_shaderStage; }
+    void setShaderStage(const QRhiShaderStage &stage) { m_shaderStage = stage; }
+
+    QRhiShaderResourceBindings *shaderResourceBindings() const { return m_shaderResourceBindings; }
+    void setShaderResourceBindings(QRhiShaderResourceBindings *srb) { m_shaderResourceBindings = srb; }
+
+protected:
+    QRhiComputePipeline(QRhiImplementation *rhi);
+    Flags m_flags;
+    QRhiShaderStage m_shaderStage;
+    QRhiShaderResourceBindings *m_shaderResourceBindings = nullptr;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiComputePipeline::Flags)
+
+class Q_GUI_EXPORT QRhiCommandBuffer : public QRhiResource
+{
+public:
+    enum IndexFormat {
+        IndexUInt16,
+        IndexUInt32
+    };
+
+    enum BeginPassFlag {
+        ExternalContent = 0x01,
+        DoNotTrackResourcesForCompute = 0x02
+    };
+    Q_DECLARE_FLAGS(BeginPassFlags, BeginPassFlag)
+
+    QRhiResource::Type resourceType() const override;
+
+    void resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates);
+
+    void beginPass(QRhiRenderTarget *rt,
+                   const QColor &colorClearValue,
+                   const QRhiDepthStencilClearValue &depthStencilClearValue,
+                   QRhiResourceUpdateBatch *resourceUpdates = nullptr,
+                   BeginPassFlags flags = {});
+    void endPass(QRhiResourceUpdateBatch *resourceUpdates = nullptr);
+
+    void setGraphicsPipeline(QRhiGraphicsPipeline *ps);
+    using DynamicOffset = QPair<int, quint32>; // binding, offset
+    void setShaderResources(QRhiShaderResourceBindings *srb = nullptr,
+                            int dynamicOffsetCount = 0,
+                            const DynamicOffset *dynamicOffsets = nullptr);
+    using VertexInput = QPair<QRhiBuffer *, quint32>; // buffer, offset
+    void setVertexInput(int startBinding, int bindingCount, const VertexInput *bindings,
+                        QRhiBuffer *indexBuf = nullptr, quint32 indexOffset = 0,
+                        IndexFormat indexFormat = IndexUInt16);
+
+    void setViewport(const QRhiViewport &viewport);
+    void setScissor(const QRhiScissor &scissor);
+    void setBlendConstants(const QColor &c);
+    void setStencilRef(quint32 refValue);
+
+    void draw(quint32 vertexCount,
+              quint32 instanceCount = 1,
+              quint32 firstVertex = 0,
+              quint32 firstInstance = 0);
+
+    void drawIndexed(quint32 indexCount,
+                     quint32 instanceCount = 1,
+                     quint32 firstIndex = 0,
+                     qint32 vertexOffset = 0,
+                     quint32 firstInstance = 0);
+
+    void debugMarkBegin(const QByteArray &name);
+    void debugMarkEnd();
+    void debugMarkMsg(const QByteArray &msg);
+
+    void beginComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr, BeginPassFlags flags = {});
+    void endComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr);
+    void setComputePipeline(QRhiComputePipeline *ps);
+    void dispatch(int x, int y, int z);
+
+    const QRhiNativeHandles *nativeHandles();
+    void beginExternal();
+    void endExternal();
+
+    double lastCompletedGpuTime();
+
+protected:
+    QRhiCommandBuffer(QRhiImplementation *rhi);
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiCommandBuffer::BeginPassFlags)
+
+struct Q_GUI_EXPORT QRhiReadbackResult
+{
+    std::function<void()> completed = nullptr;
+    QRhiTexture::Format format;
+    QSize pixelSize;
+    QByteArray data;
+};
+
+class Q_GUI_EXPORT QRhiResourceUpdateBatch
+{
+public:
+    ~QRhiResourceUpdateBatch();
+
+    void release();
+
+    void merge(QRhiResourceUpdateBatch *other);
+    bool hasOptimalCapacity() const;
+
+    void updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data);
+    void uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data);
+    void uploadStaticBuffer(QRhiBuffer *buf, const void *data);
+    void readBackBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result);
+    void uploadTexture(QRhiTexture *tex, const QRhiTextureUploadDescription &desc);
+    void uploadTexture(QRhiTexture *tex, const QImage &image);
+    void copyTexture(QRhiTexture *dst, QRhiTexture *src, const QRhiTextureCopyDescription &desc = QRhiTextureCopyDescription());
+    void readBackTexture(const QRhiReadbackDescription &rb, QRhiReadbackResult *result);
+    void generateMips(QRhiTexture *tex);
+
+private:
+    QRhiResourceUpdateBatch(QRhiImplementation *rhi);
+    Q_DISABLE_COPY(QRhiResourceUpdateBatch)
+    QRhiResourceUpdateBatchPrivate *d;
+    friend class QRhiResourceUpdateBatchPrivate;
+    friend class QRhi;
+};
+
+struct Q_GUI_EXPORT QRhiDriverInfo
+{
+    enum DeviceType {
+        UnknownDevice,
+        IntegratedDevice,
+        DiscreteDevice,
+        ExternalDevice,
+        VirtualDevice,
+        CpuDevice
+    };
+
+    QByteArray deviceName;
+    quint64 deviceId = 0;
+    quint64 vendorId = 0;
+    DeviceType deviceType = UnknownDevice;
+};
+
+Q_DECLARE_TYPEINFO(QRhiDriverInfo, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiDriverInfo &);
+#endif
+
+struct Q_GUI_EXPORT QRhiStats
+{
+    qint64 totalPipelineCreationTime = 0;
+    // Vulkan or D3D12 memory allocator statistics
+    quint32 blockCount = 0;
+    quint32 allocCount = 0;
+    quint64 usedBytes = 0;
+    quint64 unusedBytes = 0;
+    // D3D12 only, from IDXGIAdapter3::QueryVideoMemoryInfo(), incl. all resources
+    quint64 totalUsageBytes = 0;
+};
+
+Q_DECLARE_TYPEINFO(QRhiStats, Q_RELOCATABLE_TYPE);
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiStats &);
+#endif
+
+struct Q_GUI_EXPORT QRhiInitParams
+{
+};
+
+class Q_GUI_EXPORT QRhi
+{
+public:
+    enum Implementation {
+        Null,
+        Vulkan,
+        OpenGLES2,
+        D3D11,
+        Metal,
+        D3D12
+    };
+
+    enum Flag {
+        EnableDebugMarkers = 1 << 0,
+        PreferSoftwareRenderer = 1 << 1,
+        EnablePipelineCacheDataSave = 1 << 2,
+        EnableTimestamps = 1 << 3
+    };
+    Q_DECLARE_FLAGS(Flags, Flag)
+
+    enum FrameOpResult {
+        FrameOpSuccess = 0,
+        FrameOpError,
+        FrameOpSwapChainOutOfDate,
+        FrameOpDeviceLost
+    };
+
+    enum Feature {
+        MultisampleTexture = 1,
+        MultisampleRenderBuffer,
+        DebugMarkers,
+        Timestamps,
+        Instancing,
+        CustomInstanceStepRate,
+        PrimitiveRestart,
+        NonDynamicUniformBuffers,
+        NonFourAlignedEffectiveIndexBufferOffset,
+        NPOTTextureRepeat,
+        RedOrAlpha8IsRed,
+        ElementIndexUint,
+        Compute,
+        WideLines,
+        VertexShaderPointSize,
+        BaseVertex,
+        BaseInstance,
+        TriangleFanTopology,
+        ReadBackNonUniformBuffer,
+        ReadBackNonBaseMipLevel,
+        TexelFetch,
+        RenderToNonBaseMipLevel,
+        IntAttributes,
+        ScreenSpaceDerivatives,
+        ReadBackAnyTextureFormat,
+        PipelineCacheDataLoadSave,
+        ImageDataStride,
+        RenderBufferImport,
+        ThreeDimensionalTextures,
+        RenderTo3DTextureSlice,
+        TextureArrays,
+        Tessellation,
+        GeometryShader,
+        TextureArrayRange,
+        NonFillPolygonMode,
+        OneDimensionalTextures,
+        OneDimensionalTextureMipmaps,
+        HalfAttributes,
+        RenderToOneDimensionalTexture,
+        ThreeDimensionalTextureMipmaps
+    };
+
+    enum BeginFrameFlag {
+    };
+    Q_DECLARE_FLAGS(BeginFrameFlags, BeginFrameFlag)
+
+    enum EndFrameFlag {
+        SkipPresent = 1 << 0
+    };
+    Q_DECLARE_FLAGS(EndFrameFlags, EndFrameFlag)
+
+    enum ResourceLimit {
+        TextureSizeMin = 1,
+        TextureSizeMax,
+        MaxColorAttachments,
+        FramesInFlight,
+        MaxAsyncReadbackFrames,
+        MaxThreadGroupsPerDimension,
+        MaxThreadsPerThreadGroup,
+        MaxThreadGroupX,
+        MaxThreadGroupY,
+        MaxThreadGroupZ,
+        TextureArraySizeMax,
+        MaxUniformBufferRange,
+        MaxVertexInputs,
+        MaxVertexOutputs
+    };
+
+    ~QRhi();
+
+    static QRhi *create(Implementation impl,
+                        QRhiInitParams *params,
+                        Flags flags = {},
+                        QRhiNativeHandles *importDevice = nullptr);
+    static bool probe(Implementation impl, QRhiInitParams *params);
+
+    Implementation backend() const;
+    const char *backendName() const;
+    static const char *backendName(Implementation impl);
+    QRhiDriverInfo driverInfo() const;
+    QThread *thread() const;
+
+    using CleanupCallback = std::function<void(QRhi *)>;
+    void addCleanupCallback(const CleanupCallback &callback);
+    void runCleanup();
+
+    QRhiGraphicsPipeline *newGraphicsPipeline();
+    QRhiComputePipeline *newComputePipeline();
+    QRhiShaderResourceBindings *newShaderResourceBindings();
+
+    QRhiBuffer *newBuffer(QRhiBuffer::Type type,
+                          QRhiBuffer::UsageFlags usage,
+                          quint32 size);
+
+    QRhiRenderBuffer *newRenderBuffer(QRhiRenderBuffer::Type type,
+                                      const QSize &pixelSize,
+                                      int sampleCount = 1,
+                                      QRhiRenderBuffer::Flags flags = {},
+                                      QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat);
+
+    QRhiTexture *newTexture(QRhiTexture::Format format,
+                            const QSize &pixelSize,
+                            int sampleCount = 1,
+                            QRhiTexture::Flags flags = {});
+
+    QRhiTexture *newTexture(QRhiTexture::Format format,
+                            int width, int height, int depth,
+                            int sampleCount = 1,
+                            QRhiTexture::Flags flags = {});
+
+    QRhiTexture *newTextureArray(QRhiTexture::Format format,
+                                 int arraySize,
+                                 const QSize &pixelSize,
+                                 int sampleCount = 1,
+                                 QRhiTexture::Flags flags = {});
+
+    QRhiSampler *newSampler(QRhiSampler::Filter magFilter,
+                            QRhiSampler::Filter minFilter,
+                            QRhiSampler::Filter mipmapMode,
+                            QRhiSampler::AddressMode addressU,
+                            QRhiSampler::AddressMode addressV,
+                            QRhiSampler::AddressMode addressW = QRhiSampler::Repeat);
+
+    QRhiTextureRenderTarget *newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
+                                                    QRhiTextureRenderTarget::Flags flags = {});
+
+    QRhiSwapChain *newSwapChain();
+    FrameOpResult beginFrame(QRhiSwapChain *swapChain, BeginFrameFlags flags = {});
+    FrameOpResult endFrame(QRhiSwapChain *swapChain, EndFrameFlags flags = {});
+    bool isRecordingFrame() const;
+    int currentFrameSlot() const;
+
+    FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, BeginFrameFlags flags = {});
+    FrameOpResult endOffscreenFrame(EndFrameFlags flags = {});
+
+    QRhi::FrameOpResult finish();
+
+    QRhiResourceUpdateBatch *nextResourceUpdateBatch();
+
+    QList<int> supportedSampleCounts() const;
+
+    int ubufAlignment() const;
+    int ubufAligned(int v) const;
+
+    static int mipLevelsForSize(const QSize &size);
+    static QSize sizeForMipLevel(int mipLevel, const QSize &baseLevelSize);
+
+    bool isYUpInFramebuffer() const;
+    bool isYUpInNDC() const;
+    bool isClipDepthZeroToOne() const;
+
+    QMatrix4x4 clipSpaceCorrMatrix() const;
+
+    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const;
+    bool isFeatureSupported(QRhi::Feature feature) const;
+    int resourceLimit(ResourceLimit limit) const;
+
+    const QRhiNativeHandles *nativeHandles();
+    bool makeThreadLocalNativeContextCurrent();
+
+    static const int MAX_MIP_LEVELS = 16; // -> max width or height is 65536
+
+    void releaseCachedResources();
+
+    bool isDeviceLost() const;
+
+    QByteArray pipelineCacheData();
+    void setPipelineCacheData(const QByteArray &data);
+
+    QRhiStats statistics() const;
+
+    static QRhiSwapChainProxyData updateSwapChainProxyData(Implementation impl, QWindow *window);
+
+protected:
+    QRhi();
+
+private:
+    Q_DISABLE_COPY(QRhi)
+    QRhiImplementation *d = nullptr;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhi::Flags)
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhi::BeginFrameFlags)
+Q_DECLARE_OPERATORS_FOR_FLAGS(QRhi::EndFrameFlags)
+
+QT_END_NAMESPACE
+
+#include <rhi/qrhi_platform.h>
+
+#endif
diff --git a/src/gui/rhi/qrhi_p.h b/src/gui/rhi/qrhi_p.h
index 4af1dc746f..05df169a35 100644
--- a/src/gui/rhi/qrhi_p.h
+++ b/src/gui/rhi/qrhi_p.h
@@ -1,8 +1,8 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#ifndef QRHI_H
-#define QRHI_H
+#ifndef QRHI_P_H
+#define QRHI_P_H
 
 //
 //  W A R N I N G
@@ -15,1958 +15,789 @@
 // We mean it.
 //
 
-#include <QtGui/qtguiglobal.h>
-#include <QSize>
-#include <QMatrix4x4>
-#include <QList>
-#include <QVarLengthArray>
-#include <QThread>
-#include <QColor>
-#include <QImage>
-#include <functional>
-#include <array>
-#include <private/qshader_p.h>
+#include <rhi/qrhi.h>
+#include <QBitArray>
+#include <QAtomicInt>
+#include <QElapsedTimer>
+#include <QLoggingCategory>
+#include <QtCore/qset.h>
+#include <QtCore/qvarlengtharray.h>
 
 QT_BEGIN_NAMESPACE
 
-class QWindow;
-class QRhi;
-class QRhiImplementation;
-class QRhiBuffer;
-class QRhiRenderBuffer;
-class QRhiTexture;
-class QRhiSampler;
-class QRhiCommandBuffer;
-class QRhiResourceUpdateBatch;
-class QRhiResourceUpdateBatchPrivate;
-class QRhiSwapChain;
-
-class Q_GUI_EXPORT QRhiDepthStencilClearValue
-{
-public:
-    QRhiDepthStencilClearValue() = default;
-    QRhiDepthStencilClearValue(float d, quint32 s);
+#define QRHI_RES(t, x) static_cast<t *>(x)
+#define QRHI_RES_RHI(t) t *rhiD = static_cast<t *>(m_rhi)
 
-    float depthClearValue() const { return m_d; }
-    void setDepthClearValue(float d) { m_d = d; }
+Q_DECLARE_LOGGING_CATEGORY(QRHI_LOG_INFO)
 
-    quint32 stencilClearValue() const { return m_s; }
-    void setStencilClearValue(quint32 s) { m_s = s; }
+class QRhiImplementation
+{
+public:
+    virtual ~QRhiImplementation();
 
-private:
-    float m_d = 1.0f;
-    quint32 m_s = 0;
+    virtual bool create(QRhi::Flags flags) = 0;
+    virtual void destroy() = 0;
 
-    friend bool operator==(const QRhiDepthStencilClearValue &a, const QRhiDepthStencilClearValue &b) noexcept
+    virtual QRhiGraphicsPipeline *createGraphicsPipeline() = 0;
+    virtual QRhiComputePipeline *createComputePipeline() = 0;
+    virtual QRhiShaderResourceBindings *createShaderResourceBindings() = 0;
+    virtual QRhiBuffer *createBuffer(QRhiBuffer::Type type,
+                                     QRhiBuffer::UsageFlags usage,
+                                     quint32 size) = 0;
+    virtual QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
+                                                 const QSize &pixelSize,
+                                                 int sampleCount,
+                                                 QRhiRenderBuffer::Flags flags,
+                                                 QRhiTexture::Format backingFormatHint) = 0;
+    virtual QRhiTexture *createTexture(QRhiTexture::Format format,
+                                       const QSize &pixelSize,
+                                       int depth,
+                                       int arraySize,
+                                       int sampleCount,
+                                       QRhiTexture::Flags flags) = 0;
+    virtual QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
+                                       QRhiSampler::Filter minFilter,
+                                       QRhiSampler::Filter mipmapMode,
+                                       QRhiSampler:: AddressMode u,
+                                       QRhiSampler::AddressMode v,
+                                       QRhiSampler::AddressMode w) = 0;
+
+    virtual QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
+                                                               QRhiTextureRenderTarget::Flags flags) = 0;
+
+    virtual QRhiSwapChain *createSwapChain() = 0;
+    virtual QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) = 0;
+    virtual QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) = 0;
+    virtual QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) = 0;
+    virtual QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) = 0;
+    virtual QRhi::FrameOpResult finish() = 0;
+
+    virtual void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) = 0;
+
+    virtual void beginPass(QRhiCommandBuffer *cb,
+                           QRhiRenderTarget *rt,
+                           const QColor &colorClearValue,
+                           const QRhiDepthStencilClearValue &depthStencilClearValue,
+                           QRhiResourceUpdateBatch *resourceUpdates,
+                           QRhiCommandBuffer::BeginPassFlags flags) = 0;
+    virtual void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) = 0;
+
+    virtual void setGraphicsPipeline(QRhiCommandBuffer *cb,
+                                     QRhiGraphicsPipeline *ps) = 0;
+
+    virtual void setShaderResources(QRhiCommandBuffer *cb,
+                                    QRhiShaderResourceBindings *srb,
+                                    int dynamicOffsetCount,
+                                    const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) = 0;
+
+    virtual void setVertexInput(QRhiCommandBuffer *cb,
+                                int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
+                                QRhiBuffer *indexBuf, quint32 indexOffset,
+                                QRhiCommandBuffer::IndexFormat indexFormat) = 0;
+
+    virtual void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) = 0;
+    virtual void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) = 0;
+    virtual void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) = 0;
+    virtual void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) = 0;
+
+    virtual void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
+                      quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) = 0;
+    virtual void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
+                             quint32 instanceCount, quint32 firstIndex,
+                             qint32 vertexOffset, quint32 firstInstance) = 0;
+
+    virtual void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) = 0;
+    virtual void debugMarkEnd(QRhiCommandBuffer *cb) = 0;
+    virtual void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) = 0;
+
+    virtual void beginComputePass(QRhiCommandBuffer *cb,
+                                  QRhiResourceUpdateBatch *resourceUpdates,
+                                  QRhiCommandBuffer::BeginPassFlags flags) = 0;
+    virtual void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) = 0;
+    virtual void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) = 0;
+    virtual void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) = 0;
+
+    virtual const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) = 0;
+    virtual void beginExternal(QRhiCommandBuffer *cb) = 0;
+    virtual void endExternal(QRhiCommandBuffer *cb) = 0;
+    virtual double lastCompletedGpuTime(QRhiCommandBuffer *cb) = 0;
+
+    virtual QList<int> supportedSampleCounts() const = 0;
+    virtual int ubufAlignment() const = 0;
+    virtual bool isYUpInFramebuffer() const = 0;
+    virtual bool isYUpInNDC() const = 0;
+    virtual bool isClipDepthZeroToOne() const = 0;
+    virtual QMatrix4x4 clipSpaceCorrMatrix() const = 0;
+    virtual bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const = 0;
+    virtual bool isFeatureSupported(QRhi::Feature feature) const = 0;
+    virtual int resourceLimit(QRhi::ResourceLimit limit) const = 0;
+    virtual const QRhiNativeHandles *nativeHandles() = 0;
+    virtual QRhiDriverInfo driverInfo() const = 0;
+    virtual QRhiStats statistics() = 0;
+    virtual bool makeThreadLocalNativeContextCurrent() = 0;
+    virtual void releaseCachedResources() = 0;
+    virtual bool isDeviceLost() const = 0;
+
+    virtual QByteArray pipelineCacheData() = 0;
+    virtual void setPipelineCacheData(const QByteArray &data) = 0;
+
+    void prepareForCreate(QRhi *rhi, QRhi::Implementation impl, QRhi::Flags flags);
+
+    bool isCompressedFormat(QRhiTexture::Format format) const;
+    void compressedFormatInfo(QRhiTexture::Format format, const QSize &size,
+                              quint32 *bpl, quint32 *byteSize,
+                              QSize *blockDim) const;
+    void textureFormatInfo(QRhiTexture::Format format, const QSize &size,
+                           quint32 *bpl, quint32 *byteSize, quint32 *bytesPerPixel) const;
+
+    void registerResource(QRhiResource *res, bool ownsNativeResources = true)
     {
-        return a.m_d == b.m_d && a.m_s == b.m_s;
+        // The ownsNativeResources is relevant for the (graphics resource) leak
+        // check in ~QRhiImplementation; when false, the registration's sole
+        // purpose is to automatically null out the resource's m_rhi pointer in
+        // case the rhi goes away first. (which should not happen in
+        // well-written applications but we try to be graceful)
+        resources.insert(res, ownsNativeResources);
     }
 
-    friend bool operator!=(const QRhiDepthStencilClearValue &a, const QRhiDepthStencilClearValue &b) noexcept
+    void unregisterResource(QRhiResource *res)
     {
-        return !(a == b);
+        resources.remove(res);
     }
 
-    friend size_t qHash(const QRhiDepthStencilClearValue &v, size_t seed = 0) noexcept
+    void addDeleteLater(QRhiResource *res)
     {
-        QtPrivate::QHashCombine hash;
-        seed = hash(seed, v.m_d);
-        seed = hash(seed, v.m_s);
-        return seed;
+        if (inFrame)
+            pendingDeleteResources.insert(res);
+        else
+            delete res;
     }
-};
-
-Q_DECLARE_TYPEINFO(QRhiDepthStencilClearValue, Q_RELOCATABLE_TYPE);
 
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiDepthStencilClearValue &);
-#endif
-
-class Q_GUI_EXPORT QRhiViewport
-{
-public:
-    QRhiViewport() = default;
-    QRhiViewport(float x, float y, float w, float h, float minDepth = 0.0f, float maxDepth = 1.0f);
-
-    std::array<float, 4> viewport() const { return m_rect; }
-    void setViewport(float x, float y, float w, float h) {
-        m_rect[0] = x; m_rect[1] = y; m_rect[2] = w; m_rect[3] = h;
+    void addCleanupCallback(const QRhi::CleanupCallback &callback)
+    {
+        cleanupCallbacks.append(callback);
     }
 
-    float minDepth() const { return m_minDepth; }
-    void setMinDepth(float minDepth) { m_minDepth = minDepth; }
-
-    float maxDepth() const { return m_maxDepth; }
-    void setMaxDepth(float maxDepth) { m_maxDepth = maxDepth; }
+    bool sanityCheckGraphicsPipeline(QRhiGraphicsPipeline *ps);
+    bool sanityCheckShaderResourceBindings(QRhiShaderResourceBindings *srb);
+    void updateLayoutDesc(QRhiShaderResourceBindings *srb);
 
-private:
-    std::array<float, 4> m_rect { { 0.0f, 0.0f, 0.0f, 0.0f } };
-    float m_minDepth = 0.0f;
-    float m_maxDepth = 1.0f;
-
-    friend bool operator==(const QRhiViewport &a, const QRhiViewport &b) noexcept
+    quint32 pipelineCacheRhiId() const
     {
-        return a.m_rect == b.m_rect
-                && a.m_minDepth == b.m_minDepth
-                && a.m_maxDepth == b.m_maxDepth;
+        const quint32 ver = (QT_VERSION_MAJOR << 16) | (QT_VERSION_MINOR << 8) | (QT_VERSION_PATCH);
+        return (quint32(implType) << 24) | ver;
     }
 
-    friend bool operator!=(const QRhiViewport &a, const QRhiViewport &b) noexcept
+    void pipelineCreationStart()
     {
-        return !(a == b);
+        pipelineCreationTimer.start();
     }
 
-    friend size_t qHash(const QRhiViewport &v, size_t seed = 0) noexcept
+    void pipelineCreationEnd()
     {
-        QtPrivate::QHashCombine hash;
-        seed = hash(seed, v.m_rect[0]);
-        seed = hash(seed, v.m_rect[1]);
-        seed = hash(seed, v.m_rect[2]);
-        seed = hash(seed, v.m_rect[3]);
-        seed = hash(seed, v.m_minDepth);
-        seed = hash(seed, v.m_maxDepth);
-        return seed;
+        accumulatedPipelineCreationTime += pipelineCreationTimer.elapsed();
     }
-};
-
-Q_DECLARE_TYPEINFO(QRhiViewport, Q_RELOCATABLE_TYPE);
 
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiViewport &);
-#endif
-
-class Q_GUI_EXPORT QRhiScissor
-{
-public:
-    QRhiScissor() = default;
-    QRhiScissor(int x, int y, int w, int h);
-
-    std::array<int, 4> scissor() const { return m_rect; }
-    void setScissor(int x, int y, int w, int h) {
-        m_rect[0] = x; m_rect[1] = y; m_rect[2] = w; m_rect[3] = h;
+    qint64 totalPipelineCreationTime() const
+    {
+        return accumulatedPipelineCreationTime;
     }
 
-private:
-    std::array<int, 4> m_rect { { 0, 0, 0, 0 } };
+    QRhiVertexInputAttribute::Format shaderDescVariableFormatToVertexInputFormat(QShaderDescription::VariableType type) const;
+    quint32 byteSizePerVertexForVertexInputFormat(QRhiVertexInputAttribute::Format format) const;
 
-    friend bool operator==(const QRhiScissor &a, const QRhiScissor &b) noexcept
+    static const QRhiShaderResourceBinding::Data *shaderResourceBindingData(const QRhiShaderResourceBinding &binding)
     {
-        return a.m_rect == b.m_rect;
+        return &binding.d;
     }
 
-    friend bool operator!=(const QRhiScissor &a, const QRhiScissor &b) noexcept
+    static QRhiShaderResourceBinding::Data *shaderResourceBindingData(QRhiShaderResourceBinding &binding)
     {
-        return !(a == b);
+        return &binding.d;
     }
 
-    friend size_t qHash(const QRhiScissor &v, size_t seed = 0) noexcept
+    static bool sortedBindingLessThan(const QRhiShaderResourceBinding &a, const QRhiShaderResourceBinding &b)
     {
-        QtPrivate::QHashCombine hash;
-        seed = hash(seed, v.m_rect[0]);
-        seed = hash(seed, v.m_rect[1]);
-        seed = hash(seed, v.m_rect[2]);
-        seed = hash(seed, v.m_rect[3]);
-        return seed;
+        return a.d.binding < b.d.binding;
     }
-};
-
-Q_DECLARE_TYPEINFO(QRhiScissor, Q_RELOCATABLE_TYPE);
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiScissor &);
-#endif
 
-class Q_GUI_EXPORT QRhiVertexInputBinding
-{
-public:
-    enum Classification {
-        PerVertex,
-        PerInstance
-    };
-
-    QRhiVertexInputBinding() = default;
-    QRhiVertexInputBinding(quint32 stride, Classification cls = PerVertex, quint32 stepRate = 1);
+    QRhi *q;
 
-    quint32 stride() const { return m_stride; }
-    void setStride(quint32 s) { m_stride = s; }
+    static const int MAX_SHADER_CACHE_ENTRIES = 128;
 
-    Classification classification() const { return m_classification; }
-    void setClassification(Classification c) { m_classification = c; }
-
-    quint32 instanceStepRate() const { return m_instanceStepRate; }
-    void setInstanceStepRate(quint32 rate) { m_instanceStepRate = rate; }
+    bool debugMarkers = false;
+    int currentFrameSlot = 0; // for vk, mtl, and similar. unused by gl and d3d11.
+    bool inFrame = false;
 
 private:
-    quint32 m_stride = 0;
-    Classification m_classification = PerVertex;
-    quint32 m_instanceStepRate = 1;
-
-    friend bool operator==(const QRhiVertexInputBinding &a, const QRhiVertexInputBinding &b) noexcept
-    {
-        return a.m_stride == b.m_stride
-                && a.m_classification == b.m_classification
-                && a.m_instanceStepRate == b.m_instanceStepRate;
-    }
+    QRhi::Implementation implType;
+    QThread *implThread;
+    QVarLengthArray<QRhiResourceUpdateBatch *, 4> resUpdPool;
+    quint64 resUpdPoolMap = 0;
+    int lastResUpdIdx = -1;
+    QHash<QRhiResource *, bool> resources;
+    QSet<QRhiResource *> pendingDeleteResources;
+    QVarLengthArray<QRhi::CleanupCallback, 4> cleanupCallbacks;
+    QElapsedTimer pipelineCreationTimer;
+    qint64 accumulatedPipelineCreationTime = 0;
 
-    friend bool operator!=(const QRhiVertexInputBinding &a, const QRhiVertexInputBinding &b) noexcept
-    {
-        return !(a == b);
-    }
-
-    friend size_t qHash(const QRhiVertexInputBinding &v, size_t seed = 0) noexcept
-    {
-        QtPrivate::QHashCombine hash;
-        seed = hash(seed, v.m_stride);
-        seed = hash(seed, v.m_classification);
-        seed = hash(seed, v.m_instanceStepRate);
-        return seed;
-    }
+    friend class QRhi;
+    friend class QRhiResourceUpdateBatchPrivate;
 };
 
-Q_DECLARE_TYPEINFO(QRhiVertexInputBinding, Q_RELOCATABLE_TYPE);
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiVertexInputBinding &);
-#endif
-
-class Q_GUI_EXPORT QRhiVertexInputAttribute
+enum QRhiTargetRectBoundMode
 {
-public:
-    enum Format {
-        Float4,
-        Float3,
-        Float2,
-        Float,
-        UNormByte4,
-        UNormByte2,
-        UNormByte,
-        UInt4,
-        UInt3,
-        UInt2,
-        UInt,
-        SInt4,
-        SInt3,
-        SInt2,
-        SInt,
-        Half4,
-        Half3,
-        Half2,
-        Half
-    };
-
-    QRhiVertexInputAttribute() = default;
-    QRhiVertexInputAttribute(int binding, int location, Format format, quint32 offset, int matrixSlice = -1);
-
-    int binding() const { return m_binding; }
-    void setBinding(int b) { m_binding = b; }
+    UnBounded,
+    Bounded
+};
 
-    int location() const { return m_location; }
-    void setLocation(int loc) { m_location = loc; }
+template<QRhiTargetRectBoundMode boundingMode, typename T, size_t N>
+bool qrhi_toTopLeftRenderTargetRect(const QSize &outputSize, const std::array<T, N> &r,
+                                    T *x, T *y, T *w, T *h)
+{
+    // x,y are bottom-left in QRhiScissor and QRhiViewport but top-left in
+    // Vulkan/Metal/D3D. Our input is an OpenGL-style scissor rect where both
+    // negative x or y, and partly or completely out of bounds rects are
+    // allowed. The only thing the input here cannot have is a negative width
+    // or height. We must handle all other input gracefully, clamping to a zero
+    // width or height rect in the worst case, and ensuring the resulting rect
+    // is inside the rendertarget's bounds because some APIs' validation/debug
+    // layers are allergic to out of bounds scissor rects.
 
-    Format format() const { return m_format; }
-    void setFormat(Format f) { m_format = f; }
+    const T outputWidth = outputSize.width();
+    const T outputHeight = outputSize.height();
+    const T inputWidth = r[2];
+    const T inputHeight = r[3];
 
-    quint32 offset() const { return m_offset; }
-    void setOffset(quint32 ofs) { m_offset = ofs; }
+    if (inputWidth < 0 || inputHeight < 0)
+        return false;
 
-    int matrixSlice() const { return m_matrixSlice; }
-    void setMatrixSlice(int slice) { m_matrixSlice = slice; }
+    *x = r[0];
+    *y = outputHeight - (r[1] + inputHeight);
+    *w = inputWidth;
+    *h = inputHeight;
 
-private:
-    int m_binding = 0;
-    int m_location = 0;
-    Format m_format = Float4;
-    quint32 m_offset = 0;
-    int m_matrixSlice = -1;
+    if (boundingMode == Bounded) {
+        const T widthOffset = *x < 0 ? -*x : 0;
+        const T heightOffset = *y < 0 ? -*y : 0;
+        *w = *x < outputWidth ? qMax<T>(0, inputWidth - widthOffset) : 0;
+        *h = *y < outputHeight ? qMax<T>(0, inputHeight - heightOffset) : 0;
 
-    friend bool operator==(const QRhiVertexInputAttribute &a, const QRhiVertexInputAttribute &b) noexcept
-    {
-        return a.m_binding == b.m_binding
-                && a.m_location == b.m_location
-                && a.m_format == b.m_format
-                && a.m_offset == b.m_offset;
-        // matrixSlice excluded intentionally
-    }
+        if (outputWidth > 0)
+            *x = qBound<T>(0, *x, outputWidth - 1);
+        if (outputHeight > 0)
+            *y = qBound<T>(0, *y, outputHeight - 1);
 
-    friend bool operator!=(const QRhiVertexInputAttribute &a, const QRhiVertexInputAttribute &b) noexcept
-    {
-        return !(a == b);
+        if (*x + *w > outputWidth)
+            *w = qMax<T>(0, outputWidth - *x);
+        if (*y + *h > outputHeight)
+            *h = qMax<T>(0, outputHeight - *y);
     }
+    return true;
+}
 
-    friend size_t qHash(const QRhiVertexInputAttribute &v, size_t seed = 0) noexcept
-    {
-        QtPrivate::QHashCombine hash;
-        seed = hash(seed, v.m_binding);
-        seed = hash(seed, v.m_location);
-        seed = hash(seed, v.m_format);
-        seed = hash(seed, v.m_offset);
-        return seed;
-    }
+struct QRhiBufferDataPrivate
+{
+    Q_DISABLE_COPY_MOVE(QRhiBufferDataPrivate)
+    QRhiBufferDataPrivate() { }
+    ~QRhiBufferDataPrivate() { delete[] largeData; }
+    int ref = 1;
+    quint32 size = 0;
+    quint32 largeAlloc = 0;
+    char *largeData = nullptr;
+    static constexpr quint32 SMALL_DATA_SIZE = 1024;
+    char data[SMALL_DATA_SIZE];
 };
 
-Q_DECLARE_TYPEINFO(QRhiVertexInputAttribute, Q_RELOCATABLE_TYPE);
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiVertexInputAttribute &);
-#endif
-
-class Q_GUI_EXPORT QRhiVertexInputLayout
+// no detach-with-contents, no atomic refcount, no shrink
+class QRhiBufferData
 {
 public:
-    QRhiVertexInputLayout() = default;
-
-    void setBindings(std::initializer_list<QRhiVertexInputBinding> list) { m_bindings = list; }
-    template<typename InputIterator>
-    void setBindings(InputIterator first, InputIterator last)
+    QRhiBufferData() = default;
+    ~QRhiBufferData()
     {
-        m_bindings.clear();
-        std::copy(first, last, std::back_inserter(m_bindings));
+        if (d && !--d->ref)
+            delete d;
     }
-    const QRhiVertexInputBinding *cbeginBindings() const { return m_bindings.cbegin(); }
-    const QRhiVertexInputBinding *cendBindings() const { return m_bindings.cend(); }
-    const QRhiVertexInputBinding *bindingAt(qsizetype index) const { return &m_bindings.at(index); }
-    qsizetype bindingCount() const { return m_bindings.count(); }
-
-    void setAttributes(std::initializer_list<QRhiVertexInputAttribute> list) { m_attributes = list; }
-    template<typename InputIterator>
-    void setAttributes(InputIterator first, InputIterator last)
+    QRhiBufferData(const QRhiBufferData &other)
+        : d(other.d)
     {
-        m_attributes.clear();
-        std::copy(first, last, std::back_inserter(m_attributes));
+        if (d)
+            d->ref += 1;
     }
-    const QRhiVertexInputAttribute *cbeginAttributes() const { return m_attributes.cbegin(); }
-    const QRhiVertexInputAttribute *cendAttributes() const { return m_attributes.cend(); }
-    const QRhiVertexInputAttribute *attributeAt(qsizetype index) const { return &m_attributes.at(index); }
-    qsizetype attributeCount() const { return m_attributes.count(); }
-
-private:
-    QVarLengthArray<QRhiVertexInputBinding, 8> m_bindings;
-    QVarLengthArray<QRhiVertexInputAttribute, 8> m_attributes;
-
-    friend bool operator==(const QRhiVertexInputLayout &a, const QRhiVertexInputLayout &b) noexcept
+    QRhiBufferData &operator=(const QRhiBufferData &other)
     {
-        return a.m_bindings == b.m_bindings && a.m_attributes == b.m_attributes;
-    }
-
-    friend bool operator!=(const QRhiVertexInputLayout &a, const QRhiVertexInputLayout &b) noexcept
-    {
-        return !(a == b);
-    }
-
-    friend size_t qHash(const QRhiVertexInputLayout &v, size_t seed = 0) noexcept
-    {
-        QtPrivate::QHashCombine hash;
-        seed = hash(seed, v.m_bindings);
-        seed = hash(seed, v.m_attributes);
-        return seed;
-    }
-
-    friend Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiVertexInputLayout &);
-};
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiVertexInputLayout &);
-#endif
-
-class Q_GUI_EXPORT QRhiShaderStage
-{
-public:
-    enum Type {
-        Vertex,
-        TessellationControl,
-        TessellationEvaluation,
-        Geometry,
-        Fragment,
-        Compute
-    };
-
-    QRhiShaderStage() = default;
-    QRhiShaderStage(Type type, const QShader &shader,
-                    QShader::Variant v = QShader::StandardShader);
-
-    Type type() const { return m_type; }
-    void setType(Type t) { m_type = t; }
-
-    QShader shader() const { return m_shader; }
-    void setShader(const QShader &s) { m_shader = s; }
-
-    QShader::Variant shaderVariant() const { return m_shaderVariant; }
-    void setShaderVariant(QShader::Variant v) { m_shaderVariant = v; }
-
-private:
-    Type m_type = Vertex;
-    QShader m_shader;
-    QShader::Variant m_shaderVariant = QShader::StandardShader;
-
-    friend bool operator==(const QRhiShaderStage &a, const QRhiShaderStage &b) noexcept
+        if (d == other.d)
+            return *this;
+        if (other.d)
+            other.d->ref += 1;
+        if (d && !--d->ref)
+            delete d;
+        d = other.d;
+        return *this;
+    }
+    const char *constData() const
     {
-        return a.m_type == b.m_type
-                && a.m_shader == b.m_shader
-                && a.m_shaderVariant == b.m_shaderVariant;
+        return d->size <= QRhiBufferDataPrivate::SMALL_DATA_SIZE ? d->data : d->largeData;
     }
-
-    friend bool operator!=(const QRhiShaderStage &a, const QRhiShaderStage &b) noexcept
+    quint32 size() const
     {
-        return !(a == b);
+        return d->size;
     }
-
-    friend size_t qHash(const QRhiShaderStage &v, size_t seed = 0) noexcept
+    void assign(const char *s, quint32 size)
     {
-        QtPrivate::QHashCombine hash;
-        seed = hash(seed, v.m_type);
-        seed = hash(seed, v.m_shader);
-        seed = hash(seed, v.m_shaderVariant);
-        return seed;
+        if (!d) {
+            d = new QRhiBufferDataPrivate;
+        } else if (d->ref != 1) {
+            d->ref -= 1;
+            d = new QRhiBufferDataPrivate;
+        }
+        d->size = size;
+        if (size <= QRhiBufferDataPrivate::SMALL_DATA_SIZE) {
+            memcpy(d->data, s, size);
+        } else {
+            if (d->largeAlloc < size) {
+                delete[] d->largeData;
+                d->largeAlloc = size;
+                d->largeData = new char[size];
+            }
+            memcpy(d->largeData, s, size);
+        }
     }
+private:
+    QRhiBufferDataPrivate *d = nullptr;
 };
 
-Q_DECLARE_TYPEINFO(QRhiShaderStage, Q_RELOCATABLE_TYPE);
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiShaderStage &);
-#endif
-
-using QRhiGraphicsShaderStage = QRhiShaderStage;
+Q_DECLARE_TYPEINFO(QRhiBufferData, Q_RELOCATABLE_TYPE);
 
-class Q_GUI_EXPORT QRhiShaderResourceBinding
+class QRhiResourceUpdateBatchPrivate
 {
 public:
-    enum Type {
-        UniformBuffer,
-        SampledTexture,
-        Texture,
-        Sampler,
-        ImageLoad,
-        ImageStore,
-        ImageLoadStore,
-        BufferLoad,
-        BufferStore,
-        BufferLoadStore
-    };
-
-    enum StageFlag {
-        VertexStage = 1 << 0,
-        TessellationControlStage = 1 << 1,
-        TessellationEvaluationStage = 1 << 2,
-        GeometryStage = 1 << 3,
-        FragmentStage = 1 << 4,
-        ComputeStage = 1 << 5
-    };
-    Q_DECLARE_FLAGS(StageFlags, StageFlag)
-
-    QRhiShaderResourceBinding() = default;
+    struct BufferOp {
+        enum Type {
+            DynamicUpdate,
+            StaticUpload,
+            Read
+        };
+        Type type;
+        QRhiBuffer *buf;
+        quint32 offset;
+        QRhiBufferData data;
+        quint32 readSize;
+        QRhiReadbackResult *result;
+
+        static BufferOp dynamicUpdate(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
+        {
+            BufferOp op = {};
+            op.type = DynamicUpdate;
+            op.buf = buf;
+            op.offset = offset;
+            const int effectiveSize = size ? size : buf->size();
+            op.data.assign(reinterpret_cast<const char *>(data), effectiveSize);
+            return op;
+        }
 
-    bool isLayoutCompatible(const QRhiShaderResourceBinding &other) const;
+        static void changeToDynamicUpdate(BufferOp *op, QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
+        {
+            op->type = DynamicUpdate;
+            op->buf = buf;
+            op->offset = offset;
+            const int effectiveSize = size ? size : buf->size();
+            op->data.assign(reinterpret_cast<const char *>(data), effectiveSize);
+        }
 
-    static QRhiShaderResourceBinding uniformBuffer(int binding, StageFlags stage, QRhiBuffer *buf);
-    static QRhiShaderResourceBinding uniformBuffer(int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size);
-    static QRhiShaderResourceBinding uniformBufferWithDynamicOffset(int binding, StageFlags stage, QRhiBuffer *buf, quint32 size);
+        static BufferOp staticUpload(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
+        {
+            BufferOp op = {};
+            op.type = StaticUpload;
+            op.buf = buf;
+            op.offset = offset;
+            const int effectiveSize = size ? size : buf->size();
+            op.data.assign(reinterpret_cast<const char *>(data), effectiveSize);
+            return op;
+        }
 
-    static QRhiShaderResourceBinding sampledTexture(int binding, StageFlags stage, QRhiTexture *tex, QRhiSampler *sampler);
+        static void changeToStaticUpload(BufferOp *op, QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
+        {
+            op->type = StaticUpload;
+            op->buf = buf;
+            op->offset = offset;
+            const int effectiveSize = size ? size : buf->size();
+            op->data.assign(reinterpret_cast<const char *>(data), effectiveSize);
+        }
 
-    struct TextureAndSampler {
-        QRhiTexture *tex;
-        QRhiSampler *sampler;
+        static BufferOp read(QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result)
+        {
+            BufferOp op = {};
+            op.type = Read;
+            op.buf = buf;
+            op.offset = offset;
+            op.readSize = size;
+            op.result = result;
+            return op;
+        }
     };
-    static QRhiShaderResourceBinding sampledTextures(int binding, StageFlags stage, int count, const TextureAndSampler *texSamplers);
 
-    static QRhiShaderResourceBinding texture(int binding, StageFlags stage, QRhiTexture *tex);
-    static QRhiShaderResourceBinding textures(int binding, StageFlags stage, int count, QRhiTexture **tex);
-    static QRhiShaderResourceBinding sampler(int binding, StageFlags stage, QRhiSampler *sampler);
-
-    static QRhiShaderResourceBinding imageLoad(int binding, StageFlags stage, QRhiTexture *tex, int level);
-    static QRhiShaderResourceBinding imageStore(int binding, StageFlags stage, QRhiTexture *tex, int level);
-    static QRhiShaderResourceBinding imageLoadStore(int binding, StageFlags stage, QRhiTexture *tex, int level);
-
-    static QRhiShaderResourceBinding bufferLoad(int binding, StageFlags stage, QRhiBuffer *buf);
-    static QRhiShaderResourceBinding bufferLoad(int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size);
-    static QRhiShaderResourceBinding bufferStore(int binding, StageFlags stage, QRhiBuffer *buf);
-    static QRhiShaderResourceBinding bufferStore(int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size);
-    static QRhiShaderResourceBinding bufferLoadStore(int binding, StageFlags stage, QRhiBuffer *buf);
-    static QRhiShaderResourceBinding bufferLoadStore(int binding, StageFlags stage, QRhiBuffer *buf, quint32 offset, quint32 size);
-
-    struct Data
-    {
-        int binding;
-        QRhiShaderResourceBinding::StageFlags stage;
-        QRhiShaderResourceBinding::Type type;
-        struct UniformBufferData {
-            QRhiBuffer *buf;
-            quint32 offset;
-            quint32 maybeSize;
-            bool hasDynamicOffset;
-        };
-        static const int MAX_TEX_SAMPLER_ARRAY_SIZE = 16;
-        struct TextureAndOrSamplerData {
-            int count;
-            TextureAndSampler texSamplers[MAX_TEX_SAMPLER_ARRAY_SIZE];
-        };
-        struct StorageImageData {
-            QRhiTexture *tex;
-            int level;
-        };
-        struct StorageBufferData {
-            QRhiBuffer *buf;
-            quint32 offset;
-            quint32 maybeSize;
+    struct TextureOp {
+        enum Type {
+            Upload,
+            Copy,
+            Read,
+            GenMips
         };
-        union {
-            UniformBufferData ubuf;
-            TextureAndOrSamplerData stex;
-            StorageImageData simage;
-            StorageBufferData sbuf;
-        } u;
-
-        int arraySize() const
+        Type type;
+        QRhiTexture *dst;
+        // Specifying multiple uploads for a subresource must be supported.
+        // In the backend this can then end up, where applicable, as a
+        // single, batched copy operation with only one set of barriers.
+        // This helps when doing for example glyph cache fills.
+        using MipLevelUploadList = std::array<QVector<QRhiTextureSubresourceUploadDescription>, QRhi::MAX_MIP_LEVELS>;
+        QVarLengthArray<MipLevelUploadList, 6> subresDesc;
+        QRhiTexture *src;
+        QRhiTextureCopyDescription desc;
+        QRhiReadbackDescription rb;
+        QRhiReadbackResult *result;
+
+        static TextureOp upload(QRhiTexture *tex, const QRhiTextureUploadDescription &desc)
         {
-            return type == QRhiShaderResourceBinding::SampledTexture || type == QRhiShaderResourceBinding::Texture
-                    ? u.stex.count
-                    : 1;
+            TextureOp op = {};
+            op.type = Upload;
+            op.dst = tex;
+            int maxLayer = -1;
+            for (auto it = desc.cbeginEntries(), itEnd = desc.cendEntries(); it != itEnd; ++it) {
+                if (it->layer() > maxLayer)
+                    maxLayer = it->layer();
+            }
+            op.subresDesc.resize(maxLayer + 1);
+            for (auto it = desc.cbeginEntries(), itEnd = desc.cendEntries(); it != itEnd; ++it)
+                op.subresDesc[it->layer()][it->level()].append(it->description());
+            return op;
         }
 
-        template<typename Output>
-        Output serialize(Output dst) const
+        static TextureOp copy(QRhiTexture *dst, QRhiTexture *src, const QRhiTextureCopyDescription &desc)
         {
-            // must write out exactly LAYOUT_DESC_ENTRIES_PER_BINDING elements here
-            *dst++ = quint32(binding);
-            *dst++ = quint32(stage);
-            *dst++ = quint32(type);
-            *dst++ = quint32(arraySize());
-            return dst;
+            TextureOp op = {};
+            op.type = Copy;
+            op.dst = dst;
+            op.src = src;
+            op.desc = desc;
+            return op;
         }
-    };
-
-    static const int LAYOUT_DESC_ENTRIES_PER_BINDING = 4;
 
-    template<typename Output>
-    static void serializeLayoutDescription(const QRhiShaderResourceBinding *first,
-                                           const QRhiShaderResourceBinding *last,
-                                           Output dst)
-    {
-        while (first != last) {
-            dst = first->d.serialize(dst);
-            ++first;
+        static TextureOp read(const QRhiReadbackDescription &rb, QRhiReadbackResult *result)
+        {
+            TextureOp op = {};
+            op.type = Read;
+            op.rb = rb;
+            op.result = result;
+            return op;
         }
-    }
-
-private:
-    Data d;
-    friend class QRhiImplementation;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiShaderResourceBinding::StageFlags)
-
-Q_DECLARE_TYPEINFO(QRhiShaderResourceBinding, Q_PRIMITIVE_TYPE);
-
-Q_GUI_EXPORT bool operator==(const QRhiShaderResourceBinding &a, const QRhiShaderResourceBinding &b) noexcept;
-Q_GUI_EXPORT bool operator!=(const QRhiShaderResourceBinding &a, const QRhiShaderResourceBinding &b) noexcept;
-Q_GUI_EXPORT size_t qHash(const QRhiShaderResourceBinding &b, size_t seed = 0) noexcept;
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiShaderResourceBinding &);
-#endif
-
-class Q_GUI_EXPORT QRhiColorAttachment
-{
-public:
-    QRhiColorAttachment() = default;
-    QRhiColorAttachment(QRhiTexture *texture);
-    QRhiColorAttachment(QRhiRenderBuffer *renderBuffer);
 
-    QRhiTexture *texture() const { return m_texture; }
-    void setTexture(QRhiTexture *tex) { m_texture = tex; }
-
-    QRhiRenderBuffer *renderBuffer() const { return m_renderBuffer; }
-    void setRenderBuffer(QRhiRenderBuffer *rb) { m_renderBuffer = rb; }
-
-    int layer() const { return m_layer; }
-    void setLayer(int layer) { m_layer = layer; }
+        static TextureOp genMips(QRhiTexture *tex)
+        {
+            TextureOp op = {};
+            op.type = GenMips;
+            op.dst = tex;
+            return op;
+        }
+    };
 
-    int level() const { return m_level; }
-    void setLevel(int level) { m_level = level; }
+    int activeBufferOpCount = 0; // this is the real number of used elements in bufferOps, not bufferOps.count()
+    static const int BUFFER_OPS_STATIC_ALLOC = 1024;
+    QVarLengthArray<BufferOp, BUFFER_OPS_STATIC_ALLOC> bufferOps;
 
-    QRhiTexture *resolveTexture() const { return m_resolveTexture; }
-    void setResolveTexture(QRhiTexture *tex) { m_resolveTexture = tex; }
+    int activeTextureOpCount = 0; // this is the real number of used elements in textureOps, not textureOps.count()
+    static const int TEXTURE_OPS_STATIC_ALLOC = 256;
+    QVarLengthArray<TextureOp, TEXTURE_OPS_STATIC_ALLOC> textureOps;
 
-    int resolveLayer() const { return m_resolveLayer; }
-    void setResolveLayer(int layer) { m_resolveLayer = layer; }
+    QRhiResourceUpdateBatch *q = nullptr;
+    QRhiImplementation *rhi = nullptr;
+    int poolIndex = -1;
 
-    int resolveLevel() const { return m_resolveLevel; }
-    void setResolveLevel(int level) { m_resolveLevel = level; }
+    void free();
+    void merge(QRhiResourceUpdateBatchPrivate *other);
+    bool hasOptimalCapacity() const;
+    void trimOpLists();
 
-private:
-    QRhiTexture *m_texture = nullptr;
-    QRhiRenderBuffer *m_renderBuffer = nullptr;
-    int m_layer = 0;
-    int m_level = 0;
-    QRhiTexture *m_resolveTexture = nullptr;
-    int m_resolveLayer = 0;
-    int m_resolveLevel = 0;
+    static QRhiResourceUpdateBatchPrivate *get(QRhiResourceUpdateBatch *b) { return b->d; }
 };
 
-Q_DECLARE_TYPEINFO(QRhiColorAttachment, Q_RELOCATABLE_TYPE);
-
-class Q_GUI_EXPORT QRhiTextureRenderTargetDescription
+template<typename T>
+struct QRhiBatchedBindings
 {
-public:
-    QRhiTextureRenderTargetDescription() = default;
-    QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment);
-    QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiRenderBuffer *depthStencilBuffer);
-    QRhiTextureRenderTargetDescription(const QRhiColorAttachment &colorAttachment, QRhiTexture *depthTexture);
-
-    void setColorAttachments(std::initializer_list<QRhiColorAttachment> list) { m_colorAttachments = list; }
-    template<typename InputIterator>
-    void setColorAttachments(InputIterator first, InputIterator last)
-    {
-        m_colorAttachments.clear();
-        std::copy(first, last, std::back_inserter(m_colorAttachments));
+    void feed(int binding, T resource) { // binding must be strictly increasing
+        if (curBinding == -1 || binding > curBinding + 1) {
+            finish();
+            curBatch.startBinding = binding;
+            curBatch.resources.clear();
+            curBatch.resources.append(resource);
+        } else {
+            Q_ASSERT(binding == curBinding + 1);
+            curBatch.resources.append(resource);
+        }
+        curBinding = binding;
     }
-    const QRhiColorAttachment *cbeginColorAttachments() const { return m_colorAttachments.cbegin(); }
-    const QRhiColorAttachment *cendColorAttachments() const { return m_colorAttachments.cend(); }
-    const QRhiColorAttachment *colorAttachmentAt(qsizetype index) const { return &m_colorAttachments.at(index); }
-    qsizetype colorAttachmentCount() const { return m_colorAttachments.count(); }
-
-    QRhiRenderBuffer *depthStencilBuffer() const { return m_depthStencilBuffer; }
-    void setDepthStencilBuffer(QRhiRenderBuffer *renderBuffer) { m_depthStencilBuffer = renderBuffer; }
-
-    QRhiTexture *depthTexture() const { return m_depthTexture; }
-    void setDepthTexture(QRhiTexture *texture) { m_depthTexture = texture; }
-
-private:
-    QVarLengthArray<QRhiColorAttachment, 8> m_colorAttachments;
-    QRhiRenderBuffer *m_depthStencilBuffer = nullptr;
-    QRhiTexture *m_depthTexture = nullptr;
-};
-
-class Q_GUI_EXPORT QRhiTextureSubresourceUploadDescription
-{
-public:
-    QRhiTextureSubresourceUploadDescription() = default;
-    explicit QRhiTextureSubresourceUploadDescription(const QImage &image);
-    QRhiTextureSubresourceUploadDescription(const void *data, quint32 size);
-    explicit QRhiTextureSubresourceUploadDescription(const QByteArray &data);
-
-    QImage image() const { return m_image; }
-    void setImage(const QImage &image) { m_image = image; }
-
-    QByteArray data() const { return m_data; }
-    void setData(const QByteArray &data) { m_data = data; }
-
-    quint32 dataStride() const { return m_dataStride; }
-    void setDataStride(quint32 stride) { m_dataStride = stride; }
-
-    QPoint destinationTopLeft() const { return m_destinationTopLeft; }
-    void setDestinationTopLeft(const QPoint &p) { m_destinationTopLeft = p; }
-
-    QSize sourceSize() const { return m_sourceSize; }
-    void setSourceSize(const QSize &size) { m_sourceSize = size; }
-
-    QPoint sourceTopLeft() const { return m_sourceTopLeft; }
-    void setSourceTopLeft(const QPoint &p) { m_sourceTopLeft = p; }
-
-private:
-    QImage m_image;
-    QByteArray m_data;
-    quint32 m_dataStride = 0;
-    QPoint m_destinationTopLeft;
-    QSize m_sourceSize;
-    QPoint m_sourceTopLeft;
-};
-
-Q_DECLARE_TYPEINFO(QRhiTextureSubresourceUploadDescription, Q_RELOCATABLE_TYPE);
-
-class Q_GUI_EXPORT QRhiTextureUploadEntry
-{
-public:
-    QRhiTextureUploadEntry() = default;
-    QRhiTextureUploadEntry(int layer, int level, const QRhiTextureSubresourceUploadDescription &desc);
 
-    int layer() const { return m_layer; }
-    void setLayer(int layer) { m_layer = layer; }
+    bool finish() {
+        if (!curBatch.resources.isEmpty())
+            batches.append(curBatch);
+        return !batches.isEmpty();
+    }
 
-    int level() const { return m_level; }
-    void setLevel(int level) { m_level = level; }
+    void clear() {
+        batches.clear();
+        curBatch.resources.clear();
+        curBinding = -1;
+    }
 
-    QRhiTextureSubresourceUploadDescription description() const { return m_desc; }
-    void setDescription(const QRhiTextureSubresourceUploadDescription &desc) { m_desc = desc; }
+    struct Batch {
+        uint startBinding;
+        QVarLengthArray<T, 4> resources;
 
-private:
-    int m_layer = 0;
-    int m_level = 0;
-    QRhiTextureSubresourceUploadDescription m_desc;
-};
+        bool operator==(const Batch &other) const
+        {
+            return startBinding == other.startBinding && resources == other.resources;
+        }
 
-Q_DECLARE_TYPEINFO(QRhiTextureUploadEntry, Q_RELOCATABLE_TYPE);
+        bool operator!=(const Batch &other) const
+        {
+            return !operator==(other);
+        }
+    };
 
-class Q_GUI_EXPORT QRhiTextureUploadDescription
-{
-public:
-    QRhiTextureUploadDescription() = default;
-    QRhiTextureUploadDescription(const QRhiTextureUploadEntry &entry);
-    QRhiTextureUploadDescription(std::initializer_list<QRhiTextureUploadEntry> list);
+    QVarLengthArray<Batch, 4> batches; // sorted by startBinding
 
-    void setEntries(std::initializer_list<QRhiTextureUploadEntry> list) { m_entries = list; }
-    template<typename InputIterator>
-    void setEntries(InputIterator first, InputIterator last)
+    bool operator==(const QRhiBatchedBindings<T> &other) const
     {
-        m_entries.clear();
-        std::copy(first, last, std::back_inserter(m_entries));
+        return batches == other.batches;
     }
-    const QRhiTextureUploadEntry *cbeginEntries() const { return m_entries.cbegin(); }
-    const QRhiTextureUploadEntry *cendEntries() const { return m_entries.cend(); }
-    const QRhiTextureUploadEntry *entryAt(qsizetype index) const { return &m_entries.at(index); }
-    qsizetype entryCount() const { return m_entries.count(); }
 
-private:
-    QVarLengthArray<QRhiTextureUploadEntry, 16> m_entries;
-};
-
-class Q_GUI_EXPORT QRhiTextureCopyDescription
-{
-public:
-    QRhiTextureCopyDescription() = default;
-
-    QSize pixelSize() const { return m_pixelSize; }
-    void setPixelSize(const QSize &sz) { m_pixelSize = sz; }
-
-    int sourceLayer() const { return m_sourceLayer; }
-    void setSourceLayer(int layer) { m_sourceLayer = layer; }
-
-    int sourceLevel() const { return m_sourceLevel; }
-    void setSourceLevel(int level) { m_sourceLevel = level; }
-
-    QPoint sourceTopLeft() const { return m_sourceTopLeft; }
-    void setSourceTopLeft(const QPoint &p) { m_sourceTopLeft = p; }
-
-    int destinationLayer() const { return m_destinationLayer; }
-    void setDestinationLayer(int layer) { m_destinationLayer = layer; }
-
-    int destinationLevel() const { return m_destinationLevel; }
-    void setDestinationLevel(int level) { m_destinationLevel = level; }
-
-    QPoint destinationTopLeft() const { return m_destinationTopLeft; }
-    void setDestinationTopLeft(const QPoint &p) { m_destinationTopLeft = p; }
+    bool operator!=(const QRhiBatchedBindings<T> &other) const
+    {
+        return !operator==(other);
+    }
 
 private:
-    QSize m_pixelSize;
-    int m_sourceLayer = 0;
-    int m_sourceLevel = 0;
-    QPoint m_sourceTopLeft;
-    int m_destinationLayer = 0;
-    int m_destinationLevel = 0;
-    QPoint m_destinationTopLeft;
+    Batch curBatch;
+    int curBinding = -1;
 };
 
-Q_DECLARE_TYPEINFO(QRhiTextureCopyDescription, Q_RELOCATABLE_TYPE);
-
-class Q_GUI_EXPORT QRhiReadbackDescription
+class QRhiGlobalObjectIdGenerator
 {
 public:
-    QRhiReadbackDescription() = default;
-    QRhiReadbackDescription(QRhiTexture *texture);
-
-    QRhiTexture *texture() const { return m_texture; }
-    void setTexture(QRhiTexture *tex) { m_texture = tex; }
-
-    int layer() const { return m_layer; }
-    void setLayer(int layer) { m_layer = layer; }
-
-    int level() const { return m_level; }
-    void setLevel(int level) { m_level = level; }
-
-private:
-    QRhiTexture *m_texture = nullptr;
-    int m_layer = 0;
-    int m_level = 0;
-};
-
-Q_DECLARE_TYPEINFO(QRhiReadbackDescription, Q_RELOCATABLE_TYPE);
-
-struct Q_GUI_EXPORT QRhiNativeHandles
-{
+#ifdef Q_ATOMIC_INT64_IS_SUPPORTED
+    using Type = quint64;
+#else
+    using Type = quint32;
+#endif
+    static Type newId();
 };
 
-class Q_GUI_EXPORT QRhiResource
+class QRhiPassResourceTracker
 {
 public:
-    enum Type {
-        Buffer,
-        Texture,
-        Sampler,
-        RenderBuffer,
-        RenderPassDescriptor,
-        SwapChainRenderTarget,
-        TextureRenderTarget,
-        ShaderResourceBindings,
-        GraphicsPipeline,
-        SwapChain,
-        ComputePipeline,
-        CommandBuffer
-    };
-
-    virtual ~QRhiResource();
-
-    virtual Type resourceType() const = 0;
-
-    virtual void destroy() = 0;
-
-    void deleteLater();
-
-    QByteArray name() const;
-    void setName(const QByteArray &name);
+    bool isEmpty() const;
+    void reset();
 
-    quint64 globalResourceId() const;
-
-    QRhi *rhi() const;
-
-protected:
-    QRhiResource(QRhiImplementation *rhi);
-    Q_DISABLE_COPY(QRhiResource)
-    friend class QRhiImplementation;
-    QRhiImplementation *m_rhi = nullptr;
-    quint64 m_id;
-    QByteArray m_objectName;
-};
-
-class Q_GUI_EXPORT QRhiBuffer : public QRhiResource
-{
-public:
-    enum Type {
-        Immutable,
-        Static,
-        Dynamic
+    struct UsageState {
+        int layout;
+        int access;
+        int stage;
     };
 
-    enum UsageFlag {
-        VertexBuffer = 1 << 0,
-        IndexBuffer = 1 << 1,
-        UniformBuffer = 1 << 2,
-        StorageBuffer = 1 << 3
+    enum BufferStage {
+        BufVertexInputStage,
+        BufVertexStage,
+        BufTCStage,
+        BufTEStage,
+        BufFragmentStage,
+        BufComputeStage,
+        BufGeometryStage
     };
-    Q_DECLARE_FLAGS(UsageFlags, UsageFlag)
 
-    struct NativeBuffer {
-        const void *objects[3];
-        int slotCount;
+    enum BufferAccess {
+        BufVertexInput,
+        BufIndexRead,
+        BufUniformRead,
+        BufStorageLoad,
+        BufStorageStore,
+        BufStorageLoadStore
     };
 
-    QRhiResource::Type resourceType() const override;
-
-    Type type() const { return m_type; }
-    void setType(Type t) { m_type = t; }
-
-    UsageFlags usage() const { return m_usage; }
-    void setUsage(UsageFlags u) { m_usage = u; }
-
-    quint32 size() const { return m_size; }
-    void setSize(quint32 sz) { m_size = sz; }
-
-    virtual bool create() = 0;
-
-    virtual NativeBuffer nativeBuffer();
-
-    virtual char *beginFullDynamicBufferUpdateForCurrentFrame();
-    virtual void endFullDynamicBufferUpdateForCurrentFrame();
-
-protected:
-    QRhiBuffer(QRhiImplementation *rhi, Type type_, UsageFlags usage_, quint32 size_);
-    Type m_type;
-    UsageFlags m_usage;
-    quint32 m_size;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiBuffer::UsageFlags)
+    void registerBuffer(QRhiBuffer *buf, int slot, BufferAccess *access, BufferStage *stage,
+                        const UsageState &state);
 
-class Q_GUI_EXPORT QRhiTexture : public QRhiResource
-{
-public:
-    enum Flag {
-        RenderTarget = 1 << 0,
-        CubeMap = 1 << 2,
-        MipMapped = 1 << 3,
-        sRGB = 1 << 4,
-        UsedAsTransferSource = 1 << 5,
-        UsedWithGenerateMips = 1 << 6,
-        UsedWithLoadStore = 1 << 7,
-        UsedAsCompressedAtlas = 1 << 8,
-        ExternalOES = 1 << 9,
-        ThreeDimensional = 1 << 10,
-        TextureRectangleGL = 1 << 11,
-        TextureArray = 1 << 12,
-        OneDimensional = 1 << 13
-    };
-    Q_DECLARE_FLAGS(Flags, Flag)
-
-    enum Format {
-        UnknownFormat,
-
-        RGBA8,
-        BGRA8,
-        R8,
-        RG8,
-        R16,
-        RG16,
-        RED_OR_ALPHA8,
-
-        RGBA16F,
-        RGBA32F,
-        R16F,
-        R32F,
-
-        RGB10A2,
-
-        D16,
-        D24,
-        D24S8,
-        D32F,
-
-        BC1,
-        BC2,
-        BC3,
-        BC4,
-        BC5,
-        BC6H,
-        BC7,
-
-        ETC2_RGB8,
-        ETC2_RGB8A1,
-        ETC2_RGBA8,
-
-        ASTC_4x4,
-        ASTC_5x4,
-        ASTC_5x5,
-        ASTC_6x5,
-        ASTC_6x6,
-        ASTC_8x5,
-        ASTC_8x6,
-        ASTC_8x8,
-        ASTC_10x5,
-        ASTC_10x6,
-        ASTC_10x8,
-        ASTC_10x10,
-        ASTC_12x10,
-        ASTC_12x12
+    enum TextureStage {
+        TexVertexStage,
+        TexTCStage,
+        TexTEStage,
+        TexFragmentStage,
+        TexColorOutputStage,
+        TexDepthOutputStage,
+        TexComputeStage,
+        TexGeometryStage
     };
 
-    struct NativeTexture {
-        quint64 object;
-        int layout; // or state
+    enum TextureAccess {
+        TexSample,
+        TexColorOutput,
+        TexDepthOutput,
+        TexStorageLoad,
+        TexStorageStore,
+        TexStorageLoadStore
     };
 
-    QRhiResource::Type resourceType() const override;
-
-    Format format() const { return m_format; }
-    void setFormat(Format fmt) { m_format = fmt; }
-
-    QSize pixelSize() const { return m_pixelSize; }
-    void setPixelSize(const QSize &sz) { m_pixelSize = sz; }
-
-    int depth() const { return m_depth; }
-    void setDepth(int depth) { m_depth = depth; }
-
-    int arraySize() const { return m_arraySize; }
-    void setArraySize(int arraySize) { m_arraySize = arraySize; }
+    void registerTexture(QRhiTexture *tex, TextureAccess *access, TextureStage *stage,
+                         const UsageState &state);
 
-    int arrayRangeStart() const { return m_arrayRangeStart; }
-    int arrayRangeLength() const { return m_arrayRangeLength; }
-    void setArrayRange(int startIndex, int count)
-    {
-        m_arrayRangeStart = startIndex;
-        m_arrayRangeLength = count;
-    }
-
-    Flags flags() const { return m_flags; }
-    void setFlags(Flags f) { m_flags = f; }
-
-    int sampleCount() const { return m_sampleCount; }
-    void setSampleCount(int s) { m_sampleCount = s; }
-
-    virtual bool create() = 0;
-    virtual NativeTexture nativeTexture();
-    virtual bool createFrom(NativeTexture src);
-    virtual void setNativeLayout(int layout);
-
-protected:
-    QRhiTexture(QRhiImplementation *rhi, Format format_, const QSize &pixelSize_, int depth_,
-                int arraySize_, int sampleCount_, Flags flags_);
-    Format m_format;
-    QSize m_pixelSize;
-    int m_depth;
-    int m_arraySize;
-    int m_sampleCount;
-    Flags m_flags;
-    int m_arrayRangeStart = -1;
-    int m_arrayRangeLength = -1;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiTexture::Flags)
-
-class Q_GUI_EXPORT QRhiSampler : public QRhiResource
-{
-public:
-    enum Filter {
-        None,
-        Nearest,
-        Linear
-    };
-
-    enum AddressMode {
-        Repeat,
-        ClampToEdge,
-        Mirror,
-    };
-
-    enum CompareOp {
-        Never,
-        Less,
-        Equal,
-        LessOrEqual,
-        Greater,
-        NotEqual,
-        GreaterOrEqual,
-        Always
-    };
-
-    QRhiResource::Type resourceType() const override;
-
-    Filter magFilter() const { return m_magFilter; }
-    void setMagFilter(Filter f) { m_magFilter = f; }
-
-    Filter minFilter() const { return m_minFilter; }
-    void setMinFilter(Filter f) { m_minFilter = f; }
-
-    Filter mipmapMode() const { return m_mipmapMode; }
-    void setMipmapMode(Filter f) { m_mipmapMode = f; }
-
-    AddressMode addressU() const { return m_addressU; }
-    void setAddressU(AddressMode mode) { m_addressU = mode; }
-
-    AddressMode addressV() const { return m_addressV; }
-    void setAddressV(AddressMode mode) { m_addressV = mode; }
-
-    AddressMode addressW() const { return m_addressW; }
-    void setAddressW(AddressMode mode) { m_addressW = mode; }
-
-    CompareOp textureCompareOp() const { return m_compareOp; }
-    void setTextureCompareOp(CompareOp op) { m_compareOp = op; }
-
-    virtual bool create() = 0;
-
-protected:
-    QRhiSampler(QRhiImplementation *rhi,
-                Filter magFilter_, Filter minFilter_, Filter mipmapMode_,
-                AddressMode u_, AddressMode v_, AddressMode w_);
-    Filter m_magFilter;
-    Filter m_minFilter;
-    Filter m_mipmapMode;
-    AddressMode m_addressU;
-    AddressMode m_addressV;
-    AddressMode m_addressW;
-    CompareOp m_compareOp;
-};
-
-class Q_GUI_EXPORT QRhiRenderBuffer : public QRhiResource
-{
-public:
-    enum Type {
-        DepthStencil,
-        Color
+    struct Buffer {
+        int slot;
+        BufferAccess access;
+        BufferStage stage;
+        UsageState stateAtPassBegin;
     };
 
-    enum Flag {
-        UsedWithSwapChainOnly = 1 << 0
-    };
-    Q_DECLARE_FLAGS(Flags, Flag)
+    using BufferIterator = QHash<QRhiBuffer *, Buffer>::const_iterator;
+    BufferIterator cbeginBuffers() const { return m_buffers.cbegin(); }
+    BufferIterator cendBuffers() const { return m_buffers.cend(); }
 
-    struct NativeRenderBuffer {
-        quint64 object;
+    struct Texture {
+        TextureAccess access;
+        TextureStage stage;
+        UsageState stateAtPassBegin;
     };
 
-    QRhiResource::Type resourceType() const override;
-
-    Type type() const { return m_type; }
-    void setType(Type t) { m_type = t; }
-
-    QSize pixelSize() const { return m_pixelSize; }
-    void setPixelSize(const QSize &sz) { m_pixelSize = sz; }
+    using TextureIterator = QHash<QRhiTexture *, Texture>::const_iterator;
+    TextureIterator cbeginTextures() const { return m_textures.cbegin(); }
+    TextureIterator cendTextures() const { return m_textures.cend(); }
 
-    int sampleCount() const { return m_sampleCount; }
-    void setSampleCount(int s) { m_sampleCount = s; }
+    static BufferStage toPassTrackerBufferStage(QRhiShaderResourceBinding::StageFlags stages);
+    static TextureStage toPassTrackerTextureStage(QRhiShaderResourceBinding::StageFlags stages);
 
-    Flags flags() const { return m_flags; }
-    void setFlags(Flags h) { m_flags = h; }
-
-    virtual bool create() = 0;
-    virtual bool createFrom(NativeRenderBuffer src);
-
-    virtual QRhiTexture::Format backingFormat() const = 0;
-
-protected:
-    QRhiRenderBuffer(QRhiImplementation *rhi, Type type_, const QSize &pixelSize_,
-                     int sampleCount_, Flags flags_, QRhiTexture::Format backingFormatHint_);
-    Type m_type;
-    QSize m_pixelSize;
-    int m_sampleCount;
-    Flags m_flags;
-    QRhiTexture::Format m_backingFormatHint;
+private:
+    QHash<QRhiBuffer *, Buffer> m_buffers;
+    QHash<QRhiTexture *, Texture> m_textures;
 };
 
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiRenderBuffer::Flags)
+Q_DECLARE_TYPEINFO(QRhiPassResourceTracker::Buffer, Q_RELOCATABLE_TYPE);
+Q_DECLARE_TYPEINFO(QRhiPassResourceTracker::Texture, Q_RELOCATABLE_TYPE);
 
-class Q_GUI_EXPORT QRhiRenderPassDescriptor : public QRhiResource
+template<typename T, int GROW = 1024>
+class QRhiBackendCommandList
 {
 public:
-    QRhiResource::Type resourceType() const override;
-
-    virtual bool isCompatible(const QRhiRenderPassDescriptor *other) const = 0;
-    virtual const QRhiNativeHandles *nativeHandles();
-
-    virtual QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const = 0;
-
-    virtual QVector<quint32> serializedFormat() const = 0;
-
-protected:
-    QRhiRenderPassDescriptor(QRhiImplementation *rhi);
+    QRhiBackendCommandList() = default;
+    ~QRhiBackendCommandList() { delete[] v; }
+    inline void reset() { p = 0; }
+    inline bool isEmpty() const { return p == 0; }
+    inline T &get() {
+        if (p == a) {
+            a += GROW;
+            T *nv = new T[a];
+            if (v) {
+                memcpy(nv, v, p * sizeof(T));
+                delete[] v;
+            }
+            v = nv;
+        }
+        return v[p++];
+    }
+    inline void unget() { --p; }
+    inline T *cbegin() const { return v; }
+    inline T *cend() const { return v + p; }
+    inline T *begin() { return v; }
+    inline T *end() { return v + p; }
+private:
+    Q_DISABLE_COPY(QRhiBackendCommandList)
+    T *v = nullptr;
+    int a = 0;
+    int p = 0;
 };
 
-class Q_GUI_EXPORT QRhiRenderTarget : public QRhiResource
+struct QRhiRenderTargetAttachmentTracker
 {
-public:
-    virtual QSize pixelSize() const = 0;
-    virtual float devicePixelRatio() const = 0;
-    virtual int sampleCount() const = 0;
+    struct ResId { quint64 id; uint generation; };
+    using ResIdList = QVarLengthArray<ResId, 8 * 2 + 1>; // color, resolve, ds
 
-    QRhiRenderPassDescriptor *renderPassDescriptor() const { return m_renderPassDesc; }
-    void setRenderPassDescriptor(QRhiRenderPassDescriptor *desc) { m_renderPassDesc = desc; }
+    template<typename TexType, typename RenderBufferType>
+    static void updateResIdList(const QRhiTextureRenderTargetDescription &desc, ResIdList *dst);
 
-protected:
-    QRhiRenderTarget(QRhiImplementation *rhi);
-    QRhiRenderPassDescriptor *m_renderPassDesc = nullptr;
+    template<typename TexType, typename RenderBufferType>
+    static bool isUpToDate(const QRhiTextureRenderTargetDescription &desc, const ResIdList &currentResIdList);
 };
 
-class Q_GUI_EXPORT QRhiSwapChainRenderTarget : public QRhiRenderTarget
+inline bool operator==(const QRhiRenderTargetAttachmentTracker::ResId &a, const QRhiRenderTargetAttachmentTracker::ResId &b)
 {
-public:
-    QRhiResource::Type resourceType() const override;
-    QRhiSwapChain *swapChain() const { return m_swapchain; }
-
-protected:
-    QRhiSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain_);
-    QRhiSwapChain *m_swapchain;
-};
+    return a.id == b.id && a.generation == b.generation;
+}
 
-class Q_GUI_EXPORT QRhiTextureRenderTarget : public QRhiRenderTarget
+inline bool operator!=(const QRhiRenderTargetAttachmentTracker::ResId &a, const QRhiRenderTargetAttachmentTracker::ResId &b)
 {
-public:
-    enum Flag {
-        PreserveColorContents = 1 << 0,
-        PreserveDepthStencilContents = 1 << 1
-    };
-    Q_DECLARE_FLAGS(Flags, Flag)
-
-    QRhiResource::Type resourceType() const override;
-
-    QRhiTextureRenderTargetDescription description() const { return m_desc; }
-    void setDescription(const QRhiTextureRenderTargetDescription &desc) { m_desc = desc; }
-
-    Flags flags() const { return m_flags; }
-    void setFlags(Flags f) { m_flags = f; }
-
-    virtual QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() = 0;
-
-    virtual bool create() = 0;
+    return !(a == b);
+}
 
-protected:
-    QRhiTextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc_, Flags flags_);
-    QRhiTextureRenderTargetDescription m_desc;
-    Flags m_flags;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiTextureRenderTarget::Flags)
-
-class Q_GUI_EXPORT QRhiShaderResourceBindings : public QRhiResource
+template<typename TexType, typename RenderBufferType>
+void QRhiRenderTargetAttachmentTracker::updateResIdList(const QRhiTextureRenderTargetDescription &desc, ResIdList *dst)
 {
-public:
-    QRhiResource::Type resourceType() const override;
-
-    void setBindings(std::initializer_list<QRhiShaderResourceBinding> list) { m_bindings = list; }
-    template<typename InputIterator>
-    void setBindings(InputIterator first, InputIterator last)
-    {
-        m_bindings.clear();
-        std::copy(first, last, std::back_inserter(m_bindings));
-    }
-    const QRhiShaderResourceBinding *cbeginBindings() const { return m_bindings.cbegin(); }
-    const QRhiShaderResourceBinding *cendBindings() const { return m_bindings.cend(); }
-    const QRhiShaderResourceBinding *bindingAt(qsizetype index) const { return &m_bindings.at(index); }
-    qsizetype bindingCount() const { return m_bindings.count(); }
-
-    bool isLayoutCompatible(const QRhiShaderResourceBindings *other) const;
-
-    QVector<quint32> serializedLayoutDescription() const { return m_layoutDesc; }
-
-    virtual bool create() = 0;
-
-    enum UpdateFlag {
-        BindingsAreSorted = 0x01
-    };
-    Q_DECLARE_FLAGS(UpdateFlags, UpdateFlag)
-
-    virtual void updateResources(UpdateFlags flags = {}) = 0;
-
-protected:
-    static const int BINDING_PREALLOC = 12;
-    QRhiShaderResourceBindings(QRhiImplementation *rhi);
-    QVarLengthArray<QRhiShaderResourceBinding, BINDING_PREALLOC> m_bindings;
-    size_t m_layoutDescHash = 0;
-    // Intentionally not using QVLA for m_layoutDesc: clients like Qt Quick are much
-    // better served with an implicitly shared container here, because they will likely
-    // throw this directly into structs serving as cache keys.
-    QVector<quint32> m_layoutDesc;
-    friend class QRhiImplementation;
-#ifndef QT_NO_DEBUG_STREAM
-    friend Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiShaderResourceBindings &);
-#endif
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiShaderResourceBindings::UpdateFlags)
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiShaderResourceBindings &);
-#endif
-
-class Q_GUI_EXPORT QRhiGraphicsPipeline : public QRhiResource
-{
-public:
-    enum Flag {
-        UsesBlendConstants = 1 << 0,
-        UsesStencilRef = 1 << 1,
-        UsesScissor = 1 << 2,
-        CompileShadersWithDebugInfo = 1 << 3
-    };
-    Q_DECLARE_FLAGS(Flags, Flag)
-
-    enum Topology {
-        Triangles,
-        TriangleStrip,
-        TriangleFan,
-        Lines,
-        LineStrip,
-        Points,
-        Patches
-    };
-
-    enum CullMode {
-        None,
-        Front,
-        Back
-    };
-
-    enum FrontFace {
-        CCW,
-        CW
-    };
-
-    enum ColorMaskComponent {
-        R = 1 << 0,
-        G = 1 << 1,
-        B = 1 << 2,
-        A = 1 << 3
-    };
-    Q_DECLARE_FLAGS(ColorMask, ColorMaskComponent)
-
-    enum BlendFactor {
-        Zero,
-        One,
-        SrcColor,
-        OneMinusSrcColor,
-        DstColor,
-        OneMinusDstColor,
-        SrcAlpha,
-        OneMinusSrcAlpha,
-        DstAlpha,
-        OneMinusDstAlpha,
-        ConstantColor,
-        OneMinusConstantColor,
-        ConstantAlpha,
-        OneMinusConstantAlpha,
-        SrcAlphaSaturate,
-        Src1Color,
-        OneMinusSrc1Color,
-        Src1Alpha,
-        OneMinusSrc1Alpha
-    };
-
-    enum BlendOp {
-        Add,
-        Subtract,
-        ReverseSubtract,
-        Min,
-        Max
-    };
-
-    struct TargetBlend {
-        ColorMask colorWrite = ColorMask(0xF); // R | G | B | A
-        bool enable = false;
-        BlendFactor srcColor = One;
-        BlendFactor dstColor = OneMinusSrcAlpha;
-        BlendOp opColor = Add;
-        BlendFactor srcAlpha = One;
-        BlendFactor dstAlpha = OneMinusSrcAlpha;
-        BlendOp opAlpha = Add;
-    };
-
-    enum CompareOp {
-        Never,
-        Less,
-        Equal,
-        LessOrEqual,
-        Greater,
-        NotEqual,
-        GreaterOrEqual,
-        Always
-    };
-
-    enum StencilOp {
-        StencilZero,
-        Keep,
-        Replace,
-        IncrementAndClamp,
-        DecrementAndClamp,
-        Invert,
-        IncrementAndWrap,
-        DecrementAndWrap
-    };
-
-    struct StencilOpState {
-        StencilOp failOp = Keep;
-        StencilOp depthFailOp = Keep;
-        StencilOp passOp = Keep;
-        CompareOp compareOp = Always;
-    };
-
-    enum PolygonMode {
-        Fill,
-        Line
-    };
-
-    QRhiResource::Type resourceType() const override;
-
-    Flags flags() const { return m_flags; }
-    void setFlags(Flags f) { m_flags = f; }
-
-    Topology topology() const { return m_topology; }
-    void setTopology(Topology t) { m_topology = t; }
-
-    CullMode cullMode() const { return m_cullMode; }
-    void setCullMode(CullMode mode) { m_cullMode = mode; }
-
-    FrontFace frontFace() const { return m_frontFace; }
-    void setFrontFace(FrontFace f) { m_frontFace = f; }
-
-    void setTargetBlends(std::initializer_list<TargetBlend> list) { m_targetBlends = list; }
-    template<typename InputIterator>
-    void setTargetBlends(InputIterator first, InputIterator last)
-    {
-        m_targetBlends.clear();
-        std::copy(first, last, std::back_inserter(m_targetBlends));
+    const bool hasDepthStencil = desc.depthStencilBuffer() || desc.depthTexture();
+    dst->resize(desc.colorAttachmentCount() * 2 + (hasDepthStencil ? 1 : 0));
+    int n = 0;
+    for (auto it = desc.cbeginColorAttachments(), itEnd = desc.cendColorAttachments(); it != itEnd; ++it, ++n) {
+        const QRhiColorAttachment &colorAtt(*it);
+        if (colorAtt.texture()) {
+            TexType *texD = QRHI_RES(TexType, colorAtt.texture());
+            (*dst)[n] = { texD->globalResourceId(), texD->generation };
+        } else if (colorAtt.renderBuffer()) {
+            RenderBufferType *rbD = QRHI_RES(RenderBufferType, colorAtt.renderBuffer());
+            (*dst)[n] = { rbD->globalResourceId(), rbD->generation };
+        } else {
+            (*dst)[n] = { 0, 0 };
+        }
+        ++n;
+        if (colorAtt.resolveTexture()) {
+            TexType *texD = QRHI_RES(TexType, colorAtt.resolveTexture());
+            (*dst)[n] = { texD->globalResourceId(), texD->generation };
+        } else {
+            (*dst)[n] = { 0, 0 };
+        }
     }
-    const TargetBlend *cbeginTargetBlends() const { return m_targetBlends.cbegin(); }
-    const TargetBlend *cendTargetBlends() const { return m_targetBlends.cend(); }
-    const TargetBlend *targetBlendAt(qsizetype index) const { return &m_targetBlends.at(index); }
-    qsizetype targetBlendCount() const { return m_targetBlends.count(); }
-
-    bool hasDepthTest() const { return m_depthTest; }
-    void setDepthTest(bool enable) { m_depthTest = enable; }
-
-    bool hasDepthWrite() const { return m_depthWrite; }
-    void setDepthWrite(bool enable) { m_depthWrite = enable; }
-
-    CompareOp depthOp() const { return m_depthOp; }
-    void setDepthOp(CompareOp op) { m_depthOp = op; }
-
-    bool hasStencilTest() const { return m_stencilTest; }
-    void setStencilTest(bool enable) { m_stencilTest = enable; }
-
-    StencilOpState stencilFront() const { return m_stencilFront; }
-    void setStencilFront(const StencilOpState &state) { m_stencilFront = state; }
-
-    StencilOpState stencilBack() const { return m_stencilBack; }
-    void setStencilBack(const StencilOpState &state) { m_stencilBack = state; }
-
-    quint32 stencilReadMask() const { return m_stencilReadMask; }
-    void setStencilReadMask(quint32 mask) { m_stencilReadMask = mask; }
-
-    quint32 stencilWriteMask() const { return m_stencilWriteMask; }
-    void setStencilWriteMask(quint32 mask) { m_stencilWriteMask = mask; }
-
-    int sampleCount() const { return m_sampleCount; }
-    void setSampleCount(int s) { m_sampleCount = s; }
-
-    float lineWidth() const { return m_lineWidth; }
-    void setLineWidth(float width) { m_lineWidth = width; }
-
-    int depthBias() const { return m_depthBias; }
-    void setDepthBias(int bias) { m_depthBias = bias; }
-
-    float slopeScaledDepthBias() const { return m_slopeScaledDepthBias; }
-    void setSlopeScaledDepthBias(float bias) { m_slopeScaledDepthBias = bias; }
-
-    void setShaderStages(std::initializer_list<QRhiShaderStage> list) { m_shaderStages = list; }
-    template<typename InputIterator>
-    void setShaderStages(InputIterator first, InputIterator last)
-    {
-        m_shaderStages.clear();
-        std::copy(first, last, std::back_inserter(m_shaderStages));
+    if (hasDepthStencil) {
+        if (desc.depthTexture()) {
+            TexType *depthTexD = QRHI_RES(TexType, desc.depthTexture());
+            (*dst)[n] = { depthTexD->globalResourceId(), depthTexD->generation };
+        } else if (desc.depthStencilBuffer()) {
+            RenderBufferType *depthRbD = QRHI_RES(RenderBufferType, desc.depthStencilBuffer());
+            (*dst)[n] = { depthRbD->globalResourceId(), depthRbD->generation };
+        } else {
+            (*dst)[n] = { 0, 0 };
+        }
     }
-    const QRhiShaderStage *cbeginShaderStages() const { return m_shaderStages.cbegin(); }
-    const QRhiShaderStage *cendShaderStages() const { return m_shaderStages.cend(); }
-    const QRhiShaderStage *shaderStageAt(qsizetype index) const { return &m_shaderStages.at(index); }
-    qsizetype shaderStageCount() const { return m_shaderStages.count(); }
-
-    QRhiVertexInputLayout vertexInputLayout() const { return m_vertexInputLayout; }
-    void setVertexInputLayout(const QRhiVertexInputLayout &layout) { m_vertexInputLayout = layout; }
-
-    QRhiShaderResourceBindings *shaderResourceBindings() const { return m_shaderResourceBindings; }
-    void setShaderResourceBindings(QRhiShaderResourceBindings *srb) { m_shaderResourceBindings = srb; }
-
-    QRhiRenderPassDescriptor *renderPassDescriptor() const { return m_renderPassDesc; }
-    void setRenderPassDescriptor(QRhiRenderPassDescriptor *desc) { m_renderPassDesc = desc; }
-
-    int patchControlPointCount() const { return m_patchControlPointCount; }
-    void setPatchControlPointCount(int count) { m_patchControlPointCount = count; }
-
-    PolygonMode polygonMode() const {return m_polygonMode; }
-    void setPolygonMode(PolygonMode mode) {m_polygonMode = mode; }
-
-    virtual bool create() = 0;
-
-protected:
-    QRhiGraphicsPipeline(QRhiImplementation *rhi);
-    Flags m_flags;
-    Topology m_topology = Triangles;
-    CullMode m_cullMode = None;
-    FrontFace m_frontFace = CCW;
-    QVarLengthArray<TargetBlend, 8> m_targetBlends;
-    bool m_depthTest = false;
-    bool m_depthWrite = false;
-    CompareOp m_depthOp = Less;
-    bool m_stencilTest = false;
-    StencilOpState m_stencilFront;
-    StencilOpState m_stencilBack;
-    quint32 m_stencilReadMask = 0xFF;
-    quint32 m_stencilWriteMask = 0xFF;
-    int m_sampleCount = 1;
-    float m_lineWidth = 1.0f;
-    int m_depthBias = 0;
-    float m_slopeScaledDepthBias = 0.0f;
-    int m_patchControlPointCount = 3;
-    PolygonMode m_polygonMode = Fill;
-    QVarLengthArray<QRhiShaderStage, 4> m_shaderStages;
-    QRhiVertexInputLayout m_vertexInputLayout;
-    QRhiShaderResourceBindings *m_shaderResourceBindings = nullptr;
-    QRhiRenderPassDescriptor *m_renderPassDesc = nullptr;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiGraphicsPipeline::Flags)
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiGraphicsPipeline::ColorMask)
-Q_DECLARE_TYPEINFO(QRhiGraphicsPipeline::TargetBlend, Q_RELOCATABLE_TYPE);
-
-struct QRhiSwapChainHdrInfo
-{
-    bool isHardCodedDefaults;
-    enum LimitsType {
-        LuminanceInNits,
-        ColorComponentValue
-    };
-    LimitsType limitsType;
-    union {
-        struct {
-            float minLuminance;
-            float maxLuminance;
-        } luminanceInNits;
-        struct {
-            float maxColorComponentValue;
-        } colorComponentValue;
-    } limits;
-};
-
-Q_DECLARE_TYPEINFO(QRhiSwapChainHdrInfo, Q_RELOCATABLE_TYPE);
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiSwapChainHdrInfo &);
-#endif
+}
 
-struct QRhiSwapChainProxyData
+template<typename TexType, typename RenderBufferType>
+bool QRhiRenderTargetAttachmentTracker::isUpToDate(const QRhiTextureRenderTargetDescription &desc, const ResIdList &currentResIdList)
 {
-    void *reserved[2] = {};
-};
-
-class Q_GUI_EXPORT QRhiSwapChain : public QRhiResource
-{
-public:
-    enum Flag {
-        SurfaceHasPreMulAlpha = 1 << 0,
-        SurfaceHasNonPreMulAlpha = 1 << 1,
-        sRGB = 1 << 2,
-        UsedAsTransferSource = 1 << 3,
-        NoVSync = 1 << 4,
-        MinimalBufferCount = 1 << 5
-    };
-    Q_DECLARE_FLAGS(Flags, Flag)
-
-    enum Format {
-        SDR,
-        HDRExtendedSrgbLinear,
-        HDR10
-    };
-
-    enum StereoTargetBuffer {
-        LeftBuffer,
-        RightBuffer
-    };
-
-    QRhiResource::Type resourceType() const override;
-
-    QWindow *window() const { return m_window; }
-    void setWindow(QWindow *window) { m_window = window; }
-
-    QRhiSwapChainProxyData proxyData() const { return m_proxyData; }
-    void setProxyData(const QRhiSwapChainProxyData &d) { m_proxyData = d; }
-
-    Flags flags() const { return m_flags; }
-    void setFlags(Flags f) { m_flags = f; }
-
-    Format format() const { return m_format; }
-    void setFormat(Format f) { m_format = f; }
-
-    QRhiRenderBuffer *depthStencil() const { return m_depthStencil; }
-    void setDepthStencil(QRhiRenderBuffer *ds) { m_depthStencil = ds; }
-
-    int sampleCount() const { return m_sampleCount; }
-    void setSampleCount(int samples) { m_sampleCount = samples; }
-
-    QRhiRenderPassDescriptor *renderPassDescriptor() const { return m_renderPassDesc; }
-    void setRenderPassDescriptor(QRhiRenderPassDescriptor *desc) { m_renderPassDesc = desc; }
-
-    QSize currentPixelSize() const { return m_currentPixelSize; }
-
-    virtual QRhiCommandBuffer *currentFrameCommandBuffer() = 0;
-    virtual QRhiRenderTarget *currentFrameRenderTarget() = 0;
-    virtual QRhiRenderTarget *currentFrameRenderTarget(StereoTargetBuffer targetBuffer);
-    virtual QSize surfacePixelSize() = 0;
-    virtual bool isFormatSupported(Format f) = 0;
-    virtual QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() = 0;
-    virtual bool createOrResize() = 0;
-    virtual QRhiSwapChainHdrInfo hdrInfo();
-
-protected:
-    QRhiSwapChain(QRhiImplementation *rhi);
-    QWindow *m_window = nullptr;
-    Flags m_flags;
-    Format m_format = SDR;
-    QRhiRenderBuffer *m_depthStencil = nullptr;
-    int m_sampleCount = 1;
-    QRhiRenderPassDescriptor *m_renderPassDesc = nullptr;
-    QSize m_currentPixelSize;
-    QRhiSwapChainProxyData m_proxyData;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiSwapChain::Flags)
-
-class Q_GUI_EXPORT QRhiComputePipeline : public QRhiResource
-{
-public:
-    enum Flag {
-        CompileShadersWithDebugInfo = 1 << 0
-    };
-    Q_DECLARE_FLAGS(Flags, Flag)
-
-    QRhiResource::Type resourceType() const override;
-    virtual bool create() = 0;
-
-    Flags flags() const { return m_flags; }
-    void setFlags(Flags f) { m_flags = f; }
-
-    QRhiShaderStage shaderStage() const { return m_shaderStage; }
-    void setShaderStage(const QRhiShaderStage &stage) { m_shaderStage = stage; }
-
-    QRhiShaderResourceBindings *shaderResourceBindings() const { return m_shaderResourceBindings; }
-    void setShaderResourceBindings(QRhiShaderResourceBindings *srb) { m_shaderResourceBindings = srb; }
+    // Just as setShaderResources() recognizes if an srb's referenced
+    // resources have been rebuilt (got a create() since the srb's
+    // create()), we should do the same for the textures and renderbuffers
+    // referenced from the rendertarget. It is not uncommon that a texture
+    // or ds buffer gets resized due to following a window size in some
+    // form, which involves a create() on them. It is then nice if the
+    // render target auto-rebuilds in beginPass().
 
-protected:
-    QRhiComputePipeline(QRhiImplementation *rhi);
-    Flags m_flags;
-    QRhiShaderStage m_shaderStage;
-    QRhiShaderResourceBindings *m_shaderResourceBindings = nullptr;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiComputePipeline::Flags)
-
-class Q_GUI_EXPORT QRhiCommandBuffer : public QRhiResource
-{
-public:
-    enum IndexFormat {
-        IndexUInt16,
-        IndexUInt32
-    };
-
-    enum BeginPassFlag {
-        ExternalContent = 0x01,
-        DoNotTrackResourcesForCompute = 0x02
-    };
-    Q_DECLARE_FLAGS(BeginPassFlags, BeginPassFlag)
-
-    QRhiResource::Type resourceType() const override;
-
-    void resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates);
-
-    void beginPass(QRhiRenderTarget *rt,
-                   const QColor &colorClearValue,
-                   const QRhiDepthStencilClearValue &depthStencilClearValue,
-                   QRhiResourceUpdateBatch *resourceUpdates = nullptr,
-                   BeginPassFlags flags = {});
-    void endPass(QRhiResourceUpdateBatch *resourceUpdates = nullptr);
-
-    void setGraphicsPipeline(QRhiGraphicsPipeline *ps);
-    using DynamicOffset = QPair<int, quint32>; // binding, offset
-    void setShaderResources(QRhiShaderResourceBindings *srb = nullptr,
-                            int dynamicOffsetCount = 0,
-                            const DynamicOffset *dynamicOffsets = nullptr);
-    using VertexInput = QPair<QRhiBuffer *, quint32>; // buffer, offset
-    void setVertexInput(int startBinding, int bindingCount, const VertexInput *bindings,
-                        QRhiBuffer *indexBuf = nullptr, quint32 indexOffset = 0,
-                        IndexFormat indexFormat = IndexUInt16);
-
-    void setViewport(const QRhiViewport &viewport);
-    void setScissor(const QRhiScissor &scissor);
-    void setBlendConstants(const QColor &c);
-    void setStencilRef(quint32 refValue);
-
-    void draw(quint32 vertexCount,
-              quint32 instanceCount = 1,
-              quint32 firstVertex = 0,
-              quint32 firstInstance = 0);
-
-    void drawIndexed(quint32 indexCount,
-                     quint32 instanceCount = 1,
-                     quint32 firstIndex = 0,
-                     qint32 vertexOffset = 0,
-                     quint32 firstInstance = 0);
-
-    void debugMarkBegin(const QByteArray &name);
-    void debugMarkEnd();
-    void debugMarkMsg(const QByteArray &msg);
-
-    void beginComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr, BeginPassFlags flags = {});
-    void endComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr);
-    void setComputePipeline(QRhiComputePipeline *ps);
-    void dispatch(int x, int y, int z);
-
-    const QRhiNativeHandles *nativeHandles();
-    void beginExternal();
-    void endExternal();
-
-    double lastCompletedGpuTime();
-
-protected:
-    QRhiCommandBuffer(QRhiImplementation *rhi);
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhiCommandBuffer::BeginPassFlags)
-
-struct Q_GUI_EXPORT QRhiReadbackResult
-{
-    std::function<void()> completed = nullptr;
-    QRhiTexture::Format format;
-    QSize pixelSize;
-    QByteArray data;
-};
-
-class Q_GUI_EXPORT QRhiResourceUpdateBatch
-{
-public:
-    ~QRhiResourceUpdateBatch();
-
-    void release();
-
-    void merge(QRhiResourceUpdateBatch *other);
-    bool hasOptimalCapacity() const;
+    ResIdList resIdList;
+    updateResIdList<TexType, RenderBufferType>(desc, &resIdList);
+    return resIdList == currentResIdList;
+}
 
-    void updateDynamicBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data);
-    void uploadStaticBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data);
-    void uploadStaticBuffer(QRhiBuffer *buf, const void *data);
-    void readBackBuffer(QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result);
-    void uploadTexture(QRhiTexture *tex, const QRhiTextureUploadDescription &desc);
-    void uploadTexture(QRhiTexture *tex, const QImage &image);
-    void copyTexture(QRhiTexture *dst, QRhiTexture *src, const QRhiTextureCopyDescription &desc = QRhiTextureCopyDescription());
-    void readBackTexture(const QRhiReadbackDescription &rb, QRhiReadbackResult *result);
-    void generateMips(QRhiTexture *tex);
-
-private:
-    QRhiResourceUpdateBatch(QRhiImplementation *rhi);
-    Q_DISABLE_COPY(QRhiResourceUpdateBatch)
-    QRhiResourceUpdateBatchPrivate *d;
-    friend class QRhiResourceUpdateBatchPrivate;
-    friend class QRhi;
-};
-
-struct Q_GUI_EXPORT QRhiDriverInfo
+template<typename T>
+inline T *qrhi_objectFromProxyData(QRhiSwapChainProxyData *pd, QWindow *window, QRhi::Implementation impl, uint objectIndex)
 {
-    enum DeviceType {
-        UnknownDevice,
-        IntegratedDevice,
-        DiscreteDevice,
-        ExternalDevice,
-        VirtualDevice,
-        CpuDevice
-    };
-
-    QByteArray deviceName;
-    quint64 deviceId = 0;
-    quint64 vendorId = 0;
-    DeviceType deviceType = UnknownDevice;
-};
-
-Q_DECLARE_TYPEINFO(QRhiDriverInfo, Q_RELOCATABLE_TYPE);
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiDriverInfo &);
-#endif
-
-struct Q_GUI_EXPORT QRhiStats
-{
-    qint64 totalPipelineCreationTime = 0;
-    // Vulkan or D3D12 memory allocator statistics
-    quint32 blockCount = 0;
-    quint32 allocCount = 0;
-    quint64 usedBytes = 0;
-    quint64 unusedBytes = 0;
-    // D3D12 only, from IDXGIAdapter3::QueryVideoMemoryInfo(), incl. all resources
-    quint64 totalUsageBytes = 0;
-};
-
-Q_DECLARE_TYPEINFO(QRhiStats, Q_RELOCATABLE_TYPE);
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QRhiStats &);
-#endif
-
-struct Q_GUI_EXPORT QRhiInitParams
-{
-};
-
-class Q_GUI_EXPORT QRhi
-{
-public:
-    enum Implementation {
-        Null,
-        Vulkan,
-        OpenGLES2,
-        D3D11,
-        Metal,
-        D3D12
-    };
-
-    enum Flag {
-        EnableDebugMarkers = 1 << 0,
-        PreferSoftwareRenderer = 1 << 1,
-        EnablePipelineCacheDataSave = 1 << 2,
-        EnableTimestamps = 1 << 3
-    };
-    Q_DECLARE_FLAGS(Flags, Flag)
-
-    enum FrameOpResult {
-        FrameOpSuccess = 0,
-        FrameOpError,
-        FrameOpSwapChainOutOfDate,
-        FrameOpDeviceLost
-    };
-
-    enum Feature {
-        MultisampleTexture = 1,
-        MultisampleRenderBuffer,
-        DebugMarkers,
-        Timestamps,
-        Instancing,
-        CustomInstanceStepRate,
-        PrimitiveRestart,
-        NonDynamicUniformBuffers,
-        NonFourAlignedEffectiveIndexBufferOffset,
-        NPOTTextureRepeat,
-        RedOrAlpha8IsRed,
-        ElementIndexUint,
-        Compute,
-        WideLines,
-        VertexShaderPointSize,
-        BaseVertex,
-        BaseInstance,
-        TriangleFanTopology,
-        ReadBackNonUniformBuffer,
-        ReadBackNonBaseMipLevel,
-        TexelFetch,
-        RenderToNonBaseMipLevel,
-        IntAttributes,
-        ScreenSpaceDerivatives,
-        ReadBackAnyTextureFormat,
-        PipelineCacheDataLoadSave,
-        ImageDataStride,
-        RenderBufferImport,
-        ThreeDimensionalTextures,
-        RenderTo3DTextureSlice,
-        TextureArrays,
-        Tessellation,
-        GeometryShader,
-        TextureArrayRange,
-        NonFillPolygonMode,
-        OneDimensionalTextures,
-        OneDimensionalTextureMipmaps,
-        HalfAttributes,
-        RenderToOneDimensionalTexture,
-        ThreeDimensionalTextureMipmaps
-    };
-
-    enum BeginFrameFlag {
-    };
-    Q_DECLARE_FLAGS(BeginFrameFlags, BeginFrameFlag)
-
-    enum EndFrameFlag {
-        SkipPresent = 1 << 0
-    };
-    Q_DECLARE_FLAGS(EndFrameFlags, EndFrameFlag)
-
-    enum ResourceLimit {
-        TextureSizeMin = 1,
-        TextureSizeMax,
-        MaxColorAttachments,
-        FramesInFlight,
-        MaxAsyncReadbackFrames,
-        MaxThreadGroupsPerDimension,
-        MaxThreadsPerThreadGroup,
-        MaxThreadGroupX,
-        MaxThreadGroupY,
-        MaxThreadGroupZ,
-        TextureArraySizeMax,
-        MaxUniformBufferRange,
-        MaxVertexInputs,
-        MaxVertexOutputs
-    };
-
-    ~QRhi();
-
-    static QRhi *create(Implementation impl,
-                        QRhiInitParams *params,
-                        Flags flags = {},
-                        QRhiNativeHandles *importDevice = nullptr);
-    static bool probe(Implementation impl, QRhiInitParams *params);
-
-    Implementation backend() const;
-    const char *backendName() const;
-    static const char *backendName(Implementation impl);
-    QRhiDriverInfo driverInfo() const;
-    QThread *thread() const;
-
-    using CleanupCallback = std::function<void(QRhi *)>;
-    void addCleanupCallback(const CleanupCallback &callback);
-    void runCleanup();
-
-    QRhiGraphicsPipeline *newGraphicsPipeline();
-    QRhiComputePipeline *newComputePipeline();
-    QRhiShaderResourceBindings *newShaderResourceBindings();
-
-    QRhiBuffer *newBuffer(QRhiBuffer::Type type,
-                          QRhiBuffer::UsageFlags usage,
-                          quint32 size);
-
-    QRhiRenderBuffer *newRenderBuffer(QRhiRenderBuffer::Type type,
-                                      const QSize &pixelSize,
-                                      int sampleCount = 1,
-                                      QRhiRenderBuffer::Flags flags = {},
-                                      QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat);
-
-    QRhiTexture *newTexture(QRhiTexture::Format format,
-                            const QSize &pixelSize,
-                            int sampleCount = 1,
-                            QRhiTexture::Flags flags = {});
-
-    QRhiTexture *newTexture(QRhiTexture::Format format,
-                            int width, int height, int depth,
-                            int sampleCount = 1,
-                            QRhiTexture::Flags flags = {});
-
-    QRhiTexture *newTextureArray(QRhiTexture::Format format,
-                                 int arraySize,
-                                 const QSize &pixelSize,
-                                 int sampleCount = 1,
-                                 QRhiTexture::Flags flags = {});
-
-    QRhiSampler *newSampler(QRhiSampler::Filter magFilter,
-                            QRhiSampler::Filter minFilter,
-                            QRhiSampler::Filter mipmapMode,
-                            QRhiSampler::AddressMode addressU,
-                            QRhiSampler::AddressMode addressV,
-                            QRhiSampler::AddressMode addressW = QRhiSampler::Repeat);
-
-    QRhiTextureRenderTarget *newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
-                                                    QRhiTextureRenderTarget::Flags flags = {});
-
-    QRhiSwapChain *newSwapChain();
-    FrameOpResult beginFrame(QRhiSwapChain *swapChain, BeginFrameFlags flags = {});
-    FrameOpResult endFrame(QRhiSwapChain *swapChain, EndFrameFlags flags = {});
-    bool isRecordingFrame() const;
-    int currentFrameSlot() const;
-
-    FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, BeginFrameFlags flags = {});
-    FrameOpResult endOffscreenFrame(EndFrameFlags flags = {});
-
-    QRhi::FrameOpResult finish();
-
-    QRhiResourceUpdateBatch *nextResourceUpdateBatch();
-
-    QList<int> supportedSampleCounts() const;
-
-    int ubufAlignment() const;
-    int ubufAligned(int v) const;
-
-    static int mipLevelsForSize(const QSize &size);
-    static QSize sizeForMipLevel(int mipLevel, const QSize &baseLevelSize);
-
-    bool isYUpInFramebuffer() const;
-    bool isYUpInNDC() const;
-    bool isClipDepthZeroToOne() const;
-
-    QMatrix4x4 clipSpaceCorrMatrix() const;
-
-    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const;
-    bool isFeatureSupported(QRhi::Feature feature) const;
-    int resourceLimit(ResourceLimit limit) const;
-
-    const QRhiNativeHandles *nativeHandles();
-    bool makeThreadLocalNativeContextCurrent();
-
-    static const int MAX_MIP_LEVELS = 16; // a width and/or height of 65536 should be enough for everyone
-
-    void releaseCachedResources();
-
-    bool isDeviceLost() const;
-
-    QByteArray pipelineCacheData();
-    void setPipelineCacheData(const QByteArray &data);
-
-    QRhiStats statistics() const;
-
-    static QRhiSwapChainProxyData updateSwapChainProxyData(Implementation impl, QWindow *window);
-
-protected:
-    QRhi();
-
-private:
-    Q_DISABLE_COPY(QRhi)
-    QRhiImplementation *d = nullptr;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhi::Flags)
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhi::BeginFrameFlags)
-Q_DECLARE_OPERATORS_FOR_FLAGS(QRhi::EndFrameFlags)
+    Q_ASSERT(objectIndex < std::size(pd->reserved));
+    if (!pd->reserved[objectIndex]) // // was not set, no other choice, do it here, whatever thread this is
+        *pd = QRhi::updateSwapChainProxyData(impl, window);
+    return static_cast<T *>(pd->reserved[objectIndex]);
+}
 
 QT_END_NAMESPACE
 
diff --git a/src/gui/rhi/qrhi_p_p.h b/src/gui/rhi/qrhi_p_p.h
deleted file mode 100644
index 8b653c67ea..0000000000
--- a/src/gui/rhi/qrhi_p_p.h
+++ /dev/null
@@ -1,804 +0,0 @@
-// Copyright (C) 2019 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
-
-#ifndef QRHI_P_H
-#define QRHI_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists purely as an
-// implementation detail.  This header file may change from version to
-// version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qrhi_p.h"
-#include <QBitArray>
-#include <QAtomicInt>
-#include <QElapsedTimer>
-#include <QLoggingCategory>
-#include <QtCore/qset.h>
-#include <QtCore/qvarlengtharray.h>
-
-QT_BEGIN_NAMESPACE
-
-#define QRHI_RES(t, x) static_cast<t *>(x)
-#define QRHI_RES_RHI(t) t *rhiD = static_cast<t *>(m_rhi)
-
-Q_DECLARE_LOGGING_CATEGORY(QRHI_LOG_INFO)
-
-class QRhiImplementation
-{
-public:
-    virtual ~QRhiImplementation();
-
-    virtual bool create(QRhi::Flags flags) = 0;
-    virtual void destroy() = 0;
-
-    virtual QRhiGraphicsPipeline *createGraphicsPipeline() = 0;
-    virtual QRhiComputePipeline *createComputePipeline() = 0;
-    virtual QRhiShaderResourceBindings *createShaderResourceBindings() = 0;
-    virtual QRhiBuffer *createBuffer(QRhiBuffer::Type type,
-                                     QRhiBuffer::UsageFlags usage,
-                                     quint32 size) = 0;
-    virtual QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
-                                                 const QSize &pixelSize,
-                                                 int sampleCount,
-                                                 QRhiRenderBuffer::Flags flags,
-                                                 QRhiTexture::Format backingFormatHint) = 0;
-    virtual QRhiTexture *createTexture(QRhiTexture::Format format,
-                                       const QSize &pixelSize,
-                                       int depth,
-                                       int arraySize,
-                                       int sampleCount,
-                                       QRhiTexture::Flags flags) = 0;
-    virtual QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
-                                       QRhiSampler::Filter minFilter,
-                                       QRhiSampler::Filter mipmapMode,
-                                       QRhiSampler:: AddressMode u,
-                                       QRhiSampler::AddressMode v,
-                                       QRhiSampler::AddressMode w) = 0;
-
-    virtual QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
-                                                               QRhiTextureRenderTarget::Flags flags) = 0;
-
-    virtual QRhiSwapChain *createSwapChain() = 0;
-    virtual QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) = 0;
-    virtual QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) = 0;
-    virtual QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) = 0;
-    virtual QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) = 0;
-    virtual QRhi::FrameOpResult finish() = 0;
-
-    virtual void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) = 0;
-
-    virtual void beginPass(QRhiCommandBuffer *cb,
-                           QRhiRenderTarget *rt,
-                           const QColor &colorClearValue,
-                           const QRhiDepthStencilClearValue &depthStencilClearValue,
-                           QRhiResourceUpdateBatch *resourceUpdates,
-                           QRhiCommandBuffer::BeginPassFlags flags) = 0;
-    virtual void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) = 0;
-
-    virtual void setGraphicsPipeline(QRhiCommandBuffer *cb,
-                                     QRhiGraphicsPipeline *ps) = 0;
-
-    virtual void setShaderResources(QRhiCommandBuffer *cb,
-                                    QRhiShaderResourceBindings *srb,
-                                    int dynamicOffsetCount,
-                                    const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) = 0;
-
-    virtual void setVertexInput(QRhiCommandBuffer *cb,
-                                int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
-                                QRhiBuffer *indexBuf, quint32 indexOffset,
-                                QRhiCommandBuffer::IndexFormat indexFormat) = 0;
-
-    virtual void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) = 0;
-    virtual void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) = 0;
-    virtual void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) = 0;
-    virtual void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) = 0;
-
-    virtual void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
-                      quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) = 0;
-    virtual void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
-                             quint32 instanceCount, quint32 firstIndex,
-                             qint32 vertexOffset, quint32 firstInstance) = 0;
-
-    virtual void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) = 0;
-    virtual void debugMarkEnd(QRhiCommandBuffer *cb) = 0;
-    virtual void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) = 0;
-
-    virtual void beginComputePass(QRhiCommandBuffer *cb,
-                                  QRhiResourceUpdateBatch *resourceUpdates,
-                                  QRhiCommandBuffer::BeginPassFlags flags) = 0;
-    virtual void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) = 0;
-    virtual void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) = 0;
-    virtual void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) = 0;
-
-    virtual const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) = 0;
-    virtual void beginExternal(QRhiCommandBuffer *cb) = 0;
-    virtual void endExternal(QRhiCommandBuffer *cb) = 0;
-    virtual double lastCompletedGpuTime(QRhiCommandBuffer *cb) = 0;
-
-    virtual QList<int> supportedSampleCounts() const = 0;
-    virtual int ubufAlignment() const = 0;
-    virtual bool isYUpInFramebuffer() const = 0;
-    virtual bool isYUpInNDC() const = 0;
-    virtual bool isClipDepthZeroToOne() const = 0;
-    virtual QMatrix4x4 clipSpaceCorrMatrix() const = 0;
-    virtual bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const = 0;
-    virtual bool isFeatureSupported(QRhi::Feature feature) const = 0;
-    virtual int resourceLimit(QRhi::ResourceLimit limit) const = 0;
-    virtual const QRhiNativeHandles *nativeHandles() = 0;
-    virtual QRhiDriverInfo driverInfo() const = 0;
-    virtual QRhiStats statistics() = 0;
-    virtual bool makeThreadLocalNativeContextCurrent() = 0;
-    virtual void releaseCachedResources() = 0;
-    virtual bool isDeviceLost() const = 0;
-
-    virtual QByteArray pipelineCacheData() = 0;
-    virtual void setPipelineCacheData(const QByteArray &data) = 0;
-
-    void prepareForCreate(QRhi *rhi, QRhi::Implementation impl, QRhi::Flags flags);
-
-    bool isCompressedFormat(QRhiTexture::Format format) const;
-    void compressedFormatInfo(QRhiTexture::Format format, const QSize &size,
-                              quint32 *bpl, quint32 *byteSize,
-                              QSize *blockDim) const;
-    void textureFormatInfo(QRhiTexture::Format format, const QSize &size,
-                           quint32 *bpl, quint32 *byteSize, quint32 *bytesPerPixel) const;
-
-    void registerResource(QRhiResource *res, bool ownsNativeResources = true)
-    {
-        // The ownsNativeResources is relevant for the (graphics resource) leak
-        // check in ~QRhiImplementation; when false, the registration's sole
-        // purpose is to automatically null out the resource's m_rhi pointer in
-        // case the rhi goes away first. (which should not happen in
-        // well-written applications but we try to be graceful)
-        resources.insert(res, ownsNativeResources);
-    }
-
-    void unregisterResource(QRhiResource *res)
-    {
-        resources.remove(res);
-    }
-
-    void addDeleteLater(QRhiResource *res)
-    {
-        if (inFrame)
-            pendingDeleteResources.insert(res);
-        else
-            delete res;
-    }
-
-    void addCleanupCallback(const QRhi::CleanupCallback &callback)
-    {
-        cleanupCallbacks.append(callback);
-    }
-
-    bool sanityCheckGraphicsPipeline(QRhiGraphicsPipeline *ps);
-    bool sanityCheckShaderResourceBindings(QRhiShaderResourceBindings *srb);
-    void updateLayoutDesc(QRhiShaderResourceBindings *srb);
-
-    quint32 pipelineCacheRhiId() const
-    {
-        const quint32 ver = (QT_VERSION_MAJOR << 16) | (QT_VERSION_MINOR << 8) | (QT_VERSION_PATCH);
-        return (quint32(implType) << 24) | ver;
-    }
-
-    void pipelineCreationStart()
-    {
-        pipelineCreationTimer.start();
-    }
-
-    void pipelineCreationEnd()
-    {
-        accumulatedPipelineCreationTime += pipelineCreationTimer.elapsed();
-    }
-
-    qint64 totalPipelineCreationTime() const
-    {
-        return accumulatedPipelineCreationTime;
-    }
-
-    QRhiVertexInputAttribute::Format shaderDescVariableFormatToVertexInputFormat(QShaderDescription::VariableType type) const;
-    quint32 byteSizePerVertexForVertexInputFormat(QRhiVertexInputAttribute::Format format) const;
-
-    static const QRhiShaderResourceBinding::Data *shaderResourceBindingData(const QRhiShaderResourceBinding &binding)
-    {
-        return &binding.d;
-    }
-
-    static QRhiShaderResourceBinding::Data *shaderResourceBindingData(QRhiShaderResourceBinding &binding)
-    {
-        return &binding.d;
-    }
-
-    static bool sortedBindingLessThan(const QRhiShaderResourceBinding &a, const QRhiShaderResourceBinding &b)
-    {
-        return a.d.binding < b.d.binding;
-    }
-
-    QRhi *q;
-
-    static const int MAX_SHADER_CACHE_ENTRIES = 128;
-
-    bool debugMarkers = false;
-    int currentFrameSlot = 0; // for vk, mtl, and similar. unused by gl and d3d11.
-    bool inFrame = false;
-
-private:
-    QRhi::Implementation implType;
-    QThread *implThread;
-    QVarLengthArray<QRhiResourceUpdateBatch *, 4> resUpdPool;
-    quint64 resUpdPoolMap = 0;
-    int lastResUpdIdx = -1;
-    QHash<QRhiResource *, bool> resources;
-    QSet<QRhiResource *> pendingDeleteResources;
-    QVarLengthArray<QRhi::CleanupCallback, 4> cleanupCallbacks;
-    QElapsedTimer pipelineCreationTimer;
-    qint64 accumulatedPipelineCreationTime = 0;
-
-    friend class QRhi;
-    friend class QRhiResourceUpdateBatchPrivate;
-};
-
-enum QRhiTargetRectBoundMode
-{
-    UnBounded,
-    Bounded
-};
-
-template<QRhiTargetRectBoundMode boundingMode, typename T, size_t N>
-bool qrhi_toTopLeftRenderTargetRect(const QSize &outputSize, const std::array<T, N> &r,
-                                    T *x, T *y, T *w, T *h)
-{
-    // x,y are bottom-left in QRhiScissor and QRhiViewport but top-left in
-    // Vulkan/Metal/D3D. Our input is an OpenGL-style scissor rect where both
-    // negative x or y, and partly or completely out of bounds rects are
-    // allowed. The only thing the input here cannot have is a negative width
-    // or height. We must handle all other input gracefully, clamping to a zero
-    // width or height rect in the worst case, and ensuring the resulting rect
-    // is inside the rendertarget's bounds because some APIs' validation/debug
-    // layers are allergic to out of bounds scissor rects.
-
-    const T outputWidth = outputSize.width();
-    const T outputHeight = outputSize.height();
-    const T inputWidth = r[2];
-    const T inputHeight = r[3];
-
-    if (inputWidth < 0 || inputHeight < 0)
-        return false;
-
-    *x = r[0];
-    *y = outputHeight - (r[1] + inputHeight);
-    *w = inputWidth;
-    *h = inputHeight;
-
-    if (boundingMode == Bounded) {
-        const T widthOffset = *x < 0 ? -*x : 0;
-        const T heightOffset = *y < 0 ? -*y : 0;
-        *w = *x < outputWidth ? qMax<T>(0, inputWidth - widthOffset) : 0;
-        *h = *y < outputHeight ? qMax<T>(0, inputHeight - heightOffset) : 0;
-
-        if (outputWidth > 0)
-            *x = qBound<T>(0, *x, outputWidth - 1);
-        if (outputHeight > 0)
-            *y = qBound<T>(0, *y, outputHeight - 1);
-
-        if (*x + *w > outputWidth)
-            *w = qMax<T>(0, outputWidth - *x);
-        if (*y + *h > outputHeight)
-            *h = qMax<T>(0, outputHeight - *y);
-    }
-    return true;
-}
-
-struct QRhiBufferDataPrivate
-{
-    Q_DISABLE_COPY_MOVE(QRhiBufferDataPrivate)
-    QRhiBufferDataPrivate() { }
-    ~QRhiBufferDataPrivate() { delete[] largeData; }
-    int ref = 1;
-    quint32 size = 0;
-    quint32 largeAlloc = 0;
-    char *largeData = nullptr;
-    static constexpr quint32 SMALL_DATA_SIZE = 1024;
-    char data[SMALL_DATA_SIZE];
-};
-
-// no detach-with-contents, no atomic refcount, no shrink
-class QRhiBufferData
-{
-public:
-    QRhiBufferData() = default;
-    ~QRhiBufferData()
-    {
-        if (d && !--d->ref)
-            delete d;
-    }
-    QRhiBufferData(const QRhiBufferData &other)
-        : d(other.d)
-    {
-        if (d)
-            d->ref += 1;
-    }
-    QRhiBufferData &operator=(const QRhiBufferData &other)
-    {
-        if (d == other.d)
-            return *this;
-        if (other.d)
-            other.d->ref += 1;
-        if (d && !--d->ref)
-            delete d;
-        d = other.d;
-        return *this;
-    }
-    const char *constData() const
-    {
-        return d->size <= QRhiBufferDataPrivate::SMALL_DATA_SIZE ? d->data : d->largeData;
-    }
-    quint32 size() const
-    {
-        return d->size;
-    }
-    void assign(const char *s, quint32 size)
-    {
-        if (!d) {
-            d = new QRhiBufferDataPrivate;
-        } else if (d->ref != 1) {
-            d->ref -= 1;
-            d = new QRhiBufferDataPrivate;
-        }
-        d->size = size;
-        if (size <= QRhiBufferDataPrivate::SMALL_DATA_SIZE) {
-            memcpy(d->data, s, size);
-        } else {
-            if (d->largeAlloc < size) {
-                delete[] d->largeData;
-                d->largeAlloc = size;
-                d->largeData = new char[size];
-            }
-            memcpy(d->largeData, s, size);
-        }
-    }
-private:
-    QRhiBufferDataPrivate *d = nullptr;
-};
-
-Q_DECLARE_TYPEINFO(QRhiBufferData, Q_RELOCATABLE_TYPE);
-
-class QRhiResourceUpdateBatchPrivate
-{
-public:
-    struct BufferOp {
-        enum Type {
-            DynamicUpdate,
-            StaticUpload,
-            Read
-        };
-        Type type;
-        QRhiBuffer *buf;
-        quint32 offset;
-        QRhiBufferData data;
-        quint32 readSize;
-        QRhiReadbackResult *result;
-
-        static BufferOp dynamicUpdate(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
-        {
-            BufferOp op = {};
-            op.type = DynamicUpdate;
-            op.buf = buf;
-            op.offset = offset;
-            const int effectiveSize = size ? size : buf->size();
-            op.data.assign(reinterpret_cast<const char *>(data), effectiveSize);
-            return op;
-        }
-
-        static void changeToDynamicUpdate(BufferOp *op, QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
-        {
-            op->type = DynamicUpdate;
-            op->buf = buf;
-            op->offset = offset;
-            const int effectiveSize = size ? size : buf->size();
-            op->data.assign(reinterpret_cast<const char *>(data), effectiveSize);
-        }
-
-        static BufferOp staticUpload(QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
-        {
-            BufferOp op = {};
-            op.type = StaticUpload;
-            op.buf = buf;
-            op.offset = offset;
-            const int effectiveSize = size ? size : buf->size();
-            op.data.assign(reinterpret_cast<const char *>(data), effectiveSize);
-            return op;
-        }
-
-        static void changeToStaticUpload(BufferOp *op, QRhiBuffer *buf, quint32 offset, quint32 size, const void *data)
-        {
-            op->type = StaticUpload;
-            op->buf = buf;
-            op->offset = offset;
-            const int effectiveSize = size ? size : buf->size();
-            op->data.assign(reinterpret_cast<const char *>(data), effectiveSize);
-        }
-
-        static BufferOp read(QRhiBuffer *buf, quint32 offset, quint32 size, QRhiReadbackResult *result)
-        {
-            BufferOp op = {};
-            op.type = Read;
-            op.buf = buf;
-            op.offset = offset;
-            op.readSize = size;
-            op.result = result;
-            return op;
-        }
-    };
-
-    struct TextureOp {
-        enum Type {
-            Upload,
-            Copy,
-            Read,
-            GenMips
-        };
-        Type type;
-        QRhiTexture *dst;
-        // Specifying multiple uploads for a subresource must be supported.
-        // In the backend this can then end up, where applicable, as a
-        // single, batched copy operation with only one set of barriers.
-        // This helps when doing for example glyph cache fills.
-        using MipLevelUploadList = std::array<QVector<QRhiTextureSubresourceUploadDescription>, QRhi::MAX_MIP_LEVELS>;
-        QVarLengthArray<MipLevelUploadList, 6> subresDesc;
-        QRhiTexture *src;
-        QRhiTextureCopyDescription desc;
-        QRhiReadbackDescription rb;
-        QRhiReadbackResult *result;
-
-        static TextureOp upload(QRhiTexture *tex, const QRhiTextureUploadDescription &desc)
-        {
-            TextureOp op = {};
-            op.type = Upload;
-            op.dst = tex;
-            int maxLayer = -1;
-            for (auto it = desc.cbeginEntries(), itEnd = desc.cendEntries(); it != itEnd; ++it) {
-                if (it->layer() > maxLayer)
-                    maxLayer = it->layer();
-            }
-            op.subresDesc.resize(maxLayer + 1);
-            for (auto it = desc.cbeginEntries(), itEnd = desc.cendEntries(); it != itEnd; ++it)
-                op.subresDesc[it->layer()][it->level()].append(it->description());
-            return op;
-        }
-
-        static TextureOp copy(QRhiTexture *dst, QRhiTexture *src, const QRhiTextureCopyDescription &desc)
-        {
-            TextureOp op = {};
-            op.type = Copy;
-            op.dst = dst;
-            op.src = src;
-            op.desc = desc;
-            return op;
-        }
-
-        static TextureOp read(const QRhiReadbackDescription &rb, QRhiReadbackResult *result)
-        {
-            TextureOp op = {};
-            op.type = Read;
-            op.rb = rb;
-            op.result = result;
-            return op;
-        }
-
-        static TextureOp genMips(QRhiTexture *tex)
-        {
-            TextureOp op = {};
-            op.type = GenMips;
-            op.dst = tex;
-            return op;
-        }
-    };
-
-    int activeBufferOpCount = 0; // this is the real number of used elements in bufferOps, not bufferOps.count()
-    static const int BUFFER_OPS_STATIC_ALLOC = 1024;
-    QVarLengthArray<BufferOp, BUFFER_OPS_STATIC_ALLOC> bufferOps;
-
-    int activeTextureOpCount = 0; // this is the real number of used elements in textureOps, not textureOps.count()
-    static const int TEXTURE_OPS_STATIC_ALLOC = 256;
-    QVarLengthArray<TextureOp, TEXTURE_OPS_STATIC_ALLOC> textureOps;
-
-    QRhiResourceUpdateBatch *q = nullptr;
-    QRhiImplementation *rhi = nullptr;
-    int poolIndex = -1;
-
-    void free();
-    void merge(QRhiResourceUpdateBatchPrivate *other);
-    bool hasOptimalCapacity() const;
-    void trimOpLists();
-
-    static QRhiResourceUpdateBatchPrivate *get(QRhiResourceUpdateBatch *b) { return b->d; }
-};
-
-template<typename T>
-struct QRhiBatchedBindings
-{
-    void feed(int binding, T resource) { // binding must be strictly increasing
-        if (curBinding == -1 || binding > curBinding + 1) {
-            finish();
-            curBatch.startBinding = binding;
-            curBatch.resources.clear();
-            curBatch.resources.append(resource);
-        } else {
-            Q_ASSERT(binding == curBinding + 1);
-            curBatch.resources.append(resource);
-        }
-        curBinding = binding;
-    }
-
-    bool finish() {
-        if (!curBatch.resources.isEmpty())
-            batches.append(curBatch);
-        return !batches.isEmpty();
-    }
-
-    void clear() {
-        batches.clear();
-        curBatch.resources.clear();
-        curBinding = -1;
-    }
-
-    struct Batch {
-        uint startBinding;
-        QVarLengthArray<T, 4> resources;
-
-        bool operator==(const Batch &other) const
-        {
-            return startBinding == other.startBinding && resources == other.resources;
-        }
-
-        bool operator!=(const Batch &other) const
-        {
-            return !operator==(other);
-        }
-    };
-
-    QVarLengthArray<Batch, 4> batches; // sorted by startBinding
-
-    bool operator==(const QRhiBatchedBindings<T> &other) const
-    {
-        return batches == other.batches;
-    }
-
-    bool operator!=(const QRhiBatchedBindings<T> &other) const
-    {
-        return !operator==(other);
-    }
-
-private:
-    Batch curBatch;
-    int curBinding = -1;
-};
-
-class QRhiGlobalObjectIdGenerator
-{
-public:
-#ifdef Q_ATOMIC_INT64_IS_SUPPORTED
-    using Type = quint64;
-#else
-    using Type = quint32;
-#endif
-    static Type newId();
-};
-
-class QRhiPassResourceTracker
-{
-public:
-    bool isEmpty() const;
-    void reset();
-
-    struct UsageState {
-        int layout;
-        int access;
-        int stage;
-    };
-
-    enum BufferStage {
-        BufVertexInputStage,
-        BufVertexStage,
-        BufTCStage,
-        BufTEStage,
-        BufFragmentStage,
-        BufComputeStage,
-        BufGeometryStage
-    };
-
-    enum BufferAccess {
-        BufVertexInput,
-        BufIndexRead,
-        BufUniformRead,
-        BufStorageLoad,
-        BufStorageStore,
-        BufStorageLoadStore
-    };
-
-    void registerBuffer(QRhiBuffer *buf, int slot, BufferAccess *access, BufferStage *stage,
-                        const UsageState &state);
-
-    enum TextureStage {
-        TexVertexStage,
-        TexTCStage,
-        TexTEStage,
-        TexFragmentStage,
-        TexColorOutputStage,
-        TexDepthOutputStage,
-        TexComputeStage,
-        TexGeometryStage
-    };
-
-    enum TextureAccess {
-        TexSample,
-        TexColorOutput,
-        TexDepthOutput,
-        TexStorageLoad,
-        TexStorageStore,
-        TexStorageLoadStore
-    };
-
-    void registerTexture(QRhiTexture *tex, TextureAccess *access, TextureStage *stage,
-                         const UsageState &state);
-
-    struct Buffer {
-        int slot;
-        BufferAccess access;
-        BufferStage stage;
-        UsageState stateAtPassBegin;
-    };
-
-    using BufferIterator = QHash<QRhiBuffer *, Buffer>::const_iterator;
-    BufferIterator cbeginBuffers() const { return m_buffers.cbegin(); }
-    BufferIterator cendBuffers() const { return m_buffers.cend(); }
-
-    struct Texture {
-        TextureAccess access;
-        TextureStage stage;
-        UsageState stateAtPassBegin;
-    };
-
-    using TextureIterator = QHash<QRhiTexture *, Texture>::const_iterator;
-    TextureIterator cbeginTextures() const { return m_textures.cbegin(); }
-    TextureIterator cendTextures() const { return m_textures.cend(); }
-
-    static BufferStage toPassTrackerBufferStage(QRhiShaderResourceBinding::StageFlags stages);
-    static TextureStage toPassTrackerTextureStage(QRhiShaderResourceBinding::StageFlags stages);
-
-private:
-    QHash<QRhiBuffer *, Buffer> m_buffers;
-    QHash<QRhiTexture *, Texture> m_textures;
-};
-
-Q_DECLARE_TYPEINFO(QRhiPassResourceTracker::Buffer, Q_RELOCATABLE_TYPE);
-Q_DECLARE_TYPEINFO(QRhiPassResourceTracker::Texture, Q_RELOCATABLE_TYPE);
-
-template<typename T, int GROW = 1024>
-class QRhiBackendCommandList
-{
-public:
-    QRhiBackendCommandList() = default;
-    ~QRhiBackendCommandList() { delete[] v; }
-    inline void reset() { p = 0; }
-    inline bool isEmpty() const { return p == 0; }
-    inline T &get() {
-        if (p == a) {
-            a += GROW;
-            T *nv = new T[a];
-            if (v) {
-                memcpy(nv, v, p * sizeof(T));
-                delete[] v;
-            }
-            v = nv;
-        }
-        return v[p++];
-    }
-    inline void unget() { --p; }
-    inline T *cbegin() const { return v; }
-    inline T *cend() const { return v + p; }
-    inline T *begin() { return v; }
-    inline T *end() { return v + p; }
-private:
-    Q_DISABLE_COPY(QRhiBackendCommandList)
-    T *v = nullptr;
-    int a = 0;
-    int p = 0;
-};
-
-struct QRhiRenderTargetAttachmentTracker
-{
-    struct ResId { quint64 id; uint generation; };
-    using ResIdList = QVarLengthArray<ResId, 8 * 2 + 1>; // color, resolve, ds
-
-    template<typename TexType, typename RenderBufferType>
-    static void updateResIdList(const QRhiTextureRenderTargetDescription &desc, ResIdList *dst);
-
-    template<typename TexType, typename RenderBufferType>
-    static bool isUpToDate(const QRhiTextureRenderTargetDescription &desc, const ResIdList &currentResIdList);
-};
-
-inline bool operator==(const QRhiRenderTargetAttachmentTracker::ResId &a, const QRhiRenderTargetAttachmentTracker::ResId &b)
-{
-    return a.id == b.id && a.generation == b.generation;
-}
-
-inline bool operator!=(const QRhiRenderTargetAttachmentTracker::ResId &a, const QRhiRenderTargetAttachmentTracker::ResId &b)
-{
-    return !(a == b);
-}
-
-template<typename TexType, typename RenderBufferType>
-void QRhiRenderTargetAttachmentTracker::updateResIdList(const QRhiTextureRenderTargetDescription &desc, ResIdList *dst)
-{
-    const bool hasDepthStencil = desc.depthStencilBuffer() || desc.depthTexture();
-    dst->resize(desc.colorAttachmentCount() * 2 + (hasDepthStencil ? 1 : 0));
-    int n = 0;
-    for (auto it = desc.cbeginColorAttachments(), itEnd = desc.cendColorAttachments(); it != itEnd; ++it, ++n) {
-        const QRhiColorAttachment &colorAtt(*it);
-        if (colorAtt.texture()) {
-            TexType *texD = QRHI_RES(TexType, colorAtt.texture());
-            (*dst)[n] = { texD->globalResourceId(), texD->generation };
-        } else if (colorAtt.renderBuffer()) {
-            RenderBufferType *rbD = QRHI_RES(RenderBufferType, colorAtt.renderBuffer());
-            (*dst)[n] = { rbD->globalResourceId(), rbD->generation };
-        } else {
-            (*dst)[n] = { 0, 0 };
-        }
-        ++n;
-        if (colorAtt.resolveTexture()) {
-            TexType *texD = QRHI_RES(TexType, colorAtt.resolveTexture());
-            (*dst)[n] = { texD->globalResourceId(), texD->generation };
-        } else {
-            (*dst)[n] = { 0, 0 };
-        }
-    }
-    if (hasDepthStencil) {
-        if (desc.depthTexture()) {
-            TexType *depthTexD = QRHI_RES(TexType, desc.depthTexture());
-            (*dst)[n] = { depthTexD->globalResourceId(), depthTexD->generation };
-        } else if (desc.depthStencilBuffer()) {
-            RenderBufferType *depthRbD = QRHI_RES(RenderBufferType, desc.depthStencilBuffer());
-            (*dst)[n] = { depthRbD->globalResourceId(), depthRbD->generation };
-        } else {
-            (*dst)[n] = { 0, 0 };
-        }
-    }
-}
-
-template<typename TexType, typename RenderBufferType>
-bool QRhiRenderTargetAttachmentTracker::isUpToDate(const QRhiTextureRenderTargetDescription &desc, const ResIdList &currentResIdList)
-{
-    // Just as setShaderResources() recognizes if an srb's referenced
-    // resources have been rebuilt (got a create() since the srb's
-    // create()), we should do the same for the textures and renderbuffers
-    // referenced from the rendertarget. It is not uncommon that a texture
-    // or ds buffer gets resized due to following a window size in some
-    // form, which involves a create() on them. It is then nice if the
-    // render target auto-rebuilds in beginPass().
-
-    ResIdList resIdList;
-    updateResIdList<TexType, RenderBufferType>(desc, &resIdList);
-    return resIdList == currentResIdList;
-}
-
-template<typename T>
-inline T *qrhi_objectFromProxyData(QRhiSwapChainProxyData *pd, QWindow *window, QRhi::Implementation impl, uint objectIndex)
-{
-    Q_ASSERT(objectIndex < std::size(pd->reserved));
-    if (!pd->reserved[objectIndex]) // // was not set, no other choice, do it here, whatever thread this is
-        *pd = QRhi::updateSwapChainProxyData(impl, window);
-    return static_cast<T *>(pd->reserved[objectIndex]);
-}
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/rhi/qrhi_platform.h b/src/gui/rhi/qrhi_platform.h
new file mode 100644
index 0000000000..8307e9217c
--- /dev/null
+++ b/src/gui/rhi/qrhi_platform.h
@@ -0,0 +1,172 @@
+// 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
+
+#ifndef QRHIPLATFORM_H
+#define QRHIPLATFORM_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is part of the RHI API, with limited compatibility guarantees.
+// Usage of this API may make your code source and binary incompatible with
+// future versions of Qt.
+//
+
+#include <rhi/qrhi.h>
+
+#if QT_CONFIG(opengl)
+#include <QtGui/qsurfaceformat.h>
+#endif
+
+#if QT_CONFIG(vulkan)
+#include <QtGui/qvulkaninstance.h>
+#endif
+
+#if defined(Q_OS_MACOS) || defined(Q_OS_IOS) || defined(Q_QDOC)
+Q_FORWARD_DECLARE_OBJC_CLASS(MTLDevice);
+Q_FORWARD_DECLARE_OBJC_CLASS(MTLCommandQueue);
+Q_FORWARD_DECLARE_OBJC_CLASS(MTLCommandBuffer);
+Q_FORWARD_DECLARE_OBJC_CLASS(MTLRenderCommandEncoder);
+#endif
+
+QT_BEGIN_NAMESPACE
+
+struct Q_GUI_EXPORT QRhiNullInitParams : public QRhiInitParams
+{
+};
+
+struct Q_GUI_EXPORT QRhiNullNativeHandles : public QRhiNativeHandles
+{
+};
+
+#if QT_CONFIG(opengl) || defined(Q_QDOC)
+
+class QOpenGLContext;
+class QOffscreenSurface;
+class QSurface;
+class QWindow;
+
+struct Q_GUI_EXPORT QRhiGles2InitParams : public QRhiInitParams
+{
+    QRhiGles2InitParams();
+
+    QSurfaceFormat format;
+    QSurface *fallbackSurface = nullptr;
+    QWindow *window = nullptr;
+    QOpenGLContext *shareContext = nullptr;
+
+    static QOffscreenSurface *newFallbackSurface(const QSurfaceFormat &format = QSurfaceFormat::defaultFormat());
+};
+
+struct Q_GUI_EXPORT QRhiGles2NativeHandles : public QRhiNativeHandles
+{
+    QOpenGLContext *context = nullptr;
+};
+
+#endif // opengl/qdoc
+
+#if QT_CONFIG(vulkan) || defined(Q_QDOC)
+
+struct Q_GUI_EXPORT QRhiVulkanInitParams : public QRhiInitParams
+{
+    QVulkanInstance *inst = nullptr;
+    QWindow *window = nullptr;
+    QByteArrayList deviceExtensions;
+
+    static QByteArrayList preferredInstanceExtensions();
+    static QByteArrayList preferredExtensionsForImportedDevice();
+};
+
+struct Q_GUI_EXPORT QRhiVulkanNativeHandles : public QRhiNativeHandles
+{
+    // to import a physical device (always required)
+    VkPhysicalDevice physDev = VK_NULL_HANDLE;
+    // to import a device and queue
+    VkDevice dev = VK_NULL_HANDLE;
+    quint32 gfxQueueFamilyIdx = 0;
+    quint32 gfxQueueIdx = 0;
+    VkQueue gfxQueue = VK_NULL_HANDLE;
+    // and optionally, the mem allocator
+    void *vmemAllocator = nullptr;
+};
+
+struct Q_GUI_EXPORT QRhiVulkanCommandBufferNativeHandles : public QRhiNativeHandles
+{
+    VkCommandBuffer commandBuffer = VK_NULL_HANDLE;
+};
+
+struct Q_GUI_EXPORT QRhiVulkanRenderPassNativeHandles : public QRhiNativeHandles
+{
+    VkRenderPass renderPass = VK_NULL_HANDLE;
+};
+
+#endif // vulkan/qdoc
+
+#if defined(Q_OS_WIN) || defined(Q_QDOC)
+
+// no d3d includes here, to prevent precompiled header mess due to COM, hence the void pointers
+
+struct Q_GUI_EXPORT QRhiD3D11InitParams : public QRhiInitParams
+{
+    bool enableDebugLayer = false;
+};
+
+struct Q_GUI_EXPORT QRhiD3D11NativeHandles : public QRhiNativeHandles
+{
+    // to import a device and a context
+    void *dev = nullptr;
+    void *context = nullptr;
+    // alternatively, to specify the device feature level and/or the adapter to use
+    int featureLevel = 0;
+    quint32 adapterLuidLow = 0;
+    qint32 adapterLuidHigh = 0;
+};
+
+struct Q_GUI_EXPORT QRhiD3D12InitParams : public QRhiInitParams
+{
+    bool enableDebugLayer = false;
+};
+
+struct Q_GUI_EXPORT QRhiD3D12NativeHandles : public QRhiNativeHandles
+{
+    // to import a device
+    void *dev = nullptr;
+    int minimumFeatureLevel = 0;
+    // to just specify the adapter to use, set these and leave dev set to null
+    quint32 adapterLuidLow = 0;
+    qint32 adapterLuidHigh = 0;
+    // in addition, can specify the command queue to use
+    void *commandQueue = nullptr;
+};
+
+struct Q_GUI_EXPORT QRhiD3D12CommandBufferNativeHandles : public QRhiNativeHandles
+{
+    void *commandList = nullptr; // ID3D12GraphicsCommandList
+};
+
+#endif // WIN/QDOC
+
+#if defined(Q_OS_MACOS) || defined(Q_OS_IOS) || defined(Q_QDOC)
+
+struct Q_GUI_EXPORT QRhiMetalInitParams : public QRhiInitParams
+{
+};
+
+struct Q_GUI_EXPORT QRhiMetalNativeHandles : public QRhiNativeHandles
+{
+    MTLDevice *dev = nullptr;
+    MTLCommandQueue *cmdQueue = nullptr;
+};
+
+struct Q_GUI_EXPORT QRhiMetalCommandBufferNativeHandles : public QRhiNativeHandles
+{
+    MTLCommandBuffer *commandBuffer = nullptr;
+    MTLRenderCommandEncoder *encoder = nullptr;
+};
+
+#endif // MACOS/IOS/QDOC
+
+QT_END_NAMESPACE
+
+#endif
diff --git a/src/gui/rhi/qrhid3d11.cpp b/src/gui/rhi/qrhid3d11.cpp
index d995358568..1b1afeda4d 100644
--- a/src/gui/rhi/qrhid3d11.cpp
+++ b/src/gui/rhi/qrhid3d11.cpp
@@ -1,8 +1,8 @@
 // Copyright (C) 2019 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
 
-#include "qrhid3d11_p_p.h"
-#include "qshader_p.h"
+#include "qrhid3d11_p.h"
+#include "qshader.h"
 #include "vs_test_p.h"
 #include <QWindow>
 #include <qmath.h>
@@ -28,10 +28,13 @@ using namespace Qt::StringLiterals;
 
 /*!
     \class QRhiD3D11InitParams
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Direct3D 11 specific initialization parameters.
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     A D3D11-based QRhi needs no special parameters for initialization. If
     desired, enableDebugLayer can be set to \c true to enable the Direct3D
     debug layer. This can be useful during development, but should be avoided
@@ -70,16 +73,46 @@ using namespace Qt::StringLiterals;
  */
 
 /*!
+    \variable QRhiD3D11InitParams::enableDebugLayer
+
+    When set to true, a debug device is created, assuming the debug layer is
+    available. The default value is false.
+*/
+
+/*!
     \class QRhiD3D11NativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Holds the D3D device and device context used by the QRhi.
 
     \note The class uses \c{void *} as the type since including the COM-based
     \c{d3d11.h} headers is not acceptable here. The actual types are
     \c{ID3D11Device *} and \c{ID3D11DeviceContext *}.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
+/*!
+    \variable QRhiD3D11NativeHandles::dev
+*/
+
+/*!
+    \variable QRhiD3D11NativeHandles::context
+*/
+
+/*!
+    \variable QRhiD3D11NativeHandles::featureLevel
+*/
+
+/*!
+    \variable QRhiD3D11NativeHandles::adapterLuidLow
+*/
+
+/*!
+    \variable QRhiD3D11NativeHandles::adapterLuidHigh
+*/
+
 // help mingw with its ancient sdk headers
 #ifndef DXGI_ADAPTER_FLAG_SOFTWARE
 #define DXGI_ADAPTER_FLAG_SOFTWARE 2
diff --git a/src/gui/rhi/qrhid3d11_p.h b/src/gui/rhi/qrhid3d11_p.h
index 2ab3e9fea3..e410375029 100644
--- a/src/gui/rhi/qrhid3d11_p.h
+++ b/src/gui/rhi/qrhid3d11_p.h
@@ -1,8 +1,8 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#ifndef QRHID3D11_H
-#define QRHID3D11_H
+#ifndef QRHID3D11_P_H
+#define QRHID3D11_P_H
 
 //
 //  W A R N I N G
@@ -15,28 +15,838 @@
 // We mean it.
 //
 
-#include <private/qrhi_p.h>
+#include "qrhi_p.h"
+#include "qshaderdescription.h"
+#include <QWindow>
 
-// no d3d includes here, to prevent precompiled header mess due to COM
+#include <d3d11_1.h>
+#include <dxgi1_6.h>
+#include <dcomp.h>
 
 QT_BEGIN_NAMESPACE
 
-struct Q_GUI_EXPORT QRhiD3D11InitParams : public QRhiInitParams
+class QRhiD3D11;
+
+struct QD3D11Buffer : public QRhiBuffer
+{
+    QD3D11Buffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
+    ~QD3D11Buffer();
+    void destroy() override;
+    bool create() override;
+    QRhiBuffer::NativeBuffer nativeBuffer() override;
+    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
+    void endFullDynamicBufferUpdateForCurrentFrame() override;
+
+    ID3D11UnorderedAccessView *unorderedAccessView(quint32 offset);
+
+    ID3D11Buffer *buffer = nullptr;
+    char *dynBuf = nullptr;
+    bool hasPendingDynamicUpdates = false;
+    QHash<quint32, ID3D11UnorderedAccessView *> uavs;
+    uint generation = 0;
+    friend class QRhiD3D11;
+};
+
+struct QD3D11RenderBuffer : public QRhiRenderBuffer
+{
+    QD3D11RenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
+                       int sampleCount, QRhiRenderBuffer::Flags flags,
+                       QRhiTexture::Format backingFormatHint);
+    ~QD3D11RenderBuffer();
+    void destroy() override;
+    bool create() override;
+    QRhiTexture::Format backingFormat() const override;
+
+    ID3D11Texture2D *tex = nullptr;
+    ID3D11DepthStencilView *dsv = nullptr;
+    ID3D11RenderTargetView *rtv = nullptr;
+    DXGI_FORMAT dxgiFormat;
+    DXGI_SAMPLE_DESC sampleDesc;
+    uint generation = 0;
+    friend class QRhiD3D11;
+};
+
+struct QD3D11Texture : public QRhiTexture
+{
+    QD3D11Texture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
+                  int arraySize, int sampleCount, Flags flags);
+    ~QD3D11Texture();
+    void destroy() override;
+    bool create() override;
+    bool createFrom(NativeTexture src) override;
+    NativeTexture nativeTexture() override;
+
+    bool prepareCreate(QSize *adjustedSize = nullptr);
+    bool finishCreate();
+    ID3D11UnorderedAccessView *unorderedAccessViewForLevel(int level);
+    ID3D11Resource *textureResource() const
+    {
+        if (tex)
+            return tex;
+        else if (tex1D)
+            return tex1D;
+        return tex3D;
+    }
+
+    ID3D11Texture2D *tex = nullptr;
+    ID3D11Texture3D *tex3D = nullptr;
+    ID3D11Texture1D *tex1D = nullptr;
+    bool owns = true;
+    ID3D11ShaderResourceView *srv = nullptr;
+    DXGI_FORMAT dxgiFormat;
+    uint mipLevelCount = 0;
+    DXGI_SAMPLE_DESC sampleDesc;
+    ID3D11UnorderedAccessView *perLevelViews[QRhi::MAX_MIP_LEVELS];
+    uint generation = 0;
+    friend class QRhiD3D11;
+};
+
+struct QD3D11Sampler : public QRhiSampler
+{
+    QD3D11Sampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
+                  AddressMode u, AddressMode v, AddressMode w);
+    ~QD3D11Sampler();
+    void destroy() override;
+    bool create() override;
+
+    ID3D11SamplerState *samplerState = nullptr;
+    uint generation = 0;
+    friend class QRhiD3D11;
+};
+
+struct QD3D11RenderPassDescriptor : public QRhiRenderPassDescriptor
+{
+    QD3D11RenderPassDescriptor(QRhiImplementation *rhi);
+    ~QD3D11RenderPassDescriptor();
+    void destroy() override;
+    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
+    QVector<quint32> serializedFormat() const override;
+};
+
+struct QD3D11RenderTargetData
+{
+    QD3D11RenderTargetData(QRhiImplementation *)
+    {
+        for (int i = 0; i < MAX_COLOR_ATTACHMENTS; ++i)
+            rtv[i] = nullptr;
+    }
+
+    QD3D11RenderPassDescriptor *rp = nullptr;
+    QSize pixelSize;
+    float dpr = 1;
+    int sampleCount = 1;
+    int colorAttCount = 0;
+    int dsAttCount = 0;
+
+    static const int MAX_COLOR_ATTACHMENTS = 8;
+    ID3D11RenderTargetView *rtv[MAX_COLOR_ATTACHMENTS];
+    ID3D11DepthStencilView *dsv = nullptr;
+
+    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
+};
+
+struct QD3D11SwapChainRenderTarget : public QRhiSwapChainRenderTarget
+{
+    QD3D11SwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
+    ~QD3D11SwapChainRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QD3D11RenderTargetData d;
+};
+
+struct QD3D11TextureRenderTarget : public QRhiTextureRenderTarget
+{
+    QD3D11TextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
+    ~QD3D11TextureRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool create() override;
+
+    QD3D11RenderTargetData d;
+    bool ownsRtv[QD3D11RenderTargetData::MAX_COLOR_ATTACHMENTS];
+    ID3D11RenderTargetView *rtv[QD3D11RenderTargetData::MAX_COLOR_ATTACHMENTS];
+    bool ownsDsv = false;
+    ID3D11DepthStencilView *dsv = nullptr;
+    friend class QRhiD3D11;
+};
+
+struct QD3D11ShaderResourceBindings : public QRhiShaderResourceBindings
+{
+    QD3D11ShaderResourceBindings(QRhiImplementation *rhi);
+    ~QD3D11ShaderResourceBindings();
+    void destroy() override;
+    bool create() override;
+    void updateResources(UpdateFlags flags) override;
+
+    bool hasDynamicOffset = false;
+    QVarLengthArray<QRhiShaderResourceBinding, 8> sortedBindings;
+    uint generation = 0;
+
+    // Keep track of the generation number of each referenced QRhi* to be able
+    // to detect that the batched bindings are out of date.
+    struct BoundUniformBufferData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundSampledTextureData {
+        int count;
+        struct {
+            quint64 texId;
+            uint texGeneration;
+            quint64 samplerId;
+            uint samplerGeneration;
+        } d[QRhiShaderResourceBinding::Data::MAX_TEX_SAMPLER_ARRAY_SIZE];
+    };
+    struct BoundStorageImageData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundStorageBufferData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundResourceData {
+        union {
+            BoundUniformBufferData ubuf;
+            BoundSampledTextureData stex;
+            BoundStorageImageData simage;
+            BoundStorageBufferData sbuf;
+        };
+    };
+    QVarLengthArray<BoundResourceData, 8> boundResourceData;
+
+    struct StageUniformBufferBatches {
+        bool present = false;
+        QRhiBatchedBindings<ID3D11Buffer *> ubufs;
+        QRhiBatchedBindings<UINT> ubuforigbindings;
+        QRhiBatchedBindings<UINT> ubufoffsets;
+        QRhiBatchedBindings<UINT> ubufsizes;
+        void finish() {
+            present = ubufs.finish();
+            ubuforigbindings.finish();
+            ubufoffsets.finish();
+            ubufsizes.finish();
+        }
+        void clear() {
+            ubufs.clear();
+            ubuforigbindings.clear();
+            ubufoffsets.clear();
+            ubufsizes.clear();
+        }
+    };
+
+    struct StageSamplerBatches {
+        bool present = false;
+        QRhiBatchedBindings<ID3D11SamplerState *> samplers;
+        QRhiBatchedBindings<ID3D11ShaderResourceView *> shaderresources;
+        void finish() {
+            present = samplers.finish();
+            shaderresources.finish();
+        }
+        void clear() {
+            samplers.clear();
+            shaderresources.clear();
+        }
+    };
+
+    struct StageUavBatches {
+        bool present = false;
+        QRhiBatchedBindings<ID3D11UnorderedAccessView *> uavs;
+        void finish() {
+            present = uavs.finish();
+        }
+        void clear() {
+            uavs.clear();
+        }
+    };
+
+    StageUniformBufferBatches vsUniformBufferBatches;
+    StageUniformBufferBatches hsUniformBufferBatches;
+    StageUniformBufferBatches dsUniformBufferBatches;
+    StageUniformBufferBatches gsUniformBufferBatches;
+    StageUniformBufferBatches fsUniformBufferBatches;
+    StageUniformBufferBatches csUniformBufferBatches;
+
+    StageSamplerBatches vsSamplerBatches;
+    StageSamplerBatches hsSamplerBatches;
+    StageSamplerBatches dsSamplerBatches;
+    StageSamplerBatches gsSamplerBatches;
+    StageSamplerBatches fsSamplerBatches;
+    StageSamplerBatches csSamplerBatches;
+
+    StageUavBatches csUavBatches;
+
+    friend class QRhiD3D11;
+};
+
+Q_DECLARE_TYPEINFO(QD3D11ShaderResourceBindings::BoundResourceData, Q_RELOCATABLE_TYPE);
+
+struct QD3D11GraphicsPipeline : public QRhiGraphicsPipeline
+{
+    QD3D11GraphicsPipeline(QRhiImplementation *rhi);
+    ~QD3D11GraphicsPipeline();
+    void destroy() override;
+    bool create() override;
+
+    ID3D11DepthStencilState *dsState = nullptr;
+    ID3D11BlendState *blendState = nullptr;
+    struct {
+        ID3D11VertexShader *shader = nullptr;
+        QShader::NativeResourceBindingMap nativeResourceBindingMap;
+    } vs;
+    struct {
+        ID3D11HullShader *shader = nullptr;
+        QShader::NativeResourceBindingMap nativeResourceBindingMap;
+    } hs;
+    struct {
+        ID3D11DomainShader *shader = nullptr;
+        QShader::NativeResourceBindingMap nativeResourceBindingMap;
+    } ds;
+    struct {
+        ID3D11GeometryShader *shader = nullptr;
+        QShader::NativeResourceBindingMap nativeResourceBindingMap;
+    } gs;
+    struct {
+        ID3D11PixelShader *shader = nullptr;
+        QShader::NativeResourceBindingMap nativeResourceBindingMap;
+    } fs;
+    ID3D11InputLayout *inputLayout = nullptr;
+    D3D11_PRIMITIVE_TOPOLOGY d3dTopology = D3D11_PRIMITIVE_TOPOLOGY_TRIANGLELIST;
+    ID3D11RasterizerState *rastState = nullptr;
+    uint generation = 0;
+    friend class QRhiD3D11;
+};
+
+struct QD3D11ComputePipeline : public QRhiComputePipeline
 {
-    bool enableDebugLayer = false;
+    QD3D11ComputePipeline(QRhiImplementation *rhi);
+    ~QD3D11ComputePipeline();
+    void destroy() override;
+    bool create() override;
+
+    struct {
+        ID3D11ComputeShader *shader = nullptr;
+        QShader::NativeResourceBindingMap nativeResourceBindingMap;
+    } cs;
+    uint generation = 0;
+    friend class QRhiD3D11;
+};
+
+struct QD3D11SwapChain;
+
+struct QD3D11CommandBuffer : public QRhiCommandBuffer
+{
+    QD3D11CommandBuffer(QRhiImplementation *rhi);
+    ~QD3D11CommandBuffer();
+    void destroy() override;
+
+    // these must be kept at a reasonably low value otherwise sizeof Command explodes
+    static const int MAX_DYNAMIC_OFFSET_COUNT = 8;
+    static const int MAX_VERTEX_BUFFER_BINDING_COUNT = 8;
+
+    struct Command {
+        enum Cmd {
+            ResetShaderResources,
+            SetRenderTarget,
+            Clear,
+            Viewport,
+            Scissor,
+            BindVertexBuffers,
+            BindIndexBuffer,
+            BindGraphicsPipeline,
+            BindShaderResources,
+            StencilRef,
+            BlendConstants,
+            Draw,
+            DrawIndexed,
+            UpdateSubRes,
+            CopySubRes,
+            ResolveSubRes,
+            GenMip,
+            DebugMarkBegin,
+            DebugMarkEnd,
+            DebugMarkMsg,
+            BindComputePipeline,
+            Dispatch
+        };
+        enum ClearFlag { Color = 1, Depth = 2, Stencil = 4 };
+        Cmd cmd;
+
+        // QRhi*/QD3D11* references should be kept at minimum (so no
+        // QRhiTexture/Buffer/etc. pointers).
+        union Args {
+            struct {
+                QRhiRenderTarget *rt;
+            } setRenderTarget;
+            struct {
+                QRhiRenderTarget *rt;
+                int mask;
+                float c[4];
+                float d;
+                quint32 s;
+            } clear;
+            struct {
+                float x, y, w, h;
+                float d0, d1;
+            } viewport;
+            struct {
+                int x, y, w, h;
+            } scissor;
+            struct {
+                int startSlot;
+                int slotCount;
+                ID3D11Buffer *buffers[MAX_VERTEX_BUFFER_BINDING_COUNT];
+                UINT offsets[MAX_VERTEX_BUFFER_BINDING_COUNT];
+                UINT strides[MAX_VERTEX_BUFFER_BINDING_COUNT];
+            } bindVertexBuffers;
+            struct {
+                ID3D11Buffer *buffer;
+                quint32 offset;
+                DXGI_FORMAT format;
+            } bindIndexBuffer;
+            struct {
+                QD3D11GraphicsPipeline *ps;
+            } bindGraphicsPipeline;
+            struct {
+                QD3D11ShaderResourceBindings *srb;
+                bool offsetOnlyChange;
+                int dynamicOffsetCount;
+                uint dynamicOffsetPairs[MAX_DYNAMIC_OFFSET_COUNT * 2]; // binding, offsetInConstants
+            } bindShaderResources;
+            struct {
+                QD3D11GraphicsPipeline *ps;
+                quint32 ref;
+            } stencilRef;
+            struct {
+                QD3D11GraphicsPipeline *ps;
+                float c[4];
+            } blendConstants;
+            struct {
+                QD3D11GraphicsPipeline *ps;
+                quint32 vertexCount;
+                quint32 instanceCount;
+                quint32 firstVertex;
+                quint32 firstInstance;
+            } draw;
+            struct {
+                QD3D11GraphicsPipeline *ps;
+                quint32 indexCount;
+                quint32 instanceCount;
+                quint32 firstIndex;
+                qint32 vertexOffset;
+                quint32 firstInstance;
+            } drawIndexed;
+            struct {
+                ID3D11Resource *dst;
+                UINT dstSubRes;
+                bool hasDstBox;
+                D3D11_BOX dstBox;
+                const void *src; // must come from retain*()
+                UINT srcRowPitch;
+            } updateSubRes;
+            struct {
+                ID3D11Resource *dst;
+                UINT dstSubRes;
+                UINT dstX;
+                UINT dstY;
+                UINT dstZ;
+                ID3D11Resource *src;
+                UINT srcSubRes;
+                bool hasSrcBox;
+                D3D11_BOX srcBox;
+            } copySubRes;
+            struct {
+                ID3D11Resource *dst;
+                UINT dstSubRes;
+                ID3D11Resource *src;
+                UINT srcSubRes;
+                DXGI_FORMAT format;
+            } resolveSubRes;
+            struct {
+                ID3D11ShaderResourceView *srv;
+            } genMip;
+            struct {
+                char s[64];
+            } debugMark;
+            struct {
+                QD3D11ComputePipeline *ps;
+            } bindComputePipeline;
+            struct {
+                UINT x;
+                UINT y;
+                UINT z;
+            } dispatch;
+        } args;
+    };
+
+    enum PassType {
+        NoPass,
+        RenderPass,
+        ComputePass
+    };
+
+    QRhiBackendCommandList<Command> commands;
+    PassType recordingPass;
+    double lastGpuTime = 0;
+    QRhiRenderTarget *currentTarget;
+    QRhiGraphicsPipeline *currentGraphicsPipeline;
+    QRhiComputePipeline *currentComputePipeline;
+    uint currentPipelineGeneration;
+    QRhiShaderResourceBindings *currentGraphicsSrb;
+    QRhiShaderResourceBindings *currentComputeSrb;
+    uint currentSrbGeneration;
+    ID3D11Buffer *currentIndexBuffer;
+    quint32 currentIndexOffset;
+    DXGI_FORMAT currentIndexFormat;
+    ID3D11Buffer *currentVertexBuffers[D3D11_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT];
+    quint32 currentVertexOffsets[D3D11_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT];
+
+    QVarLengthArray<QByteArray, 4> dataRetainPool;
+    QVarLengthArray<QRhiBufferData, 4> bufferDataRetainPool;
+    QVarLengthArray<QImage, 4> imageRetainPool;
+
+    // relies heavily on implicit sharing (no copies of the actual data will be made)
+    const uchar *retainData(const QByteArray &data) {
+        dataRetainPool.append(data);
+        return reinterpret_cast<const uchar *>(dataRetainPool.last().constData());
+    }
+    const uchar *retainBufferData(const QRhiBufferData &data) {
+        bufferDataRetainPool.append(data);
+        return reinterpret_cast<const uchar *>(bufferDataRetainPool.last().constData());
+    }
+    const uchar *retainImage(const QImage &image) {
+        imageRetainPool.append(image);
+        return imageRetainPool.last().constBits();
+    }
+    void resetCommands() {
+        commands.reset();
+        dataRetainPool.clear();
+        bufferDataRetainPool.clear();
+        imageRetainPool.clear();
+    }
+    void resetState() {
+        recordingPass = NoPass;
+        // do not zero lastGpuTime
+        currentTarget = nullptr;
+        resetCommands();
+        resetCachedState();
+    }
+    void resetCachedState() {
+        currentGraphicsPipeline = nullptr;
+        currentComputePipeline = nullptr;
+        currentPipelineGeneration = 0;
+        currentGraphicsSrb = nullptr;
+        currentComputeSrb = nullptr;
+        currentSrbGeneration = 0;
+        currentIndexBuffer = nullptr;
+        currentIndexOffset = 0;
+        currentIndexFormat = DXGI_FORMAT_R16_UINT;
+        memset(currentVertexBuffers, 0, sizeof(currentVertexBuffers));
+        memset(currentVertexOffsets, 0, sizeof(currentVertexOffsets));
+    }
+};
+
+static const int QD3D11_SWAPCHAIN_BUFFER_COUNT = 2;
+
+struct QD3D11Timestamps
+{
+    static const int MAX_TIMESTAMP_PAIRS = QD3D11_SWAPCHAIN_BUFFER_COUNT;
+    bool active[MAX_TIMESTAMP_PAIRS] = {};
+    ID3D11Query *disjointQuery[MAX_TIMESTAMP_PAIRS] = {};
+    ID3D11Query *query[MAX_TIMESTAMP_PAIRS * 2] = {};
+    int pairCount = 0;
+
+    bool prepare(int pairCount, QRhiD3D11 *rhiD);
+    void destroy();
+    bool tryQueryTimestamps(int idx, ID3D11DeviceContext *context, double *elapsedSec);
+};
+
+struct QD3D11SwapChain : public QRhiSwapChain
+{
+    QD3D11SwapChain(QRhiImplementation *rhi);
+    ~QD3D11SwapChain();
+    void destroy() override;
+
+    QRhiCommandBuffer *currentFrameCommandBuffer() override;
+    QRhiRenderTarget *currentFrameRenderTarget() override;
+
+    QSize surfacePixelSize() override;
+    bool isFormatSupported(Format f) override;
+    QRhiSwapChainHdrInfo hdrInfo() override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool createOrResize() override;
+
+    void releaseBuffers();
+    bool newColorBuffer(const QSize &size, DXGI_FORMAT format, DXGI_SAMPLE_DESC sampleDesc,
+                        ID3D11Texture2D **tex, ID3D11RenderTargetView **rtv) const;
+
+    QWindow *window = nullptr;
+    QSize pixelSize;
+    QD3D11SwapChainRenderTarget rt;
+    QD3D11CommandBuffer cb;
+    DXGI_FORMAT colorFormat;
+    DXGI_FORMAT srgbAdjustedColorFormat;
+    IDXGISwapChain *swapChain = nullptr;
+    UINT swapChainFlags = 0;
+    ID3D11Texture2D *backBufferTex;
+    ID3D11RenderTargetView *backBufferRtv;
+    static const int BUFFER_COUNT = QD3D11_SWAPCHAIN_BUFFER_COUNT;
+    ID3D11Texture2D *msaaTex[BUFFER_COUNT];
+    ID3D11RenderTargetView *msaaRtv[BUFFER_COUNT];
+    DXGI_SAMPLE_DESC sampleDesc;
+    int currentFrameSlot = 0;
+    int frameCount = 0;
+    QD3D11RenderBuffer *ds = nullptr;
+    UINT swapInterval = 1;
+    IDCompositionTarget *dcompTarget = nullptr;
+    IDCompositionVisual *dcompVisual = nullptr;
+    QD3D11Timestamps timestamps;
 };
 
-struct Q_GUI_EXPORT QRhiD3D11NativeHandles : public QRhiNativeHandles
+class QRhiD3D11 : public QRhiImplementation
 {
-    // to import a device and a context
-    void *dev = nullptr;
-    void *context = nullptr;
-    // alternatively, to specify the device feature level and/or the adapter to use
-    int featureLevel = 0;
-    quint32 adapterLuidLow = 0;
-    qint32 adapterLuidHigh = 0;
+public:
+    QRhiD3D11(QRhiD3D11InitParams *params, QRhiD3D11NativeHandles *importDevice = nullptr);
+
+    bool create(QRhi::Flags flags) override;
+    void destroy() override;
+
+    QRhiGraphicsPipeline *createGraphicsPipeline() override;
+    QRhiComputePipeline *createComputePipeline() override;
+    QRhiShaderResourceBindings *createShaderResourceBindings() override;
+    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
+                             QRhiBuffer::UsageFlags usage,
+                             quint32 size) override;
+    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
+                                         const QSize &pixelSize,
+                                         int sampleCount,
+                                         QRhiRenderBuffer::Flags flags,
+                                         QRhiTexture::Format backingFormatHint) override;
+    QRhiTexture *createTexture(QRhiTexture::Format format,
+                               const QSize &pixelSize,
+                               int depth,
+                               int arraySize,
+                               int sampleCount,
+                               QRhiTexture::Flags flags) override;
+    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
+                               QRhiSampler::Filter minFilter,
+                               QRhiSampler::Filter mipmapMode,
+                               QRhiSampler:: AddressMode u,
+                               QRhiSampler::AddressMode v,
+                               QRhiSampler::AddressMode w) override;
+
+    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
+                                                       QRhiTextureRenderTarget::Flags flags) override;
+
+    QRhiSwapChain *createSwapChain() override;
+    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult finish() override;
+
+    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void beginPass(QRhiCommandBuffer *cb,
+                   QRhiRenderTarget *rt,
+                   const QColor &colorClearValue,
+                   const QRhiDepthStencilClearValue &depthStencilClearValue,
+                   QRhiResourceUpdateBatch *resourceUpdates,
+                   QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void setGraphicsPipeline(QRhiCommandBuffer *cb,
+                             QRhiGraphicsPipeline *ps) override;
+
+    void setShaderResources(QRhiCommandBuffer *cb,
+                            QRhiShaderResourceBindings *srb,
+                            int dynamicOffsetCount,
+                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
+
+    void setVertexInput(QRhiCommandBuffer *cb,
+                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
+                        QRhiBuffer *indexBuf, quint32 indexOffset,
+                        QRhiCommandBuffer::IndexFormat indexFormat) override;
+
+    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
+    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
+    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
+    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
+
+    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
+              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
+
+    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
+                     quint32 instanceCount, quint32 firstIndex,
+                     qint32 vertexOffset, quint32 firstInstance) override;
+
+    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
+    void debugMarkEnd(QRhiCommandBuffer *cb) override;
+    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
+
+    void beginComputePass(QRhiCommandBuffer *cb,
+                          QRhiResourceUpdateBatch *resourceUpdates,
+                          QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
+    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
+
+    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
+    void beginExternal(QRhiCommandBuffer *cb) override;
+    void endExternal(QRhiCommandBuffer *cb) override;
+    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
+
+    QList<int> supportedSampleCounts() const override;
+    int ubufAlignment() const override;
+    bool isYUpInFramebuffer() const override;
+    bool isYUpInNDC() const override;
+    bool isClipDepthZeroToOne() const override;
+    QMatrix4x4 clipSpaceCorrMatrix() const override;
+    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
+    bool isFeatureSupported(QRhi::Feature feature) const override;
+    int resourceLimit(QRhi::ResourceLimit limit) const override;
+    const QRhiNativeHandles *nativeHandles() override;
+    QRhiDriverInfo driverInfo() const override;
+    QRhiStats statistics() override;
+    bool makeThreadLocalNativeContextCurrent() override;
+    void releaseCachedResources() override;
+    bool isDeviceLost() const override;
+
+    QByteArray pipelineCacheData() override;
+    void setPipelineCacheData(const QByteArray &data) override;
+
+    void enqueueSubresUpload(QD3D11Texture *texD, QD3D11CommandBuffer *cbD,
+                             int layer, int level, const QRhiTextureSubresourceUploadDescription &subresDesc);
+    void enqueueResourceUpdates(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates);
+    void updateShaderResourceBindings(QD3D11ShaderResourceBindings *srbD,
+                                      const QShader::NativeResourceBindingMap *nativeResourceBindingMaps[]);
+    void executeBufferHostWrites(QD3D11Buffer *bufD);
+    void bindShaderResources(QD3D11ShaderResourceBindings *srbD,
+                             const uint *dynOfsPairs, int dynOfsPairCount,
+                             bool offsetOnlyChange);
+    void resetShaderResources();
+    void executeCommandBuffer(QD3D11CommandBuffer *cbD, QD3D11SwapChain *timestampSwapChain = nullptr);
+    DXGI_SAMPLE_DESC effectiveSampleCount(int sampleCount) const;
+    void finishActiveReadbacks();
+    void reportLiveObjects(ID3D11Device *device);
+    void clearShaderCache();
+    QByteArray compileHlslShaderSource(const QShader &shader, QShader::Variant shaderVariant, uint flags,
+                                       QString *error, QShaderKey *usedShaderKey);
+    bool ensureDirectCompositionDevice();
+
+    QRhi::Flags rhiFlags;
+    bool debugLayer = false;
+    bool importedDeviceAndContext = false;
+    ID3D11Device *dev = nullptr;
+    ID3D11DeviceContext1 *context = nullptr;
+    D3D_FEATURE_LEVEL featureLevel = D3D_FEATURE_LEVEL(0);
+    LUID adapterLuid = {};
+    ID3DUserDefinedAnnotation *annotations = nullptr;
+    IDXGIAdapter1 *activeAdapter = nullptr;
+    IDXGIFactory1 *dxgiFactory = nullptr;
+    IDCompositionDevice *dcompDevice = nullptr;
+    bool supportsAllowTearing = false;
+    bool deviceLost = false;
+    QRhiD3D11NativeHandles nativeHandlesStruct;
+    QRhiDriverInfo driverInfoStruct;
+
+    struct {
+        int vsHighestActiveVertexBufferBinding = -1;
+        bool vsHasIndexBufferBound = false;
+        int vsHighestActiveSrvBinding = -1;
+        int hsHighestActiveSrvBinding = -1;
+        int dsHighestActiveSrvBinding = -1;
+        int gsHighestActiveSrvBinding = -1;
+        int fsHighestActiveSrvBinding = -1;
+        int csHighestActiveSrvBinding = -1;
+        int csHighestActiveUavBinding = -1;
+        QD3D11SwapChain *currentSwapChain = nullptr;
+    } contextState;
+
+    struct OffscreenFrame {
+        OffscreenFrame(QRhiImplementation *rhi) : cbWrapper(rhi) { }
+        bool active = false;
+        QD3D11CommandBuffer cbWrapper;
+        QD3D11Timestamps timestamps;
+        int timestampIdx = 0;
+    } ofr;
+
+    struct TextureReadback {
+        QRhiReadbackDescription desc;
+        QRhiReadbackResult *result;
+        ID3D11Texture2D *stagingTex;
+        quint32 byteSize;
+        quint32 bpl;
+        QSize pixelSize;
+        QRhiTexture::Format format;
+    };
+    QVarLengthArray<TextureReadback, 2> activeTextureReadbacks;
+    struct BufferReadback {
+        QRhiReadbackResult *result;
+        quint32 byteSize;
+        ID3D11Buffer *stagingBuf;
+    };
+    QVarLengthArray<BufferReadback, 2> activeBufferReadbacks;
+
+    struct Shader {
+        Shader() = default;
+        Shader(IUnknown *s, const QByteArray &bytecode, const QShader::NativeResourceBindingMap &rbm)
+            : s(s), bytecode(bytecode), nativeResourceBindingMap(rbm) { }
+        IUnknown *s;
+        QByteArray bytecode;
+        QShader::NativeResourceBindingMap nativeResourceBindingMap;
+    };
+    QHash<QRhiShaderStage, Shader> m_shaderCache;
+
+    // This is what gets exposed as the "pipeline cache", not that that concept
+    // applies anyway. Here we are just storing the DX bytecode for a shader so
+    // we can skip the HLSL->DXBC compilation when the QShader has HLSL source
+    // code and the same shader source has already been compiled before.
+    // m_shaderCache seemingly does the same, but this here does not care about
+    // the ID3D11*Shader, this is just about the bytecode and about allowing
+    // the data to be serialized to persistent storage and then reloaded in
+    // future runs of the app, or when creating another QRhi, etc.
+    struct BytecodeCacheKey {
+        QByteArray sourceHash;
+        QByteArray target;
+        QByteArray entryPoint;
+        uint compileFlags;
+    };
+    QHash<BytecodeCacheKey, QByteArray> m_bytecodeCache;
 };
 
+Q_DECLARE_TYPEINFO(QRhiD3D11::TextureReadback, Q_RELOCATABLE_TYPE);
+Q_DECLARE_TYPEINFO(QRhiD3D11::BufferReadback, Q_RELOCATABLE_TYPE);
+
+inline bool operator==(const QRhiD3D11::BytecodeCacheKey &a, const QRhiD3D11::BytecodeCacheKey &b) noexcept
+{
+    return a.sourceHash == b.sourceHash
+            && a.target == b.target
+            && a.entryPoint == b.entryPoint
+            && a.compileFlags == b.compileFlags;
+}
+
+inline bool operator!=(const QRhiD3D11::BytecodeCacheKey &a, const QRhiD3D11::BytecodeCacheKey &b) noexcept
+{
+    return !(a == b);
+}
+
+inline size_t qHash(const QRhiD3D11::BytecodeCacheKey &k, size_t seed = 0) noexcept
+{
+    return qHash(k.sourceHash, seed) ^ qHash(k.target) ^ qHash(k.entryPoint) ^ k.compileFlags;
+}
+
 QT_END_NAMESPACE
 
 #endif
diff --git a/src/gui/rhi/qrhid3d11_p_p.h b/src/gui/rhi/qrhid3d11_p_p.h
deleted file mode 100644
index 232afb696f..0000000000
--- a/src/gui/rhi/qrhid3d11_p_p.h
+++ /dev/null
@@ -1,853 +0,0 @@
-// Copyright (C) 2019 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
-
-#ifndef QRHID3D11_P_H
-#define QRHID3D11_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists purely as an
-// implementation detail.  This header file may change from version to
-// version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qrhid3d11_p.h"
-#include "qrhi_p_p.h"
-#include "qshaderdescription_p.h"
-#include <QWindow>
-
-#include <d3d11_1.h>
-#include <dxgi1_6.h>
-#include <dcomp.h>
-
-QT_BEGIN_NAMESPACE
-
-class QRhiD3D11;
-
-struct QD3D11Buffer : public QRhiBuffer
-{
-    QD3D11Buffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
-    ~QD3D11Buffer();
-    void destroy() override;
-    bool create() override;
-    QRhiBuffer::NativeBuffer nativeBuffer() override;
-    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
-    void endFullDynamicBufferUpdateForCurrentFrame() override;
-
-    ID3D11UnorderedAccessView *unorderedAccessView(quint32 offset);
-
-    ID3D11Buffer *buffer = nullptr;
-    char *dynBuf = nullptr;
-    bool hasPendingDynamicUpdates = false;
-    QHash<quint32, ID3D11UnorderedAccessView *> uavs;
-    uint generation = 0;
-    friend class QRhiD3D11;
-};
-
-struct QD3D11RenderBuffer : public QRhiRenderBuffer
-{
-    QD3D11RenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
-                       int sampleCount, QRhiRenderBuffer::Flags flags,
-                       QRhiTexture::Format backingFormatHint);
-    ~QD3D11RenderBuffer();
-    void destroy() override;
-    bool create() override;
-    QRhiTexture::Format backingFormat() const override;
-
-    ID3D11Texture2D *tex = nullptr;
-    ID3D11DepthStencilView *dsv = nullptr;
-    ID3D11RenderTargetView *rtv = nullptr;
-    DXGI_FORMAT dxgiFormat;
-    DXGI_SAMPLE_DESC sampleDesc;
-    uint generation = 0;
-    friend class QRhiD3D11;
-};
-
-struct QD3D11Texture : public QRhiTexture
-{
-    QD3D11Texture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
-                  int arraySize, int sampleCount, Flags flags);
-    ~QD3D11Texture();
-    void destroy() override;
-    bool create() override;
-    bool createFrom(NativeTexture src) override;
-    NativeTexture nativeTexture() override;
-
-    bool prepareCreate(QSize *adjustedSize = nullptr);
-    bool finishCreate();
-    ID3D11UnorderedAccessView *unorderedAccessViewForLevel(int level);
-    ID3D11Resource *textureResource() const
-    {
-        if (tex)
-            return tex;
-        else if (tex1D)
-            return tex1D;
-        return tex3D;
-    }
-
-    ID3D11Texture2D *tex = nullptr;
-    ID3D11Texture3D *tex3D = nullptr;
-    ID3D11Texture1D *tex1D = nullptr;
-    bool owns = true;
-    ID3D11ShaderResourceView *srv = nullptr;
-    DXGI_FORMAT dxgiFormat;
-    uint mipLevelCount = 0;
-    DXGI_SAMPLE_DESC sampleDesc;
-    ID3D11UnorderedAccessView *perLevelViews[QRhi::MAX_MIP_LEVELS];
-    uint generation = 0;
-    friend class QRhiD3D11;
-};
-
-struct QD3D11Sampler : public QRhiSampler
-{
-    QD3D11Sampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
-                  AddressMode u, AddressMode v, AddressMode w);
-    ~QD3D11Sampler();
-    void destroy() override;
-    bool create() override;
-
-    ID3D11SamplerState *samplerState = nullptr;
-    uint generation = 0;
-    friend class QRhiD3D11;
-};
-
-struct QD3D11RenderPassDescriptor : public QRhiRenderPassDescriptor
-{
-    QD3D11RenderPassDescriptor(QRhiImplementation *rhi);
-    ~QD3D11RenderPassDescriptor();
-    void destroy() override;
-    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
-    QVector<quint32> serializedFormat() const override;
-};
-
-struct QD3D11RenderTargetData
-{
-    QD3D11RenderTargetData(QRhiImplementation *)
-    {
-        for (int i = 0; i < MAX_COLOR_ATTACHMENTS; ++i)
-            rtv[i] = nullptr;
-    }
-
-    QD3D11RenderPassDescriptor *rp = nullptr;
-    QSize pixelSize;
-    float dpr = 1;
-    int sampleCount = 1;
-    int colorAttCount = 0;
-    int dsAttCount = 0;
-
-    static const int MAX_COLOR_ATTACHMENTS = 8;
-    ID3D11RenderTargetView *rtv[MAX_COLOR_ATTACHMENTS];
-    ID3D11DepthStencilView *dsv = nullptr;
-
-    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
-};
-
-struct QD3D11SwapChainRenderTarget : public QRhiSwapChainRenderTarget
-{
-    QD3D11SwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
-    ~QD3D11SwapChainRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QD3D11RenderTargetData d;
-};
-
-struct QD3D11TextureRenderTarget : public QRhiTextureRenderTarget
-{
-    QD3D11TextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
-    ~QD3D11TextureRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool create() override;
-
-    QD3D11RenderTargetData d;
-    bool ownsRtv[QD3D11RenderTargetData::MAX_COLOR_ATTACHMENTS];
-    ID3D11RenderTargetView *rtv[QD3D11RenderTargetData::MAX_COLOR_ATTACHMENTS];
-    bool ownsDsv = false;
-    ID3D11DepthStencilView *dsv = nullptr;
-    friend class QRhiD3D11;
-};
-
-struct QD3D11ShaderResourceBindings : public QRhiShaderResourceBindings
-{
-    QD3D11ShaderResourceBindings(QRhiImplementation *rhi);
-    ~QD3D11ShaderResourceBindings();
-    void destroy() override;
-    bool create() override;
-    void updateResources(UpdateFlags flags) override;
-
-    bool hasDynamicOffset = false;
-    QVarLengthArray<QRhiShaderResourceBinding, 8> sortedBindings;
-    uint generation = 0;
-
-    // Keep track of the generation number of each referenced QRhi* to be able
-    // to detect that the batched bindings are out of date.
-    struct BoundUniformBufferData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundSampledTextureData {
-        int count;
-        struct {
-            quint64 texId;
-            uint texGeneration;
-            quint64 samplerId;
-            uint samplerGeneration;
-        } d[QRhiShaderResourceBinding::Data::MAX_TEX_SAMPLER_ARRAY_SIZE];
-    };
-    struct BoundStorageImageData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundStorageBufferData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundResourceData {
-        union {
-            BoundUniformBufferData ubuf;
-            BoundSampledTextureData stex;
-            BoundStorageImageData simage;
-            BoundStorageBufferData sbuf;
-        };
-    };
-    QVarLengthArray<BoundResourceData, 8> boundResourceData;
-
-    struct StageUniformBufferBatches {
-        bool present = false;
-        QRhiBatchedBindings<ID3D11Buffer *> ubufs;
-        QRhiBatchedBindings<UINT> ubuforigbindings;
-        QRhiBatchedBindings<UINT> ubufoffsets;
-        QRhiBatchedBindings<UINT> ubufsizes;
-        void finish() {
-            present = ubufs.finish();
-            ubuforigbindings.finish();
-            ubufoffsets.finish();
-            ubufsizes.finish();
-        }
-        void clear() {
-            ubufs.clear();
-            ubuforigbindings.clear();
-            ubufoffsets.clear();
-            ubufsizes.clear();
-        }
-    };
-
-    struct StageSamplerBatches {
-        bool present = false;
-        QRhiBatchedBindings<ID3D11SamplerState *> samplers;
-        QRhiBatchedBindings<ID3D11ShaderResourceView *> shaderresources;
-        void finish() {
-            present = samplers.finish();
-            shaderresources.finish();
-        }
-        void clear() {
-            samplers.clear();
-            shaderresources.clear();
-        }
-    };
-
-    struct StageUavBatches {
-        bool present = false;
-        QRhiBatchedBindings<ID3D11UnorderedAccessView *> uavs;
-        void finish() {
-            present = uavs.finish();
-        }
-        void clear() {
-            uavs.clear();
-        }
-    };
-
-    StageUniformBufferBatches vsUniformBufferBatches;
-    StageUniformBufferBatches hsUniformBufferBatches;
-    StageUniformBufferBatches dsUniformBufferBatches;
-    StageUniformBufferBatches gsUniformBufferBatches;
-    StageUniformBufferBatches fsUniformBufferBatches;
-    StageUniformBufferBatches csUniformBufferBatches;
-
-    StageSamplerBatches vsSamplerBatches;
-    StageSamplerBatches hsSamplerBatches;
-    StageSamplerBatches dsSamplerBatches;
-    StageSamplerBatches gsSamplerBatches;
-    StageSamplerBatches fsSamplerBatches;
-    StageSamplerBatches csSamplerBatches;
-
-    StageUavBatches csUavBatches;
-
-    friend class QRhiD3D11;
-};
-
-Q_DECLARE_TYPEINFO(QD3D11ShaderResourceBindings::BoundResourceData, Q_RELOCATABLE_TYPE);
-
-struct QD3D11GraphicsPipeline : public QRhiGraphicsPipeline
-{
-    QD3D11GraphicsPipeline(QRhiImplementation *rhi);
-    ~QD3D11GraphicsPipeline();
-    void destroy() override;
-    bool create() override;
-
-    ID3D11DepthStencilState *dsState = nullptr;
-    ID3D11BlendState *blendState = nullptr;
-    struct {
-        ID3D11VertexShader *shader = nullptr;
-        QShader::NativeResourceBindingMap nativeResourceBindingMap;
-    } vs;
-    struct {
-        ID3D11HullShader *shader = nullptr;
-        QShader::NativeResourceBindingMap nativeResourceBindingMap;
-    } hs;
-    struct {
-        ID3D11DomainShader *shader = nullptr;
-        QShader::NativeResourceBindingMap nativeResourceBindingMap;
-    } ds;
-    struct {
-        ID3D11GeometryShader *shader = nullptr;
-        QShader::NativeResourceBindingMap nativeResourceBindingMap;
-    } gs;
-    struct {
-        ID3D11PixelShader *shader = nullptr;
-        QShader::NativeResourceBindingMap nativeResourceBindingMap;
-    } fs;
-    ID3D11InputLayout *inputLayout = nullptr;
-    D3D11_PRIMITIVE_TOPOLOGY d3dTopology = D3D11_PRIMITIVE_TOPOLOGY_TRIANGLELIST;
-    ID3D11RasterizerState *rastState = nullptr;
-    uint generation = 0;
-    friend class QRhiD3D11;
-};
-
-struct QD3D11ComputePipeline : public QRhiComputePipeline
-{
-    QD3D11ComputePipeline(QRhiImplementation *rhi);
-    ~QD3D11ComputePipeline();
-    void destroy() override;
-    bool create() override;
-
-    struct {
-        ID3D11ComputeShader *shader = nullptr;
-        QShader::NativeResourceBindingMap nativeResourceBindingMap;
-    } cs;
-    uint generation = 0;
-    friend class QRhiD3D11;
-};
-
-struct QD3D11SwapChain;
-
-struct QD3D11CommandBuffer : public QRhiCommandBuffer
-{
-    QD3D11CommandBuffer(QRhiImplementation *rhi);
-    ~QD3D11CommandBuffer();
-    void destroy() override;
-
-    // these must be kept at a reasonably low value otherwise sizeof Command explodes
-    static const int MAX_DYNAMIC_OFFSET_COUNT = 8;
-    static const int MAX_VERTEX_BUFFER_BINDING_COUNT = 8;
-
-    struct Command {
-        enum Cmd {
-            ResetShaderResources,
-            SetRenderTarget,
-            Clear,
-            Viewport,
-            Scissor,
-            BindVertexBuffers,
-            BindIndexBuffer,
-            BindGraphicsPipeline,
-            BindShaderResources,
-            StencilRef,
-            BlendConstants,
-            Draw,
-            DrawIndexed,
-            UpdateSubRes,
-            CopySubRes,
-            ResolveSubRes,
-            GenMip,
-            DebugMarkBegin,
-            DebugMarkEnd,
-            DebugMarkMsg,
-            BindComputePipeline,
-            Dispatch
-        };
-        enum ClearFlag { Color = 1, Depth = 2, Stencil = 4 };
-        Cmd cmd;
-
-        // QRhi*/QD3D11* references should be kept at minimum (so no
-        // QRhiTexture/Buffer/etc. pointers).
-        union Args {
-            struct {
-                QRhiRenderTarget *rt;
-            } setRenderTarget;
-            struct {
-                QRhiRenderTarget *rt;
-                int mask;
-                float c[4];
-                float d;
-                quint32 s;
-            } clear;
-            struct {
-                float x, y, w, h;
-                float d0, d1;
-            } viewport;
-            struct {
-                int x, y, w, h;
-            } scissor;
-            struct {
-                int startSlot;
-                int slotCount;
-                ID3D11Buffer *buffers[MAX_VERTEX_BUFFER_BINDING_COUNT];
-                UINT offsets[MAX_VERTEX_BUFFER_BINDING_COUNT];
-                UINT strides[MAX_VERTEX_BUFFER_BINDING_COUNT];
-            } bindVertexBuffers;
-            struct {
-                ID3D11Buffer *buffer;
-                quint32 offset;
-                DXGI_FORMAT format;
-            } bindIndexBuffer;
-            struct {
-                QD3D11GraphicsPipeline *ps;
-            } bindGraphicsPipeline;
-            struct {
-                QD3D11ShaderResourceBindings *srb;
-                bool offsetOnlyChange;
-                int dynamicOffsetCount;
-                uint dynamicOffsetPairs[MAX_DYNAMIC_OFFSET_COUNT * 2]; // binding, offsetInConstants
-            } bindShaderResources;
-            struct {
-                QD3D11GraphicsPipeline *ps;
-                quint32 ref;
-            } stencilRef;
-            struct {
-                QD3D11GraphicsPipeline *ps;
-                float c[4];
-            } blendConstants;
-            struct {
-                QD3D11GraphicsPipeline *ps;
-                quint32 vertexCount;
-                quint32 instanceCount;
-                quint32 firstVertex;
-                quint32 firstInstance;
-            } draw;
-            struct {
-                QD3D11GraphicsPipeline *ps;
-                quint32 indexCount;
-                quint32 instanceCount;
-                quint32 firstIndex;
-                qint32 vertexOffset;
-                quint32 firstInstance;
-            } drawIndexed;
-            struct {
-                ID3D11Resource *dst;
-                UINT dstSubRes;
-                bool hasDstBox;
-                D3D11_BOX dstBox;
-                const void *src; // must come from retain*()
-                UINT srcRowPitch;
-            } updateSubRes;
-            struct {
-                ID3D11Resource *dst;
-                UINT dstSubRes;
-                UINT dstX;
-                UINT dstY;
-                UINT dstZ;
-                ID3D11Resource *src;
-                UINT srcSubRes;
-                bool hasSrcBox;
-                D3D11_BOX srcBox;
-            } copySubRes;
-            struct {
-                ID3D11Resource *dst;
-                UINT dstSubRes;
-                ID3D11Resource *src;
-                UINT srcSubRes;
-                DXGI_FORMAT format;
-            } resolveSubRes;
-            struct {
-                ID3D11ShaderResourceView *srv;
-            } genMip;
-            struct {
-                char s[64];
-            } debugMark;
-            struct {
-                QD3D11ComputePipeline *ps;
-            } bindComputePipeline;
-            struct {
-                UINT x;
-                UINT y;
-                UINT z;
-            } dispatch;
-        } args;
-    };
-
-    enum PassType {
-        NoPass,
-        RenderPass,
-        ComputePass
-    };
-
-    QRhiBackendCommandList<Command> commands;
-    PassType recordingPass;
-    double lastGpuTime = 0;
-    QRhiRenderTarget *currentTarget;
-    QRhiGraphicsPipeline *currentGraphicsPipeline;
-    QRhiComputePipeline *currentComputePipeline;
-    uint currentPipelineGeneration;
-    QRhiShaderResourceBindings *currentGraphicsSrb;
-    QRhiShaderResourceBindings *currentComputeSrb;
-    uint currentSrbGeneration;
-    ID3D11Buffer *currentIndexBuffer;
-    quint32 currentIndexOffset;
-    DXGI_FORMAT currentIndexFormat;
-    ID3D11Buffer *currentVertexBuffers[D3D11_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT];
-    quint32 currentVertexOffsets[D3D11_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT];
-
-    QVarLengthArray<QByteArray, 4> dataRetainPool;
-    QVarLengthArray<QRhiBufferData, 4> bufferDataRetainPool;
-    QVarLengthArray<QImage, 4> imageRetainPool;
-
-    // relies heavily on implicit sharing (no copies of the actual data will be made)
-    const uchar *retainData(const QByteArray &data) {
-        dataRetainPool.append(data);
-        return reinterpret_cast<const uchar *>(dataRetainPool.last().constData());
-    }
-    const uchar *retainBufferData(const QRhiBufferData &data) {
-        bufferDataRetainPool.append(data);
-        return reinterpret_cast<const uchar *>(bufferDataRetainPool.last().constData());
-    }
-    const uchar *retainImage(const QImage &image) {
-        imageRetainPool.append(image);
-        return imageRetainPool.last().constBits();
-    }
-    void resetCommands() {
-        commands.reset();
-        dataRetainPool.clear();
-        bufferDataRetainPool.clear();
-        imageRetainPool.clear();
-    }
-    void resetState() {
-        recordingPass = NoPass;
-        // do not zero lastGpuTime
-        currentTarget = nullptr;
-        resetCommands();
-        resetCachedState();
-    }
-    void resetCachedState() {
-        currentGraphicsPipeline = nullptr;
-        currentComputePipeline = nullptr;
-        currentPipelineGeneration = 0;
-        currentGraphicsSrb = nullptr;
-        currentComputeSrb = nullptr;
-        currentSrbGeneration = 0;
-        currentIndexBuffer = nullptr;
-        currentIndexOffset = 0;
-        currentIndexFormat = DXGI_FORMAT_R16_UINT;
-        memset(currentVertexBuffers, 0, sizeof(currentVertexBuffers));
-        memset(currentVertexOffsets, 0, sizeof(currentVertexOffsets));
-    }
-};
-
-static const int QD3D11_SWAPCHAIN_BUFFER_COUNT = 2;
-
-struct QD3D11Timestamps
-{
-    static const int MAX_TIMESTAMP_PAIRS = QD3D11_SWAPCHAIN_BUFFER_COUNT;
-    bool active[MAX_TIMESTAMP_PAIRS] = {};
-    ID3D11Query *disjointQuery[MAX_TIMESTAMP_PAIRS] = {};
-    ID3D11Query *query[MAX_TIMESTAMP_PAIRS * 2] = {};
-    int pairCount = 0;
-
-    bool prepare(int pairCount, QRhiD3D11 *rhiD);
-    void destroy();
-    bool tryQueryTimestamps(int idx, ID3D11DeviceContext *context, double *elapsedSec);
-};
-
-struct QD3D11SwapChain : public QRhiSwapChain
-{
-    QD3D11SwapChain(QRhiImplementation *rhi);
-    ~QD3D11SwapChain();
-    void destroy() override;
-
-    QRhiCommandBuffer *currentFrameCommandBuffer() override;
-    QRhiRenderTarget *currentFrameRenderTarget() override;
-
-    QSize surfacePixelSize() override;
-    bool isFormatSupported(Format f) override;
-    QRhiSwapChainHdrInfo hdrInfo() override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool createOrResize() override;
-
-    void releaseBuffers();
-    bool newColorBuffer(const QSize &size, DXGI_FORMAT format, DXGI_SAMPLE_DESC sampleDesc,
-                        ID3D11Texture2D **tex, ID3D11RenderTargetView **rtv) const;
-
-    QWindow *window = nullptr;
-    QSize pixelSize;
-    QD3D11SwapChainRenderTarget rt;
-    QD3D11CommandBuffer cb;
-    DXGI_FORMAT colorFormat;
-    DXGI_FORMAT srgbAdjustedColorFormat;
-    IDXGISwapChain *swapChain = nullptr;
-    UINT swapChainFlags = 0;
-    ID3D11Texture2D *backBufferTex;
-    ID3D11RenderTargetView *backBufferRtv;
-    static const int BUFFER_COUNT = QD3D11_SWAPCHAIN_BUFFER_COUNT;
-    ID3D11Texture2D *msaaTex[BUFFER_COUNT];
-    ID3D11RenderTargetView *msaaRtv[BUFFER_COUNT];
-    DXGI_SAMPLE_DESC sampleDesc;
-    int currentFrameSlot = 0;
-    int frameCount = 0;
-    QD3D11RenderBuffer *ds = nullptr;
-    UINT swapInterval = 1;
-    IDCompositionTarget *dcompTarget = nullptr;
-    IDCompositionVisual *dcompVisual = nullptr;
-    QD3D11Timestamps timestamps;
-};
-
-class QRhiD3D11 : public QRhiImplementation
-{
-public:
-    QRhiD3D11(QRhiD3D11InitParams *params, QRhiD3D11NativeHandles *importDevice = nullptr);
-
-    bool create(QRhi::Flags flags) override;
-    void destroy() override;
-
-    QRhiGraphicsPipeline *createGraphicsPipeline() override;
-    QRhiComputePipeline *createComputePipeline() override;
-    QRhiShaderResourceBindings *createShaderResourceBindings() override;
-    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
-                             QRhiBuffer::UsageFlags usage,
-                             quint32 size) override;
-    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
-                                         const QSize &pixelSize,
-                                         int sampleCount,
-                                         QRhiRenderBuffer::Flags flags,
-                                         QRhiTexture::Format backingFormatHint) override;
-    QRhiTexture *createTexture(QRhiTexture::Format format,
-                               const QSize &pixelSize,
-                               int depth,
-                               int arraySize,
-                               int sampleCount,
-                               QRhiTexture::Flags flags) override;
-    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
-                               QRhiSampler::Filter minFilter,
-                               QRhiSampler::Filter mipmapMode,
-                               QRhiSampler:: AddressMode u,
-                               QRhiSampler::AddressMode v,
-                               QRhiSampler::AddressMode w) override;
-
-    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
-                                                       QRhiTextureRenderTarget::Flags flags) override;
-
-    QRhiSwapChain *createSwapChain() override;
-    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult finish() override;
-
-    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void beginPass(QRhiCommandBuffer *cb,
-                   QRhiRenderTarget *rt,
-                   const QColor &colorClearValue,
-                   const QRhiDepthStencilClearValue &depthStencilClearValue,
-                   QRhiResourceUpdateBatch *resourceUpdates,
-                   QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void setGraphicsPipeline(QRhiCommandBuffer *cb,
-                             QRhiGraphicsPipeline *ps) override;
-
-    void setShaderResources(QRhiCommandBuffer *cb,
-                            QRhiShaderResourceBindings *srb,
-                            int dynamicOffsetCount,
-                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
-
-    void setVertexInput(QRhiCommandBuffer *cb,
-                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
-                        QRhiBuffer *indexBuf, quint32 indexOffset,
-                        QRhiCommandBuffer::IndexFormat indexFormat) override;
-
-    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
-    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
-    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
-    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
-
-    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
-              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
-
-    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
-                     quint32 instanceCount, quint32 firstIndex,
-                     qint32 vertexOffset, quint32 firstInstance) override;
-
-    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
-    void debugMarkEnd(QRhiCommandBuffer *cb) override;
-    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
-
-    void beginComputePass(QRhiCommandBuffer *cb,
-                          QRhiResourceUpdateBatch *resourceUpdates,
-                          QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
-    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
-
-    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
-    void beginExternal(QRhiCommandBuffer *cb) override;
-    void endExternal(QRhiCommandBuffer *cb) override;
-    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
-
-    QList<int> supportedSampleCounts() const override;
-    int ubufAlignment() const override;
-    bool isYUpInFramebuffer() const override;
-    bool isYUpInNDC() const override;
-    bool isClipDepthZeroToOne() const override;
-    QMatrix4x4 clipSpaceCorrMatrix() const override;
-    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
-    bool isFeatureSupported(QRhi::Feature feature) const override;
-    int resourceLimit(QRhi::ResourceLimit limit) const override;
-    const QRhiNativeHandles *nativeHandles() override;
-    QRhiDriverInfo driverInfo() const override;
-    QRhiStats statistics() override;
-    bool makeThreadLocalNativeContextCurrent() override;
-    void releaseCachedResources() override;
-    bool isDeviceLost() const override;
-
-    QByteArray pipelineCacheData() override;
-    void setPipelineCacheData(const QByteArray &data) override;
-
-    void enqueueSubresUpload(QD3D11Texture *texD, QD3D11CommandBuffer *cbD,
-                             int layer, int level, const QRhiTextureSubresourceUploadDescription &subresDesc);
-    void enqueueResourceUpdates(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates);
-    void updateShaderResourceBindings(QD3D11ShaderResourceBindings *srbD,
-                                      const QShader::NativeResourceBindingMap *nativeResourceBindingMaps[]);
-    void executeBufferHostWrites(QD3D11Buffer *bufD);
-    void bindShaderResources(QD3D11ShaderResourceBindings *srbD,
-                             const uint *dynOfsPairs, int dynOfsPairCount,
-                             bool offsetOnlyChange);
-    void resetShaderResources();
-    void executeCommandBuffer(QD3D11CommandBuffer *cbD, QD3D11SwapChain *timestampSwapChain = nullptr);
-    DXGI_SAMPLE_DESC effectiveSampleCount(int sampleCount) const;
-    void finishActiveReadbacks();
-    void reportLiveObjects(ID3D11Device *device);
-    void clearShaderCache();
-    QByteArray compileHlslShaderSource(const QShader &shader, QShader::Variant shaderVariant, uint flags,
-                                       QString *error, QShaderKey *usedShaderKey);
-    bool ensureDirectCompositionDevice();
-
-    QRhi::Flags rhiFlags;
-    bool debugLayer = false;
-    bool importedDeviceAndContext = false;
-    ID3D11Device *dev = nullptr;
-    ID3D11DeviceContext1 *context = nullptr;
-    D3D_FEATURE_LEVEL featureLevel = D3D_FEATURE_LEVEL(0);
-    LUID adapterLuid = {};
-    ID3DUserDefinedAnnotation *annotations = nullptr;
-    IDXGIAdapter1 *activeAdapter = nullptr;
-    IDXGIFactory1 *dxgiFactory = nullptr;
-    IDCompositionDevice *dcompDevice = nullptr;
-    bool supportsAllowTearing = false;
-    bool deviceLost = false;
-    QRhiD3D11NativeHandles nativeHandlesStruct;
-    QRhiDriverInfo driverInfoStruct;
-
-    struct {
-        int vsHighestActiveVertexBufferBinding = -1;
-        bool vsHasIndexBufferBound = false;
-        int vsHighestActiveSrvBinding = -1;
-        int hsHighestActiveSrvBinding = -1;
-        int dsHighestActiveSrvBinding = -1;
-        int gsHighestActiveSrvBinding = -1;
-        int fsHighestActiveSrvBinding = -1;
-        int csHighestActiveSrvBinding = -1;
-        int csHighestActiveUavBinding = -1;
-        QD3D11SwapChain *currentSwapChain = nullptr;
-    } contextState;
-
-    struct OffscreenFrame {
-        OffscreenFrame(QRhiImplementation *rhi) : cbWrapper(rhi) { }
-        bool active = false;
-        QD3D11CommandBuffer cbWrapper;
-        QD3D11Timestamps timestamps;
-        int timestampIdx = 0;
-    } ofr;
-
-    struct TextureReadback {
-        QRhiReadbackDescription desc;
-        QRhiReadbackResult *result;
-        ID3D11Texture2D *stagingTex;
-        quint32 byteSize;
-        quint32 bpl;
-        QSize pixelSize;
-        QRhiTexture::Format format;
-    };
-    QVarLengthArray<TextureReadback, 2> activeTextureReadbacks;
-    struct BufferReadback {
-        QRhiReadbackResult *result;
-        quint32 byteSize;
-        ID3D11Buffer *stagingBuf;
-    };
-    QVarLengthArray<BufferReadback, 2> activeBufferReadbacks;
-
-    struct Shader {
-        Shader() = default;
-        Shader(IUnknown *s, const QByteArray &bytecode, const QShader::NativeResourceBindingMap &rbm)
-            : s(s), bytecode(bytecode), nativeResourceBindingMap(rbm) { }
-        IUnknown *s;
-        QByteArray bytecode;
-        QShader::NativeResourceBindingMap nativeResourceBindingMap;
-    };
-    QHash<QRhiShaderStage, Shader> m_shaderCache;
-
-    // This is what gets exposed as the "pipeline cache", not that that concept
-    // applies anyway. Here we are just storing the DX bytecode for a shader so
-    // we can skip the HLSL->DXBC compilation when the QShader has HLSL source
-    // code and the same shader source has already been compiled before.
-    // m_shaderCache seemingly does the same, but this here does not care about
-    // the ID3D11*Shader, this is just about the bytecode and about allowing
-    // the data to be serialized to persistent storage and then reloaded in
-    // future runs of the app, or when creating another QRhi, etc.
-    struct BytecodeCacheKey {
-        QByteArray sourceHash;
-        QByteArray target;
-        QByteArray entryPoint;
-        uint compileFlags;
-    };
-    QHash<BytecodeCacheKey, QByteArray> m_bytecodeCache;
-};
-
-Q_DECLARE_TYPEINFO(QRhiD3D11::TextureReadback, Q_RELOCATABLE_TYPE);
-Q_DECLARE_TYPEINFO(QRhiD3D11::BufferReadback, Q_RELOCATABLE_TYPE);
-
-inline bool operator==(const QRhiD3D11::BytecodeCacheKey &a, const QRhiD3D11::BytecodeCacheKey &b) noexcept
-{
-    return a.sourceHash == b.sourceHash
-            && a.target == b.target
-            && a.entryPoint == b.entryPoint
-            && a.compileFlags == b.compileFlags;
-}
-
-inline bool operator!=(const QRhiD3D11::BytecodeCacheKey &a, const QRhiD3D11::BytecodeCacheKey &b) noexcept
-{
-    return !(a == b);
-}
-
-inline size_t qHash(const QRhiD3D11::BytecodeCacheKey &k, size_t seed = 0) noexcept
-{
-    return qHash(k.sourceHash, seed) ^ qHash(k.target) ^ qHash(k.entryPoint) ^ k.compileFlags;
-}
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/rhi/qrhid3d12.cpp b/src/gui/rhi/qrhid3d12.cpp
index 2b129b5742..c6d3f59058 100644
--- a/src/gui/rhi/qrhid3d12.cpp
+++ b/src/gui/rhi/qrhid3d12.cpp
@@ -1,8 +1,8 @@
-// Copyright (C) 2022 The Qt Company Ltd.
+// 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
 
-#include "qrhid3d12_p_p.h"
-#include "qshader_p.h"
+#include "qrhid3d12_p.h"
+#include "qshader.h"
 #include <QWindow>
 #include <qmath.h>
 #include <private/qsystemlibrary_p.h>
@@ -30,6 +30,9 @@ QT_BEGIN_NAMESPACE
     \inmodule QtGui
     \brief Direct3D 12 specific initialization parameters.
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     A D3D12-based QRhi needs no special parameters for initialization. If
     desired, enableDebugLayer can be set to \c true to enable the Direct3D
     debug layer. This can be useful during development, but should be avoided
@@ -63,16 +66,46 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
+    \variable QRhiD3D12InitParams::enableDebugLayer
+
+    When set to true, the debug layer is enabled, if installed and available.
+    The default value is false.
+*/
+
+/*!
     \class QRhiD3D12NativeHandles
     \inmodule QtGui
     \brief Holds the D3D12 device used by the QRhi.
 
     \note The class uses \c{void *} as the type since including the COM-based
-    \c{d3d12.h} headers is not acceptable here. The actual type is
-    \c{ID3D12Device *}.
+    \c{d3d12.h} headers is not acceptable here. The actual types are
+    \c{ID3D12Device *} and \c{ID3D12CommandQueue *}.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
+    \variable QRhiD3D12NativeHandles::dev
+*/
+
+/*!
+    \variable QRhiD3D12NativeHandles::minimumFeatureLevel
+*/
+
+/*!
+    \variable QRhiD3D12NativeHandles::adapterLuidLow
+*/
+
+/*!
+    \variable QRhiD3D12NativeHandles::adapterLuidHigh
+*/
+
+/*!
+    \variable QRhiD3D12NativeHandles::commandQueue
+*/
+
+/*!
     \class QRhiD3D12CommandBufferNativeHandles
     \inmodule QtGui
     \brief Holds the ID3D12GraphicsCommandList object that is backing a QRhiCommandBuffer.
@@ -82,8 +115,15 @@ QT_BEGIN_NAMESPACE
     \l{QRhi::beginFrame()}{beginFrame()} - \l{QRhi::endFrame()}{endFrame()} or
     \l{QRhi::beginOffscreenFrame()}{beginOffscreenFrame()} -
     \l{QRhi::endOffscreenFrame()}{endOffscreenFrame()} pair.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
+/*!
+    \variable QRhiD3D12CommandBufferNativeHandles::commandList
+*/
+
 // https://learn.microsoft.com/en-us/windows/win32/direct3d12/hardware-feature-levels
 static const D3D_FEATURE_LEVEL MIN_FEATURE_LEVEL = D3D_FEATURE_LEVEL_11_0;
 
diff --git a/src/gui/rhi/qrhid3d12_p.h b/src/gui/rhi/qrhid3d12_p.h
index e49ef57eaf..d40046355b 100644
--- a/src/gui/rhi/qrhid3d12_p.h
+++ b/src/gui/rhi/qrhid3d12_p.h
@@ -1,8 +1,8 @@
-// Copyright (C) 2022 The Qt Company Ltd.
+// 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
 
-#ifndef QRHID3D12_H
-#define QRHID3D12_H
+#ifndef QRHID3D12_P_H
+#define QRHID3D12_P_H
 
 //
 //  W A R N I N G
@@ -15,32 +15,1178 @@
 // We mean it.
 //
 
-#include <private/qrhi_p.h>
+#include "qrhi_p.h"
+#include "qshaderdescription.h"
+#include <QWindow>
+#include <QBitArray>
 
-// no d3d includes here, to prevent precompiled header mess due to COM
+#include <optional>
+#include <array>
+
+#include <d3d12.h>
+#include <d3d12sdklayers.h>
+#include <dxgi1_6.h>
+#include <dcomp.h>
+
+#include "D3D12MemAlloc.h"
 
 QT_BEGIN_NAMESPACE
 
-struct Q_GUI_EXPORT QRhiD3D12InitParams : public QRhiInitParams
+static const int QD3D12_FRAMES_IN_FLIGHT = 2;
+
+class QRhiD3D12;
+
+struct QD3D12Descriptor
+{
+    D3D12_CPU_DESCRIPTOR_HANDLE cpuHandle = {};
+    D3D12_GPU_DESCRIPTOR_HANDLE gpuHandle = {};
+
+    bool isValid() const { return cpuHandle.ptr != 0; }
+};
+
+struct QD3D12ReleaseQueue;
+
+struct QD3D12DescriptorHeap
+{
+    bool isValid() const { return heap && capacity; }
+    bool create(ID3D12Device *device,
+                quint32 descriptorCount,
+                D3D12_DESCRIPTOR_HEAP_TYPE heapType,
+                D3D12_DESCRIPTOR_HEAP_FLAGS heapFlags);
+    void createWithExisting(const QD3D12DescriptorHeap &other,
+                            quint32 offsetInDescriptors,
+                            quint32 descriptorCount);
+    void destroy();
+    void destroyWithDeferredRelease(QD3D12ReleaseQueue *releaseQueue);
+
+    QD3D12Descriptor get(quint32 count);
+    QD3D12Descriptor at(quint32 index) const;
+    quint32 remainingCapacity() const { return capacity - head; }
+
+    QD3D12Descriptor incremented(const QD3D12Descriptor &descriptor, quint32 offsetInDescriptors) const
+    {
+        D3D12_CPU_DESCRIPTOR_HANDLE cpuHandle = descriptor.cpuHandle;
+        cpuHandle.ptr += offsetInDescriptors * descriptorByteSize;
+        D3D12_GPU_DESCRIPTOR_HANDLE gpuHandle = descriptor.gpuHandle;
+        if (gpuHandle.ptr)
+            gpuHandle.ptr += offsetInDescriptors * descriptorByteSize;
+        return { cpuHandle, gpuHandle };
+    }
+
+    ID3D12DescriptorHeap *heap = nullptr;
+    quint32 capacity = 0;
+    QD3D12Descriptor heapStart;
+    quint32 head = 0;
+    quint32 descriptorByteSize = 0;
+    D3D12_DESCRIPTOR_HEAP_TYPE heapType;
+    D3D12_DESCRIPTOR_HEAP_FLAGS heapFlags;
+};
+
+struct QD3D12CpuDescriptorPool
+{
+    bool isValid() const { return !heaps.isEmpty(); }
+    bool create(ID3D12Device *device, D3D12_DESCRIPTOR_HEAP_TYPE heapType, const char *debugName = "");
+    void destroy();
+
+    QD3D12Descriptor allocate(quint32 count);
+    void release(const QD3D12Descriptor &descriptor, quint32 count);
+
+    static const int DESCRIPTORS_PER_HEAP = 256;
+
+    struct HeapWithMap {
+        QD3D12DescriptorHeap heap;
+        QBitArray map;
+        static HeapWithMap init(const QD3D12DescriptorHeap &heap, quint32 descriptorCount) {
+            HeapWithMap result;
+            result.heap = heap;
+            result.map.resize(descriptorCount);
+            return result;
+        }
+    };
+
+    ID3D12Device *device;
+    quint32 descriptorByteSize;
+    QVector<HeapWithMap> heaps;
+    const char *debugName;
+};
+
+struct QD3D12StagingArea
+{
+    static const quint32 ALIGNMENT = D3D12_TEXTURE_DATA_PLACEMENT_ALIGNMENT; // 512 so good enough both for cb and texdata
+
+    struct Allocation {
+        quint8 *p = nullptr;
+        D3D12_GPU_VIRTUAL_ADDRESS gpuAddr = 0;
+        ID3D12Resource *buffer = nullptr;
+        quint32 bufferOffset = 0;
+        bool isValid() const { return p != nullptr; }
+    };
+
+    bool isValid() const { return allocation && mem.isValid(); }
+    bool create(QRhiD3D12 *rhi, quint32 capacity, D3D12_HEAP_TYPE heapType);
+    void destroy();
+    void destroyWithDeferredRelease(QD3D12ReleaseQueue *releaseQueue);
+
+    Allocation get(quint32 byteSize);
+
+    quint32 remainingCapacity() const
+    {
+        return capacity - head;
+    }
+
+    static quint32 allocSizeForArray(quint32 size, int count = 1)
+    {
+        return count * ((size + ALIGNMENT - 1) & ~(ALIGNMENT - 1));
+    }
+
+    Allocation mem;
+    ID3D12Resource *resource =  nullptr;
+    D3D12MA::Allocation *allocation = nullptr;
+    quint32 head;
+    quint32 capacity;
+};
+
+struct QD3D12ObjectHandle
+{
+    quint32 index = 0;
+    quint32 generation = 0;
+
+    // the default, null handle is guaranteed to give ObjectPool::isValid() == false
+    bool isNull() const { return index == 0 && generation == 0; }
+};
+
+inline bool operator==(const QD3D12ObjectHandle &a, const QD3D12ObjectHandle &b) noexcept
+{
+    return a.index == b.index && a.generation == b.generation;
+}
+
+inline bool operator!=(const QD3D12ObjectHandle &a, const QD3D12ObjectHandle &b) noexcept
+{
+    return !(a == b);
+}
+
+template<typename T>
+struct QD3D12ObjectPool
+{
+    void create(const char *debugName = "")
+    {
+        this->debugName = debugName;
+        Q_ASSERT(data.isEmpty());
+        data.append(Data()); // index 0 is always invalid
+    }
+
+    void destroy() {
+        int leakCount = 0; // will nicely destroy everything here, but warn about it if enabled
+        for (Data &d : data) {
+            if (d.object.has_value()) {
+                leakCount += 1;
+                d.object->releaseResources();
+            }
+        }
+        data.clear();
+#ifndef QT_NO_DEBUG
+        // debug builds: just do it always
+        static bool leakCheck = true;
+#else
+        // release builds: opt-in
+        static bool leakCheck = qEnvironmentVariableIntValue("QT_RHI_LEAK_CHECK");
+#endif
+        if (leakCheck) {
+            if (leakCount > 0) {
+                qWarning("QD3D12ObjectPool::destroy(): Pool %p '%s' had %d unreleased objects",
+                         this, debugName, leakCount);
+            }
+        }
+    }
+
+    bool isValid(const QD3D12ObjectHandle &handle) const
+    {
+        return handle.index > 0
+                && handle.index < quint32(data.count())
+                && handle.generation > 0
+                && handle.generation == data[handle.index].generation
+                && data[handle.index].object.has_value();
+    }
+
+    T lookup(const QD3D12ObjectHandle &handle) const
+    {
+        return isValid(handle) ? *data[handle.index].object : T();
+    }
+
+    const T *lookupRef(const QD3D12ObjectHandle &handle) const
+    {
+        return isValid(handle) ? &*data[handle.index].object : nullptr;
+    }
+
+    T *lookupRef(const QD3D12ObjectHandle &handle)
+    {
+        return isValid(handle) ? &*data[handle.index].object : nullptr;
+    }
+
+    QD3D12ObjectHandle add(const T &object)
+    {
+        Q_ASSERT(!data.isEmpty());
+        const quint32 count = quint32(data.count());
+        quint32 index = 1; // index 0 is always invalid
+        for (; index < count; ++index) {
+            if (!data[index].object.has_value())
+                break;
+        }
+        if (index < count) {
+            data[index].object = object;
+            quint32 &generation = data[index].generation;
+            generation += 1u;
+            return { index, generation };
+        } else {
+            data.append({ object, 1 });
+            return { count, 1 };
+        }
+    }
+
+    void remove(const QD3D12ObjectHandle &handle)
+    {
+        if (T *object = lookupRef(handle)) {
+            object->releaseResources();
+            data[handle.index].object.reset();
+        }
+    }
+
+    const char *debugName;
+    struct Data {
+        std::optional<T> object;
+        quint32 generation = 0;
+    };
+    QVector<Data> data;
+};
+
+struct QD3D12Resource
+{
+    ID3D12Resource *resource;
+    D3D12_RESOURCE_STATES state;
+    D3D12_RESOURCE_DESC desc;
+    D3D12MA::Allocation *allocation;
+    void *cpuMapPtr;
+    enum { UavUsageRead = 0x01, UavUsageWrite = 0x02 };
+    int uavUsage;
+    bool owns;
+
+    // note that this assumes the allocation (if there is one) and the resource
+    // are separately releaseable, see D3D12MemAlloc docs
+    static QD3D12ObjectHandle addToPool(QD3D12ObjectPool<QD3D12Resource> *pool,
+                                        ID3D12Resource *resource,
+                                        D3D12_RESOURCE_STATES state,
+                                        D3D12MA::Allocation *allocation = nullptr,
+                                        void *cpuMapPtr = nullptr)
+    {
+        Q_ASSERT(resource);
+        return pool->add({ resource, state, resource->GetDesc(), allocation, cpuMapPtr, 0, true });
+    }
+
+    // for QRhiTexture::createFrom() where the ID3D12Resource is not owned by us
+    static QD3D12ObjectHandle addNonOwningToPool(QD3D12ObjectPool<QD3D12Resource> *pool,
+                                                 ID3D12Resource *resource,
+                                                 D3D12_RESOURCE_STATES state)
+    {
+        Q_ASSERT(resource);
+        return pool->add({ resource, state, resource->GetDesc(), nullptr, nullptr, 0, false });
+    }
+
+    void releaseResources()
+    {
+        if (owns) {
+            // order matters: resource first, then the allocation
+            resource->Release();
+            if (allocation)
+                allocation->Release();
+        }
+    }
+};
+
+struct QD3D12Pipeline
+{
+    enum Type {
+        Graphics,
+        Compute
+    };
+    Type type;
+    ID3D12PipelineState *pso;
+
+    static QD3D12ObjectHandle addToPool(QD3D12ObjectPool<QD3D12Pipeline> *pool,
+                                        Type type,
+                                        ID3D12PipelineState *pso)
+    {
+        return pool->add({ type, pso });
+    }
+
+    void releaseResources()
+    {
+        pso->Release();
+    }
+};
+
+struct QD3D12RootSignature
+{
+    ID3D12RootSignature *rootSig;
+
+    static QD3D12ObjectHandle addToPool(QD3D12ObjectPool<QD3D12RootSignature> *pool,
+                                        ID3D12RootSignature *rootSig)
+    {
+        return pool->add({ rootSig });
+    }
+
+    void releaseResources()
+    {
+        rootSig->Release();
+    }
+};
+
+struct QD3D12ReleaseQueue
+{
+    void create(QD3D12ObjectPool<QD3D12Resource> *resourcePool,
+                QD3D12ObjectPool<QD3D12Pipeline> *pipelinePool,
+                QD3D12ObjectPool<QD3D12RootSignature> *rootSignaturePool)
+    {
+        this->resourcePool = resourcePool;
+        this->pipelinePool = pipelinePool;
+        this->rootSignaturePool = rootSignaturePool;
+    }
+
+    void deferredReleaseResource(const QD3D12ObjectHandle &handle);
+    void deferredReleaseResourceWithViews(const QD3D12ObjectHandle &handle,
+                                          QD3D12CpuDescriptorPool *pool,
+                                          const QD3D12Descriptor &viewsStart,
+                                          int viewCount);
+    void deferredReleasePipeline(const QD3D12ObjectHandle &handle);
+    void deferredReleaseRootSignature(const QD3D12ObjectHandle &handle);
+    void deferredReleaseCallback(std::function<void(void*)> callback, void *userData);
+    void deferredReleaseResourceAndAllocation(ID3D12Resource *resource,
+                                              D3D12MA::Allocation *allocation);
+    void deferredReleaseDescriptorHeap(ID3D12DescriptorHeap *heap);
+    void deferredReleaseViews(QD3D12CpuDescriptorPool *pool,
+                              const QD3D12Descriptor &viewsStart,
+                              int viewCount);
+
+    void activatePendingDeferredReleaseRequests(int frameSlot);
+    void executeDeferredReleases(int frameSlot, bool forced = false);
+    void releaseAll();
+
+    struct DeferredReleaseEntry {
+        enum Type {
+            Resource,
+            Pipeline,
+            RootSignature,
+            Callback,
+            ResourceAndAllocation,
+            DescriptorHeap,
+            Views
+        };
+        Type type = Resource;
+        std::optional<int> frameSlotToBeReleasedIn;
+        QD3D12ObjectHandle handle;
+        QD3D12CpuDescriptorPool *poolForViews = nullptr;
+        QD3D12Descriptor viewsStart;
+        int viewCount = 0;
+        std::function<void(void*)> callback = nullptr;
+        void *callbackUserData = nullptr;
+        QPair<ID3D12Resource *, D3D12MA::Allocation *> resourceAndAllocation = {};
+        ID3D12DescriptorHeap *descriptorHeap = nullptr;
+    };
+    QVector<DeferredReleaseEntry> queue;
+    QD3D12ObjectPool<QD3D12Resource> *resourcePool = nullptr;
+    QD3D12ObjectPool<QD3D12Pipeline> *pipelinePool = nullptr;
+    QD3D12ObjectPool<QD3D12RootSignature> *rootSignaturePool = nullptr;
+};
+
+struct QD3D12CommandBuffer;
+
+struct QD3D12ResourceBarrierGenerator
+{
+    static const int PREALLOC = 16;
+
+    void create(QD3D12ObjectPool<QD3D12Resource> *resourcePool)
+    {
+        this->resourcePool = resourcePool;
+    }
+
+    void addTransitionBarrier(const QD3D12ObjectHandle &resourceHandle, D3D12_RESOURCE_STATES stateAfter);
+    void enqueueBufferedTransitionBarriers(QD3D12CommandBuffer *cbD);
+    void enqueueSubresourceTransitionBarrier(QD3D12CommandBuffer *cbD,
+                                             const QD3D12ObjectHandle &resourceHandle,
+                                             UINT subresource,
+                                             D3D12_RESOURCE_STATES stateBefore,
+                                             D3D12_RESOURCE_STATES stateAfter);
+    void enqueueUavBarrier(QD3D12CommandBuffer *cbD, const QD3D12ObjectHandle &resourceHandle);
+
+    struct TransitionResourceBarrier {
+        QD3D12ObjectHandle resourceHandle;
+        D3D12_RESOURCE_STATES stateBefore;
+        D3D12_RESOURCE_STATES stateAfter;
+    };
+    QVarLengthArray<TransitionResourceBarrier, PREALLOC> transitionResourceBarriers;
+    QD3D12ObjectPool<QD3D12Resource> *resourcePool = nullptr;
+};
+
+struct QD3D12ShaderBytecodeCache
+{
+    struct Shader {
+        Shader() = default;
+        Shader(const QByteArray &bytecode, const QShader::NativeResourceBindingMap &rbm)
+            : bytecode(bytecode), nativeResourceBindingMap(rbm)
+        { }
+        QByteArray bytecode;
+        QShader::NativeResourceBindingMap nativeResourceBindingMap;
+    };
+
+    QHash<QRhiShaderStage, Shader> data;
+
+    void insertWithCapacityLimit(const QRhiShaderStage &key, const Shader &s);
+};
+
+struct QD3D12ShaderVisibleDescriptorHeap
+{
+    bool create(ID3D12Device *device, D3D12_DESCRIPTOR_HEAP_TYPE type, quint32 perFrameDescriptorCount);
+    void destroy();
+    void destroyWithDeferredRelease(QD3D12ReleaseQueue *releaseQueue);
+
+    QD3D12DescriptorHeap heap;
+    QD3D12DescriptorHeap perFrameHeapSlice[QD3D12_FRAMES_IN_FLIGHT];
+};
+
+// wrap foreign struct so we can legally supply equality operators and qHash:
+struct Q_D3D12_SAMPLER_DESC
+{
+    D3D12_SAMPLER_DESC desc;
+
+    friend bool operator==(const Q_D3D12_SAMPLER_DESC &lhs, const Q_D3D12_SAMPLER_DESC &rhs) noexcept
+    {
+        return lhs.desc.Filter == rhs.desc.Filter
+                && lhs.desc.AddressU == rhs.desc.AddressU
+                && lhs.desc.AddressV == rhs.desc.AddressV
+                && lhs.desc.AddressW == rhs.desc.AddressW
+                && lhs.desc.MipLODBias == rhs.desc.MipLODBias
+                && lhs.desc.MaxAnisotropy == rhs.desc.MaxAnisotropy
+                && lhs.desc.ComparisonFunc == rhs.desc.ComparisonFunc
+                // BorderColor is never used, skip it
+                && lhs.desc.MinLOD == rhs.desc.MinLOD
+                && lhs.desc.MaxLOD == rhs.desc.MaxLOD;
+    }
+
+    friend bool operator!=(const Q_D3D12_SAMPLER_DESC &lhs, const Q_D3D12_SAMPLER_DESC &rhs) noexcept
+    {
+        return !(lhs == rhs);
+    }
+
+    friend size_t qHash(const Q_D3D12_SAMPLER_DESC &key, size_t seed = 0) noexcept
+    {
+        QtPrivate::QHashCombine hash;
+        seed = hash(seed, key.desc.Filter);
+        seed = hash(seed, key.desc.AddressU);
+        seed = hash(seed, key.desc.AddressV);
+        seed = hash(seed, key.desc.AddressW);
+        seed = hash(seed, key.desc.MipLODBias);
+        seed = hash(seed, key.desc.MaxAnisotropy);
+        seed = hash(seed, key.desc.ComparisonFunc);
+        // BorderColor is never used, skip it
+        seed = hash(seed, key.desc.MinLOD);
+        seed = hash(seed, key.desc.MaxLOD);
+        return seed;
+    }
+};
+
+struct QD3D12SamplerManager
+{
+    const quint32 MAX_SAMPLERS = 512;
+
+    bool create(ID3D12Device *device);
+    void destroy();
+
+    QD3D12Descriptor getShaderVisibleDescriptor(const D3D12_SAMPLER_DESC &desc);
+
+    ID3D12Device *device = nullptr;
+    QD3D12ShaderVisibleDescriptorHeap shaderVisibleSamplerHeap;
+    QHash<Q_D3D12_SAMPLER_DESC, QD3D12Descriptor> gpuMap;
+};
+
+enum QD3D12Stage { VS = 0, HS, DS, GS, PS, CS };
+
+static inline QD3D12Stage qd3d12_stage(QRhiShaderStage::Type type)
 {
-    bool enableDebugLayer = false;
+    switch (type) {
+    case QRhiShaderStage::Vertex:
+        return VS;
+    case QRhiShaderStage::TessellationControl:
+        return HS;
+    case QRhiShaderStage::TessellationEvaluation:
+        return DS;
+    case QRhiShaderStage::Geometry:
+        return GS;
+    case QRhiShaderStage::Fragment:
+        return PS;
+    case QRhiShaderStage::Compute:
+        return CS;
+    }
+    Q_UNREACHABLE_RETURN(VS);
+}
+
+static inline D3D12_SHADER_VISIBILITY qd3d12_stageToVisibility(QD3D12Stage s)
+{
+    switch (s) {
+    case VS:
+        return D3D12_SHADER_VISIBILITY_VERTEX;
+    case HS:
+        return D3D12_SHADER_VISIBILITY_HULL;
+    case DS:
+        return D3D12_SHADER_VISIBILITY_DOMAIN;
+    case GS:
+        return D3D12_SHADER_VISIBILITY_GEOMETRY;
+    case PS:
+        return D3D12_SHADER_VISIBILITY_PIXEL;
+    case CS:
+        return D3D12_SHADER_VISIBILITY_ALL;
+    }
+    Q_UNREACHABLE_RETURN(D3D12_SHADER_VISIBILITY_ALL);
+}
+
+static inline QRhiShaderResourceBinding::StageFlag qd3d12_stageToSrb(QD3D12Stage s)
+{
+    switch (s) {
+    case VS:
+        return QRhiShaderResourceBinding::VertexStage;
+    case HS:
+        return QRhiShaderResourceBinding::TessellationControlStage;
+    case DS:
+        return QRhiShaderResourceBinding::TessellationEvaluationStage;
+    case GS:
+        return QRhiShaderResourceBinding::GeometryStage;
+    case PS:
+        return QRhiShaderResourceBinding::FragmentStage;
+    case CS:
+        return QRhiShaderResourceBinding::ComputeStage;
+    }
+    Q_UNREACHABLE_RETURN(QRhiShaderResourceBinding::VertexStage);
+}
+
+struct QD3D12ShaderStageData
+{
+    bool valid = false; // to allow simple arrays where unused stages are indicated by !valid
+    QD3D12Stage stage = VS;
+    QShader::NativeResourceBindingMap nativeResourceBindingMap;
+};
+
+struct QD3D12ShaderResourceBindings;
+
+struct QD3D12ShaderResourceVisitor
+{
+    enum StorageOp { Load = 0, Store, LoadStore };
+
+    QD3D12ShaderResourceVisitor(const QD3D12ShaderResourceBindings *srb,
+                                const QD3D12ShaderStageData *stageData,
+                                int stageCount)
+        : srb(srb),
+          stageData(stageData),
+          stageCount(stageCount)
+    {
+    }
+
+    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::Data::UniformBufferData &, int, int)> uniformBuffer = nullptr;
+    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::TextureAndSampler &, int)> texture = nullptr;
+    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::TextureAndSampler &, int)> sampler = nullptr;
+    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::Data::StorageImageData &, StorageOp, int)> storageImage = nullptr;
+    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::Data::StorageBufferData &, StorageOp, int)> storageBuffer = nullptr;
+
+    void visit();
+
+    const QD3D12ShaderResourceBindings *srb;
+    const QD3D12ShaderStageData *stageData;
+    int stageCount;
 };
 
-struct Q_GUI_EXPORT QRhiD3D12NativeHandles : public QRhiNativeHandles
+struct QD3D12Readback
 {
-    // to import a device
-    void *dev = nullptr;
-    int minimumFeatureLevel = 0;
-    // to just specify the adapter to use, set these and leave dev set to null
-    quint32 adapterLuidLow = 0;
-    qint32 adapterLuidHigh = 0;
-    // in addition, can specify the command queue to use
-    void *commandQueue = nullptr;
+    // common
+    int frameSlot = -1;
+    QRhiReadbackResult *result = nullptr;
+    QD3D12StagingArea staging;
+    quint32 byteSize = 0;
+    // textures
+    quint32 bytesPerLine = 0;
+    QSize pixelSize;
+    QRhiTexture::Format format = QRhiTexture::UnknownFormat;
+    quint32 stagingRowPitch = 0;
 };
 
-struct Q_GUI_EXPORT QRhiD3D12CommandBufferNativeHandles : public QRhiNativeHandles
+struct QD3D12MipmapGenerator
 {
-    void *commandList = nullptr; // ID3D12GraphicsCommandList
+    bool create(QRhiD3D12 *rhiD);
+    void destroy();
+    void generate(QD3D12CommandBuffer *cbD, const QD3D12ObjectHandle &textureHandle);
+
+    QRhiD3D12 *rhiD;
+    QD3D12ObjectHandle rootSigHandle;
+    QD3D12ObjectHandle pipelineHandle;
+};
+
+struct QD3D12MemoryAllocator
+{
+    bool create(ID3D12Device *device, IDXGIAdapter1 *adapter);
+    void destroy();
+
+    HRESULT createResource(D3D12_HEAP_TYPE heapType,
+                           const D3D12_RESOURCE_DESC *resourceDesc,
+                           D3D12_RESOURCE_STATES initialState,
+                           const D3D12_CLEAR_VALUE *optimizedClearValue,
+                           D3D12MA::Allocation **maybeAllocation,
+                           REFIID riidResource,
+                           void **ppvResource);
+
+    void getBudget(D3D12MA::Budget *localBudget, D3D12MA::Budget *nonLocalBudget);
+
+    bool isUsingD3D12MA() const { return allocator != nullptr; }
+
+    ID3D12Device *device = nullptr;
+    D3D12MA::Allocator *allocator = nullptr;
+};
+
+struct QD3D12Buffer : public QRhiBuffer
+{
+    QD3D12Buffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
+    ~QD3D12Buffer();
+
+    void destroy() override;
+    bool create() override;
+    QRhiBuffer::NativeBuffer nativeBuffer() override;
+    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
+    void endFullDynamicBufferUpdateForCurrentFrame() override;
+
+    void executeHostWritesForFrameSlot(int frameSlot);
+
+    QD3D12ObjectHandle handles[QD3D12_FRAMES_IN_FLIGHT] = {};
+    struct HostWrite {
+        quint32 offset;
+        QRhiBufferData data;
+    };
+    QVarLengthArray<HostWrite, 16> pendingHostWrites[QD3D12_FRAMES_IN_FLIGHT];
+    friend class QRhiD3D12;
+};
+
+struct QD3D12RenderBuffer : public QRhiRenderBuffer
+{
+    QD3D12RenderBuffer(QRhiImplementation *rhi,
+                       Type type,
+                       const QSize &pixelSize,
+                       int sampleCount,
+                       Flags flags,
+                       QRhiTexture::Format backingFormatHint);
+    ~QD3D12RenderBuffer();
+    void destroy() override;
+    bool create() override;
+    QRhiTexture::Format backingFormat() const override;
+
+    static const DXGI_FORMAT DS_FORMAT = DXGI_FORMAT_D24_UNORM_S8_UINT;
+
+    QD3D12ObjectHandle handle;
+    QD3D12Descriptor rtv;
+    QD3D12Descriptor dsv;
+    DXGI_FORMAT dxgiFormat;
+    DXGI_SAMPLE_DESC sampleDesc;
+    uint generation = 0;
+    friend class QRhiD3D12;
+};
+
+struct QD3D12Texture : public QRhiTexture
+{
+    QD3D12Texture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
+                  int arraySize, int sampleCount, Flags flags);
+    ~QD3D12Texture();
+    void destroy() override;
+    bool create() override;
+    bool createFrom(NativeTexture src) override;
+    NativeTexture nativeTexture() override;
+    void setNativeLayout(int layout) override;
+
+    bool prepareCreate(QSize *adjustedSize = nullptr);
+    bool finishCreate();
+
+    QD3D12ObjectHandle handle;
+    QD3D12Descriptor srv;
+    DXGI_FORMAT dxgiFormat;
+    uint mipLevelCount;
+    DXGI_SAMPLE_DESC sampleDesc;
+    uint generation = 0;
+    friend class QRhiD3D12;
+};
+
+struct QD3D12Sampler : public QRhiSampler
+{
+    QD3D12Sampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
+                  AddressMode u, AddressMode v, AddressMode w);
+    ~QD3D12Sampler();
+    void destroy() override;
+    bool create() override;
+
+    QD3D12Descriptor lookupOrCreateShaderVisibleDescriptor();
+
+    D3D12_SAMPLER_DESC desc = {};
+    QD3D12Descriptor shaderVisibleDescriptor;
+};
+
+struct QD3D12RenderPassDescriptor : public QRhiRenderPassDescriptor
+{
+    QD3D12RenderPassDescriptor(QRhiImplementation *rhi);
+    ~QD3D12RenderPassDescriptor();
+    void destroy() override;
+    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
+    QVector<quint32> serializedFormat() const override;
+
+    void updateSerializedFormat();
+
+    static const int MAX_COLOR_ATTACHMENTS = 8;
+    int colorAttachmentCount = 0;
+    bool hasDepthStencil = false;
+    int colorFormat[MAX_COLOR_ATTACHMENTS];
+    int dsFormat;
+    QVector<quint32> serializedFormatData;
+};
+
+struct QD3D12RenderTargetData
+{
+    QD3D12RenderTargetData(QRhiImplementation *) { }
+
+    QD3D12RenderPassDescriptor *rp = nullptr;
+    QSize pixelSize;
+    float dpr = 1;
+    int sampleCount = 1;
+    int colorAttCount = 0;
+    int dsAttCount = 0;
+    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
+    static const int MAX_COLOR_ATTACHMENTS = QD3D12RenderPassDescriptor::MAX_COLOR_ATTACHMENTS;
+    D3D12_CPU_DESCRIPTOR_HANDLE rtv[MAX_COLOR_ATTACHMENTS];
+    D3D12_CPU_DESCRIPTOR_HANDLE dsv;
+};
+
+struct QD3D12SwapChainRenderTarget : public QRhiSwapChainRenderTarget
+{
+    QD3D12SwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
+    ~QD3D12SwapChainRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QD3D12RenderTargetData d;
+};
+
+struct QD3D12TextureRenderTarget : public QRhiTextureRenderTarget
+{
+    QD3D12TextureRenderTarget(QRhiImplementation *rhi,
+                              const QRhiTextureRenderTargetDescription &desc,
+                              Flags flags);
+    ~QD3D12TextureRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool create() override;
+
+    QD3D12RenderTargetData d;
+    bool ownsRtv[QD3D12RenderTargetData::MAX_COLOR_ATTACHMENTS];
+    QD3D12Descriptor rtv[QD3D12RenderTargetData::MAX_COLOR_ATTACHMENTS];
+    bool ownsDsv = false;
+    QD3D12Descriptor dsv;
+    friend class QRhiD3D12;
+};
+
+struct QD3D12ShaderResourceBindings : public QRhiShaderResourceBindings
+{
+    QD3D12ShaderResourceBindings(QRhiImplementation *rhi);
+    ~QD3D12ShaderResourceBindings();
+    void destroy() override;
+    bool create() override;
+    void updateResources(UpdateFlags flags) override;
+
+    QD3D12ObjectHandle createRootSignature(const QD3D12ShaderStageData *stageData, int stageCount);
+
+    struct VisitorData {
+        QVarLengthArray<D3D12_ROOT_PARAMETER1, 2> cbParams[6];
+
+        D3D12_ROOT_PARAMETER1 srvTables[6] = {};
+        QVarLengthArray<D3D12_DESCRIPTOR_RANGE1, 4> srvRanges[6];
+        quint32 currentSrvRangeOffset[6] = {};
+
+        QVarLengthArray<D3D12_ROOT_PARAMETER1, 4> samplerTables[6];
+        std::array<D3D12_DESCRIPTOR_RANGE1, 16> samplerRanges[6] = {};
+        int samplerRangeHeads[6] = {};
+
+        D3D12_ROOT_PARAMETER1 uavTables[6] = {};
+        QVarLengthArray<D3D12_DESCRIPTOR_RANGE1, 4> uavRanges[6];
+        quint32 currentUavRangeOffset[6] = {};
+    } visitorData;
+
+
+    void visitUniformBuffer(QD3D12Stage s,
+                            const QRhiShaderResourceBinding::Data::UniformBufferData &d,
+                            int shaderRegister,
+                            int binding);
+    void visitTexture(QD3D12Stage s,
+                      const QRhiShaderResourceBinding::TextureAndSampler &d,
+                      int shaderRegister);
+    void visitSampler(QD3D12Stage s,
+                      const QRhiShaderResourceBinding::TextureAndSampler &d,
+                      int shaderRegister);
+    void visitStorageBuffer(QD3D12Stage s,
+                            const QRhiShaderResourceBinding::Data::StorageBufferData &d,
+                            QD3D12ShaderResourceVisitor::StorageOp op,
+                            int shaderRegister);
+    void visitStorageImage(QD3D12Stage s,
+                           const QRhiShaderResourceBinding::Data::StorageImageData &d,
+                           QD3D12ShaderResourceVisitor::StorageOp op,
+                           int shaderRegister);
+
+    QVarLengthArray<QRhiShaderResourceBinding, 8> sortedBindings;
+    bool hasDynamicOffset = false;
+    uint generation = 0;
+};
+
+struct QD3D12GraphicsPipeline : public QRhiGraphicsPipeline
+{
+    QD3D12GraphicsPipeline(QRhiImplementation *rhi);
+    ~QD3D12GraphicsPipeline();
+    void destroy() override;
+    bool create() override;
+
+    QD3D12ObjectHandle handle;
+    QD3D12ObjectHandle rootSigHandle;
+    std::array<QD3D12ShaderStageData, 5> stageData;
+    D3D12_PRIMITIVE_TOPOLOGY topology;
+    uint generation = 0;
+    friend class QRhiD3D12;
+};
+
+struct QD3D12ComputePipeline : public QRhiComputePipeline
+{
+    QD3D12ComputePipeline(QRhiImplementation *rhi);
+    ~QD3D12ComputePipeline();
+    void destroy() override;
+    bool create() override;
+
+    QD3D12ObjectHandle handle;
+    QD3D12ObjectHandle rootSigHandle;
+    QD3D12ShaderStageData stageData;
+    uint generation = 0;
+    friend class QRhiD3D12;
+};
+
+struct QD3D12CommandBuffer : public QRhiCommandBuffer
+{
+    QD3D12CommandBuffer(QRhiImplementation *rhi);
+    ~QD3D12CommandBuffer();
+    void destroy() override;
+
+    const QRhiNativeHandles *nativeHandles();
+
+    ID3D12GraphicsCommandList *cmdList = nullptr; // not owned
+    QRhiD3D12CommandBufferNativeHandles nativeHandlesStruct;
+
+    enum PassType {
+        NoPass,
+        RenderPass,
+        ComputePass
+    };
+
+    void resetState()
+    {
+        recordingPass = NoPass;
+        currentTarget = nullptr;
+
+        resetPerPassState();
+    }
+
+    void resetPerPassState()
+    {
+        currentGraphicsPipeline = nullptr;
+        currentComputePipeline = nullptr;
+        currentPipelineGeneration = 0;
+        currentGraphicsSrb = nullptr;
+        currentComputeSrb = nullptr;
+        currentSrbGeneration = 0;
+        currentIndexBuffer = {};
+        currentIndexOffset = 0;
+        currentIndexFormat = DXGI_FORMAT_R16_UINT;
+        currentVertexBuffers = {};
+        currentVertexOffsets = {};
+    }
+
+    PassType recordingPass;
+    QRhiRenderTarget *currentTarget;
+
+    QD3D12GraphicsPipeline *currentGraphicsPipeline;
+    QD3D12ComputePipeline *currentComputePipeline;
+    uint currentPipelineGeneration;
+    QRhiShaderResourceBindings *currentGraphicsSrb;
+    QRhiShaderResourceBindings *currentComputeSrb;
+    uint currentSrbGeneration;
+    QD3D12ObjectHandle currentIndexBuffer;
+    quint32 currentIndexOffset;
+    DXGI_FORMAT currentIndexFormat;
+    std::array<QD3D12ObjectHandle, D3D12_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT> currentVertexBuffers;
+    std::array<quint32, D3D12_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT> currentVertexOffsets;
+};
+
+struct QD3D12SwapChain : public QRhiSwapChain
+{
+    QD3D12SwapChain(QRhiImplementation *rhi);
+    ~QD3D12SwapChain();
+    void destroy() override;
+
+    QRhiCommandBuffer *currentFrameCommandBuffer() override;
+    QRhiRenderTarget *currentFrameRenderTarget() override;
+
+    QSize surfacePixelSize() override;
+    bool isFormatSupported(Format f) override;
+    QRhiSwapChainHdrInfo hdrInfo() override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool createOrResize() override;
+
+    void releaseBuffers();
+    void waitCommandCompletionForFrameSlot(int frameSlot);
+    void addCommandCompletionSignalForCurrentFrameSlot();
+    void chooseFormats();
+
+    QWindow *window = nullptr;
+    IDXGISwapChain1 *sourceSwapChain1 = nullptr;
+    IDXGISwapChain3 *swapChain = nullptr;
+    QSize pixelSize;
+    UINT swapInterval = 1;
+    UINT swapChainFlags = 0;
+    DXGI_FORMAT colorFormat;
+    DXGI_FORMAT srgbAdjustedColorFormat;
+    DXGI_COLOR_SPACE_TYPE hdrColorSpace;
+    IDCompositionTarget *dcompTarget = nullptr;
+    IDCompositionVisual *dcompVisual = nullptr;
+    static const UINT BUFFER_COUNT = 3;
+    QD3D12ObjectHandle colorBuffers[BUFFER_COUNT];
+    QD3D12Descriptor rtvs[BUFFER_COUNT];
+    DXGI_SAMPLE_DESC sampleDesc;
+    QD3D12ObjectHandle msaaBuffers[BUFFER_COUNT];
+    QD3D12Descriptor msaaRtvs[BUFFER_COUNT];
+    QD3D12RenderBuffer *ds = nullptr;
+    UINT currentBackBufferIndex = 0;
+    QD3D12SwapChainRenderTarget rtWrapper;
+    QD3D12CommandBuffer cbWrapper;
+
+    struct FrameResources {
+        ID3D12Fence *fence = nullptr;
+        HANDLE fenceEvent = nullptr;
+        UINT64 fenceCounter = 0;
+        ID3D12GraphicsCommandList *cmdList = nullptr;
+    } frameRes[QD3D12_FRAMES_IN_FLIGHT];
+
+    int currentFrameSlot = 0; // index in frameRes
+};
+
+class QRhiD3D12 : public QRhiImplementation
+{
+public:
+    // 16MB * QD3D12_FRAMES_IN_FLIGHT; buffer and texture upload staging data that
+    // gets no space from this will get their own temporary staging areas.
+    static const quint32 SMALL_STAGING_AREA_BYTES_PER_FRAME = 16 * 1024 * 1024;
+
+    static const quint32 SHADER_VISIBLE_CBV_SRV_UAV_HEAP_PER_FRAME_START_SIZE = 16384;
+
+    QRhiD3D12(QRhiD3D12InitParams *params, QRhiD3D12NativeHandles *importDevice = nullptr);
+
+    bool create(QRhi::Flags flags) override;
+    void destroy() override;
+
+    QRhiGraphicsPipeline *createGraphicsPipeline() override;
+    QRhiComputePipeline *createComputePipeline() override;
+    QRhiShaderResourceBindings *createShaderResourceBindings() override;
+    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
+                             QRhiBuffer::UsageFlags usage,
+                             quint32 size) override;
+    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
+                                         const QSize &pixelSize,
+                                         int sampleCount,
+                                         QRhiRenderBuffer::Flags flags,
+                                         QRhiTexture::Format backingFormatHint) override;
+    QRhiTexture *createTexture(QRhiTexture::Format format,
+                               const QSize &pixelSize,
+                               int depth,
+                               int arraySize,
+                               int sampleCount,
+                               QRhiTexture::Flags flags) override;
+    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
+                               QRhiSampler::Filter minFilter,
+                               QRhiSampler::Filter mipmapMode,
+                               QRhiSampler:: AddressMode u,
+                               QRhiSampler::AddressMode v,
+                               QRhiSampler::AddressMode w) override;
+
+    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
+                                                       QRhiTextureRenderTarget::Flags flags) override;
+
+    QRhiSwapChain *createSwapChain() override;
+    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult finish() override;
+
+    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void beginPass(QRhiCommandBuffer *cb,
+                   QRhiRenderTarget *rt,
+                   const QColor &colorClearValue,
+                   const QRhiDepthStencilClearValue &depthStencilClearValue,
+                   QRhiResourceUpdateBatch *resourceUpdates,
+                   QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void setGraphicsPipeline(QRhiCommandBuffer *cb,
+                             QRhiGraphicsPipeline *ps) override;
+
+    void setShaderResources(QRhiCommandBuffer *cb,
+                            QRhiShaderResourceBindings *srb,
+                            int dynamicOffsetCount,
+                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
+
+    void setVertexInput(QRhiCommandBuffer *cb,
+                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
+                        QRhiBuffer *indexBuf, quint32 indexOffset,
+                        QRhiCommandBuffer::IndexFormat indexFormat) override;
+
+    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
+    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
+    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
+    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
+
+    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
+              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
+
+    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
+                     quint32 instanceCount, quint32 firstIndex,
+                     qint32 vertexOffset, quint32 firstInstance) override;
+
+    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
+    void debugMarkEnd(QRhiCommandBuffer *cb) override;
+    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
+
+    void beginComputePass(QRhiCommandBuffer *cb,
+                          QRhiResourceUpdateBatch *resourceUpdates,
+                          QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
+    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
+
+    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
+    void beginExternal(QRhiCommandBuffer *cb) override;
+    void endExternal(QRhiCommandBuffer *cb) override;
+    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
+
+    QList<int> supportedSampleCounts() const override;
+    int ubufAlignment() const override;
+    bool isYUpInFramebuffer() const override;
+    bool isYUpInNDC() const override;
+    bool isClipDepthZeroToOne() const override;
+    QMatrix4x4 clipSpaceCorrMatrix() const override;
+    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
+    bool isFeatureSupported(QRhi::Feature feature) const override;
+    int resourceLimit(QRhi::ResourceLimit limit) const override;
+    const QRhiNativeHandles *nativeHandles() override;
+    QRhiDriverInfo driverInfo() const override;
+    QRhiStats statistics() override;
+    bool makeThreadLocalNativeContextCurrent() override;
+    void releaseCachedResources() override;
+    bool isDeviceLost() const override;
+
+    QByteArray pipelineCacheData() override;
+    void setPipelineCacheData(const QByteArray &data) override;
+
+    void waitGpu();
+    DXGI_SAMPLE_DESC effectiveSampleCount(int sampleCount, DXGI_FORMAT format) const;
+    bool ensureDirectCompositionDevice();
+    bool startCommandListForCurrentFrameSlot(ID3D12GraphicsCommandList **cmdList);
+    void enqueueResourceUpdates(QD3D12CommandBuffer *cbD, QRhiResourceUpdateBatch *resourceUpdates);
+    void finishActiveReadbacks(bool forced = false);
+    bool ensureShaderVisibleDescriptorHeapCapacity(QD3D12ShaderVisibleDescriptorHeap *h,
+                                                   D3D12_DESCRIPTOR_HEAP_TYPE type,
+                                                   int frameSlot,
+                                                   quint32 neededDescriptorCount,
+                                                   bool *gotNew);
+    void bindShaderVisibleHeaps(QD3D12CommandBuffer *cbD);
+
+    bool debugLayer = false;
+    ID3D12Device *dev = nullptr;
+    D3D_FEATURE_LEVEL minimumFeatureLevel = D3D_FEATURE_LEVEL(0);
+    LUID adapterLuid = {};
+    bool importedDevice = false;
+    bool importedCommandQueue = false;
+    QRhi::Flags rhiFlags;
+    IDXGIFactory2 *dxgiFactory = nullptr;
+    bool supportsAllowTearing = false;
+    IDXGIAdapter1 *activeAdapter = nullptr;
+    QRhiDriverInfo driverInfoStruct;
+    QRhiD3D12NativeHandles nativeHandlesStruct;
+    bool deviceLost = false;
+    ID3D12CommandQueue *cmdQueue = nullptr;
+    ID3D12Fence *fullFence = nullptr;
+    HANDLE fullFenceEvent = nullptr;
+    UINT64 fullFenceCounter = 0;
+    ID3D12CommandAllocator *cmdAllocators[QD3D12_FRAMES_IN_FLIGHT] = {};
+    QD3D12MemoryAllocator vma;
+    QD3D12CpuDescriptorPool rtvPool;
+    QD3D12CpuDescriptorPool dsvPool;
+    QD3D12CpuDescriptorPool cbvSrvUavPool;
+    QD3D12ObjectPool<QD3D12Resource> resourcePool;
+    QD3D12ObjectPool<QD3D12Pipeline> pipelinePool;
+    QD3D12ObjectPool<QD3D12RootSignature> rootSignaturePool;
+    QD3D12ReleaseQueue releaseQueue;
+    QD3D12ResourceBarrierGenerator barrierGen;
+    QD3D12SamplerManager samplerMgr;
+    QD3D12MipmapGenerator mipmapGen;
+    QD3D12StagingArea smallStagingAreas[QD3D12_FRAMES_IN_FLIGHT];
+    QD3D12ShaderVisibleDescriptorHeap shaderVisibleCbvSrvUavHeap;
+    IDCompositionDevice *dcompDevice = nullptr;
+    QD3D12SwapChain *currentSwapChain = nullptr;
+    QSet<QD3D12SwapChain *> swapchains;
+    QD3D12ShaderBytecodeCache shaderBytecodeCache;
+    QVarLengthArray<QD3D12Readback, 4> activeReadbacks;
+    bool offscreenActive = false;
+    QD3D12CommandBuffer *offscreenCb[QD3D12_FRAMES_IN_FLIGHT] = {};
+
+    struct VisitorData {
+        QVarLengthArray<QPair<QD3D12ObjectHandle, quint32>, 4> cbufs[6];
+        QVarLengthArray<QD3D12Descriptor, 8> srvs[6];
+        QVarLengthArray<QD3D12Descriptor, 8> samplers[6];
+        QVarLengthArray<QPair<QD3D12ObjectHandle, D3D12_UNORDERED_ACCESS_VIEW_DESC>, 4> uavs[6];
+    } visitorData;
+
+    void visitUniformBuffer(QD3D12Stage s,
+                            const QRhiShaderResourceBinding::Data::UniformBufferData &d,
+                            int shaderRegister,
+                            int binding,
+                            int dynamicOffsetCount,
+                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets);
+    void visitTexture(QD3D12Stage s,
+                      const QRhiShaderResourceBinding::TextureAndSampler &d,
+                      int shaderRegister);
+    void visitSampler(QD3D12Stage s,
+                      const QRhiShaderResourceBinding::TextureAndSampler &d,
+                      int shaderRegister);
+    void visitStorageBuffer(QD3D12Stage s,
+                            const QRhiShaderResourceBinding::Data::StorageBufferData &d,
+                            QD3D12ShaderResourceVisitor::StorageOp op,
+                            int shaderRegister);
+    void visitStorageImage(QD3D12Stage s,
+                           const QRhiShaderResourceBinding::Data::StorageImageData &d,
+                           QD3D12ShaderResourceVisitor::StorageOp op,
+                           int shaderRegister);
 };
 
 QT_END_NAMESPACE
diff --git a/src/gui/rhi/qrhid3d12_p_p.h b/src/gui/rhi/qrhid3d12_p_p.h
deleted file mode 100644
index d8ad22ce29..0000000000
--- a/src/gui/rhi/qrhid3d12_p_p.h
+++ /dev/null
@@ -1,1195 +0,0 @@
-// Copyright (C) 2022 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
-
-#ifndef QRHID3D12_P_H
-#define QRHID3D12_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists purely as an
-// implementation detail.  This header file may change from version to
-// version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qrhid3d12_p.h"
-#include "qrhi_p_p.h"
-#include "qshaderdescription_p.h"
-#include <QWindow>
-#include <QBitArray>
-
-#include <optional>
-#include <array>
-
-#include <d3d12.h>
-#include <d3d12sdklayers.h>
-#include <dxgi1_6.h>
-#include <dcomp.h>
-
-#include "D3D12MemAlloc.h"
-
-QT_BEGIN_NAMESPACE
-
-static const int QD3D12_FRAMES_IN_FLIGHT = 2;
-
-class QRhiD3D12;
-
-struct QD3D12Descriptor
-{
-    D3D12_CPU_DESCRIPTOR_HANDLE cpuHandle = {};
-    D3D12_GPU_DESCRIPTOR_HANDLE gpuHandle = {};
-
-    bool isValid() const { return cpuHandle.ptr != 0; }
-};
-
-struct QD3D12ReleaseQueue;
-
-struct QD3D12DescriptorHeap
-{
-    bool isValid() const { return heap && capacity; }
-    bool create(ID3D12Device *device,
-                quint32 descriptorCount,
-                D3D12_DESCRIPTOR_HEAP_TYPE heapType,
-                D3D12_DESCRIPTOR_HEAP_FLAGS heapFlags);
-    void createWithExisting(const QD3D12DescriptorHeap &other,
-                            quint32 offsetInDescriptors,
-                            quint32 descriptorCount);
-    void destroy();
-    void destroyWithDeferredRelease(QD3D12ReleaseQueue *releaseQueue);
-
-    QD3D12Descriptor get(quint32 count);
-    QD3D12Descriptor at(quint32 index) const;
-    quint32 remainingCapacity() const { return capacity - head; }
-
-    QD3D12Descriptor incremented(const QD3D12Descriptor &descriptor, quint32 offsetInDescriptors) const
-    {
-        D3D12_CPU_DESCRIPTOR_HANDLE cpuHandle = descriptor.cpuHandle;
-        cpuHandle.ptr += offsetInDescriptors * descriptorByteSize;
-        D3D12_GPU_DESCRIPTOR_HANDLE gpuHandle = descriptor.gpuHandle;
-        if (gpuHandle.ptr)
-            gpuHandle.ptr += offsetInDescriptors * descriptorByteSize;
-        return { cpuHandle, gpuHandle };
-    }
-
-    ID3D12DescriptorHeap *heap = nullptr;
-    quint32 capacity = 0;
-    QD3D12Descriptor heapStart;
-    quint32 head = 0;
-    quint32 descriptorByteSize = 0;
-    D3D12_DESCRIPTOR_HEAP_TYPE heapType;
-    D3D12_DESCRIPTOR_HEAP_FLAGS heapFlags;
-};
-
-struct QD3D12CpuDescriptorPool
-{
-    bool isValid() const { return !heaps.isEmpty(); }
-    bool create(ID3D12Device *device, D3D12_DESCRIPTOR_HEAP_TYPE heapType, const char *debugName = "");
-    void destroy();
-
-    QD3D12Descriptor allocate(quint32 count);
-    void release(const QD3D12Descriptor &descriptor, quint32 count);
-
-    static const int DESCRIPTORS_PER_HEAP = 256;
-
-    struct HeapWithMap {
-        QD3D12DescriptorHeap heap;
-        QBitArray map;
-        static HeapWithMap init(const QD3D12DescriptorHeap &heap, quint32 descriptorCount) {
-            HeapWithMap result;
-            result.heap = heap;
-            result.map.resize(descriptorCount);
-            return result;
-        }
-    };
-
-    ID3D12Device *device;
-    quint32 descriptorByteSize;
-    QVector<HeapWithMap> heaps;
-    const char *debugName;
-};
-
-struct QD3D12StagingArea
-{
-    static const quint32 ALIGNMENT = D3D12_TEXTURE_DATA_PLACEMENT_ALIGNMENT; // 512 so good enough both for cb and texdata
-
-    struct Allocation {
-        quint8 *p = nullptr;
-        D3D12_GPU_VIRTUAL_ADDRESS gpuAddr = 0;
-        ID3D12Resource *buffer = nullptr;
-        quint32 bufferOffset = 0;
-        bool isValid() const { return p != nullptr; }
-    };
-
-    bool isValid() const { return allocation && mem.isValid(); }
-    bool create(QRhiD3D12 *rhi, quint32 capacity, D3D12_HEAP_TYPE heapType);
-    void destroy();
-    void destroyWithDeferredRelease(QD3D12ReleaseQueue *releaseQueue);
-
-    Allocation get(quint32 byteSize);
-
-    quint32 remainingCapacity() const
-    {
-        return capacity - head;
-    }
-
-    static quint32 allocSizeForArray(quint32 size, int count = 1)
-    {
-        return count * ((size + ALIGNMENT - 1) & ~(ALIGNMENT - 1));
-    }
-
-    Allocation mem;
-    ID3D12Resource *resource =  nullptr;
-    D3D12MA::Allocation *allocation = nullptr;
-    quint32 head;
-    quint32 capacity;
-};
-
-struct QD3D12ObjectHandle
-{
-    quint32 index = 0;
-    quint32 generation = 0;
-
-    // the default, null handle is guaranteed to give ObjectPool::isValid() == false
-    bool isNull() const { return index == 0 && generation == 0; }
-};
-
-inline bool operator==(const QD3D12ObjectHandle &a, const QD3D12ObjectHandle &b) noexcept
-{
-    return a.index == b.index && a.generation == b.generation;
-}
-
-inline bool operator!=(const QD3D12ObjectHandle &a, const QD3D12ObjectHandle &b) noexcept
-{
-    return !(a == b);
-}
-
-template<typename T>
-struct QD3D12ObjectPool
-{
-    void create(const char *debugName = "")
-    {
-        this->debugName = debugName;
-        Q_ASSERT(data.isEmpty());
-        data.append(Data()); // index 0 is always invalid
-    }
-
-    void destroy() {
-        int leakCount = 0; // will nicely destroy everything here, but warn about it if enabled
-        for (Data &d : data) {
-            if (d.object.has_value()) {
-                leakCount += 1;
-                d.object->releaseResources();
-            }
-        }
-        data.clear();
-#ifndef QT_NO_DEBUG
-        // debug builds: just do it always
-        static bool leakCheck = true;
-#else
-        // release builds: opt-in
-        static bool leakCheck = qEnvironmentVariableIntValue("QT_RHI_LEAK_CHECK");
-#endif
-        if (leakCheck) {
-            if (leakCount > 0) {
-                qWarning("QD3D12ObjectPool::destroy(): Pool %p '%s' had %d unreleased objects",
-                         this, debugName, leakCount);
-            }
-        }
-    }
-
-    bool isValid(const QD3D12ObjectHandle &handle) const
-    {
-        return handle.index > 0
-                && handle.index < quint32(data.count())
-                && handle.generation > 0
-                && handle.generation == data[handle.index].generation
-                && data[handle.index].object.has_value();
-    }
-
-    T lookup(const QD3D12ObjectHandle &handle) const
-    {
-        return isValid(handle) ? *data[handle.index].object : T();
-    }
-
-    const T *lookupRef(const QD3D12ObjectHandle &handle) const
-    {
-        return isValid(handle) ? &*data[handle.index].object : nullptr;
-    }
-
-    T *lookupRef(const QD3D12ObjectHandle &handle)
-    {
-        return isValid(handle) ? &*data[handle.index].object : nullptr;
-    }
-
-    QD3D12ObjectHandle add(const T &object)
-    {
-        Q_ASSERT(!data.isEmpty());
-        const quint32 count = quint32(data.count());
-        quint32 index = 1; // index 0 is always invalid
-        for (; index < count; ++index) {
-            if (!data[index].object.has_value())
-                break;
-        }
-        if (index < count) {
-            data[index].object = object;
-            quint32 &generation = data[index].generation;
-            generation += 1u;
-            return { index, generation };
-        } else {
-            data.append({ object, 1 });
-            return { count, 1 };
-        }
-    }
-
-    void remove(const QD3D12ObjectHandle &handle)
-    {
-        if (T *object = lookupRef(handle)) {
-            object->releaseResources();
-            data[handle.index].object.reset();
-        }
-    }
-
-    const char *debugName;
-    struct Data {
-        std::optional<T> object;
-        quint32 generation = 0;
-    };
-    QVector<Data> data;
-};
-
-struct QD3D12Resource
-{
-    ID3D12Resource *resource;
-    D3D12_RESOURCE_STATES state;
-    D3D12_RESOURCE_DESC desc;
-    D3D12MA::Allocation *allocation;
-    void *cpuMapPtr;
-    enum { UavUsageRead = 0x01, UavUsageWrite = 0x02 };
-    int uavUsage;
-    bool owns;
-
-    // note that this assumes the allocation (if there is one) and the resource
-    // are separately releaseable, see D3D12MemAlloc docs
-    static QD3D12ObjectHandle addToPool(QD3D12ObjectPool<QD3D12Resource> *pool,
-                                        ID3D12Resource *resource,
-                                        D3D12_RESOURCE_STATES state,
-                                        D3D12MA::Allocation *allocation = nullptr,
-                                        void *cpuMapPtr = nullptr)
-    {
-        Q_ASSERT(resource);
-        return pool->add({ resource, state, resource->GetDesc(), allocation, cpuMapPtr, 0, true });
-    }
-
-    // for QRhiTexture::createFrom() where the ID3D12Resource is not owned by us
-    static QD3D12ObjectHandle addNonOwningToPool(QD3D12ObjectPool<QD3D12Resource> *pool,
-                                                 ID3D12Resource *resource,
-                                                 D3D12_RESOURCE_STATES state)
-    {
-        Q_ASSERT(resource);
-        return pool->add({ resource, state, resource->GetDesc(), nullptr, nullptr, 0, false });
-    }
-
-    void releaseResources()
-    {
-        if (owns) {
-            // order matters: resource first, then the allocation
-            resource->Release();
-            if (allocation)
-                allocation->Release();
-        }
-    }
-};
-
-struct QD3D12Pipeline
-{
-    enum Type {
-        Graphics,
-        Compute
-    };
-    Type type;
-    ID3D12PipelineState *pso;
-
-    static QD3D12ObjectHandle addToPool(QD3D12ObjectPool<QD3D12Pipeline> *pool,
-                                        Type type,
-                                        ID3D12PipelineState *pso)
-    {
-        return pool->add({ type, pso });
-    }
-
-    void releaseResources()
-    {
-        pso->Release();
-    }
-};
-
-struct QD3D12RootSignature
-{
-    ID3D12RootSignature *rootSig;
-
-    static QD3D12ObjectHandle addToPool(QD3D12ObjectPool<QD3D12RootSignature> *pool,
-                                        ID3D12RootSignature *rootSig)
-    {
-        return pool->add({ rootSig });
-    }
-
-    void releaseResources()
-    {
-        rootSig->Release();
-    }
-};
-
-struct QD3D12ReleaseQueue
-{
-    void create(QD3D12ObjectPool<QD3D12Resource> *resourcePool,
-                QD3D12ObjectPool<QD3D12Pipeline> *pipelinePool,
-                QD3D12ObjectPool<QD3D12RootSignature> *rootSignaturePool)
-    {
-        this->resourcePool = resourcePool;
-        this->pipelinePool = pipelinePool;
-        this->rootSignaturePool = rootSignaturePool;
-    }
-
-    void deferredReleaseResource(const QD3D12ObjectHandle &handle);
-    void deferredReleaseResourceWithViews(const QD3D12ObjectHandle &handle,
-                                          QD3D12CpuDescriptorPool *pool,
-                                          const QD3D12Descriptor &viewsStart,
-                                          int viewCount);
-    void deferredReleasePipeline(const QD3D12ObjectHandle &handle);
-    void deferredReleaseRootSignature(const QD3D12ObjectHandle &handle);
-    void deferredReleaseCallback(std::function<void(void*)> callback, void *userData);
-    void deferredReleaseResourceAndAllocation(ID3D12Resource *resource,
-                                              D3D12MA::Allocation *allocation);
-    void deferredReleaseDescriptorHeap(ID3D12DescriptorHeap *heap);
-    void deferredReleaseViews(QD3D12CpuDescriptorPool *pool,
-                              const QD3D12Descriptor &viewsStart,
-                              int viewCount);
-
-    void activatePendingDeferredReleaseRequests(int frameSlot);
-    void executeDeferredReleases(int frameSlot, bool forced = false);
-    void releaseAll();
-
-    struct DeferredReleaseEntry {
-        enum Type {
-            Resource,
-            Pipeline,
-            RootSignature,
-            Callback,
-            ResourceAndAllocation,
-            DescriptorHeap,
-            Views
-        };
-        Type type = Resource;
-        std::optional<int> frameSlotToBeReleasedIn;
-        QD3D12ObjectHandle handle;
-        QD3D12CpuDescriptorPool *poolForViews = nullptr;
-        QD3D12Descriptor viewsStart;
-        int viewCount = 0;
-        std::function<void(void*)> callback = nullptr;
-        void *callbackUserData = nullptr;
-        QPair<ID3D12Resource *, D3D12MA::Allocation *> resourceAndAllocation = {};
-        ID3D12DescriptorHeap *descriptorHeap = nullptr;
-    };
-    QVector<DeferredReleaseEntry> queue;
-    QD3D12ObjectPool<QD3D12Resource> *resourcePool = nullptr;
-    QD3D12ObjectPool<QD3D12Pipeline> *pipelinePool = nullptr;
-    QD3D12ObjectPool<QD3D12RootSignature> *rootSignaturePool = nullptr;
-};
-
-struct QD3D12CommandBuffer;
-
-struct QD3D12ResourceBarrierGenerator
-{
-    static const int PREALLOC = 16;
-
-    void create(QD3D12ObjectPool<QD3D12Resource> *resourcePool)
-    {
-        this->resourcePool = resourcePool;
-    }
-
-    void addTransitionBarrier(const QD3D12ObjectHandle &resourceHandle, D3D12_RESOURCE_STATES stateAfter);
-    void enqueueBufferedTransitionBarriers(QD3D12CommandBuffer *cbD);
-    void enqueueSubresourceTransitionBarrier(QD3D12CommandBuffer *cbD,
-                                             const QD3D12ObjectHandle &resourceHandle,
-                                             UINT subresource,
-                                             D3D12_RESOURCE_STATES stateBefore,
-                                             D3D12_RESOURCE_STATES stateAfter);
-    void enqueueUavBarrier(QD3D12CommandBuffer *cbD, const QD3D12ObjectHandle &resourceHandle);
-
-    struct TransitionResourceBarrier {
-        QD3D12ObjectHandle resourceHandle;
-        D3D12_RESOURCE_STATES stateBefore;
-        D3D12_RESOURCE_STATES stateAfter;
-    };
-    QVarLengthArray<TransitionResourceBarrier, PREALLOC> transitionResourceBarriers;
-    QD3D12ObjectPool<QD3D12Resource> *resourcePool = nullptr;
-};
-
-struct QD3D12ShaderBytecodeCache
-{
-    struct Shader {
-        Shader() = default;
-        Shader(const QByteArray &bytecode, const QShader::NativeResourceBindingMap &rbm)
-            : bytecode(bytecode), nativeResourceBindingMap(rbm)
-        { }
-        QByteArray bytecode;
-        QShader::NativeResourceBindingMap nativeResourceBindingMap;
-    };
-
-    QHash<QRhiShaderStage, Shader> data;
-
-    void insertWithCapacityLimit(const QRhiShaderStage &key, const Shader &s);
-};
-
-struct QD3D12ShaderVisibleDescriptorHeap
-{
-    bool create(ID3D12Device *device, D3D12_DESCRIPTOR_HEAP_TYPE type, quint32 perFrameDescriptorCount);
-    void destroy();
-    void destroyWithDeferredRelease(QD3D12ReleaseQueue *releaseQueue);
-
-    QD3D12DescriptorHeap heap;
-    QD3D12DescriptorHeap perFrameHeapSlice[QD3D12_FRAMES_IN_FLIGHT];
-};
-
-// wrap foreign struct so we can legally supply equality operators and qHash:
-struct Q_D3D12_SAMPLER_DESC
-{
-    D3D12_SAMPLER_DESC desc;
-
-    friend bool operator==(const Q_D3D12_SAMPLER_DESC &lhs, const Q_D3D12_SAMPLER_DESC &rhs) noexcept
-    {
-        return lhs.desc.Filter == rhs.desc.Filter
-                && lhs.desc.AddressU == rhs.desc.AddressU
-                && lhs.desc.AddressV == rhs.desc.AddressV
-                && lhs.desc.AddressW == rhs.desc.AddressW
-                && lhs.desc.MipLODBias == rhs.desc.MipLODBias
-                && lhs.desc.MaxAnisotropy == rhs.desc.MaxAnisotropy
-                && lhs.desc.ComparisonFunc == rhs.desc.ComparisonFunc
-                // BorderColor is never used, skip it
-                && lhs.desc.MinLOD == rhs.desc.MinLOD
-                && lhs.desc.MaxLOD == rhs.desc.MaxLOD;
-    }
-
-    friend bool operator!=(const Q_D3D12_SAMPLER_DESC &lhs, const Q_D3D12_SAMPLER_DESC &rhs) noexcept
-    {
-        return !(lhs == rhs);
-    }
-
-    friend size_t qHash(const Q_D3D12_SAMPLER_DESC &key, size_t seed = 0) noexcept
-    {
-        QtPrivate::QHashCombine hash;
-        seed = hash(seed, key.desc.Filter);
-        seed = hash(seed, key.desc.AddressU);
-        seed = hash(seed, key.desc.AddressV);
-        seed = hash(seed, key.desc.AddressW);
-        seed = hash(seed, key.desc.MipLODBias);
-        seed = hash(seed, key.desc.MaxAnisotropy);
-        seed = hash(seed, key.desc.ComparisonFunc);
-        // BorderColor is never used, skip it
-        seed = hash(seed, key.desc.MinLOD);
-        seed = hash(seed, key.desc.MaxLOD);
-        return seed;
-    }
-};
-
-struct QD3D12SamplerManager
-{
-    const quint32 MAX_SAMPLERS = 512;
-
-    bool create(ID3D12Device *device);
-    void destroy();
-
-    QD3D12Descriptor getShaderVisibleDescriptor(const D3D12_SAMPLER_DESC &desc);
-
-    ID3D12Device *device = nullptr;
-    QD3D12ShaderVisibleDescriptorHeap shaderVisibleSamplerHeap;
-    QHash<Q_D3D12_SAMPLER_DESC, QD3D12Descriptor> gpuMap;
-};
-
-enum QD3D12Stage { VS = 0, HS, DS, GS, PS, CS };
-
-static inline QD3D12Stage qd3d12_stage(QRhiShaderStage::Type type)
-{
-    switch (type) {
-    case QRhiShaderStage::Vertex:
-        return VS;
-    case QRhiShaderStage::TessellationControl:
-        return HS;
-    case QRhiShaderStage::TessellationEvaluation:
-        return DS;
-    case QRhiShaderStage::Geometry:
-        return GS;
-    case QRhiShaderStage::Fragment:
-        return PS;
-    case QRhiShaderStage::Compute:
-        return CS;
-    }
-    Q_UNREACHABLE_RETURN(VS);
-}
-
-static inline D3D12_SHADER_VISIBILITY qd3d12_stageToVisibility(QD3D12Stage s)
-{
-    switch (s) {
-    case VS:
-        return D3D12_SHADER_VISIBILITY_VERTEX;
-    case HS:
-        return D3D12_SHADER_VISIBILITY_HULL;
-    case DS:
-        return D3D12_SHADER_VISIBILITY_DOMAIN;
-    case GS:
-        return D3D12_SHADER_VISIBILITY_GEOMETRY;
-    case PS:
-        return D3D12_SHADER_VISIBILITY_PIXEL;
-    case CS:
-        return D3D12_SHADER_VISIBILITY_ALL;
-    }
-    Q_UNREACHABLE_RETURN(D3D12_SHADER_VISIBILITY_ALL);
-}
-
-static inline QRhiShaderResourceBinding::StageFlag qd3d12_stageToSrb(QD3D12Stage s)
-{
-    switch (s) {
-    case VS:
-        return QRhiShaderResourceBinding::VertexStage;
-    case HS:
-        return QRhiShaderResourceBinding::TessellationControlStage;
-    case DS:
-        return QRhiShaderResourceBinding::TessellationEvaluationStage;
-    case GS:
-        return QRhiShaderResourceBinding::GeometryStage;
-    case PS:
-        return QRhiShaderResourceBinding::FragmentStage;
-    case CS:
-        return QRhiShaderResourceBinding::ComputeStage;
-    }
-    Q_UNREACHABLE_RETURN(QRhiShaderResourceBinding::VertexStage);
-}
-
-struct QD3D12ShaderStageData
-{
-    bool valid = false; // to allow simple arrays where unused stages are indicated by !valid
-    QD3D12Stage stage = VS;
-    QShader::NativeResourceBindingMap nativeResourceBindingMap;
-};
-
-struct QD3D12ShaderResourceBindings;
-
-struct QD3D12ShaderResourceVisitor
-{
-    enum StorageOp { Load = 0, Store, LoadStore };
-
-    QD3D12ShaderResourceVisitor(const QD3D12ShaderResourceBindings *srb,
-                                const QD3D12ShaderStageData *stageData,
-                                int stageCount)
-        : srb(srb),
-          stageData(stageData),
-          stageCount(stageCount)
-    {
-    }
-
-    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::Data::UniformBufferData &, int, int)> uniformBuffer = nullptr;
-    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::TextureAndSampler &, int)> texture = nullptr;
-    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::TextureAndSampler &, int)> sampler = nullptr;
-    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::Data::StorageImageData &, StorageOp, int)> storageImage = nullptr;
-    std::function<void(QD3D12Stage, const QRhiShaderResourceBinding::Data::StorageBufferData &, StorageOp, int)> storageBuffer = nullptr;
-
-    void visit();
-
-    const QD3D12ShaderResourceBindings *srb;
-    const QD3D12ShaderStageData *stageData;
-    int stageCount;
-};
-
-struct QD3D12Readback
-{
-    // common
-    int frameSlot = -1;
-    QRhiReadbackResult *result = nullptr;
-    QD3D12StagingArea staging;
-    quint32 byteSize = 0;
-    // textures
-    quint32 bytesPerLine = 0;
-    QSize pixelSize;
-    QRhiTexture::Format format = QRhiTexture::UnknownFormat;
-    quint32 stagingRowPitch = 0;
-};
-
-struct QD3D12MipmapGenerator
-{
-    bool create(QRhiD3D12 *rhiD);
-    void destroy();
-    void generate(QD3D12CommandBuffer *cbD, const QD3D12ObjectHandle &textureHandle);
-
-    QRhiD3D12 *rhiD;
-    QD3D12ObjectHandle rootSigHandle;
-    QD3D12ObjectHandle pipelineHandle;
-};
-
-struct QD3D12MemoryAllocator
-{
-    bool create(ID3D12Device *device, IDXGIAdapter1 *adapter);
-    void destroy();
-
-    HRESULT createResource(D3D12_HEAP_TYPE heapType,
-                           const D3D12_RESOURCE_DESC *resourceDesc,
-                           D3D12_RESOURCE_STATES initialState,
-                           const D3D12_CLEAR_VALUE *optimizedClearValue,
-                           D3D12MA::Allocation **maybeAllocation,
-                           REFIID riidResource,
-                           void **ppvResource);
-
-    void getBudget(D3D12MA::Budget *localBudget, D3D12MA::Budget *nonLocalBudget);
-
-    bool isUsingD3D12MA() const { return allocator != nullptr; }
-
-    ID3D12Device *device = nullptr;
-    D3D12MA::Allocator *allocator = nullptr;
-};
-
-struct QD3D12Buffer : public QRhiBuffer
-{
-    QD3D12Buffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
-    ~QD3D12Buffer();
-
-    void destroy() override;
-    bool create() override;
-    QRhiBuffer::NativeBuffer nativeBuffer() override;
-    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
-    void endFullDynamicBufferUpdateForCurrentFrame() override;
-
-    void executeHostWritesForFrameSlot(int frameSlot);
-
-    QD3D12ObjectHandle handles[QD3D12_FRAMES_IN_FLIGHT] = {};
-    struct HostWrite {
-        quint32 offset;
-        QRhiBufferData data;
-    };
-    QVarLengthArray<HostWrite, 16> pendingHostWrites[QD3D12_FRAMES_IN_FLIGHT];
-    friend class QRhiD3D12;
-};
-
-struct QD3D12RenderBuffer : public QRhiRenderBuffer
-{
-    QD3D12RenderBuffer(QRhiImplementation *rhi,
-                       Type type,
-                       const QSize &pixelSize,
-                       int sampleCount,
-                       Flags flags,
-                       QRhiTexture::Format backingFormatHint);
-    ~QD3D12RenderBuffer();
-    void destroy() override;
-    bool create() override;
-    QRhiTexture::Format backingFormat() const override;
-
-    static const DXGI_FORMAT DS_FORMAT = DXGI_FORMAT_D24_UNORM_S8_UINT;
-
-    QD3D12ObjectHandle handle;
-    QD3D12Descriptor rtv;
-    QD3D12Descriptor dsv;
-    DXGI_FORMAT dxgiFormat;
-    DXGI_SAMPLE_DESC sampleDesc;
-    uint generation = 0;
-    friend class QRhiD3D12;
-};
-
-struct QD3D12Texture : public QRhiTexture
-{
-    QD3D12Texture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
-                  int arraySize, int sampleCount, Flags flags);
-    ~QD3D12Texture();
-    void destroy() override;
-    bool create() override;
-    bool createFrom(NativeTexture src) override;
-    NativeTexture nativeTexture() override;
-    void setNativeLayout(int layout) override;
-
-    bool prepareCreate(QSize *adjustedSize = nullptr);
-    bool finishCreate();
-
-    QD3D12ObjectHandle handle;
-    QD3D12Descriptor srv;
-    DXGI_FORMAT dxgiFormat;
-    uint mipLevelCount;
-    DXGI_SAMPLE_DESC sampleDesc;
-    uint generation = 0;
-    friend class QRhiD3D12;
-};
-
-struct QD3D12Sampler : public QRhiSampler
-{
-    QD3D12Sampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
-                  AddressMode u, AddressMode v, AddressMode w);
-    ~QD3D12Sampler();
-    void destroy() override;
-    bool create() override;
-
-    QD3D12Descriptor lookupOrCreateShaderVisibleDescriptor();
-
-    D3D12_SAMPLER_DESC desc = {};
-    QD3D12Descriptor shaderVisibleDescriptor;
-};
-
-struct QD3D12RenderPassDescriptor : public QRhiRenderPassDescriptor
-{
-    QD3D12RenderPassDescriptor(QRhiImplementation *rhi);
-    ~QD3D12RenderPassDescriptor();
-    void destroy() override;
-    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
-    QVector<quint32> serializedFormat() const override;
-
-    void updateSerializedFormat();
-
-    static const int MAX_COLOR_ATTACHMENTS = 8;
-    int colorAttachmentCount = 0;
-    bool hasDepthStencil = false;
-    int colorFormat[MAX_COLOR_ATTACHMENTS];
-    int dsFormat;
-    QVector<quint32> serializedFormatData;
-};
-
-struct QD3D12RenderTargetData
-{
-    QD3D12RenderTargetData(QRhiImplementation *) { }
-
-    QD3D12RenderPassDescriptor *rp = nullptr;
-    QSize pixelSize;
-    float dpr = 1;
-    int sampleCount = 1;
-    int colorAttCount = 0;
-    int dsAttCount = 0;
-    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
-    static const int MAX_COLOR_ATTACHMENTS = QD3D12RenderPassDescriptor::MAX_COLOR_ATTACHMENTS;
-    D3D12_CPU_DESCRIPTOR_HANDLE rtv[MAX_COLOR_ATTACHMENTS];
-    D3D12_CPU_DESCRIPTOR_HANDLE dsv;
-};
-
-struct QD3D12SwapChainRenderTarget : public QRhiSwapChainRenderTarget
-{
-    QD3D12SwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
-    ~QD3D12SwapChainRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QD3D12RenderTargetData d;
-};
-
-struct QD3D12TextureRenderTarget : public QRhiTextureRenderTarget
-{
-    QD3D12TextureRenderTarget(QRhiImplementation *rhi,
-                              const QRhiTextureRenderTargetDescription &desc,
-                              Flags flags);
-    ~QD3D12TextureRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool create() override;
-
-    QD3D12RenderTargetData d;
-    bool ownsRtv[QD3D12RenderTargetData::MAX_COLOR_ATTACHMENTS];
-    QD3D12Descriptor rtv[QD3D12RenderTargetData::MAX_COLOR_ATTACHMENTS];
-    bool ownsDsv = false;
-    QD3D12Descriptor dsv;
-    friend class QRhiD3D12;
-};
-
-struct QD3D12ShaderResourceBindings : public QRhiShaderResourceBindings
-{
-    QD3D12ShaderResourceBindings(QRhiImplementation *rhi);
-    ~QD3D12ShaderResourceBindings();
-    void destroy() override;
-    bool create() override;
-    void updateResources(UpdateFlags flags) override;
-
-    QD3D12ObjectHandle createRootSignature(const QD3D12ShaderStageData *stageData, int stageCount);
-
-    struct VisitorData {
-        QVarLengthArray<D3D12_ROOT_PARAMETER1, 2> cbParams[6];
-
-        D3D12_ROOT_PARAMETER1 srvTables[6] = {};
-        QVarLengthArray<D3D12_DESCRIPTOR_RANGE1, 4> srvRanges[6];
-        quint32 currentSrvRangeOffset[6] = {};
-
-        QVarLengthArray<D3D12_ROOT_PARAMETER1, 4> samplerTables[6];
-        std::array<D3D12_DESCRIPTOR_RANGE1, 16> samplerRanges[6] = {};
-        int samplerRangeHeads[6] = {};
-
-        D3D12_ROOT_PARAMETER1 uavTables[6] = {};
-        QVarLengthArray<D3D12_DESCRIPTOR_RANGE1, 4> uavRanges[6];
-        quint32 currentUavRangeOffset[6] = {};
-    } visitorData;
-
-
-    void visitUniformBuffer(QD3D12Stage s,
-                            const QRhiShaderResourceBinding::Data::UniformBufferData &d,
-                            int shaderRegister,
-                            int binding);
-    void visitTexture(QD3D12Stage s,
-                      const QRhiShaderResourceBinding::TextureAndSampler &d,
-                      int shaderRegister);
-    void visitSampler(QD3D12Stage s,
-                      const QRhiShaderResourceBinding::TextureAndSampler &d,
-                      int shaderRegister);
-    void visitStorageBuffer(QD3D12Stage s,
-                            const QRhiShaderResourceBinding::Data::StorageBufferData &d,
-                            QD3D12ShaderResourceVisitor::StorageOp op,
-                            int shaderRegister);
-    void visitStorageImage(QD3D12Stage s,
-                           const QRhiShaderResourceBinding::Data::StorageImageData &d,
-                           QD3D12ShaderResourceVisitor::StorageOp op,
-                           int shaderRegister);
-
-    QVarLengthArray<QRhiShaderResourceBinding, 8> sortedBindings;
-    bool hasDynamicOffset = false;
-    uint generation = 0;
-};
-
-struct QD3D12GraphicsPipeline : public QRhiGraphicsPipeline
-{
-    QD3D12GraphicsPipeline(QRhiImplementation *rhi);
-    ~QD3D12GraphicsPipeline();
-    void destroy() override;
-    bool create() override;
-
-    QD3D12ObjectHandle handle;
-    QD3D12ObjectHandle rootSigHandle;
-    std::array<QD3D12ShaderStageData, 5> stageData;
-    D3D12_PRIMITIVE_TOPOLOGY topology;
-    uint generation = 0;
-    friend class QRhiD3D12;
-};
-
-struct QD3D12ComputePipeline : public QRhiComputePipeline
-{
-    QD3D12ComputePipeline(QRhiImplementation *rhi);
-    ~QD3D12ComputePipeline();
-    void destroy() override;
-    bool create() override;
-
-    QD3D12ObjectHandle handle;
-    QD3D12ObjectHandle rootSigHandle;
-    QD3D12ShaderStageData stageData;
-    uint generation = 0;
-    friend class QRhiD3D12;
-};
-
-struct QD3D12CommandBuffer : public QRhiCommandBuffer
-{
-    QD3D12CommandBuffer(QRhiImplementation *rhi);
-    ~QD3D12CommandBuffer();
-    void destroy() override;
-
-    const QRhiNativeHandles *nativeHandles();
-
-    ID3D12GraphicsCommandList *cmdList = nullptr; // not owned
-    QRhiD3D12CommandBufferNativeHandles nativeHandlesStruct;
-
-    enum PassType {
-        NoPass,
-        RenderPass,
-        ComputePass
-    };
-
-    void resetState()
-    {
-        recordingPass = NoPass;
-        currentTarget = nullptr;
-
-        resetPerPassState();
-    }
-
-    void resetPerPassState()
-    {
-        currentGraphicsPipeline = nullptr;
-        currentComputePipeline = nullptr;
-        currentPipelineGeneration = 0;
-        currentGraphicsSrb = nullptr;
-        currentComputeSrb = nullptr;
-        currentSrbGeneration = 0;
-        currentIndexBuffer = {};
-        currentIndexOffset = 0;
-        currentIndexFormat = DXGI_FORMAT_R16_UINT;
-        currentVertexBuffers = {};
-        currentVertexOffsets = {};
-    }
-
-    PassType recordingPass;
-    QRhiRenderTarget *currentTarget;
-
-    QD3D12GraphicsPipeline *currentGraphicsPipeline;
-    QD3D12ComputePipeline *currentComputePipeline;
-    uint currentPipelineGeneration;
-    QRhiShaderResourceBindings *currentGraphicsSrb;
-    QRhiShaderResourceBindings *currentComputeSrb;
-    uint currentSrbGeneration;
-    QD3D12ObjectHandle currentIndexBuffer;
-    quint32 currentIndexOffset;
-    DXGI_FORMAT currentIndexFormat;
-    std::array<QD3D12ObjectHandle, D3D12_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT> currentVertexBuffers;
-    std::array<quint32, D3D12_IA_VERTEX_INPUT_RESOURCE_SLOT_COUNT> currentVertexOffsets;
-};
-
-struct QD3D12SwapChain : public QRhiSwapChain
-{
-    QD3D12SwapChain(QRhiImplementation *rhi);
-    ~QD3D12SwapChain();
-    void destroy() override;
-
-    QRhiCommandBuffer *currentFrameCommandBuffer() override;
-    QRhiRenderTarget *currentFrameRenderTarget() override;
-
-    QSize surfacePixelSize() override;
-    bool isFormatSupported(Format f) override;
-    QRhiSwapChainHdrInfo hdrInfo() override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool createOrResize() override;
-
-    void releaseBuffers();
-    void waitCommandCompletionForFrameSlot(int frameSlot);
-    void addCommandCompletionSignalForCurrentFrameSlot();
-    void chooseFormats();
-
-    QWindow *window = nullptr;
-    IDXGISwapChain1 *sourceSwapChain1 = nullptr;
-    IDXGISwapChain3 *swapChain = nullptr;
-    QSize pixelSize;
-    UINT swapInterval = 1;
-    UINT swapChainFlags = 0;
-    DXGI_FORMAT colorFormat;
-    DXGI_FORMAT srgbAdjustedColorFormat;
-    DXGI_COLOR_SPACE_TYPE hdrColorSpace;
-    IDCompositionTarget *dcompTarget = nullptr;
-    IDCompositionVisual *dcompVisual = nullptr;
-    static const UINT BUFFER_COUNT = 3;
-    QD3D12ObjectHandle colorBuffers[BUFFER_COUNT];
-    QD3D12Descriptor rtvs[BUFFER_COUNT];
-    DXGI_SAMPLE_DESC sampleDesc;
-    QD3D12ObjectHandle msaaBuffers[BUFFER_COUNT];
-    QD3D12Descriptor msaaRtvs[BUFFER_COUNT];
-    QD3D12RenderBuffer *ds = nullptr;
-    UINT currentBackBufferIndex = 0;
-    QD3D12SwapChainRenderTarget rtWrapper;
-    QD3D12CommandBuffer cbWrapper;
-
-    struct FrameResources {
-        ID3D12Fence *fence = nullptr;
-        HANDLE fenceEvent = nullptr;
-        UINT64 fenceCounter = 0;
-        ID3D12GraphicsCommandList *cmdList = nullptr;
-    } frameRes[QD3D12_FRAMES_IN_FLIGHT];
-
-    int currentFrameSlot = 0; // index in frameRes
-};
-
-class QRhiD3D12 : public QRhiImplementation
-{
-public:
-    // 16MB * QD3D12_FRAMES_IN_FLIGHT; buffer and texture upload staging data that
-    // gets no space from this will get their own temporary staging areas.
-    static const quint32 SMALL_STAGING_AREA_BYTES_PER_FRAME = 16 * 1024 * 1024;
-
-    static const quint32 SHADER_VISIBLE_CBV_SRV_UAV_HEAP_PER_FRAME_START_SIZE = 16384;
-
-    QRhiD3D12(QRhiD3D12InitParams *params, QRhiD3D12NativeHandles *importDevice = nullptr);
-
-    bool create(QRhi::Flags flags) override;
-    void destroy() override;
-
-    QRhiGraphicsPipeline *createGraphicsPipeline() override;
-    QRhiComputePipeline *createComputePipeline() override;
-    QRhiShaderResourceBindings *createShaderResourceBindings() override;
-    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
-                             QRhiBuffer::UsageFlags usage,
-                             quint32 size) override;
-    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
-                                         const QSize &pixelSize,
-                                         int sampleCount,
-                                         QRhiRenderBuffer::Flags flags,
-                                         QRhiTexture::Format backingFormatHint) override;
-    QRhiTexture *createTexture(QRhiTexture::Format format,
-                               const QSize &pixelSize,
-                               int depth,
-                               int arraySize,
-                               int sampleCount,
-                               QRhiTexture::Flags flags) override;
-    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
-                               QRhiSampler::Filter minFilter,
-                               QRhiSampler::Filter mipmapMode,
-                               QRhiSampler:: AddressMode u,
-                               QRhiSampler::AddressMode v,
-                               QRhiSampler::AddressMode w) override;
-
-    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
-                                                       QRhiTextureRenderTarget::Flags flags) override;
-
-    QRhiSwapChain *createSwapChain() override;
-    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult finish() override;
-
-    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void beginPass(QRhiCommandBuffer *cb,
-                   QRhiRenderTarget *rt,
-                   const QColor &colorClearValue,
-                   const QRhiDepthStencilClearValue &depthStencilClearValue,
-                   QRhiResourceUpdateBatch *resourceUpdates,
-                   QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void setGraphicsPipeline(QRhiCommandBuffer *cb,
-                             QRhiGraphicsPipeline *ps) override;
-
-    void setShaderResources(QRhiCommandBuffer *cb,
-                            QRhiShaderResourceBindings *srb,
-                            int dynamicOffsetCount,
-                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
-
-    void setVertexInput(QRhiCommandBuffer *cb,
-                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
-                        QRhiBuffer *indexBuf, quint32 indexOffset,
-                        QRhiCommandBuffer::IndexFormat indexFormat) override;
-
-    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
-    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
-    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
-    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
-
-    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
-              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
-
-    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
-                     quint32 instanceCount, quint32 firstIndex,
-                     qint32 vertexOffset, quint32 firstInstance) override;
-
-    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
-    void debugMarkEnd(QRhiCommandBuffer *cb) override;
-    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
-
-    void beginComputePass(QRhiCommandBuffer *cb,
-                          QRhiResourceUpdateBatch *resourceUpdates,
-                          QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
-    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
-
-    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
-    void beginExternal(QRhiCommandBuffer *cb) override;
-    void endExternal(QRhiCommandBuffer *cb) override;
-    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
-
-    QList<int> supportedSampleCounts() const override;
-    int ubufAlignment() const override;
-    bool isYUpInFramebuffer() const override;
-    bool isYUpInNDC() const override;
-    bool isClipDepthZeroToOne() const override;
-    QMatrix4x4 clipSpaceCorrMatrix() const override;
-    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
-    bool isFeatureSupported(QRhi::Feature feature) const override;
-    int resourceLimit(QRhi::ResourceLimit limit) const override;
-    const QRhiNativeHandles *nativeHandles() override;
-    QRhiDriverInfo driverInfo() const override;
-    QRhiStats statistics() override;
-    bool makeThreadLocalNativeContextCurrent() override;
-    void releaseCachedResources() override;
-    bool isDeviceLost() const override;
-
-    QByteArray pipelineCacheData() override;
-    void setPipelineCacheData(const QByteArray &data) override;
-
-    void waitGpu();
-    DXGI_SAMPLE_DESC effectiveSampleCount(int sampleCount, DXGI_FORMAT format) const;
-    bool ensureDirectCompositionDevice();
-    bool startCommandListForCurrentFrameSlot(ID3D12GraphicsCommandList **cmdList);
-    void enqueueResourceUpdates(QD3D12CommandBuffer *cbD, QRhiResourceUpdateBatch *resourceUpdates);
-    void finishActiveReadbacks(bool forced = false);
-    bool ensureShaderVisibleDescriptorHeapCapacity(QD3D12ShaderVisibleDescriptorHeap *h,
-                                                   D3D12_DESCRIPTOR_HEAP_TYPE type,
-                                                   int frameSlot,
-                                                   quint32 neededDescriptorCount,
-                                                   bool *gotNew);
-    void bindShaderVisibleHeaps(QD3D12CommandBuffer *cbD);
-
-    bool debugLayer = false;
-    ID3D12Device *dev = nullptr;
-    D3D_FEATURE_LEVEL minimumFeatureLevel = D3D_FEATURE_LEVEL(0);
-    LUID adapterLuid = {};
-    bool importedDevice = false;
-    bool importedCommandQueue = false;
-    QRhi::Flags rhiFlags;
-    IDXGIFactory2 *dxgiFactory = nullptr;
-    bool supportsAllowTearing = false;
-    IDXGIAdapter1 *activeAdapter = nullptr;
-    QRhiDriverInfo driverInfoStruct;
-    QRhiD3D12NativeHandles nativeHandlesStruct;
-    bool deviceLost = false;
-    ID3D12CommandQueue *cmdQueue = nullptr;
-    ID3D12Fence *fullFence = nullptr;
-    HANDLE fullFenceEvent = nullptr;
-    UINT64 fullFenceCounter = 0;
-    ID3D12CommandAllocator *cmdAllocators[QD3D12_FRAMES_IN_FLIGHT] = {};
-    QD3D12MemoryAllocator vma;
-    QD3D12CpuDescriptorPool rtvPool;
-    QD3D12CpuDescriptorPool dsvPool;
-    QD3D12CpuDescriptorPool cbvSrvUavPool;
-    QD3D12ObjectPool<QD3D12Resource> resourcePool;
-    QD3D12ObjectPool<QD3D12Pipeline> pipelinePool;
-    QD3D12ObjectPool<QD3D12RootSignature> rootSignaturePool;
-    QD3D12ReleaseQueue releaseQueue;
-    QD3D12ResourceBarrierGenerator barrierGen;
-    QD3D12SamplerManager samplerMgr;
-    QD3D12MipmapGenerator mipmapGen;
-    QD3D12StagingArea smallStagingAreas[QD3D12_FRAMES_IN_FLIGHT];
-    QD3D12ShaderVisibleDescriptorHeap shaderVisibleCbvSrvUavHeap;
-    IDCompositionDevice *dcompDevice = nullptr;
-    QD3D12SwapChain *currentSwapChain = nullptr;
-    QSet<QD3D12SwapChain *> swapchains;
-    QD3D12ShaderBytecodeCache shaderBytecodeCache;
-    QVarLengthArray<QD3D12Readback, 4> activeReadbacks;
-    bool offscreenActive = false;
-    QD3D12CommandBuffer *offscreenCb[QD3D12_FRAMES_IN_FLIGHT] = {};
-
-    struct VisitorData {
-        QVarLengthArray<QPair<QD3D12ObjectHandle, quint32>, 4> cbufs[6];
-        QVarLengthArray<QD3D12Descriptor, 8> srvs[6];
-        QVarLengthArray<QD3D12Descriptor, 8> samplers[6];
-        QVarLengthArray<QPair<QD3D12ObjectHandle, D3D12_UNORDERED_ACCESS_VIEW_DESC>, 4> uavs[6];
-    } visitorData;
-
-    void visitUniformBuffer(QD3D12Stage s,
-                            const QRhiShaderResourceBinding::Data::UniformBufferData &d,
-                            int shaderRegister,
-                            int binding,
-                            int dynamicOffsetCount,
-                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets);
-    void visitTexture(QD3D12Stage s,
-                      const QRhiShaderResourceBinding::TextureAndSampler &d,
-                      int shaderRegister);
-    void visitSampler(QD3D12Stage s,
-                      const QRhiShaderResourceBinding::TextureAndSampler &d,
-                      int shaderRegister);
-    void visitStorageBuffer(QD3D12Stage s,
-                            const QRhiShaderResourceBinding::Data::StorageBufferData &d,
-                            QD3D12ShaderResourceVisitor::StorageOp op,
-                            int shaderRegister);
-    void visitStorageImage(QD3D12Stage s,
-                           const QRhiShaderResourceBinding::Data::StorageImageData &d,
-                           QD3D12ShaderResourceVisitor::StorageOp op,
-                           int shaderRegister);
-};
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/rhi/qrhigles2.cpp b/src/gui/rhi/qrhigles2.cpp
index d0a0c0a870..806e17c1a6 100644
--- a/src/gui/rhi/qrhigles2.cpp
+++ b/src/gui/rhi/qrhigles2.cpp
@@ -1,7 +1,7 @@
-// Copyright (C) 2021 The Qt Company Ltd.
+// 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
 
-#include "qrhigles2_p_p.h"
+#include "qrhigles2_p.h"
 #include <QOffscreenSurface>
 #include <QOpenGLContext>
 #include <QtCore/qmap.h>
@@ -27,10 +27,13 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QRhiGles2InitParams
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief OpenGL specific initialization parameters.
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     An OpenGL-based QRhi needs an already created QSurface that can be used in
     combination with QOpenGLContext. Most commonly, this is a QOffscreenSurface
     in practice. Additionally, while optional, it is recommended that the QWindow
@@ -104,12 +107,50 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
+    \variable QRhiGles2InitParams::format
+
+    The QSurfaceFormat, initialized to QSurfaceFormat::defaultFormat() by default.
+*/
+
+/*!
+    \variable QRhiGles2InitParams::fallbackSurface
+
+    A QSurface compatible with \l format. Typically a QOffscreenSurface.
+    Providing this is mandatory. Be aware of the threading implications: a
+    QOffscreenSurface, like QWindow, must only ever be created and destroyed on
+    the main (gui) thread, even if the QRhi is created and operates on another
+    thread.
+*/
+
+/*!
+    \variable QRhiGles2InitParams::window
+
+    Optional, but setting it is recommended when targeting a QWindow with the
+    QRhi.
+*/
+
+/*!
+    \variable QRhiGles2InitParams::shareContext
+
+    Optional, the QOpenGLContext to share resource with. QRhi creates its own
+    context, and setting this member to a valid QOpenGLContext leads to calling
+    \l{QOpenGLContext::setShareContext()}{setShareContext()} with it.
+*/
+
+/*!
     \class QRhiGles2NativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Holds the OpenGL context used by the QRhi.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
+/*!
+    \variable QRhiGles2NativeHandles::context
+*/
+
 #ifndef GL_BGRA
 #define GL_BGRA                           0x80E1
 #endif
diff --git a/src/gui/rhi/qrhigles2_p.h b/src/gui/rhi/qrhigles2_p.h
index e3f4fbe7d7..47d6c3f6d7 100644
--- a/src/gui/rhi/qrhigles2_p.h
+++ b/src/gui/rhi/qrhigles2_p.h
@@ -1,8 +1,8 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#ifndef QRHIGLES2_H
-#define QRHIGLES2_H
+#ifndef QRHIGLES2_P_H
+#define QRHIGLES2_P_H
 
 //
 //  W A R N I N G
@@ -15,33 +15,1062 @@
 // We mean it.
 //
 
-#include <private/qrhi_p.h>
-#include <QtGui/qsurfaceformat.h>
+#include "qrhi_p.h"
+#include "qshaderdescription.h"
+#include <qopengl.h>
+#include <QByteArray>
+#include <QWindow>
+#include <QPointer>
+#include <QtCore/private/qduplicatetracker_p.h>
+#include <optional>
 
 QT_BEGIN_NAMESPACE
 
-class QOpenGLContext;
-class QOffscreenSurface;
-class QSurface;
-class QWindow;
+class QOpenGLExtensions;
 
-struct Q_GUI_EXPORT QRhiGles2InitParams : public QRhiInitParams
+struct QGles2Buffer : public QRhiBuffer
 {
-    QRhiGles2InitParams();
+    QGles2Buffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
+    ~QGles2Buffer();
+    void destroy() override;
+    bool create() override;
+    QRhiBuffer::NativeBuffer nativeBuffer() override;
+    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
+    void endFullDynamicBufferUpdateForCurrentFrame() override;
 
-    QSurfaceFormat format;
-    QSurface *fallbackSurface = nullptr;
-    QWindow *window = nullptr;
-    QOpenGLContext *shareContext = nullptr;
+    quint32 nonZeroSize = 0;
+    GLuint buffer = 0;
+    GLenum targetForDataOps;
+    QByteArray data;
+    enum Access {
+        AccessNone,
+        AccessVertex,
+        AccessIndex,
+        AccessUniform,
+        AccessStorageRead,
+        AccessStorageWrite,
+        AccessStorageReadWrite,
+        AccessUpdate
+    };
+    struct UsageState {
+        Access access;
+    };
+    UsageState usageState;
+    friend class QRhiGles2;
+};
+
+struct QGles2RenderBuffer : public QRhiRenderBuffer
+{
+    QGles2RenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
+                       int sampleCount, QRhiRenderBuffer::Flags flags,
+                       QRhiTexture::Format backingFormatHint);
+    ~QGles2RenderBuffer();
+    void destroy() override;
+    bool create() override;
+    bool createFrom(NativeRenderBuffer src) override;
+    QRhiTexture::Format backingFormat() const override;
+
+    GLuint renderbuffer = 0;
+    GLuint stencilRenderbuffer = 0; // when packed depth-stencil not supported
+    int samples;
+    bool owns = true;
+    uint generation = 0;
+    friend class QRhiGles2;
+};
+
+struct QGles2SamplerData
+{
+    GLenum glminfilter = 0;
+    GLenum glmagfilter = 0;
+    GLenum glwraps = 0;
+    GLenum glwrapt = 0;
+    GLenum glwrapr = 0;
+    GLenum gltexcomparefunc = 0;
+};
+
+inline bool operator==(const QGles2SamplerData &a, const QGles2SamplerData &b)
+{
+    return a.glminfilter == b.glminfilter
+            && a.glmagfilter == b.glmagfilter
+            && a.glwraps == b.glwraps
+            && a.glwrapt == b.glwrapt
+            && a.glwrapr == b.glwrapr
+            && a.gltexcomparefunc == b.gltexcomparefunc;
+}
+
+inline bool operator!=(const QGles2SamplerData &a, const QGles2SamplerData &b)
+{
+    return !(a == b);
+}
+
+struct QGles2Texture : public QRhiTexture
+{
+    QGles2Texture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
+                  int arraySize, int sampleCount, Flags flags);
+    ~QGles2Texture();
+    void destroy() override;
+    bool create() override;
+    bool createFrom(NativeTexture src) override;
+    NativeTexture nativeTexture() override;
+
+    bool prepareCreate(QSize *adjustedSize = nullptr);
+
+    GLuint texture = 0;
+    bool owns = true;
+    GLenum target;
+    GLenum glintformat;
+    GLenum glsizedintformat;
+    GLenum glformat;
+    GLenum gltype;
+    QGles2SamplerData samplerState;
+    bool specified = false;
+    bool zeroInitialized = false;
+    int mipLevelCount = 0;
+
+    enum Access {
+        AccessNone,
+        AccessSample,
+        AccessFramebuffer,
+        AccessStorageRead,
+        AccessStorageWrite,
+        AccessStorageReadWrite,
+        AccessUpdate,
+        AccessRead
+    };
+    struct UsageState {
+        Access access;
+    };
+    UsageState usageState;
+
+    uint generation = 0;
+    friend class QRhiGles2;
+};
+
+struct QGles2Sampler : public QRhiSampler
+{
+    QGles2Sampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
+                  AddressMode u, AddressMode v, AddressMode w);
+    ~QGles2Sampler();
+    void destroy() override;
+    bool create() override;
+
+    QGles2SamplerData d;
+    uint generation = 0;
+    friend class QRhiGles2;
+};
+
+struct QGles2RenderPassDescriptor : public QRhiRenderPassDescriptor
+{
+    QGles2RenderPassDescriptor(QRhiImplementation *rhi);
+    ~QGles2RenderPassDescriptor();
+    void destroy() override;
+    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
+    QVector<quint32> serializedFormat() const override;
+};
+
+struct QGles2RenderTargetData
+{
+    QGles2RenderTargetData(QRhiImplementation *) { }
+
+    bool isValid() const { return rp != nullptr; }
+
+    QGles2RenderPassDescriptor *rp = nullptr;
+    QSize pixelSize;
+    float dpr = 1;
+    int sampleCount = 1;
+    int colorAttCount = 0;
+    int dsAttCount = 0;
+    bool srgbUpdateAndBlend = false;
+    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
+    std::optional<QRhiSwapChain::StereoTargetBuffer> stereoTarget;
+};
 
-    static QOffscreenSurface *newFallbackSurface(const QSurfaceFormat &format = QSurfaceFormat::defaultFormat());
+struct QGles2SwapChainRenderTarget : public QRhiSwapChainRenderTarget
+{
+    QGles2SwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
+    ~QGles2SwapChainRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QGles2RenderTargetData d;
+};
+
+struct QGles2TextureRenderTarget : public QRhiTextureRenderTarget
+{
+    QGles2TextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
+    ~QGles2TextureRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool create() override;
+
+    QGles2RenderTargetData d;
+    GLuint framebuffer = 0;
+    friend class QRhiGles2;
+};
+
+struct QGles2ShaderResourceBindings : public QRhiShaderResourceBindings
+{
+    QGles2ShaderResourceBindings(QRhiImplementation *rhi);
+    ~QGles2ShaderResourceBindings();
+    void destroy() override;
+    bool create() override;
+    void updateResources(UpdateFlags flags) override;
+
+    bool hasDynamicOffset = false;
+    uint generation = 0;
+    friend class QRhiGles2;
+};
+
+struct QGles2UniformDescription
+{
+    QShaderDescription::VariableType type;
+    int glslLocation;
+    int binding;
+    quint32 offset;
+    quint32 size;
+    int arrayDim;
 };
 
-struct Q_GUI_EXPORT QRhiGles2NativeHandles : public QRhiNativeHandles
+Q_DECLARE_TYPEINFO(QGles2UniformDescription, Q_RELOCATABLE_TYPE);
+
+struct QGles2SamplerDescription
+{
+    int glslLocation;
+    int combinedBinding;
+    int tbinding;
+    int sbinding;
+};
+
+Q_DECLARE_TYPEINFO(QGles2SamplerDescription, Q_RELOCATABLE_TYPE);
+
+using QGles2UniformDescriptionVector = QVarLengthArray<QGles2UniformDescription, 8>;
+using QGles2SamplerDescriptionVector = QVarLengthArray<QGles2SamplerDescription, 4>;
+
+struct QGles2UniformState
+{
+    static constexpr int MAX_TRACKED_LOCATION = 1023;
+    int componentCount;
+    float v[4];
+};
+
+struct QGles2GraphicsPipeline : public QRhiGraphicsPipeline
+{
+    QGles2GraphicsPipeline(QRhiImplementation *rhi);
+    ~QGles2GraphicsPipeline();
+    void destroy() override;
+    bool create() override;
+
+    GLuint program = 0;
+    GLenum drawMode = GL_TRIANGLES;
+    QGles2UniformDescriptionVector uniforms;
+    QGles2SamplerDescriptionVector samplers;
+    QGles2UniformState uniformState[QGles2UniformState::MAX_TRACKED_LOCATION + 1];
+    QRhiShaderResourceBindings *currentSrb = nullptr;
+    uint currentSrbGeneration = 0;
+    uint generation = 0;
+    friend class QRhiGles2;
+};
+
+struct QGles2ComputePipeline : public QRhiComputePipeline
 {
-    QOpenGLContext *context = nullptr;
+    QGles2ComputePipeline(QRhiImplementation *rhi);
+    ~QGles2ComputePipeline();
+    void destroy() override;
+    bool create() override;
+
+    GLuint program = 0;
+    QGles2UniformDescriptionVector uniforms;
+    QGles2SamplerDescriptionVector samplers;
+    QGles2UniformState uniformState[QGles2UniformState::MAX_TRACKED_LOCATION + 1];
+    QRhiShaderResourceBindings *currentSrb = nullptr;
+    uint currentSrbGeneration = 0;
+    uint generation = 0;
+    friend class QRhiGles2;
 };
 
+struct QGles2CommandBuffer : public QRhiCommandBuffer
+{
+    QGles2CommandBuffer(QRhiImplementation *rhi);
+    ~QGles2CommandBuffer();
+    void destroy() override;
+
+    // keep at a reasonably low value otherwise sizeof Command explodes
+    static const int MAX_DYNAMIC_OFFSET_COUNT = 8;
+
+    struct Command {
+        enum Cmd {
+            BeginFrame,
+            EndFrame,
+            ResetFrame,
+            Viewport,
+            Scissor,
+            BlendConstants,
+            StencilRef,
+            BindVertexBuffer,
+            BindIndexBuffer,
+            Draw,
+            DrawIndexed,
+            BindGraphicsPipeline,
+            BindShaderResources,
+            BindFramebuffer,
+            Clear,
+            BufferSubData,
+            GetBufferSubData,
+            CopyTex,
+            ReadPixels,
+            SubImage,
+            CompressedImage,
+            CompressedSubImage,
+            BlitFromRenderbuffer,
+            GenMip,
+            BindComputePipeline,
+            Dispatch,
+            BarriersForPass,
+            Barrier
+        };
+        Cmd cmd;
+
+        // QRhi*/QGles2* references should be kept at minimum (so no
+        // QRhiTexture/Buffer/etc. pointers).
+        union Args {
+            struct {
+                float x, y, w, h;
+                float d0, d1;
+            } viewport;
+            struct {
+                int x, y, w, h;
+            } scissor;
+            struct {
+                float r, g, b, a;
+            } blendConstants;
+            struct {
+                quint32 ref;
+                QRhiGraphicsPipeline *ps;
+            } stencilRef;
+            struct {
+                QRhiGraphicsPipeline *ps;
+                GLuint buffer;
+                quint32 offset;
+                int binding;
+            } bindVertexBuffer;
+            struct {
+                GLuint buffer;
+                quint32 offset;
+                GLenum type;
+            } bindIndexBuffer;
+            struct {
+                QRhiGraphicsPipeline *ps;
+                quint32 vertexCount;
+                quint32 firstVertex;
+                quint32 instanceCount;
+                quint32 baseInstance;
+            } draw;
+            struct {
+                QRhiGraphicsPipeline *ps;
+                quint32 indexCount;
+                quint32 firstIndex;
+                quint32 instanceCount;
+                quint32 baseInstance;
+                qint32 baseVertex;
+            } drawIndexed;
+            struct {
+                QRhiGraphicsPipeline *ps;
+            } bindGraphicsPipeline;
+            struct {
+                QRhiGraphicsPipeline *maybeGraphicsPs;
+                QRhiComputePipeline *maybeComputePs;
+                QRhiShaderResourceBindings *srb;
+                int dynamicOffsetCount;
+                uint dynamicOffsetPairs[MAX_DYNAMIC_OFFSET_COUNT * 2]; // binding, offset
+            } bindShaderResources;
+            struct {
+                GLbitfield mask;
+                float c[4];
+                float d;
+                quint32 s;
+            } clear;
+            struct {
+                GLuint fbo;
+                bool srgb;
+                int colorAttCount;
+                bool stereo;
+                QRhiSwapChain::StereoTargetBuffer stereoTarget;
+            } bindFramebuffer;
+            struct {
+                GLenum target;
+                GLuint buffer;
+                int offset;
+                int size;
+                const void *data; // must come from retainData()
+            } bufferSubData;
+            struct {
+                QRhiReadbackResult *result;
+                GLenum target;
+                GLuint buffer;
+                int offset;
+                int size;
+            } getBufferSubData;
+            struct {
+                GLenum srcTarget;
+                GLenum srcFaceTarget;
+                GLuint srcTexture;
+                int srcLevel;
+                int srcX;
+                int srcY;
+                int srcZ;
+                GLenum dstTarget;
+                GLuint dstTexture;
+                GLenum dstFaceTarget;
+                int dstLevel;
+                int dstX;
+                int dstY;
+                int dstZ;
+                int w;
+                int h;
+            } copyTex;
+            struct {
+                QRhiReadbackResult *result;
+                GLuint texture;
+                int w;
+                int h;
+                QRhiTexture::Format format;
+                GLenum readTarget;
+                int level;
+                int slice3D;
+            } readPixels;
+            struct {
+                GLenum target;
+                GLuint texture;
+                GLenum faceTarget;
+                int level;
+                int dx;
+                int dy;
+                int dz;
+                int w;
+                int h;
+                GLenum glformat;
+                GLenum gltype;
+                int rowStartAlign;
+                int rowLength;
+                const void *data; // must come from retainImage()
+            } subImage;
+            struct {
+                GLenum target;
+                GLuint texture;
+                GLenum faceTarget;
+                int level;
+                GLenum glintformat;
+                int w;
+                int h;
+                int depth;
+                int size;
+                const void *data; // must come from retainData()
+            } compressedImage;
+            struct {
+                GLenum target;
+                GLuint texture;
+                GLenum faceTarget;
+                int level;
+                int dx;
+                int dy;
+                int dz;
+                int w;
+                int h;
+                GLenum glintformat;
+                int size;
+                const void *data; // must come from retainData()
+            } compressedSubImage;
+            struct {
+                GLuint renderbuffer;
+                int w;
+                int h;
+                GLenum target;
+                GLuint texture;
+                int dstLevel;
+                int dstLayer;
+            } blitFromRb;
+            struct {
+                GLenum target;
+                GLuint texture;
+            } genMip;
+            struct {
+                QRhiComputePipeline *ps;
+            } bindComputePipeline;
+            struct {
+                GLuint x;
+                GLuint y;
+                GLuint z;
+            } dispatch;
+            struct {
+                int trackerIndex;
+            } barriersForPass;
+            struct {
+                GLbitfield barriers;
+            } barrier;
+        } args;
+    };
+
+    enum PassType {
+        NoPass,
+        RenderPass,
+        ComputePass
+    };
+
+    QRhiBackendCommandList<Command> commands;
+    QVarLengthArray<QRhiPassResourceTracker, 8> passResTrackers;
+    int currentPassResTrackerIndex;
+
+    PassType recordingPass;
+    bool passNeedsResourceTracking;
+    QRhiRenderTarget *currentTarget;
+    QRhiGraphicsPipeline *currentGraphicsPipeline;
+    QRhiComputePipeline *currentComputePipeline;
+    uint currentPipelineGeneration;
+    QRhiShaderResourceBindings *currentGraphicsSrb;
+    QRhiShaderResourceBindings *currentComputeSrb;
+    uint currentSrbGeneration;
+
+    struct GraphicsPassState {
+        bool valid = false;
+        bool scissor;
+        bool cullFace;
+        GLenum cullMode;
+        GLenum frontFace;
+        bool blendEnabled;
+        struct ColorMask { bool r, g, b, a; } colorMask;
+        struct Blend {
+            GLenum srcColor;
+            GLenum dstColor;
+            GLenum srcAlpha;
+            GLenum dstAlpha;
+            GLenum opColor;
+            GLenum opAlpha;
+        } blend;
+        bool depthTest;
+        bool depthWrite;
+        GLenum depthFunc;
+        bool stencilTest;
+        GLuint stencilReadMask;
+        GLuint stencilWriteMask;
+        struct StencilFace {
+            GLenum func;
+            GLenum failOp;
+            GLenum zfailOp;
+            GLenum zpassOp;
+        } stencil[2]; // front, back
+        bool polyOffsetFill;
+        float polyOffsetFactor;
+        float polyOffsetUnits;
+        float lineWidth;
+        int cpCount;
+        GLenum polygonMode;
+        void reset() { valid = false; }
+        struct {
+            // not part of QRhiGraphicsPipeline but used by setGraphicsPipeline()
+            GLint stencilRef = 0;
+        } dynamic;
+    } graphicsPassState;
+
+    struct ComputePassState {
+        enum Access {
+            Read = 0x01,
+            Write = 0x02
+        };
+        QHash<QRhiResource *, QPair<int, bool> > writtenResources;
+        void reset() {
+            writtenResources.clear();
+        }
+    } computePassState;
+
+    struct TextureUnitState {
+        void *ps;
+        uint psGeneration;
+        uint texture;
+    } textureUnitState[16];
+
+    QVarLengthArray<QByteArray, 4> dataRetainPool;
+    QVarLengthArray<QRhiBufferData, 4> bufferDataRetainPool;
+    QVarLengthArray<QImage, 4> imageRetainPool;
+
+    // relies heavily on implicit sharing (no copies of the actual data will be made)
+    const void *retainData(const QByteArray &data) {
+        dataRetainPool.append(data);
+        return dataRetainPool.last().constData();
+    }
+    const uchar *retainBufferData(const QRhiBufferData &data) {
+        bufferDataRetainPool.append(data);
+        return reinterpret_cast<const uchar *>(bufferDataRetainPool.last().constData());
+    }
+    const void *retainImage(const QImage &image) {
+        imageRetainPool.append(image);
+        return imageRetainPool.last().constBits();
+    }
+    void resetCommands() {
+        commands.reset();
+        dataRetainPool.clear();
+        bufferDataRetainPool.clear();
+        imageRetainPool.clear();
+
+        passResTrackers.clear();
+        currentPassResTrackerIndex = -1;
+    }
+    void resetState() {
+        recordingPass = NoPass;
+        passNeedsResourceTracking = true;
+        currentTarget = nullptr;
+        resetCommands();
+        resetCachedState();
+    }
+    void resetCachedState() {
+        currentGraphicsPipeline = nullptr;
+        currentComputePipeline = nullptr;
+        currentPipelineGeneration = 0;
+        currentGraphicsSrb = nullptr;
+        currentComputeSrb = nullptr;
+        currentSrbGeneration = 0;
+        graphicsPassState.reset();
+        computePassState.reset();
+        memset(textureUnitState, 0, sizeof(textureUnitState));
+    }
+};
+
+inline bool operator==(const QGles2CommandBuffer::GraphicsPassState::StencilFace &a,
+                       const QGles2CommandBuffer::GraphicsPassState::StencilFace &b)
+{
+    return a.func == b.func
+            && a.failOp == b.failOp
+            && a.zfailOp == b.zfailOp
+            && a.zpassOp == b.zpassOp;
+}
+
+inline bool operator!=(const QGles2CommandBuffer::GraphicsPassState::StencilFace &a,
+                       const QGles2CommandBuffer::GraphicsPassState::StencilFace &b)
+{
+    return !(a == b);
+}
+
+inline bool operator==(const QGles2CommandBuffer::GraphicsPassState::ColorMask &a,
+                       const QGles2CommandBuffer::GraphicsPassState::ColorMask &b)
+{
+    return a.r == b.r && a.g == b.g && a.b == b.b && a.a == b.a;
+}
+
+inline bool operator!=(const QGles2CommandBuffer::GraphicsPassState::ColorMask &a,
+                       const QGles2CommandBuffer::GraphicsPassState::ColorMask &b)
+{
+    return !(a == b);
+}
+
+inline bool operator==(const QGles2CommandBuffer::GraphicsPassState::Blend &a,
+                       const QGles2CommandBuffer::GraphicsPassState::Blend &b)
+{
+    return a.srcColor == b.srcColor
+            && a.dstColor == b.dstColor
+            && a.srcAlpha == b.srcAlpha
+            && a.dstAlpha == b.dstAlpha
+            && a.opColor == b.opColor
+            && a.opAlpha == b.opAlpha;
+}
+
+inline bool operator!=(const QGles2CommandBuffer::GraphicsPassState::Blend &a,
+                       const QGles2CommandBuffer::GraphicsPassState::Blend &b)
+{
+    return !(a == b);
+}
+
+struct QGles2SwapChain : public QRhiSwapChain
+{
+    QGles2SwapChain(QRhiImplementation *rhi);
+    ~QGles2SwapChain();
+    void destroy() override;
+
+    QRhiCommandBuffer *currentFrameCommandBuffer() override;
+    QRhiRenderTarget *currentFrameRenderTarget() override;
+    QRhiRenderTarget *currentFrameRenderTarget(StereoTargetBuffer targetBuffer) override;
+
+    QSize surfacePixelSize() override;
+    bool isFormatSupported(Format f) override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool createOrResize() override;
+
+    void initSwapChainRenderTarget(QGles2SwapChainRenderTarget *rt);
+
+    QSurface *surface = nullptr;
+    QSize pixelSize;
+    QGles2SwapChainRenderTarget rt;
+    QGles2SwapChainRenderTarget rtLeft;
+    QGles2SwapChainRenderTarget rtRight;
+    QGles2CommandBuffer cb;
+    int frameCount = 0;
+};
+
+class QRhiGles2 : public QRhiImplementation
+{
+public:
+    QRhiGles2(QRhiGles2InitParams *params, QRhiGles2NativeHandles *importDevice = nullptr);
+
+    bool create(QRhi::Flags flags) override;
+    void destroy() override;
+
+    QRhiGraphicsPipeline *createGraphicsPipeline() override;
+    QRhiComputePipeline *createComputePipeline() override;
+    QRhiShaderResourceBindings *createShaderResourceBindings() override;
+    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
+                             QRhiBuffer::UsageFlags usage,
+                             quint32 size) override;
+    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
+                                         const QSize &pixelSize,
+                                         int sampleCount,
+                                         QRhiRenderBuffer::Flags flags,
+                                         QRhiTexture::Format backingFormatHint) override;
+    QRhiTexture *createTexture(QRhiTexture::Format format,
+                               const QSize &pixelSize,
+                               int depth,
+                               int arraySize,
+                               int sampleCount,
+                               QRhiTexture::Flags flags) override;
+    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
+                               QRhiSampler::Filter minFilter,
+                               QRhiSampler::Filter mipmapMode,
+                               QRhiSampler:: AddressMode u,
+                               QRhiSampler::AddressMode v,
+                               QRhiSampler::AddressMode w) override;
+
+    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
+                                                       QRhiTextureRenderTarget::Flags flags) override;
+
+    QRhiSwapChain *createSwapChain() override;
+    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult finish() override;
+
+    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void beginPass(QRhiCommandBuffer *cb,
+                   QRhiRenderTarget *rt,
+                   const QColor &colorClearValue,
+                   const QRhiDepthStencilClearValue &depthStencilClearValue,
+                   QRhiResourceUpdateBatch *resourceUpdates,
+                   QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void setGraphicsPipeline(QRhiCommandBuffer *cb,
+                             QRhiGraphicsPipeline *ps) override;
+
+    void setShaderResources(QRhiCommandBuffer *cb,
+                            QRhiShaderResourceBindings *srb,
+                            int dynamicOffsetCount,
+                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
+
+    void setVertexInput(QRhiCommandBuffer *cb,
+                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
+                        QRhiBuffer *indexBuf, quint32 indexOffset,
+                        QRhiCommandBuffer::IndexFormat indexFormat) override;
+
+    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
+    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
+    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
+    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
+
+    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
+              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
+
+    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
+                     quint32 instanceCount, quint32 firstIndex,
+                     qint32 vertexOffset, quint32 firstInstance) override;
+
+    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
+    void debugMarkEnd(QRhiCommandBuffer *cb) override;
+    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
+
+    void beginComputePass(QRhiCommandBuffer *cb,
+                          QRhiResourceUpdateBatch *resourceUpdates,
+                          QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
+    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
+
+    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
+    void beginExternal(QRhiCommandBuffer *cb) override;
+    void endExternal(QRhiCommandBuffer *cb) override;
+    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
+
+    QList<int> supportedSampleCounts() const override;
+    int ubufAlignment() const override;
+    bool isYUpInFramebuffer() const override;
+    bool isYUpInNDC() const override;
+    bool isClipDepthZeroToOne() const override;
+    QMatrix4x4 clipSpaceCorrMatrix() const override;
+    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
+    bool isFeatureSupported(QRhi::Feature feature) const override;
+    int resourceLimit(QRhi::ResourceLimit limit) const override;
+    const QRhiNativeHandles *nativeHandles() override;
+    QRhiDriverInfo driverInfo() const override;
+    QRhiStats statistics() override;
+    bool makeThreadLocalNativeContextCurrent() override;
+    void releaseCachedResources() override;
+    bool isDeviceLost() const override;
+
+    QByteArray pipelineCacheData() override;
+    void setPipelineCacheData(const QByteArray &data) override;
+
+    bool ensureContext(QSurface *surface = nullptr) const;
+    QSurface *evaluateFallbackSurface() const;
+    void executeDeferredReleases();
+    void trackedBufferBarrier(QGles2CommandBuffer *cbD, QGles2Buffer *bufD, QGles2Buffer::Access access);
+    void trackedImageBarrier(QGles2CommandBuffer *cbD, QGles2Texture *texD, QGles2Texture::Access access);
+    void enqueueSubresUpload(QGles2Texture *texD, QGles2CommandBuffer *cbD,
+                             int layer, int level, const QRhiTextureSubresourceUploadDescription &subresDesc);
+    void enqueueResourceUpdates(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates);
+    void trackedRegisterBuffer(QRhiPassResourceTracker *passResTracker,
+                               QGles2Buffer *bufD,
+                               QRhiPassResourceTracker::BufferAccess access,
+                               QRhiPassResourceTracker::BufferStage stage);
+    void trackedRegisterTexture(QRhiPassResourceTracker *passResTracker,
+                                QGles2Texture *texD,
+                                QRhiPassResourceTracker::TextureAccess access,
+                                QRhiPassResourceTracker::TextureStage stage);
+    void executeCommandBuffer(QRhiCommandBuffer *cb);
+    void executeBindGraphicsPipeline(QGles2CommandBuffer *cbD, QGles2GraphicsPipeline *psD);
+    void bindCombinedSampler(QGles2CommandBuffer *cbD, QGles2Texture *texD, QGles2Sampler *samplerD,
+                             void *ps, uint psGeneration, int glslLocation,
+                             int *texUnit, bool *activeTexUnitAltered);
+    void bindShaderResources(QGles2CommandBuffer *cbD,
+                             QRhiGraphicsPipeline *maybeGraphicsPs, QRhiComputePipeline *maybeComputePs,
+                             QRhiShaderResourceBindings *srb,
+                             const uint *dynOfsPairs, int dynOfsCount);
+    QGles2RenderTargetData *enqueueBindFramebuffer(QRhiRenderTarget *rt, QGles2CommandBuffer *cbD,
+                                                   bool *wantsColorClear = nullptr, bool *wantsDsClear = nullptr);
+    void enqueueBarriersForPass(QGles2CommandBuffer *cbD);
+    int effectiveSampleCount(int sampleCount) const;
+    QByteArray shaderSource(const QRhiShaderStage &shaderStage, QShaderVersion *shaderVersion);
+    bool compileShader(GLuint program, const QRhiShaderStage &shaderStage, QShaderVersion *shaderVersion);
+    bool linkProgram(GLuint program);
+    void registerUniformIfActive(const QShaderDescription::BlockVariable &var,
+                                 const QByteArray &namePrefix, int binding, int baseOffset,
+                                 GLuint program,
+                                 QDuplicateTracker<int, 256> *activeUniformLocations,
+                                 QGles2UniformDescriptionVector *dst);
+    void gatherUniforms(GLuint program, const QShaderDescription::UniformBlock &ub,
+                        QDuplicateTracker<int, 256> *activeUniformLocations, QGles2UniformDescriptionVector *dst);
+    void gatherSamplers(GLuint program, const QShaderDescription::InOutVariable &v,
+                        QGles2SamplerDescriptionVector *dst);
+    void gatherGeneratedSamplers(GLuint program,
+                                 const QShader::SeparateToCombinedImageSamplerMapping &mapping,
+                                 QGles2SamplerDescriptionVector *dst);
+    void sanityCheckVertexFragmentInterface(const QShaderDescription &vsDesc, const QShaderDescription &fsDesc);
+    bool isProgramBinaryDiskCacheEnabled() const;
+
+    enum ProgramCacheResult {
+        ProgramCacheHit,
+        ProgramCacheMiss,
+        ProgramCacheError
+    };
+    ProgramCacheResult tryLoadFromDiskOrPipelineCache(const QRhiShaderStage *stages,
+                                                      int stageCount,
+                                                      GLuint program,
+                                                      const QVector<QShaderDescription::InOutVariable> &inputVars,
+                                                      QByteArray *cacheKey);
+    void trySaveToDiskCache(GLuint program, const QByteArray &cacheKey);
+    void trySaveToPipelineCache(GLuint program, const QByteArray &cacheKey, bool force = false);
+
+    QRhi::Flags rhiFlags;
+    QOpenGLContext *ctx = nullptr;
+    bool importedContext = false;
+    QSurfaceFormat requestedFormat;
+    QSurface *fallbackSurface = nullptr;
+    QPointer<QWindow> maybeWindow = nullptr;
+    QOpenGLContext *maybeShareContext = nullptr;
+    mutable bool needsMakeCurrentDueToSwap = false;
+    QOpenGLExtensions *f = nullptr;
+    void (QOPENGLF_APIENTRYP glPolygonMode) (GLenum, GLenum) = nullptr;
+    void(QOPENGLF_APIENTRYP glTexImage1D)(GLenum, GLint, GLint, GLsizei, GLint, GLenum, GLenum,
+                                          const void *) = nullptr;
+    void(QOPENGLF_APIENTRYP glTexStorage1D)(GLenum, GLint, GLenum, GLsizei) = nullptr;
+    void(QOPENGLF_APIENTRYP glTexSubImage1D)(GLenum, GLint, GLint, GLsizei, GLenum, GLenum,
+                                             const GLvoid *) = nullptr;
+    void(QOPENGLF_APIENTRYP glCopyTexSubImage1D)(GLenum, GLint, GLint, GLint, GLint,
+                                                 GLsizei) = nullptr;
+    void(QOPENGLF_APIENTRYP glCompressedTexImage1D)(GLenum, GLint, GLenum, GLsizei, GLint, GLsizei,
+                                                    const GLvoid *) = nullptr;
+    void(QOPENGLF_APIENTRYP glCompressedTexSubImage1D)(GLenum, GLint, GLint, GLsizei, GLenum,
+                                                       GLsizei, const GLvoid *) = nullptr;
+    void(QOPENGLF_APIENTRYP glFramebufferTexture1D)(GLenum, GLenum, GLenum, GLuint,
+                                                    GLint) = nullptr;
+
+    uint vao = 0;
+    struct Caps {
+        Caps()
+            : ctxMajor(2),
+              ctxMinor(0),
+              maxTextureSize(2048),
+              maxDrawBuffers(4),
+              maxSamples(16),
+              maxTextureArraySize(0),
+              maxThreadGroupsPerDimension(0),
+              maxThreadsPerThreadGroup(0),
+              maxThreadGroupsX(0),
+              maxThreadGroupsY(0),
+              maxThreadGroupsZ(0),
+              maxUniformVectors(4096),
+              maxVertexInputs(8),
+              maxVertexOutputs(8),
+              msaaRenderBuffer(false),
+              multisampledTexture(false),
+              npotTextureFull(true),
+              gles(false),
+              fixedIndexPrimitiveRestart(false),
+              bgraExternalFormat(false),
+              bgraInternalFormat(false),
+              r8Format(false),
+              r16Format(false),
+              floatFormats(false),
+              rgb10Formats(false),
+              depthTexture(false),
+              packedDepthStencil(false),
+              needsDepthStencilCombinedAttach(false),
+              srgbCapableDefaultFramebuffer(false),
+              coreProfile(false),
+              uniformBuffers(false),
+              elementIndexUint(false),
+              depth24(false),
+              rgba8Format(false),
+              instancing(false),
+              baseVertex(false),
+              compute(false),
+              textureCompareMode(false),
+              properMapBuffer(false),
+              nonBaseLevelFramebufferTexture(false),
+              texelFetch(false),
+              intAttributes(true),
+              screenSpaceDerivatives(false),
+              programBinary(false),
+              texture3D(false),
+              tessellation(false),
+              geometryShader(false),
+              texture1D(false),
+              hasDrawBuffersFunc(false),
+              halfAttributes(false)
+        { }
+        int ctxMajor;
+        int ctxMinor;
+        int maxTextureSize;
+        int maxDrawBuffers;
+        int maxSamples;
+        int maxTextureArraySize;
+        int maxThreadGroupsPerDimension;
+        int maxThreadsPerThreadGroup;
+        int maxThreadGroupsX;
+        int maxThreadGroupsY;
+        int maxThreadGroupsZ;
+        int maxUniformVectors;
+        int maxVertexInputs;
+        int maxVertexOutputs;
+        // Multisample fb and blit are supported (GLES 3.0 or OpenGL 3.x). Not
+        // the same as multisample textures!
+        uint msaaRenderBuffer : 1;
+        uint multisampledTexture : 1;
+        uint npotTextureFull : 1;
+        uint gles : 1;
+        uint fixedIndexPrimitiveRestart : 1;
+        uint bgraExternalFormat : 1;
+        uint bgraInternalFormat : 1;
+        uint r8Format : 1;
+        uint r16Format : 1;
+        uint floatFormats : 1;
+        uint rgb10Formats : 1;
+        uint depthTexture : 1;
+        uint packedDepthStencil : 1;
+        uint needsDepthStencilCombinedAttach : 1;
+        uint srgbCapableDefaultFramebuffer : 1;
+        uint coreProfile : 1;
+        uint uniformBuffers : 1;
+        uint elementIndexUint : 1;
+        uint depth24 : 1;
+        uint rgba8Format : 1;
+        uint instancing : 1;
+        uint baseVertex : 1;
+        uint compute : 1;
+        uint textureCompareMode : 1;
+        uint properMapBuffer : 1;
+        uint nonBaseLevelFramebufferTexture : 1;
+        uint texelFetch : 1;
+        uint intAttributes : 1;
+        uint screenSpaceDerivatives : 1;
+        uint programBinary : 1;
+        uint texture3D : 1;
+        uint tessellation : 1;
+        uint geometryShader : 1;
+        uint texture1D : 1;
+        uint hasDrawBuffersFunc : 1;
+        uint halfAttributes : 1;
+    } caps;
+    QGles2SwapChain *currentSwapChain = nullptr;
+    QSet<GLint> supportedCompressedFormats;
+    mutable QList<int> supportedSampleCountList;
+    QRhiGles2NativeHandles nativeHandlesStruct;
+    QRhiDriverInfo driverInfoStruct;
+    mutable bool contextLost = false;
+
+    struct DeferredReleaseEntry {
+        enum Type {
+            Buffer,
+            Pipeline,
+            Texture,
+            RenderBuffer,
+            TextureRenderTarget
+        };
+        Type type;
+        union {
+            struct {
+                GLuint buffer;
+            } buffer;
+            struct {
+                GLuint program;
+            } pipeline;
+            struct {
+                GLuint texture;
+            } texture;
+            struct {
+                GLuint renderbuffer;
+                GLuint renderbuffer2;
+            } renderbuffer;
+            struct {
+                GLuint framebuffer;
+            } textureRenderTarget;
+        };
+    };
+    QList<DeferredReleaseEntry> releaseQueue;
+
+    struct OffscreenFrame {
+        OffscreenFrame(QRhiImplementation *rhi) : cbWrapper(rhi) { }
+        bool active = false;
+        QGles2CommandBuffer cbWrapper;
+    } ofr;
+
+    QHash<QRhiShaderStage, uint> m_shaderCache;
+
+    struct PipelineCacheData {
+        quint32 format;
+        QByteArray data;
+    };
+    QHash<QByteArray, PipelineCacheData> m_pipelineCache;
+};
+
+Q_DECLARE_TYPEINFO(QRhiGles2::DeferredReleaseEntry, Q_RELOCATABLE_TYPE);
+
 QT_END_NAMESPACE
 
 #endif
diff --git a/src/gui/rhi/qrhigles2_p_p.h b/src/gui/rhi/qrhigles2_p_p.h
deleted file mode 100644
index f4cf7b98b6..0000000000
--- a/src/gui/rhi/qrhigles2_p_p.h
+++ /dev/null
@@ -1,1077 +0,0 @@
-// Copyright (C) 2019 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
-
-#ifndef QRHIGLES2_P_H
-#define QRHIGLES2_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists purely as an
-// implementation detail.  This header file may change from version to
-// version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qrhigles2_p.h"
-#include "qrhi_p_p.h"
-#include "qshaderdescription_p.h"
-#include <qopengl.h>
-#include <QByteArray>
-#include <QWindow>
-#include <QPointer>
-#include <QtCore/private/qduplicatetracker_p.h>
-#include <optional>
-
-QT_BEGIN_NAMESPACE
-
-class QOpenGLExtensions;
-
-struct QGles2Buffer : public QRhiBuffer
-{
-    QGles2Buffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
-    ~QGles2Buffer();
-    void destroy() override;
-    bool create() override;
-    QRhiBuffer::NativeBuffer nativeBuffer() override;
-    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
-    void endFullDynamicBufferUpdateForCurrentFrame() override;
-
-    quint32 nonZeroSize = 0;
-    GLuint buffer = 0;
-    GLenum targetForDataOps;
-    QByteArray data;
-    enum Access {
-        AccessNone,
-        AccessVertex,
-        AccessIndex,
-        AccessUniform,
-        AccessStorageRead,
-        AccessStorageWrite,
-        AccessStorageReadWrite,
-        AccessUpdate
-    };
-    struct UsageState {
-        Access access;
-    };
-    UsageState usageState;
-    friend class QRhiGles2;
-};
-
-struct QGles2RenderBuffer : public QRhiRenderBuffer
-{
-    QGles2RenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
-                       int sampleCount, QRhiRenderBuffer::Flags flags,
-                       QRhiTexture::Format backingFormatHint);
-    ~QGles2RenderBuffer();
-    void destroy() override;
-    bool create() override;
-    bool createFrom(NativeRenderBuffer src) override;
-    QRhiTexture::Format backingFormat() const override;
-
-    GLuint renderbuffer = 0;
-    GLuint stencilRenderbuffer = 0; // when packed depth-stencil not supported
-    int samples;
-    bool owns = true;
-    uint generation = 0;
-    friend class QRhiGles2;
-};
-
-struct QGles2SamplerData
-{
-    GLenum glminfilter = 0;
-    GLenum glmagfilter = 0;
-    GLenum glwraps = 0;
-    GLenum glwrapt = 0;
-    GLenum glwrapr = 0;
-    GLenum gltexcomparefunc = 0;
-};
-
-inline bool operator==(const QGles2SamplerData &a, const QGles2SamplerData &b)
-{
-    return a.glminfilter == b.glminfilter
-            && a.glmagfilter == b.glmagfilter
-            && a.glwraps == b.glwraps
-            && a.glwrapt == b.glwrapt
-            && a.glwrapr == b.glwrapr
-            && a.gltexcomparefunc == b.gltexcomparefunc;
-}
-
-inline bool operator!=(const QGles2SamplerData &a, const QGles2SamplerData &b)
-{
-    return !(a == b);
-}
-
-struct QGles2Texture : public QRhiTexture
-{
-    QGles2Texture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
-                  int arraySize, int sampleCount, Flags flags);
-    ~QGles2Texture();
-    void destroy() override;
-    bool create() override;
-    bool createFrom(NativeTexture src) override;
-    NativeTexture nativeTexture() override;
-
-    bool prepareCreate(QSize *adjustedSize = nullptr);
-
-    GLuint texture = 0;
-    bool owns = true;
-    GLenum target;
-    GLenum glintformat;
-    GLenum glsizedintformat;
-    GLenum glformat;
-    GLenum gltype;
-    QGles2SamplerData samplerState;
-    bool specified = false;
-    bool zeroInitialized = false;
-    int mipLevelCount = 0;
-
-    enum Access {
-        AccessNone,
-        AccessSample,
-        AccessFramebuffer,
-        AccessStorageRead,
-        AccessStorageWrite,
-        AccessStorageReadWrite,
-        AccessUpdate,
-        AccessRead
-    };
-    struct UsageState {
-        Access access;
-    };
-    UsageState usageState;
-
-    uint generation = 0;
-    friend class QRhiGles2;
-};
-
-struct QGles2Sampler : public QRhiSampler
-{
-    QGles2Sampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
-                  AddressMode u, AddressMode v, AddressMode w);
-    ~QGles2Sampler();
-    void destroy() override;
-    bool create() override;
-
-    QGles2SamplerData d;
-    uint generation = 0;
-    friend class QRhiGles2;
-};
-
-struct QGles2RenderPassDescriptor : public QRhiRenderPassDescriptor
-{
-    QGles2RenderPassDescriptor(QRhiImplementation *rhi);
-    ~QGles2RenderPassDescriptor();
-    void destroy() override;
-    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
-    QVector<quint32> serializedFormat() const override;
-};
-
-struct QGles2RenderTargetData
-{
-    QGles2RenderTargetData(QRhiImplementation *) { }
-
-    bool isValid() const { return rp != nullptr; }
-
-    QGles2RenderPassDescriptor *rp = nullptr;
-    QSize pixelSize;
-    float dpr = 1;
-    int sampleCount = 1;
-    int colorAttCount = 0;
-    int dsAttCount = 0;
-    bool srgbUpdateAndBlend = false;
-    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
-    std::optional<QRhiSwapChain::StereoTargetBuffer> stereoTarget;
-};
-
-struct QGles2SwapChainRenderTarget : public QRhiSwapChainRenderTarget
-{
-    QGles2SwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
-    ~QGles2SwapChainRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QGles2RenderTargetData d;
-};
-
-struct QGles2TextureRenderTarget : public QRhiTextureRenderTarget
-{
-    QGles2TextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
-    ~QGles2TextureRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool create() override;
-
-    QGles2RenderTargetData d;
-    GLuint framebuffer = 0;
-    friend class QRhiGles2;
-};
-
-struct QGles2ShaderResourceBindings : public QRhiShaderResourceBindings
-{
-    QGles2ShaderResourceBindings(QRhiImplementation *rhi);
-    ~QGles2ShaderResourceBindings();
-    void destroy() override;
-    bool create() override;
-    void updateResources(UpdateFlags flags) override;
-
-    bool hasDynamicOffset = false;
-    uint generation = 0;
-    friend class QRhiGles2;
-};
-
-struct QGles2UniformDescription
-{
-    QShaderDescription::VariableType type;
-    int glslLocation;
-    int binding;
-    quint32 offset;
-    quint32 size;
-    int arrayDim;
-};
-
-Q_DECLARE_TYPEINFO(QGles2UniformDescription, Q_RELOCATABLE_TYPE);
-
-struct QGles2SamplerDescription
-{
-    int glslLocation;
-    int combinedBinding;
-    int tbinding;
-    int sbinding;
-};
-
-Q_DECLARE_TYPEINFO(QGles2SamplerDescription, Q_RELOCATABLE_TYPE);
-
-using QGles2UniformDescriptionVector = QVarLengthArray<QGles2UniformDescription, 8>;
-using QGles2SamplerDescriptionVector = QVarLengthArray<QGles2SamplerDescription, 4>;
-
-struct QGles2UniformState
-{
-    static constexpr int MAX_TRACKED_LOCATION = 1023;
-    int componentCount;
-    float v[4];
-};
-
-struct QGles2GraphicsPipeline : public QRhiGraphicsPipeline
-{
-    QGles2GraphicsPipeline(QRhiImplementation *rhi);
-    ~QGles2GraphicsPipeline();
-    void destroy() override;
-    bool create() override;
-
-    GLuint program = 0;
-    GLenum drawMode = GL_TRIANGLES;
-    QGles2UniformDescriptionVector uniforms;
-    QGles2SamplerDescriptionVector samplers;
-    QGles2UniformState uniformState[QGles2UniformState::MAX_TRACKED_LOCATION + 1];
-    QRhiShaderResourceBindings *currentSrb = nullptr;
-    uint currentSrbGeneration = 0;
-    uint generation = 0;
-    friend class QRhiGles2;
-};
-
-struct QGles2ComputePipeline : public QRhiComputePipeline
-{
-    QGles2ComputePipeline(QRhiImplementation *rhi);
-    ~QGles2ComputePipeline();
-    void destroy() override;
-    bool create() override;
-
-    GLuint program = 0;
-    QGles2UniformDescriptionVector uniforms;
-    QGles2SamplerDescriptionVector samplers;
-    QGles2UniformState uniformState[QGles2UniformState::MAX_TRACKED_LOCATION + 1];
-    QRhiShaderResourceBindings *currentSrb = nullptr;
-    uint currentSrbGeneration = 0;
-    uint generation = 0;
-    friend class QRhiGles2;
-};
-
-struct QGles2CommandBuffer : public QRhiCommandBuffer
-{
-    QGles2CommandBuffer(QRhiImplementation *rhi);
-    ~QGles2CommandBuffer();
-    void destroy() override;
-
-    // keep at a reasonably low value otherwise sizeof Command explodes
-    static const int MAX_DYNAMIC_OFFSET_COUNT = 8;
-
-    struct Command {
-        enum Cmd {
-            BeginFrame,
-            EndFrame,
-            ResetFrame,
-            Viewport,
-            Scissor,
-            BlendConstants,
-            StencilRef,
-            BindVertexBuffer,
-            BindIndexBuffer,
-            Draw,
-            DrawIndexed,
-            BindGraphicsPipeline,
-            BindShaderResources,
-            BindFramebuffer,
-            Clear,
-            BufferSubData,
-            GetBufferSubData,
-            CopyTex,
-            ReadPixels,
-            SubImage,
-            CompressedImage,
-            CompressedSubImage,
-            BlitFromRenderbuffer,
-            GenMip,
-            BindComputePipeline,
-            Dispatch,
-            BarriersForPass,
-            Barrier
-        };
-        Cmd cmd;
-
-        // QRhi*/QGles2* references should be kept at minimum (so no
-        // QRhiTexture/Buffer/etc. pointers).
-        union Args {
-            struct {
-                float x, y, w, h;
-                float d0, d1;
-            } viewport;
-            struct {
-                int x, y, w, h;
-            } scissor;
-            struct {
-                float r, g, b, a;
-            } blendConstants;
-            struct {
-                quint32 ref;
-                QRhiGraphicsPipeline *ps;
-            } stencilRef;
-            struct {
-                QRhiGraphicsPipeline *ps;
-                GLuint buffer;
-                quint32 offset;
-                int binding;
-            } bindVertexBuffer;
-            struct {
-                GLuint buffer;
-                quint32 offset;
-                GLenum type;
-            } bindIndexBuffer;
-            struct {
-                QRhiGraphicsPipeline *ps;
-                quint32 vertexCount;
-                quint32 firstVertex;
-                quint32 instanceCount;
-                quint32 baseInstance;
-            } draw;
-            struct {
-                QRhiGraphicsPipeline *ps;
-                quint32 indexCount;
-                quint32 firstIndex;
-                quint32 instanceCount;
-                quint32 baseInstance;
-                qint32 baseVertex;
-            } drawIndexed;
-            struct {
-                QRhiGraphicsPipeline *ps;
-            } bindGraphicsPipeline;
-            struct {
-                QRhiGraphicsPipeline *maybeGraphicsPs;
-                QRhiComputePipeline *maybeComputePs;
-                QRhiShaderResourceBindings *srb;
-                int dynamicOffsetCount;
-                uint dynamicOffsetPairs[MAX_DYNAMIC_OFFSET_COUNT * 2]; // binding, offset
-            } bindShaderResources;
-            struct {
-                GLbitfield mask;
-                float c[4];
-                float d;
-                quint32 s;
-            } clear;
-            struct {
-                GLuint fbo;
-                bool srgb;
-                int colorAttCount;
-                bool stereo;
-                QRhiSwapChain::StereoTargetBuffer stereoTarget;
-            } bindFramebuffer;
-            struct {
-                GLenum target;
-                GLuint buffer;
-                int offset;
-                int size;
-                const void *data; // must come from retainData()
-            } bufferSubData;
-            struct {
-                QRhiReadbackResult *result;
-                GLenum target;
-                GLuint buffer;
-                int offset;
-                int size;
-            } getBufferSubData;
-            struct {
-                GLenum srcTarget;
-                GLenum srcFaceTarget;
-                GLuint srcTexture;
-                int srcLevel;
-                int srcX;
-                int srcY;
-                int srcZ;
-                GLenum dstTarget;
-                GLuint dstTexture;
-                GLenum dstFaceTarget;
-                int dstLevel;
-                int dstX;
-                int dstY;
-                int dstZ;
-                int w;
-                int h;
-            } copyTex;
-            struct {
-                QRhiReadbackResult *result;
-                GLuint texture;
-                int w;
-                int h;
-                QRhiTexture::Format format;
-                GLenum readTarget;
-                int level;
-                int slice3D;
-            } readPixels;
-            struct {
-                GLenum target;
-                GLuint texture;
-                GLenum faceTarget;
-                int level;
-                int dx;
-                int dy;
-                int dz;
-                int w;
-                int h;
-                GLenum glformat;
-                GLenum gltype;
-                int rowStartAlign;
-                int rowLength;
-                const void *data; // must come from retainImage()
-            } subImage;
-            struct {
-                GLenum target;
-                GLuint texture;
-                GLenum faceTarget;
-                int level;
-                GLenum glintformat;
-                int w;
-                int h;
-                int depth;
-                int size;
-                const void *data; // must come from retainData()
-            } compressedImage;
-            struct {
-                GLenum target;
-                GLuint texture;
-                GLenum faceTarget;
-                int level;
-                int dx;
-                int dy;
-                int dz;
-                int w;
-                int h;
-                GLenum glintformat;
-                int size;
-                const void *data; // must come from retainData()
-            } compressedSubImage;
-            struct {
-                GLuint renderbuffer;
-                int w;
-                int h;
-                GLenum target;
-                GLuint texture;
-                int dstLevel;
-                int dstLayer;
-            } blitFromRb;
-            struct {
-                GLenum target;
-                GLuint texture;
-            } genMip;
-            struct {
-                QRhiComputePipeline *ps;
-            } bindComputePipeline;
-            struct {
-                GLuint x;
-                GLuint y;
-                GLuint z;
-            } dispatch;
-            struct {
-                int trackerIndex;
-            } barriersForPass;
-            struct {
-                GLbitfield barriers;
-            } barrier;
-        } args;
-    };
-
-    enum PassType {
-        NoPass,
-        RenderPass,
-        ComputePass
-    };
-
-    QRhiBackendCommandList<Command> commands;
-    QVarLengthArray<QRhiPassResourceTracker, 8> passResTrackers;
-    int currentPassResTrackerIndex;
-
-    PassType recordingPass;
-    bool passNeedsResourceTracking;
-    QRhiRenderTarget *currentTarget;
-    QRhiGraphicsPipeline *currentGraphicsPipeline;
-    QRhiComputePipeline *currentComputePipeline;
-    uint currentPipelineGeneration;
-    QRhiShaderResourceBindings *currentGraphicsSrb;
-    QRhiShaderResourceBindings *currentComputeSrb;
-    uint currentSrbGeneration;
-
-    struct GraphicsPassState {
-        bool valid = false;
-        bool scissor;
-        bool cullFace;
-        GLenum cullMode;
-        GLenum frontFace;
-        bool blendEnabled;
-        struct ColorMask { bool r, g, b, a; } colorMask;
-        struct Blend {
-            GLenum srcColor;
-            GLenum dstColor;
-            GLenum srcAlpha;
-            GLenum dstAlpha;
-            GLenum opColor;
-            GLenum opAlpha;
-        } blend;
-        bool depthTest;
-        bool depthWrite;
-        GLenum depthFunc;
-        bool stencilTest;
-        GLuint stencilReadMask;
-        GLuint stencilWriteMask;
-        struct StencilFace {
-            GLenum func;
-            GLenum failOp;
-            GLenum zfailOp;
-            GLenum zpassOp;
-        } stencil[2]; // front, back
-        bool polyOffsetFill;
-        float polyOffsetFactor;
-        float polyOffsetUnits;
-        float lineWidth;
-        int cpCount;
-        GLenum polygonMode;
-        void reset() { valid = false; }
-        struct {
-            // not part of QRhiGraphicsPipeline but used by setGraphicsPipeline()
-            GLint stencilRef = 0;
-        } dynamic;
-    } graphicsPassState;
-
-    struct ComputePassState {
-        enum Access {
-            Read = 0x01,
-            Write = 0x02
-        };
-        QHash<QRhiResource *, QPair<int, bool> > writtenResources;
-        void reset() {
-            writtenResources.clear();
-        }
-    } computePassState;
-
-    struct TextureUnitState {
-        void *ps;
-        uint psGeneration;
-        uint texture;
-    } textureUnitState[16];
-
-    QVarLengthArray<QByteArray, 4> dataRetainPool;
-    QVarLengthArray<QRhiBufferData, 4> bufferDataRetainPool;
-    QVarLengthArray<QImage, 4> imageRetainPool;
-
-    // relies heavily on implicit sharing (no copies of the actual data will be made)
-    const void *retainData(const QByteArray &data) {
-        dataRetainPool.append(data);
-        return dataRetainPool.last().constData();
-    }
-    const uchar *retainBufferData(const QRhiBufferData &data) {
-        bufferDataRetainPool.append(data);
-        return reinterpret_cast<const uchar *>(bufferDataRetainPool.last().constData());
-    }
-    const void *retainImage(const QImage &image) {
-        imageRetainPool.append(image);
-        return imageRetainPool.last().constBits();
-    }
-    void resetCommands() {
-        commands.reset();
-        dataRetainPool.clear();
-        bufferDataRetainPool.clear();
-        imageRetainPool.clear();
-
-        passResTrackers.clear();
-        currentPassResTrackerIndex = -1;
-    }
-    void resetState() {
-        recordingPass = NoPass;
-        passNeedsResourceTracking = true;
-        currentTarget = nullptr;
-        resetCommands();
-        resetCachedState();
-    }
-    void resetCachedState() {
-        currentGraphicsPipeline = nullptr;
-        currentComputePipeline = nullptr;
-        currentPipelineGeneration = 0;
-        currentGraphicsSrb = nullptr;
-        currentComputeSrb = nullptr;
-        currentSrbGeneration = 0;
-        graphicsPassState.reset();
-        computePassState.reset();
-        memset(textureUnitState, 0, sizeof(textureUnitState));
-    }
-};
-
-inline bool operator==(const QGles2CommandBuffer::GraphicsPassState::StencilFace &a,
-                       const QGles2CommandBuffer::GraphicsPassState::StencilFace &b)
-{
-    return a.func == b.func
-            && a.failOp == b.failOp
-            && a.zfailOp == b.zfailOp
-            && a.zpassOp == b.zpassOp;
-}
-
-inline bool operator!=(const QGles2CommandBuffer::GraphicsPassState::StencilFace &a,
-                       const QGles2CommandBuffer::GraphicsPassState::StencilFace &b)
-{
-    return !(a == b);
-}
-
-inline bool operator==(const QGles2CommandBuffer::GraphicsPassState::ColorMask &a,
-                       const QGles2CommandBuffer::GraphicsPassState::ColorMask &b)
-{
-    return a.r == b.r && a.g == b.g && a.b == b.b && a.a == b.a;
-}
-
-inline bool operator!=(const QGles2CommandBuffer::GraphicsPassState::ColorMask &a,
-                       const QGles2CommandBuffer::GraphicsPassState::ColorMask &b)
-{
-    return !(a == b);
-}
-
-inline bool operator==(const QGles2CommandBuffer::GraphicsPassState::Blend &a,
-                       const QGles2CommandBuffer::GraphicsPassState::Blend &b)
-{
-    return a.srcColor == b.srcColor
-            && a.dstColor == b.dstColor
-            && a.srcAlpha == b.srcAlpha
-            && a.dstAlpha == b.dstAlpha
-            && a.opColor == b.opColor
-            && a.opAlpha == b.opAlpha;
-}
-
-inline bool operator!=(const QGles2CommandBuffer::GraphicsPassState::Blend &a,
-                       const QGles2CommandBuffer::GraphicsPassState::Blend &b)
-{
-    return !(a == b);
-}
-
-struct QGles2SwapChain : public QRhiSwapChain
-{
-    QGles2SwapChain(QRhiImplementation *rhi);
-    ~QGles2SwapChain();
-    void destroy() override;
-
-    QRhiCommandBuffer *currentFrameCommandBuffer() override;
-    QRhiRenderTarget *currentFrameRenderTarget() override;
-    QRhiRenderTarget *currentFrameRenderTarget(StereoTargetBuffer targetBuffer) override;
-
-    QSize surfacePixelSize() override;
-    bool isFormatSupported(Format f) override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool createOrResize() override;
-
-    void initSwapChainRenderTarget(QGles2SwapChainRenderTarget *rt);
-
-    QSurface *surface = nullptr;
-    QSize pixelSize;
-    QGles2SwapChainRenderTarget rt;
-    QGles2SwapChainRenderTarget rtLeft;
-    QGles2SwapChainRenderTarget rtRight;
-    QGles2CommandBuffer cb;
-    int frameCount = 0;
-};
-
-class QRhiGles2 : public QRhiImplementation
-{
-public:
-    QRhiGles2(QRhiGles2InitParams *params, QRhiGles2NativeHandles *importDevice = nullptr);
-
-    bool create(QRhi::Flags flags) override;
-    void destroy() override;
-
-    QRhiGraphicsPipeline *createGraphicsPipeline() override;
-    QRhiComputePipeline *createComputePipeline() override;
-    QRhiShaderResourceBindings *createShaderResourceBindings() override;
-    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
-                             QRhiBuffer::UsageFlags usage,
-                             quint32 size) override;
-    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
-                                         const QSize &pixelSize,
-                                         int sampleCount,
-                                         QRhiRenderBuffer::Flags flags,
-                                         QRhiTexture::Format backingFormatHint) override;
-    QRhiTexture *createTexture(QRhiTexture::Format format,
-                               const QSize &pixelSize,
-                               int depth,
-                               int arraySize,
-                               int sampleCount,
-                               QRhiTexture::Flags flags) override;
-    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
-                               QRhiSampler::Filter minFilter,
-                               QRhiSampler::Filter mipmapMode,
-                               QRhiSampler:: AddressMode u,
-                               QRhiSampler::AddressMode v,
-                               QRhiSampler::AddressMode w) override;
-
-    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
-                                                       QRhiTextureRenderTarget::Flags flags) override;
-
-    QRhiSwapChain *createSwapChain() override;
-    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult finish() override;
-
-    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void beginPass(QRhiCommandBuffer *cb,
-                   QRhiRenderTarget *rt,
-                   const QColor &colorClearValue,
-                   const QRhiDepthStencilClearValue &depthStencilClearValue,
-                   QRhiResourceUpdateBatch *resourceUpdates,
-                   QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void setGraphicsPipeline(QRhiCommandBuffer *cb,
-                             QRhiGraphicsPipeline *ps) override;
-
-    void setShaderResources(QRhiCommandBuffer *cb,
-                            QRhiShaderResourceBindings *srb,
-                            int dynamicOffsetCount,
-                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
-
-    void setVertexInput(QRhiCommandBuffer *cb,
-                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
-                        QRhiBuffer *indexBuf, quint32 indexOffset,
-                        QRhiCommandBuffer::IndexFormat indexFormat) override;
-
-    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
-    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
-    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
-    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
-
-    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
-              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
-
-    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
-                     quint32 instanceCount, quint32 firstIndex,
-                     qint32 vertexOffset, quint32 firstInstance) override;
-
-    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
-    void debugMarkEnd(QRhiCommandBuffer *cb) override;
-    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
-
-    void beginComputePass(QRhiCommandBuffer *cb,
-                          QRhiResourceUpdateBatch *resourceUpdates,
-                          QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
-    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
-
-    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
-    void beginExternal(QRhiCommandBuffer *cb) override;
-    void endExternal(QRhiCommandBuffer *cb) override;
-    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
-
-    QList<int> supportedSampleCounts() const override;
-    int ubufAlignment() const override;
-    bool isYUpInFramebuffer() const override;
-    bool isYUpInNDC() const override;
-    bool isClipDepthZeroToOne() const override;
-    QMatrix4x4 clipSpaceCorrMatrix() const override;
-    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
-    bool isFeatureSupported(QRhi::Feature feature) const override;
-    int resourceLimit(QRhi::ResourceLimit limit) const override;
-    const QRhiNativeHandles *nativeHandles() override;
-    QRhiDriverInfo driverInfo() const override;
-    QRhiStats statistics() override;
-    bool makeThreadLocalNativeContextCurrent() override;
-    void releaseCachedResources() override;
-    bool isDeviceLost() const override;
-
-    QByteArray pipelineCacheData() override;
-    void setPipelineCacheData(const QByteArray &data) override;
-
-    bool ensureContext(QSurface *surface = nullptr) const;
-    QSurface *evaluateFallbackSurface() const;
-    void executeDeferredReleases();
-    void trackedBufferBarrier(QGles2CommandBuffer *cbD, QGles2Buffer *bufD, QGles2Buffer::Access access);
-    void trackedImageBarrier(QGles2CommandBuffer *cbD, QGles2Texture *texD, QGles2Texture::Access access);
-    void enqueueSubresUpload(QGles2Texture *texD, QGles2CommandBuffer *cbD,
-                             int layer, int level, const QRhiTextureSubresourceUploadDescription &subresDesc);
-    void enqueueResourceUpdates(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates);
-    void trackedRegisterBuffer(QRhiPassResourceTracker *passResTracker,
-                               QGles2Buffer *bufD,
-                               QRhiPassResourceTracker::BufferAccess access,
-                               QRhiPassResourceTracker::BufferStage stage);
-    void trackedRegisterTexture(QRhiPassResourceTracker *passResTracker,
-                                QGles2Texture *texD,
-                                QRhiPassResourceTracker::TextureAccess access,
-                                QRhiPassResourceTracker::TextureStage stage);
-    void executeCommandBuffer(QRhiCommandBuffer *cb);
-    void executeBindGraphicsPipeline(QGles2CommandBuffer *cbD, QGles2GraphicsPipeline *psD);
-    void bindCombinedSampler(QGles2CommandBuffer *cbD, QGles2Texture *texD, QGles2Sampler *samplerD,
-                             void *ps, uint psGeneration, int glslLocation,
-                             int *texUnit, bool *activeTexUnitAltered);
-    void bindShaderResources(QGles2CommandBuffer *cbD,
-                             QRhiGraphicsPipeline *maybeGraphicsPs, QRhiComputePipeline *maybeComputePs,
-                             QRhiShaderResourceBindings *srb,
-                             const uint *dynOfsPairs, int dynOfsCount);
-    QGles2RenderTargetData *enqueueBindFramebuffer(QRhiRenderTarget *rt, QGles2CommandBuffer *cbD,
-                                                   bool *wantsColorClear = nullptr, bool *wantsDsClear = nullptr);
-    void enqueueBarriersForPass(QGles2CommandBuffer *cbD);
-    int effectiveSampleCount(int sampleCount) const;
-    QByteArray shaderSource(const QRhiShaderStage &shaderStage, QShaderVersion *shaderVersion);
-    bool compileShader(GLuint program, const QRhiShaderStage &shaderStage, QShaderVersion *shaderVersion);
-    bool linkProgram(GLuint program);
-    void registerUniformIfActive(const QShaderDescription::BlockVariable &var,
-                                 const QByteArray &namePrefix, int binding, int baseOffset,
-                                 GLuint program,
-                                 QDuplicateTracker<int, 256> *activeUniformLocations,
-                                 QGles2UniformDescriptionVector *dst);
-    void gatherUniforms(GLuint program, const QShaderDescription::UniformBlock &ub,
-                        QDuplicateTracker<int, 256> *activeUniformLocations, QGles2UniformDescriptionVector *dst);
-    void gatherSamplers(GLuint program, const QShaderDescription::InOutVariable &v,
-                        QGles2SamplerDescriptionVector *dst);
-    void gatherGeneratedSamplers(GLuint program,
-                                 const QShader::SeparateToCombinedImageSamplerMapping &mapping,
-                                 QGles2SamplerDescriptionVector *dst);
-    void sanityCheckVertexFragmentInterface(const QShaderDescription &vsDesc, const QShaderDescription &fsDesc);
-    bool isProgramBinaryDiskCacheEnabled() const;
-
-    enum ProgramCacheResult {
-        ProgramCacheHit,
-        ProgramCacheMiss,
-        ProgramCacheError
-    };
-    ProgramCacheResult tryLoadFromDiskOrPipelineCache(const QRhiShaderStage *stages,
-                                                      int stageCount,
-                                                      GLuint program,
-                                                      const QVector<QShaderDescription::InOutVariable> &inputVars,
-                                                      QByteArray *cacheKey);
-    void trySaveToDiskCache(GLuint program, const QByteArray &cacheKey);
-    void trySaveToPipelineCache(GLuint program, const QByteArray &cacheKey, bool force = false);
-
-    QRhi::Flags rhiFlags;
-    QOpenGLContext *ctx = nullptr;
-    bool importedContext = false;
-    QSurfaceFormat requestedFormat;
-    QSurface *fallbackSurface = nullptr;
-    QPointer<QWindow> maybeWindow = nullptr;
-    QOpenGLContext *maybeShareContext = nullptr;
-    mutable bool needsMakeCurrentDueToSwap = false;
-    QOpenGLExtensions *f = nullptr;
-    void (QOPENGLF_APIENTRYP glPolygonMode) (GLenum, GLenum) = nullptr;
-    void(QOPENGLF_APIENTRYP glTexImage1D)(GLenum, GLint, GLint, GLsizei, GLint, GLenum, GLenum,
-                                          const void *) = nullptr;
-    void(QOPENGLF_APIENTRYP glTexStorage1D)(GLenum, GLint, GLenum, GLsizei) = nullptr;
-    void(QOPENGLF_APIENTRYP glTexSubImage1D)(GLenum, GLint, GLint, GLsizei, GLenum, GLenum,
-                                             const GLvoid *) = nullptr;
-    void(QOPENGLF_APIENTRYP glCopyTexSubImage1D)(GLenum, GLint, GLint, GLint, GLint,
-                                                 GLsizei) = nullptr;
-    void(QOPENGLF_APIENTRYP glCompressedTexImage1D)(GLenum, GLint, GLenum, GLsizei, GLint, GLsizei,
-                                                    const GLvoid *) = nullptr;
-    void(QOPENGLF_APIENTRYP glCompressedTexSubImage1D)(GLenum, GLint, GLint, GLsizei, GLenum,
-                                                       GLsizei, const GLvoid *) = nullptr;
-    void(QOPENGLF_APIENTRYP glFramebufferTexture1D)(GLenum, GLenum, GLenum, GLuint,
-                                                    GLint) = nullptr;
-
-    uint vao = 0;
-    struct Caps {
-        Caps()
-            : ctxMajor(2),
-              ctxMinor(0),
-              maxTextureSize(2048),
-              maxDrawBuffers(4),
-              maxSamples(16),
-              maxTextureArraySize(0),
-              maxThreadGroupsPerDimension(0),
-              maxThreadsPerThreadGroup(0),
-              maxThreadGroupsX(0),
-              maxThreadGroupsY(0),
-              maxThreadGroupsZ(0),
-              maxUniformVectors(4096),
-              maxVertexInputs(8),
-              maxVertexOutputs(8),
-              msaaRenderBuffer(false),
-              multisampledTexture(false),
-              npotTextureFull(true),
-              gles(false),
-              fixedIndexPrimitiveRestart(false),
-              bgraExternalFormat(false),
-              bgraInternalFormat(false),
-              r8Format(false),
-              r16Format(false),
-              floatFormats(false),
-              rgb10Formats(false),
-              depthTexture(false),
-              packedDepthStencil(false),
-              needsDepthStencilCombinedAttach(false),
-              srgbCapableDefaultFramebuffer(false),
-              coreProfile(false),
-              uniformBuffers(false),
-              elementIndexUint(false),
-              depth24(false),
-              rgba8Format(false),
-              instancing(false),
-              baseVertex(false),
-              compute(false),
-              textureCompareMode(false),
-              properMapBuffer(false),
-              nonBaseLevelFramebufferTexture(false),
-              texelFetch(false),
-              intAttributes(true),
-              screenSpaceDerivatives(false),
-              programBinary(false),
-              texture3D(false),
-              tessellation(false),
-              geometryShader(false),
-              texture1D(false),
-              hasDrawBuffersFunc(false),
-              halfAttributes(false)
-        { }
-        int ctxMajor;
-        int ctxMinor;
-        int maxTextureSize;
-        int maxDrawBuffers;
-        int maxSamples;
-        int maxTextureArraySize;
-        int maxThreadGroupsPerDimension;
-        int maxThreadsPerThreadGroup;
-        int maxThreadGroupsX;
-        int maxThreadGroupsY;
-        int maxThreadGroupsZ;
-        int maxUniformVectors;
-        int maxVertexInputs;
-        int maxVertexOutputs;
-        // Multisample fb and blit are supported (GLES 3.0 or OpenGL 3.x). Not
-        // the same as multisample textures!
-        uint msaaRenderBuffer : 1;
-        uint multisampledTexture : 1;
-        uint npotTextureFull : 1;
-        uint gles : 1;
-        uint fixedIndexPrimitiveRestart : 1;
-        uint bgraExternalFormat : 1;
-        uint bgraInternalFormat : 1;
-        uint r8Format : 1;
-        uint r16Format : 1;
-        uint floatFormats : 1;
-        uint rgb10Formats : 1;
-        uint depthTexture : 1;
-        uint packedDepthStencil : 1;
-        uint needsDepthStencilCombinedAttach : 1;
-        uint srgbCapableDefaultFramebuffer : 1;
-        uint coreProfile : 1;
-        uint uniformBuffers : 1;
-        uint elementIndexUint : 1;
-        uint depth24 : 1;
-        uint rgba8Format : 1;
-        uint instancing : 1;
-        uint baseVertex : 1;
-        uint compute : 1;
-        uint textureCompareMode : 1;
-        uint properMapBuffer : 1;
-        uint nonBaseLevelFramebufferTexture : 1;
-        uint texelFetch : 1;
-        uint intAttributes : 1;
-        uint screenSpaceDerivatives : 1;
-        uint programBinary : 1;
-        uint texture3D : 1;
-        uint tessellation : 1;
-        uint geometryShader : 1;
-        uint texture1D : 1;
-        uint hasDrawBuffersFunc : 1;
-        uint halfAttributes : 1;
-    } caps;
-    QGles2SwapChain *currentSwapChain = nullptr;
-    QSet<GLint> supportedCompressedFormats;
-    mutable QList<int> supportedSampleCountList;
-    QRhiGles2NativeHandles nativeHandlesStruct;
-    QRhiDriverInfo driverInfoStruct;
-    mutable bool contextLost = false;
-
-    struct DeferredReleaseEntry {
-        enum Type {
-            Buffer,
-            Pipeline,
-            Texture,
-            RenderBuffer,
-            TextureRenderTarget
-        };
-        Type type;
-        union {
-            struct {
-                GLuint buffer;
-            } buffer;
-            struct {
-                GLuint program;
-            } pipeline;
-            struct {
-                GLuint texture;
-            } texture;
-            struct {
-                GLuint renderbuffer;
-                GLuint renderbuffer2;
-            } renderbuffer;
-            struct {
-                GLuint framebuffer;
-            } textureRenderTarget;
-        };
-    };
-    QList<DeferredReleaseEntry> releaseQueue;
-
-    struct OffscreenFrame {
-        OffscreenFrame(QRhiImplementation *rhi) : cbWrapper(rhi) { }
-        bool active = false;
-        QGles2CommandBuffer cbWrapper;
-    } ofr;
-
-    QHash<QRhiShaderStage, uint> m_shaderCache;
-
-    struct PipelineCacheData {
-        quint32 format;
-        QByteArray data;
-    };
-    QHash<QByteArray, PipelineCacheData> m_pipelineCache;
-};
-
-Q_DECLARE_TYPEINFO(QRhiGles2::DeferredReleaseEntry, Q_RELOCATABLE_TYPE);
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/rhi/qrhimetal.mm b/src/gui/rhi/qrhimetal.mm
index 20b28e9dc6..57f5aefdd4 100644
--- a/src/gui/rhi/qrhimetal.mm
+++ b/src/gui/rhi/qrhimetal.mm
@@ -1,8 +1,8 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#include "qrhimetal_p_p.h"
-#include <QtGui/private/qshader_p_p.h>
+#include "qrhimetal_p.h"
+#include "qshader_p.h"
 #include <QGuiApplication>
 #include <QWindow>
 #include <QUrl>
@@ -50,9 +50,12 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QRhiMetalInitParams
     \inmodule QtRhi
-    \internal
+    \since 6.6
     \brief Metal specific initialization parameters.
 
+    \note This an RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     A Metal-based QRhi needs no special parameters for initialization.
 
     \badcode
@@ -85,14 +88,25 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QRhiMetalNativeHandles
     \inmodule QtRhi
-    \internal
+    \since 6.6
     \brief Holds the Metal device used by the QRhi.
+
+    \note This an RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
+    \variable QRhiMetalNativeHandles::dev
+*/
+
+/*!
+    \variable QRhiMetalNativeHandles::cmdQueue
+*/
+
+/*!
     \class QRhiMetalCommandBufferNativeHandles
     \inmodule QtRhi
-    \internal
+    \since 6.6
     \brief Holds the MTLCommandBuffer and MTLRenderCommandEncoder objects that are backing a QRhiCommandBuffer.
 
     \note The command buffer object is only guaranteed to be valid while
@@ -104,8 +118,19 @@ QT_BEGIN_NAMESPACE
     \note The command encoder is only valid while recording a pass, that is,
     between \l{QRhiCommandBuffer::beginPass()} -
     \l{QRhiCommandBuffer::endPass()}.
+
+    \note This an RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
+/*!
+    \variable QRhiMetalCommandBufferNativeHandles::commandBuffer
+*/
+
+/*!
+    \variable QRhiMetalCommandBufferNativeHandles::encoder
+*/
+
 struct QMetalShader
 {
     id<MTLLibrary> lib = nil;
diff --git a/src/gui/rhi/qrhimetal_p.h b/src/gui/rhi/qrhimetal_p.h
index 016bf749e2..8fb2ce84b0 100644
--- a/src/gui/rhi/qrhimetal_p.h
+++ b/src/gui/rhi/qrhimetal_p.h
@@ -1,8 +1,8 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#ifndef QRHIMETAL_H
-#define QRHIMETAL_H
+#ifndef QRHIMETAL_P_H
+#define QRHIMETAL_P_H
 
 //
 //  W A R N I N G
@@ -15,29 +15,493 @@
 // We mean it.
 //
 
-#include <private/qrhi_p.h>
-
-Q_FORWARD_DECLARE_OBJC_CLASS(MTLDevice);
-Q_FORWARD_DECLARE_OBJC_CLASS(MTLCommandQueue);
-Q_FORWARD_DECLARE_OBJC_CLASS(MTLCommandBuffer);
-Q_FORWARD_DECLARE_OBJC_CLASS(MTLRenderCommandEncoder);
+#include "qrhi_p.h"
+#include <QWindow>
 
 QT_BEGIN_NAMESPACE
 
-struct Q_GUI_EXPORT QRhiMetalInitParams : public QRhiInitParams
+static const int QMTL_FRAMES_IN_FLIGHT = 2;
+
+// have to hide the ObjC stuff, this header cannot contain MTL* at all
+struct QMetalBufferData;
+
+struct QMetalBuffer : public QRhiBuffer
+{
+    QMetalBuffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
+    ~QMetalBuffer();
+    void destroy() override;
+    bool create() override;
+    QRhiBuffer::NativeBuffer nativeBuffer() override;
+    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
+    void endFullDynamicBufferUpdateForCurrentFrame() override;
+
+    QMetalBufferData *d;
+    uint generation = 0;
+    int lastActiveFrameSlot = -1;
+    friend class QRhiMetal;
+    friend struct QMetalShaderResourceBindings;
+
+    static constexpr int WorkBufPoolUsage = 1 << 8;
+    static_assert(WorkBufPoolUsage > QRhiBuffer::StorageBuffer);
+};
+
+struct QMetalRenderBufferData;
+
+struct QMetalRenderBuffer : public QRhiRenderBuffer
+{
+    QMetalRenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
+                       int sampleCount, QRhiRenderBuffer::Flags flags,
+                       QRhiTexture::Format backingFormatHint);
+    ~QMetalRenderBuffer();
+    void destroy() override;
+    bool create() override;
+    QRhiTexture::Format backingFormat() const override;
+
+    QMetalRenderBufferData *d;
+    int samples = 1;
+    uint generation = 0;
+    int lastActiveFrameSlot = -1;
+    friend class QRhiMetal;
+};
+
+struct QMetalTextureData;
+
+struct QMetalTexture : public QRhiTexture
+{
+    QMetalTexture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
+                  int arraySize, int sampleCount, Flags flags);
+    ~QMetalTexture();
+    void destroy() override;
+    bool create() override;
+    bool createFrom(NativeTexture src) override;
+    NativeTexture nativeTexture() override;
+
+    bool prepareCreate(QSize *adjustedSize = nullptr);
+
+    QMetalTextureData *d;
+    int mipLevelCount = 0;
+    int samples = 1;
+    uint generation = 0;
+    int lastActiveFrameSlot = -1;
+    friend class QRhiMetal;
+    friend struct QMetalShaderResourceBindings;
+    friend struct QMetalTextureData;
+};
+
+struct QMetalSamplerData;
+
+struct QMetalSampler : public QRhiSampler
+{
+    QMetalSampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
+                  AddressMode u, AddressMode v, AddressMode w);
+    ~QMetalSampler();
+    void destroy() override;
+    bool create() override;
+
+    QMetalSamplerData *d;
+    uint generation = 0;
+    int lastActiveFrameSlot = -1;
+    friend class QRhiMetal;
+    friend struct QMetalShaderResourceBindings;
+};
+
+struct QMetalRenderPassDescriptor : public QRhiRenderPassDescriptor
 {
+    QMetalRenderPassDescriptor(QRhiImplementation *rhi);
+    ~QMetalRenderPassDescriptor();
+    void destroy() override;
+    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
+    QVector<quint32> serializedFormat() const override;
+
+    void updateSerializedFormat();
+
+    // there is no MTLRenderPassDescriptor here as one will be created for each pass in beginPass()
+
+    // but the things needed for the render pipeline descriptor have to be provided
+    static const int MAX_COLOR_ATTACHMENTS = 8;
+    int colorAttachmentCount = 0;
+    bool hasDepthStencil = false;
+    int colorFormat[MAX_COLOR_ATTACHMENTS];
+    int dsFormat;
+    QVector<quint32> serializedFormatData;
+};
+
+struct QMetalRenderTargetData;
+
+struct QMetalSwapChainRenderTarget : public QRhiSwapChainRenderTarget
+{
+    QMetalSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
+    ~QMetalSwapChainRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QMetalRenderTargetData *d;
+};
+
+struct QMetalTextureRenderTarget : public QRhiTextureRenderTarget
+{
+    QMetalTextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
+    ~QMetalTextureRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool create() override;
+
+    QMetalRenderTargetData *d;
+    friend class QRhiMetal;
 };
 
-struct Q_GUI_EXPORT QRhiMetalNativeHandles : public QRhiNativeHandles
+struct QMetalShaderResourceBindings : public QRhiShaderResourceBindings
 {
-    MTLDevice *dev = nullptr;
-    MTLCommandQueue *cmdQueue = nullptr;
+    QMetalShaderResourceBindings(QRhiImplementation *rhi);
+    ~QMetalShaderResourceBindings();
+    void destroy() override;
+    bool create() override;
+    void updateResources(UpdateFlags flags) override;
+
+    QVarLengthArray<QRhiShaderResourceBinding, 8> sortedBindings;
+    int maxBinding = -1;
+
+    struct BoundUniformBufferData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundSampledTextureData {
+        int count;
+        struct {
+            quint64 texId;
+            uint texGeneration;
+            quint64 samplerId;
+            uint samplerGeneration;
+        } d[QRhiShaderResourceBinding::Data::MAX_TEX_SAMPLER_ARRAY_SIZE];
+    };
+    struct BoundStorageImageData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundStorageBufferData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundResourceData {
+        union {
+            BoundUniformBufferData ubuf;
+            BoundSampledTextureData stex;
+            BoundStorageImageData simage;
+            BoundStorageBufferData sbuf;
+        };
+    };
+    QVarLengthArray<BoundResourceData, 8> boundResourceData;
+
+    uint generation = 0;
+    friend class QRhiMetal;
 };
 
-struct Q_GUI_EXPORT QRhiMetalCommandBufferNativeHandles : public QRhiNativeHandles
+struct QMetalGraphicsPipelineData;
+struct QMetalCommandBuffer;
+
+struct QMetalGraphicsPipeline : public QRhiGraphicsPipeline
 {
-    MTLCommandBuffer *commandBuffer = nullptr;
-    MTLRenderCommandEncoder *encoder = nullptr;
+    QMetalGraphicsPipeline(QRhiImplementation *rhi);
+    ~QMetalGraphicsPipeline();
+    void destroy() override;
+    bool create() override;
+
+    void makeActiveForCurrentRenderPassEncoder(QMetalCommandBuffer *cbD);
+    void setupAttachmentsInMetalRenderPassDescriptor(void *metalRpDesc, QMetalRenderPassDescriptor *rpD);
+    void setupMetalDepthStencilDescriptor(void *metalDsDesc);
+    void mapStates();
+    bool createVertexFragmentPipeline();
+    bool createTessellationPipelines(const QShader &tessVert, const QShader &tesc, const QShader &tese, const QShader &tessFrag);
+
+    QMetalGraphicsPipelineData *d;
+    uint generation = 0;
+    int lastActiveFrameSlot = -1;
+    friend class QRhiMetal;
+};
+
+struct QMetalComputePipelineData;
+
+struct QMetalComputePipeline : public QRhiComputePipeline
+{
+    QMetalComputePipeline(QRhiImplementation *rhi);
+    ~QMetalComputePipeline();
+    void destroy() override;
+    bool create() override;
+
+    QMetalComputePipelineData *d;
+    uint generation = 0;
+    int lastActiveFrameSlot = -1;
+    friend class QRhiMetal;
+};
+
+struct QMetalCommandBufferData;
+struct QMetalSwapChain;
+
+struct QMetalCommandBuffer : public QRhiCommandBuffer
+{
+    QMetalCommandBuffer(QRhiImplementation *rhi);
+    ~QMetalCommandBuffer();
+    void destroy() override;
+
+    QMetalCommandBufferData *d = nullptr;
+    QRhiMetalCommandBufferNativeHandles nativeHandlesStruct;
+
+    enum PassType {
+        NoPass,
+        RenderPass,
+        ComputePass
+    };
+
+    // per-pass (render or compute command encoder) persistent state
+    PassType recordingPass;
+    QRhiRenderTarget *currentTarget;
+
+    // per-pass (render or compute command encoder) volatile (cached) state
+    QMetalGraphicsPipeline *currentGraphicsPipeline;
+    QMetalComputePipeline *currentComputePipeline;
+    uint currentPipelineGeneration;
+    QMetalShaderResourceBindings *currentGraphicsSrb;
+    QMetalShaderResourceBindings *currentComputeSrb;
+    uint currentSrbGeneration;
+    int currentResSlot;
+    QMetalBuffer *currentIndexBuffer;
+    quint32 currentIndexOffset;
+    QRhiCommandBuffer::IndexFormat currentIndexFormat;
+    int currentCullMode;
+    int currentTriangleFillMode;
+    int currentFrontFaceWinding;
+    QPair<float, float> currentDepthBiasValues;
+
+    const QRhiNativeHandles *nativeHandles();
+    void resetState(double lastGpuTime = 0);
+    void resetPerPassState();
+    void resetPerPassCachedState();
+};
+
+struct QMetalSwapChainData;
+
+struct QMetalSwapChain : public QRhiSwapChain
+{
+    QMetalSwapChain(QRhiImplementation *rhi);
+    ~QMetalSwapChain();
+    void destroy() override;
+
+    QRhiCommandBuffer *currentFrameCommandBuffer() override;
+    QRhiRenderTarget *currentFrameRenderTarget() override;
+    QSize surfacePixelSize() override;
+    bool isFormatSupported(Format f) override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+
+    bool createOrResize() override;
+
+    virtual QRhiSwapChainHdrInfo hdrInfo() override;
+
+    void chooseFormats();
+    void waitUntilCompleted(int slot);
+
+    QWindow *window = nullptr;
+    QSize pixelSize;
+    int currentFrameSlot = 0; // 0..QMTL_FRAMES_IN_FLIGHT-1
+    int frameCount = 0;
+    int samples = 1;
+    QMetalSwapChainRenderTarget rtWrapper;
+    QMetalCommandBuffer cbWrapper;
+    QMetalRenderBuffer *ds = nullptr;
+    QMetalSwapChainData *d = nullptr;
+};
+
+struct QRhiMetalData;
+
+class QRhiMetal : public QRhiImplementation
+{
+public:
+    QRhiMetal(QRhiMetalInitParams *params, QRhiMetalNativeHandles *importDevice = nullptr);
+    ~QRhiMetal();
+
+    static bool probe(QRhiMetalInitParams *params);
+    static QRhiSwapChainProxyData updateSwapChainProxyData(QWindow *window);
+
+    bool create(QRhi::Flags flags) override;
+    void destroy() override;
+
+    QRhiGraphicsPipeline *createGraphicsPipeline() override;
+    QRhiComputePipeline *createComputePipeline() override;
+    QRhiShaderResourceBindings *createShaderResourceBindings() override;
+    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
+                             QRhiBuffer::UsageFlags usage,
+                             quint32 size) override;
+    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
+                                         const QSize &pixelSize,
+                                         int sampleCount,
+                                         QRhiRenderBuffer::Flags flags,
+                                         QRhiTexture::Format backingFormatHint) override;
+    QRhiTexture *createTexture(QRhiTexture::Format format,
+                               const QSize &pixelSize,
+                               int depth,
+                               int arraySize,
+                               int sampleCount,
+                               QRhiTexture::Flags flags) override;
+    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
+                               QRhiSampler::Filter minFilter,
+                               QRhiSampler::Filter mipmapMode,
+                               QRhiSampler:: AddressMode u,
+                               QRhiSampler::AddressMode v,
+                               QRhiSampler::AddressMode w) override;
+
+    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
+                                                       QRhiTextureRenderTarget::Flags flags) override;
+
+    QRhiSwapChain *createSwapChain() override;
+    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult finish() override;
+
+    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void beginPass(QRhiCommandBuffer *cb,
+                   QRhiRenderTarget *rt,
+                   const QColor &colorClearValue,
+                   const QRhiDepthStencilClearValue &depthStencilClearValue,
+                   QRhiResourceUpdateBatch *resourceUpdates,
+                   QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void setGraphicsPipeline(QRhiCommandBuffer *cb,
+                             QRhiGraphicsPipeline *ps) override;
+
+    void setShaderResources(QRhiCommandBuffer *cb,
+                            QRhiShaderResourceBindings *srb,
+                            int dynamicOffsetCount,
+                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
+
+    void setVertexInput(QRhiCommandBuffer *cb,
+                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
+                        QRhiBuffer *indexBuf, quint32 indexOffset,
+                        QRhiCommandBuffer::IndexFormat indexFormat) override;
+
+    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
+    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
+    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
+    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
+
+    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
+              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
+
+    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
+                     quint32 instanceCount, quint32 firstIndex,
+                     qint32 vertexOffset, quint32 firstInstance) override;
+
+    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
+    void debugMarkEnd(QRhiCommandBuffer *cb) override;
+    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
+
+    void beginComputePass(QRhiCommandBuffer *cb,
+                          QRhiResourceUpdateBatch *resourceUpdates,
+                          QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
+    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
+
+    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
+    void beginExternal(QRhiCommandBuffer *cb) override;
+    void endExternal(QRhiCommandBuffer *cb) override;
+    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
+
+    QList<int> supportedSampleCounts() const override;
+    int ubufAlignment() const override;
+    bool isYUpInFramebuffer() const override;
+    bool isYUpInNDC() const override;
+    bool isClipDepthZeroToOne() const override;
+    QMatrix4x4 clipSpaceCorrMatrix() const override;
+    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
+    bool isFeatureSupported(QRhi::Feature feature) const override;
+    int resourceLimit(QRhi::ResourceLimit limit) const override;
+    const QRhiNativeHandles *nativeHandles() override;
+    QRhiDriverInfo driverInfo() const override;
+    QRhiStats statistics() override;
+    bool makeThreadLocalNativeContextCurrent() override;
+    void releaseCachedResources() override;
+    bool isDeviceLost() const override;
+
+    QByteArray pipelineCacheData() override;
+    void setPipelineCacheData(const QByteArray &data) override;
+
+    void executeDeferredReleases(bool forced = false);
+    void finishActiveReadbacks(bool forced = false);
+    qsizetype subresUploadByteSize(const QRhiTextureSubresourceUploadDescription &subresDesc) const;
+    void enqueueSubresUpload(QMetalTexture *texD, void *mp, void *blitEncPtr,
+                             int layer, int level, const QRhiTextureSubresourceUploadDescription &subresDesc,
+                             qsizetype *curOfs);
+    void enqueueResourceUpdates(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates);
+    void executeBufferHostWritesForSlot(QMetalBuffer *bufD, int slot);
+    void executeBufferHostWritesForCurrentFrame(QMetalBuffer *bufD);
+    static const int SUPPORTED_STAGES = 5;
+    void enqueueShaderResourceBindings(QMetalShaderResourceBindings *srbD,
+                                       QMetalCommandBuffer *cbD,
+                                       int dynamicOffsetCount,
+                                       const QRhiCommandBuffer::DynamicOffset *dynamicOffsets,
+                                       bool offsetOnlyChange,
+                                       const QShader::NativeResourceBindingMap *nativeResourceBindingMaps[SUPPORTED_STAGES]);
+    int effectiveSampleCount(int sampleCount) const;
+    struct TessDrawArgs {
+        QMetalCommandBuffer *cbD;
+        enum {
+            NonIndexed,
+            U16Indexed,
+            U32Indexed
+        } type;
+        struct NonIndexedArgs {
+            quint32 vertexCount;
+            quint32 instanceCount;
+            quint32 firstVertex;
+            quint32 firstInstance;
+        };
+        struct IndexedArgs {
+            quint32 indexCount;
+            quint32 instanceCount;
+            quint32 firstIndex;
+            qint32 vertexOffset;
+            quint32 firstInstance;
+            void *indexBuffer;
+        };
+        union {
+            NonIndexedArgs draw;
+            IndexedArgs drawIndexed;
+        };
+    };
+    void tessellatedDraw(const TessDrawArgs &args);
+
+    QRhi::Flags rhiFlags;
+    bool importedDevice = false;
+    bool importedCmdQueue = false;
+    QMetalSwapChain *currentSwapChain = nullptr;
+    QSet<QMetalSwapChain *> swapchains;
+    QRhiMetalNativeHandles nativeHandlesStruct;
+    QRhiDriverInfo driverInfoStruct;
+    quint32 osMajor = 0;
+    quint32 osMinor = 0;
+
+    struct {
+        int maxTextureSize = 4096;
+        bool baseVertexAndInstance = true;
+        QVector<int> supportedSampleCounts;
+        bool isAppleGPU = false;
+        int maxThreadGroupSize = 512;
+    } caps;
+
+    QRhiMetalData *d = nullptr;
 };
 
 QT_END_NAMESPACE
diff --git a/src/gui/rhi/qrhimetal_p_p.h b/src/gui/rhi/qrhimetal_p_p.h
deleted file mode 100644
index 9f60923851..0000000000
--- a/src/gui/rhi/qrhimetal_p_p.h
+++ /dev/null
@@ -1,510 +0,0 @@
-// Copyright (C) 2019 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
-
-#ifndef QRHIMETAL_P_H
-#define QRHIMETAL_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists purely as an
-// implementation detail.  This header file may change from version to
-// version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qrhimetal_p.h"
-#include "qrhi_p_p.h"
-#include <QWindow>
-
-QT_BEGIN_NAMESPACE
-
-static const int QMTL_FRAMES_IN_FLIGHT = 2;
-
-// have to hide the ObjC stuff, this header cannot contain MTL* at all
-struct QMetalBufferData;
-
-struct QMetalBuffer : public QRhiBuffer
-{
-    QMetalBuffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
-    ~QMetalBuffer();
-    void destroy() override;
-    bool create() override;
-    QRhiBuffer::NativeBuffer nativeBuffer() override;
-    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
-    void endFullDynamicBufferUpdateForCurrentFrame() override;
-
-    QMetalBufferData *d;
-    uint generation = 0;
-    int lastActiveFrameSlot = -1;
-    friend class QRhiMetal;
-    friend struct QMetalShaderResourceBindings;
-
-    static constexpr int WorkBufPoolUsage = 1 << 8;
-    static_assert(WorkBufPoolUsage > QRhiBuffer::StorageBuffer);
-};
-
-struct QMetalRenderBufferData;
-
-struct QMetalRenderBuffer : public QRhiRenderBuffer
-{
-    QMetalRenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
-                       int sampleCount, QRhiRenderBuffer::Flags flags,
-                       QRhiTexture::Format backingFormatHint);
-    ~QMetalRenderBuffer();
-    void destroy() override;
-    bool create() override;
-    QRhiTexture::Format backingFormat() const override;
-
-    QMetalRenderBufferData *d;
-    int samples = 1;
-    uint generation = 0;
-    int lastActiveFrameSlot = -1;
-    friend class QRhiMetal;
-};
-
-struct QMetalTextureData;
-
-struct QMetalTexture : public QRhiTexture
-{
-    QMetalTexture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
-                  int arraySize, int sampleCount, Flags flags);
-    ~QMetalTexture();
-    void destroy() override;
-    bool create() override;
-    bool createFrom(NativeTexture src) override;
-    NativeTexture nativeTexture() override;
-
-    bool prepareCreate(QSize *adjustedSize = nullptr);
-
-    QMetalTextureData *d;
-    int mipLevelCount = 0;
-    int samples = 1;
-    uint generation = 0;
-    int lastActiveFrameSlot = -1;
-    friend class QRhiMetal;
-    friend struct QMetalShaderResourceBindings;
-    friend struct QMetalTextureData;
-};
-
-struct QMetalSamplerData;
-
-struct QMetalSampler : public QRhiSampler
-{
-    QMetalSampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
-                  AddressMode u, AddressMode v, AddressMode w);
-    ~QMetalSampler();
-    void destroy() override;
-    bool create() override;
-
-    QMetalSamplerData *d;
-    uint generation = 0;
-    int lastActiveFrameSlot = -1;
-    friend class QRhiMetal;
-    friend struct QMetalShaderResourceBindings;
-};
-
-struct QMetalRenderPassDescriptor : public QRhiRenderPassDescriptor
-{
-    QMetalRenderPassDescriptor(QRhiImplementation *rhi);
-    ~QMetalRenderPassDescriptor();
-    void destroy() override;
-    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
-    QVector<quint32> serializedFormat() const override;
-
-    void updateSerializedFormat();
-
-    // there is no MTLRenderPassDescriptor here as one will be created for each pass in beginPass()
-
-    // but the things needed for the render pipeline descriptor have to be provided
-    static const int MAX_COLOR_ATTACHMENTS = 8;
-    int colorAttachmentCount = 0;
-    bool hasDepthStencil = false;
-    int colorFormat[MAX_COLOR_ATTACHMENTS];
-    int dsFormat;
-    QVector<quint32> serializedFormatData;
-};
-
-struct QMetalRenderTargetData;
-
-struct QMetalSwapChainRenderTarget : public QRhiSwapChainRenderTarget
-{
-    QMetalSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
-    ~QMetalSwapChainRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QMetalRenderTargetData *d;
-};
-
-struct QMetalTextureRenderTarget : public QRhiTextureRenderTarget
-{
-    QMetalTextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
-    ~QMetalTextureRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool create() override;
-
-    QMetalRenderTargetData *d;
-    friend class QRhiMetal;
-};
-
-struct QMetalShaderResourceBindings : public QRhiShaderResourceBindings
-{
-    QMetalShaderResourceBindings(QRhiImplementation *rhi);
-    ~QMetalShaderResourceBindings();
-    void destroy() override;
-    bool create() override;
-    void updateResources(UpdateFlags flags) override;
-
-    QVarLengthArray<QRhiShaderResourceBinding, 8> sortedBindings;
-    int maxBinding = -1;
-
-    struct BoundUniformBufferData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundSampledTextureData {
-        int count;
-        struct {
-            quint64 texId;
-            uint texGeneration;
-            quint64 samplerId;
-            uint samplerGeneration;
-        } d[QRhiShaderResourceBinding::Data::MAX_TEX_SAMPLER_ARRAY_SIZE];
-    };
-    struct BoundStorageImageData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundStorageBufferData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundResourceData {
-        union {
-            BoundUniformBufferData ubuf;
-            BoundSampledTextureData stex;
-            BoundStorageImageData simage;
-            BoundStorageBufferData sbuf;
-        };
-    };
-    QVarLengthArray<BoundResourceData, 8> boundResourceData;
-
-    uint generation = 0;
-    friend class QRhiMetal;
-};
-
-struct QMetalGraphicsPipelineData;
-struct QMetalCommandBuffer;
-
-struct QMetalGraphicsPipeline : public QRhiGraphicsPipeline
-{
-    QMetalGraphicsPipeline(QRhiImplementation *rhi);
-    ~QMetalGraphicsPipeline();
-    void destroy() override;
-    bool create() override;
-
-    void makeActiveForCurrentRenderPassEncoder(QMetalCommandBuffer *cbD);
-    void setupAttachmentsInMetalRenderPassDescriptor(void *metalRpDesc, QMetalRenderPassDescriptor *rpD);
-    void setupMetalDepthStencilDescriptor(void *metalDsDesc);
-    void mapStates();
-    bool createVertexFragmentPipeline();
-    bool createTessellationPipelines(const QShader &tessVert, const QShader &tesc, const QShader &tese, const QShader &tessFrag);
-
-    QMetalGraphicsPipelineData *d;
-    uint generation = 0;
-    int lastActiveFrameSlot = -1;
-    friend class QRhiMetal;
-};
-
-struct QMetalComputePipelineData;
-
-struct QMetalComputePipeline : public QRhiComputePipeline
-{
-    QMetalComputePipeline(QRhiImplementation *rhi);
-    ~QMetalComputePipeline();
-    void destroy() override;
-    bool create() override;
-
-    QMetalComputePipelineData *d;
-    uint generation = 0;
-    int lastActiveFrameSlot = -1;
-    friend class QRhiMetal;
-};
-
-struct QMetalCommandBufferData;
-struct QMetalSwapChain;
-
-struct QMetalCommandBuffer : public QRhiCommandBuffer
-{
-    QMetalCommandBuffer(QRhiImplementation *rhi);
-    ~QMetalCommandBuffer();
-    void destroy() override;
-
-    QMetalCommandBufferData *d = nullptr;
-    QRhiMetalCommandBufferNativeHandles nativeHandlesStruct;
-
-    enum PassType {
-        NoPass,
-        RenderPass,
-        ComputePass
-    };
-
-    // per-pass (render or compute command encoder) persistent state
-    PassType recordingPass;
-    QRhiRenderTarget *currentTarget;
-
-    // per-pass (render or compute command encoder) volatile (cached) state
-    QMetalGraphicsPipeline *currentGraphicsPipeline;
-    QMetalComputePipeline *currentComputePipeline;
-    uint currentPipelineGeneration;
-    QMetalShaderResourceBindings *currentGraphicsSrb;
-    QMetalShaderResourceBindings *currentComputeSrb;
-    uint currentSrbGeneration;
-    int currentResSlot;
-    QMetalBuffer *currentIndexBuffer;
-    quint32 currentIndexOffset;
-    QRhiCommandBuffer::IndexFormat currentIndexFormat;
-    int currentCullMode;
-    int currentTriangleFillMode;
-    int currentFrontFaceWinding;
-    QPair<float, float> currentDepthBiasValues;
-
-    const QRhiNativeHandles *nativeHandles();
-    void resetState(double lastGpuTime = 0);
-    void resetPerPassState();
-    void resetPerPassCachedState();
-};
-
-struct QMetalSwapChainData;
-
-struct QMetalSwapChain : public QRhiSwapChain
-{
-    QMetalSwapChain(QRhiImplementation *rhi);
-    ~QMetalSwapChain();
-    void destroy() override;
-
-    QRhiCommandBuffer *currentFrameCommandBuffer() override;
-    QRhiRenderTarget *currentFrameRenderTarget() override;
-    QSize surfacePixelSize() override;
-    bool isFormatSupported(Format f) override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-
-    bool createOrResize() override;
-
-    virtual QRhiSwapChainHdrInfo hdrInfo() override;
-
-    void chooseFormats();
-    void waitUntilCompleted(int slot);
-
-    QWindow *window = nullptr;
-    QSize pixelSize;
-    int currentFrameSlot = 0; // 0..QMTL_FRAMES_IN_FLIGHT-1
-    int frameCount = 0;
-    int samples = 1;
-    QMetalSwapChainRenderTarget rtWrapper;
-    QMetalCommandBuffer cbWrapper;
-    QMetalRenderBuffer *ds = nullptr;
-    QMetalSwapChainData *d = nullptr;
-};
-
-struct QRhiMetalData;
-
-class QRhiMetal : public QRhiImplementation
-{
-public:
-    QRhiMetal(QRhiMetalInitParams *params, QRhiMetalNativeHandles *importDevice = nullptr);
-    ~QRhiMetal();
-
-    static bool probe(QRhiMetalInitParams *params);
-    static QRhiSwapChainProxyData updateSwapChainProxyData(QWindow *window);
-
-    bool create(QRhi::Flags flags) override;
-    void destroy() override;
-
-    QRhiGraphicsPipeline *createGraphicsPipeline() override;
-    QRhiComputePipeline *createComputePipeline() override;
-    QRhiShaderResourceBindings *createShaderResourceBindings() override;
-    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
-                             QRhiBuffer::UsageFlags usage,
-                             quint32 size) override;
-    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
-                                         const QSize &pixelSize,
-                                         int sampleCount,
-                                         QRhiRenderBuffer::Flags flags,
-                                         QRhiTexture::Format backingFormatHint) override;
-    QRhiTexture *createTexture(QRhiTexture::Format format,
-                               const QSize &pixelSize,
-                               int depth,
-                               int arraySize,
-                               int sampleCount,
-                               QRhiTexture::Flags flags) override;
-    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
-                               QRhiSampler::Filter minFilter,
-                               QRhiSampler::Filter mipmapMode,
-                               QRhiSampler:: AddressMode u,
-                               QRhiSampler::AddressMode v,
-                               QRhiSampler::AddressMode w) override;
-
-    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
-                                                       QRhiTextureRenderTarget::Flags flags) override;
-
-    QRhiSwapChain *createSwapChain() override;
-    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult finish() override;
-
-    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void beginPass(QRhiCommandBuffer *cb,
-                   QRhiRenderTarget *rt,
-                   const QColor &colorClearValue,
-                   const QRhiDepthStencilClearValue &depthStencilClearValue,
-                   QRhiResourceUpdateBatch *resourceUpdates,
-                   QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void setGraphicsPipeline(QRhiCommandBuffer *cb,
-                             QRhiGraphicsPipeline *ps) override;
-
-    void setShaderResources(QRhiCommandBuffer *cb,
-                            QRhiShaderResourceBindings *srb,
-                            int dynamicOffsetCount,
-                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
-
-    void setVertexInput(QRhiCommandBuffer *cb,
-                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
-                        QRhiBuffer *indexBuf, quint32 indexOffset,
-                        QRhiCommandBuffer::IndexFormat indexFormat) override;
-
-    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
-    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
-    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
-    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
-
-    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
-              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
-
-    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
-                     quint32 instanceCount, quint32 firstIndex,
-                     qint32 vertexOffset, quint32 firstInstance) override;
-
-    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
-    void debugMarkEnd(QRhiCommandBuffer *cb) override;
-    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
-
-    void beginComputePass(QRhiCommandBuffer *cb,
-                          QRhiResourceUpdateBatch *resourceUpdates,
-                          QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
-    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
-
-    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
-    void beginExternal(QRhiCommandBuffer *cb) override;
-    void endExternal(QRhiCommandBuffer *cb) override;
-    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
-
-    QList<int> supportedSampleCounts() const override;
-    int ubufAlignment() const override;
-    bool isYUpInFramebuffer() const override;
-    bool isYUpInNDC() const override;
-    bool isClipDepthZeroToOne() const override;
-    QMatrix4x4 clipSpaceCorrMatrix() const override;
-    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
-    bool isFeatureSupported(QRhi::Feature feature) const override;
-    int resourceLimit(QRhi::ResourceLimit limit) const override;
-    const QRhiNativeHandles *nativeHandles() override;
-    QRhiDriverInfo driverInfo() const override;
-    QRhiStats statistics() override;
-    bool makeThreadLocalNativeContextCurrent() override;
-    void releaseCachedResources() override;
-    bool isDeviceLost() const override;
-
-    QByteArray pipelineCacheData() override;
-    void setPipelineCacheData(const QByteArray &data) override;
-
-    void executeDeferredReleases(bool forced = false);
-    void finishActiveReadbacks(bool forced = false);
-    qsizetype subresUploadByteSize(const QRhiTextureSubresourceUploadDescription &subresDesc) const;
-    void enqueueSubresUpload(QMetalTexture *texD, void *mp, void *blitEncPtr,
-                             int layer, int level, const QRhiTextureSubresourceUploadDescription &subresDesc,
-                             qsizetype *curOfs);
-    void enqueueResourceUpdates(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates);
-    void executeBufferHostWritesForSlot(QMetalBuffer *bufD, int slot);
-    void executeBufferHostWritesForCurrentFrame(QMetalBuffer *bufD);
-    static const int SUPPORTED_STAGES = 5;
-    void enqueueShaderResourceBindings(QMetalShaderResourceBindings *srbD,
-                                       QMetalCommandBuffer *cbD,
-                                       int dynamicOffsetCount,
-                                       const QRhiCommandBuffer::DynamicOffset *dynamicOffsets,
-                                       bool offsetOnlyChange,
-                                       const QShader::NativeResourceBindingMap *nativeResourceBindingMaps[SUPPORTED_STAGES]);
-    int effectiveSampleCount(int sampleCount) const;
-    struct TessDrawArgs {
-        QMetalCommandBuffer *cbD;
-        enum {
-            NonIndexed,
-            U16Indexed,
-            U32Indexed
-        } type;
-        struct NonIndexedArgs {
-            quint32 vertexCount;
-            quint32 instanceCount;
-            quint32 firstVertex;
-            quint32 firstInstance;
-        };
-        struct IndexedArgs {
-            quint32 indexCount;
-            quint32 instanceCount;
-            quint32 firstIndex;
-            qint32 vertexOffset;
-            quint32 firstInstance;
-            void *indexBuffer;
-        };
-        union {
-            NonIndexedArgs draw;
-            IndexedArgs drawIndexed;
-        };
-    };
-    void tessellatedDraw(const TessDrawArgs &args);
-
-    QRhi::Flags rhiFlags;
-    bool importedDevice = false;
-    bool importedCmdQueue = false;
-    QMetalSwapChain *currentSwapChain = nullptr;
-    QSet<QMetalSwapChain *> swapchains;
-    QRhiMetalNativeHandles nativeHandlesStruct;
-    QRhiDriverInfo driverInfoStruct;
-    quint32 osMajor = 0;
-    quint32 osMinor = 0;
-
-    struct {
-        int maxTextureSize = 4096;
-        bool baseVertexAndInstance = true;
-        QVector<int> supportedSampleCounts;
-        bool isAppleGPU = false;
-        int maxThreadGroupSize = 512;
-    } caps;
-
-    QRhiMetalData *d = nullptr;
-};
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/rhi/qrhinull.cpp b/src/gui/rhi/qrhinull.cpp
index 6100492457..6d87baaec0 100644
--- a/src/gui/rhi/qrhinull.cpp
+++ b/src/gui/rhi/qrhinull.cpp
@@ -1,7 +1,7 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#include "qrhinull_p_p.h"
+#include "qrhinull_p.h"
 #include <qmath.h>
 #include <QPainter>
 
@@ -9,10 +9,13 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QRhiNullInitParams
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Null backend specific initialization parameters.
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     A Null QRhi needs no special parameters for initialization.
 
     \badcode
@@ -28,9 +31,12 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QRhiNullNativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Empty.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 QRhiNull::QRhiNull(QRhiNullInitParams *params)
diff --git a/src/gui/rhi/qrhinull_p.h b/src/gui/rhi/qrhinull_p.h
index 061b6eba4a..fc266b4f38 100644
--- a/src/gui/rhi/qrhinull_p.h
+++ b/src/gui/rhi/qrhinull_p.h
@@ -1,8 +1,8 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#ifndef QRHINULL_H
-#define QRHINULL_H
+#ifndef QRHINULL_P_H
+#define QRHINULL_P_H
 
 //
 //  W A R N I N G
@@ -15,16 +15,279 @@
 // We mean it.
 //
 
-#include <private/qrhi_p.h>
+#include "qrhi_p.h"
 
 QT_BEGIN_NAMESPACE
 
-struct Q_GUI_EXPORT QRhiNullInitParams : public QRhiInitParams
+struct QNullBuffer : public QRhiBuffer
 {
+    QNullBuffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
+    ~QNullBuffer();
+    void destroy() override;
+    bool create() override;
+    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
+
+    char *data = nullptr;
+};
+
+struct QNullRenderBuffer : public QRhiRenderBuffer
+{
+    QNullRenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
+                      int sampleCount, QRhiRenderBuffer::Flags flags,
+                      QRhiTexture::Format backingFormatHint);
+    ~QNullRenderBuffer();
+    void destroy() override;
+    bool create() override;
+    QRhiTexture::Format backingFormat() const override;
+
+    bool valid = false;
+    uint generation = 0;
+};
+
+struct QNullTexture : public QRhiTexture
+{
+    QNullTexture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
+                 int arraySize, int sampleCount, Flags flags);
+    ~QNullTexture();
+    void destroy() override;
+    bool create() override;
+    bool createFrom(NativeTexture src) override;
+
+    bool valid = false;
+    QVarLengthArray<std::array<QImage, QRhi::MAX_MIP_LEVELS>, 6> image;
+    uint generation = 0;
+};
+
+struct QNullSampler : public QRhiSampler
+{
+    QNullSampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
+                 AddressMode u, AddressMode v, AddressMode w);
+    ~QNullSampler();
+    void destroy() override;
+    bool create() override;
+};
+
+struct QNullRenderPassDescriptor : public QRhiRenderPassDescriptor
+{
+    QNullRenderPassDescriptor(QRhiImplementation *rhi);
+    ~QNullRenderPassDescriptor();
+    void destroy() override;
+    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
+    QVector<quint32> serializedFormat() const override;
+};
+
+struct QNullRenderTargetData
+{
+    QNullRenderTargetData(QRhiImplementation *) { }
+
+    QNullRenderPassDescriptor *rp = nullptr;
+    QSize pixelSize;
+    float dpr = 1;
+    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
+};
+
+struct QNullSwapChainRenderTarget : public QRhiSwapChainRenderTarget
+{
+    QNullSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
+    ~QNullSwapChainRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QNullRenderTargetData d;
+};
+
+struct QNullTextureRenderTarget : public QRhiTextureRenderTarget
+{
+    QNullTextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
+    ~QNullTextureRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool create() override;
+
+    QNullRenderTargetData d;
+};
+
+struct QNullShaderResourceBindings : public QRhiShaderResourceBindings
+{
+    QNullShaderResourceBindings(QRhiImplementation *rhi);
+    ~QNullShaderResourceBindings();
+    void destroy() override;
+    bool create() override;
+    void updateResources(UpdateFlags flags) override;
+};
+
+struct QNullGraphicsPipeline : public QRhiGraphicsPipeline
+{
+    QNullGraphicsPipeline(QRhiImplementation *rhi);
+    ~QNullGraphicsPipeline();
+    void destroy() override;
+    bool create() override;
+};
+
+struct QNullComputePipeline : public QRhiComputePipeline
+{
+    QNullComputePipeline(QRhiImplementation *rhi);
+    ~QNullComputePipeline();
+    void destroy() override;
+    bool create() override;
 };
 
-struct Q_GUI_EXPORT QRhiNullNativeHandles : public QRhiNativeHandles
+struct QNullCommandBuffer : public QRhiCommandBuffer
 {
+    QNullCommandBuffer(QRhiImplementation *rhi);
+    ~QNullCommandBuffer();
+    void destroy() override;
+};
+
+struct QNullSwapChain : public QRhiSwapChain
+{
+    QNullSwapChain(QRhiImplementation *rhi);
+    ~QNullSwapChain();
+    void destroy() override;
+
+    QRhiCommandBuffer *currentFrameCommandBuffer() override;
+    QRhiRenderTarget *currentFrameRenderTarget() override;
+
+    QSize surfacePixelSize() override;
+    bool isFormatSupported(Format f) override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool createOrResize() override;
+
+    QWindow *window = nullptr;
+    QNullSwapChainRenderTarget rt;
+    QNullCommandBuffer cb;
+    int frameCount = 0;
+};
+
+class QRhiNull : public QRhiImplementation
+{
+public:
+    QRhiNull(QRhiNullInitParams *params);
+
+    bool create(QRhi::Flags flags) override;
+    void destroy() override;
+
+    QRhiGraphicsPipeline *createGraphicsPipeline() override;
+    QRhiComputePipeline *createComputePipeline() override;
+    QRhiShaderResourceBindings *createShaderResourceBindings() override;
+    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
+                             QRhiBuffer::UsageFlags usage,
+                             quint32 size) override;
+    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
+                                         const QSize &pixelSize,
+                                         int sampleCount,
+                                         QRhiRenderBuffer::Flags flags,
+                                         QRhiTexture::Format backingFormatHint) override;
+    QRhiTexture *createTexture(QRhiTexture::Format format,
+                               const QSize &pixelSize,
+                               int depth,
+                               int arraySize,
+                               int sampleCount,
+                               QRhiTexture::Flags flags) override;
+    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
+                               QRhiSampler::Filter minFilter,
+                               QRhiSampler::Filter mipmapMode,
+                               QRhiSampler:: AddressMode u,
+                               QRhiSampler::AddressMode v,
+                               QRhiSampler::AddressMode w) override;
+
+    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
+                                                       QRhiTextureRenderTarget::Flags flags) override;
+
+    QRhiSwapChain *createSwapChain() override;
+    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult finish() override;
+
+    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void beginPass(QRhiCommandBuffer *cb,
+                   QRhiRenderTarget *rt,
+                   const QColor &colorClearValue,
+                   const QRhiDepthStencilClearValue &depthStencilClearValue,
+                   QRhiResourceUpdateBatch *resourceUpdates,
+                   QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void setGraphicsPipeline(QRhiCommandBuffer *cb,
+                             QRhiGraphicsPipeline *ps) override;
+
+    void setShaderResources(QRhiCommandBuffer *cb,
+                            QRhiShaderResourceBindings *srb,
+                            int dynamicOffsetCount,
+                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
+
+    void setVertexInput(QRhiCommandBuffer *cb,
+                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
+                        QRhiBuffer *indexBuf, quint32 indexOffset,
+                        QRhiCommandBuffer::IndexFormat indexFormat) override;
+
+    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
+    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
+    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
+    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
+
+    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
+              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
+
+    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
+                     quint32 instanceCount, quint32 firstIndex,
+                     qint32 vertexOffset, quint32 firstInstance) override;
+
+    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
+    void debugMarkEnd(QRhiCommandBuffer *cb) override;
+    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
+
+    void beginComputePass(QRhiCommandBuffer *cb,
+                          QRhiResourceUpdateBatch *resourceUpdates,
+                          QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
+    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
+
+    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
+    void beginExternal(QRhiCommandBuffer *cb) override;
+    void endExternal(QRhiCommandBuffer *cb) override;
+    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
+
+    QList<int> supportedSampleCounts() const override;
+    int ubufAlignment() const override;
+    bool isYUpInFramebuffer() const override;
+    bool isYUpInNDC() const override;
+    bool isClipDepthZeroToOne() const override;
+    QMatrix4x4 clipSpaceCorrMatrix() const override;
+    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
+    bool isFeatureSupported(QRhi::Feature feature) const override;
+    int resourceLimit(QRhi::ResourceLimit limit) const override;
+    const QRhiNativeHandles *nativeHandles() override;
+    QRhiDriverInfo driverInfo() const override;
+    QRhiStats statistics() override;
+    bool makeThreadLocalNativeContextCurrent() override;
+    void releaseCachedResources() override;
+    bool isDeviceLost() const override;
+
+    QByteArray pipelineCacheData() override;
+    void setPipelineCacheData(const QByteArray &data) override;
+
+    void simulateTextureUpload(const QRhiResourceUpdateBatchPrivate::TextureOp &u);
+    void simulateTextureCopy(const QRhiResourceUpdateBatchPrivate::TextureOp &u);
+    void simulateTextureGenMips(const QRhiResourceUpdateBatchPrivate::TextureOp &u);
+
+    QRhiNullNativeHandles nativeHandlesStruct;
+    QRhiSwapChain *currentSwapChain = nullptr;
+    QNullCommandBuffer offscreenCommandBuffer;
 };
 
 QT_END_NAMESPACE
diff --git a/src/gui/rhi/qrhinull_p_p.h b/src/gui/rhi/qrhinull_p_p.h
deleted file mode 100644
index 152622d117..0000000000
--- a/src/gui/rhi/qrhinull_p_p.h
+++ /dev/null
@@ -1,296 +0,0 @@
-// Copyright (C) 2019 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
-
-#ifndef QRHINULL_P_H
-#define QRHINULL_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists purely as an
-// implementation detail.  This header file may change from version to
-// version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qrhinull_p.h"
-#include "qrhi_p_p.h"
-
-QT_BEGIN_NAMESPACE
-
-struct QNullBuffer : public QRhiBuffer
-{
-    QNullBuffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
-    ~QNullBuffer();
-    void destroy() override;
-    bool create() override;
-    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
-
-    char *data = nullptr;
-};
-
-struct QNullRenderBuffer : public QRhiRenderBuffer
-{
-    QNullRenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
-                      int sampleCount, QRhiRenderBuffer::Flags flags,
-                      QRhiTexture::Format backingFormatHint);
-    ~QNullRenderBuffer();
-    void destroy() override;
-    bool create() override;
-    QRhiTexture::Format backingFormat() const override;
-
-    bool valid = false;
-    uint generation = 0;
-};
-
-struct QNullTexture : public QRhiTexture
-{
-    QNullTexture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
-                 int arraySize, int sampleCount, Flags flags);
-    ~QNullTexture();
-    void destroy() override;
-    bool create() override;
-    bool createFrom(NativeTexture src) override;
-
-    bool valid = false;
-    QVarLengthArray<std::array<QImage, QRhi::MAX_MIP_LEVELS>, 6> image;
-    uint generation = 0;
-};
-
-struct QNullSampler : public QRhiSampler
-{
-    QNullSampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
-                 AddressMode u, AddressMode v, AddressMode w);
-    ~QNullSampler();
-    void destroy() override;
-    bool create() override;
-};
-
-struct QNullRenderPassDescriptor : public QRhiRenderPassDescriptor
-{
-    QNullRenderPassDescriptor(QRhiImplementation *rhi);
-    ~QNullRenderPassDescriptor();
-    void destroy() override;
-    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
-    QVector<quint32> serializedFormat() const override;
-};
-
-struct QNullRenderTargetData
-{
-    QNullRenderTargetData(QRhiImplementation *) { }
-
-    QNullRenderPassDescriptor *rp = nullptr;
-    QSize pixelSize;
-    float dpr = 1;
-    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
-};
-
-struct QNullSwapChainRenderTarget : public QRhiSwapChainRenderTarget
-{
-    QNullSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
-    ~QNullSwapChainRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QNullRenderTargetData d;
-};
-
-struct QNullTextureRenderTarget : public QRhiTextureRenderTarget
-{
-    QNullTextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
-    ~QNullTextureRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool create() override;
-
-    QNullRenderTargetData d;
-};
-
-struct QNullShaderResourceBindings : public QRhiShaderResourceBindings
-{
-    QNullShaderResourceBindings(QRhiImplementation *rhi);
-    ~QNullShaderResourceBindings();
-    void destroy() override;
-    bool create() override;
-    void updateResources(UpdateFlags flags) override;
-};
-
-struct QNullGraphicsPipeline : public QRhiGraphicsPipeline
-{
-    QNullGraphicsPipeline(QRhiImplementation *rhi);
-    ~QNullGraphicsPipeline();
-    void destroy() override;
-    bool create() override;
-};
-
-struct QNullComputePipeline : public QRhiComputePipeline
-{
-    QNullComputePipeline(QRhiImplementation *rhi);
-    ~QNullComputePipeline();
-    void destroy() override;
-    bool create() override;
-};
-
-struct QNullCommandBuffer : public QRhiCommandBuffer
-{
-    QNullCommandBuffer(QRhiImplementation *rhi);
-    ~QNullCommandBuffer();
-    void destroy() override;
-};
-
-struct QNullSwapChain : public QRhiSwapChain
-{
-    QNullSwapChain(QRhiImplementation *rhi);
-    ~QNullSwapChain();
-    void destroy() override;
-
-    QRhiCommandBuffer *currentFrameCommandBuffer() override;
-    QRhiRenderTarget *currentFrameRenderTarget() override;
-
-    QSize surfacePixelSize() override;
-    bool isFormatSupported(Format f) override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool createOrResize() override;
-
-    QWindow *window = nullptr;
-    QNullSwapChainRenderTarget rt;
-    QNullCommandBuffer cb;
-    int frameCount = 0;
-};
-
-class QRhiNull : public QRhiImplementation
-{
-public:
-    QRhiNull(QRhiNullInitParams *params);
-
-    bool create(QRhi::Flags flags) override;
-    void destroy() override;
-
-    QRhiGraphicsPipeline *createGraphicsPipeline() override;
-    QRhiComputePipeline *createComputePipeline() override;
-    QRhiShaderResourceBindings *createShaderResourceBindings() override;
-    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
-                             QRhiBuffer::UsageFlags usage,
-                             quint32 size) override;
-    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
-                                         const QSize &pixelSize,
-                                         int sampleCount,
-                                         QRhiRenderBuffer::Flags flags,
-                                         QRhiTexture::Format backingFormatHint) override;
-    QRhiTexture *createTexture(QRhiTexture::Format format,
-                               const QSize &pixelSize,
-                               int depth,
-                               int arraySize,
-                               int sampleCount,
-                               QRhiTexture::Flags flags) override;
-    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
-                               QRhiSampler::Filter minFilter,
-                               QRhiSampler::Filter mipmapMode,
-                               QRhiSampler:: AddressMode u,
-                               QRhiSampler::AddressMode v,
-                               QRhiSampler::AddressMode w) override;
-
-    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
-                                                       QRhiTextureRenderTarget::Flags flags) override;
-
-    QRhiSwapChain *createSwapChain() override;
-    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult finish() override;
-
-    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void beginPass(QRhiCommandBuffer *cb,
-                   QRhiRenderTarget *rt,
-                   const QColor &colorClearValue,
-                   const QRhiDepthStencilClearValue &depthStencilClearValue,
-                   QRhiResourceUpdateBatch *resourceUpdates,
-                   QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void setGraphicsPipeline(QRhiCommandBuffer *cb,
-                             QRhiGraphicsPipeline *ps) override;
-
-    void setShaderResources(QRhiCommandBuffer *cb,
-                            QRhiShaderResourceBindings *srb,
-                            int dynamicOffsetCount,
-                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
-
-    void setVertexInput(QRhiCommandBuffer *cb,
-                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
-                        QRhiBuffer *indexBuf, quint32 indexOffset,
-                        QRhiCommandBuffer::IndexFormat indexFormat) override;
-
-    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
-    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
-    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
-    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
-
-    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
-              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
-
-    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
-                     quint32 instanceCount, quint32 firstIndex,
-                     qint32 vertexOffset, quint32 firstInstance) override;
-
-    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
-    void debugMarkEnd(QRhiCommandBuffer *cb) override;
-    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
-
-    void beginComputePass(QRhiCommandBuffer *cb,
-                          QRhiResourceUpdateBatch *resourceUpdates,
-                          QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
-    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
-
-    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
-    void beginExternal(QRhiCommandBuffer *cb) override;
-    void endExternal(QRhiCommandBuffer *cb) override;
-    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
-
-    QList<int> supportedSampleCounts() const override;
-    int ubufAlignment() const override;
-    bool isYUpInFramebuffer() const override;
-    bool isYUpInNDC() const override;
-    bool isClipDepthZeroToOne() const override;
-    QMatrix4x4 clipSpaceCorrMatrix() const override;
-    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
-    bool isFeatureSupported(QRhi::Feature feature) const override;
-    int resourceLimit(QRhi::ResourceLimit limit) const override;
-    const QRhiNativeHandles *nativeHandles() override;
-    QRhiDriverInfo driverInfo() const override;
-    QRhiStats statistics() override;
-    bool makeThreadLocalNativeContextCurrent() override;
-    void releaseCachedResources() override;
-    bool isDeviceLost() const override;
-
-    QByteArray pipelineCacheData() override;
-    void setPipelineCacheData(const QByteArray &data) override;
-
-    void simulateTextureUpload(const QRhiResourceUpdateBatchPrivate::TextureOp &u);
-    void simulateTextureCopy(const QRhiResourceUpdateBatchPrivate::TextureOp &u);
-    void simulateTextureGenMips(const QRhiResourceUpdateBatchPrivate::TextureOp &u);
-
-    QRhiNullNativeHandles nativeHandlesStruct;
-    QRhiSwapChain *currentSwapChain = nullptr;
-    QNullCommandBuffer offscreenCommandBuffer;
-};
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/rhi/qrhivulkan.cpp b/src/gui/rhi/qrhivulkan.cpp
index 2f8afb389a..6fe79f223e 100644
--- a/src/gui/rhi/qrhivulkan.cpp
+++ b/src/gui/rhi/qrhivulkan.cpp
@@ -1,7 +1,7 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#include "qrhivulkan_p_p.h"
+#include "qrhivulkan_p.h"
 #include "qrhivulkanext_p.h"
 #include <qpa/qplatformvulkaninstance.h>
 
@@ -60,10 +60,13 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QRhiVulkanInitParams
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Vulkan specific initialization parameters.
 
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
+
     A Vulkan-based QRhi needs at minimum a valid QVulkanInstance. It is up to
     the user to ensure this is available and initialized. This is typically
     done in main() similarly to the following:
@@ -166,18 +169,80 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
+    \variable QRhiVulkanInitParams::inst
+
+    The QVulkanInstance that has already been successfully
+    \l{QVulkanInstance::create()}{created}, required.
+*/
+
+/*!
+    \variable QRhiVulkanInitParams::window
+
+    Optional, but recommended when targeting a QWindow.
+*/
+
+/*!
+    \variable QRhiVulkanInitParams::deviceExtensions
+
+    Optional, empty by default. The list of Vulkan device extensions to enable.
+    Unsupported extensions are ignored gracefully.
+*/
+
+/*!
     \class QRhiVulkanNativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Collects device, queue, and other Vulkan objects that are used by the QRhi.
 
     \note Ownership of the Vulkan objects is never transferred.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
+    \variable QRhiVulkanNativeHandles::physDev
+
+    When different from \nullptr, specifies the Vulkan physical device to use.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::dev
+
+    When wanting to import not just a physical device, but also use an already
+    existing VkDevice, set this and the graphics queue index and family index.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::gfxQueueFamilyIdx
+
+    Graphics queue family index.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::gfxQueueIdx
+
+    Graphics queue index.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::gfxQueue
+
+    Output only, not used by QRhi::create(), only set by the
+    QRhi::nativeHandles() accessor. The graphics VkQueue used by the QRhi.
+*/
+
+/*!
+    \variable QRhiVulkanNativeHandles::vmemAllocator
+
+    Relevant only when importing an existing memory allocator object,
+    leave it set to \nullptr otherwise.
+*/
+
+/*!
     \class QRhiVulkanCommandBufferNativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Holds the Vulkan command buffer object that is backing a QRhiCommandBuffer.
 
     \note The Vulkan command buffer object is only guaranteed to be valid, and
@@ -185,15 +250,33 @@ QT_BEGIN_NAMESPACE
     \l{QRhi::beginFrame()}{beginFrame()} - \l{QRhi::endFrame()}{endFrame()} or
     \l{QRhi::beginOffscreenFrame()}{beginOffscreenFrame()} -
     \l{QRhi::endOffscreenFrame()}{endOffscreenFrame()} pair.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
 /*!
+    \variable QRhiVulkanCommandBufferNativeHandles::commandBuffer
+
+    The VkCommandBuffer object.
+*/
+
+/*!
     \class QRhiVulkanRenderPassNativeHandles
-    \internal
     \inmodule QtGui
+    \since 6.6
     \brief Holds the Vulkan render pass object backing a QRhiRenderPassDescriptor.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QRhi
+    for details.
  */
 
+/*!
+    \variable QRhiVulkanRenderPassNativeHandles::renderPass
+
+    The VkRenderPass object.
+*/
+
 template <class Int>
 inline Int aligned(Int v, Int byteAlign)
 {
@@ -222,6 +305,13 @@ static inline VmaAllocator toVmaAllocator(QVkAllocator a)
     return reinterpret_cast<VmaAllocator>(a);
 }
 
+/*!
+    \return the list of instance extensions that are expected to be enabled on
+    the QVulkanInstance that is used for the Vulkan-based QRhi.
+
+    The returned list can be safely passed to QVulkanInstance::setExtensions()
+    as-is, because unsupported extensions are filtered out automatically.
+ */
 QByteArrayList QRhiVulkanInitParams::preferredInstanceExtensions()
 {
     return {
@@ -229,6 +319,11 @@ QByteArrayList QRhiVulkanInitParams::preferredInstanceExtensions()
     };
 }
 
+/*!
+    \return the list of device extensions that are expected to be enabled on the
+    \c VkDevice when creating a Vulkan-based QRhi with an externally created
+    \c VkDevice object.
+ */
 QByteArrayList QRhiVulkanInitParams::preferredExtensionsForImportedDevice()
 {
     return {
diff --git a/src/gui/rhi/qrhivulkan_p.h b/src/gui/rhi/qrhivulkan_p.h
index f592cf7e54..7ba1b8c89b 100644
--- a/src/gui/rhi/qrhivulkan_p.h
+++ b/src/gui/rhi/qrhivulkan_p.h
@@ -1,8 +1,8 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#ifndef QRHIVULKAN_H
-#define QRHIVULKAN_H
+#ifndef QRHIVULKAN_P_H
+#define QRHIVULKAN_P_H
 
 //
 //  W A R N I N G
@@ -15,44 +15,991 @@
 // We mean it.
 //
 
-#include <private/qrhi_p.h>
-#include <QtGui/qvulkaninstance.h> // this is where vulkan.h gets pulled in
+#include "qrhi_p.h"
 
 QT_BEGIN_NAMESPACE
 
-struct Q_GUI_EXPORT QRhiVulkanInitParams : public QRhiInitParams
+class QVulkanFunctions;
+class QVulkanDeviceFunctions;
+
+static const int QVK_FRAMES_IN_FLIGHT = 2;
+
+static const int QVK_DESC_SETS_PER_POOL = 128;
+static const int QVK_UNIFORM_BUFFERS_PER_POOL = 256;
+static const int QVK_COMBINED_IMAGE_SAMPLERS_PER_POOL = 256;
+static const int QVK_STORAGE_BUFFERS_PER_POOL = 128;
+static const int QVK_STORAGE_IMAGES_PER_POOL = 128;
+
+static const int QVK_MAX_ACTIVE_TIMESTAMP_PAIRS = 16;
+
+// no vk_mem_alloc.h available here, void* is good enough
+typedef void * QVkAlloc;
+typedef void * QVkAllocator;
+
+struct QVkBuffer : public QRhiBuffer
 {
-    QVulkanInstance *inst = nullptr;
+    QVkBuffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
+    ~QVkBuffer();
+    void destroy() override;
+    bool create() override;
+    QRhiBuffer::NativeBuffer nativeBuffer() override;
+    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
+    void endFullDynamicBufferUpdateForCurrentFrame() override;
+
+    VkBuffer buffers[QVK_FRAMES_IN_FLIGHT];
+    QVkAlloc allocations[QVK_FRAMES_IN_FLIGHT];
+    struct DynamicUpdate {
+        quint32 offset;
+        QRhiBufferData data;
+    };
+    QVarLengthArray<DynamicUpdate, 16> pendingDynamicUpdates[QVK_FRAMES_IN_FLIGHT];
+    VkBuffer stagingBuffers[QVK_FRAMES_IN_FLIGHT];
+    QVkAlloc stagingAllocations[QVK_FRAMES_IN_FLIGHT];
+    struct UsageState {
+        VkAccessFlags access = 0;
+        VkPipelineStageFlags stage = 0;
+    };
+    UsageState usageState[QVK_FRAMES_IN_FLIGHT];
+    int lastActiveFrameSlot = -1;
+    uint generation = 0;
+    friend class QRhiVulkan;
+};
+
+Q_DECLARE_TYPEINFO(QVkBuffer::DynamicUpdate, Q_RELOCATABLE_TYPE);
+
+struct QVkTexture;
+
+struct QVkRenderBuffer : public QRhiRenderBuffer
+{
+    QVkRenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
+                    int sampleCount, Flags flags,
+                    QRhiTexture::Format backingFormatHint);
+    ~QVkRenderBuffer();
+    void destroy() override;
+    bool create() override;
+    QRhiTexture::Format backingFormat() const override;
+
+    VkDeviceMemory memory = VK_NULL_HANDLE;
+    VkImage image = VK_NULL_HANDLE;
+    VkImageView imageView = VK_NULL_HANDLE;
+    VkSampleCountFlagBits samples;
+    QVkTexture *backingTexture = nullptr;
+    VkFormat vkformat;
+    int lastActiveFrameSlot = -1;
+    uint generation = 0;
+    friend class QRhiVulkan;
+};
+
+struct QVkTexture : public QRhiTexture
+{
+    QVkTexture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
+               int arraySize, int sampleCount, Flags flags);
+    ~QVkTexture();
+    void destroy() override;
+    bool create() override;
+    bool createFrom(NativeTexture src) override;
+    NativeTexture nativeTexture() override;
+    void setNativeLayout(int layout) override;
+
+    bool prepareCreate(QSize *adjustedSize = nullptr);
+    bool finishCreate();
+    VkImageView imageViewForLevel(int level);
+
+    VkImage image = VK_NULL_HANDLE;
+    VkImageView imageView = VK_NULL_HANDLE;
+    QVkAlloc imageAlloc = nullptr;
+    VkBuffer stagingBuffers[QVK_FRAMES_IN_FLIGHT];
+    QVkAlloc stagingAllocations[QVK_FRAMES_IN_FLIGHT];
+    VkImageView perLevelImageViews[QRhi::MAX_MIP_LEVELS];
+    bool owns = true;
+    struct UsageState {
+        // no tracking of subresource layouts (some operations can keep
+        // subresources in different layouts for some time, but that does not
+        // need to be kept track of)
+        VkImageLayout layout;
+        VkAccessFlags access;
+        VkPipelineStageFlags stage;
+    };
+    UsageState usageState;
+    VkFormat vkformat;
+    uint mipLevelCount = 0;
+    VkSampleCountFlagBits samples;
+    int lastActiveFrameSlot = -1;
+    uint generation = 0;
+    friend class QRhiVulkan;
+};
+
+struct QVkSampler : public QRhiSampler
+{
+    QVkSampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
+               AddressMode u, AddressMode v, AddressMode w);
+    ~QVkSampler();
+    void destroy() override;
+    bool create() override;
+
+    VkSampler sampler = VK_NULL_HANDLE;
+    int lastActiveFrameSlot = -1;
+    uint generation = 0;
+    friend class QRhiVulkan;
+};
+
+struct QVkRenderPassDescriptor : public QRhiRenderPassDescriptor
+{
+    QVkRenderPassDescriptor(QRhiImplementation *rhi);
+    ~QVkRenderPassDescriptor();
+    void destroy() override;
+    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
+    QVector<quint32> serializedFormat() const override;
+    const QRhiNativeHandles *nativeHandles() override;
+
+    void updateSerializedFormat();
+
+    VkRenderPass rp = VK_NULL_HANDLE;
+    bool ownsRp = false;
+    QVarLengthArray<VkAttachmentDescription, 8> attDescs;
+    QVarLengthArray<VkAttachmentReference, 8> colorRefs;
+    QVarLengthArray<VkAttachmentReference, 8> resolveRefs;
+    QVarLengthArray<VkSubpassDependency, 2> subpassDeps;
+    bool hasDepthStencil = false;
+    VkAttachmentReference dsRef;
+    QVector<quint32> serializedFormatData;
+    QRhiVulkanRenderPassNativeHandles nativeHandlesStruct;
+    int lastActiveFrameSlot = -1;
+};
+
+struct QVkRenderTargetData
+{
+    VkFramebuffer fb = VK_NULL_HANDLE;
+    QVkRenderPassDescriptor *rp = nullptr;
+    QSize pixelSize;
+    float dpr = 1;
+    int sampleCount = 1;
+    int colorAttCount = 0;
+    int dsAttCount = 0;
+    int resolveAttCount = 0;
+    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
+    static const int MAX_COLOR_ATTACHMENTS = 8;
+};
+
+struct QVkSwapChainRenderTarget : public QRhiSwapChainRenderTarget
+{
+    QVkSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
+    ~QVkSwapChainRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QVkRenderTargetData d;
+};
+
+struct QVkTextureRenderTarget : public QRhiTextureRenderTarget
+{
+    QVkTextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
+    ~QVkTextureRenderTarget();
+    void destroy() override;
+
+    QSize pixelSize() const override;
+    float devicePixelRatio() const override;
+    int sampleCount() const override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool create() override;
+
+    QVkRenderTargetData d;
+    VkImageView rtv[QVkRenderTargetData::MAX_COLOR_ATTACHMENTS];
+    VkImageView resrtv[QVkRenderTargetData::MAX_COLOR_ATTACHMENTS];
+    int lastActiveFrameSlot = -1;
+    friend class QRhiVulkan;
+};
+
+struct QVkShaderResourceBindings : public QRhiShaderResourceBindings
+{
+    QVkShaderResourceBindings(QRhiImplementation *rhi);
+    ~QVkShaderResourceBindings();
+    void destroy() override;
+    bool create() override;
+    void updateResources(UpdateFlags flags) override;
+
+    QVarLengthArray<QRhiShaderResourceBinding, 8> sortedBindings;
+    bool hasSlottedResource = false;
+    bool hasDynamicOffset = false;
+    int poolIndex = -1;
+    VkDescriptorSetLayout layout = VK_NULL_HANDLE;
+    VkDescriptorSet descSets[QVK_FRAMES_IN_FLIGHT]; // multiple sets to support dynamic buffers
+    int lastActiveFrameSlot = -1;
+    uint generation = 0;
+
+    // Keep track of the generation number of each referenced QRhi* to be able
+    // to detect that the underlying descriptor set became out of date and they
+    // need to be written again with the up-to-date VkBuffer etc. objects.
+    struct BoundUniformBufferData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundSampledTextureData {
+        int count;
+        struct {
+            quint64 texId;
+            uint texGeneration;
+            quint64 samplerId;
+            uint samplerGeneration;
+        } d[QRhiShaderResourceBinding::Data::MAX_TEX_SAMPLER_ARRAY_SIZE];
+    };
+    struct BoundStorageImageData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundStorageBufferData {
+        quint64 id;
+        uint generation;
+    };
+    struct BoundResourceData {
+        union {
+            BoundUniformBufferData ubuf;
+            BoundSampledTextureData stex;
+            BoundStorageImageData simage;
+            BoundStorageBufferData sbuf;
+        };
+    };
+    QVarLengthArray<BoundResourceData, 8> boundResourceData[QVK_FRAMES_IN_FLIGHT];
+
+    friend class QRhiVulkan;
+};
+
+Q_DECLARE_TYPEINFO(QVkShaderResourceBindings::BoundResourceData, Q_RELOCATABLE_TYPE);
+
+struct QVkGraphicsPipeline : public QRhiGraphicsPipeline
+{
+    QVkGraphicsPipeline(QRhiImplementation *rhi);
+    ~QVkGraphicsPipeline();
+    void destroy() override;
+    bool create() override;
+
+    VkPipelineLayout layout = VK_NULL_HANDLE;
+    VkPipeline pipeline = VK_NULL_HANDLE;
+    int lastActiveFrameSlot = -1;
+    uint generation = 0;
+    friend class QRhiVulkan;
+};
+
+struct QVkComputePipeline : public QRhiComputePipeline
+{
+    QVkComputePipeline(QRhiImplementation *rhi);
+    ~QVkComputePipeline();
+    void destroy() override;
+    bool create() override;
+
+    VkPipelineLayout layout = VK_NULL_HANDLE;
+    VkPipeline pipeline = VK_NULL_HANDLE;
+    int lastActiveFrameSlot = -1;
+    uint generation = 0;
+    friend class QRhiVulkan;
+};
+
+struct QVkCommandBuffer : public QRhiCommandBuffer
+{
+    QVkCommandBuffer(QRhiImplementation *rhi);
+    ~QVkCommandBuffer();
+    void destroy() override;
+
+    const QRhiNativeHandles *nativeHandles();
+
+    VkCommandBuffer cb = VK_NULL_HANDLE; // primary
+    QRhiVulkanCommandBufferNativeHandles nativeHandlesStruct;
+
+    enum PassType {
+        NoPass,
+        RenderPass,
+        ComputePass
+    };
+
+    void resetState() {
+        recordingPass = NoPass;
+        passUsesSecondaryCb = false;
+        lastGpuTime = 0;
+        currentTarget = nullptr;
+        activeSecondaryCbStack.clear();
+        resetCommands();
+        resetCachedState();
+    }
+
+    void resetCachedState() {
+        currentGraphicsPipeline = nullptr;
+        currentComputePipeline = nullptr;
+        currentPipelineGeneration = 0;
+        currentGraphicsSrb = nullptr;
+        currentComputeSrb = nullptr;
+        currentSrbGeneration = 0;
+        currentDescSetSlot = -1;
+        currentIndexBuffer = VK_NULL_HANDLE;
+        currentIndexOffset = 0;
+        currentIndexFormat = VK_INDEX_TYPE_UINT16;
+        memset(currentVertexBuffers, 0, sizeof(currentVertexBuffers));
+        memset(currentVertexOffsets, 0, sizeof(currentVertexOffsets));
+        inExternal = false;
+    }
+
+    PassType recordingPass;
+    bool passUsesSecondaryCb;
+    double lastGpuTime = 0;
+    QRhiRenderTarget *currentTarget;
+    QRhiGraphicsPipeline *currentGraphicsPipeline;
+    QRhiComputePipeline *currentComputePipeline;
+    uint currentPipelineGeneration;
+    QRhiShaderResourceBindings *currentGraphicsSrb;
+    QRhiShaderResourceBindings *currentComputeSrb;
+    uint currentSrbGeneration;
+    int currentDescSetSlot;
+    VkBuffer currentIndexBuffer;
+    quint32 currentIndexOffset;
+    VkIndexType currentIndexFormat;
+    static const int VERTEX_INPUT_RESOURCE_SLOT_COUNT = 32;
+    VkBuffer currentVertexBuffers[VERTEX_INPUT_RESOURCE_SLOT_COUNT];
+    quint32 currentVertexOffsets[VERTEX_INPUT_RESOURCE_SLOT_COUNT];
+    QVarLengthArray<VkCommandBuffer, 4> activeSecondaryCbStack;
+    bool inExternal;
+
+    struct {
+        QHash<QRhiResource *, QPair<VkAccessFlags, bool> > writtenResources;
+        void reset() {
+            writtenResources.clear();
+        }
+    } computePassState;
+
+    struct Command {
+        enum Cmd {
+            CopyBuffer,
+            CopyBufferToImage,
+            CopyImage,
+            CopyImageToBuffer,
+            ImageBarrier,
+            BufferBarrier,
+            BlitImage,
+            BeginRenderPass,
+            EndRenderPass,
+            BindPipeline,
+            BindDescriptorSet,
+            BindVertexBuffer,
+            BindIndexBuffer,
+            SetViewport,
+            SetScissor,
+            SetBlendConstants,
+            SetStencilRef,
+            Draw,
+            DrawIndexed,
+            DebugMarkerBegin,
+            DebugMarkerEnd,
+            DebugMarkerInsert,
+            TransitionPassResources,
+            Dispatch,
+            ExecuteSecondary
+        };
+        Cmd cmd;
+
+        union Args {
+            struct {
+                VkBuffer src;
+                VkBuffer dst;
+                VkBufferCopy desc;
+            } copyBuffer;
+            struct {
+                VkBuffer src;
+                VkImage dst;
+                VkImageLayout dstLayout;
+                int count;
+                int bufferImageCopyIndex;
+            } copyBufferToImage;
+            struct {
+                VkImage src;
+                VkImageLayout srcLayout;
+                VkImage dst;
+                VkImageLayout dstLayout;
+                VkImageCopy desc;
+            } copyImage;
+            struct {
+                VkImage src;
+                VkImageLayout srcLayout;
+                VkBuffer dst;
+                VkBufferImageCopy desc;
+            } copyImageToBuffer;
+            struct {
+                VkPipelineStageFlags srcStageMask;
+                VkPipelineStageFlags dstStageMask;
+                int count;
+                int index;
+            } imageBarrier;
+            struct {
+                VkPipelineStageFlags srcStageMask;
+                VkPipelineStageFlags dstStageMask;
+                int count;
+                int index;
+            } bufferBarrier;
+            struct {
+                VkImage src;
+                VkImageLayout srcLayout;
+                VkImage dst;
+                VkImageLayout dstLayout;
+                VkFilter filter;
+                VkImageBlit desc;
+            } blitImage;
+            struct {
+                VkRenderPassBeginInfo desc;
+                int clearValueIndex;
+                bool useSecondaryCb;
+            } beginRenderPass;
+            struct {
+            } endRenderPass;
+            struct {
+                VkPipelineBindPoint bindPoint;
+                VkPipeline pipeline;
+            } bindPipeline;
+            struct {
+                VkPipelineBindPoint bindPoint;
+                VkPipelineLayout pipelineLayout;
+                VkDescriptorSet descSet;
+                int dynamicOffsetCount;
+                int dynamicOffsetIndex;
+            } bindDescriptorSet;
+            struct {
+                int startBinding;
+                int count;
+                int vertexBufferIndex;
+                int vertexBufferOffsetIndex;
+            } bindVertexBuffer;
+            struct {
+                VkBuffer buf;
+                VkDeviceSize ofs;
+                VkIndexType type;
+            } bindIndexBuffer;
+            struct {
+                VkViewport viewport;
+            } setViewport;
+            struct {
+                VkRect2D scissor;
+            } setScissor;
+            struct {
+                float c[4];
+            } setBlendConstants;
+            struct {
+                uint32_t ref;
+            } setStencilRef;
+            struct {
+                uint32_t vertexCount;
+                uint32_t instanceCount;
+                uint32_t firstVertex;
+                uint32_t firstInstance;
+            } draw;
+            struct {
+                uint32_t indexCount;
+                uint32_t instanceCount;
+                uint32_t firstIndex;
+                int32_t vertexOffset;
+                uint32_t firstInstance;
+            } drawIndexed;
+            struct {
+#ifdef VK_EXT_debug_utils
+                VkDebugUtilsLabelEXT label;
+                int labelNameIndex;
+#endif
+            } debugMarkerBegin;
+            struct {
+            } debugMarkerEnd;
+            struct {
+#ifdef VK_EXT_debug_utils
+                VkDebugUtilsLabelEXT label;
+                int labelNameIndex;
+#endif
+            } debugMarkerInsert;
+            struct {
+                int trackerIndex;
+            } transitionResources;
+            struct {
+                int x, y, z;
+            } dispatch;
+            struct {
+                VkCommandBuffer cb;
+            } executeSecondary;
+        } args;
+    };
+
+    QRhiBackendCommandList<Command> commands;
+    QVarLengthArray<QRhiPassResourceTracker, 8> passResTrackers;
+    int currentPassResTrackerIndex;
+
+    void resetCommands() {
+        commands.reset();
+        resetPools();
+
+        passResTrackers.clear();
+        currentPassResTrackerIndex = -1;
+    }
+
+    void resetPools() {
+        pools.clearValue.clear();
+        pools.bufferImageCopy.clear();
+        pools.dynamicOffset.clear();
+        pools.vertexBuffer.clear();
+        pools.vertexBufferOffset.clear();
+        pools.debugMarkerData.clear();
+        pools.imageBarrier.clear();
+        pools.bufferBarrier.clear();
+    }
+
+    struct {
+        QVarLengthArray<VkClearValue, 4> clearValue;
+        QVarLengthArray<VkBufferImageCopy, 16> bufferImageCopy;
+        QVarLengthArray<uint32_t, 4> dynamicOffset;
+        QVarLengthArray<VkBuffer, 4> vertexBuffer;
+        QVarLengthArray<VkDeviceSize, 4> vertexBufferOffset;
+        QVarLengthArray<QByteArray, 4> debugMarkerData;
+        QVarLengthArray<VkImageMemoryBarrier, 8> imageBarrier;
+        QVarLengthArray<VkBufferMemoryBarrier, 8> bufferBarrier;
+    } pools;
+
+    friend class QRhiVulkan;
+};
+
+struct QVkSwapChain : public QRhiSwapChain
+{
+    QVkSwapChain(QRhiImplementation *rhi);
+    ~QVkSwapChain();
+    void destroy() override;
+
+    QRhiCommandBuffer *currentFrameCommandBuffer() override;
+    QRhiRenderTarget *currentFrameRenderTarget() override;
+
+    QSize surfacePixelSize() override;
+    bool isFormatSupported(Format f) override;
+
+    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
+    bool createOrResize() override;
+
+    bool ensureSurface();
+
+    static const quint32 EXPECTED_MAX_BUFFER_COUNT = 4;
+
     QWindow *window = nullptr;
-    QByteArrayList deviceExtensions;
+    QSize pixelSize;
+    bool supportsReadback = false;
+    VkSwapchainKHR sc = VK_NULL_HANDLE;
+    int bufferCount = 0;
+    VkSurfaceKHR surface = VK_NULL_HANDLE;
+    VkSurfaceKHR lastConnectedSurface = VK_NULL_HANDLE;
+    VkFormat colorFormat = VK_FORMAT_B8G8R8A8_UNORM;
+    VkColorSpaceKHR colorSpace = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR;
+    QVkRenderBuffer *ds = nullptr;
+    VkSampleCountFlagBits samples = VK_SAMPLE_COUNT_1_BIT;
+    QVarLengthArray<VkPresentModeKHR, 8> supportedPresentationModes;
+    VkDeviceMemory msaaImageMem = VK_NULL_HANDLE;
+    QVkSwapChainRenderTarget rtWrapper;
+    QVkCommandBuffer cbWrapper;
+
+    struct ImageResources {
+        VkImage image = VK_NULL_HANDLE;
+        VkImageView imageView = VK_NULL_HANDLE;
+        VkFramebuffer fb = VK_NULL_HANDLE;
+        VkImage msaaImage = VK_NULL_HANDLE;
+        VkImageView msaaImageView = VK_NULL_HANDLE;
+        enum LastUse {
+            ScImageUseNone,
+            ScImageUseRender,
+            ScImageUseTransferSource
+        };
+        LastUse lastUse = ScImageUseNone;
+    };
+    QVarLengthArray<ImageResources, EXPECTED_MAX_BUFFER_COUNT> imageRes;
+
+    struct FrameResources {
+        VkFence imageFence = VK_NULL_HANDLE;
+        bool imageFenceWaitable = false;
+        VkSemaphore imageSem = VK_NULL_HANDLE;
+        VkSemaphore drawSem = VK_NULL_HANDLE;
+        bool imageAcquired = false;
+        bool imageSemWaitable = false;
+        VkFence cmdFence = VK_NULL_HANDLE;
+        bool cmdFenceWaitable = false;
+        VkCommandBuffer cmdBuf = VK_NULL_HANDLE; // primary
+        int timestampQueryIndex = -1;
+    } frameRes[QVK_FRAMES_IN_FLIGHT];
 
-    static QByteArrayList preferredInstanceExtensions();
-    static QByteArrayList preferredExtensionsForImportedDevice();
+    quint32 currentImageIndex = 0; // index in imageRes
+    quint32 currentFrameSlot = 0; // index in frameRes
+    int frameCount = 0;
+
+    friend class QRhiVulkan;
 };
 
-struct Q_GUI_EXPORT QRhiVulkanNativeHandles : public QRhiNativeHandles
+class QRhiVulkan : public QRhiImplementation
 {
-    // to import a physical device (always required)
+public:
+    QRhiVulkan(QRhiVulkanInitParams *params, QRhiVulkanNativeHandles *importParams = nullptr);
+
+    bool create(QRhi::Flags flags) override;
+    void destroy() override;
+
+    QRhiGraphicsPipeline *createGraphicsPipeline() override;
+    QRhiComputePipeline *createComputePipeline() override;
+    QRhiShaderResourceBindings *createShaderResourceBindings() override;
+    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
+                             QRhiBuffer::UsageFlags usage,
+                             quint32 size) override;
+    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
+                                         const QSize &pixelSize,
+                                         int sampleCount,
+                                         QRhiRenderBuffer::Flags flags,
+                                         QRhiTexture::Format backingFormatHint) override;
+    QRhiTexture *createTexture(QRhiTexture::Format format,
+                               const QSize &pixelSize,
+                               int depth,
+                               int arraySize,
+                               int sampleCount,
+                               QRhiTexture::Flags flags) override;
+    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
+                               QRhiSampler::Filter minFilter,
+                               QRhiSampler::Filter mipmapMode,
+                               QRhiSampler:: AddressMode u,
+                               QRhiSampler::AddressMode v,
+                               QRhiSampler::AddressMode w) override;
+
+    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
+                                                       QRhiTextureRenderTarget::Flags flags) override;
+
+    QRhiSwapChain *createSwapChain() override;
+    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
+    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
+    QRhi::FrameOpResult finish() override;
+
+    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void beginPass(QRhiCommandBuffer *cb,
+                   QRhiRenderTarget *rt,
+                   const QColor &colorClearValue,
+                   const QRhiDepthStencilClearValue &depthStencilClearValue,
+                   QRhiResourceUpdateBatch *resourceUpdates,
+                   QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+
+    void setGraphicsPipeline(QRhiCommandBuffer *cb,
+                             QRhiGraphicsPipeline *ps) override;
+
+    void setShaderResources(QRhiCommandBuffer *cb,
+                            QRhiShaderResourceBindings *srb,
+                            int dynamicOffsetCount,
+                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
+
+    void setVertexInput(QRhiCommandBuffer *cb,
+                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
+                        QRhiBuffer *indexBuf, quint32 indexOffset,
+                        QRhiCommandBuffer::IndexFormat indexFormat) override;
+
+    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
+    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
+    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
+    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
+
+    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
+              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
+
+    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
+                     quint32 instanceCount, quint32 firstIndex,
+                     qint32 vertexOffset, quint32 firstInstance) override;
+
+    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
+    void debugMarkEnd(QRhiCommandBuffer *cb) override;
+    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
+
+    void beginComputePass(QRhiCommandBuffer *cb,
+                          QRhiResourceUpdateBatch *resourceUpdates,
+                          QRhiCommandBuffer::BeginPassFlags flags) override;
+    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
+    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
+    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
+
+    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
+    void beginExternal(QRhiCommandBuffer *cb) override;
+    void endExternal(QRhiCommandBuffer *cb) override;
+    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
+
+    QList<int> supportedSampleCounts() const override;
+    int ubufAlignment() const override;
+    bool isYUpInFramebuffer() const override;
+    bool isYUpInNDC() const override;
+    bool isClipDepthZeroToOne() const override;
+    QMatrix4x4 clipSpaceCorrMatrix() const override;
+    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
+    bool isFeatureSupported(QRhi::Feature feature) const override;
+    int resourceLimit(QRhi::ResourceLimit limit) const override;
+    const QRhiNativeHandles *nativeHandles() override;
+    QRhiDriverInfo driverInfo() const override;
+    QRhiStats statistics() override;
+    bool makeThreadLocalNativeContextCurrent() override;
+    void releaseCachedResources() override;
+    bool isDeviceLost() const override;
+
+    QByteArray pipelineCacheData() override;
+    void setPipelineCacheData(const QByteArray &data) override;
+
+    VkResult createDescriptorPool(VkDescriptorPool *pool);
+    bool allocateDescriptorSet(VkDescriptorSetAllocateInfo *allocInfo, VkDescriptorSet *result, int *resultPoolIndex);
+    uint32_t chooseTransientImageMemType(VkImage img, uint32_t startIndex);
+    bool createTransientImage(VkFormat format, const QSize &pixelSize, VkImageUsageFlags usage,
+                              VkImageAspectFlags aspectMask, VkSampleCountFlagBits samples,
+                              VkDeviceMemory *mem, VkImage *images, VkImageView *views, int count);
+
+    bool recreateSwapChain(QRhiSwapChain *swapChain);
+    void releaseSwapChainResources(QRhiSwapChain *swapChain);
+
+    VkFormat optimalDepthStencilFormat();
+    VkSampleCountFlagBits effectiveSampleCount(int sampleCount);
+    bool createDefaultRenderPass(QVkRenderPassDescriptor *rpD,
+                                 bool hasDepthStencil,
+                                 VkSampleCountFlagBits samples,
+                                 VkFormat colorFormat);
+    bool createOffscreenRenderPass(QVkRenderPassDescriptor *rpD,
+                                   const QRhiColorAttachment *firstColorAttachment,
+                                   const QRhiColorAttachment *lastColorAttachment,
+                                   bool preserveColor,
+                                   bool preserveDs,
+                                   QRhiRenderBuffer *depthStencilBuffer,
+                                   QRhiTexture *depthTexture);
+    bool ensurePipelineCache(const void *initialData = nullptr, size_t initialDataSize = 0);
+    VkShaderModule createShader(const QByteArray &spirv);
+
+    void prepareNewFrame(QRhiCommandBuffer *cb);
+    VkCommandBuffer startSecondaryCommandBuffer(QVkRenderTargetData *rtD = nullptr);
+    void endAndEnqueueSecondaryCommandBuffer(VkCommandBuffer cb, QVkCommandBuffer *cbD);
+    QRhi::FrameOpResult startPrimaryCommandBuffer(VkCommandBuffer *cb);
+    QRhi::FrameOpResult endAndSubmitPrimaryCommandBuffer(VkCommandBuffer cb, VkFence cmdFence,
+                                                         VkSemaphore *waitSem, VkSemaphore *signalSem);
+    void waitCommandCompletion(int frameSlot);
+    VkDeviceSize subresUploadByteSize(const QRhiTextureSubresourceUploadDescription &subresDesc) const;
+    using BufferImageCopyList = QVarLengthArray<VkBufferImageCopy, 16>;
+    void prepareUploadSubres(QVkTexture *texD, int layer, int level,
+                             const QRhiTextureSubresourceUploadDescription &subresDesc,
+                             size_t *curOfs, void *mp,
+                             BufferImageCopyList *copyInfos);
+    void enqueueResourceUpdates(QVkCommandBuffer *cbD, QRhiResourceUpdateBatch *resourceUpdates);
+    void executeBufferHostWritesForSlot(QVkBuffer *bufD, int slot);
+    void enqueueTransitionPassResources(QVkCommandBuffer *cbD);
+    void recordPrimaryCommandBuffer(QVkCommandBuffer *cbD);
+    void trackedRegisterBuffer(QRhiPassResourceTracker *passResTracker,
+                               QVkBuffer *bufD,
+                               int slot,
+                               QRhiPassResourceTracker::BufferAccess access,
+                               QRhiPassResourceTracker::BufferStage stage);
+    void trackedRegisterTexture(QRhiPassResourceTracker *passResTracker,
+                                QVkTexture *texD,
+                                QRhiPassResourceTracker::TextureAccess access,
+                                QRhiPassResourceTracker::TextureStage stage);
+    void recordTransitionPassResources(QVkCommandBuffer *cbD, const QRhiPassResourceTracker &tracker);
+    void activateTextureRenderTarget(QVkCommandBuffer *cbD, QVkTextureRenderTarget *rtD);
+    void executeDeferredReleases(bool forced = false);
+    void finishActiveReadbacks(bool forced = false);
+
+    void setObjectName(uint64_t object, VkObjectType type, const QByteArray &name, int slot = -1);
+    void trackedBufferBarrier(QVkCommandBuffer *cbD, QVkBuffer *bufD, int slot,
+                              VkAccessFlags access, VkPipelineStageFlags stage);
+    void trackedImageBarrier(QVkCommandBuffer *cbD, QVkTexture *texD,
+                             VkImageLayout layout, VkAccessFlags access, VkPipelineStageFlags stage);
+    void depthStencilExplicitBarrier(QVkCommandBuffer *cbD, QVkRenderBuffer *rbD);
+    void subresourceBarrier(QVkCommandBuffer *cbD, VkImage image,
+                            VkImageLayout oldLayout, VkImageLayout newLayout,
+                            VkAccessFlags srcAccess, VkAccessFlags dstAccess,
+                            VkPipelineStageFlags srcStage, VkPipelineStageFlags dstStage,
+                            int startLayer, int layerCount,
+                            int startLevel, int levelCount);
+    void updateShaderResourceBindings(QRhiShaderResourceBindings *srb, int descSetIdx = -1);
+    void ensureCommandPoolForNewFrame();
+    double elapsedSecondsFromTimestamp(quint64 timestamp[2], bool *ok);
+
+    QVulkanInstance *inst = nullptr;
+    QWindow *maybeWindow = nullptr;
+    QByteArrayList requestedDeviceExtensions;
+    bool importedDevice = false;
     VkPhysicalDevice physDev = VK_NULL_HANDLE;
-    // to import a device and queue
     VkDevice dev = VK_NULL_HANDLE;
+    VkCommandPool cmdPool[QVK_FRAMES_IN_FLIGHT] = {};
     quint32 gfxQueueFamilyIdx = 0;
     quint32 gfxQueueIdx = 0;
     VkQueue gfxQueue = VK_NULL_HANDLE;
-    // and optionally, the mem allocator
-    void *vmemAllocator = nullptr;
-};
+    quint32 timestampValidBits = 0;
+    bool importedAllocator = false;
+    QVkAllocator allocator = nullptr;
+    QVulkanFunctions *f = nullptr;
+    QVulkanDeviceFunctions *df = nullptr;
+    QRhi::Flags rhiFlags;
+    VkPhysicalDeviceFeatures physDevFeatures;
+    VkPhysicalDeviceProperties physDevProperties;
+    VkDeviceSize ubufAlign;
+    VkDeviceSize texbufAlign;
+    bool deviceLost = false;
+    bool releaseCachedResourcesCalledBeforeFrameStart = false;
 
-struct Q_GUI_EXPORT QRhiVulkanCommandBufferNativeHandles : public QRhiNativeHandles
-{
-    VkCommandBuffer commandBuffer = VK_NULL_HANDLE;
-};
+#ifdef VK_EXT_debug_utils
+    PFN_vkSetDebugUtilsObjectNameEXT vkSetDebugUtilsObjectNameEXT = nullptr;
+    PFN_vkCmdBeginDebugUtilsLabelEXT vkCmdBeginDebugUtilsLabelEXT = nullptr;
+    PFN_vkCmdEndDebugUtilsLabelEXT vkCmdEndDebugUtilsLabelEXT = nullptr;
+    PFN_vkCmdInsertDebugUtilsLabelEXT vkCmdInsertDebugUtilsLabelEXT = nullptr;
+#endif
 
-struct Q_GUI_EXPORT QRhiVulkanRenderPassNativeHandles : public QRhiNativeHandles
-{
-    VkRenderPass renderPass = VK_NULL_HANDLE;
+    PFN_vkCreateSwapchainKHR vkCreateSwapchainKHR = nullptr;
+    PFN_vkDestroySwapchainKHR vkDestroySwapchainKHR;
+    PFN_vkGetSwapchainImagesKHR vkGetSwapchainImagesKHR;
+    PFN_vkAcquireNextImageKHR vkAcquireNextImageKHR;
+    PFN_vkQueuePresentKHR vkQueuePresentKHR;
+    PFN_vkGetPhysicalDeviceSurfaceCapabilitiesKHR vkGetPhysicalDeviceSurfaceCapabilitiesKHR;
+    PFN_vkGetPhysicalDeviceSurfaceFormatsKHR vkGetPhysicalDeviceSurfaceFormatsKHR;
+    PFN_vkGetPhysicalDeviceSurfacePresentModesKHR vkGetPhysicalDeviceSurfacePresentModesKHR;
+
+    struct {
+        bool compute = false;
+        bool wideLines = false;
+        bool debugUtils = false;
+        bool vertexAttribDivisor = false;
+        bool texture3DSliceAs2D = false;
+        bool tessellation = false;
+        bool geometryShader = false;
+        bool nonFillPolygonMode = false;
+        QVersionNumber apiVersion;
+    } caps;
+
+    VkPipelineCache pipelineCache = VK_NULL_HANDLE;
+    struct DescriptorPoolData {
+        DescriptorPoolData() { }
+        DescriptorPoolData(VkDescriptorPool pool_)
+            : pool(pool_)
+        { }
+        VkDescriptorPool pool = VK_NULL_HANDLE;
+        int refCount = 0;
+        int allocedDescSets = 0;
+    };
+    QVarLengthArray<DescriptorPoolData, 8> descriptorPools;
+    QVarLengthArray<VkCommandBuffer, 4> freeSecondaryCbs[QVK_FRAMES_IN_FLIGHT];
+
+    VkQueryPool timestampQueryPool = VK_NULL_HANDLE;
+    QBitArray timestampQueryPoolMap;
+
+    VkFormat optimalDsFormat = VK_FORMAT_UNDEFINED;
+    QMatrix4x4 clipCorrectMatrix;
+
+    QVkSwapChain *currentSwapChain = nullptr;
+    QSet<QVkSwapChain *> swapchains;
+    QRhiVulkanNativeHandles nativeHandlesStruct;
+    QRhiDriverInfo driverInfoStruct;
+
+    struct OffscreenFrame {
+        OffscreenFrame(QRhiImplementation *rhi)
+        {
+            for (int i = 0; i < QVK_FRAMES_IN_FLIGHT; ++i)
+                cbWrapper[i] = new QVkCommandBuffer(rhi);
+        }
+        ~OffscreenFrame()
+        {
+            for (int i = 0; i < QVK_FRAMES_IN_FLIGHT; ++i)
+                delete cbWrapper[i];
+        }
+        bool active = false;
+        QVkCommandBuffer *cbWrapper[QVK_FRAMES_IN_FLIGHT];
+        VkFence cmdFence = VK_NULL_HANDLE;
+        int timestampQueryIndex = -1;
+    } ofr;
+
+    struct TextureReadback {
+        int activeFrameSlot = -1;
+        QRhiReadbackDescription desc;
+        QRhiReadbackResult *result;
+        VkBuffer stagingBuf;
+        QVkAlloc stagingAlloc;
+        quint32 byteSize;
+        QSize pixelSize;
+        QRhiTexture::Format format;
+    };
+    QVarLengthArray<TextureReadback, 2> activeTextureReadbacks;
+    struct BufferReadback {
+        int activeFrameSlot = -1;
+        QRhiReadbackResult *result;
+        quint32 byteSize;
+        VkBuffer stagingBuf;
+        QVkAlloc stagingAlloc;
+    };
+    QVarLengthArray<BufferReadback, 2> activeBufferReadbacks;
+
+    struct DeferredReleaseEntry {
+        enum Type {
+            Pipeline,
+            ShaderResourceBindings,
+            Buffer,
+            RenderBuffer,
+            Texture,
+            Sampler,
+            TextureRenderTarget,
+            RenderPass,
+            StagingBuffer,
+            SecondaryCommandBuffer
+        };
+        Type type;
+        int lastActiveFrameSlot; // -1 if not used otherwise 0..FRAMES_IN_FLIGHT-1
+        union {
+            struct {
+                VkPipeline pipeline;
+                VkPipelineLayout layout;
+            } pipelineState;
+            struct {
+                int poolIndex;
+                VkDescriptorSetLayout layout;
+            } shaderResourceBindings;
+            struct {
+                VkBuffer buffers[QVK_FRAMES_IN_FLIGHT];
+                QVkAlloc allocations[QVK_FRAMES_IN_FLIGHT];
+                VkBuffer stagingBuffers[QVK_FRAMES_IN_FLIGHT];
+                QVkAlloc stagingAllocations[QVK_FRAMES_IN_FLIGHT];
+            } buffer;
+            struct {
+                VkDeviceMemory memory;
+                VkImage image;
+                VkImageView imageView;
+            } renderBuffer;
+            struct {
+                VkImage image;
+                VkImageView imageView;
+                QVkAlloc allocation;
+                VkBuffer stagingBuffers[QVK_FRAMES_IN_FLIGHT];
+                QVkAlloc stagingAllocations[QVK_FRAMES_IN_FLIGHT];
+                VkImageView extraImageViews[QRhi::MAX_MIP_LEVELS];
+            } texture;
+            struct {
+                VkSampler sampler;
+            } sampler;
+            struct {
+                VkFramebuffer fb;
+                VkImageView rtv[QVkRenderTargetData::MAX_COLOR_ATTACHMENTS];
+                VkImageView resrtv[QVkRenderTargetData::MAX_COLOR_ATTACHMENTS];
+            } textureRenderTarget;
+            struct {
+                VkRenderPass rp;
+            } renderPass;
+            struct {
+                VkBuffer stagingBuffer;
+                QVkAlloc stagingAllocation;
+            } stagingBuffer;
+            struct {
+                VkCommandBuffer cb;
+            } secondaryCommandBuffer;
+        };
+    };
+    QList<DeferredReleaseEntry> releaseQueue;
 };
 
+Q_DECLARE_TYPEINFO(QRhiVulkan::DescriptorPoolData, Q_RELOCATABLE_TYPE);
+Q_DECLARE_TYPEINFO(QRhiVulkan::DeferredReleaseEntry, Q_RELOCATABLE_TYPE);
+Q_DECLARE_TYPEINFO(QRhiVulkan::TextureReadback, Q_RELOCATABLE_TYPE);
+Q_DECLARE_TYPEINFO(QRhiVulkan::BufferReadback, Q_RELOCATABLE_TYPE);
+
 QT_END_NAMESPACE
 
 #endif
diff --git a/src/gui/rhi/qrhivulkan_p_p.h b/src/gui/rhi/qrhivulkan_p_p.h
deleted file mode 100644
index 69bd6df305..0000000000
--- a/src/gui/rhi/qrhivulkan_p_p.h
+++ /dev/null
@@ -1,1006 +0,0 @@
-// Copyright (C) 2019 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
-
-#ifndef QRHIVULKAN_P_H
-#define QRHIVULKAN_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists purely as an
-// implementation detail.  This header file may change from version to
-// version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qrhivulkan_p.h"
-#include "qrhi_p_p.h"
-
-QT_BEGIN_NAMESPACE
-
-class QVulkanFunctions;
-class QVulkanDeviceFunctions;
-
-static const int QVK_FRAMES_IN_FLIGHT = 2;
-
-static const int QVK_DESC_SETS_PER_POOL = 128;
-static const int QVK_UNIFORM_BUFFERS_PER_POOL = 256;
-static const int QVK_COMBINED_IMAGE_SAMPLERS_PER_POOL = 256;
-static const int QVK_STORAGE_BUFFERS_PER_POOL = 128;
-static const int QVK_STORAGE_IMAGES_PER_POOL = 128;
-
-static const int QVK_MAX_ACTIVE_TIMESTAMP_PAIRS = 16;
-
-// no vk_mem_alloc.h available here, void* is good enough
-typedef void * QVkAlloc;
-typedef void * QVkAllocator;
-
-struct QVkBuffer : public QRhiBuffer
-{
-    QVkBuffer(QRhiImplementation *rhi, Type type, UsageFlags usage, quint32 size);
-    ~QVkBuffer();
-    void destroy() override;
-    bool create() override;
-    QRhiBuffer::NativeBuffer nativeBuffer() override;
-    char *beginFullDynamicBufferUpdateForCurrentFrame() override;
-    void endFullDynamicBufferUpdateForCurrentFrame() override;
-
-    VkBuffer buffers[QVK_FRAMES_IN_FLIGHT];
-    QVkAlloc allocations[QVK_FRAMES_IN_FLIGHT];
-    struct DynamicUpdate {
-        quint32 offset;
-        QRhiBufferData data;
-    };
-    QVarLengthArray<DynamicUpdate, 16> pendingDynamicUpdates[QVK_FRAMES_IN_FLIGHT];
-    VkBuffer stagingBuffers[QVK_FRAMES_IN_FLIGHT];
-    QVkAlloc stagingAllocations[QVK_FRAMES_IN_FLIGHT];
-    struct UsageState {
-        VkAccessFlags access = 0;
-        VkPipelineStageFlags stage = 0;
-    };
-    UsageState usageState[QVK_FRAMES_IN_FLIGHT];
-    int lastActiveFrameSlot = -1;
-    uint generation = 0;
-    friend class QRhiVulkan;
-};
-
-Q_DECLARE_TYPEINFO(QVkBuffer::DynamicUpdate, Q_RELOCATABLE_TYPE);
-
-struct QVkTexture;
-
-struct QVkRenderBuffer : public QRhiRenderBuffer
-{
-    QVkRenderBuffer(QRhiImplementation *rhi, Type type, const QSize &pixelSize,
-                    int sampleCount, Flags flags,
-                    QRhiTexture::Format backingFormatHint);
-    ~QVkRenderBuffer();
-    void destroy() override;
-    bool create() override;
-    QRhiTexture::Format backingFormat() const override;
-
-    VkDeviceMemory memory = VK_NULL_HANDLE;
-    VkImage image = VK_NULL_HANDLE;
-    VkImageView imageView = VK_NULL_HANDLE;
-    VkSampleCountFlagBits samples;
-    QVkTexture *backingTexture = nullptr;
-    VkFormat vkformat;
-    int lastActiveFrameSlot = -1;
-    uint generation = 0;
-    friend class QRhiVulkan;
-};
-
-struct QVkTexture : public QRhiTexture
-{
-    QVkTexture(QRhiImplementation *rhi, Format format, const QSize &pixelSize, int depth,
-               int arraySize, int sampleCount, Flags flags);
-    ~QVkTexture();
-    void destroy() override;
-    bool create() override;
-    bool createFrom(NativeTexture src) override;
-    NativeTexture nativeTexture() override;
-    void setNativeLayout(int layout) override;
-
-    bool prepareCreate(QSize *adjustedSize = nullptr);
-    bool finishCreate();
-    VkImageView imageViewForLevel(int level);
-
-    VkImage image = VK_NULL_HANDLE;
-    VkImageView imageView = VK_NULL_HANDLE;
-    QVkAlloc imageAlloc = nullptr;
-    VkBuffer stagingBuffers[QVK_FRAMES_IN_FLIGHT];
-    QVkAlloc stagingAllocations[QVK_FRAMES_IN_FLIGHT];
-    VkImageView perLevelImageViews[QRhi::MAX_MIP_LEVELS];
-    bool owns = true;
-    struct UsageState {
-        // no tracking of subresource layouts (some operations can keep
-        // subresources in different layouts for some time, but that does not
-        // need to be kept track of)
-        VkImageLayout layout;
-        VkAccessFlags access;
-        VkPipelineStageFlags stage;
-    };
-    UsageState usageState;
-    VkFormat vkformat;
-    uint mipLevelCount = 0;
-    VkSampleCountFlagBits samples;
-    int lastActiveFrameSlot = -1;
-    uint generation = 0;
-    friend class QRhiVulkan;
-};
-
-struct QVkSampler : public QRhiSampler
-{
-    QVkSampler(QRhiImplementation *rhi, Filter magFilter, Filter minFilter, Filter mipmapMode,
-               AddressMode u, AddressMode v, AddressMode w);
-    ~QVkSampler();
-    void destroy() override;
-    bool create() override;
-
-    VkSampler sampler = VK_NULL_HANDLE;
-    int lastActiveFrameSlot = -1;
-    uint generation = 0;
-    friend class QRhiVulkan;
-};
-
-struct QVkRenderPassDescriptor : public QRhiRenderPassDescriptor
-{
-    QVkRenderPassDescriptor(QRhiImplementation *rhi);
-    ~QVkRenderPassDescriptor();
-    void destroy() override;
-    bool isCompatible(const QRhiRenderPassDescriptor *other) const override;
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() const override;
-    QVector<quint32> serializedFormat() const override;
-    const QRhiNativeHandles *nativeHandles() override;
-
-    void updateSerializedFormat();
-
-    VkRenderPass rp = VK_NULL_HANDLE;
-    bool ownsRp = false;
-    QVarLengthArray<VkAttachmentDescription, 8> attDescs;
-    QVarLengthArray<VkAttachmentReference, 8> colorRefs;
-    QVarLengthArray<VkAttachmentReference, 8> resolveRefs;
-    QVarLengthArray<VkSubpassDependency, 2> subpassDeps;
-    bool hasDepthStencil = false;
-    VkAttachmentReference dsRef;
-    QVector<quint32> serializedFormatData;
-    QRhiVulkanRenderPassNativeHandles nativeHandlesStruct;
-    int lastActiveFrameSlot = -1;
-};
-
-struct QVkRenderTargetData
-{
-    VkFramebuffer fb = VK_NULL_HANDLE;
-    QVkRenderPassDescriptor *rp = nullptr;
-    QSize pixelSize;
-    float dpr = 1;
-    int sampleCount = 1;
-    int colorAttCount = 0;
-    int dsAttCount = 0;
-    int resolveAttCount = 0;
-    QRhiRenderTargetAttachmentTracker::ResIdList currentResIdList;
-    static const int MAX_COLOR_ATTACHMENTS = 8;
-};
-
-struct QVkSwapChainRenderTarget : public QRhiSwapChainRenderTarget
-{
-    QVkSwapChainRenderTarget(QRhiImplementation *rhi, QRhiSwapChain *swapchain);
-    ~QVkSwapChainRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QVkRenderTargetData d;
-};
-
-struct QVkTextureRenderTarget : public QRhiTextureRenderTarget
-{
-    QVkTextureRenderTarget(QRhiImplementation *rhi, const QRhiTextureRenderTargetDescription &desc, Flags flags);
-    ~QVkTextureRenderTarget();
-    void destroy() override;
-
-    QSize pixelSize() const override;
-    float devicePixelRatio() const override;
-    int sampleCount() const override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool create() override;
-
-    QVkRenderTargetData d;
-    VkImageView rtv[QVkRenderTargetData::MAX_COLOR_ATTACHMENTS];
-    VkImageView resrtv[QVkRenderTargetData::MAX_COLOR_ATTACHMENTS];
-    int lastActiveFrameSlot = -1;
-    friend class QRhiVulkan;
-};
-
-struct QVkShaderResourceBindings : public QRhiShaderResourceBindings
-{
-    QVkShaderResourceBindings(QRhiImplementation *rhi);
-    ~QVkShaderResourceBindings();
-    void destroy() override;
-    bool create() override;
-    void updateResources(UpdateFlags flags) override;
-
-    QVarLengthArray<QRhiShaderResourceBinding, 8> sortedBindings;
-    bool hasSlottedResource = false;
-    bool hasDynamicOffset = false;
-    int poolIndex = -1;
-    VkDescriptorSetLayout layout = VK_NULL_HANDLE;
-    VkDescriptorSet descSets[QVK_FRAMES_IN_FLIGHT]; // multiple sets to support dynamic buffers
-    int lastActiveFrameSlot = -1;
-    uint generation = 0;
-
-    // Keep track of the generation number of each referenced QRhi* to be able
-    // to detect that the underlying descriptor set became out of date and they
-    // need to be written again with the up-to-date VkBuffer etc. objects.
-    struct BoundUniformBufferData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundSampledTextureData {
-        int count;
-        struct {
-            quint64 texId;
-            uint texGeneration;
-            quint64 samplerId;
-            uint samplerGeneration;
-        } d[QRhiShaderResourceBinding::Data::MAX_TEX_SAMPLER_ARRAY_SIZE];
-    };
-    struct BoundStorageImageData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundStorageBufferData {
-        quint64 id;
-        uint generation;
-    };
-    struct BoundResourceData {
-        union {
-            BoundUniformBufferData ubuf;
-            BoundSampledTextureData stex;
-            BoundStorageImageData simage;
-            BoundStorageBufferData sbuf;
-        };
-    };
-    QVarLengthArray<BoundResourceData, 8> boundResourceData[QVK_FRAMES_IN_FLIGHT];
-
-    friend class QRhiVulkan;
-};
-
-Q_DECLARE_TYPEINFO(QVkShaderResourceBindings::BoundResourceData, Q_RELOCATABLE_TYPE);
-
-struct QVkGraphicsPipeline : public QRhiGraphicsPipeline
-{
-    QVkGraphicsPipeline(QRhiImplementation *rhi);
-    ~QVkGraphicsPipeline();
-    void destroy() override;
-    bool create() override;
-
-    VkPipelineLayout layout = VK_NULL_HANDLE;
-    VkPipeline pipeline = VK_NULL_HANDLE;
-    int lastActiveFrameSlot = -1;
-    uint generation = 0;
-    friend class QRhiVulkan;
-};
-
-struct QVkComputePipeline : public QRhiComputePipeline
-{
-    QVkComputePipeline(QRhiImplementation *rhi);
-    ~QVkComputePipeline();
-    void destroy() override;
-    bool create() override;
-
-    VkPipelineLayout layout = VK_NULL_HANDLE;
-    VkPipeline pipeline = VK_NULL_HANDLE;
-    int lastActiveFrameSlot = -1;
-    uint generation = 0;
-    friend class QRhiVulkan;
-};
-
-struct QVkCommandBuffer : public QRhiCommandBuffer
-{
-    QVkCommandBuffer(QRhiImplementation *rhi);
-    ~QVkCommandBuffer();
-    void destroy() override;
-
-    const QRhiNativeHandles *nativeHandles();
-
-    VkCommandBuffer cb = VK_NULL_HANDLE; // primary
-    QRhiVulkanCommandBufferNativeHandles nativeHandlesStruct;
-
-    enum PassType {
-        NoPass,
-        RenderPass,
-        ComputePass
-    };
-
-    void resetState() {
-        recordingPass = NoPass;
-        passUsesSecondaryCb = false;
-        lastGpuTime = 0;
-        currentTarget = nullptr;
-        activeSecondaryCbStack.clear();
-        resetCommands();
-        resetCachedState();
-    }
-
-    void resetCachedState() {
-        currentGraphicsPipeline = nullptr;
-        currentComputePipeline = nullptr;
-        currentPipelineGeneration = 0;
-        currentGraphicsSrb = nullptr;
-        currentComputeSrb = nullptr;
-        currentSrbGeneration = 0;
-        currentDescSetSlot = -1;
-        currentIndexBuffer = VK_NULL_HANDLE;
-        currentIndexOffset = 0;
-        currentIndexFormat = VK_INDEX_TYPE_UINT16;
-        memset(currentVertexBuffers, 0, sizeof(currentVertexBuffers));
-        memset(currentVertexOffsets, 0, sizeof(currentVertexOffsets));
-        inExternal = false;
-    }
-
-    PassType recordingPass;
-    bool passUsesSecondaryCb;
-    double lastGpuTime = 0;
-    QRhiRenderTarget *currentTarget;
-    QRhiGraphicsPipeline *currentGraphicsPipeline;
-    QRhiComputePipeline *currentComputePipeline;
-    uint currentPipelineGeneration;
-    QRhiShaderResourceBindings *currentGraphicsSrb;
-    QRhiShaderResourceBindings *currentComputeSrb;
-    uint currentSrbGeneration;
-    int currentDescSetSlot;
-    VkBuffer currentIndexBuffer;
-    quint32 currentIndexOffset;
-    VkIndexType currentIndexFormat;
-    static const int VERTEX_INPUT_RESOURCE_SLOT_COUNT = 32;
-    VkBuffer currentVertexBuffers[VERTEX_INPUT_RESOURCE_SLOT_COUNT];
-    quint32 currentVertexOffsets[VERTEX_INPUT_RESOURCE_SLOT_COUNT];
-    QVarLengthArray<VkCommandBuffer, 4> activeSecondaryCbStack;
-    bool inExternal;
-
-    struct {
-        QHash<QRhiResource *, QPair<VkAccessFlags, bool> > writtenResources;
-        void reset() {
-            writtenResources.clear();
-        }
-    } computePassState;
-
-    struct Command {
-        enum Cmd {
-            CopyBuffer,
-            CopyBufferToImage,
-            CopyImage,
-            CopyImageToBuffer,
-            ImageBarrier,
-            BufferBarrier,
-            BlitImage,
-            BeginRenderPass,
-            EndRenderPass,
-            BindPipeline,
-            BindDescriptorSet,
-            BindVertexBuffer,
-            BindIndexBuffer,
-            SetViewport,
-            SetScissor,
-            SetBlendConstants,
-            SetStencilRef,
-            Draw,
-            DrawIndexed,
-            DebugMarkerBegin,
-            DebugMarkerEnd,
-            DebugMarkerInsert,
-            TransitionPassResources,
-            Dispatch,
-            ExecuteSecondary
-        };
-        Cmd cmd;
-
-        union Args {
-            struct {
-                VkBuffer src;
-                VkBuffer dst;
-                VkBufferCopy desc;
-            } copyBuffer;
-            struct {
-                VkBuffer src;
-                VkImage dst;
-                VkImageLayout dstLayout;
-                int count;
-                int bufferImageCopyIndex;
-            } copyBufferToImage;
-            struct {
-                VkImage src;
-                VkImageLayout srcLayout;
-                VkImage dst;
-                VkImageLayout dstLayout;
-                VkImageCopy desc;
-            } copyImage;
-            struct {
-                VkImage src;
-                VkImageLayout srcLayout;
-                VkBuffer dst;
-                VkBufferImageCopy desc;
-            } copyImageToBuffer;
-            struct {
-                VkPipelineStageFlags srcStageMask;
-                VkPipelineStageFlags dstStageMask;
-                int count;
-                int index;
-            } imageBarrier;
-            struct {
-                VkPipelineStageFlags srcStageMask;
-                VkPipelineStageFlags dstStageMask;
-                int count;
-                int index;
-            } bufferBarrier;
-            struct {
-                VkImage src;
-                VkImageLayout srcLayout;
-                VkImage dst;
-                VkImageLayout dstLayout;
-                VkFilter filter;
-                VkImageBlit desc;
-            } blitImage;
-            struct {
-                VkRenderPassBeginInfo desc;
-                int clearValueIndex;
-                bool useSecondaryCb;
-            } beginRenderPass;
-            struct {
-            } endRenderPass;
-            struct {
-                VkPipelineBindPoint bindPoint;
-                VkPipeline pipeline;
-            } bindPipeline;
-            struct {
-                VkPipelineBindPoint bindPoint;
-                VkPipelineLayout pipelineLayout;
-                VkDescriptorSet descSet;
-                int dynamicOffsetCount;
-                int dynamicOffsetIndex;
-            } bindDescriptorSet;
-            struct {
-                int startBinding;
-                int count;
-                int vertexBufferIndex;
-                int vertexBufferOffsetIndex;
-            } bindVertexBuffer;
-            struct {
-                VkBuffer buf;
-                VkDeviceSize ofs;
-                VkIndexType type;
-            } bindIndexBuffer;
-            struct {
-                VkViewport viewport;
-            } setViewport;
-            struct {
-                VkRect2D scissor;
-            } setScissor;
-            struct {
-                float c[4];
-            } setBlendConstants;
-            struct {
-                uint32_t ref;
-            } setStencilRef;
-            struct {
-                uint32_t vertexCount;
-                uint32_t instanceCount;
-                uint32_t firstVertex;
-                uint32_t firstInstance;
-            } draw;
-            struct {
-                uint32_t indexCount;
-                uint32_t instanceCount;
-                uint32_t firstIndex;
-                int32_t vertexOffset;
-                uint32_t firstInstance;
-            } drawIndexed;
-            struct {
-#ifdef VK_EXT_debug_utils
-                VkDebugUtilsLabelEXT label;
-                int labelNameIndex;
-#endif
-            } debugMarkerBegin;
-            struct {
-            } debugMarkerEnd;
-            struct {
-#ifdef VK_EXT_debug_utils
-                VkDebugUtilsLabelEXT label;
-                int labelNameIndex;
-#endif
-            } debugMarkerInsert;
-            struct {
-                int trackerIndex;
-            } transitionResources;
-            struct {
-                int x, y, z;
-            } dispatch;
-            struct {
-                VkCommandBuffer cb;
-            } executeSecondary;
-        } args;
-    };
-
-    QRhiBackendCommandList<Command> commands;
-    QVarLengthArray<QRhiPassResourceTracker, 8> passResTrackers;
-    int currentPassResTrackerIndex;
-
-    void resetCommands() {
-        commands.reset();
-        resetPools();
-
-        passResTrackers.clear();
-        currentPassResTrackerIndex = -1;
-    }
-
-    void resetPools() {
-        pools.clearValue.clear();
-        pools.bufferImageCopy.clear();
-        pools.dynamicOffset.clear();
-        pools.vertexBuffer.clear();
-        pools.vertexBufferOffset.clear();
-        pools.debugMarkerData.clear();
-        pools.imageBarrier.clear();
-        pools.bufferBarrier.clear();
-    }
-
-    struct {
-        QVarLengthArray<VkClearValue, 4> clearValue;
-        QVarLengthArray<VkBufferImageCopy, 16> bufferImageCopy;
-        QVarLengthArray<uint32_t, 4> dynamicOffset;
-        QVarLengthArray<VkBuffer, 4> vertexBuffer;
-        QVarLengthArray<VkDeviceSize, 4> vertexBufferOffset;
-        QVarLengthArray<QByteArray, 4> debugMarkerData;
-        QVarLengthArray<VkImageMemoryBarrier, 8> imageBarrier;
-        QVarLengthArray<VkBufferMemoryBarrier, 8> bufferBarrier;
-    } pools;
-
-    friend class QRhiVulkan;
-};
-
-struct QVkSwapChain : public QRhiSwapChain
-{
-    QVkSwapChain(QRhiImplementation *rhi);
-    ~QVkSwapChain();
-    void destroy() override;
-
-    QRhiCommandBuffer *currentFrameCommandBuffer() override;
-    QRhiRenderTarget *currentFrameRenderTarget() override;
-
-    QSize surfacePixelSize() override;
-    bool isFormatSupported(Format f) override;
-
-    QRhiRenderPassDescriptor *newCompatibleRenderPassDescriptor() override;
-    bool createOrResize() override;
-
-    bool ensureSurface();
-
-    static const quint32 EXPECTED_MAX_BUFFER_COUNT = 4;
-
-    QWindow *window = nullptr;
-    QSize pixelSize;
-    bool supportsReadback = false;
-    VkSwapchainKHR sc = VK_NULL_HANDLE;
-    int bufferCount = 0;
-    VkSurfaceKHR surface = VK_NULL_HANDLE;
-    VkSurfaceKHR lastConnectedSurface = VK_NULL_HANDLE;
-    VkFormat colorFormat = VK_FORMAT_B8G8R8A8_UNORM;
-    VkColorSpaceKHR colorSpace = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR;
-    QVkRenderBuffer *ds = nullptr;
-    VkSampleCountFlagBits samples = VK_SAMPLE_COUNT_1_BIT;
-    QVarLengthArray<VkPresentModeKHR, 8> supportedPresentationModes;
-    VkDeviceMemory msaaImageMem = VK_NULL_HANDLE;
-    QVkSwapChainRenderTarget rtWrapper;
-    QVkCommandBuffer cbWrapper;
-
-    struct ImageResources {
-        VkImage image = VK_NULL_HANDLE;
-        VkImageView imageView = VK_NULL_HANDLE;
-        VkFramebuffer fb = VK_NULL_HANDLE;
-        VkImage msaaImage = VK_NULL_HANDLE;
-        VkImageView msaaImageView = VK_NULL_HANDLE;
-        enum LastUse {
-            ScImageUseNone,
-            ScImageUseRender,
-            ScImageUseTransferSource
-        };
-        LastUse lastUse = ScImageUseNone;
-    };
-    QVarLengthArray<ImageResources, EXPECTED_MAX_BUFFER_COUNT> imageRes;
-
-    struct FrameResources {
-        VkFence imageFence = VK_NULL_HANDLE;
-        bool imageFenceWaitable = false;
-        VkSemaphore imageSem = VK_NULL_HANDLE;
-        VkSemaphore drawSem = VK_NULL_HANDLE;
-        bool imageAcquired = false;
-        bool imageSemWaitable = false;
-        VkFence cmdFence = VK_NULL_HANDLE;
-        bool cmdFenceWaitable = false;
-        VkCommandBuffer cmdBuf = VK_NULL_HANDLE; // primary
-        int timestampQueryIndex = -1;
-    } frameRes[QVK_FRAMES_IN_FLIGHT];
-
-    quint32 currentImageIndex = 0; // index in imageRes
-    quint32 currentFrameSlot = 0; // index in frameRes
-    int frameCount = 0;
-
-    friend class QRhiVulkan;
-};
-
-class QRhiVulkan : public QRhiImplementation
-{
-public:
-    QRhiVulkan(QRhiVulkanInitParams *params, QRhiVulkanNativeHandles *importParams = nullptr);
-
-    bool create(QRhi::Flags flags) override;
-    void destroy() override;
-
-    QRhiGraphicsPipeline *createGraphicsPipeline() override;
-    QRhiComputePipeline *createComputePipeline() override;
-    QRhiShaderResourceBindings *createShaderResourceBindings() override;
-    QRhiBuffer *createBuffer(QRhiBuffer::Type type,
-                             QRhiBuffer::UsageFlags usage,
-                             quint32 size) override;
-    QRhiRenderBuffer *createRenderBuffer(QRhiRenderBuffer::Type type,
-                                         const QSize &pixelSize,
-                                         int sampleCount,
-                                         QRhiRenderBuffer::Flags flags,
-                                         QRhiTexture::Format backingFormatHint) override;
-    QRhiTexture *createTexture(QRhiTexture::Format format,
-                               const QSize &pixelSize,
-                               int depth,
-                               int arraySize,
-                               int sampleCount,
-                               QRhiTexture::Flags flags) override;
-    QRhiSampler *createSampler(QRhiSampler::Filter magFilter,
-                               QRhiSampler::Filter minFilter,
-                               QRhiSampler::Filter mipmapMode,
-                               QRhiSampler:: AddressMode u,
-                               QRhiSampler::AddressMode v,
-                               QRhiSampler::AddressMode w) override;
-
-    QRhiTextureRenderTarget *createTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc,
-                                                       QRhiTextureRenderTarget::Flags flags) override;
-
-    QRhiSwapChain *createSwapChain() override;
-    QRhi::FrameOpResult beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags) override;
-    QRhi::FrameOpResult endOffscreenFrame(QRhi::EndFrameFlags flags) override;
-    QRhi::FrameOpResult finish() override;
-
-    void resourceUpdate(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void beginPass(QRhiCommandBuffer *cb,
-                   QRhiRenderTarget *rt,
-                   const QColor &colorClearValue,
-                   const QRhiDepthStencilClearValue &depthStencilClearValue,
-                   QRhiResourceUpdateBatch *resourceUpdates,
-                   QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endPass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-
-    void setGraphicsPipeline(QRhiCommandBuffer *cb,
-                             QRhiGraphicsPipeline *ps) override;
-
-    void setShaderResources(QRhiCommandBuffer *cb,
-                            QRhiShaderResourceBindings *srb,
-                            int dynamicOffsetCount,
-                            const QRhiCommandBuffer::DynamicOffset *dynamicOffsets) override;
-
-    void setVertexInput(QRhiCommandBuffer *cb,
-                        int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings,
-                        QRhiBuffer *indexBuf, quint32 indexOffset,
-                        QRhiCommandBuffer::IndexFormat indexFormat) override;
-
-    void setViewport(QRhiCommandBuffer *cb, const QRhiViewport &viewport) override;
-    void setScissor(QRhiCommandBuffer *cb, const QRhiScissor &scissor) override;
-    void setBlendConstants(QRhiCommandBuffer *cb, const QColor &c) override;
-    void setStencilRef(QRhiCommandBuffer *cb, quint32 refValue) override;
-
-    void draw(QRhiCommandBuffer *cb, quint32 vertexCount,
-              quint32 instanceCount, quint32 firstVertex, quint32 firstInstance) override;
-
-    void drawIndexed(QRhiCommandBuffer *cb, quint32 indexCount,
-                     quint32 instanceCount, quint32 firstIndex,
-                     qint32 vertexOffset, quint32 firstInstance) override;
-
-    void debugMarkBegin(QRhiCommandBuffer *cb, const QByteArray &name) override;
-    void debugMarkEnd(QRhiCommandBuffer *cb) override;
-    void debugMarkMsg(QRhiCommandBuffer *cb, const QByteArray &msg) override;
-
-    void beginComputePass(QRhiCommandBuffer *cb,
-                          QRhiResourceUpdateBatch *resourceUpdates,
-                          QRhiCommandBuffer::BeginPassFlags flags) override;
-    void endComputePass(QRhiCommandBuffer *cb, QRhiResourceUpdateBatch *resourceUpdates) override;
-    void setComputePipeline(QRhiCommandBuffer *cb, QRhiComputePipeline *ps) override;
-    void dispatch(QRhiCommandBuffer *cb, int x, int y, int z) override;
-
-    const QRhiNativeHandles *nativeHandles(QRhiCommandBuffer *cb) override;
-    void beginExternal(QRhiCommandBuffer *cb) override;
-    void endExternal(QRhiCommandBuffer *cb) override;
-    double lastCompletedGpuTime(QRhiCommandBuffer *cb) override;
-
-    QList<int> supportedSampleCounts() const override;
-    int ubufAlignment() const override;
-    bool isYUpInFramebuffer() const override;
-    bool isYUpInNDC() const override;
-    bool isClipDepthZeroToOne() const override;
-    QMatrix4x4 clipSpaceCorrMatrix() const override;
-    bool isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags) const override;
-    bool isFeatureSupported(QRhi::Feature feature) const override;
-    int resourceLimit(QRhi::ResourceLimit limit) const override;
-    const QRhiNativeHandles *nativeHandles() override;
-    QRhiDriverInfo driverInfo() const override;
-    QRhiStats statistics() override;
-    bool makeThreadLocalNativeContextCurrent() override;
-    void releaseCachedResources() override;
-    bool isDeviceLost() const override;
-
-    QByteArray pipelineCacheData() override;
-    void setPipelineCacheData(const QByteArray &data) override;
-
-    VkResult createDescriptorPool(VkDescriptorPool *pool);
-    bool allocateDescriptorSet(VkDescriptorSetAllocateInfo *allocInfo, VkDescriptorSet *result, int *resultPoolIndex);
-    uint32_t chooseTransientImageMemType(VkImage img, uint32_t startIndex);
-    bool createTransientImage(VkFormat format, const QSize &pixelSize, VkImageUsageFlags usage,
-                              VkImageAspectFlags aspectMask, VkSampleCountFlagBits samples,
-                              VkDeviceMemory *mem, VkImage *images, VkImageView *views, int count);
-
-    bool recreateSwapChain(QRhiSwapChain *swapChain);
-    void releaseSwapChainResources(QRhiSwapChain *swapChain);
-
-    VkFormat optimalDepthStencilFormat();
-    VkSampleCountFlagBits effectiveSampleCount(int sampleCount);
-    bool createDefaultRenderPass(QVkRenderPassDescriptor *rpD,
-                                 bool hasDepthStencil,
-                                 VkSampleCountFlagBits samples,
-                                 VkFormat colorFormat);
-    bool createOffscreenRenderPass(QVkRenderPassDescriptor *rpD,
-                                   const QRhiColorAttachment *firstColorAttachment,
-                                   const QRhiColorAttachment *lastColorAttachment,
-                                   bool preserveColor,
-                                   bool preserveDs,
-                                   QRhiRenderBuffer *depthStencilBuffer,
-                                   QRhiTexture *depthTexture);
-    bool ensurePipelineCache(const void *initialData = nullptr, size_t initialDataSize = 0);
-    VkShaderModule createShader(const QByteArray &spirv);
-
-    void prepareNewFrame(QRhiCommandBuffer *cb);
-    VkCommandBuffer startSecondaryCommandBuffer(QVkRenderTargetData *rtD = nullptr);
-    void endAndEnqueueSecondaryCommandBuffer(VkCommandBuffer cb, QVkCommandBuffer *cbD);
-    QRhi::FrameOpResult startPrimaryCommandBuffer(VkCommandBuffer *cb);
-    QRhi::FrameOpResult endAndSubmitPrimaryCommandBuffer(VkCommandBuffer cb, VkFence cmdFence,
-                                                         VkSemaphore *waitSem, VkSemaphore *signalSem);
-    void waitCommandCompletion(int frameSlot);
-    VkDeviceSize subresUploadByteSize(const QRhiTextureSubresourceUploadDescription &subresDesc) const;
-    using BufferImageCopyList = QVarLengthArray<VkBufferImageCopy, 16>;
-    void prepareUploadSubres(QVkTexture *texD, int layer, int level,
-                             const QRhiTextureSubresourceUploadDescription &subresDesc,
-                             size_t *curOfs, void *mp,
-                             BufferImageCopyList *copyInfos);
-    void enqueueResourceUpdates(QVkCommandBuffer *cbD, QRhiResourceUpdateBatch *resourceUpdates);
-    void executeBufferHostWritesForSlot(QVkBuffer *bufD, int slot);
-    void enqueueTransitionPassResources(QVkCommandBuffer *cbD);
-    void recordPrimaryCommandBuffer(QVkCommandBuffer *cbD);
-    void trackedRegisterBuffer(QRhiPassResourceTracker *passResTracker,
-                               QVkBuffer *bufD,
-                               int slot,
-                               QRhiPassResourceTracker::BufferAccess access,
-                               QRhiPassResourceTracker::BufferStage stage);
-    void trackedRegisterTexture(QRhiPassResourceTracker *passResTracker,
-                                QVkTexture *texD,
-                                QRhiPassResourceTracker::TextureAccess access,
-                                QRhiPassResourceTracker::TextureStage stage);
-    void recordTransitionPassResources(QVkCommandBuffer *cbD, const QRhiPassResourceTracker &tracker);
-    void activateTextureRenderTarget(QVkCommandBuffer *cbD, QVkTextureRenderTarget *rtD);
-    void executeDeferredReleases(bool forced = false);
-    void finishActiveReadbacks(bool forced = false);
-
-    void setObjectName(uint64_t object, VkObjectType type, const QByteArray &name, int slot = -1);
-    void trackedBufferBarrier(QVkCommandBuffer *cbD, QVkBuffer *bufD, int slot,
-                              VkAccessFlags access, VkPipelineStageFlags stage);
-    void trackedImageBarrier(QVkCommandBuffer *cbD, QVkTexture *texD,
-                             VkImageLayout layout, VkAccessFlags access, VkPipelineStageFlags stage);
-    void depthStencilExplicitBarrier(QVkCommandBuffer *cbD, QVkRenderBuffer *rbD);
-    void subresourceBarrier(QVkCommandBuffer *cbD, VkImage image,
-                            VkImageLayout oldLayout, VkImageLayout newLayout,
-                            VkAccessFlags srcAccess, VkAccessFlags dstAccess,
-                            VkPipelineStageFlags srcStage, VkPipelineStageFlags dstStage,
-                            int startLayer, int layerCount,
-                            int startLevel, int levelCount);
-    void updateShaderResourceBindings(QRhiShaderResourceBindings *srb, int descSetIdx = -1);
-    void ensureCommandPoolForNewFrame();
-    double elapsedSecondsFromTimestamp(quint64 timestamp[2], bool *ok);
-
-    QVulkanInstance *inst = nullptr;
-    QWindow *maybeWindow = nullptr;
-    QByteArrayList requestedDeviceExtensions;
-    bool importedDevice = false;
-    VkPhysicalDevice physDev = VK_NULL_HANDLE;
-    VkDevice dev = VK_NULL_HANDLE;
-    VkCommandPool cmdPool[QVK_FRAMES_IN_FLIGHT] = {};
-    quint32 gfxQueueFamilyIdx = 0;
-    quint32 gfxQueueIdx = 0;
-    VkQueue gfxQueue = VK_NULL_HANDLE;
-    quint32 timestampValidBits = 0;
-    bool importedAllocator = false;
-    QVkAllocator allocator = nullptr;
-    QVulkanFunctions *f = nullptr;
-    QVulkanDeviceFunctions *df = nullptr;
-    QRhi::Flags rhiFlags;
-    VkPhysicalDeviceFeatures physDevFeatures;
-    VkPhysicalDeviceProperties physDevProperties;
-    VkDeviceSize ubufAlign;
-    VkDeviceSize texbufAlign;
-    bool deviceLost = false;
-    bool releaseCachedResourcesCalledBeforeFrameStart = false;
-
-#ifdef VK_EXT_debug_utils
-    PFN_vkSetDebugUtilsObjectNameEXT vkSetDebugUtilsObjectNameEXT = nullptr;
-    PFN_vkCmdBeginDebugUtilsLabelEXT vkCmdBeginDebugUtilsLabelEXT = nullptr;
-    PFN_vkCmdEndDebugUtilsLabelEXT vkCmdEndDebugUtilsLabelEXT = nullptr;
-    PFN_vkCmdInsertDebugUtilsLabelEXT vkCmdInsertDebugUtilsLabelEXT = nullptr;
-#endif
-
-    PFN_vkCreateSwapchainKHR vkCreateSwapchainKHR = nullptr;
-    PFN_vkDestroySwapchainKHR vkDestroySwapchainKHR;
-    PFN_vkGetSwapchainImagesKHR vkGetSwapchainImagesKHR;
-    PFN_vkAcquireNextImageKHR vkAcquireNextImageKHR;
-    PFN_vkQueuePresentKHR vkQueuePresentKHR;
-    PFN_vkGetPhysicalDeviceSurfaceCapabilitiesKHR vkGetPhysicalDeviceSurfaceCapabilitiesKHR;
-    PFN_vkGetPhysicalDeviceSurfaceFormatsKHR vkGetPhysicalDeviceSurfaceFormatsKHR;
-    PFN_vkGetPhysicalDeviceSurfacePresentModesKHR vkGetPhysicalDeviceSurfacePresentModesKHR;
-
-    struct {
-        bool compute = false;
-        bool wideLines = false;
-        bool debugUtils = false;
-        bool vertexAttribDivisor = false;
-        bool texture3DSliceAs2D = false;
-        bool tessellation = false;
-        bool geometryShader = false;
-        bool nonFillPolygonMode = false;
-        QVersionNumber apiVersion;
-    } caps;
-
-    VkPipelineCache pipelineCache = VK_NULL_HANDLE;
-    struct DescriptorPoolData {
-        DescriptorPoolData() { }
-        DescriptorPoolData(VkDescriptorPool pool_)
-            : pool(pool_)
-        { }
-        VkDescriptorPool pool = VK_NULL_HANDLE;
-        int refCount = 0;
-        int allocedDescSets = 0;
-    };
-    QVarLengthArray<DescriptorPoolData, 8> descriptorPools;
-    QVarLengthArray<VkCommandBuffer, 4> freeSecondaryCbs[QVK_FRAMES_IN_FLIGHT];
-
-    VkQueryPool timestampQueryPool = VK_NULL_HANDLE;
-    QBitArray timestampQueryPoolMap;
-
-    VkFormat optimalDsFormat = VK_FORMAT_UNDEFINED;
-    QMatrix4x4 clipCorrectMatrix;
-
-    QVkSwapChain *currentSwapChain = nullptr;
-    QSet<QVkSwapChain *> swapchains;
-    QRhiVulkanNativeHandles nativeHandlesStruct;
-    QRhiDriverInfo driverInfoStruct;
-
-    struct OffscreenFrame {
-        OffscreenFrame(QRhiImplementation *rhi)
-        {
-            for (int i = 0; i < QVK_FRAMES_IN_FLIGHT; ++i)
-                cbWrapper[i] = new QVkCommandBuffer(rhi);
-        }
-        ~OffscreenFrame()
-        {
-            for (int i = 0; i < QVK_FRAMES_IN_FLIGHT; ++i)
-                delete cbWrapper[i];
-        }
-        bool active = false;
-        QVkCommandBuffer *cbWrapper[QVK_FRAMES_IN_FLIGHT];
-        VkFence cmdFence = VK_NULL_HANDLE;
-        int timestampQueryIndex = -1;
-    } ofr;
-
-    struct TextureReadback {
-        int activeFrameSlot = -1;
-        QRhiReadbackDescription desc;
-        QRhiReadbackResult *result;
-        VkBuffer stagingBuf;
-        QVkAlloc stagingAlloc;
-        quint32 byteSize;
-        QSize pixelSize;
-        QRhiTexture::Format format;
-    };
-    QVarLengthArray<TextureReadback, 2> activeTextureReadbacks;
-    struct BufferReadback {
-        int activeFrameSlot = -1;
-        QRhiReadbackResult *result;
-        quint32 byteSize;
-        VkBuffer stagingBuf;
-        QVkAlloc stagingAlloc;
-    };
-    QVarLengthArray<BufferReadback, 2> activeBufferReadbacks;
-
-    struct DeferredReleaseEntry {
-        enum Type {
-            Pipeline,
-            ShaderResourceBindings,
-            Buffer,
-            RenderBuffer,
-            Texture,
-            Sampler,
-            TextureRenderTarget,
-            RenderPass,
-            StagingBuffer,
-            SecondaryCommandBuffer
-        };
-        Type type;
-        int lastActiveFrameSlot; // -1 if not used otherwise 0..FRAMES_IN_FLIGHT-1
-        union {
-            struct {
-                VkPipeline pipeline;
-                VkPipelineLayout layout;
-            } pipelineState;
-            struct {
-                int poolIndex;
-                VkDescriptorSetLayout layout;
-            } shaderResourceBindings;
-            struct {
-                VkBuffer buffers[QVK_FRAMES_IN_FLIGHT];
-                QVkAlloc allocations[QVK_FRAMES_IN_FLIGHT];
-                VkBuffer stagingBuffers[QVK_FRAMES_IN_FLIGHT];
-                QVkAlloc stagingAllocations[QVK_FRAMES_IN_FLIGHT];
-            } buffer;
-            struct {
-                VkDeviceMemory memory;
-                VkImage image;
-                VkImageView imageView;
-            } renderBuffer;
-            struct {
-                VkImage image;
-                VkImageView imageView;
-                QVkAlloc allocation;
-                VkBuffer stagingBuffers[QVK_FRAMES_IN_FLIGHT];
-                QVkAlloc stagingAllocations[QVK_FRAMES_IN_FLIGHT];
-                VkImageView extraImageViews[QRhi::MAX_MIP_LEVELS];
-            } texture;
-            struct {
-                VkSampler sampler;
-            } sampler;
-            struct {
-                VkFramebuffer fb;
-                VkImageView rtv[QVkRenderTargetData::MAX_COLOR_ATTACHMENTS];
-                VkImageView resrtv[QVkRenderTargetData::MAX_COLOR_ATTACHMENTS];
-            } textureRenderTarget;
-            struct {
-                VkRenderPass rp;
-            } renderPass;
-            struct {
-                VkBuffer stagingBuffer;
-                QVkAlloc stagingAllocation;
-            } stagingBuffer;
-            struct {
-                VkCommandBuffer cb;
-            } secondaryCommandBuffer;
-        };
-    };
-    QList<DeferredReleaseEntry> releaseQueue;
-};
-
-Q_DECLARE_TYPEINFO(QRhiVulkan::DescriptorPoolData, Q_RELOCATABLE_TYPE);
-Q_DECLARE_TYPEINFO(QRhiVulkan::DeferredReleaseEntry, Q_RELOCATABLE_TYPE);
-Q_DECLARE_TYPEINFO(QRhiVulkan::TextureReadback, Q_RELOCATABLE_TYPE);
-Q_DECLARE_TYPEINFO(QRhiVulkan::BufferReadback, Q_RELOCATABLE_TYPE);
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/rhi/qshader.cpp b/src/gui/rhi/qshader.cpp
index 52cb503521..0cc98c44d6 100644
--- a/src/gui/rhi/qshader.cpp
+++ b/src/gui/rhi/qshader.cpp
@@ -1,7 +1,7 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#include "qshader_p_p.h"
+#include "qshader_p.h"
 #include <QDataStream>
 #include <QBuffer>
 
@@ -9,8 +9,9 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QShader
-    \internal
+    \ingroup painting-3D
     \inmodule QtGui
+    \since 6.6
 
     \brief Contains multiple versions of a shader translated to multiple shading languages,
     together with reflection metadata.
@@ -21,6 +22,16 @@ QT_BEGIN_NAMESPACE
     as, Vulkan, Metal, Direct3D, and OpenGL, take QShader as their input
     whenever a shader needs to be specified.
 
+    \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/qshader.h>}.
+
     A QShader instance is empty and thus invalid by default. To get a useful
     instance, the two typical methods are:
 
@@ -68,8 +79,9 @@ QT_BEGIN_NAMESPACE
     can be returned or passed by value. Detach happens implicitly when calling
     a setter.
 
-    For reference, QRhi expects that a QShader suitable for all its
-    backends contains at least the following:
+    For reference, a typical, portable QRhi expects that a QShader suitable for
+    all its backends contains at least the following. (this excludes support
+    for core profile OpenGL contexts, add GLSL 150 or newer for that)
 
     \list
 
@@ -77,11 +89,11 @@ QT_BEGIN_NAMESPACE
 
     \li GLSL/ES 100 source code suitable for OpenGL ES 2.0 or newer
 
-    \li GLSL 120 source code suitable for OpenGL 2.1
+    \li GLSL 120 source code suitable for OpenGL 2.1 or newer
 
-    \li HLSL Shader Model 5.0 source code or the corresponding DXBC bytecode suitable for Direct3D 11
+    \li HLSL Shader Model 5.0 source code or the corresponding DXBC bytecode suitable for Direct3D 11/12
 
-    \li Metal Shading Language 1.2 source code or the corresponding bytecode suitable for Metal
+    \li Metal Shading Language 1.2 source code or the corresponding bytecode suitable for Metal 1.2 or newer
 
     \endlist
 
@@ -102,8 +114,8 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QShaderVersion
-    \internal
     \inmodule QtGui
+    \since 6.6
 
     \brief Specifies the shading language version.
 
@@ -128,6 +140,9 @@ QT_BEGIN_NAMESPACE
 
     A default constructed QShaderVersion contains a version of 100 and no
     flags set.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShader
+    for details.
  */
 
 /*!
@@ -140,13 +155,16 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QShaderKey
-    \internal
     \inmodule QtGui
+    \since 6.6
 
     \brief Specifies the shading language, the version with flags, and the variant.
 
     A default constructed QShaderKey has source set to SpirvShader and
     sourceVersion set to 100. sourceVariant defaults to StandardShader.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShader
+    for details.
  */
 
 /*!
@@ -197,13 +215,16 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QShaderCode
-    \internal
     \inmodule QtGui
+    \since 6.6
 
     \brief Contains source or binary code for a shader and additional metadata.
 
     When shader() is empty after retrieving a QShaderCode instance from
     QShader, it indicates no shader code was found for the requested key.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShader
+    for details.
  */
 
 /*!
@@ -226,7 +247,7 @@ void QShader::detach()
 }
 
 /*!
-    \internal
+    Constructs a copy of \a other.
  */
 QShader::QShader(const QShader &other)
     : d(other.d)
@@ -236,7 +257,7 @@ QShader::QShader(const QShader &other)
 }
 
 /*!
-    \internal
+    Assigns \a other to this object.
  */
 QShader &QShader::operator=(const QShader &other)
 {
@@ -577,16 +598,79 @@ QShader QShader::fromSerialized(const QByteArray &data)
     return bs;
 }
 
+/*!
+    \fn QShaderVersion::QShaderVersion() = default
+ */
+
+/*!
+    Constructs a new QShaderVersion with version \a v and flags \a f.
+ */
 QShaderVersion::QShaderVersion(int v, Flags f)
     : m_version(v), m_flags(f)
 {
 }
 
+/*!
+    \fn int QShaderVersion::version() const
+    \return the version.
+ */
+
+/*!
+    \fn void QShaderVersion::setVersion(int v)
+    Sets the shading language version to \a v.
+ */
+
+/*!
+    \fn QShaderVersion::Flags QShaderVersion::flags() const
+    \return the flags.
+ */
+
+/*!
+    \fn void QShaderVersion::setFlags(Flags f)
+    Sets the flags \a f.
+ */
+
+/*!
+    \fn QShaderCode::QShaderCode() = default
+ */
+
+/*!
+    Constructs a new QShaderCode with the specified shader source \a code and
+    \a entry point name.
+ */
 QShaderCode::QShaderCode(const QByteArray &code, const QByteArray &entry)
     : m_shader(code), m_entryPoint(entry)
 {
 }
 
+/*!
+    \fn QByteArray QShaderCode::shader() const
+    \return the shader source or bytecode.
+ */
+
+/*!
+    \fn void QShaderCode::setShader(const QByteArray &code)
+    Sets the shader source or byte \a code.
+ */
+
+/*!
+    \fn QByteArray QShaderCode::entryPoint() const
+    \return the entry point name.
+ */
+
+/*!
+    \fn void QShaderCode::setEntryPoint(const QByteArray &entry)
+    Sets the \a entry point name.
+ */
+
+/*!
+    \fn QShaderKey::QShaderKey() = default
+ */
+
+/*!
+    Constructs a new QShaderKey with shader type \a s, version \a sver, and
+    variant \a svar.
+ */
 QShaderKey::QShaderKey(QShader::Source s,
                        const QShaderVersion &sver,
                        QShader::Variant svar)
@@ -597,6 +681,36 @@ QShaderKey::QShaderKey(QShader::Source s,
 }
 
 /*!
+    \fn QShader::Source QShaderKey::source() const
+    \return the shader type.
+ */
+
+/*!
+    \fn void QShaderKey::setSource(QShader::Source s)
+    Sets the shader type \a s.
+ */
+
+/*!
+    \fn QShaderVersion QShaderKey::sourceVersion() const
+    \return the shading language version.
+ */
+
+/*!
+    \fn void QShaderKey::setSourceVersion(const QShaderVersion &sver)
+    Sets the shading language version \a sver.
+ */
+
+/*!
+    \fn QShader::Variant QShaderKey::sourceVariant() const
+    \return the type of the variant to use.
+ */
+
+/*!
+    \fn void QShaderKey::setSourceVariant(QShader::Variant svar)
+    Sets the type of variant to use to \a svar.
+ */
+
+/*!
     Returns \c true if the two QShader objects \a lhs and \a rhs are equal,
     meaning they are for the same stage with matching sets of shader source or
     binary code.
@@ -614,10 +728,9 @@ bool operator==(const QShader &lhs, const QShader &rhs) noexcept
 }
 
 /*!
-    \internal
     \fn bool operator!=(const QShader &lhs, const QShader &rhs)
 
-    Returns \c false if the values in the two QShader objects \a a and \a b
+    Returns \c false if the values in the two QShader objects \a lhs and \a rhs
     are equal; otherwise returns \c true.
 
     \relates QShader
@@ -660,6 +773,8 @@ size_t qHash(const QShaderVersion &s, size_t seed) noexcept
 #endif
 
 /*!
+    \return true if \a lhs is smaller than \a rhs.
+
     Establishes a sorting order between the two QShaderVersion \a lhs and \a rhs.
 
     \relates QShaderVersion
@@ -676,11 +791,10 @@ bool operator<(const QShaderVersion &lhs, const QShaderVersion &rhs) noexcept
 }
 
 /*!
-    \internal
     \fn bool operator!=(const QShaderVersion &lhs, const QShaderVersion &rhs)
 
-    Returns \c false if the values in the two QShaderVersion objects \a a
-    and \a b are equal; otherwise returns \c true.
+    Returns \c false if the values in the two QShaderVersion objects \a lhs
+    and \a rhs are equal; otherwise returns \c true.
 
     \relates QShaderVersion
  */
@@ -697,6 +811,8 @@ bool operator==(const QShaderKey &lhs, const QShaderKey &rhs) noexcept
 }
 
 /*!
+    \return true if \a lhs is smaller than \a rhs.
+
     Establishes a sorting order between the two keys \a lhs and \a rhs.
 
     \relates QShaderKey
@@ -719,11 +835,10 @@ bool operator<(const QShaderKey &lhs, const QShaderKey &rhs) noexcept
 }
 
 /*!
-    \internal
     \fn bool operator!=(const QShaderKey &lhs, const QShaderKey &rhs)
 
-    Returns \c false if the values in the two QShaderKey objects \a a
-    and \a b are equal; otherwise returns \c true.
+    Returns \c false if the values in the two QShaderKey objects \a lhs
+    and \a rhs are equal; otherwise returns \c true.
 
     \relates QShaderKey
  */
@@ -753,11 +868,10 @@ bool operator==(const QShaderCode &lhs, const QShaderCode &rhs) noexcept
 }
 
 /*!
-    \internal
     \fn bool operator!=(const QShaderCode &lhs, const QShaderCode &rhs)
 
-    Returns \c false if the values in the two QShaderCode objects \a a
-    and \a b are equal; otherwise returns \c true.
+    Returns \c false if the values in the two QShaderCode objects \a lhs
+    and \a rhs are equal; otherwise returns \c true.
 
     \relates QShaderCode
  */
@@ -895,6 +1009,7 @@ void QShader::removeResourceBindingMap(const QShaderKey &key)
 
 /*!
     \struct QShader::SeparateToCombinedImageSamplerMapping
+    \brief Mapping metadata for sampler uniforms.
 
     Describes a mapping from a traditional combined image sampler uniform to
     binding points for a separate texture and sampler.
@@ -904,9 +1019,24 @@ void QShader::removeResourceBindingMap(const QShaderKey &key)
     contains a \c sampler2D (or sampler3D, etc.) uniform with the name of
     \c{_54} which corresponds to two separate resource bindings (\c 1 and \c 2)
     in the original shader.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShader
+    for details.
  */
 
 /*!
+    \variable QShader::SeparateToCombinedImageSamplerMapping::combinedSamplerName
+*/
+
+/*!
+    \variable QShader::SeparateToCombinedImageSamplerMapping::textureBinding
+*/
+
+/*!
+    \variable QShader::SeparateToCombinedImageSamplerMapping::samplerBinding
+*/
+
+/*!
     \return the combined image sampler mapping list for \a key, or an empty
     list if there is no data available for \a key, for example because such a
     mapping is not applicable for the shading language.
@@ -953,6 +1083,7 @@ void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &
 
 /*!
     \struct QShader::NativeShaderInfo
+    \brief Additional metadata about the native shader code.
 
     Describes information about the native shader code, if applicable. This
     becomes relevant with certain shader languages for certain shader stages,
@@ -969,9 +1100,20 @@ void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &
     not be present at all if per-patch output variables were not used. The fact
     that the shader code relies on such a buffer present can be indicated by
     the data in this struct.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShader
+    for details.
  */
 
 /*!
+    \variable QShader::NativeShaderInfo::flags
+*/
+
+/*!
+    \variable QShader::NativeShaderInfo::extraBufferBindings
+*/
+
+/*!
     \return the native shader info struct for \a key, or an empty object if
     there is no data available for \a key, for example because such a mapping
     is not applicable for the shading language or the shader stage.
diff --git a/src/gui/rhi/qshader.h b/src/gui/rhi/qshader.h
new file mode 100644
index 0000000000..0b52022596
--- /dev/null
+++ b/src/gui/rhi/qshader.h
@@ -0,0 +1,237 @@
+// 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
+
+#ifndef QSHADER_H
+#define QSHADER_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is part of the RHI API, with limited compatibility guarantees.
+// Usage of this API may make your code source and binary incompatible with
+// future versions of Qt.
+//
+
+#include <QtGui/qtguiglobal.h>
+#include <QtCore/qhash.h>
+#include <QtCore/qmap.h>
+#include <rhi/qshaderdescription.h>
+
+QT_BEGIN_NAMESPACE
+
+struct QShaderPrivate;
+class QShaderKey;
+
+#ifdef Q_OS_INTEGRITY
+  class QShaderVersion;
+  size_t qHash(const QShaderVersion &, size_t = 0) noexcept;
+#endif
+
+class Q_GUI_EXPORT QShaderVersion
+{
+public:
+    enum Flag {
+        GlslEs = 0x01
+    };
+    Q_DECLARE_FLAGS(Flags, Flag)
+
+    QShaderVersion() = default;
+    QShaderVersion(int v, Flags f = Flags());
+
+    int version() const { return m_version; }
+    void setVersion(int v) { m_version = v; }
+
+    Flags flags() const { return m_flags; }
+    void setFlags(Flags f) { m_flags = f; }
+
+private:
+    int m_version = 100;
+    Flags m_flags;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QShaderVersion::Flags)
+Q_DECLARE_TYPEINFO(QShaderVersion, Q_RELOCATABLE_TYPE);
+
+class QShaderCode;
+Q_GUI_EXPORT size_t qHash(const QShaderCode &, size_t = 0) noexcept;
+
+class Q_GUI_EXPORT QShaderCode
+{
+public:
+    QShaderCode() = default;
+    QShaderCode(const QByteArray &code, const QByteArray &entry = QByteArray());
+
+    QByteArray shader() const { return m_shader; }
+    void setShader(const QByteArray &code) { m_shader = code; }
+
+    QByteArray entryPoint() const { return m_entryPoint; }
+    void setEntryPoint(const QByteArray &entry) { m_entryPoint = entry; }
+
+private:
+    friend Q_GUI_EXPORT size_t qHash(const QShaderCode &, size_t) noexcept;
+
+    QByteArray m_shader;
+    QByteArray m_entryPoint;
+};
+
+Q_DECLARE_TYPEINFO(QShaderCode, Q_RELOCATABLE_TYPE);
+
+class Q_GUI_EXPORT QShader
+{
+public:
+    enum Stage {
+        VertexStage = 0,
+        TessellationControlStage,
+        TessellationEvaluationStage,
+        GeometryStage,
+        FragmentStage,
+        ComputeStage
+    };
+
+    enum Source {
+        SpirvShader = 0,
+        GlslShader,
+        HlslShader,
+        DxbcShader, // fxc
+        MslShader,
+        DxilShader, // dxc
+        MetalLibShader, // xcrun metal + xcrun metallib
+        WgslShader
+    };
+
+    enum Variant {
+        StandardShader = 0,
+        BatchableVertexShader,
+        UInt16IndexedVertexAsComputeShader,
+        UInt32IndexedVertexAsComputeShader,
+        NonIndexedVertexAsComputeShader
+    };
+
+    enum class SerializedFormatVersion {
+        Latest = 0,
+        Qt_6_5,
+        Qt_6_4
+    };
+
+    QShader();
+    QShader(const QShader &other);
+    QShader &operator=(const QShader &other);
+    ~QShader();
+    void detach();
+
+    bool isValid() const;
+
+    Stage stage() const;
+    void setStage(Stage stage);
+
+    QShaderDescription description() const;
+    void setDescription(const QShaderDescription &desc);
+
+    QList<QShaderKey> availableShaders() const;
+    QShaderCode shader(const QShaderKey &key) const;
+    void setShader(const QShaderKey &key, const QShaderCode &shader);
+    void removeShader(const QShaderKey &key);
+
+    QByteArray serialized(SerializedFormatVersion version = SerializedFormatVersion::Latest) const;
+    static QShader fromSerialized(const QByteArray &data);
+
+    using NativeResourceBindingMap = QMap<int, QPair<int, int> >; // binding -> native_binding[, native_binding]
+    NativeResourceBindingMap nativeResourceBindingMap(const QShaderKey &key) const;
+    void setResourceBindingMap(const QShaderKey &key, const NativeResourceBindingMap &map);
+    void removeResourceBindingMap(const QShaderKey &key);
+
+    struct SeparateToCombinedImageSamplerMapping {
+        QByteArray combinedSamplerName;
+        int textureBinding;
+        int samplerBinding;
+    };
+    using SeparateToCombinedImageSamplerMappingList = QList<SeparateToCombinedImageSamplerMapping>;
+    SeparateToCombinedImageSamplerMappingList separateToCombinedImageSamplerMappingList(const QShaderKey &key) const;
+    void setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key,
+                                                      const SeparateToCombinedImageSamplerMappingList &list);
+    void removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key);
+
+    struct NativeShaderInfo {
+        int flags = 0;
+        QMap<int, int> extraBufferBindings;
+    };
+    NativeShaderInfo nativeShaderInfo(const QShaderKey &key) const;
+    void setNativeShaderInfo(const QShaderKey &key, const NativeShaderInfo &info);
+    void removeNativeShaderInfo(const QShaderKey &key);
+
+private:
+    QShaderPrivate *d;
+    friend struct QShaderPrivate;
+    friend Q_GUI_EXPORT bool operator==(const QShader &, const QShader &) noexcept;
+    friend Q_GUI_EXPORT size_t qHash(const QShader &, size_t) noexcept;
+#ifndef QT_NO_DEBUG_STREAM
+    friend Q_GUI_EXPORT QDebug operator<<(QDebug, const QShader &);
+#endif
+};
+
+class Q_GUI_EXPORT QShaderKey
+{
+public:
+    QShaderKey() = default;
+    QShaderKey(QShader::Source s,
+               const QShaderVersion &sver,
+               QShader::Variant svar = QShader::StandardShader);
+
+    QShader::Source source() const { return m_source; }
+    void setSource(QShader::Source s) { m_source = s; }
+
+    QShaderVersion sourceVersion() const { return m_sourceVersion; }
+    void setSourceVersion(const QShaderVersion &sver) { m_sourceVersion = sver; }
+
+    QShader::Variant sourceVariant() const { return m_sourceVariant; }
+    void setSourceVariant(QShader::Variant svar) { m_sourceVariant = svar; }
+
+private:
+    QShader::Source m_source = QShader::SpirvShader;
+    QShaderVersion m_sourceVersion;
+    QShader::Variant m_sourceVariant = QShader::StandardShader;
+};
+
+Q_DECLARE_TYPEINFO(QShaderKey, Q_RELOCATABLE_TYPE);
+
+Q_GUI_EXPORT bool operator==(const QShader &lhs, const QShader &rhs) noexcept;
+Q_GUI_EXPORT size_t qHash(const QShader &s, size_t seed = 0) noexcept;
+
+inline bool operator!=(const QShader &lhs, const QShader &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+Q_GUI_EXPORT bool operator==(const QShaderVersion &lhs, const QShaderVersion &rhs) noexcept;
+Q_GUI_EXPORT bool operator<(const QShaderVersion &lhs, const QShaderVersion &rhs) noexcept;
+Q_GUI_EXPORT bool operator==(const QShaderKey &lhs, const QShaderKey &rhs) noexcept;
+Q_GUI_EXPORT bool operator<(const QShaderKey &lhs, const QShaderKey &rhs) noexcept;
+Q_GUI_EXPORT bool operator==(const QShaderCode &lhs, const QShaderCode &rhs) noexcept;
+
+inline bool operator!=(const QShaderVersion &lhs, const QShaderVersion &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+inline bool operator!=(const QShaderKey &lhs, const QShaderKey &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+inline bool operator!=(const QShaderCode &lhs, const QShaderCode &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+Q_GUI_EXPORT size_t qHash(const QShaderKey &k, size_t seed = 0) noexcept;
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QShader &);
+Q_GUI_EXPORT QDebug operator<<(QDebug dbg, const QShaderKey &k);
+Q_GUI_EXPORT QDebug operator<<(QDebug dbg, const QShaderVersion &v);
+#endif
+
+QT_END_NAMESPACE
+
+#endif
diff --git a/src/gui/rhi/qshader_p.h b/src/gui/rhi/qshader_p.h
index f85b075a83..a2df33d96b 100644
--- a/src/gui/rhi/qshader_p.h
+++ b/src/gui/rhi/qshader_p.h
@@ -1,4 +1,4 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
 #ifndef QSHADER_P_H
@@ -15,225 +15,76 @@
 // We mean it.
 //
 
-#include <QtGui/qtguiglobal.h>
-#include <QtCore/qhash.h>
-#include <QtCore/qmap.h>
-#include <private/qshaderdescription_p.h>
+#include <rhi/qshader.h>
+#include <QtCore/QAtomicInt>
+#include <QtCore/QMap>
+#include <QtCore/QDebug>
 
 QT_BEGIN_NAMESPACE
 
-struct QShaderPrivate;
-class QShaderKey;
-
-#ifdef Q_OS_INTEGRITY
-  class QShaderVersion;
-  size_t qHash(const QShaderVersion &, size_t = 0) noexcept;
-#endif
-
-class Q_GUI_EXPORT QShaderVersion
-{
-public:
-    enum Flag {
-        GlslEs = 0x01
-    };
-    Q_DECLARE_FLAGS(Flags, Flag)
-
-    QShaderVersion() = default;
-    QShaderVersion(int v, Flags f = Flags());
-
-    int version() const { return m_version; }
-    void setVersion(int v) { m_version = v; }
-
-    Flags flags() const { return m_flags; }
-    void setFlags(Flags f) { m_flags = f; }
-
-private:
-    int m_version = 100;
-    Flags m_flags;
-};
-
-Q_DECLARE_OPERATORS_FOR_FLAGS(QShaderVersion::Flags)
-Q_DECLARE_TYPEINFO(QShaderVersion, Q_RELOCATABLE_TYPE);
-
-class QShaderCode;
-Q_GUI_EXPORT size_t qHash(const QShaderCode &, size_t = 0) noexcept;
-
-class Q_GUI_EXPORT QShaderCode
-{
-public:
-    QShaderCode() = default;
-    QShaderCode(const QByteArray &code, const QByteArray &entry = QByteArray());
-
-    QByteArray shader() const { return m_shader; }
-    void setShader(const QByteArray &code) { m_shader = code; }
-
-    QByteArray entryPoint() const { return m_entryPoint; }
-    void setEntryPoint(const QByteArray &entry) { m_entryPoint = entry; }
-
-private:
-    friend Q_GUI_EXPORT size_t qHash(const QShaderCode &, size_t) noexcept;
-
-    QByteArray m_shader;
-    QByteArray m_entryPoint;
-};
-
-Q_DECLARE_TYPEINFO(QShaderCode, Q_RELOCATABLE_TYPE);
-
-class Q_GUI_EXPORT QShader
+struct Q_GUI_EXPORT QShaderPrivate
 {
-public:
-    enum Stage {
-        VertexStage = 0,
-        TessellationControlStage,
-        TessellationEvaluationStage,
-        GeometryStage,
-        FragmentStage,
-        ComputeStage
-    };
-
-    enum Source {
-        SpirvShader = 0,
-        GlslShader,
-        HlslShader,
-        DxbcShader, // fxc
-        MslShader,
-        DxilShader, // dxc
-        MetalLibShader, // xcrun metal + xcrun metallib
-        WgslShader
-    };
-
-    enum Variant {
-        StandardShader = 0,
-        BatchableVertexShader,
-        UInt16IndexedVertexAsComputeShader,
-        UInt32IndexedVertexAsComputeShader,
-        NonIndexedVertexAsComputeShader
-    };
-
-    enum class SerializedFormatVersion {
-        Latest = 0,
-        Qt_6_5,
-        Qt_6_4
-    };
-
-    QShader();
-    QShader(const QShader &other);
-    QShader &operator=(const QShader &other);
-    ~QShader();
-    void detach();
-
-    bool isValid() const;
-
-    Stage stage() const;
-    void setStage(Stage stage);
-
-    QShaderDescription description() const;
-    void setDescription(const QShaderDescription &desc);
-
-    QList<QShaderKey> availableShaders() const;
-    QShaderCode shader(const QShaderKey &key) const;
-    void setShader(const QShaderKey &key, const QShaderCode &shader);
-    void removeShader(const QShaderKey &key);
-
-    QByteArray serialized(SerializedFormatVersion version = SerializedFormatVersion::Latest) const;
-    static QShader fromSerialized(const QByteArray &data);
-
-    using NativeResourceBindingMap = QMap<int, QPair<int, int> >; // binding -> native_binding[, native_binding]
-    NativeResourceBindingMap nativeResourceBindingMap(const QShaderKey &key) const;
-    void setResourceBindingMap(const QShaderKey &key, const NativeResourceBindingMap &map);
-    void removeResourceBindingMap(const QShaderKey &key);
-
-    struct SeparateToCombinedImageSamplerMapping {
-        QByteArray combinedSamplerName;
-        int textureBinding;
-        int samplerBinding;
-    };
-    using SeparateToCombinedImageSamplerMappingList = QList<SeparateToCombinedImageSamplerMapping>;
-    SeparateToCombinedImageSamplerMappingList separateToCombinedImageSamplerMappingList(const QShaderKey &key) const;
-    void setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key,
-                                                      const SeparateToCombinedImageSamplerMappingList &list);
-    void removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key);
-
-    struct NativeShaderInfo {
-        int flags = 0;
-        QMap<int, int> extraBufferBindings;
+    static const int QSB_VERSION = 9;
+    static const int QSB_VERSION_WITHOUT_INPUT_OUTPUT_INTERFACE_BLOCKS = 8;
+    static const int QSB_VERSION_WITHOUT_EXTENDED_STORAGE_BUFFER_INFO = 7;
+    static const int QSB_VERSION_WITHOUT_NATIVE_SHADER_INFO = 6;
+    static const int QSB_VERSION_WITHOUT_SEPARATE_IMAGES_AND_SAMPLERS = 5;
+    static const int QSB_VERSION_WITHOUT_VAR_ARRAYDIMS = 4;
+    static const int QSB_VERSION_WITH_CBOR = 3;
+    static const int QSB_VERSION_WITH_BINARY_JSON = 2;
+    static const int QSB_VERSION_WITHOUT_BINDINGS = 1;
+
+    enum MslNativeShaderInfoExtraBufferBindings {
+        MslTessVertIndicesBufferBinding = 0,
+        MslTessVertTescOutputBufferBinding,
+        MslTessTescTessLevelBufferBinding,
+        MslTessTescPatchOutputBufferBinding,
+        MslTessTescParamsBufferBinding,
+        MslTessTescInputBufferBinding,
+        MslBufferSizeBufferBinding
     };
-    NativeShaderInfo nativeShaderInfo(const QShaderKey &key) const;
-    void setNativeShaderInfo(const QShaderKey &key, const NativeShaderInfo &info);
-    void removeNativeShaderInfo(const QShaderKey &key);
-
-private:
-    QShaderPrivate *d;
-    friend struct QShaderPrivate;
-    friend Q_GUI_EXPORT bool operator==(const QShader &, const QShader &) noexcept;
-    friend Q_GUI_EXPORT size_t qHash(const QShader &, size_t) noexcept;
-#ifndef QT_NO_DEBUG_STREAM
-    friend Q_GUI_EXPORT QDebug operator<<(QDebug, const QShader &);
-#endif
-};
-
-class Q_GUI_EXPORT QShaderKey
-{
-public:
-    QShaderKey() = default;
-    QShaderKey(QShader::Source s,
-               const QShaderVersion &sver,
-               QShader::Variant svar = QShader::StandardShader);
-
-    QShader::Source source() const { return m_source; }
-    void setSource(QShader::Source s) { m_source = s; }
-
-    QShaderVersion sourceVersion() const { return m_sourceVersion; }
-    void setSourceVersion(const QShaderVersion &sver) { m_sourceVersion = sver; }
 
-    QShader::Variant sourceVariant() const { return m_sourceVariant; }
-    void setSourceVariant(QShader::Variant svar) { m_sourceVariant = svar; }
-
-private:
-    QShader::Source m_source = QShader::SpirvShader;
-    QShaderVersion m_sourceVersion;
-    QShader::Variant m_sourceVariant = QShader::StandardShader;
+    QShaderPrivate()
+        : ref(1)
+    {
+    }
+
+    QShaderPrivate(const QShaderPrivate &other)
+        : ref(1),
+          qsbVersion(other.qsbVersion),
+          stage(other.stage),
+          desc(other.desc),
+          shaders(other.shaders),
+          bindings(other.bindings),
+          combinedImageMap(other.combinedImageMap),
+          nativeShaderInfoMap(other.nativeShaderInfoMap)
+    {
+    }
+
+    static QShaderPrivate *get(QShader *s) { return s->d; }
+    static const QShaderPrivate *get(const QShader *s) { return s->d; }
+    static int qtQsbVersion(QShader::SerializedFormatVersion qtVersion) {
+        switch (qtVersion) {
+        case QShader::SerializedFormatVersion::Qt_6_4:
+            return (QShaderPrivate::QSB_VERSION_WITHOUT_SEPARATE_IMAGES_AND_SAMPLERS + 1);
+        case QShader::SerializedFormatVersion::Qt_6_5:
+            return (QShaderPrivate::QSB_VERSION_WITHOUT_EXTENDED_STORAGE_BUFFER_INFO + 1);
+        default:
+            return QShaderPrivate::QSB_VERSION;
+        }
+    }
+
+    QAtomicInt ref;
+    int qsbVersion = QSB_VERSION;
+    QShader::Stage stage = QShader::VertexStage;
+    QShaderDescription desc;
+    // QMap not QHash because we need to be able to iterate based on sorted keys
+    QMap<QShaderKey, QShaderCode> shaders;
+    QMap<QShaderKey, QShader::NativeResourceBindingMap> bindings;
+    QMap<QShaderKey, QShader::SeparateToCombinedImageSamplerMappingList> combinedImageMap;
+    QMap<QShaderKey, QShader::NativeShaderInfo> nativeShaderInfoMap;
 };
 
-Q_DECLARE_TYPEINFO(QShaderKey, Q_RELOCATABLE_TYPE);
-
-Q_GUI_EXPORT bool operator==(const QShader &lhs, const QShader &rhs) noexcept;
-Q_GUI_EXPORT size_t qHash(const QShader &s, size_t seed = 0) noexcept;
-
-inline bool operator!=(const QShader &lhs, const QShader &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-Q_GUI_EXPORT bool operator==(const QShaderVersion &lhs, const QShaderVersion &rhs) noexcept;
-Q_GUI_EXPORT bool operator<(const QShaderVersion &lhs, const QShaderVersion &rhs) noexcept;
-Q_GUI_EXPORT bool operator==(const QShaderKey &lhs, const QShaderKey &rhs) noexcept;
-Q_GUI_EXPORT bool operator<(const QShaderKey &lhs, const QShaderKey &rhs) noexcept;
-Q_GUI_EXPORT bool operator==(const QShaderCode &lhs, const QShaderCode &rhs) noexcept;
-
-inline bool operator!=(const QShaderVersion &lhs, const QShaderVersion &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-inline bool operator!=(const QShaderKey &lhs, const QShaderKey &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-inline bool operator!=(const QShaderCode &lhs, const QShaderCode &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-Q_GUI_EXPORT size_t qHash(const QShaderKey &k, size_t seed = 0) noexcept;
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QShader &);
-Q_GUI_EXPORT QDebug operator<<(QDebug dbg, const QShaderKey &k);
-Q_GUI_EXPORT QDebug operator<<(QDebug dbg, const QShaderVersion &v);
-#endif
-
 QT_END_NAMESPACE
 
 #endif
diff --git a/src/gui/rhi/qshader_p_p.h b/src/gui/rhi/qshader_p_p.h
deleted file mode 100644
index 9cc9207f69..0000000000
--- a/src/gui/rhi/qshader_p_p.h
+++ /dev/null
@@ -1,90 +0,0 @@
-// Copyright (C) 2019 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
-
-#ifndef QSHADER_P_P_H
-#define QSHADER_P_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists for the convenience
-// of a number of Qt sources files.  This header file may change from
-// version to version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qshader_p.h"
-#include <QtCore/QAtomicInt>
-#include <QtCore/QMap>
-#include <QtCore/QDebug>
-
-QT_BEGIN_NAMESPACE
-
-struct Q_GUI_EXPORT QShaderPrivate
-{
-    static const int QSB_VERSION = 9;
-    static const int QSB_VERSION_WITHOUT_INPUT_OUTPUT_INTERFACE_BLOCKS = 8;
-    static const int QSB_VERSION_WITHOUT_EXTENDED_STORAGE_BUFFER_INFO = 7;
-    static const int QSB_VERSION_WITHOUT_NATIVE_SHADER_INFO = 6;
-    static const int QSB_VERSION_WITHOUT_SEPARATE_IMAGES_AND_SAMPLERS = 5;
-    static const int QSB_VERSION_WITHOUT_VAR_ARRAYDIMS = 4;
-    static const int QSB_VERSION_WITH_CBOR = 3;
-    static const int QSB_VERSION_WITH_BINARY_JSON = 2;
-    static const int QSB_VERSION_WITHOUT_BINDINGS = 1;
-
-    enum MslNativeShaderInfoExtraBufferBindings {
-        MslTessVertIndicesBufferBinding = 0,
-        MslTessVertTescOutputBufferBinding,
-        MslTessTescTessLevelBufferBinding,
-        MslTessTescPatchOutputBufferBinding,
-        MslTessTescParamsBufferBinding,
-        MslTessTescInputBufferBinding,
-        MslBufferSizeBufferBinding
-    };
-
-    QShaderPrivate()
-        : ref(1)
-    {
-    }
-
-    QShaderPrivate(const QShaderPrivate &other)
-        : ref(1),
-          qsbVersion(other.qsbVersion),
-          stage(other.stage),
-          desc(other.desc),
-          shaders(other.shaders),
-          bindings(other.bindings),
-          combinedImageMap(other.combinedImageMap),
-          nativeShaderInfoMap(other.nativeShaderInfoMap)
-    {
-    }
-
-    static QShaderPrivate *get(QShader *s) { return s->d; }
-    static const QShaderPrivate *get(const QShader *s) { return s->d; }
-    static int qtQsbVersion(QShader::SerializedFormatVersion qtVersion) {
-        switch (qtVersion) {
-        case QShader::SerializedFormatVersion::Qt_6_4:
-            return (QShaderPrivate::QSB_VERSION_WITHOUT_SEPARATE_IMAGES_AND_SAMPLERS + 1);
-        case QShader::SerializedFormatVersion::Qt_6_5:
-            return (QShaderPrivate::QSB_VERSION_WITHOUT_EXTENDED_STORAGE_BUFFER_INFO + 1);
-        default:
-            return QShaderPrivate::QSB_VERSION;
-        }
-    }
-
-    QAtomicInt ref;
-    int qsbVersion = QSB_VERSION;
-    QShader::Stage stage = QShader::VertexStage;
-    QShaderDescription desc;
-    // QMap not QHash because we need to be able to iterate based on sorted keys
-    QMap<QShaderKey, QShaderCode> shaders;
-    QMap<QShaderKey, QShader::NativeResourceBindingMap> bindings;
-    QMap<QShaderKey, QShader::SeparateToCombinedImageSamplerMappingList> combinedImageMap;
-    QMap<QShaderKey, QShader::NativeShaderInfo> nativeShaderInfoMap;
-};
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/rhi/qshaderdescription.cpp b/src/gui/rhi/qshaderdescription.cpp
index 44fcd936fd..97b8798034 100644
--- a/src/gui/rhi/qshaderdescription.cpp
+++ b/src/gui/rhi/qshaderdescription.cpp
@@ -1,8 +1,8 @@
-// Copyright (C) 2019 The Qt Company Ltd.
+// 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
 
-#include "qshaderdescription_p_p.h"
-#include "qshader_p_p.h"
+#include "qshaderdescription_p.h"
+#include "qshader_p.h"
 #include <QDebug>
 #include <QDataStream>
 #include <QJsonObject>
@@ -12,11 +12,22 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QShaderDescription
-    \internal
+    \ingroup painting-3D
     \inmodule QtGui
+    \since 6.6
 
     \brief Describes the interface of a shader.
 
+    \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/qshaderdescription.h>}.
+
     A shader typically has a set of inputs and outputs. A vertex shader for
     example has a number of input variables and may use one or more uniform
     buffers to access data (e.g. a modelview matrix) provided by the
@@ -51,8 +62,6 @@ QT_BEGIN_NAMESPACE
             float opacity;
         } ubuf;
 
-        out gl_PerVertex { vec4 gl_Position; };
-
         void main()
         {
             v_color = color;
@@ -200,28 +209,179 @@ QT_BEGIN_NAMESPACE
     \value ImageRect
     \value ImageBuffer
     \value Struct
+    \value Half
+    \value Half2
+    \value Half3
+    \value Half4
  */
 
 /*!
-    \class QShaderDescription::InOutVariable
-    \internal
+    \enum QShaderDescription::ImageFormat
+    Image format.
+
+    \value ImageFormatUnknown
+    \value ImageFormatRgba32f
+    \value ImageFormatRgba16f
+    \value ImageFormatR32f
+    \value ImageFormatRgba8
+    \value ImageFormatRgba8Snorm
+    \value ImageFormatRg32f
+    \value ImageFormatRg16f
+    \value ImageFormatR11fG11fB10f
+    \value ImageFormatR16f
+    \value ImageFormatRgba16
+    \value ImageFormatRgb10A2
+    \value ImageFormatRg16
+    \value ImageFormatRg8
+    \value ImageFormatR16
+    \value ImageFormatR8
+    \value ImageFormatRgba16Snorm
+    \value ImageFormatRg16Snorm
+    \value ImageFormatRg8Snorm
+    \value ImageFormatR16Snorm
+    \value ImageFormatR8Snorm
+    \value ImageFormatRgba32i
+    \value ImageFormatRgba16i
+    \value ImageFormatRgba8i
+    \value ImageFormatR32i
+    \value ImageFormatRg32i
+    \value ImageFormatRg16i
+    \value ImageFormatRg8i
+    \value ImageFormatR16i
+    \value ImageFormatR8i
+    \value ImageFormatRgba32ui
+    \value ImageFormatRgba16ui
+    \value ImageFormatRgba8ui
+    \value ImageFormatR32ui
+    \value ImageFormatRgb10a2ui
+    \value ImageFormatRg32ui
+    \value ImageFormatRg16ui
+    \value ImageFormatRg8ui
+    \value ImageFormatR16ui
+    \value ImageFormatR8ui
+ */
+
+/*!
+    \enum QShaderDescription::ImageFlag
+    Image flags.
+
+    \value ReadOnlyImage
+    \value WriteOnlyImage
+ */
+
+/*!
+    \enum QShaderDescription::QualifierFlag
+    Qualifier flags.
+
+    \value QualifierReadOnly
+    \value QualifierWriteOnly
+    \value QualifierCoherent
+    \value QualifierVolatile
+    \value QualifierRestrict
+ */
+
+/*!
+    \struct QShaderDescription::InOutVariable
     \inmodule QtGui
+    \since 6.6
 
     \brief Describes an input or output variable in the shader.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShaderDescription
+    for details.
  */
 
 /*!
-    \class QShaderDescription::BlockVariable
-    \internal
+    \variable QShaderDescription::InOutVariable::name
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::type
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::location
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::binding
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::descriptorSet
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::imageFormat
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::imageFlags
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::arrayDims
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::perPatch
+ */
+
+/*!
+    \variable QShaderDescription::InOutVariable::structMembers
+ */
+
+/*!
+    \struct QShaderDescription::BlockVariable
     \inmodule QtGui
+    \since 6.6
 
     \brief Describes a member of a uniform or push constant block.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShaderDescription
+    for details.
  */
 
 /*!
-    \class QShaderDescription::UniformBlock
-    \internal
+    \variable QShaderDescription::BlockVariable::name
+ */
+
+/*!
+    \variable QShaderDescription::BlockVariable::type
+ */
+
+/*!
+    \variable QShaderDescription::BlockVariable::offset
+ */
+
+/*!
+    \variable QShaderDescription::BlockVariable::size
+ */
+
+/*!
+    \variable QShaderDescription::BlockVariable::arrayDims
+ */
+
+/*!
+    \variable QShaderDescription::BlockVariable::arrayStride
+ */
+
+/*!
+    \variable QShaderDescription::BlockVariable::matrixStride
+ */
+
+/*!
+    \variable QShaderDescription::BlockVariable::matrixIsRowMajor
+ */
+
+/*!
+    \variable QShaderDescription::BlockVariable::structMembers
+ */
+
+/*!
+    \struct QShaderDescription::UniformBlock
     \inmodule QtGui
+    \since 6.6
 
     \brief Describes a uniform block.
 
@@ -229,22 +389,157 @@ QT_BEGIN_NAMESPACE
     (like GLSL 120 or GLSL/ES 100), uniform blocks are replaced with ordinary
     uniforms in a struct. The name of the struct, and so the prefix for the
     uniforms generated from the block members, is given by structName.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShaderDescription
+    for details.
  */
 
 /*!
-    \class QShaderDescription::PushConstantBlock
-    \internal
+    \variable QShaderDescription::UniformBlock::blockName
+ */
+
+/*!
+    \variable QShaderDescription::UniformBlock::structName
+ */
+
+/*!
+    \variable QShaderDescription::UniformBlock::size
+ */
+
+/*!
+    \variable QShaderDescription::UniformBlock::binding
+ */
+
+/*!
+    \variable QShaderDescription::UniformBlock::descriptorSet
+ */
+
+/*!
+    \variable QShaderDescription::UniformBlock::members
+ */
+
+/*!
+    \struct QShaderDescription::PushConstantBlock
     \inmodule QtGui
+    \since 6.6
 
     \brief Describes a push constant block.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShaderDescription
+    for details.
  */
 
 /*!
-    \class QShaderDescription::StorageBlock
-    \internal
+    \variable QShaderDescription::PushConstantBlock::name
+ */
+
+/*!
+    \variable QShaderDescription::PushConstantBlock::size
+ */
+
+/*!
+    \variable QShaderDescription::PushConstantBlock::members
+ */
+
+/*!
+    \struct QShaderDescription::StorageBlock
     \inmodule QtGui
+    \since 6.6
 
     \brief Describes a shader storage block.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShaderDescription
+    for details.
+ */
+
+/*!
+    \variable QShaderDescription::StorageBlock::blockName
+ */
+
+/*!
+    \variable QShaderDescription::StorageBlock::instanceName
+ */
+
+/*!
+    \variable QShaderDescription::StorageBlock::knownSize
+ */
+
+/*!
+    \variable QShaderDescription::StorageBlock::binding
+ */
+
+/*!
+    \variable QShaderDescription::StorageBlock::descriptorSet
+ */
+
+/*!
+    \variable QShaderDescription::StorageBlock::members
+ */
+
+/*!
+    \variable QShaderDescription::StorageBlock::runtimeArrayStride
+ */
+
+/*!
+    \variable QShaderDescription::StorageBlock::qualifierFlags
+ */
+
+/*!
+    \struct QShaderDescription::BuiltinVariable
+    \inmodule QtGui
+    \since 6.6
+
+    \brief Describes a built-in variable.
+
+    \note This a RHI API with limited compatibility guarantees, see \l QShaderDescription
+    for details.
+ */
+
+/*!
+    \variable QShaderDescription::BuiltinVariable::type
+ */
+
+/*!
+    \variable QShaderDescription::BuiltinVariable::varType
+ */
+
+/*!
+    \variable QShaderDescription::BuiltinVariable::arrayDims
+ */
+
+/*!
+    \enum QShaderDescription::BuiltinType
+    Built-in variable type.
+
+    \value PositionBuiltin
+    \value PointSizeBuiltin
+    \value ClipDistanceBuiltin
+    \value CullDistanceBuiltin
+    \value VertexIdBuiltin
+    \value InstanceIdBuiltin
+    \value PrimitiveIdBuiltin
+    \value InvocationIdBuiltin
+    \value LayerBuiltin
+    \value ViewportIndexBuiltin
+    \value TessLevelOuterBuiltin
+    \value TessLevelInnerBuiltin
+    \value TessCoordBuiltin
+    \value PatchVerticesBuiltin
+    \value FragCoordBuiltin
+    \value PointCoordBuiltin
+    \value FrontFacingBuiltin
+    \value SampleIdBuiltin
+    \value SamplePositionBuiltin
+    \value SampleMaskBuiltin
+    \value FragDepthBuiltin
+    \value NumWorkGroupsBuiltin
+    \value WorkgroupSizeBuiltin
+    \value WorkgroupIdBuiltin
+    \value LocalInvocationIdBuiltin
+    \value GlobalInvocationIdBuiltin
+    \value LocalInvocationIndexBuiltin
+    \value VertexIndexBuiltin
+    \value InstanceIndexBuiltin
  */
 
 /*!
@@ -267,7 +562,7 @@ void QShaderDescription::detach()
 }
 
 /*!
-    \internal
+    Constructs a copy of \a other.
  */
 QShaderDescription::QShaderDescription(const QShaderDescription &other)
     : d(other.d)
@@ -276,7 +571,7 @@ QShaderDescription::QShaderDescription(const QShaderDescription &other)
 }
 
 /*!
-    \internal
+    Assigns \a other to this object.
  */
 QShaderDescription &QShaderDescription::operator=(const QShaderDescription &other)
 {
@@ -574,7 +869,7 @@ uint QShaderDescription::tessellationOutputVertexCount() const
     \value UnknownTessellationMode
     \value TrianglesTessellationMode
     \value QuadTessellationMode
-    \value IsolinesTessellationMode
+    \value IsolineTessellationMode
  */
 
 /*!
diff --git a/src/gui/rhi/qshaderdescription.h b/src/gui/rhi/qshaderdescription.h
new file mode 100644
index 0000000000..02492a1598
--- /dev/null
+++ b/src/gui/rhi/qshaderdescription.h
@@ -0,0 +1,386 @@
+// 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
+
+#ifndef QSHADERDESCRIPTION_H
+#define QSHADERDESCRIPTION_H
+
+//
+//  W A R N I N G
+//  -------------
+//
+// This file is part of the RHI API, with limited compatibility guarantees.
+// Usage of this API may make your code source and binary incompatible with
+// future versions of Qt.
+//
+
+#include <QtGui/qtguiglobal.h>
+#include <QtCore/qstring.h>
+#include <QtCore/qlist.h>
+#include <array>
+
+QT_BEGIN_NAMESPACE
+
+struct QShaderDescriptionPrivate;
+class QDataStream;
+
+class Q_GUI_EXPORT QShaderDescription
+{
+public:
+    QShaderDescription();
+    QShaderDescription(const QShaderDescription &other);
+    QShaderDescription &operator=(const QShaderDescription &other);
+    ~QShaderDescription();
+    void detach();
+
+    bool isValid() const;
+
+    void serialize(QDataStream *stream, int version) const;
+    QByteArray toJson() const;
+
+    static QShaderDescription deserialize(QDataStream *stream, int version);
+
+    enum VariableType {
+        Unknown = 0,
+
+        // do not reorder
+        Float,
+        Vec2,
+        Vec3,
+        Vec4,
+        Mat2,
+        Mat2x3,
+        Mat2x4,
+        Mat3,
+        Mat3x2,
+        Mat3x4,
+        Mat4,
+        Mat4x2,
+        Mat4x3,
+
+        Int,
+        Int2,
+        Int3,
+        Int4,
+
+        Uint,
+        Uint2,
+        Uint3,
+        Uint4,
+
+        Bool,
+        Bool2,
+        Bool3,
+        Bool4,
+
+        Double,
+        Double2,
+        Double3,
+        Double4,
+        DMat2,
+        DMat2x3,
+        DMat2x4,
+        DMat3,
+        DMat3x2,
+        DMat3x4,
+        DMat4,
+        DMat4x2,
+        DMat4x3,
+
+        Sampler1D,
+        Sampler2D,
+        Sampler2DMS,
+        Sampler3D,
+        SamplerCube,
+        Sampler1DArray,
+        Sampler2DArray,
+        Sampler2DMSArray,
+        Sampler3DArray,
+        SamplerCubeArray,
+        SamplerRect,
+        SamplerBuffer,
+        SamplerExternalOES,
+        Sampler,
+
+        Image1D,
+        Image2D,
+        Image2DMS,
+        Image3D,
+        ImageCube,
+        Image1DArray,
+        Image2DArray,
+        Image2DMSArray,
+        Image3DArray,
+        ImageCubeArray,
+        ImageRect,
+        ImageBuffer,
+
+        Struct,
+
+        Half,
+        Half2,
+        Half3,
+        Half4
+    };
+
+    enum ImageFormat {
+        // must match SPIR-V's ImageFormat
+        ImageFormatUnknown = 0,
+        ImageFormatRgba32f = 1,
+        ImageFormatRgba16f = 2,
+        ImageFormatR32f = 3,
+        ImageFormatRgba8 = 4,
+        ImageFormatRgba8Snorm = 5,
+        ImageFormatRg32f = 6,
+        ImageFormatRg16f = 7,
+        ImageFormatR11fG11fB10f = 8,
+        ImageFormatR16f = 9,
+        ImageFormatRgba16 = 10,
+        ImageFormatRgb10A2 = 11,
+        ImageFormatRg16 = 12,
+        ImageFormatRg8 = 13,
+        ImageFormatR16 = 14,
+        ImageFormatR8 = 15,
+        ImageFormatRgba16Snorm = 16,
+        ImageFormatRg16Snorm = 17,
+        ImageFormatRg8Snorm = 18,
+        ImageFormatR16Snorm = 19,
+        ImageFormatR8Snorm = 20,
+        ImageFormatRgba32i = 21,
+        ImageFormatRgba16i = 22,
+        ImageFormatRgba8i = 23,
+        ImageFormatR32i = 24,
+        ImageFormatRg32i = 25,
+        ImageFormatRg16i = 26,
+        ImageFormatRg8i = 27,
+        ImageFormatR16i = 28,
+        ImageFormatR8i = 29,
+        ImageFormatRgba32ui = 30,
+        ImageFormatRgba16ui = 31,
+        ImageFormatRgba8ui = 32,
+        ImageFormatR32ui = 33,
+        ImageFormatRgb10a2ui = 34,
+        ImageFormatRg32ui = 35,
+        ImageFormatRg16ui = 36,
+        ImageFormatRg8ui = 37,
+        ImageFormatR16ui = 38,
+        ImageFormatR8ui = 39
+    };
+
+    enum ImageFlag {
+        ReadOnlyImage = 1 << 0,
+        WriteOnlyImage = 1 << 1
+    };
+    Q_DECLARE_FLAGS(ImageFlags, ImageFlag)
+
+    enum QualifierFlag {
+        QualifierReadOnly = 1 << 0,
+        QualifierWriteOnly = 1 << 1,
+        QualifierCoherent = 1 << 2,
+        QualifierVolatile = 1 << 3,
+        QualifierRestrict = 1 << 4,
+    };
+    Q_DECLARE_FLAGS(QualifierFlags, QualifierFlag)
+
+    // Optional data (like decorations) usually default to an otherwise invalid value (-1 or 0). This is intentional.
+
+    struct BlockVariable {
+        QByteArray name;
+        VariableType type = Unknown;
+        int offset = 0;
+        int size = 0;
+        QList<int> arrayDims;
+        int arrayStride = 0;
+        int matrixStride = 0;
+        bool matrixIsRowMajor = false;
+        QList<BlockVariable> structMembers;
+    };
+
+    struct InOutVariable {
+        QByteArray name;
+        VariableType type = Unknown;
+        int location = -1;
+        int binding = -1;
+        int descriptorSet = -1;
+        ImageFormat imageFormat = ImageFormatUnknown;
+        ImageFlags imageFlags;
+        QList<int> arrayDims;
+        bool perPatch = false;
+        QList<BlockVariable> structMembers;
+    };
+
+    struct UniformBlock {
+        QByteArray blockName;
+        QByteArray structName; // instanceName
+        int size = 0;
+        int binding = -1;
+        int descriptorSet = -1;
+        QList<BlockVariable> members;
+    };
+
+    struct PushConstantBlock {
+        QByteArray name;
+        int size = 0;
+        QList<BlockVariable> members;
+    };
+
+    struct StorageBlock {
+        QByteArray blockName;
+        QByteArray instanceName;
+        int knownSize = 0;
+        int binding = -1;
+        int descriptorSet = -1;
+        QList<BlockVariable> members;
+        int runtimeArrayStride = 0;
+        QualifierFlags qualifierFlags;
+    };
+
+    QList<InOutVariable> inputVariables() const;
+    QList<InOutVariable> outputVariables() const;
+    QList<UniformBlock> uniformBlocks() const;
+    QList<PushConstantBlock> pushConstantBlocks() const;
+    QList<StorageBlock> storageBlocks() const;
+    QList<InOutVariable> combinedImageSamplers() const;
+    QList<InOutVariable> separateImages() const;
+    QList<InOutVariable> separateSamplers() const;
+    QList<InOutVariable> storageImages() const;
+
+    enum BuiltinType {
+        // must match SpvBuiltIn
+        PositionBuiltin = 0,
+        PointSizeBuiltin = 1,
+        ClipDistanceBuiltin = 3,
+        CullDistanceBuiltin = 4,
+        VertexIdBuiltin = 5,
+        InstanceIdBuiltin = 6,
+        PrimitiveIdBuiltin = 7,
+        InvocationIdBuiltin = 8,
+        LayerBuiltin = 9,
+        ViewportIndexBuiltin = 10,
+        TessLevelOuterBuiltin = 11,
+        TessLevelInnerBuiltin = 12,
+        TessCoordBuiltin = 13,
+        PatchVerticesBuiltin = 14,
+        FragCoordBuiltin = 15,
+        PointCoordBuiltin = 16,
+        FrontFacingBuiltin = 17,
+        SampleIdBuiltin = 18,
+        SamplePositionBuiltin = 19,
+        SampleMaskBuiltin = 20,
+        FragDepthBuiltin = 22,
+        NumWorkGroupsBuiltin = 24,
+        WorkgroupSizeBuiltin = 25,
+        WorkgroupIdBuiltin = 26,
+        LocalInvocationIdBuiltin = 27,
+        GlobalInvocationIdBuiltin = 28,
+        LocalInvocationIndexBuiltin = 29,
+        VertexIndexBuiltin = 42,
+        InstanceIndexBuiltin = 43
+    };
+
+    struct BuiltinVariable {
+        BuiltinType type;
+        VariableType varType;
+        QList<int> arrayDims;
+    };
+
+    QList<BuiltinVariable> inputBuiltinVariables() const;
+    QList<BuiltinVariable> outputBuiltinVariables() const;
+
+    std::array<uint, 3> computeShaderLocalSize() const;
+
+    uint tessellationOutputVertexCount() const;
+
+    enum TessellationMode {
+        UnknownTessellationMode,
+        TrianglesTessellationMode,
+        QuadTessellationMode,
+        IsolineTessellationMode
+    };
+
+    TessellationMode tessellationMode() const;
+
+    enum TessellationWindingOrder {
+        UnknownTessellationWindingOrder,
+        CwTessellationWindingOrder,
+        CcwTessellationWindingOrder
+    };
+
+    TessellationWindingOrder tessellationWindingOrder() const;
+
+    enum TessellationPartitioning {
+        UnknownTessellationPartitioning,
+        EqualTessellationPartitioning,
+        FractionalEvenTessellationPartitioning,
+        FractionalOddTessellationPartitioning
+    };
+
+    TessellationPartitioning tessellationPartitioning() const;
+
+private:
+    QShaderDescriptionPrivate *d;
+    friend struct QShaderDescriptionPrivate;
+#ifndef QT_NO_DEBUG_STREAM
+    friend Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription &);
+#endif
+    friend Q_GUI_EXPORT bool operator==(const QShaderDescription &lhs, const QShaderDescription &rhs) noexcept;
+};
+
+Q_DECLARE_OPERATORS_FOR_FLAGS(QShaderDescription::ImageFlags)
+Q_DECLARE_OPERATORS_FOR_FLAGS(QShaderDescription::QualifierFlags)
+
+#ifndef QT_NO_DEBUG_STREAM
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription &);
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::InOutVariable &);
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::BlockVariable &);
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::UniformBlock &);
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::PushConstantBlock &);
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::StorageBlock &);
+Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::BuiltinVariable &);
+#endif
+
+Q_GUI_EXPORT bool operator==(const QShaderDescription &lhs, const QShaderDescription &rhs) noexcept;
+Q_GUI_EXPORT bool operator==(const QShaderDescription::InOutVariable &lhs, const QShaderDescription::InOutVariable &rhs) noexcept;
+Q_GUI_EXPORT bool operator==(const QShaderDescription::BlockVariable &lhs, const QShaderDescription::BlockVariable &rhs) noexcept;
+Q_GUI_EXPORT bool operator==(const QShaderDescription::UniformBlock &lhs, const QShaderDescription::UniformBlock &rhs) noexcept;
+Q_GUI_EXPORT bool operator==(const QShaderDescription::PushConstantBlock &lhs, const QShaderDescription::PushConstantBlock &rhs) noexcept;
+Q_GUI_EXPORT bool operator==(const QShaderDescription::StorageBlock &lhs, const QShaderDescription::StorageBlock &rhs) noexcept;
+Q_GUI_EXPORT bool operator==(const QShaderDescription::BuiltinVariable &lhs, const QShaderDescription::BuiltinVariable &rhs) noexcept;
+
+inline bool operator!=(const QShaderDescription &lhs, const QShaderDescription &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+inline bool operator!=(const QShaderDescription::InOutVariable &lhs, const QShaderDescription::InOutVariable &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+inline bool operator!=(const QShaderDescription::BlockVariable &lhs, const QShaderDescription::BlockVariable &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+inline bool operator!=(const QShaderDescription::UniformBlock &lhs, const QShaderDescription::UniformBlock &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+inline bool operator!=(const QShaderDescription::PushConstantBlock &lhs, const QShaderDescription::PushConstantBlock &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+inline bool operator!=(const QShaderDescription::StorageBlock &lhs, const QShaderDescription::StorageBlock &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+inline bool operator!=(const QShaderDescription::BuiltinVariable &lhs, const QShaderDescription::BuiltinVariable &rhs) noexcept
+{
+    return !(lhs == rhs);
+}
+
+QT_END_NAMESPACE
+
+#endif
diff --git a/src/gui/rhi/qshaderdescription_p.h b/src/gui/rhi/qshaderdescription_p.h
index 990cb12003..df694bbf40 100644
--- a/src/gui/rhi/qshaderdescription_p.h
+++ b/src/gui/rhi/qshaderdescription_p.h
@@ -1,8 +1,8 @@
-// Copyright (C) 2021 The Qt Company Ltd.
+// 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
 
-#ifndef QSHADERDESCRIPTION_H
-#define QSHADERDESCRIPTION_H
+#ifndef QSHADERDESCRIPTION_P_H
+#define QSHADERDESCRIPTION_P_H
 
 //
 //  W A R N I N G
@@ -15,376 +15,67 @@
 // We mean it.
 //
 
-#include <QtGui/qtguiglobal.h>
-#include <QtCore/QString>
+#include <rhi/qshaderdescription.h>
 #include <QtCore/QList>
-#include <QtCore/private/qglobal_p.h>
-#include <array>
+#include <QtCore/QAtomicInt>
+#include <QtCore/QJsonDocument>
 
 QT_BEGIN_NAMESPACE
 
-struct QShaderDescriptionPrivate;
-class QDataStream;
-
-class Q_GUI_EXPORT QShaderDescription
+struct Q_GUI_EXPORT QShaderDescriptionPrivate
 {
-public:
-    QShaderDescription();
-    QShaderDescription(const QShaderDescription &other);
-    QShaderDescription &operator=(const QShaderDescription &other);
-    ~QShaderDescription();
-    void detach();
-
-    bool isValid() const;
-
-    void serialize(QDataStream *stream, int version) const;
-    QByteArray toJson() const;
-
-    static QShaderDescription deserialize(QDataStream *stream, int version);
-
-    enum VariableType {
-        Unknown = 0,
-
-        // do not reorder
-        Float,
-        Vec2,
-        Vec3,
-        Vec4,
-        Mat2,
-        Mat2x3,
-        Mat2x4,
-        Mat3,
-        Mat3x2,
-        Mat3x4,
-        Mat4,
-        Mat4x2,
-        Mat4x3,
-
-        Int,
-        Int2,
-        Int3,
-        Int4,
-
-        Uint,
-        Uint2,
-        Uint3,
-        Uint4,
-
-        Bool,
-        Bool2,
-        Bool3,
-        Bool4,
-
-        Double,
-        Double2,
-        Double3,
-        Double4,
-        DMat2,
-        DMat2x3,
-        DMat2x4,
-        DMat3,
-        DMat3x2,
-        DMat3x4,
-        DMat4,
-        DMat4x2,
-        DMat4x3,
-
-        Sampler1D,
-        Sampler2D,
-        Sampler2DMS,
-        Sampler3D,
-        SamplerCube,
-        Sampler1DArray,
-        Sampler2DArray,
-        Sampler2DMSArray,
-        Sampler3DArray,
-        SamplerCubeArray,
-        SamplerRect,
-        SamplerBuffer,
-        SamplerExternalOES,
-        Sampler,
-
-        Image1D,
-        Image2D,
-        Image2DMS,
-        Image3D,
-        ImageCube,
-        Image1DArray,
-        Image2DArray,
-        Image2DMSArray,
-        Image3DArray,
-        ImageCubeArray,
-        ImageRect,
-        ImageBuffer,
-
-        Struct,
-
-        Half,
-        Half2,
-        Half3,
-        Half4
-    };
-
-    enum ImageFormat {
-        // must match SPIR-V's ImageFormat
-        ImageFormatUnknown = 0,
-        ImageFormatRgba32f = 1,
-        ImageFormatRgba16f = 2,
-        ImageFormatR32f = 3,
-        ImageFormatRgba8 = 4,
-        ImageFormatRgba8Snorm = 5,
-        ImageFormatRg32f = 6,
-        ImageFormatRg16f = 7,
-        ImageFormatR11fG11fB10f = 8,
-        ImageFormatR16f = 9,
-        ImageFormatRgba16 = 10,
-        ImageFormatRgb10A2 = 11,
-        ImageFormatRg16 = 12,
-        ImageFormatRg8 = 13,
-        ImageFormatR16 = 14,
-        ImageFormatR8 = 15,
-        ImageFormatRgba16Snorm = 16,
-        ImageFormatRg16Snorm = 17,
-        ImageFormatRg8Snorm = 18,
-        ImageFormatR16Snorm = 19,
-        ImageFormatR8Snorm = 20,
-        ImageFormatRgba32i = 21,
-        ImageFormatRgba16i = 22,
-        ImageFormatRgba8i = 23,
-        ImageFormatR32i = 24,
-        ImageFormatRg32i = 25,
-        ImageFormatRg16i = 26,
-        ImageFormatRg8i = 27,
-        ImageFormatR16i = 28,
-        ImageFormatR8i = 29,
-        ImageFormatRgba32ui = 30,
-        ImageFormatRgba16ui = 31,
-        ImageFormatRgba8ui = 32,
-        ImageFormatR32ui = 33,
-        ImageFormatRgb10a2ui = 34,
-        ImageFormatRg32ui = 35,
-        ImageFormatRg16ui = 36,
-        ImageFormatRg8ui = 37,
-        ImageFormatR16ui = 38,
-        ImageFormatR8ui = 39
-    };
-
-    enum ImageFlag {
-        ReadOnlyImage = 1 << 0,
-        WriteOnlyImage = 1 << 1
-    };
-    Q_DECLARE_FLAGS(ImageFlags, ImageFlag)
-
-    enum QualifierFlag {
-        QualifierReadOnly = 1 << 0,
-        QualifierWriteOnly = 1 << 1,
-        QualifierCoherent = 1 << 2,
-        QualifierVolatile = 1 << 3,
-        QualifierRestrict = 1 << 4,
-    };
-    Q_DECLARE_FLAGS(QualifierFlags, QualifierFlag)
-
-    // Optional data (like decorations) usually default to an otherwise invalid value (-1 or 0). This is intentional.
-
-    struct BlockVariable
+    QShaderDescriptionPrivate()
+        : ref(1)
     {
-        QByteArray name;
-        VariableType type = Unknown;
-        int offset = 0;
-        int size = 0;
-        QList<int> arrayDims;
-        int arrayStride = 0;
-        int matrixStride = 0;
-        bool matrixIsRowMajor = false;
-        QList<BlockVariable> structMembers;
-    };
-
-    struct InOutVariable {
-        QByteArray name;
-        VariableType type = Unknown;
-        int location = -1;
-        int binding = -1;
-        int descriptorSet = -1;
-        ImageFormat imageFormat = ImageFormatUnknown;
-        ImageFlags imageFlags;
-        QList<int> arrayDims;
-        bool perPatch = false;
-        QList<BlockVariable> structMembers;
-    };
-
-    struct UniformBlock {
-        QByteArray blockName;
-        QByteArray structName; // instanceName
-        int size = 0;
-        int binding = -1;
-        int descriptorSet = -1;
-        QList<BlockVariable> members;
-    };
-
-    struct PushConstantBlock {
-        QByteArray name;
-        int size = 0;
-        QList<BlockVariable> members;
-    };
-
-    struct StorageBlock {
-        QByteArray blockName;
-        QByteArray instanceName;
-        int knownSize = 0;
-        int binding = -1;
-        int descriptorSet = -1;
-        QList<BlockVariable> members;
-        int runtimeArrayStride = 0;
-        QualifierFlags qualifierFlags;
-    };
-
-    QList<InOutVariable> inputVariables() const;
-    QList<InOutVariable> outputVariables() const;
-    QList<UniformBlock> uniformBlocks() const;
-    QList<PushConstantBlock> pushConstantBlocks() const;
-    QList<StorageBlock> storageBlocks() const;
-    QList<InOutVariable> combinedImageSamplers() const;
-    QList<InOutVariable> separateImages() const;
-    QList<InOutVariable> separateSamplers() const;
-    QList<InOutVariable> storageImages() const;
-
-    enum BuiltinType {
-        // must match SpvBuiltIn
-        PositionBuiltin = 0,
-        PointSizeBuiltin = 1,
-        ClipDistanceBuiltin = 3,
-        CullDistanceBuiltin = 4,
-        VertexIdBuiltin = 5,
-        InstanceIdBuiltin = 6,
-        PrimitiveIdBuiltin = 7,
-        InvocationIdBuiltin = 8,
-        LayerBuiltin = 9,
-        ViewportIndexBuiltin = 10,
-        TessLevelOuterBuiltin = 11,
-        TessLevelInnerBuiltin = 12,
-        TessCoordBuiltin = 13,
-        PatchVerticesBuiltin = 14,
-        FragCoordBuiltin = 15,
-        PointCoordBuiltin = 16,
-        FrontFacingBuiltin = 17,
-        SampleIdBuiltin = 18,
-        SamplePositionBuiltin = 19,
-        SampleMaskBuiltin = 20,
-        FragDepthBuiltin = 22,
-        NumWorkGroupsBuiltin = 24,
-        WorkgroupSizeBuiltin = 25,
-        WorkgroupIdBuiltin = 26,
-        LocalInvocationIdBuiltin = 27,
-        GlobalInvocationIdBuiltin = 28,
-        LocalInvocationIndexBuiltin = 29,
-        VertexIndexBuiltin = 42,
-        InstanceIndexBuiltin = 43
-    };
-
-    struct BuiltinVariable {
-        BuiltinType type;
-        VariableType varType;
-        QList<int> arrayDims;
-    };
-
-    QList<BuiltinVariable> inputBuiltinVariables() const;
-    QList<BuiltinVariable> outputBuiltinVariables() const;
-
-    std::array<uint, 3> computeShaderLocalSize() const;
-
-    uint tessellationOutputVertexCount() const;
-
-    enum TessellationMode {
-        UnknownTessellationMode,
-        TrianglesTessellationMode,
-        QuadTessellationMode,
-        IsolineTessellationMode
-    };
-
-    TessellationMode tessellationMode() const;
-
-    enum TessellationWindingOrder {
-        UnknownTessellationWindingOrder,
-        CwTessellationWindingOrder,
-        CcwTessellationWindingOrder
-    };
-
-    TessellationWindingOrder tessellationWindingOrder() const;
-
-    enum TessellationPartitioning {
-        UnknownTessellationPartitioning,
-        EqualTessellationPartitioning,
-        FractionalEvenTessellationPartitioning,
-        FractionalOddTessellationPartitioning
-    };
-
-    TessellationPartitioning tessellationPartitioning() const;
-
-private:
-    QShaderDescriptionPrivate *d;
-    friend struct QShaderDescriptionPrivate;
-#ifndef QT_NO_DEBUG_STREAM
-    friend Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription &);
-#endif
-    friend Q_GUI_EXPORT bool operator==(const QShaderDescription &lhs, const QShaderDescription &rhs) noexcept;
+    }
+
+    QShaderDescriptionPrivate(const QShaderDescriptionPrivate &other)
+        : ref(1),
+          inVars(other.inVars),
+          outVars(other.outVars),
+          uniformBlocks(other.uniformBlocks),
+          pushConstantBlocks(other.pushConstantBlocks),
+          storageBlocks(other.storageBlocks),
+          combinedImageSamplers(other.combinedImageSamplers),
+          separateImages(other.separateImages),
+          separateSamplers(other.separateSamplers),
+          storageImages(other.storageImages),
+          inBuiltins(other.inBuiltins),
+          outBuiltins(other.outBuiltins),
+          localSize(other.localSize),
+          tessOutVertCount(other.tessOutVertCount),
+          tessMode(other.tessMode),
+          tessWind(other.tessWind),
+          tessPart(other.tessPart)
+    {
+    }
+
+    static QShaderDescriptionPrivate *get(QShaderDescription *desc) { return desc->d; }
+    static const QShaderDescriptionPrivate *get(const QShaderDescription *desc) { return desc->d; }
+
+    QJsonDocument makeDoc();
+    void writeToStream(QDataStream *stream, int version);
+    void loadFromStream(QDataStream *stream, int version);
+
+    QAtomicInt ref;
+    QList<QShaderDescription::InOutVariable> inVars;
+    QList<QShaderDescription::InOutVariable> outVars;
+    QList<QShaderDescription::UniformBlock> uniformBlocks;
+    QList<QShaderDescription::PushConstantBlock> pushConstantBlocks;
+    QList<QShaderDescription::StorageBlock> storageBlocks;
+    QList<QShaderDescription::InOutVariable> combinedImageSamplers;
+    QList<QShaderDescription::InOutVariable> separateImages;
+    QList<QShaderDescription::InOutVariable> separateSamplers;
+    QList<QShaderDescription::InOutVariable> storageImages;
+    QList<QShaderDescription::BuiltinVariable> inBuiltins;
+    QList<QShaderDescription::BuiltinVariable> outBuiltins;
+    std::array<uint, 3> localSize = {};
+    uint tessOutVertCount = 0;
+    QShaderDescription::TessellationMode tessMode = QShaderDescription::UnknownTessellationMode;
+    QShaderDescription::TessellationWindingOrder tessWind = QShaderDescription::UnknownTessellationWindingOrder;
+    QShaderDescription::TessellationPartitioning tessPart = QShaderDescription::UnknownTessellationPartitioning;
 };
 
-Q_DECLARE_OPERATORS_FOR_FLAGS(QShaderDescription::ImageFlags)
-Q_DECLARE_OPERATORS_FOR_FLAGS(QShaderDescription::QualifierFlags)
-
-#ifndef QT_NO_DEBUG_STREAM
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription &);
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::InOutVariable &);
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::BlockVariable &);
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::UniformBlock &);
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::PushConstantBlock &);
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::StorageBlock &);
-Q_GUI_EXPORT QDebug operator<<(QDebug, const QShaderDescription::BuiltinVariable &);
-#endif
-
-Q_GUI_EXPORT bool operator==(const QShaderDescription &lhs, const QShaderDescription &rhs) noexcept;
-Q_GUI_EXPORT bool operator==(const QShaderDescription::InOutVariable &lhs, const QShaderDescription::InOutVariable &rhs) noexcept;
-Q_GUI_EXPORT bool operator==(const QShaderDescription::BlockVariable &lhs, const QShaderDescription::BlockVariable &rhs) noexcept;
-Q_GUI_EXPORT bool operator==(const QShaderDescription::UniformBlock &lhs, const QShaderDescription::UniformBlock &rhs) noexcept;
-Q_GUI_EXPORT bool operator==(const QShaderDescription::PushConstantBlock &lhs, const QShaderDescription::PushConstantBlock &rhs) noexcept;
-Q_GUI_EXPORT bool operator==(const QShaderDescription::StorageBlock &lhs, const QShaderDescription::StorageBlock &rhs) noexcept;
-Q_GUI_EXPORT bool operator==(const QShaderDescription::BuiltinVariable &lhs, const QShaderDescription::BuiltinVariable &rhs) noexcept;
-
-inline bool operator!=(const QShaderDescription &lhs, const QShaderDescription &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-inline bool operator!=(const QShaderDescription::InOutVariable &lhs, const QShaderDescription::InOutVariable &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-inline bool operator!=(const QShaderDescription::BlockVariable &lhs, const QShaderDescription::BlockVariable &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-inline bool operator!=(const QShaderDescription::UniformBlock &lhs, const QShaderDescription::UniformBlock &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-inline bool operator!=(const QShaderDescription::PushConstantBlock &lhs, const QShaderDescription::PushConstantBlock &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-inline bool operator!=(const QShaderDescription::StorageBlock &lhs, const QShaderDescription::StorageBlock &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
-inline bool operator!=(const QShaderDescription::BuiltinVariable &lhs, const QShaderDescription::BuiltinVariable &rhs) noexcept
-{
-    return !(lhs == rhs);
-}
-
 QT_END_NAMESPACE
 
 #endif
diff --git a/src/gui/rhi/qshaderdescription_p_p.h b/src/gui/rhi/qshaderdescription_p_p.h
deleted file mode 100644
index c22ddda8ad..0000000000
--- a/src/gui/rhi/qshaderdescription_p_p.h
+++ /dev/null
@@ -1,81 +0,0 @@
-// Copyright (C) 2019 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
-
-#ifndef QSHADERDESCRIPTION_P_H
-#define QSHADERDESCRIPTION_P_H
-
-//
-//  W A R N I N G
-//  -------------
-//
-// This file is not part of the Qt API.  It exists for the convenience
-// of a number of Qt sources files.  This header file may change from
-// version to version without notice, or even be removed.
-//
-// We mean it.
-//
-
-#include "qshaderdescription_p.h"
-#include <QtCore/QList>
-#include <QtCore/QAtomicInt>
-#include <QtCore/QJsonDocument>
-
-QT_BEGIN_NAMESPACE
-
-struct Q_GUI_EXPORT QShaderDescriptionPrivate
-{
-    QShaderDescriptionPrivate()
-        : ref(1)
-    {
-    }
-
-    QShaderDescriptionPrivate(const QShaderDescriptionPrivate &other)
-        : ref(1),
-          inVars(other.inVars),
-          outVars(other.outVars),
-          uniformBlocks(other.uniformBlocks),
-          pushConstantBlocks(other.pushConstantBlocks),
-          storageBlocks(other.storageBlocks),
-          combinedImageSamplers(other.combinedImageSamplers),
-          separateImages(other.separateImages),
-          separateSamplers(other.separateSamplers),
-          storageImages(other.storageImages),
-          inBuiltins(other.inBuiltins),
-          outBuiltins(other.outBuiltins),
-          localSize(other.localSize),
-          tessOutVertCount(other.tessOutVertCount),
-          tessMode(other.tessMode),
-          tessWind(other.tessWind),
-          tessPart(other.tessPart)
-    {
-    }
-
-    static QShaderDescriptionPrivate *get(QShaderDescription *desc) { return desc->d; }
-    static const QShaderDescriptionPrivate *get(const QShaderDescription *desc) { return desc->d; }
-
-    QJsonDocument makeDoc();
-    void writeToStream(QDataStream *stream, int version);
-    void loadFromStream(QDataStream *stream, int version);
-
-    QAtomicInt ref;
-    QList<QShaderDescription::InOutVariable> inVars;
-    QList<QShaderDescription::InOutVariable> outVars;
-    QList<QShaderDescription::UniformBlock> uniformBlocks;
-    QList<QShaderDescription::PushConstantBlock> pushConstantBlocks;
-    QList<QShaderDescription::StorageBlock> storageBlocks;
-    QList<QShaderDescription::InOutVariable> combinedImageSamplers;
-    QList<QShaderDescription::InOutVariable> separateImages;
-    QList<QShaderDescription::InOutVariable> separateSamplers;
-    QList<QShaderDescription::InOutVariable> storageImages;
-    QList<QShaderDescription::BuiltinVariable> inBuiltins;
-    QList<QShaderDescription::BuiltinVariable> outBuiltins;
-    std::array<uint, 3> localSize = {};
-    uint tessOutVertCount = 0;
-    QShaderDescription::TessellationMode tessMode = QShaderDescription::UnknownTessellationMode;
-    QShaderDescription::TessellationWindingOrder tessWind = QShaderDescription::UnknownTessellationWindingOrder;
-    QShaderDescription::TessellationPartitioning tessPart = QShaderDescription::UnknownTessellationPartitioning;
-};
-
-QT_END_NAMESPACE
-
-#endif
diff --git a/src/gui/vulkan/qvulkandefaultinstance.cpp b/src/gui/vulkan/qvulkandefaultinstance.cpp
index f2de61a9ba..b4f343cf17 100644
--- a/src/gui/vulkan/qvulkandefaultinstance.cpp
+++ b/src/gui/vulkan/qvulkandefaultinstance.cpp
@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
 
 #include "qvulkandefaultinstance_p.h"
-#include <private/qrhivulkan_p.h>
+#include <rhi/qrhi.h>
 #include <QLoggingCategory>
 
 QT_BEGIN_NAMESPACE
diff --git a/src/gui/vulkan/qvulkaninstance.cpp b/src/gui/vulkan/qvulkaninstance.cpp
index 946a183d89..fc157bdae1 100644
--- a/src/gui/vulkan/qvulkaninstance.cpp
+++ b/src/gui/vulkan/qvulkaninstance.cpp
@@ -12,6 +12,7 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QVulkanInstance
     \since 5.10
+    \ingroup painting-3D
     \inmodule QtGui
 
     \brief The QVulkanInstance class represents a native Vulkan instance, enabling
diff --git a/src/opengl/qopenglcompositor.cpp b/src/opengl/qopenglcompositor.cpp
index 3e1b2aebed..b260445fec 100644
--- a/src/opengl/qopenglcompositor.cpp
+++ b/src/opengl/qopenglcompositor.cpp
@@ -4,7 +4,7 @@
 #include <QtOpenGL/QOpenGLFramebufferObject>
 #include <QtGui/QOpenGLContext>
 #include <QtGui/QWindow>
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 #include <qpa/qplatformbackingstore.h>
 
 #include "qopenglcompositor_p.h"
diff --git a/src/opengl/qopenglcompositorbackingstore.cpp b/src/opengl/qopenglcompositorbackingstore.cpp
index a5cc391e48..8bc1ec75ff 100644
--- a/src/opengl/qopenglcompositorbackingstore.cpp
+++ b/src/opengl/qopenglcompositorbackingstore.cpp
@@ -6,7 +6,7 @@
 #include <QtGui/QPainter>
 #include <qpa/qplatformbackingstore.h>
 #include <private/qwindow_p.h>
-#include <private/qrhi_p.h>
+#include <rhi/qrhi.h>
 
 #include "qopenglcompositorbackingstore_p.h"
 #include "qopenglcompositor_p.h"
diff --git a/src/openglwidgets/qopenglwidget.cpp b/src/openglwidgets/qopenglwidget.cpp
index 25c4dcf902..dc231acf6b 100644
--- a/src/openglwidgets/qopenglwidget.cpp
+++ b/src/openglwidgets/qopenglwidget.cpp
@@ -23,8 +23,7 @@
 #include <QtWidgets/private/qwidget_p.h>
 #include <QtWidgets/private/qwidgetrepaintmanager_p.h>
 
-#include <QtGui/private/qrhi_p.h>
-#include <QtGui/private/qrhigles2_p.h>
+#include <rhi/qrhi.h>
 
 QT_BEGIN_NAMESPACE
 
diff --git a/src/tools/syncqt/main.cpp b/src/tools/syncqt/main.cpp
index 6486e0d6fe..3255c6ad9a 100644
--- a/src/tools/syncqt/main.cpp
+++ b/src/tools/syncqt/main.cpp
@@ -149,6 +149,8 @@ public:
 
     const std::string &qpaIncludeDir() const { return m_qpaIncludeDir; }
 
+    const std::string &rhiIncludeDir() const { return m_rhiIncludeDir; }
+
     const std::string &stagingDir() const { return m_stagingDir; }
 
     const std::string &versionScriptFile() const { return m_versionScriptFile; }
@@ -157,6 +159,8 @@ public:
 
     const std::regex &qpaHeadersRegex() const { return m_qpaHeadersRegex; }
 
+    const std::regex &rhiHeadersRegex() const { return m_rhiHeadersRegex; }
+
     const std::regex &privateHeadersRegex() const { return m_privateHeadersRegex; }
 
     const std::regex &publicNamespaceRegex() const { return m_publicNamespaceRegex; }
@@ -188,9 +192,9 @@ public:
     void printHelp() const
     {
         std::cout << "Usage: syncqt -sourceDir <dir> -binaryDir <dir> -module <module name>"
-                     " -includeDir <dir> -privateIncludeDir <dir> -qpaIncludeDir <dir>"
+                     " -includeDir <dir> -privateIncludeDir <dir> -qpaIncludeDir <dir> -rhiIncludeDir <dir>"
                      " -stagingDir <dir> <-headers <header list>|-all> [-debug]"
-                     " [-versionScript <path>] [-qpaHeadersFilter <regex>]"
+                     " [-versionScript <path>] [-qpaHeadersFilter <regex>] [-rhiHeadersFilter <regex>]"
                      " [-framework [-frameworkIncludeDir <dir>]]"
                      " [-knownModules <module1> <module2>... <moduleN>]"
                      " [-nonQt] [-internal] [-copy]\n"
@@ -212,6 +216,8 @@ public:
                      "                                  generated private header files.\n"
                      "  -qpaIncludeDir                  Module include directory for the \n"
                      "                                  generated QPA header files.\n"
+                     "  -rhiIncludeDir                  Module include directory for the \n"
+                     "                                  generated RHI header files.\n"
                      "  -stagingDir                     Temporary staging directory to collect\n"
                      "                                  artifacts that need to be installed.\n"
                      "  -knownModules                   list of known modules. syncqt uses the\n"
@@ -225,6 +231,8 @@ public:
                      "                                  from the list of 'headers'.\n"
                      "  -qpaHeadersFilter               Regex that filters qpa header files from.\n"
                      "                                  the list of 'headers'.\n"
+                     "  -rhiHeadersFilter               Regex that filters rhi header files from.\n"
+                     "                                  the list of 'headers'.\n"
                      "  -publicNamespaceFilter          Symbols that are in the specified\n"
                      "                                  namespace.\n"
                      "                                  are treated as public symbols.\n"
@@ -262,6 +270,7 @@ private:
     [[nodiscard]] bool parseArguments(int argc, char *argv[])
     {
         std::string qpaHeadersFilter;
+        std::string rhiHeadersFilter;
         std::string privateHeadersFilter;
         std::string publicNamespaceFilter;
         static std::unordered_map<std::string, CommandLineOption<std::string>> stringArgumentMap = {
@@ -270,9 +279,11 @@ private:
             { "-binaryDir", { &m_binaryDir } },
             { "-privateHeadersFilter", { &privateHeadersFilter, true } },
             { "-qpaHeadersFilter", { &qpaHeadersFilter, true } },
+            { "-rhiHeadersFilter", { &rhiHeadersFilter, true } },
             { "-includeDir", { &m_includeDir } },
             { "-privateIncludeDir", { &m_privateIncludeDir } },
             { "-qpaIncludeDir", { &m_qpaIncludeDir } },
+            { "-rhiIncludeDir", { &m_rhiIncludeDir } },
             { "-stagingDir", { &m_stagingDir, true } },
             { "-versionScript", { &m_versionScriptFile, true } },
             { "-frameworkIncludeDir", { &m_frameworkIncludeDir, true } },
@@ -386,6 +397,9 @@ private:
         if (!qpaHeadersFilter.empty())
             m_qpaHeadersRegex = std::regex(qpaHeadersFilter);
 
+        if (!rhiHeadersFilter.empty())
+            m_rhiHeadersRegex = std::regex(rhiHeadersFilter);
+
         if (!privateHeadersFilter.empty())
             m_privateHeadersRegex = std::regex(privateHeadersFilter);
 
@@ -418,9 +432,10 @@ private:
     // Convert all paths from command line to a generic one.
     void normilizePaths()
     {
-        static std::array<std::string *, 8> paths = {
+        static std::array<std::string *, 9> paths = {
             &m_sourceDir,     &m_binaryDir,  &m_includeDir,        &m_privateIncludeDir,
-            &m_qpaIncludeDir, &m_stagingDir, &m_versionScriptFile, &m_frameworkIncludeDir
+            &m_qpaIncludeDir, &m_rhiIncludeDir, &m_stagingDir,
+            &m_versionScriptFile, &m_frameworkIncludeDir
         };
         for (auto path : paths) {
             if (!path->empty())
@@ -434,6 +449,7 @@ private:
     std::string m_includeDir;
     std::string m_privateIncludeDir;
     std::string m_qpaIncludeDir;
+    std::string m_rhiIncludeDir;
     std::string m_stagingDir;
     std::string m_versionScriptFile;
     std::string m_frameworkIncludeDir;
@@ -451,6 +467,7 @@ private:
     bool m_showOnly = false;
     bool m_warningsAreErrors = false;
     std::regex m_qpaHeadersRegex;
+    std::regex m_rhiHeadersRegex;
     std::regex m_privateHeadersRegex;
     std::regex m_publicNamespaceRegex;
 
@@ -522,7 +539,7 @@ class SyncScanner
     size_t m_currentFileLineNumber = 0;
     bool m_currentFileInSourceDir = false;
 
-    enum FileType { PublicHeader = 0, PrivateHeader = 1, QpaHeader = 2, ExportHeader = 4 };
+    enum FileType { PublicHeader = 0, PrivateHeader = 1, QpaHeader = 2, ExportHeader = 4, RhiHeader = 8 };
     unsigned int m_currentFileType = PublicHeader;
 
     int m_criticalChecks = CriticalChecks;
@@ -725,6 +742,9 @@ public:
         if (isHeaderQpa(m_currentFilename))
             m_currentFileType = QpaHeader | PrivateHeader;
 
+        if (isHeaderRhi(m_currentFilename))
+            m_currentFileType = RhiHeader | PrivateHeader;
+
         if (std::regex_match(m_currentFilename, ExportsHeaderRegex))
             m_currentFileType |= ExportHeader;
     }
@@ -762,12 +782,14 @@ public:
 
         bool isPrivate = m_currentFileType & PrivateHeader;
         bool isQpa = m_currentFileType & QpaHeader;
+        bool isRhi = m_currentFileType & RhiHeader;
         bool isExport = m_currentFileType & ExportHeader;
         scannerDebug()
             << "processHeader:start: " << headerFile
             << " m_currentFilename: " << m_currentFilename
             << " isPrivate: " << isPrivate
             << " isQpa: " << isQpa
+            << " isRhi: " << isRhi
             << std::endl;
 
         // Chose the directory where to generate the header aliases or to copy header file if
@@ -775,6 +797,8 @@ public:
         std::string outputDir = m_commandLineArgs->includeDir();
         if (isQpa)
             outputDir = m_commandLineArgs->qpaIncludeDir();
+        else if (isRhi)
+            outputDir = m_commandLineArgs->rhiIncludeDir();
         else if (isPrivate)
             outputDir = m_commandLineArgs->privateIncludeDir();
 
@@ -826,7 +850,7 @@ public:
             unsigned int skipChecks = m_commandLineArgs->scanAllMode() ? AllChecks : NoChecks;
 
             // Collect checks that should skipped for the header file.
-            if (m_commandLineArgs->isNonQtModule() || is3rdParty || isQpa
+            if (m_commandLineArgs->isNonQtModule() || is3rdParty || isQpa || isRhi
                 || !m_currentFileInSourceDir || isGenerated) {
                 skipChecks = AllChecks;
             } else {
@@ -847,7 +871,7 @@ public:
 
             ParsingResult parsingResult;
             parsingResult.masterInclude = m_currentFileInSourceDir && !isExport && !is3rdParty
-                    && !isQpa && !isPrivate && !isGenerated;
+                    && !isQpa && !isRhi && !isPrivate && !isGenerated;
             if (!parseHeader(headerFile, parsingResult, skipChecks)) {
                 scannerDebug() << "parseHeader failed: " << headerFile << std::endl;
                 return false;
@@ -864,7 +888,7 @@ public:
             // Add the '#if QT_CONFIG(<feature>)' check for header files that supposed to be
             // included into the module master header only if corresponding feature is enabled.
             bool willBeInModuleMasterHeader = false;
-            if (!isQpa && !isPrivate) {
+            if (!isQpa && !isRhi && !isPrivate) {
                 if (m_currentFilename.find('_') == std::string::npos
                     && parsingResult.masterInclude) {
                     m_masterHeaderContents[m_currentFilename] = parsingResult.requireConfig;
@@ -1150,7 +1174,7 @@ public:
             ++linesProcessed;
 
             bool skipSymbols =
-                    (m_currentFileType & PrivateHeader) || (m_currentFileType & QpaHeader);
+                    (m_currentFileType & PrivateHeader) || (m_currentFileType & QpaHeader) || (m_currentFileType & RhiHeader);
 
             // Parse pragmas
             if (std::regex_match(buffer, MacroRegex)) {
@@ -1331,6 +1355,11 @@ public:
         return std::regex_match(headerFileName, m_commandLineArgs->qpaHeadersRegex());
     }
 
+    [[nodiscard]] bool isHeaderRhi(const std::string &headerFileName)
+    {
+        return std::regex_match(headerFileName, m_commandLineArgs->rhiHeadersRegex());
+    }
+
     [[nodiscard]] bool isHeaderPrivate(const std::string &headerFile)
     {
         return std::regex_match(headerFile, m_commandLineArgs->privateHeadersRegex());
diff --git a/sync.profile b/sync.profile
index bc85d0e3b2..661f14da05 100644
--- a/sync.profile
+++ b/sync.profile
@@ -73,6 +73,7 @@
 );
 
 @qpa_headers = ( qr/^qplatform/, qr/^qwindowsystem/ );
+@rhi_headers = ( "qrhi.h", "qrhi_platform.h", "qshader.h", "qshaderdescription.h");
 my @internal_zlib_headers = ( "crc32.h", "deflate.h", "gzguts.h", "inffast.h", "inffixed.h", "inflate.h", "inftrees.h", "trees.h", "zutil.h" );
 my @zlib_headers = ( "zconf.h", "zlib.h" );
 @ignore_headers = ( @internal_zlib_headers );
diff --git a/tests/auto/gui/rhi/qrhi/tst_qrhi.cpp b/tests/auto/gui/rhi/qrhi/tst_qrhi.cpp
index 53ad597713..6aeae2eb03 100644
--- a/tests/auto/gui/rhi/qrhi/tst_qrhi.cpp
+++ b/tests/auto/gui/rhi/qrhi/tst_qrhi.cpp
@@ -9,14 +9,11 @@
 #include <qrgbafloat.h>
 #include <qrgba64.h>
 
-#include <QtGui/private/qrhi_p.h>
-#include <QtGui/private/qrhi_p_p.h>
-#include <QtGui/private/qrhinull_p.h>
+#include <private/qrhi_p.h>
 
 #if QT_CONFIG(opengl)
 # include <QOpenGLContext>
 # include <QOpenGLFunctions>
-# include <QtGui/private/qrhigles2_p.h>
 # include <QtGui/private/qguiapplication_p.h>
 # include <qpa/qplatformintegration.h>
 # define TST_GL
@@ -25,19 +22,15 @@
 #if QT_CONFIG(vulkan)
 # include <QVulkanInstance>
 # include <QVulkanFunctions>
-# include <QtGui/private/qrhivulkan_p.h>
 # define TST_VK
 #endif
 
 #ifdef Q_OS_WIN
-#include <QtGui/private/qrhid3d11_p.h>
-#include <QtGui/private/qrhid3d12_p.h>
 # define TST_D3D11
 # define TST_D3D12
 #endif
 
 #if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
-# include <QtGui/private/qrhimetal_p.h>
 # define TST_MTL
 #endif
 
diff --git a/tests/auto/gui/rhi/qshader/tst_qshader.cpp b/tests/auto/gui/rhi/qshader/tst_qshader.cpp
index 425b5951d0..fed2e883e0 100644
--- a/tests/auto/gui/rhi/qshader/tst_qshader.cpp
+++ b/tests/auto/gui/rhi/qshader/tst_qshader.cpp
@@ -5,8 +5,8 @@
 #include <QFile>
 #include <QBuffer>
 
-#include <QtGui/private/qshaderdescription_p_p.h>
-#include <QtGui/private/qshader_p_p.h>
+#include <private/qshaderdescription_p.h>
+#include <private/qshader_p.h>
 
 class tst_QShader : public QObject
 {
diff --git a/tests/auto/widgets/widgets/qopenglwidget/tst_qopenglwidget.cpp b/tests/auto/widgets/widgets/qopenglwidget/tst_qopenglwidget.cpp
index 07cce4cdc3..d4d5d9d583 100644
--- a/tests/auto/widgets/widgets/qopenglwidget/tst_qopenglwidget.cpp
+++ b/tests/auto/widgets/widgets/qopenglwidget/tst_qopenglwidget.cpp
@@ -24,8 +24,7 @@
 #include <private/qguiapplication_p.h>
 #include <qpa/qplatformbackingstore.h>
 #include <qpa/qplatformintegration.h>
-#include <private/qrhi_p.h>
-#include <private/qrhigles2_p.h>
+#include <rhi/qrhi.h>
 
 class tst_QOpenGLWidget : public QObject
 {
diff --git a/tests/manual/rhi/hellominimalcrossgfxtriangle/hellowindow.cpp b/tests/manual/rhi/hellominimalcrossgfxtriangle/hellowindow.cpp
index 9cbcebb380..895d7f0007 100644
--- a/tests/manual/rhi/hellominimalcrossgfxtriangle/hellowindow.cpp
+++ b/tests/manual/rhi/hellominimalcrossgfxtriangle/hellowindow.cpp
@@ -3,7 +3,7 @@
 
 #include "hellowindow.h"
 #include <QFile>
-#include <QtGui/private/qshader_p.h>
+#include <rhi/qshader.h>
 
 static float vertexData[] = {
     // Y up (note clipSpaceCorrMatrix in m_proj), CCW
diff --git a/tests/manual/rhi/hellominimalcrossgfxtriangle/window.h b/tests/manual/rhi/hellominimalcrossgfxtriangle/window.h
index b3223e8042..5f0fc09941 100644
--- a/tests/manual/rhi/hellominimalcrossgfxtriangle/window.h
+++ b/tests/manual/rhi/hellominimalcrossgfxtriangle/window.h
@@ -5,22 +5,8 @@
 #define WINDOW_H
 
 #include <QWindow>
-
-#include <QtGui/private/qrhinull_p.h>
-#if QT_CONFIG(opengl)
-#include <QtGui/private/qrhigles2_p.h>
 #include <QOffscreenSurface>
-#endif
-#if QT_CONFIG(vulkan)
-#include <QtGui/private/qrhivulkan_p.h>
-#endif
-#ifdef Q_OS_WIN
-#include <QtGui/private/qrhid3d11_p.h>
-#include <QtGui/private/qrhid3d12_p.h>
-#endif
-#if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
-#include <QtGui/private/qrhimetal_p.h>
-#endif
+#include <rhi/qrhi.h>
 
 class Window : public QWindow
 {
diff --git a/tests/manual/rhi/multiwindow/multiwindow.cpp b/tests/manual/rhi/multiwindow/multiwindow.cpp
index f25a68c621..7ff6644e26 100644
--- a/tests/manual/rhi/multiwindow/multiwindow.cpp
+++ b/tests/manual/rhi/multiwindow/multiwindow.cpp
@@ -13,33 +13,17 @@
 #include <QWindow>
 #include <QPlatformSurfaceEvent>
 #include <QElapsedTimer>
-
-#include <QtGui/private/qshader_p.h>
 #include <QFile>
-
-#ifndef QT_NO_OPENGL
-#include <QtGui/private/qrhigles2_p.h>
-#include <QOffscreenSurface>
-#endif
-
-#if QT_CONFIG(vulkan)
 #include <QLoggingCategory>
-#include <QtGui/private/qrhivulkan_p.h>
-#endif
-
-#ifdef Q_OS_WIN
-#include <QtGui/private/qrhid3d11_p.h>
-#endif
-
-#if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
-#include <QtGui/private/qrhimetal_p.h>
-#endif
+#include <QOffscreenSurface>
+#include <rhi/qrhi.h>
 
 enum GraphicsApi
 {
     OpenGL,
     Vulkan,
     D3D11,
+    D3D12,
     Metal
 };
 
@@ -54,6 +38,8 @@ static QString graphicsApiName()
         return QLatin1String("Vulkan");
     case D3D11:
         return QLatin1String("Direct3D 11");
+    case D3D12:
+        return QLatin1String("Direct3D 12");
     case Metal:
         return QLatin1String("Metal");
     default:
@@ -98,6 +84,10 @@ void createRhi()
         QRhiD3D11InitParams params;
         params.enableDebugLayer = true;
         r.r = QRhi::create(QRhi::D3D11, &params);
+    } else if (graphicsApi == D3D12) {
+        QRhiD3D12InitParams params;
+        params.enableDebugLayer = true;
+        r.r = QRhi::create(QRhi::D3D12, &params);
     }
 #endif
 
@@ -281,6 +271,7 @@ Window::Window(const QString &title, const QColor &bgColor, int axis, bool noVSy
 #endif
         break;
     case D3D11:
+    case D3D12:
         setSurfaceType(Direct3DSurface);
         break;
     case Metal:
@@ -494,6 +485,8 @@ int main(int argc, char **argv)
     cmdLineParser.addOption(vkOption);
     QCommandLineOption d3dOption({ "d", "d3d11" }, QLatin1String("Direct3D 11"));
     cmdLineParser.addOption(d3dOption);
+    QCommandLineOption d3d12Option({ "D", "d3d12" }, QLatin1String("Direct3D 12"));
+    cmdLineParser.addOption(d3d12Option);
     QCommandLineOption mtlOption({ "m", "metal" }, QLatin1String("Metal"));
     cmdLineParser.addOption(mtlOption);
     cmdLineParser.process(app);
@@ -503,6 +496,8 @@ int main(int argc, char **argv)
         graphicsApi = Vulkan;
     if (cmdLineParser.isSet(d3dOption))
         graphicsApi = D3D11;
+    if (cmdLineParser.isSet(d3d12Option))
+        graphicsApi = D3D12;
     if (cmdLineParser.isSet(mtlOption))
         graphicsApi = Metal;
 
@@ -517,6 +512,7 @@ int main(int argc, char **argv)
     r.instance = new QVulkanInstance;
     if (graphicsApi == Vulkan) {
         r.instance->setLayers({ "VK_LAYER_KHRONOS_validation" });
+        r.instance->setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
         if (!r.instance->create()) {
             qWarning("Failed to create Vulkan instance, switching to OpenGL");
             graphicsApi = OpenGL;
diff --git a/tests/manual/rhi/multiwindow_threaded/multiwindow_threaded.cpp b/tests/manual/rhi/multiwindow_threaded/multiwindow_threaded.cpp
index d817c90c69..eff0b536d0 100644
--- a/tests/manual/rhi/multiwindow_threaded/multiwindow_threaded.cpp
+++ b/tests/manual/rhi/multiwindow_threaded/multiwindow_threaded.cpp
@@ -16,27 +16,10 @@
 #include <QEvent>
 #include <QCommandLineParser>
 #include <QElapsedTimer>
-
-#include <QtGui/private/qshader_p.h>
 #include <QFile>
-
-#ifndef QT_NO_OPENGL
-#include <QtGui/private/qrhigles2_p.h>
-#include <QOffscreenSurface>
-#endif
-
-#if QT_CONFIG(vulkan)
 #include <QLoggingCategory>
-#include <QtGui/private/qrhivulkan_p.h>
-#endif
-
-#ifdef Q_OS_WIN
-#include <QtGui/private/qrhid3d11_p.h>
-#endif
-
-#if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
-#include <QtGui/private/qrhimetal_p.h>
-#endif
+#include <QOffscreenSurface>
+#include <rhi/qrhi.h>
 
 #ifdef Q_OS_DARWIN
 #include <QtCore/private/qcore_mac_p.h>
@@ -66,6 +49,8 @@ static QString graphicsApiName()
         return QLatin1String("Vulkan");
     case D3D11:
         return QLatin1String("Direct3D 11");
+    case D3D12:
+        return QLatin1String("Direct3D 12");
     case Metal:
         return QLatin1String("Metal");
     default:
@@ -329,6 +314,10 @@ void Renderer::createRhi()
         QRhiD3D11InitParams params;
         params.enableDebugLayer = true;
         r = QRhi::create(QRhi::D3D11, &params, rhiFlags);
+    } else if (graphicsApi == D3D12) {
+        QRhiD3D12InitParams params;
+        params.enableDebugLayer = true;
+        r = QRhi::create(QRhi::D3D12, &params, rhiFlags);
     }
 #endif
 
@@ -681,6 +670,8 @@ int main(int argc, char **argv)
     cmdLineParser.addOption(vkOption);
     QCommandLineOption d3dOption({ "d", "d3d11" }, QLatin1String("Direct3D 11"));
     cmdLineParser.addOption(d3dOption);
+    QCommandLineOption d3d12Option({ "D", "d3d12" }, QLatin1String("Direct3D 12"));
+    cmdLineParser.addOption(d3d12Option);
     QCommandLineOption mtlOption({ "m", "metal" }, QLatin1String("Metal"));
     cmdLineParser.addOption(mtlOption);
     cmdLineParser.process(app);
@@ -690,6 +681,8 @@ int main(int argc, char **argv)
         graphicsApi = Vulkan;
     if (cmdLineParser.isSet(d3dOption))
         graphicsApi = D3D11;
+    if (cmdLineParser.isSet(d3d12Option))
+        graphicsApi = D3D12;
     if (cmdLineParser.isSet(mtlOption))
         graphicsApi = Metal;
 
diff --git a/tests/manual/rhi/multiwindow_threaded/window.cpp b/tests/manual/rhi/multiwindow_threaded/window.cpp
index ea098b7f37..7b5ecf1634 100644
--- a/tests/manual/rhi/multiwindow_threaded/window.cpp
+++ b/tests/manual/rhi/multiwindow_threaded/window.cpp
@@ -4,10 +4,6 @@
 #include "window.h"
 #include <QPlatformSurfaceEvent>
 
-#ifndef QT_NO_OPENGL
-#include <QtGui/private/qrhigles2_p.h>
-#endif
-
 #if QT_CONFIG(vulkan)
 extern QVulkanInstance *instance;
 #endif
@@ -25,6 +21,7 @@ Window::Window(const QString &title, GraphicsApi api)
 #endif
         break;
     case D3D11:
+    case D3D12:
         setSurfaceType(Direct3DSurface);
         break;
     case Metal:
diff --git a/tests/manual/rhi/multiwindow_threaded/window.h b/tests/manual/rhi/multiwindow_threaded/window.h
index 3e0212f772..da1269283a 100644
--- a/tests/manual/rhi/multiwindow_threaded/window.h
+++ b/tests/manual/rhi/multiwindow_threaded/window.h
@@ -11,6 +11,7 @@ enum GraphicsApi
     OpenGL,
     Vulkan,
     D3D11,
+    D3D12,
     Metal
 };
 
diff --git a/tests/manual/rhi/offscreen/offscreen.cpp b/tests/manual/rhi/offscreen/offscreen.cpp
index 1334fe3fb6..04ce8543ac 100644
--- a/tests/manual/rhi/offscreen/offscreen.cpp
+++ b/tests/manual/rhi/offscreen/offscreen.cpp
@@ -7,28 +7,10 @@
 #include <QFile>
 #include <QLoggingCategory>
 #include <QCommandLineParser>
-#include <QtGui/private/qshader_p.h>
-
-#include <QtGui/private/qrhinull_p.h>
-
-#ifndef QT_NO_OPENGL
-#include <QtGui/private/qrhigles2_p.h>
-#include <QOffscreenSurface>
-#endif
-
-#if QT_CONFIG(vulkan)
 #include <QLoggingCategory>
-#include <QtGui/private/qrhivulkan_p.h>
-#endif
-
-#ifdef Q_OS_WIN
-#include <QtGui/private/qrhid3d11_p.h>
-#include <QtGui/private/qrhid3d12_p.h>
-#endif
+#include <QOffscreenSurface>
 
-#if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
-#include <QtGui/private/qrhimetal_p.h>
-#endif
+#include <rhi/qrhi.h>
 
 //#define TEST_FINISH
 
diff --git a/tests/manual/rhi/rhiwidget/examplewidget.h b/tests/manual/rhi/rhiwidget/examplewidget.h
index 1b58eedc20..b85ae6f1f7 100644
--- a/tests/manual/rhi/rhiwidget/examplewidget.h
+++ b/tests/manual/rhi/rhiwidget/examplewidget.h
@@ -5,7 +5,7 @@
 #define EXAMPLEWIDGET_H
 
 #include "rhiwidget.h"
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 
 class ExampleRhiWidget : public QRhiWidget
 {
diff --git a/tests/manual/rhi/rhiwidget/rhiwidget.h b/tests/manual/rhi/rhiwidget/rhiwidget.h
index 12ca7db413..94cc108e28 100644
--- a/tests/manual/rhi/rhiwidget/rhiwidget.h
+++ b/tests/manual/rhi/rhiwidget/rhiwidget.h
@@ -5,7 +5,7 @@
 #define RHIWIDGET_H
 
 #include <QWidget>
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 
 class QRhiWidgetPrivate;
 
diff --git a/tests/manual/rhi/shared/examplefw.h b/tests/manual/rhi/shared/examplefw.h
index 75f48aa0c7..2bab0a9e68 100644
--- a/tests/manual/rhi/shared/examplefw.h
+++ b/tests/manual/rhi/shared/examplefw.h
@@ -13,28 +13,9 @@
 #include <QTimer>
 #include <QLoggingCategory>
 #include <QColorSpace>
-
-#include <QtGui/private/qshader_p.h>
 #include <QFile>
-#include <QtGui/private/qrhinull_p.h>
-
-#ifndef QT_NO_OPENGL
-#include <QtGui/private/qrhigles2_p.h>
 #include <QOffscreenSurface>
-#endif
-
-#if QT_CONFIG(vulkan)
-#include <QtGui/private/qrhivulkan_p.h>
-#endif
-
-#ifdef Q_OS_WIN
-#include <QtGui/private/qrhid3d11_p.h>
-#include <QtGui/private/qrhid3d12_p.h>
-#endif
-
-#if defined(Q_OS_MACOS) || defined(Q_OS_IOS)
-#include <QtGui/private/qrhimetal_p.h>
-#endif
+#include <rhi/qrhi.h>
 
 #ifdef EXAMPLEFW_IMGUI
 #include "qrhiimgui_p.h"
diff --git a/tests/manual/rhi/shared/imgui/qrhiimgui_p.h b/tests/manual/rhi/shared/imgui/qrhiimgui_p.h
index 1b4b4d67b6..31782144bf 100644
--- a/tests/manual/rhi/shared/imgui/qrhiimgui_p.h
+++ b/tests/manual/rhi/shared/imgui/qrhiimgui_p.h
@@ -4,7 +4,7 @@
 #ifndef QRHIIMGUI_P_H
 #define QRHIIMGUI_P_H
 
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 
 QT_BEGIN_NAMESPACE
 
diff --git a/tests/manual/rhi/stereo/window.cpp b/tests/manual/rhi/stereo/window.cpp
index a3785badca..391e8b75fc 100644
--- a/tests/manual/rhi/stereo/window.cpp
+++ b/tests/manual/rhi/stereo/window.cpp
@@ -5,7 +5,7 @@
 #include <QPlatformSurfaceEvent>
 #include <QTimer>
 #include <QFile>
-#include <QtGui/private/qshader_p.h>
+#include <rhi/qshader.h>
 #include "../shared/cube.h"
 
 Window::Window()
diff --git a/tests/manual/rhi/stereo/window.h b/tests/manual/rhi/stereo/window.h
index 28e25dfdb4..ea35040a7a 100644
--- a/tests/manual/rhi/stereo/window.h
+++ b/tests/manual/rhi/stereo/window.h
@@ -5,8 +5,8 @@
 #define WINDOW_H
 
 #include <QWindow>
-#include <QtGui/private/qrhigles2_p.h>
 #include <QOffscreenSurface>
+#include <rhi/qrhi.h>
 
 class Window : public QWindow
 {
diff --git a/tests/manual/rhi/triquadcube/quadrenderer.cpp b/tests/manual/rhi/triquadcube/quadrenderer.cpp
index 4536412309..09c2047c35 100644
--- a/tests/manual/rhi/triquadcube/quadrenderer.cpp
+++ b/tests/manual/rhi/triquadcube/quadrenderer.cpp
@@ -3,7 +3,7 @@
 
 #include "quadrenderer.h"
 #include <QFile>
-#include <QtGui/private/qshader_p.h>
+#include <rhi/qshader.h>
 
 // Renders a quad using indexed drawing. No QRhiGraphicsPipeline is created, it
 // expects to reuse the one created by TriangleRenderer. A separate
diff --git a/tests/manual/rhi/triquadcube/quadrenderer.h b/tests/manual/rhi/triquadcube/quadrenderer.h
index a9f882fe54..f8757992ff 100644
--- a/tests/manual/rhi/triquadcube/quadrenderer.h
+++ b/tests/manual/rhi/triquadcube/quadrenderer.h
@@ -4,7 +4,7 @@
 #ifndef QUADRENDERER_H
 #define QUADRENDERER_H
 
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 
 class QuadRenderer
 {
diff --git a/tests/manual/rhi/triquadcube/texturedcuberenderer.cpp b/tests/manual/rhi/triquadcube/texturedcuberenderer.cpp
index 23b3c5c7c5..8e73194fc8 100644
--- a/tests/manual/rhi/triquadcube/texturedcuberenderer.cpp
+++ b/tests/manual/rhi/triquadcube/texturedcuberenderer.cpp
@@ -3,7 +3,7 @@
 
 #include "texturedcuberenderer.h"
 #include <QFile>
-#include <QtGui/private/qshader_p.h>
+#include <rhi/qshader.h>
 
 #include "../shared/cube.h"
 
diff --git a/tests/manual/rhi/triquadcube/texturedcuberenderer.h b/tests/manual/rhi/triquadcube/texturedcuberenderer.h
index 59517b2fef..0972ad6d46 100644
--- a/tests/manual/rhi/triquadcube/texturedcuberenderer.h
+++ b/tests/manual/rhi/triquadcube/texturedcuberenderer.h
@@ -4,7 +4,7 @@
 #ifndef TEXTUREDCUBERENDERER_H
 #define TEXTUREDCUBERENDERER_H
 
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 
 class TexturedCubeRenderer
 {
diff --git a/tests/manual/rhi/triquadcube/triangleoncuberenderer.cpp b/tests/manual/rhi/triquadcube/triangleoncuberenderer.cpp
index b66d869642..683134589e 100644
--- a/tests/manual/rhi/triquadcube/triangleoncuberenderer.cpp
+++ b/tests/manual/rhi/triquadcube/triangleoncuberenderer.cpp
@@ -3,7 +3,7 @@
 
 #include "triangleoncuberenderer.h"
 #include <QFile>
-#include <QtGui/private/qshader_p.h>
+#include <rhi/qshader.h>
 
 // toggle to test the preserved content (no clear) path
 const bool IMAGE_UNDER_OFFSCREEN_RENDERING = false;
diff --git a/tests/manual/rhi/triquadcube/trianglerenderer.cpp b/tests/manual/rhi/triquadcube/trianglerenderer.cpp
index 160a94ef46..46f6e0dec4 100644
--- a/tests/manual/rhi/triquadcube/trianglerenderer.cpp
+++ b/tests/manual/rhi/triquadcube/trianglerenderer.cpp
@@ -3,7 +3,7 @@
 
 #include "trianglerenderer.h"
 #include <QFile>
-#include <QtGui/private/qshader_p.h>
+#include <rhi/qshader.h>
 
 //#define VBUF_IS_DYNAMIC
 
diff --git a/tests/manual/rhi/triquadcube/trianglerenderer.h b/tests/manual/rhi/triquadcube/trianglerenderer.h
index ec591eb284..e6e3d0c0a9 100644
--- a/tests/manual/rhi/triquadcube/trianglerenderer.h
+++ b/tests/manual/rhi/triquadcube/trianglerenderer.h
@@ -4,7 +4,7 @@
 #ifndef TRIANGLERENDERER_H
 #define TRIANGLERENDERER_H
 
-#include <QtGui/private/qrhi_p.h>
+#include <rhi/qrhi.h>
 
 class TriangleRenderer
 {
diff --git a/tests/manual/wasm/qstdweb/qwasmcompositor_main.cpp b/tests/manual/wasm/qstdweb/qwasmcompositor_main.cpp
index ef19e0503f..6866fe229f 100644
--- a/tests/manual/wasm/qstdweb/qwasmcompositor_main.cpp
+++ b/tests/manual/wasm/qstdweb/qwasmcompositor_main.cpp
@@ -7,7 +7,7 @@
 #include <QtGui/qguiapplication.h>
 #include <QtGui/qoffscreensurface.h>
 #include <QtGui/qpa/qwindowsysteminterface.h>
-#include <QtGui/private/qrhigles2_p.h>
+#include <QtGui/rhi/qrhi.h>
 
 #include <qtwasmtestlib.h>