<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qvulkaninstance.cpp -->
<title>QVulkanInstance Class | Qt GUI 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtgui-index.html">Qt GUI</a></td><td ><a href="qtgui-module.html">C++ Classes</a></td><td >QVulkanInstance</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtgui-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#static-public-members">Static Public Members</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#initialization">Initialization</a></li>
<li class="level2"><a href="#configuration">Configuration</a></li>
<li class="level2"><a href="#adopting-an-existing-instance">Adopting an Existing Instance</a></li>
<li class="level2"><a href="#accessing-core-vulkan-commands">Accessing Core Vulkan Commands</a></li>
<li class="level2"><a href="#getting-a-native-vulkan-surface-for-a-window">Getting a Native Vulkan Surface for a Window</a></li>
<li class="level2"><a href="#troubleshooting">Troubleshooting</a></li>
<li class="level2"><a href="#example">Example</a></li>
<li class="level2"><a href="#using-c-bindings-for-vulkan">Using C++ Bindings for Vulkan</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QVulkanInstance Class</h1>
<!-- $$$QVulkanInstance-brief -->
<p>The <a href="qvulkaninstance.html">QVulkanInstance</a> class represents a native Vulkan instance, enabling Vulkan rendering onto a <a href="qsurface.html">QSurface</a>. <a href="#details">More...</a></p>
<!-- @@@QVulkanInstance -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QVulkanInstance></span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += gui</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 5.10</td></tr></table></div><ul>
<li><a href="qvulkaninstance-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h2 id="public-types">Public Types</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#Flag-enum">Flag</a></b> { NoDebugOutputRedirect }</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> flags </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#Flag-enum">Flags</a></b></td></tr>
</table></div>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#QVulkanInstance">QVulkanInstance</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#dtor.QVulkanInstance">~QVulkanInstance</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QVersionNumber </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#apiVersion">apiVersion</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#create">create</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#destroy">destroy</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QVulkanDeviceFunctions *</td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#deviceFunctions">deviceFunctions</a></b>(int <i>device</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> int </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#errorCode">errorCode</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QByteArrayList </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#extensions">extensions</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QVulkanInstance::Flags </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#flags">flags</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QVulkanFunctions *</td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#functions">functions</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> PFN_vkVoidFunction </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#getInstanceProcAddr">getInstanceProcAddr</a></b>(const char *<i>name</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#isValid">isValid</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QByteArrayList </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#layers">layers</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#presentQueued">presentQueued</a></b>(QWindow *<i>window</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#resetDeviceFunctions">resetDeviceFunctions</a></b>(int <i>device</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#setApiVersion">setApiVersion</a></b>(const QVersionNumber &<i>vulkanVersion</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#setExtensions">setExtensions</a></b>(const QByteArrayList &<i>extensions</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#setFlags">setFlags</a></b>(QVulkanInstance::Flags <i>flags</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#setLayers">setLayers</a></b>(const QByteArrayList &<i>layers</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#setVkInstance">setVkInstance</a></b>(int <i>existingVkInstance</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QVulkanInfoVector<QVulkanExtension> </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#supportedExtensions">supportedExtensions</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QVulkanInfoVector<QVulkanLayer> </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#supportedLayers">supportedLayers</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#supportsPresent">supportsPresent</a></b>(int <i>physicalDevice</i>, uint32_t <i>queueFamilyIndex</i>, QWindow *<i>window</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> int </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#vkInstance">vkInstance</a></b>() const</td></tr>
</table></div>
<a name="static-public-members"></a>
<h2 id="static-public-members">Static Public Members</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> VkSurfaceKHR </td><td class="memItemRight bottomAlign"><b><a href="qvulkaninstance.html#surfaceForWindow">surfaceForWindow</a></b>(QWindow *<i>window</i>)</td></tr>
</table></div>
<a name="details"></a>
<!-- $$$QVulkanInstance-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>The <a href="qvulkaninstance.html">QVulkanInstance</a> class represents a native Vulkan instance, enabling Vulkan rendering onto a <a href="qsurface.html">QSurface</a>.</p>
<p><a href="https://www.khronos.org/vulkan/">Vulkan</a> is a cross-platform, explicit graphics and compute API. This class provides support for loading a Vulkan library and creating an <code>instance</code> in a cross-platform manner. For an introduction on Vulkan instances, refer <a href="https://www.khronos.org/registry/vulkan/specs/1.0/html/vkspec.html#initialization-instances">to section 3.2 of the specification</a>.</p>
<p><b>Note: </b>Platform-specific support for Vulkan instances and windows with Vulkan-capable surfaces is provided by the various platform plugins. Not all of them will support Vulkan, however. When running on such a platform, <a href="qvulkaninstance.html#create">create</a>() will fail and always return <code>false</code>.</p><p><b>Note: </b>Vulkan support may get automatically disabled for a given Qt build due to not having the necessary Vulkan headers available at build time. When this is the case, and the output of <code>configure</code> indicates Vulkan support is disabled, the QVulkan* classes will be unavailable.</p><p><b>Note: </b>Some functions changed their signature between the various Vulkan header revisions. When building Qt and only headers with the old, conflicting signatures are present in a system, Vulkan support will get disabled. It is recommended to use headers from Vulkan 1.0.39 or newer.</p><a name="initialization"></a>
<h3 id="initialization">Initialization</h3>
<p>Similarly to <a href="qopenglcontext.html">QOpenGLContext</a>, any actual Vulkan instance creation happens only when calling <a href="qvulkaninstance.html#create">create</a>(). This allows using <a href="qvulkaninstance.html">QVulkanInstance</a> as a plain member variable while retaining control over when to perform initialization.</p>
<p>Querying the supported instance-level layers and extensions is possible by calling <a href="qvulkaninstance.html#supportedLayers">supportedLayers</a>() and <a href="qvulkaninstance.html#supportedExtensions">supportedExtensions</a>(). These ensure the Vulkan library is loaded, and can therefore be called safely before <a href="qvulkaninstance.html#create">create</a>() as well.</p>
<p>Instances store per-application Vulkan state and creating a <code>VkInstance</code> object initializes the Vulkan library. In practice there will typically be a single instance constructed early on in main(). The object then stays alive until exiting the application.</p>
<p>Every Vulkan-based <a href="qwindow.html">QWindow</a> must be associated with a <a href="qvulkaninstance.html">QVulkanInstance</a> by calling <a href="qwindow.html#setVulkanInstance">QWindow::setVulkanInstance</a>(). Thus a typical application pattern is the following:</p>
<pre class="cpp">
<span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span><span class="operator">*</span>argv)
{
<span class="type"><a href="qguiapplication.html">QGuiApplication</a></span> app(argc<span class="operator">,</span> argv);
<span class="type"><a href="qvulkaninstance.html#QVulkanInstance">QVulkanInstance</a></span> inst;
<span class="keyword">if</span> (<span class="operator">!</span>inst<span class="operator">.</span>create())
<span class="keyword">return</span> <span class="number">1</span>;
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
window<span class="operator">-</span><span class="operator">></span>setVulkanInstance(<span class="operator">&</span>inst);
window<span class="operator">-</span><span class="operator">></span>show();
<span class="keyword">return</span> app<span class="operator">.</span>exec();
}
</pre>
<a name="configuration"></a>
<h3 id="configuration">Configuration</h3>
<p><a href="qvulkaninstance.html">QVulkanInstance</a> automatically enables the minimum set of extensions it needs on the newly created instance. In practice this means the <code>VK_KHR_*_surface</code> family of extensions.</p>
<p>By default Vulkan debug output, for example messages from the validation layers, is routed to <a href="../qtcore/qtglobal.html#qDebug">qDebug</a>(). This can be disabled by passing the flag <code>NoDebugOutputRedirect</code> to <a href="qvulkaninstance.html#setFlags">setFlags</a>() <i>before</i> invoking <a href="qvulkaninstance.html#create">create</a>().</p>
<p>To enable additional layers and extensions, provide the list via <a href="qvulkaninstance.html#setLayers">setLayers</a>() and <a href="qvulkaninstance.html#setExtensions">setExtensions</a>() <i>before</i> invoking <a href="qvulkaninstance.html#create">create</a>(). When a given layer or extension is not reported as available from the instance, the request is ignored. After a successful call to <a href="qvulkaninstance.html#create">create</a>(), the values returned from functions like <a href="qvulkaninstance.html#layers">layers</a>() and <a href="qvulkaninstance.html#extensions">extensions</a>() reflect the actual enabled layers and extensions. When necessary, for example to avoid requesting extensions that conflict and thus would fail the Vulkan instance creation, the list of actually supported layers and extensions can be examined via <a href="qvulkaninstance.html#supportedLayers">supportedLayers</a>() and <a href="qvulkaninstance.html#supportedExtensions">supportedExtensions</a>() before calling <a href="qvulkaninstance.html#create">create</a>().</p>
<p>For example, to enable the standard validation layers, one could do the following:</p>
<pre class="cpp">
<span class="type"><a href="qvulkaninstance.html#QVulkanInstance">QVulkanInstance</a></span> inst;
<span class="comment">// Enable validation layer, if supported. Messages go to qDebug by default.</span>
inst<span class="operator">.</span>setLayers(<span class="type"><a href="../qtcore/qbytearraylist.html">QByteArrayList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"VK_LAYER_LUNARG_standard_validation"</span>);
bool ok <span class="operator">=</span> inst<span class="operator">.</span>create();
<span class="keyword">if</span> (<span class="operator">!</span>ok)
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> <span class="comment">// Vulkan not available</span>
<span class="keyword">if</span> (<span class="operator">!</span>inst<span class="operator">.</span>layers()<span class="operator">.</span>contains(<span class="string">"VK_LAYER_LUNARG_standard_validation"</span>))
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> <span class="comment">// validation layer not available</span>
</pre>
<p>Or, alternatively, to make decisions before attempting to create a Vulkan instance:</p>
<pre class="cpp">
<span class="type"><a href="qvulkaninstance.html#QVulkanInstance">QVulkanInstance</a></span> inst;
<span class="keyword">if</span> (inst<span class="operator">.</span>supportedLayers()<span class="operator">.</span>contains(<span class="string">"VK_LAYER_LUNARG_standard_validation"</span>))
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
bool ok <span class="operator">=</span> inst<span class="operator">.</span>create();
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
</pre>
<a name="adopting-an-existing-instance"></a>
<h3 id="adopting-an-existing-instance">Adopting an Existing Instance</h3>
<p>By default <a href="qvulkaninstance.html">QVulkanInstance</a> creates a new Vulkan instance. When working with external engines and renderers, this may sometimes not be desirable. When there is a <code>VkInstance</code> handle already available, call <a href="qvulkaninstance.html#setVkInstance">setVkInstance</a>() before invoking <a href="qvulkaninstance.html#create">create</a>(). This way no additional instances will get created, and <a href="qvulkaninstance.html">QVulkanInstance</a> will not own the handle.</p>
<p><b>Note: </b>It is up to the component creating the external instance to ensure the necessary extensions are enabled on it. These are: <code>VK_KHR_surface</code>, the WSI-specific <code>VK_KHR_*_surface</code> that is appropriate for the platform in question, and <code>VK_EXT_debug_report</code> in case <a href="qvulkaninstance.html">QVulkanInstance</a>'s debug output redirection is desired.</p><a name="accessing-core-vulkan-commands"></a>
<h3 id="accessing-core-vulkan-commands">Accessing Core Vulkan Commands</h3>
<p>To access the <code>VkInstance</code> handle the <a href="qvulkaninstance.html">QVulkanInstance</a> wraps, call <a href="qvulkaninstance.html#vkInstance">vkInstance</a>(). To resolve Vulkan functions, call <a href="qvulkaninstance.html#getInstanceProcAddr">getInstanceProcAddr</a>(). For core Vulkan commands manual resolving is not necessary as they are provided via the <a href="qvulkanfunctions.html">QVulkanFunctions</a> and <a href="qvulkandevicefunctions.html">QVulkanDeviceFunctions</a> objects accessible via <a href="qvulkaninstance.html#functions">functions</a>() and <a href="qvulkaninstance.html#deviceFunctions">deviceFunctions</a>().</p>
<p><b>Note: </b><a href="qvulkanfunctions.html">QVulkanFunctions</a> and <a href="qvulkandevicefunctions.html">QVulkanDeviceFunctions</a> are generated from the Vulkan API XML specifications when building the Qt libraries. Therefore no documentation is provided for them. They contain the Vulkan 1.0 functions with the same signatures as described in the <a href="https://www.khronos.org/registry/vulkan/specs/1.0/html/">Vulkan API documentation</a>.</p><a name="getting-a-native-vulkan-surface-for-a-window"></a>
<h3 id="getting-a-native-vulkan-surface-for-a-window">Getting a Native Vulkan Surface for a Window</h3>
<p>The two common windowing system specific operations are getting a surface (a <code>VkSurfaceKHR</code> handle) for a window, and querying if a given queue family supports presenting to a given surface. To avoid WSI-specific bits in the applications, these are abstracted by <a href="qvulkaninstance.html">QVulkanInstance</a> and the underlying QPA layers.</p>
<p>To create a Vulkan surface for a window, or retrieve an existing one, call <a href="qvulkaninstance.html#surfaceForWindow">surfaceForWindow</a>(). Most platforms will only create the surface via <code>VK_KHR_*_surface</code> when first calling <a href="qvulkaninstance.html#surfaceForWindow">surfaceForWindow</a>(), but there may be platform-specific variations in the internal behavior. Once created, subsequent calls to <a href="qvulkaninstance.html#surfaceForWindow">surfaceForWindow</a>() just return the same handle. This fits the structure of typical Vulkan-enabled <a href="qwindow.html">QWindow</a> subclasses well.</p>
<p>To query if a given queue family within a physical device can be used to perform presentation to a given surface, call <a href="qvulkaninstance.html#supportsPresent">supportsPresent</a>(). This encapsulates both the generic <code>vkGetPhysicalDeviceSurfaceSupportKHR</code> and the WSI-specific <code>vkGetPhysicalDevice*PresentationSupportKHR</code> checks.</p>
<a name="troubleshooting"></a>
<h3 id="troubleshooting">Troubleshooting</h3>
<p>Besides returning <code>false</code> from <a href="qvulkaninstance.html#create">create</a>() or <code>0</code> from <a href="qvulkaninstance.html#surfaceForWindow">surfaceForWindow</a>(), critical errors will also get printed to the debug output via <a href="../qtcore/qtglobal.html#qWarning">qWarning</a>(). Additional logging can be requested by enabling debug output for the logging category <code>qt.vulkan</code>. The actual Vulkan error code from instance creation can be retrieved by calling <a href="qvulkaninstance.html#errorCode">errorCode</a>() after a failing <a href="qvulkaninstance.html#create">create</a>().</p>
<p>In some special cases it may be necessary to override the Vulkan library name. This can be achieved by setting the <code>QT_VULKAN_LIB</code> environment variable.</p>
<a name="example"></a>
<h3 id="example">Example</h3>
<p>The following is the basic outline of creating a Vulkan-capable <a href="qwindow.html">QWindow</a>:</p>
<pre class="cpp">
<span class="keyword">class</span> VulkanWindow : <span class="keyword">public</span> <span class="type"><a href="qwindow.html">QWindow</a></span>
{
<span class="keyword">public</span>:
VulkanWindow() {
setSurfaceType(VulkanSurface);
}
<span class="type">void</span> exposeEvent(<span class="type"><a href="qexposeevent.html">QExposeEvent</a></span> <span class="operator">*</span>) {
<span class="keyword">if</span> (isExposed()) {
<span class="keyword">if</span> (<span class="operator">!</span>m_initialized) {
m_initialized <span class="operator">=</span> <span class="keyword">true</span>;
<span class="comment">// initialize device, swapchain, etc.</span>
<span class="type"><a href="qvulkaninstance.html#QVulkanInstance">QVulkanInstance</a></span> <span class="operator">*</span>inst <span class="operator">=</span> vulkanInstance();
<span class="type"><a href="qvulkanfunctions.html">QVulkanFunctions</a></span> <span class="operator">*</span>f <span class="operator">=</span> inst<span class="operator">-</span><span class="operator">></span>functions();
uint32_t devCount <span class="operator">=</span> <span class="number">0</span>;
f<span class="operator">-</span><span class="operator">></span>vkEnumeratePhysicalDevices(inst<span class="operator">-</span><span class="operator">></span>vkInstance()<span class="operator">,</span> <span class="operator">&</span>devCount<span class="operator">,</span> nullptr);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="comment">// build the first frame</span>
render();
}
}
}
bool event(<span class="type"><a href="../qtcore/qevent.html">QEvent</a></span> <span class="operator">*</span>e) {
<span class="keyword">if</span> (e<span class="operator">-</span><span class="operator">></span>type() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="../qtcore/qevent.html">QEvent</a></span><span class="operator">::</span>UpdateRequest)
render();
<span class="keyword">return</span> <span class="type"><a href="qwindow.html">QWindow</a></span><span class="operator">::</span>event(e);
}
<span class="type">void</span> render() {
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
requestUpdate(); <span class="comment">// render continuously</span>
}
<span class="keyword">private</span>:
bool m_initialized <span class="operator">=</span> <span class="keyword">false</span>;
};
<span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span><span class="operator">*</span>argv)
{
<span class="type"><a href="qguiapplication.html">QGuiApplication</a></span> app(argc<span class="operator">,</span> argv);
<span class="type"><a href="qvulkaninstance.html#QVulkanInstance">QVulkanInstance</a></span> inst;
<span class="keyword">if</span> (<span class="operator">!</span>inst<span class="operator">.</span>create()) {
<a href="../qtcore/qtglobal.html#qWarning">qWarning</a>(<span class="string">"Vulkan not available"</span>);
<span class="keyword">return</span> <span class="number">1</span>;
}
VulkanWindow window;
window<span class="operator">.</span>showMaximized();
<span class="keyword">return</span> app<span class="operator">.</span>exec();
}
</pre>
<p><b>Note: </b>In addition to expose, a well-behaving window implementation will also have to take care of additional events like resize and <a href="qplatformsurfaceevent.html">QPlatformSurfaceEvent</a> in order to ensure proper management of the swap chain. Additionally, some platforms may require releasing resources when not being exposed anymore.</p><a name="using-c-bindings-for-vulkan"></a>
<h3 id="using-c-bindings-for-vulkan">Using C++ Bindings for Vulkan</h3>
<p>Combining Qt's Vulkan enablers with a C++ Vulkan wrapper, for example <a href="https://github.com/KhronosGroup/Vulkan-Hpp">Vulkan-Hpp</a>, is possible as well. The pre-requisite here is that the C++ layer must be able to adopt native handles (VkInstance, VkSurfaceKHR) in its classes without taking ownership (since the ownership stays with <a href="qvulkaninstance.html">QVulkanInstance</a> and <a href="qwindow.html">QWindow</a>). Consider also the following:</p>
<ul>
<li>Some wrappers require exception support to be enabled. Qt does not use exceptions. To enable exceptions for the application, add <code>CONFIG += exceptions</code> to the <code>.pro</code> file.</li>
<li>Some wrappers call Vulkan functions directly, assuming <code>vulkan.h</code> provides prototypes and the application links to a Vulkan library exporting all necessary symbols. Qt may not directly link to a Vulkan library. Therefore, on some platforms it may be necessary to add <code>LIBS += -lvulkan</code> or similar in the application's <code>.pro</code> file.</li>
<li>The headers for the QVulkan classes may include <code>vulkan.h</code> with <code>VK_NO_PROTOTYPES</code> enabled. This can cause issues in C++ wrapper headers that rely on the prototypes. Hence in application code it may be necessary to include <code>vulkan.hpp</code> or similar before any of the QVulkan headers.</li>
</ul>
</div>
<p><b>See also </b><a href="qvulkanfunctions.html">QVulkanFunctions</a> and <a href="qsurface.html#SurfaceType-enum">QSurface::SurfaceType</a>.</p>
<!-- @@@QVulkanInstance -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$Flag$$$NoDebugOutputRedirect -->
<h3 class="flags" id="Flag-enum"><a name="Flag-enum"></a>enum QVulkanInstance::<span class="name">Flag</span><br/>flags QVulkanInstance::<span class="name">Flags</span></h3>
<p>This enum describes the flags that can be passed to <a href="qvulkaninstance.html#setFlags">setFlags</a>(). These control the behavior of <a href="qvulkaninstance.html#create">create</a>().</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QVulkanInstance::NoDebugOutputRedirect</code></td><td class="topAlign tblval"><code>0x01</code></td><td class="topAlign">Disables Vulkan debug output (<code>VK_EXT_debug_report</code>) redirection to <a href="../qtcore/qtglobal.html#qDebug">qDebug</a>.</td></tr>
</table></div>
<p>This enum was introduced or modified in Qt 5.10.</p>
<p>The Flags type is a typedef for <a href="../qtcore/qflags.html">QFlags</a><Flag>. It stores an OR combination of Flag values.</p>
<!-- @@@Flag -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QVulkanInstance[overload1]$$$QVulkanInstance -->
<h3 class="fn" id="QVulkanInstance"><a name="QVulkanInstance"></a>QVulkanInstance::<span class="name">QVulkanInstance</span>()</h3>
<p>Constructs a new instance.</p>
<p><b>Note: </b>No Vulkan initialization is performed in the constructor.</p><!-- @@@QVulkanInstance -->
<!-- $$$~QVulkanInstance[overload1]$$$~QVulkanInstance -->
<h3 class="fn" id="dtor.QVulkanInstance"><a name="dtor.QVulkanInstance"></a>QVulkanInstance::<span class="name">~QVulkanInstance</span>()</h3>
<p>Destructor.</p>
<p><b>Note: </b>current() will return <code>nullptr</code> once the instance is destroyed.</p><!-- @@@~QVulkanInstance -->
<!-- $$$apiVersion[overload1]$$$apiVersion -->
<h3 class="fn" id="apiVersion"><a name="apiVersion"></a><span class="type"><a href="../qtcore/qversionnumber.html">QVersionNumber</a></span> QVulkanInstance::<span class="name">apiVersion</span>() const</h3>
<p>Returns the requested Vulkan API version against which the application expects to run, or a null version number if <a href="qvulkaninstance.html#setApiVersion">setApiVersion</a>() was not called before <a href="qvulkaninstance.html#create">create</a>().</p>
<p><b>See also </b><a href="qvulkaninstance.html#setApiVersion">setApiVersion</a>().</p>
<!-- @@@apiVersion -->
<!-- $$$create[overload1]$$$create -->
<h3 class="fn" id="create"><a name="create"></a><span class="type">bool</span> QVulkanInstance::<span class="name">create</span>()</h3>
<p>Initializes the Vulkan library and creates a new or adopts and existing Vulkan instance.</p>
<p>Returns true if successful, false on error or when Vulkan is not supported.</p>
<p>When successful, the pointer to this <a href="qvulkaninstance.html">QVulkanInstance</a> is retrievable via the static function current().</p>
<p>The Vulkan instance and library is available as long as this <a href="qvulkaninstance.html">QVulkanInstance</a> exists, or until <a href="qvulkaninstance.html#destroy">destroy</a>() is called.</p>
<!-- @@@create -->
<!-- $$$destroy[overload1]$$$destroy -->
<h3 class="fn" id="destroy"><a name="destroy"></a><span class="type">void</span> QVulkanInstance::<span class="name">destroy</span>()</h3>
<p>Destroys the underlying platform instance, thus destroying the VkInstance (when owned). The <a href="qvulkaninstance.html">QVulkanInstance</a> object is still reusable by calling <a href="qvulkaninstance.html#create">create</a>() again.</p>
<!-- @@@destroy -->
<!-- $$$deviceFunctions[overload1]$$$deviceFunctionsint -->
<h3 class="fn" id="deviceFunctions"><a name="deviceFunctions"></a><span class="type"><a href="qvulkandevicefunctions.html">QVulkanDeviceFunctions</a></span> *QVulkanInstance::<span class="name">deviceFunctions</span>(<span class="type">int</span> <i>device</i>)</h3>
<p>Returns the <a href="qvulkandevicefunctions.html">QVulkanDeviceFunctions</a> object that exposes the device level core Vulkan command set and is guaranteed to be functional cross-platform.</p>
<p><b>Note: </b>The Vulkan functions in the returned object must only be called with <i>device</i> or a child object (VkQueue, VkCommandBuffer) of <i>device</i> as their first parameter. This is because these functions are resolved via <a href="https://www.khronos.org/registry/vulkan/specs/1.0/man/html/vkGetDeviceProcAddr.html">vkGetDeviceProcAddr</a> in order to avoid the potential overhead of internal dispatching.</p><p><b>Note: </b>The returned object is owned and managed by the <a href="qvulkaninstance.html">QVulkanInstance</a>. Do not destroy or alter it.</p><p><b>Note: </b>The object is cached so calling this function with the same <i>device</i> again is a cheap operation. However, when the device gets destroyed, it is up to the application to notify the <a href="qvulkaninstance.html">QVulkanInstance</a> by calling <a href="qvulkaninstance.html#resetDeviceFunctions">resetDeviceFunctions</a>().</p><p><b>See also </b><a href="qvulkaninstance.html#functions">functions</a>() and <a href="qvulkaninstance.html#resetDeviceFunctions">resetDeviceFunctions</a>().</p>
<!-- @@@deviceFunctions -->
<!-- $$$errorCode[overload1]$$$errorCode -->
<h3 class="fn" id="errorCode"><a name="errorCode"></a><span class="type">int</span> QVulkanInstance::<span class="name">errorCode</span>() const</h3>
<p>Returns the Vulkan error code after an unsuccessful <a href="qvulkaninstance.html#create">create</a>(), <code>VK_SUCCESS</code> otherwise.</p>
<p>The value is typically the return value from vkCreateInstance() (when creating a new Vulkan instance instead of adopting an existing one), but may also be <code>VK_NOT_READY</code> if the platform plugin does not support Vulkan.</p>
<!-- @@@errorCode -->
<!-- $$$extensions[overload1]$$$extensions -->
<h3 class="fn" id="extensions"><a name="extensions"></a><span class="type"><a href="../qtcore/qbytearraylist.html">QByteArrayList</a></span> QVulkanInstance::<span class="name">extensions</span>() const</h3>
<p>Returns the enabled instance extensions, if <a href="qvulkaninstance.html#create">create</a>() was called and was successful. The requested extensions otherwise.</p>
<p><b>See also </b><a href="qvulkaninstance.html#setExtensions">setExtensions</a>().</p>
<!-- @@@extensions -->
<!-- $$$flags[overload1]$$$flags -->
<h3 class="fn" id="flags"><a name="flags"></a><span class="type"><a href="qvulkaninstance.html#Flag-enum">QVulkanInstance::Flags</a></span> QVulkanInstance::<span class="name">flags</span>() const</h3>
<p>Returns the requested flags.</p>
<p><b>See also </b><a href="qvulkaninstance.html#setFlags">setFlags</a>().</p>
<!-- @@@flags -->
<!-- $$$functions[overload1]$$$functions -->
<h3 class="fn" id="functions"><a name="functions"></a><span class="type"><a href="qvulkanfunctions.html">QVulkanFunctions</a></span> *QVulkanInstance::<span class="name">functions</span>() const</h3>
<p>Returns the corresponding <a href="qvulkanfunctions.html">QVulkanFunctions</a> object that exposes the core Vulkan command set, excluding device level functions, and is guaranteed to be functional cross-platform.</p>
<p><b>Note: </b>The returned object is owned and managed by the <a href="qvulkaninstance.html">QVulkanInstance</a>. Do not destroy or alter it.</p><p><b>See also </b><a href="qvulkaninstance.html#deviceFunctions">deviceFunctions</a>().</p>
<!-- @@@functions -->
<!-- $$$getInstanceProcAddr[overload1]$$$getInstanceProcAddrconstchar* -->
<h3 class="fn" id="getInstanceProcAddr"><a name="getInstanceProcAddr"></a><span class="type">PFN_vkVoidFunction</span> QVulkanInstance::<span class="name">getInstanceProcAddr</span>(const <span class="type">char</span> *<i>name</i>)</h3>
<p>Resolves the Vulkan function with the given <i>name</i>.</p>
<p>For core Vulkan commands prefer using the function wrappers retrievable from <a href="qvulkaninstance.html#functions">functions</a>() and <a href="qvulkaninstance.html#deviceFunctions">deviceFunctions</a>() instead.</p>
<!-- @@@getInstanceProcAddr -->
<!-- $$$isValid[overload1]$$$isValid -->
<h3 class="fn" id="isValid"><a name="isValid"></a><span class="type">bool</span> QVulkanInstance::<span class="name">isValid</span>() const</h3>
<p>Returns true if <a href="qvulkaninstance.html#create">create</a>() was successful and the instance is valid.</p>
<!-- @@@isValid -->
<!-- $$$layers[overload1]$$$layers -->
<h3 class="fn" id="layers"><a name="layers"></a><span class="type"><a href="../qtcore/qbytearraylist.html">QByteArrayList</a></span> QVulkanInstance::<span class="name">layers</span>() const</h3>
<p>Returns the enabled instance layers, if <a href="qvulkaninstance.html#create">create</a>() was called and was successful. The requested layers otherwise.</p>
<p><b>See also </b><a href="qvulkaninstance.html#setLayers">setLayers</a>().</p>
<!-- @@@layers -->
<!-- $$$presentQueued[overload1]$$$presentQueuedQWindow* -->
<h3 class="fn" id="presentQueued"><a name="presentQueued"></a><span class="type">void</span> QVulkanInstance::<span class="name">presentQueued</span>(<span class="type"><a href="qwindow.html">QWindow</a></span> *<i>window</i>)</h3>
<p>This function should be called by the application's renderer after queuing a present operation for <i>window</i>.</p>
<p>While on some platforms this will be a no-op, some may perform windowing system dependent synchronization. For example, on X11 this will update <code>_NET_WM_SYNC_REQUEST_COUNTER</code>.</p>
<!-- @@@presentQueued -->
<!-- $$$resetDeviceFunctions[overload1]$$$resetDeviceFunctionsint -->
<h3 class="fn" id="resetDeviceFunctions"><a name="resetDeviceFunctions"></a><span class="type">void</span> QVulkanInstance::<span class="name">resetDeviceFunctions</span>(<span class="type">int</span> <i>device</i>)</h3>
<p>Invalidates and destroys the <a href="qvulkandevicefunctions.html">QVulkanDeviceFunctions</a> object for the given <i>device</i>.</p>
<p>This function must be called when a VkDevice, for which <a href="qvulkaninstance.html#deviceFunctions">deviceFunctions</a>() was called, gets destroyed while the application intends to continue running, possibly creating a new logical Vulkan device later on.</p>
<p>There is no need to call this before destroying the <a href="qvulkaninstance.html">QVulkanInstance</a> since clean up is then performed automatically.</p>
<p><b>See also </b><a href="qvulkaninstance.html#deviceFunctions">deviceFunctions</a>().</p>
<!-- @@@resetDeviceFunctions -->
<!-- $$$setApiVersion[overload1]$$$setApiVersionconstQVersionNumber& -->
<h3 class="fn" id="setApiVersion"><a name="setApiVersion"></a><span class="type">void</span> QVulkanInstance::<span class="name">setApiVersion</span>(const <span class="type"><a href="../qtcore/qversionnumber.html">QVersionNumber</a></span> &<i>vulkanVersion</i>)</h3>
<p>Specifies the Vulkan API against which the application expects to run.</p>
<p>By default no <i>vulkanVersion</i> is specified, and so no version check is performed during Vulkan instance creation.</p>
<p><b>Note: </b>This function can only be called before <a href="qvulkaninstance.html#create">create</a>() and has no effect if called afterwards.</p><p><b>See also </b><a href="qvulkaninstance.html#apiVersion">apiVersion</a>().</p>
<!-- @@@setApiVersion -->
<!-- $$$setExtensions[overload1]$$$setExtensionsconstQByteArrayList& -->
<h3 class="fn" id="setExtensions"><a name="setExtensions"></a><span class="type">void</span> QVulkanInstance::<span class="name">setExtensions</span>(const <span class="type"><a href="../qtcore/qbytearraylist.html">QByteArrayList</a></span> &<i>extensions</i>)</h3>
<p>Specifies the list of additional instance <i>extensions</i> to enable. It is safe to specify unsupported extensions as well because these get ignored when not supported at run time. The surface-related extensions required by Qt will always be added automatically, no need to include them in this list.</p>
<p><b>Note: </b>This function can only be called before <a href="qvulkaninstance.html#create">create</a>() and has no effect if called afterwards.</p><p><b>See also </b><a href="qvulkaninstance.html#extensions">extensions</a>().</p>
<!-- @@@setExtensions -->
<!-- $$$setFlags[overload1]$$$setFlagsQVulkanInstance::Flags -->
<h3 class="fn" id="setFlags"><a name="setFlags"></a><span class="type">void</span> QVulkanInstance::<span class="name">setFlags</span>(<span class="type"><a href="qvulkaninstance.html#Flag-enum">QVulkanInstance::Flags</a></span> <i>flags</i>)</h3>
<p>Configures the behavior of <a href="qvulkaninstance.html#create">create</a>() based on the provided <i>flags</i>.</p>
<p><b>Note: </b>This function can only be called before <a href="qvulkaninstance.html#create">create</a>() and has no effect if called afterwards.</p><p><b>See also </b><a href="qvulkaninstance.html#flags">flags</a>().</p>
<!-- @@@setFlags -->
<!-- $$$setLayers[overload1]$$$setLayersconstQByteArrayList& -->
<h3 class="fn" id="setLayers"><a name="setLayers"></a><span class="type">void</span> QVulkanInstance::<span class="name">setLayers</span>(const <span class="type"><a href="../qtcore/qbytearraylist.html">QByteArrayList</a></span> &<i>layers</i>)</h3>
<p>Specifies the list of instance <i>layers</i> to enable. It is safe to specify unsupported layers as well because these get ignored when not supported at run time.</p>
<p><b>Note: </b>This function can only be called before <a href="qvulkaninstance.html#create">create</a>() and has no effect if called afterwards.</p><p><b>See also </b><a href="qvulkaninstance.html#layers">layers</a>().</p>
<!-- @@@setLayers -->
<!-- $$$setVkInstance[overload1]$$$setVkInstanceint -->
<h3 class="fn" id="setVkInstance"><a name="setVkInstance"></a><span class="type">void</span> QVulkanInstance::<span class="name">setVkInstance</span>(<span class="type">int</span> <i>existingVkInstance</i>)</h3>
<p>Makes <a href="qvulkaninstance.html">QVulkanInstance</a> adopt an existing VkInstance handle instead of creating a new one.</p>
<p><b>Note: </b><i>existingVkInstance</i> must have at least <code>VK_KHR_surface</code> and the appropriate WSI-specific <code>VK_KHR_*_surface</code> extensions enabled. To ensure debug output redirection is functional, <code>VK_EXT_debug_report</code> is needed as well.</p><p><b>Note: </b>This function can only be called before <a href="qvulkaninstance.html#create">create</a>() and has no effect if called afterwards.</p><p><b>See also </b><a href="qvulkaninstance.html#vkInstance">vkInstance</a>().</p>
<!-- @@@setVkInstance -->
<!-- $$$supportedExtensions[overload1]$$$supportedExtensions -->
<h3 class="fn" id="supportedExtensions"><a name="supportedExtensions"></a><span class="type"><a href="qvulkaninfovector.html">QVulkanInfoVector</a></span><<span class="type"><a href="qvulkanextension.html">QVulkanExtension</a></span>> QVulkanInstance::<span class="name">supportedExtensions</span>()</h3>
<p>Returns the list of supported instance-level extensions.</p>
<p><b>Note: </b>This function can be called before <a href="qvulkaninstance.html#create">create</a>().</p><!-- @@@supportedExtensions -->
<!-- $$$supportedLayers[overload1]$$$supportedLayers -->
<h3 class="fn" id="supportedLayers"><a name="supportedLayers"></a><span class="type"><a href="qvulkaninfovector.html">QVulkanInfoVector</a></span><<span class="type"><a href="qvulkanlayer.html">QVulkanLayer</a></span>> QVulkanInstance::<span class="name">supportedLayers</span>()</h3>
<p>Returns the list of supported instance-level layers.</p>
<p><b>Note: </b>This function can be called before <a href="qvulkaninstance.html#create">create</a>().</p><!-- @@@supportedLayers -->
<!-- $$$supportsPresent[overload1]$$$supportsPresentintuint32_tQWindow* -->
<h3 class="fn" id="supportsPresent"><a name="supportsPresent"></a><span class="type">bool</span> QVulkanInstance::<span class="name">supportsPresent</span>(<span class="type">int</span> <i>physicalDevice</i>, <span class="type">uint32_t</span> <i>queueFamilyIndex</i>, <span class="type"><a href="qwindow.html">QWindow</a></span> *<i>window</i>)</h3>
<p>Returns true if the queue family with <i>queueFamilyIndex</i> within the <i>physicalDevice</i> supports presenting to <i>window</i>.</p>
<p>Call this function when examining the queues of a given Vulkan device, in order to decide which queue can be used for performing presentation.</p>
<!-- @@@supportsPresent -->
<!-- $$$surfaceForWindow[overload1]$$$surfaceForWindowQWindow* -->
<h3 class="fn" id="surfaceForWindow"><a name="surfaceForWindow"></a><code>[static] </code><span class="type">VkSurfaceKHR</span> QVulkanInstance::<span class="name">surfaceForWindow</span>(<span class="type"><a href="qwindow.html">QWindow</a></span> *<i>window</i>)</h3>
<p>Creates or retrieves the already existing <code>VkSurfaceKHR</code> handle for the given <i>window</i>.</p>
<p>Returns the Vulkan surface handle or 0 when failed.</p>
<!-- @@@surfaceForWindow -->
<!-- $$$vkInstance[overload1]$$$vkInstance -->
<h3 class="fn" id="vkInstance"><a name="vkInstance"></a><span class="type">int</span> QVulkanInstance::<span class="name">vkInstance</span>() const</h3>
<p>Returns the VkInstance handle this <a href="qvulkaninstance.html">QVulkanInstance</a> wraps, or <code>null</code> if <a href="qvulkaninstance.html#create">create</a>() has not yet been successfully called and no existing instance has been provided via <a href="qvulkaninstance.html#setVkInstance">setVkInstance</a>().</p>
<p><b>See also </b><a href="qvulkaninstance.html#setVkInstance">setVkInstance</a>().</p>
<!-- @@@vkInstance -->
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
d5e62c01ae8d1e579463c6a871dd44bf
>
files
>
1940
