Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qsgrendererinterface.cpp
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qsgrendererinterface.h"
5
6QT_BEGIN_NAMESPACE
7
8/*!
9 \class QSGRendererInterface
10 \brief An interface providing access to some of the graphics API specific internals
11 of the scenegraph.
12 \inmodule QtQuick
13 \since 5.8
14
15 Renderer interfaces allow accessing graphics API specific functionality in
16 the scenegraph. Such internals are not typically exposed. However, when
17 integrating custom rendering via QSGRenderNode for example, it may become
18 necessary to query certain values, for instance the graphics device (e.g.
19 the Direct3D or Vulkan device) that is used by the scenegraph.
20
21 QSGRendererInterface's functions have varying availability. API and
22 language queries, such as, graphicsApi() or shaderType() are always
23 available, meaning it is sufficient to construct a QQuickWindow or
24 QQuickView, and the graphics API or shading language in use can be queried
25 right after via QQuickWindow::rendererInterface(). This guarantees that
26 utilities like the GraphicsInfo QML type are able to report the correct
27 values as early as possible, without having conditional property values -
28 depending on for instance shaderType() - evaluate to unexpected values.
29
30 Engine-specific accessors, like getResource(), are however available only
31 after the scenegraph is initialized. Additionally, there may be
32 backend-specific limitations on when such functions can be called. The only
33 way that is guaranteed to succeed is calling them when the rendering of a
34 node (i.e. the preparation of the command list for the next frame) is
35 active. In practice this typically means QSGRenderNode::render().
36 */
37
38/*!
39 \enum QSGRendererInterface::GraphicsApi
40 \value Unknown An unknown graphics API is in use
41 \value Software The Qt Quick 2D Renderer is in use
42 \value OpenVG OpenVG via EGL
43 \value [since 5.14] OpenGL OpenGL ES 2.0 or higher via a graphics abstraction layer.
44 \value [since 5.14] Direct3D11 Direct3D 11 via a graphics abstraction layer.
45 \value [since 6.6] Direct3D12 Direct3D 12 via a graphics abstraction layer.
46 \value [since 5.14] Vulkan Vulkan 1.0 via a graphics abstraction layer.
47 \value [since 5.14] Metal Metal via a graphics abstraction layer.
48 \value [since 5.14] Null Null (no output) via a graphics abstraction layer.
49 \omitvalue OpenGLRhi
50 \omitvalue Direct3D11Rhi
51 \omitvalue VulkanRhi
52 \omitvalue MetalRhi
53 \omitvalue NullRhi
54 */
55
56/*!
57 \enum QSGRendererInterface::Resource
58
59 \value DeviceResource The resource is a pointer to the graphics device,
60 when applicable. For example, a \c{VkDevice *}, \c{MTLDevice *} or
61 \c{ID3D11Device *}. Note that with Vulkan the returned value is a pointer
62 to the VkDevice, not the handle itself. This is because Vulkan handles may
63 not be pointers, and may use a different size from the architecture's
64 pointer size so merely casting to/from \c{void *} is wrong.
65
66 \value CommandQueueResource The resource is a pointer to the graphics
67 command queue used by the scenegraph, when applicable. For example, a
68 \c{VkQueue *} or \c{MTLCommandQueue *}. Note that with Vulkan the returned
69 value is a pointer to the VkQueue, not the handle itself.
70
71 \value CommandListResource The resource is a pointer to the command list or
72 buffer used by the scenegraph, when applicable. For example, a
73 \c{VkCommandBuffer *} or \c{MTLCommandBuffer *}. This object has limited
74 validity, and is only valid while the scene graph is preparing the next
75 frame. Note that with Vulkan the returned value is a pointer to the
76 VkCommandBuffer, not the handle itself.
77
78 \value PainterResource The resource is a pointer to the active QPainter
79 used by the scenegraph, when running with the software backend.
80
81 \value [since 5.14] RhiResource The resource is a pointer to the QRhi instance used by
82 the scenegraph, when applicable.
83
84 \value [since 6.0] RhiSwapchainResource The resource is a pointer to a QRhiSwapchain
85 instance that is associated with the window. The value is null when the
86 window is used in combination with QQuickRenderControl.
87
88 \value [since 6.0] RhiRedirectCommandBuffer The resource is a pointer to a
89 QRhiCommandBuffer instance that is associated with the window and its
90 QQuickRenderControl. The value is null when the window is not associated
91 with a QQuickRenderControl.
92
93 \value [since 6.0] RhiRedirectRenderTarget The resource is a pointer to a
94 QRhiTextureRenderTarget instance that is associated with the window and its
95 QQuickRenderControl. The value is null when the window is not associated
96 with a QQuickRenderControl. Note that the value always reflects the main
97 texture render target and it does not depend on the Qt Quick scene, meaning
98 it does not take any additional texture-targeting render passes generated
99 by ShaderEffect or QQuickItem layers into account.
100
101 \value [since 5.14] PhysicalDeviceResource The resource is a pointer to the pysical
102 device object used by the scenegraph, when applicable. For example, a
103 \c{VkPhysicalDevice *}. Note that with Vulkan the returned value is a
104 pointer to the VkPhysicalDevice, not the handle itself.
105
106 \value [since 5.14] OpenGLContextResource The resource is a pointer to the
107 QOpenGLContext used by the scenegraph (on the render thread), when
108 applicable.
109
110 \value [since 5.14] DeviceContextResource The resource is a pointer to the device
111 context used by the scenegraph, when applicable. For example, a
112 \c{ID3D11DeviceContext *}.
113
114 \value [since 5.14] CommandEncoderResource The resource is a pointer to the currently
115 active render command encoder object used by the scenegraph, when
116 applicable. For example, a \c{MTLRenderCommandEncoder *}. This object has
117 limited validity, and is only valid while the scene graph is recording a
118 render pass for the next frame.
119
120 \value [since 5.14] VulkanInstanceResource The resource is a pointer to the
121 QVulkanInstance used by the scenegraph, when applicable.
122
123 \value [since 5.14] RenderPassResource The resource is a pointer to the main render pass
124 used by the scenegraph, describing the color and depth/stecil attachments
125 and how they are used. For example, a \c{VkRenderPass *}. Note that the
126 value always reflects the main render target (either the on-screen window
127 or the texture QQuickRenderControl redirects to) and it does not depend on
128 the Qt Quick scene, meaning it does not take any additional
129 texture-targeting render passes generated by ShaderEffect or QQuickItem
130 layers into account.
131
132 \value [since 6.4] RedirectPaintDevice The resource is a pointer to QPaintDevice instance
133 that is associated with the window and its QQuickRenderControl. The value is
134 null when the window is not associated with a QQuickRenderControl.
135
136 \value [since 6.6] GraphicsQueueFamilyIndexResource The resource is a pointer to the
137 graphics queue family index used by the scenegraph, when applicable. With
138 Vulkan, this is a pointer to a \c uint32_t index value.
139
140 \value [since 6.6] GraphicsQueueIndexResource The resource is a pointer to the graphics
141 queue index (uint32_t) used by the scenegraph, when applicable. With
142 Vulkan, this is a pointer to a \c uint32_t index value, which in practice
143 is the index of the VkQueue reported for \c CommandQueueResource.
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 [since 5.14] RhiShader Consumes QShader instances containing shader variants for
152 multiple target languages and intermediate formats.
153 */
154
155/*!
156 \enum QSGRendererInterface::ShaderCompilationType
157 \value RuntimeCompilation Runtime compilation of shader source code is supported
158 \value OfflineCompilation Pre-compiled bytecode supported
159 */
160
161/*!
162 \enum QSGRendererInterface::ShaderSourceType
163
164 \value ShaderSourceString Shader source can be provided as a string in
165 the corresponding properties of ShaderEffect
166
167 \value ShaderSourceFile Local or resource files containing shader source
168 code are supported
169
170 \value ShaderByteCode Local or resource files containing shader bytecode are
171 supported
172 */
173
174/*!
175 \enum QSGRendererInterface::RenderMode
176
177 \value RenderMode2D Normal 2D rendering
178 \value RenderMode2DNoDepthBuffer Normal 2D rendering with depth buffer disabled
179 \value RenderMode3D Scene is rendered as part of a 3D graph
180 */
181QSGRendererInterface::~QSGRendererInterface()
182{
183}
184
185/*!
186 \fn QSGRendererInterface::GraphicsApi QSGRendererInterface::graphicsApi() const
187
188 Returns the graphics API that is in use by the Qt Quick scenegraph.
189
190 \note This function can be called on any thread.
191 */
192
193/*!
194 Queries a graphics \a resource in \a window. Returns null when the resource in question is
195 not supported or not available.
196
197 When successful, the returned pointer is either a direct pointer to an
198 interface, or a pointer to an opaque handle that needs to be dereferenced
199 first (for example, \c{VkDevice dev = *static_cast<VkDevice
200 *>(result)}). The latter is necessary since such handles may have sizes
201 different from a pointer.
202
203 \note The ownership of the returned pointer is never transferred to the caller.
204
205 \note This function must only be called on the render thread.
206 */
207void *QSGRendererInterface::getResource(QQuickWindow *window, Resource resource) const
208{
209 Q_UNUSED(window);
210 Q_UNUSED(resource);
211 return nullptr;
212}
213
214/*!
215 Queries a graphics resource. \a resource is a backend-specific key. This
216 allows supporting any future resources that are not listed in the
217 Resource enum.
218
219 \note The ownership of the returned pointer is never transferred to the caller.
220
221 \note This function must only be called on the render thread.
222 */
223void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const
224{
225 Q_UNUSED(window);
226 Q_UNUSED(resource);
227 return nullptr;
228}
229
230/*!
231 \return true if \a api is based on a graphics abstraction layer (QRhi)
232 instead of directly calling the native graphics API.
233
234 \note This function can be called on any thread.
235
236 \since 5.14
237 */
238bool QSGRendererInterface::isApiRhiBased(GraphicsApi api)
239{
240 switch (api) {
241 case OpenGL:
242 case Direct3D11:
243 case Direct3D12:
244 case Vulkan:
245 case Metal:
246 case Null:
247 return true;
248 default:
249 return false;
250 }
251}
252
253/*!
254 \fn QSGRendererInterface::ShaderType QSGRendererInterface::shaderType() const
255
256 \return the shading language supported by the Qt Quick backend the
257 application is using.
258
259 \note This function can be called on any thread.
260
261 \sa QtQuick::GraphicsInfo
262 */
263
264/*!
265 \fn QSGRendererInterface::ShaderCompilationTypes QSGRendererInterface::shaderCompilationType() const
266
267 \return a bitmask of the shader compilation approaches supported by the Qt
268 Quick backend the application is using.
269
270 \note This function can be called on any thread.
271
272 \sa QtQuick::GraphicsInfo
273 */
274
275/*!
276 \fn QSGRendererInterface::ShaderSourceTypes QSGRendererInterface::shaderSourceType() const
277
278 \return a bitmask of the supported ways of providing shader sources in ShaderEffect items.
279
280 \note This function can be called on any thread.
281
282 \sa QtQuick::GraphicsInfo
283 */
284
285QT_END_NAMESPACE