1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtQuick module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qsgrendererinterface.h"
41
42QT_BEGIN_NAMESPACE
43
44/*!
45 \class QSGRendererInterface
46 \brief An interface providing access to some of the graphics API specific internals
47 of the scenegraph.
48 \inmodule QtQuick
49 \since 5.8
50
51 Renderer interfaces allow accessing graphics API specific functionality in
52 the scenegraph. Such internals are not typically exposed. However, when
53 integrating custom rendering via QSGRenderNode for example, it may become
54 necessary to query certain values, for instance the graphics device (e.g.
55 the Direct3D or Vulkan device) that is used by the scenegraph.
56
57 QSGRendererInterface's functions have varying availability. API and
58 language queries, such as, graphicsApi() or shaderType() are always
59 available, meaning it is sufficient to construct a QQuickWindow or
60 QQuickView, and the graphics API or shading language in use can be queried
61 right after via QQuickWindow::rendererInterface(). This guarantees that
62 utilities like the GraphicsInfo QML type are able to report the correct
63 values as early as possible, without having conditional property values -
64 depending on for instance shaderType() - evaluate to unexpected values.
65
66 Engine-specific accessors, like getResource(), are however available only
67 after the scenegraph is initialized. Additionally, there may be
68 backend-specific limitations on when such functions can be called. The only
69 way that is guaranteed to succeed is calling them when the rendering of a
70 node (i.e. the preparation of the command list for the next frame) is
71 active. In practice this typically means QSGRenderNode::render().
72 */
73
74/*!
75 \enum QSGRendererInterface::GraphicsApi
76 \value Unknown An unknown graphics API is in use
77 \value Software The Qt Quick 2D Renderer is in use
78 \value OpenGL OpenGL ES 2.0 or higher
79 \value Direct3D12 Direct3D 12
80 \value OpenVG OpenVG via EGL
81 \value OpenGLRhi OpenGL ES 2.0 or higher via a graphics abstraction layer
82 \value Direct3D11Rhi Direct3D 11 via a graphics abstraction layer
83 \value VulkanRhi Vulkan 1.0 via a graphics abstraction layer
84 \value MetalRhi Metal via a graphics abstraction layer
85 \value NullRhi Null (no output) via a graphics abstraction layer
86 */
87
88/*!
89 \enum QSGRendererInterface::Resource
90
91 \value DeviceResource The resource is a pointer to the graphics device,
92 when applicable. For example, a \c{VkDevice *}, \c{MTLDevice *} or
93 \c{ID3D11Device *}. Note that with Vulkan the returned value is a pointer
94 to the VkDevice, not the handle itself. This is because Vulkan handles may
95 not be pointers, and may use a different size from the architecture's
96 pointer size so merely casting to/from \c{void *} is wrong.
97
98 \value CommandQueueResource The resource is a pointer to the graphics
99 command queue used by the scenegraph, when applicable. For example, a
100 \c{VkQueue *} or \c{MTLCommandQueue *}. Note that with Vulkan the returned
101 value is a pointer to the VkQueue, not the handle itself.
102
103 \value CommandListResource The resource is a pointer to the command list or
104 buffer used by the scenegraph, when applicable. For example, a
105 \c{VkCommandBuffer *} or \c{MTLCommandBuffer *}. This object has limited
106 validity, and is only valid while the scene graph is preparing the next
107 frame. Note that with Vulkan the returned value is a pointer to the
108 VkCommandBuffer, not the handle itself.
109
110 \value PainterResource The resource is a pointer to the active QPainter
111 used by the scenegraph, when running with the software backend.
112
113 \value RhiResource The resource is a pointer to the QRhi instance used by
114 the scenegraph, when applicable.
115
116 \value PhysicalDeviceResource The resource is a pointer to the pysical
117 device object used by the scenegraph, when applicable. For example, a
118 \c{VkPhysicalDevice *}. Note that with Vulkan the returned value is a
119 pointer to the VkPhysicalDevice, not the handle itself.
120
121 \value OpenGLContextResource The resource is a pointer to the
122 QOpenGLContext used by the scenegraph (on the render thread), when
123 applicable.
124
125 \value DeviceContextResource The resource is a pointer to the device
126 context used by the scenegraph, when applicable. For example, a
127 \c{ID3D11DeviceContext *}.
128
129 \value CommandEncoderResource The resource is a pointer to the currently
130 active render command encoder object used by the scenegraph, when
131 applicable. For example, a \c{MTLRenderCommandEncoder *}. This object has
132 limited validity, and is only valid while the scene graph is recording a
133 render pass for the next frame.
134
135 \value VulkanInstanceResource The resource is a pointer to the
136 QVulkanInstance used by the scenegraph, when applicable.
137 */
138
139/*!
140 \enum QSGRendererInterface::ShaderType
141 \value UnknownShadingLanguage Not yet known due to no window and scenegraph associated
142 \value GLSL GLSL or GLSL ES
143 \value HLSL HLSL
144 \value RhiShader Consumes QShader instances containing shader
145 variants for multiple target languages and bytecode formats
146 */
147
148/*!
149 \enum QSGRendererInterface::ShaderCompilationType
150 \value RuntimeCompilation Runtime compilation of shader source code is supported
151 \value OfflineCompilation Pre-compiled bytecode supported
152 */
153
154/*!
155 \enum QSGRendererInterface::ShaderSourceType
156
157 \value ShaderSourceString Shader source can be provided as a string in
158 the corresponding properties of ShaderEffect
159
160 \value ShaderSourceFile Local or resource files containing shader source
161 code are supported
162
163 \value ShaderByteCode Local or resource files containing shader bytecode are
164 supported
165 */
166
167QSGRendererInterface::~QSGRendererInterface()
168{
169}
170
171/*!
172 \fn QSGRendererInterface::GraphicsApi QSGRendererInterface::graphicsApi() const
173
174 Returns the graphics API that is in use by the Qt Quick scenegraph.
175
176 \note This function can be called on any thread.
177 */
178
179/*!
180 Queries a graphics \a resource in \a window. Returns null when the resource in question is
181 not supported or not available.
182
183 When successful, the returned pointer is either a direct pointer to an
184 interface (and can be cast, for example, to \c{ID3D12Device *}) or a
185 pointer to an opaque handle that needs to be dereferenced first (for
186 example, \c{VkDevice dev = *static_cast<VkDevice *>(result)}). The latter
187 is necessary since such handles may have sizes different from a pointer.
188
189 \note The ownership of the returned pointer is never transferred to the caller.
190
191 \note This function must only be called on the render thread.
192 */
193void *QSGRendererInterface::getResource(QQuickWindow *window, Resource resource) const
194{
195 Q_UNUSED(window);
196 Q_UNUSED(resource);
197 return nullptr;
198}
199
200/*!
201 Queries a graphics resource. \a resource is a backend-specific key. This
202 allows supporting any future resources that are not listed in the
203 Resource enum.
204
205 \note The ownership of the returned pointer is never transferred to the caller.
206
207 \note This function must only be called on the render thread.
208 */
209void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const
210{
211 Q_UNUSED(window);
212 Q_UNUSED(resource);
213 return nullptr;
214}
215
216/*!
217 \return true if \a api is based on a graphics abstraction layer (QRhi)
218 instead of directly calling the native graphics API.
219
220 \note This function can be called on any thread.
221 */
222bool QSGRendererInterface::isApiRhiBased(GraphicsApi api)
223{
224 switch (api) {
225 case OpenGLRhi:
226 Q_FALLTHROUGH();
227 case Direct3D11Rhi:
228 Q_FALLTHROUGH();
229 case VulkanRhi:
230 Q_FALLTHROUGH();
231 case MetalRhi:
232 Q_FALLTHROUGH();
233 case NullRhi:
234 return true;
235 default:
236 return false;
237 }
238}
239
240/*!
241 \fn QSGRendererInterface::ShaderType QSGRendererInterface::shaderType() const
242
243 \return the shading language supported by the Qt Quick backend the
244 application is using.
245
246 \note This function can be called on any thread.
247
248 \sa QtQuick::GraphicsInfo
249 */
250
251/*!
252 \fn QSGRendererInterface::ShaderCompilationTypes QSGRendererInterface::shaderCompilationType() const
253
254 \return a bitmask of the shader compilation approaches supported by the Qt
255 Quick backend the application is using.
256
257 \note This function can be called on any thread.
258
259 \sa QtQuick::GraphicsInfo
260 */
261
262/*!
263 \fn QSGRendererInterface::ShaderSourceTypes QSGRendererInterface::shaderSourceType() const
264
265 \return a bitmask of the supported ways of providing shader sources in ShaderEffect items.
266
267 \note This function can be called on any thread.
268
269 \sa QtQuick::GraphicsInfo
270 */
271
272QT_END_NAMESPACE
273