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