eu07/maszyna
16
0
Fork 0
mirror of https://github.com/MaSzyna-EU07/maszyna.git synced 2026-07-21 13:39:18 +02:00
Code Issues 123 Wiki Activity

maintenance: glfw update to v 3.3.2

Browse Source
This commit is contained in:
tmj-fstate
2020-10-05 18:35:59 +02:00
parent 730ba72516
commit ef200df575
166 changed files with 4592 additions and 2302 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
ref/glfw/docs/html/vulkan_guide.html
View File

@@ -3,7 +3,7 @@
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.15"/>
<meta name="generator" content="Doxygen 1.8.16"/>
<title>GLFW: Vulkan guide</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
@@ -27,7 +27,7 @@
</div>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.15 -->
<!-- Generated by Doxygen 1.8.16 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
@@ -93,48 +93,93 @@ Linking against the Vulkan loader</h1>
<h1><a class="anchor" id="vulkan_include"></a>
Including the Vulkan and GLFW header files</h1>
<p>To include the Vulkan header, define <a class="el" href="build_guide.html#GLFW_INCLUDE_VULKAN">GLFW_INCLUDE_VULKAN</a> before including the GLFW header.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define GLFW_INCLUDE_VULKAN</span></div><div class="line"><span class="preprocessor">#include &lt;GLFW/glfw3.h&gt;</span></div></div><!-- fragment --><p>If you instead want to include the Vulkan header from a custom location or use your own custom Vulkan header then do this before the GLFW header.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;path/to/vulkan.h&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="glfw3_8h.html">GLFW/glfw3.h</a>&gt;</span></div></div><!-- fragment --><p>Unless a Vulkan header is included, either by the GLFW header or above it, any GLFW functions that take or return Vulkan types will not be declared.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#define GLFW_INCLUDE_VULKAN</span></div>
<div class="line"><span class="preprocessor">#include &lt;GLFW/glfw3.h&gt;</span></div>
</div><!-- fragment --><p>If you instead want to include the Vulkan header from a custom location or use your own custom Vulkan header then do this before the GLFW header.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;path/to/vulkan.h&gt;</span></div>
<div class="line"><span class="preprocessor">#include &lt;<a class="code" href="glfw3_8h.html">GLFW/glfw3.h</a>&gt;</span></div>
</div><!-- fragment --><p>Unless a Vulkan header is included, either by the GLFW header or above it, any GLFW functions that take or return Vulkan types will not be declared.</p>
<p>The <code>VK_USE_PLATFORM_*_KHR</code> macros do not need to be defined for the Vulkan part of GLFW to work. Define them only if you are using these extensions directly.</p>
<h1><a class="anchor" id="vulkan_support"></a>
Querying for Vulkan support</h1>
<p>If you are linking directly against the Vulkan loader then you can skip this section. The canonical desktop loader library exports all Vulkan core and Khronos extension functions, allowing them to be called directly.</p>
<p>If you are loading the Vulkan loader dynamically instead of linking directly against it, you can check for the availability of a loader and ICD with <a class="el" href="group__vulkan.html#ga2e7f30931e02464b5bc8d0d4b6f9fe2b">glfwVulkanSupported</a>.</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__vulkan.html#ga2e7f30931e02464b5bc8d0d4b6f9fe2b">glfwVulkanSupported</a>())</div><div class="line">{</div><div class="line"> <span class="comment">// Vulkan is available, at least for compute</span></div><div class="line">}</div></div><!-- fragment --><p>This function returns <code>GLFW_TRUE</code> if the Vulkan loader and any minimally functional ICD was found.</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__vulkan.html#ga2e7f30931e02464b5bc8d0d4b6f9fe2b">glfwVulkanSupported</a>())</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// Vulkan is available, at least for compute</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>This function returns <code>GLFW_TRUE</code> if the Vulkan loader and any minimally functional ICD was found.</p>
<p>If if one or both were not found, calling any other Vulkan related GLFW function will generate a <a class="el" href="group__errors.html#ga56882b290db23261cc6c053c40c2d08e">GLFW_API_UNAVAILABLE</a> error.</p>
<h2><a class="anchor" id="vulkan_proc"></a>
Querying Vulkan function pointers</h2>
<p>To load any Vulkan core or extension function from the found loader, call <a class="el" href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>. To load functions needed for instance creation, pass <code>NULL</code> as the instance.</p>
<div class="fragment"><div class="line">PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance)</div><div class="line"> <a class="code" href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>(NULL, <span class="stringliteral">&quot;vkCreateInstance&quot;</span>);</div></div><!-- fragment --><p>Once you have created an instance, you can load from it all other Vulkan core functions and functions from any instance extensions you enabled.</p>
<div class="fragment"><div class="line">PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice)</div><div class="line"> <a class="code" href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>(instance, <span class="stringliteral">&quot;vkCreateDevice&quot;</span>);</div></div><!-- fragment --><p>This function in turn calls <code>vkGetInstanceProcAddr</code>. If that fails, the function falls back to a platform-specific query of the Vulkan loader (i.e. <code>dlsym</code> or <code>GetProcAddress</code>). If that also fails, the function returns <code>NULL</code>. For more information about <code>vkGetInstanceProcAddr</code>, see the Vulkan documentation.</p>
<div class="fragment"><div class="line">PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance)</div>
<div class="line"> <a class="code" href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>(NULL, <span class="stringliteral">&quot;vkCreateInstance&quot;</span>);</div>
</div><!-- fragment --><p>Once you have created an instance, you can load from it all other Vulkan core functions and functions from any instance extensions you enabled.</p>
<div class="fragment"><div class="line">PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice)</div>
<div class="line"> <a class="code" href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>(instance, <span class="stringliteral">&quot;vkCreateDevice&quot;</span>);</div>
</div><!-- fragment --><p>This function in turn calls <code>vkGetInstanceProcAddr</code>. If that fails, the function falls back to a platform-specific query of the Vulkan loader (i.e. <code>dlsym</code> or <code>GetProcAddress</code>). If that also fails, the function returns <code>NULL</code>. For more information about <code>vkGetInstanceProcAddr</code>, see the Vulkan documentation.</p>
<p>Vulkan also provides <code>vkGetDeviceProcAddr</code> for loading device-specific versions of Vulkan function. This function can be retrieved from an instance with <a class="el" href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>.</p>
<div class="fragment"><div class="line">PFN_vkGetDeviceProcAddr pfnGetDeviceProcAddr = (PFN_vkGetDeviceProcAddr)</div><div class="line"> <a class="code" href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>(instance, <span class="stringliteral">&quot;vkGetDeviceProcAddr&quot;</span>);</div></div><!-- fragment --><p>Device-specific functions may execute a little bit faster, due to not having to dispatch internally based on the device passed to them. For more information about <code>vkGetDeviceProcAddr</code>, see the Vulkan documentation.</p>
<div class="fragment"><div class="line">PFN_vkGetDeviceProcAddr pfnGetDeviceProcAddr = (PFN_vkGetDeviceProcAddr)</div>
<div class="line"> <a class="code" href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>(instance, <span class="stringliteral">&quot;vkGetDeviceProcAddr&quot;</span>);</div>
</div><!-- fragment --><p>Device-specific functions may execute a little bit faster, due to not having to dispatch internally based on the device passed to them. For more information about <code>vkGetDeviceProcAddr</code>, see the Vulkan documentation.</p>
<h1><a class="anchor" id="vulkan_ext"></a>
Querying required Vulkan extensions</h1>
<p>To do anything useful with Vulkan you need to create an instance. If you want to use Vulkan to render to a window, you must enable the instance extensions GLFW requires to create Vulkan surfaces.</p>
<p>To query the instance extensions required, call <a class="el" href="group__vulkan.html#ga1abcbe61033958f22f63ef82008874b1">glfwGetRequiredInstanceExtensions</a>.</p>
<div class="fragment"><div class="line">uint32_t count;</div><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>** extensions = <a class="code" href="group__vulkan.html#ga1abcbe61033958f22f63ef82008874b1">glfwGetRequiredInstanceExtensions</a>(&amp;count);</div></div><!-- fragment --><p>These extensions must all be enabled when creating instances that are going to be passed to <a class="el" href="group__vulkan.html#gaff3823355cdd7e2f3f9f4d9ea9518d92">glfwGetPhysicalDevicePresentationSupport</a> and <a class="el" href="group__vulkan.html#ga1a24536bec3f80b08ead18e28e6ae965">glfwCreateWindowSurface</a>. The set of extensions will vary depending on platform and may also vary depending on graphics drivers and other factors.</p>
<div class="fragment"><div class="line">uint32_t count;</div>
<div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>** extensions = <a class="code" href="group__vulkan.html#ga1abcbe61033958f22f63ef82008874b1">glfwGetRequiredInstanceExtensions</a>(&amp;count);</div>
</div><!-- fragment --><p>These extensions must all be enabled when creating instances that are going to be passed to <a class="el" href="group__vulkan.html#gaff3823355cdd7e2f3f9f4d9ea9518d92">glfwGetPhysicalDevicePresentationSupport</a> and <a class="el" href="group__vulkan.html#ga1a24536bec3f80b08ead18e28e6ae965">glfwCreateWindowSurface</a>. The set of extensions will vary depending on platform and may also vary depending on graphics drivers and other factors.</p>
<p>If it fails it will return <code>NULL</code> and GLFW will not be able to create Vulkan window surfaces. You can still use Vulkan for off-screen rendering and compute work.</p>
<p>If successful the returned array will always include <code>VK_KHR_surface</code>, so if you don't require any additional extensions you can pass this list directly to the <code>VkInstanceCreateInfo</code> struct.</p>
<div class="fragment"><div class="line">VkInstanceCreateInfo ici;</div><div class="line"></div><div class="line">memset(&amp;ici, 0, <span class="keyword">sizeof</span>(ici));</div><div class="line">ici.enabledExtensionCount = count;</div><div class="line">ici.ppEnabledExtensionNames = extensions;</div><div class="line">...</div></div><!-- fragment --><p>Additional extensions may be required by future versions of GLFW. You should check whether any extensions you wish to enable are already in the returned array, as it is an error to specify an extension more than once in the <code>VkInstanceCreateInfo</code> struct.</p>
<div class="fragment"><div class="line">VkInstanceCreateInfo ici;</div>
<div class="line"> </div>
<div class="line">memset(&amp;ici, 0, <span class="keyword">sizeof</span>(ici));</div>
<div class="line">ici.enabledExtensionCount = count;</div>
<div class="line">ici.ppEnabledExtensionNames = extensions;</div>
<div class="line">...</div>
</div><!-- fragment --><p>Additional extensions may be required by future versions of GLFW. You should check whether any extensions you wish to enable are already in the returned array, as it is an error to specify an extension more than once in the <code>VkInstanceCreateInfo</code> struct.</p>
<h1><a class="anchor" id="vulkan_present"></a>
Querying for Vulkan presentation support</h1>
<p>Not every queue family of every Vulkan device can present images to surfaces. To check whether a specific queue family of a physical device supports image presentation without first having to create a window and surface, call <a class="el" href="group__vulkan.html#gaff3823355cdd7e2f3f9f4d9ea9518d92">glfwGetPhysicalDevicePresentationSupport</a>.</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__vulkan.html#gaff3823355cdd7e2f3f9f4d9ea9518d92">glfwGetPhysicalDevicePresentationSupport</a>(instance, physical_device, queue_family_index))</div><div class="line">{</div><div class="line"> <span class="comment">// Queue family supports image presentation</span></div><div class="line">}</div></div><!-- fragment --><p>The <code>VK_KHR_surface</code> extension additionally provides the <code>vkGetPhysicalDeviceSurfaceSupportKHR</code> function, which performs the same test on an existing Vulkan surface.</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (<a class="code" href="group__vulkan.html#gaff3823355cdd7e2f3f9f4d9ea9518d92">glfwGetPhysicalDevicePresentationSupport</a>(instance, physical_device, queue_family_index))</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// Queue family supports image presentation</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>The <code>VK_KHR_surface</code> extension additionally provides the <code>vkGetPhysicalDeviceSurfaceSupportKHR</code> function, which performs the same test on an existing Vulkan surface.</p>
<h1><a class="anchor" id="vulkan_window"></a>
Creating the window</h1>
<p>Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan, there is no need to create a context. You can disable context creation with the <a class="el" href="window_guide.html#GLFW_CLIENT_API_hint">GLFW_CLIENT_API</a> hint.</p>
<div class="fragment"><div class="line"><a class="code" href="group__window.html#ga7d9c8c62384b1e2821c4dc48952d2033">glfwWindowHint</a>(<a class="code" href="group__window.html#ga649309cf72a3d3de5b1348ca7936c95b">GLFW_CLIENT_API</a>, <a class="code" href="glfw3_8h.html#a8f6dcdc968d214ff14779564f1389264">GLFW_NO_API</a>);</div><div class="line"><a class="code" href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window = <a class="code" href="group__window.html#ga5c336fddf2cbb5b92f65f10fb6043344">glfwCreateWindow</a>(640, 480, <span class="stringliteral">&quot;Window Title&quot;</span>, NULL, NULL);</div></div><!-- fragment --><p>See <a class="el" href="context_guide.html#context_less">Windows without contexts</a> for more information.</p>
<div class="fragment"><div class="line"><a class="code" href="group__window.html#ga7d9c8c62384b1e2821c4dc48952d2033">glfwWindowHint</a>(<a class="code" href="group__window.html#ga649309cf72a3d3de5b1348ca7936c95b">GLFW_CLIENT_API</a>, <a class="code" href="glfw3_8h.html#a8f6dcdc968d214ff14779564f1389264">GLFW_NO_API</a>);</div>
<div class="line"><a class="code" href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window = <a class="code" href="group__window.html#ga5c336fddf2cbb5b92f65f10fb6043344">glfwCreateWindow</a>(640, 480, <span class="stringliteral">&quot;Window Title&quot;</span>, NULL, NULL);</div>
</div><!-- fragment --><p>See <a class="el" href="context_guide.html#context_less">Windows without contexts</a> for more information.</p>
<h1><a class="anchor" id="vulkan_surface"></a>
Creating a Vulkan window surface</h1>
<p>You can create a Vulkan surface (as defined by the <code>VK_KHR_surface</code> extension) for a GLFW window with <a class="el" href="group__vulkan.html#ga1a24536bec3f80b08ead18e28e6ae965">glfwCreateWindowSurface</a>.</p>
<div class="fragment"><div class="line">VkSurfaceKHR surface;</div><div class="line">VkResult err = <a class="code" href="group__vulkan.html#ga1a24536bec3f80b08ead18e28e6ae965">glfwCreateWindowSurface</a>(instance, window, NULL, &amp;surface);</div><div class="line"><span class="keywordflow">if</span> (err)</div><div class="line">{</div><div class="line"> <span class="comment">// Window surface creation failed</span></div><div class="line">}</div></div><!-- fragment --><p>If an OpenGL or OpenGL ES context was created on the window, the context has ownership of the presentation on the window and a Vulkan surface cannot be created.</p>
<div class="fragment"><div class="line">VkSurfaceKHR surface;</div>
<div class="line">VkResult err = <a class="code" href="group__vulkan.html#ga1a24536bec3f80b08ead18e28e6ae965">glfwCreateWindowSurface</a>(instance, window, NULL, &amp;surface);</div>
<div class="line"><span class="keywordflow">if</span> (err)</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// Window surface creation failed</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>If an OpenGL or OpenGL ES context was created on the window, the context has ownership of the presentation on the window and a Vulkan surface cannot be created.</p>
<p>It is your responsibility to destroy the surface. GLFW does not destroy it for you. Call <code>vkDestroySurfaceKHR</code> function from the same extension to destroy it. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
</div></div><!-- contents -->
</div><!-- PageDoc -->
<div class="ttc" id="aglfw3_8h_html"><div class="ttname"><a href="glfw3_8h.html">glfw3.h</a></div><div class="ttdoc">The header of the GLFW 3 API.</div></div>
<div class="ttc" id="agroup__window_html_ga3c96d80d363e67d13a41b5d1821f3242"><div class="ttname"><a href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a></div><div class="ttdeci">struct GLFWwindow GLFWwindow</div><div class="ttdoc">Opaque window object.</div><div class="ttdef"><b>Definition:</b> glfw3.h:1152</div></div>
<div class="ttc" id="agroup__vulkan_html_ga1abcbe61033958f22f63ef82008874b1"><div class="ttname"><a href="group__vulkan.html#ga1abcbe61033958f22f63ef82008874b1">glfwGetRequiredInstanceExtensions</a></div><div class="ttdeci">const char ** glfwGetRequiredInstanceExtensions(uint32_t *count)</div><div class="ttdoc">Returns the Vulkan instance extensions required by GLFW.</div></div>
<div class="ttc" id="agroup__vulkan_html_ga2e7f30931e02464b5bc8d0d4b6f9fe2b"><div class="ttname"><a href="group__vulkan.html#ga2e7f30931e02464b5bc8d0d4b6f9fe2b">glfwVulkanSupported</a></div><div class="ttdeci">int glfwVulkanSupported(void)</div><div class="ttdoc">Returns whether the Vulkan loader and an ICD have been found.</div></div>
<div class="ttc" id="agroup__vulkan_html_ga1a24536bec3f80b08ead18e28e6ae965"><div class="ttname"><a href="group__vulkan.html#ga1a24536bec3f80b08ead18e28e6ae965">glfwCreateWindowSurface</a></div><div class="ttdeci">VkResult glfwCreateWindowSurface(VkInstance instance, GLFWwindow *window, const VkAllocationCallbacks *allocator, VkSurfaceKHR *surface)</div><div class="ttdoc">Creates a Vulkan surface for the specified window.</div></div>
<div class="ttc" id="aglfw3_8h_html_a8f6dcdc968d214ff14779564f1389264"><div class="ttname"><a href="glfw3_8h.html#a8f6dcdc968d214ff14779564f1389264">GLFW_NO_API</a></div><div class="ttdeci">#define GLFW_NO_API</div><div class="ttdef"><b>Definition:</b> glfw3.h:1004</div></div>
<div class="ttc" id="agroup__window_html_ga649309cf72a3d3de5b1348ca7936c95b"><div class="ttname"><a href="group__window.html#ga649309cf72a3d3de5b1348ca7936c95b">GLFW_CLIENT_API</a></div><div class="ttdeci">#define GLFW_CLIENT_API</div><div class="ttdoc">Context client API hint and attribute.</div><div class="ttdef"><b>Definition:</b> glfw3.h:917</div></div>
<div class="ttc" id="agroup__window_html_ga5c336fddf2cbb5b92f65f10fb6043344"><div class="ttname"><a href="group__window.html#ga5c336fddf2cbb5b92f65f10fb6043344">glfwCreateWindow</a></div><div class="ttdeci">GLFWwindow * glfwCreateWindow(int width, int height, const char *title, GLFWmonitor *monitor, GLFWwindow *share)</div><div class="ttdoc">Creates a window and its associated context.</div></div>
<div class="ttc" id="agroup__window_html_ga7d9c8c62384b1e2821c4dc48952d2033"><div class="ttname"><a href="group__window.html#ga7d9c8c62384b1e2821c4dc48952d2033">glfwWindowHint</a></div><div class="ttdeci">void glfwWindowHint(int hint, int value)</div><div class="ttdoc">Sets the specified window hint to the desired value.</div></div>
<div class="ttc" id="agroup__vulkan_html_gaff3823355cdd7e2f3f9f4d9ea9518d92"><div class="ttname"><a href="group__vulkan.html#gaff3823355cdd7e2f3f9f4d9ea9518d92">glfwGetPhysicalDevicePresentationSupport</a></div><div class="ttdeci">int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily)</div><div class="ttdoc">Returns whether the specified queue family can present images.</div></div>
<div class="ttc" id="agroup__vulkan_html_gadf228fac94c5fd8f12423ec9af9ff1e9"><div class="ttname"><a href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a></div><div class="ttdeci">GLFWvkproc glfwGetInstanceProcAddress(VkInstance instance, const char *procname)</div><div class="ttdoc">Returns the address of the specified Vulkan instance function.</div></div>
<address class="footer">
<p>
Last update on Tue Apr 16 2019 for GLFW 3.3.0
Last update on Mon Jan 20 2020 for GLFW 3.3.2
</p>
</address>
</body>