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. This value was introduced in Qt 5.14.
82 \value Direct3D11Rhi Direct3D 11 via a graphics abstraction layer. This value was introduced in Qt 5.14.
83 \value VulkanRhi Vulkan 1.0 via a graphics abstraction layer. This value was introduced in Qt 5.14.
84 \value MetalRhi Metal via a graphics abstraction layer. This value was introduced in Qt 5.14.
85 \value NullRhi Null (no output) via a graphics abstraction layer. This value was introduced in Qt 5.14.
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. This value was introduced in Qt 5.14.
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. This value was
120 introduced in Qt 5.14.
121
122 \value OpenGLContextResource The resource is a pointer to the
123 QOpenGLContext used by the scenegraph (on the render thread), when
124 applicable. This value was introduced in Qt 5.14.
125
126 \value DeviceContextResource The resource is a pointer to the device
127 context used by the scenegraph, when applicable. For example, a
128 \c{ID3D11DeviceContext *}. This value was introduced in Qt 5.14.
129
130 \value CommandEncoderResource The resource is a pointer to the currently
131 active render command encoder object used by the scenegraph, when
132 applicable. For example, a \c{MTLRenderCommandEncoder *}. This object has
133 limited validity, and is only valid while the scene graph is recording a
134 render pass for the next frame. This value was introduced in Qt 5.14.
135
136 \value VulkanInstanceResource The resource is a pointer to the
137 QVulkanInstance used by the scenegraph, when applicable. This value was
138 introduced in Qt 5.14.
139
140 \value RenderPassResource The resource is a pointer to the render pass used
141 by the scenegraph, describing the color and depth/stecil attachments and
142 how they are used. For example, a \c{VkRenderPass *}. This value was
143 introduced in Qt 5.14.
144 */
145
146/*!
147 \enum QSGRendererInterface::ShaderType
148 \value UnknownShadingLanguage Not yet known due to no window and scenegraph associated
149 \value GLSL GLSL or GLSL ES
150 \value HLSL HLSL
151 \value RhiShader Consumes QShader instances containing shader variants for
152 multiple target languages and intermediate formats. This value was introduced in
153 Qt 5.14.
154 */
155
156/*!
157 \enum QSGRendererInterface::ShaderCompilationType
158 \value RuntimeCompilation Runtime compilation of shader source code is supported
159 \value OfflineCompilation Pre-compiled bytecode supported
160 */
161
162/*!
163 \enum QSGRendererInterface::ShaderSourceType
164
165 \value ShaderSourceString Shader source can be provided as a string in
166 the corresponding properties of ShaderEffect
167
168 \value ShaderSourceFile Local or resource files containing shader source
169 code are supported
170
171 \value ShaderByteCode Local or resource files containing shader bytecode are
172 supported
173 */
174
175QSGRendererInterface::~QSGRendererInterface()
176{
177}
178
179/*!
180 \fn QSGRendererInterface::GraphicsApi QSGRendererInterface::graphicsApi() const
181
182 Returns the graphics API that is in use by the Qt Quick scenegraph.
183
184 \note This function can be called on any thread.
185 */
186
187/*!
188 Queries a graphics \a resource in \a window. Returns null when the resource in question is
189 not supported or not available.
190
191 When successful, the returned pointer is either a direct pointer to an
192 interface (and can be cast, for example, to \c{ID3D12Device *}) or a
193 pointer to an opaque handle that needs to be dereferenced first (for
194 example, \c{VkDevice dev = *static_cast<VkDevice *>(result)}). The latter
195 is necessary since such handles may have sizes different from a pointer.
196
197 \note The ownership of the returned pointer is never transferred to the caller.
198
199 \note This function must only be called on the render thread.
200 */
201void *QSGRendererInterface::getResource(QQuickWindow *window, Resource resource) const
202{
203 Q_UNUSED(window);
204 Q_UNUSED(resource);
205 return nullptr;
206}
207
208/*!
209 Queries a graphics resource. \a resource is a backend-specific key. This
210 allows supporting any future resources that are not listed in the
211 Resource enum.
212
213 \note The ownership of the returned pointer is never transferred to the caller.
214
215 \note This function must only be called on the render thread.
216 */
217void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const
218{
219 Q_UNUSED(window);
220 Q_UNUSED(resource);
221 return nullptr;
222}
223
224/*!
225 \return true if \a api is based on a graphics abstraction layer (QRhi)
226 instead of directly calling the native graphics API.
227
228 \note This function can be called on any thread.
229
230 \since 5.14
231 */
232bool QSGRendererInterface::isApiRhiBased(GraphicsApi api)
233{
234 switch (api) {
235 case OpenGLRhi:
236 Q_FALLTHROUGH();
237 case Direct3D11Rhi:
238 Q_FALLTHROUGH();
239 case VulkanRhi:
240 Q_FALLTHROUGH();
241 case MetalRhi:
242 Q_FALLTHROUGH();
243 case NullRhi:
244 return true;
245 default:
246 return false;
247 }
248}
249
250/*!
251 \fn QSGRendererInterface::ShaderType QSGRendererInterface::shaderType() const
252
253 \return the shading language supported by the Qt Quick backend the
254 application is using.
255
256 \note This function can be called on any thread.
257
258 \sa QtQuick::GraphicsInfo
259 */
260
261/*!
262 \fn QSGRendererInterface::ShaderCompilationTypes QSGRendererInterface::shaderCompilationType() const
263
264 \return a bitmask of the shader compilation approaches supported by the Qt
265 Quick backend the application is using.
266
267 \note This function can be called on any thread.
268
269 \sa QtQuick::GraphicsInfo
270 */
271
272/*!
273 \fn QSGRendererInterface::ShaderSourceTypes QSGRendererInterface::shaderSourceType() const
274
275 \return a bitmask of the supported ways of providing shader sources in ShaderEffect items.
276
277 \note This function can be called on any thread.
278
279 \sa QtQuick::GraphicsInfo
280 */
281
282QT_END_NAMESPACE
283

source code of qtdeclarative/src/quick/scenegraph/coreapi/qsgrendererinterface.cpp