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
qvulkanfunctions.cpp
Go to the documentation of this file.
1// Copyright (C) 2017 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 <private/qvulkanfunctions_p.h>
6
7QT_BEGIN_NAMESPACE
8
9/*!
10 \class QVulkanFunctions
11 \since 5.10
12 \ingroup painting-3D
13 \inmodule QtGui
14 \wrapper
15
16 \brief The QVulkanFunctions class provides cross-platform access to the
17 instance level core Vulkan 1.3 API.
18
19 Qt and Qt applications do not link to any Vulkan libraries by default.
20 Instead, all functions are resolved dynamically at run time. Each
21 QVulkanInstance provides a QVulkanFunctions object retrievable via
22 QVulkanInstance::functions(). This does not contain device level functions
23 in order to avoid the potential overhead of an internal dispatching.
24 Instead, functions that rely on a device, or a dispatchable child object of
25 a device, are exposed via QVulkanDeviceFunctions and
26 QVulkanInstance::deviceFunctions(). QVulkanFunctions and
27 QVulkanDeviceFunctions together provides access to the full core Vulkan
28 API, excluding any extensions.
29
30 \note QVulkanFunctions instances cannot be constructed directly.
31
32 The typical usage is the following:
33
34 \snippet code/src_gui_vulkan_qvulkanfunctions.cpp 0
35
36 \note Windowing system interface (WSI) specifics and extensions are
37 excluded. This class only covers core Vulkan commands, with the exception
38 of instance creation, destruction, and function resolving, since such
39 functionality is covered by QVulkanInstance itself.
40
41 To access additional functions, applications can use
42 QVulkanInstance::getInstanceProcAddr() and vkGetDeviceProcAddr().
43 Applications can also decide to link to a Vulkan library directly, as
44 platforms with an appropriate loader will typically export function symbols
45 for the core commands. See
46 \l{https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkGetInstanceProcAddr.html}{the
47 man page for vkGetInstanceProcAddr} for more information.
48
49 \note The member function prototypes for Vulkan 1.1, 1.2, and 1.3 commands
50 are \c ifdefed with the appropriate \c{VK_VERSION_1_x} that is defined by
51 the Vulkan headers. As such, these functions will only be callable by an
52 application when the system's (on which the application is built) Vulkan
53 header is new enough and it contains 1.1, 1.2, or 1.3 Vulkan API
54 definitions. When building Qt from source, this has an additional
55 consequence: the Vulkan headers on the build environment must also be 1.1,
56 1.2, and 1.3 compatible to get a Qt build that supports resolving
57 the 1.1, 1.2, and 1.3 API commands. If neither of these conditions is met,
58 applications will only be able to call the Vulkan 1.0 commands through
59 QVulkanFunctions and QVulkanDeviceFunctions.
60
61 \section1 Security Considerations
62
63 QVulkanFunctions is a thin dispatch layer that exposes the Vulkan API as-is.
64 The arguments are forwarded verbatim to the underlying Vulkan
65 implementation, which is a trusted, in-process platform dependency. Qt does
66 not inspect, validate, or sanitize the handles, structures, and pointers
67 passed in, and does not act on the results returned. Calling a member
68 function here is therefore equivalent to calling the corresponding Vulkan
69 command directly, and the valid usage rules in the
70 \l{https://www.khronos.org/registry/vulkan/}{Vulkan specification} apply
71 unchanged. Violating them leads to undefined behavior in the Vulkan
72 implementation, not to a graceful failure from Qt.
73
74 \warning All data passed through QVulkanFunctions is expected to be trusted
75 content. Application developers are advised to carefully consider the
76 potential implications before deriving any of it from user-provided content
77 that is not part of the application and is not under the developers'
78 control. See \l{QVulkanInstance#Security Considerations}{QVulkanInstance}
79 for more information.
80
81 \sa QVulkanInstance, QVulkanDeviceFunctions, QWindow::setVulkanInstance(), QWindow::setSurfaceType()
82*/
83
84/*!
85 \class QVulkanDeviceFunctions
86 \since 5.10
87 \ingroup painting-3D
88 \inmodule QtGui
89 \wrapper
90
91 \brief The QVulkanDeviceFunctions class provides cross-platform access to
92 the device level core Vulkan 1.3 API.
93
94 Qt and Qt applications do not link to any Vulkan libraries by default.
95 Instead, all functions are resolved dynamically at run time. Each
96 QVulkanInstance provides a QVulkanFunctions object retrievable via
97 QVulkanInstance::functions(). This does not contain device level functions
98 in order to avoid the potential overhead of an internal dispatching.
99 Instead, functions that rely on a device, or a dispatchable child object of
100 a device, are exposed via QVulkanDeviceFunctions and
101 QVulkanInstance::deviceFunctions(). QVulkanFunctions and
102 QVulkanDeviceFunctions together provides access to the full core Vulkan
103 API, excluding any extensions.
104
105 \note QVulkanDeviceFunctions instances cannot be constructed directly.
106
107 The typical usage is the following:
108
109 \snippet code/src_gui_vulkan_qvulkanfunctions.cpp 1
110
111 The QVulkanDeviceFunctions object specific to the provided VkDevice is
112 created when QVulkanInstance::deviceFunctions() is first called with the
113 device in question. The object is then cached internally.
114
115 To access additional functions, applications can use
116 QVulkanInstance::getInstanceProcAddr() and vkGetDeviceProcAddr().
117 Applications can also decide to link to a Vulkan library directly, as many
118 implementations export function symbols for the core commands. See
119 \l{https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkGetInstanceProcAddr.html}{the
120 man page for vkGetInstanceProcAddr} for more information.
121
122 \section1 Security Considerations
123
124 QVulkanDeviceFunctions is a thin dispatch layer that exposes the Vulkan API
125 as-is. The arguments are forwarded verbatim to the underlying Vulkan
126 implementation, which is a trusted, in-process platform dependency. Qt does
127 not inspect, validate, or sanitize the handles, structures, and pointers
128 passed in, and does not act on the results returned. This covers, among
129 others, all resource creation, memory mapping, and command buffer building
130 commands. Calling a member function here is therefore equivalent to calling
131 the corresponding Vulkan command directly, and the valid usage rules in the
132 \l{https://www.khronos.org/registry/vulkan/}{Vulkan specification} apply
133 unchanged. Violating them leads to undefined behavior in the Vulkan
134 implementation, not to a graceful failure from Qt.
135
136 \warning All data passed through QVulkanDeviceFunctions is expected to be
137 trusted content. Application developers are advised to carefully consider
138 the potential implications before deriving any of it from user-provided
139 content that is not part of the application and is not under the developers'
140 control. See \l{QVulkanInstance#Security Considerations}{QVulkanInstance}
141 for more information.
142
143 \sa QVulkanInstance, QVulkanFunctions, QWindow::setVulkanInstance(), QWindow::setSurfaceType()
144*/
145
146/*
147 Constructs a new QVulkanFunctions for \a inst.
148 \internal
149 */
150QVulkanFunctions::QVulkanFunctions(QVulkanInstance *inst)
151 : d_ptr(new QVulkanFunctionsPrivate(inst))
152{
153}
154
155/*
156 Destructor.
157 */
158QVulkanFunctions::~QVulkanFunctions()
159{
160}
161
162/*
163 Constructs a new QVulkanDeviceFunctions for \a inst and the given \a device.
164 \internal
165 */
166QVulkanDeviceFunctions::QVulkanDeviceFunctions(QVulkanInstance *inst, VkDevice device)
167 : d_ptr(new QVulkanDeviceFunctionsPrivate(inst, device))
168{
169}
170
171/*
172 Destructor.
173 */
174QVulkanDeviceFunctions::~QVulkanDeviceFunctions()
175{
176}
177
178QT_END_NAMESPACE