Remove D3D12 scenegraph backend

Task-number: QTBUG-79925
Change-Id: Id3f0a688f47efaf1653c85d23ef49618ed09c931
Reviewed-by: Paul Olav Tvete <paul.tvete@qt.io>

1 files changed, 5 insertions, 243 deletions

diff --git a/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc b/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc
index 88003b68d3..86292921a6 100644
--- a/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/adaptations.qdoc
@@ -34,11 +34,10 @@
 Originally, Qt Quick always relied on OpenGL (OpenGL ES 2.0 or OpenGL 2.0) to
 parse the scene graph and render the results to a render target
 
-From Qt 5.8 onwards, Qt Quick also supports rendering in software, with OpenVG,
-and with Direct3D 12. This is realized by having additional scene graph
-adaptations, either in form of plugins (d3d12, openvg) or built-in to the Qt
-Quick library (software). The default adaptation continues to rely directly on
-OpenGL.
+From Qt 5.8 onwards, Qt Quick also supports rendering in software, and with
+OpenVG.  This is realized by having additional scene graph adaptations, either
+in form of plugins (openvg) or built-in to the Qt Quick library
+(software). The default adaptation continues to rely directly on OpenGL.
 
 From Qt 5.14 onwards, the default adaptation gains the option of rendering via
 a graphics abstraction layer, the Qt Rendering Hardware Interface (RHI),
@@ -52,7 +51,7 @@ appropriate for the various graphics APIs.
 \target Switching Between the Adaptation Used by the Application
 \section1 Switch Between Adaptations in Your Application
 
-Unlike \c software or \c d3d12, the RHI-based renderer is not an additional
+Unlike \c software, the RHI-based renderer is not an additional
 adaptation, and is always built-in. As of Qt 5.14 it can be enabled by setting
 the environment variable \c{QSG_RHI} to a non-zero value before starting the
 application, or via \l QQuickWindow::setSceneGraphBackend() in combination with
@@ -75,8 +74,6 @@ The following backends are supported:
         different than the ones listed below.
     \li Software - Request with the \c{"software"} string or the QSGRendererInterface::Software
         enum value.
-    \li Direct3D 12 - Request with the \c{"d3d12"} string or the QSGRendererInterface::Direct3D12
-        enum value.
     \li OpenVG - Request with the \c{"openvg"} string or the QSGRendererInterface::OpenVG enum
         value.
 \endlist
@@ -111,12 +108,6 @@ The Software adaptation is an alternative renderer for \l{Qt Quick} 2 that uses
 engine to render the contents of the scene graph. For more details, see
 \l{qtquick-visualcanvas-adaptations-software.html}{Software Adaptation}.
 
-\section1 Direct3D 12 (experimental)
-
-The Direct3D 12 adaptation is an alternative renderer for \l{Qt Quick} 2 when running on Windows
-10, both for Win32 and UWP applications. For more details, see
-\l{qtquick-visualcanvas-adaptations-d3d12.html}{Direct3D 12 Adaptation}.
-
 \section1 OpenVG
 
 The OpenVG adaptation is an alternative renderer for \l{Qt Quick} 2 that renders the contents of
@@ -172,235 +163,6 @@ behavior, which is only present in the default OpenGL adaptation.
 
 
 /*!
-\title Qt Quick Direct3D 12 Adaptation
-\page qtquick-visualcanvas-adaptations-d3d12.html
-
-The Direct3D 12 adaptation for Windows 10, both in Win32 (\c windows platform plugin) and in UWP
-(\c winrt platform plugin), is shipped as a dynamically loaded plugin. This adaptation doesn't work
-on earlier Windows versions. Building this plugin is enabled automatically, whenever the necessary
-D3D and DXGI develpoment files are present. In practice, this currently means Visual Studio 2015
-and newer.
-
-The adaptation is available both in normal, OpenGL-enabled Qt builds, and also when Qt is
-configured with \c{-no-opengl}. However, it's never the default, meaning that the user or the
-application has to explicitly request it by setting the \c{QT_QUICK_BACKEND} environment variable
-to \c{d3d12} or by calling QQuickWindow::setSceneGraphBackend().
-
-\section2 Motivation
-
-This experimental adaptation is the first Qt Quick backend that focuses on a modern, lower-level
-graphics API in combination with a windowing system interface that's different from the traditional
-approaches used in combination with OpenGL.
-
-This adaptation also allows better integration with Windows, as Direct3D is the primary
-vendor-supported solution. Consequently, there are fewer problems anticipated with drivers,
-operations like window resizes, and special events like graphics device loss caused by device
-resets or graphics driver updates.
-
-Performance-wise, the general expectation is a somewhat lower CPU usage compared to OpenGL, due to
-lower driver overhead, and a higher GPU utilization with less idle time wastage. The backend
-doesn't heavily utilize threads yet, which means there are opportunities for further improvements
-in the future, for example to further optimize image loading.
-
-The D3D12 backend also introduces support for pre-compiled shaders. All the backend's own shaders
-(used by the built-in materials on which the Rectangle, Image, Text, and other QML types are built
-with) are compiled to D3D shader bytecode when you compile Qt. Applications using ShaderEffect
-items can choose to ship bytecode either in regular files, via the Qt resource system, or use
-High Level Shading Language for DirectX (HLSL) source strings. Unlike OpenGL, the compilation for
-HLSL is properly threaded, meaning shader compilation won't block the application and its user
-interface.
-
-\section2 Graphics Adapters
-
-The plugin does not necessarily require hardware acceleration. You can also use WARP, the Direct3D
-software rasterizer. By default, the first adapter providing hardware acceleration is chosen. To
-override this and use another graphics adapter or to force the use of the software rasterizer, set
-the \c{QT_D3D_ADAPTER_INDEX} environment variable to the index of the adapter. The adapters
-discovered are printed at startup when \c{QSG_INFO} or the \c{qt.scenegraph.general} logging
-category is enabled.
-
-\section2 Troubleshooting
-
-If you encounter issues, always set the \c{QSG_INFO} and \c{QT_D3D_DEBUG} environment variables
-to \c 1, to get debug and warning messages printed on the debug output. \c{QT_D3D_DEBUG} enables
-the Direct3D debug layer.
-
-\note The debug layer shouldn't be enabled in production use, since it can significantly impact
-performance (CPU load) due to increased API overhead.
-
-\section2 Render Loops
-
-By default, the D3D12 adaptation uses a single-threaded render loop similar to OpenGL's \c windows
-render loop. A threaded variant is also available, that you can request by setting the
-\c{QSG_RENDER_LOOP} environment variable to \c threaded. However, due to conceptual limitations in
-DXGI, the windowing system interface, the threaded loop is prone to deadlocks when multiple
-QQuickWindow or QQuickView instances are shown. Consequently, for the time being, the default is
-the single-threaded loop. This means that with the D3D12 backend, applications are expected to move
-their work from the main (GUI) thread out to worker threads, instead of expecting Qt to keep the
-GUI thread responsive and suitable for heavy, blocking operations.
-
-For more information see \l{qtquick-visualcanvas-scenegraph.html}{Qt Quick Scene Graph} for
-details on render loops and
-\l{https://docs.microsoft.com/en-us/windows/desktop/direct3darticles/dxgi-best-practices#multithreading-and-dxgi}{Multithreading and DXGI}
-regarding the issues with multithreading.
-
-\section2 Renderer
-
-The scene graph renderer in the D3D12 adaptation currently doesn't perform any batching. This is
-less of an issue, unlike OpenGL, because state changes don't present any problems in the first
-place. The simpler renderer logic can also lead to lower CPU overhead in some cases. The trade-offs
-between the various approaches are currently under research.
-
-\section2 Shader Effects
-
-The ShaderEffect QML type is fully functional with the D3D12 adaptation as well. However, the
-interpretation of the fragmentShader and vertexShader properties is different than with OpenGL.
-
-With D3D12, these strings can either be a URL for a local file, a file in the resource system,
-or an HLSL source string. Using a URL for a local file or a file in the resource system
-indicates that the file in question contains pre-compiled D3D shader bytecode generated by the
-\c fxc tool, or, alternatively, HLSL source code. The type of file is detected automatically.
-This means that the D3D12 backend supports all options from GraphicsInfo.shaderCompilationType
-and GraphicsInfo.shaderSourceType.
-
-Unlike OpenGL, whenever you open a file, there is a QFileSelector with the extra \c hlsl selector
-used. This provides easy creation of ShaderEffect items that are functional across both backends,
-for example by placing the GLSL source code into \c{shaders/effect.frag}, the HLSL source code or
-- preferably - pre-compiled bytecode into \c{shaders/+hlsl/effect.frag}, while simply writing
-\c{fragmentShader: "qrc:shaders/effect.frag"} in QML. For more details, see ShaderEffect.
-
-\section2 Multisample Render Targets
-
-The Direct3D 12 adaptation ignores the QSurfaceFormat set on the QQuickWindow or QQuickView, or
-set via QSurfaceFormat::setDefaultFormat(), with two exceptions: QSurfaceFormat::samples() and
-QSurfaceFormat::alphaBufferSize() are still taken into account. When the sample value is greater
-than 1, multisample offscreen render targets will be created with the specified sample count at
-the maximum supported quality level. The backend automatically performs resolving into the
-non-multisample swapchain buffers after each frame.
-
-\section2 Semi-transparent Windows
-
-When the alpha channel is enabled either via QQuickWindow::setDefaultAlphaBuffer() or by setting
-alphaBufferSize to a non-zero value in the window's QSurfaceFormat or in the global format managed
-by QSurfaceFormat::setDefaultFormat(), the D3D12 backend will create a swapchain for composition
-and go through DirectComposition. This is necessary, because the mandatory flip model swapchain
-wouldn't support transparency otherwise.
-
-Therefore, it's important not to unneccessarily request an alpha channel. When the alphaBufferSize
-is 0 or the default -1, all these extra steps can be avoided and the traditional window-based
-swapchain is sufficient.
-
-On WinRT, this isn't relevant because the backend there always uses a composition swapchain which
-is associated with the ISwapChainPanel that backs QWindow on that platform.
-
-\section2 Mipmaps
-
-Mipmap generation is supported and handled transparently to the applications via a built-in compute
-shader. However, at the moment, this feature is experimental and only supports power-of-two images.
-Textures of other size will work too, but this involves a QImage-based scaling on the CPU first.
-Therefore, avoid enabling mipmapping for Non-Power-Of-Two (NPOT) images whenever possible.
-
-\section2 Image Formats
-
-When creating textures via C++ scene graph APIs like QQuickWindow::createTextureFromImage(), 32-bit
-formats won't involve any conversion, they'll map directly to the corresponding \c{R8G8B8A8_UNORM}
-or \c{B8G8R8A8_UNORM} format. Everything else will trigger a QImage-based format conversion on the
-CPU first.
-
-\section2 Unsupported Features
-
-Particles and some other OpenGL-dependent utilities, like QQuickFramebufferObject, are currently
-not supported.
-
-Like with \l{qtquick-visualcanvas-adaptations-software.html}{Software adaptation}, text is always
-rendered using the native method. Distance field-based text rendering is currently not implemented.
-
-The shader sources in the \l {Qt Graphical Effects} module have not been ported to any format other
-than the OpenGL 2.0 compatible one, meaning that the QML types provided by that module are currently
-not functional with the D3D12 backend.
-
-Texture atlases are currently not in use.
-
-The renderer may lack support for certain minor features, such as drawing points and lines with a
-width other than 1.
-
-Custom Qt Quick items using custom scene graph nodes can be problematic because materials are
-inherently tied to the graphics API. Therefore, only items that use the utility rectangle and image
-nodes are functional across all adaptations.
-
-QQuickWidget and its underlying OpenGL-based compositing architecture is not supported. If you need
-to mix with QWidget-based user interfaces, use QWidget::createWindowContainer() to embed the native
-window of the QQuickWindow or QQuickView.
-
-Finally, rendering via QSGEngine and QSGAbstractRenderer is not feasible with the D3D12 adaptation
-at the moment.
-
-\section2 Related APIs
-
-To integrate custom Direct3D 12 rendering, use QSGRenderNode in combination with
-QSGRendererInterface. This approach doesn't rely on OpenGL contexts or API specifics like
-framebuffers, and allows exposing the graphics device and command buffer from the adaptation. It's
-not necessarily suitable for easy integration of all types of content, in particular true 3D, so
-it'll likely get complemented by an alternative to QQuickFramebufferObject in future releases.
-
-To perform runtime decisions based on the adaptation, use QSGRendererInterface from C++ and
-GraphicsInfo from QML. They can also be used to check the level of shader support: shading
-language, compilation approach, and so on.
-
-When creating custom items, use the new QSGRectangleNode and QSGImageNode classes. These replace
-the now deprecated QSGSimpleRectNode and QSGSimpleTextureNode. Unlike their predecessors, these new
-classes are interfaces, and implementations are created via the QQuickWindow::createRectangleNode()
-and QQuickWindow::createImageNode() factory functions.
-
-\section2 Advanced Configuration
-
-The D3D12 adaptation can keep multiple frames in flight, similar to modern game engines. This is
-somewhat different from the traditional "render - swap - wait for vsync" model and allows for
-better GPU utilization at the expense of higher resource use. This means that the renderer will
-be a number of frames ahead of what is displayed on the screen.
-
-For a discussion of flip model swap chains and the typical configuration parameters, refer to
-\l{https://software.intel.com/en-us/articles/sample-application-for-direct3d-12-flip-model-swap-chains}
-{Sample Application for Direct3D 12 Flip Model Swap Chains}.
-
-Vertical synchronization is always enabled, meaning Present() is invoked with an interval of 1.
-
-The configuration can be changed by setting the following environment variables:
-
-\table
-    \header
-        \li Environment variable
-        \li Description
-    \row
-        \li \c{QT_D3D_BUFFER_COUNT}
-        \li The number of swap chain buffers in range 2 - 4. The default value is 3.
-    \row
-        \li \c{QT_D3D_FRAME_COUNT}
-        \li The number of frames prepared without blocking in range 1 - 4. The default value is 2.
-            Present() starts blocking after queuing 3 frames (regardless of
-            \c{QT_D3D_BUFFER_COUNT}), unless the waitable object is in use. Every additional frame
-            increases GPU resource usage since geometry and constant buffer data needs to be
-            duplicated, and involves more bookkeeping on the CPU side.
-    \row
-        \li \c{QT_D3D_WAITABLE_SWAP_CHAIN_MAX_LATENCY}
-        \li The frame latency in range 1 - 16. The default value is 0 (disabled).
-            Changes the limit for Present() and triggers a wait for an available swap chain buffer
-            when beginning each frame. For a detailed discussion, see the article linked above.
-            \note Currently, this behavior is experimental.
-    \row
-        \li \c{QT_D3D_BLOCKING_PRESENT}
-        \li The time the CPU should wait, a non-zero value, for the GPU to finish its work after
-            each call to Present(). The default value is 0 (disabled). This behavior effectively
-            kills all parallelism but makes the behavior resemble the traditional
-            swap-blocks-for-vsync model, which can be useful in some special cases. However, this
-            behavior is not the same as setting the frame count to 1 because that still avoids
-            blocking after Present(), and may only block when starting to prepare the next frame
-            (or may not block at all depending on the time gap between the frames).
-\endtable
-
-*/
-
-/*!
 \title Qt Quick OpenVG Adaptation
 \page qtquick-visualcanvas-adaptations-openvg.html