eu07/maszyna
16
0
Fork 0
mirror of https://github.com/MaSzyna-EU07/maszyna.git synced 2026-07-21 15:59:18 +02:00
Code Issues 124 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

76
ref/glfw/docs/html/intro_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: Introduction to the API</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');
@@ -106,7 +106,7 @@ Initialization and termination</h1>
<li><a class="el" href="group__init.html#ga9f8ffaacf3c269cc48eafbf8b9b71197">glfwGetVersion</a></li>
<li><a class="el" href="group__init.html#ga23d47dc013fce2bf58036da66079a657">glfwGetVersionString</a></li>
<li><a class="el" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a></li>
<li><a class="el" href="group__init.html#gaa5d796c3cf7c1a7f02f845486333fb5f">glfwSetErrorCallback</a></li>
<li><a class="el" href="group__init.html#gaff45816610d53f0b83656092a4034f40">glfwSetErrorCallback</a></li>
<li><a class="el" href="group__init.html#ga110fd1d3f0412822b4f1908c026f724a">glfwInitHint</a></li>
<li><a class="el" href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a></li>
<li><a class="el" href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a></li>
@@ -115,12 +115,17 @@ Initialization and termination</h1>
<h2><a class="anchor" id="intro_init_init"></a>
Initializing GLFW</h2>
<p>The library is initialized with <a class="el" href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a>, which returns <code>GLFW_FALSE</code> if an error occurred.</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (!<a class="code" href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a>())</div><div class="line">{</div><div class="line"> <span class="comment">// Handle initialization failure</span></div><div class="line">}</div></div><!-- fragment --><p>If any part of initialization fails, any parts that succeeded are terminated as if <a class="el" href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a> had been called. The library only needs to be initialized once and additional calls to an already initialized library will return <code>GLFW_TRUE</code> immediately.</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (!<a class="code" href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a>())</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// Handle initialization failure</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>If any part of initialization fails, any parts that succeeded are terminated as if <a class="el" href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a> had been called. The library only needs to be initialized once and additional calls to an already initialized library will return <code>GLFW_TRUE</code> immediately.</p>
<p>Once the library has been successfully initialized, it should be terminated before the application exits. Modern systems are very good at freeing resources allocated by programs that exit, but GLFW sometimes has to change global system settings and these might not be restored without termination.</p>
<h2><a class="anchor" id="init_hints"></a>
Initialization hints</h2>
<p>Initialization hints are set before <a class="el" href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a> and affect how the library behaves until termination. Hints are set with <a class="el" href="group__init.html#ga110fd1d3f0412822b4f1908c026f724a">glfwInitHint</a>.</p>
<div class="fragment"><div class="line"><a class="code" href="group__init.html#ga110fd1d3f0412822b4f1908c026f724a">glfwInitHint</a>(<a class="code" href="group__init.html#gab9c0534709fda03ec8959201da3a9a18">GLFW_JOYSTICK_HAT_BUTTONS</a>, <a class="code" href="group__init.html#gac877fe3b627d21ef3a0a23e0a73ba8c5">GLFW_FALSE</a>);</div></div><!-- fragment --><p>The values you set hints to are never reset by GLFW, but they only take effect during initialization. Once GLFW has been initialized, any values you set will be ignored until the library is terminated and initialized again.</p>
<div class="fragment"><div class="line"><a class="code" href="group__init.html#ga110fd1d3f0412822b4f1908c026f724a">glfwInitHint</a>(<a class="code" href="group__init.html#gab9c0534709fda03ec8959201da3a9a18">GLFW_JOYSTICK_HAT_BUTTONS</a>, <a class="code" href="group__init.html#gac877fe3b627d21ef3a0a23e0a73ba8c5">GLFW_FALSE</a>);</div>
</div><!-- fragment --><p>The values you set hints to are never reset by GLFW, but they only take effect during initialization. Once GLFW has been initialized, any values you set will be ignored until the library is terminated and initialized again.</p>
<p>Some hints are platform specific. These may be set on any platform but they will only affect their specific platform. Other platforms will ignore them. Setting these hints requires no platform specific headers or functions.</p>
<h3><a class="anchor" id="init_hints_shared"></a>
Shared init hints</h3>
@@ -144,27 +149,41 @@ Supported and default values</h3>
<h2><a class="anchor" id="intro_init_terminate"></a>
Terminating GLFW</h2>
<p>Before your application exits, you should terminate the GLFW library if it has been initialized. This is done with <a class="el" href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a>.</p>
<div class="fragment"><div class="line"><a class="code" href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a>();</div></div><!-- fragment --><p>This will destroy any remaining window, monitor and cursor objects, restore any modified gamma ramps, re-enable the screensaver if it had been disabled and free any other resources allocated by GLFW.</p>
<div class="fragment"><div class="line"><a class="code" href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a>();</div>
</div><!-- fragment --><p>This will destroy any remaining window, monitor and cursor objects, restore any modified gamma ramps, re-enable the screensaver if it had been disabled and free any other resources allocated by GLFW.</p>
<p>Once the library is terminated, it is as if it had never been initialized and you will need to initialize it again before being able to use GLFW. If the library was not initialized or had already been terminated, it return immediately.</p>
<h1><a class="anchor" id="error_handling"></a>
Error handling</h1>
<p>Some GLFW functions have return values that indicate an error, but this is often not very helpful when trying to figure out what happened or why it occurred. Other functions have no return value reserved for errors, so error notification needs a separate channel. Finally, far from all GLFW functions have return values.</p>
<p>The last <a class="el" href="group__errors.html">error code</a> for the calling thread can be queried at any time with <a class="el" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a>.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> code = <a class="code" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a>(NULL);</div><div class="line"></div><div class="line"><span class="keywordflow">if</span> (code != <a class="code" href="group__errors.html#gafa30deee5db4d69c4c93d116ed87dbf4">GLFW_NO_ERROR</a>)</div><div class="line"> handle_error(code);</div></div><!-- fragment --><p>If no error has occurred since the last call, <a class="el" href="group__errors.html#gafa30deee5db4d69c4c93d116ed87dbf4">GLFW_NO_ERROR</a> (zero) is returned. The error is cleared before the function returns.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> code = <a class="code" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a>(NULL);</div>
<div class="line"> </div>
<div class="line"><span class="keywordflow">if</span> (code != <a class="code" href="group__errors.html#gafa30deee5db4d69c4c93d116ed87dbf4">GLFW_NO_ERROR</a>)</div>
<div class="line"> handle_error(code);</div>
</div><!-- fragment --><p>If no error has occurred since the last call, <a class="el" href="group__errors.html#gafa30deee5db4d69c4c93d116ed87dbf4">GLFW_NO_ERROR</a> (zero) is returned. The error is cleared before the function returns.</p>
<p>The error code indicates the general category of the error. Some error codes, such as <a class="el" href="group__errors.html#ga2374ee02c177f12e1fa76ff3ed15e14a">GLFW_NOT_INITIALIZED</a> has only a single meaning, whereas others like <a class="el" href="group__errors.html#gad44162d78100ea5e87cdd38426b8c7a1">GLFW_PLATFORM_ERROR</a> are used for many different errors.</p>
<p>GLFW often has more information about an error than its general category. You can retrieve a UTF-8 encoded human-readable description along with the error code. If no error has occurred since the last call, the description is set to <code>NULL</code>.</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>* description;</div><div class="line"><span class="keywordtype">int</span> code = <a class="code" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a>(&amp;description);</div><div class="line"></div><div class="line"><span class="keywordflow">if</span> (description)</div><div class="line"> display_error_message(code, description);</div></div><!-- fragment --><p>The retrieved description string is only valid until the next error occurs. This means you must make a copy of it if you want to keep it.</p>
<p>You can also set an error callback, which will be called each time an error occurs. It is set with <a class="el" href="group__init.html#gaa5d796c3cf7c1a7f02f845486333fb5f">glfwSetErrorCallback</a>.</p>
<div class="fragment"><div class="line"><a class="code" href="group__init.html#gaa5d796c3cf7c1a7f02f845486333fb5f">glfwSetErrorCallback</a>(error_callback);</div></div><!-- fragment --><p>The error callback receives the same error code and human-readable description returned by <a class="el" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a>.</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> error_callback(<span class="keywordtype">int</span> code, <span class="keyword">const</span> <span class="keywordtype">char</span>* description)</div><div class="line">{</div><div class="line"> display_error_message(code, description);</div><div class="line">}</div></div><!-- fragment --><p>The error callback is called after the error is stored, so calling <a class="el" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a> from within the error callback returns the same values as the callback argument.</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>* description;</div>
<div class="line"><span class="keywordtype">int</span> code = <a class="code" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a>(&amp;description);</div>
<div class="line"> </div>
<div class="line"><span class="keywordflow">if</span> (description)</div>
<div class="line"> display_error_message(code, description);</div>
</div><!-- fragment --><p>The retrieved description string is only valid until the next error occurs. This means you must make a copy of it if you want to keep it.</p>
<p>You can also set an error callback, which will be called each time an error occurs. It is set with <a class="el" href="group__init.html#gaff45816610d53f0b83656092a4034f40">glfwSetErrorCallback</a>.</p>
<div class="fragment"><div class="line"><a class="code" href="group__init.html#gaff45816610d53f0b83656092a4034f40">glfwSetErrorCallback</a>(error_callback);</div>
</div><!-- fragment --><p>The error callback receives the same error code and human-readable description returned by <a class="el" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a>.</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> error_callback(<span class="keywordtype">int</span> code, <span class="keyword">const</span> <span class="keywordtype">char</span>* description)</div>
<div class="line">{</div>
<div class="line"> display_error_message(code, description);</div>
<div class="line">}</div>
</div><!-- fragment --><p>The error callback is called after the error is stored, so calling <a class="el" href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a> from within the error callback returns the same values as the callback argument.</p>
<p>The description string passed to the callback is only valid until the error callback returns. This means you must make a copy of it if you want to keep it.</p>
<p><b>Reported errors are never fatal.</b> As long as GLFW was successfully initialized, it will remain initialized and in a safe state until terminated regardless of how many errors occur. If an error occurs during initialization that causes <a class="el" href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a> to fail, any part of the library that was initialized will be safely terminated.</p>
<p>Do not rely on a currently invalid call to generate a specific error, as in the future that same call may generate a different error or become valid.</p>
<h1><a class="anchor" id="coordinate_systems"></a>
Coordinate systems</h1>
<p>GLFW has two primary coordinate systems: the <em>virtual screen</em> and the window <em>content area</em> or <em>content area</em>. Both use the same unit: <em>virtual screen coordinates</em>, or just <em>screen coordinates</em>, which don't necessarily correspond to pixels.</p>
<object type="image/svg+xml" data="spaces.svg" width="90%"></object>
/>
<p><img src="spaces.svg" alt="" width="90%" class="inline"/></p>
<p>Both the virtual screen and the content area coordinate systems have the X-axis pointing to the right and the Y-axis pointing down.</p>
<p>Window and monitor positions are specified as the position of the upper-left corners of their content areas relative to the virtual screen, while cursor positions are specified relative to a window's content area.</p>
<p>Because the origin of the window's content area coordinate system is also the point from which the window position is specified, you can translate content area coordinates to the virtual screen by adding the window position. The window frame, when present, extends out from the content area but does not affect the window position.</p>
@@ -262,10 +281,18 @@ Version management</h1>
<h2><a class="anchor" id="intro_version_compile"></a>
Compile-time version</h2>
<p>The compile-time version of GLFW is provided by the GLFW header with the <code>GLFW_VERSION_MAJOR</code>, <code>GLFW_VERSION_MINOR</code> and <code>GLFW_VERSION_REVISION</code> macros.</p>
<div class="fragment"><div class="line">printf(<span class="stringliteral">&quot;Compiled against GLFW %i.%i.%i\n&quot;</span>,</div><div class="line"> <a class="code" href="group__init.html#ga6337d9ea43b22fc529b2bba066b4a576">GLFW_VERSION_MAJOR</a>,</div><div class="line"> <a class="code" href="group__init.html#gaf80d40f0aea7088ff337606e9c48f7a3">GLFW_VERSION_MINOR</a>,</div><div class="line"> <a class="code" href="group__init.html#gab72ae2e2035d9ea461abc3495eac0502">GLFW_VERSION_REVISION</a>);</div></div><!-- fragment --><h2><a class="anchor" id="intro_version_runtime"></a>
<div class="fragment"><div class="line">printf(<span class="stringliteral">&quot;Compiled against GLFW %i.%i.%i\n&quot;</span>,</div>
<div class="line"> <a class="code" href="group__init.html#ga6337d9ea43b22fc529b2bba066b4a576">GLFW_VERSION_MAJOR</a>,</div>
<div class="line"> <a class="code" href="group__init.html#gaf80d40f0aea7088ff337606e9c48f7a3">GLFW_VERSION_MINOR</a>,</div>
<div class="line"> <a class="code" href="group__init.html#gab72ae2e2035d9ea461abc3495eac0502">GLFW_VERSION_REVISION</a>);</div>
</div><!-- fragment --><h2><a class="anchor" id="intro_version_runtime"></a>
Run-time version</h2>
<p>The run-time version can be retrieved with <a class="el" href="group__init.html#ga9f8ffaacf3c269cc48eafbf8b9b71197">glfwGetVersion</a>, a function that may be called regardless of whether GLFW is initialized.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> major, minor, revision;</div><div class="line"><a class="code" href="group__init.html#ga9f8ffaacf3c269cc48eafbf8b9b71197">glfwGetVersion</a>(&amp;major, &amp;minor, &amp;revision);</div><div class="line"></div><div class="line">printf(<span class="stringliteral">&quot;Running against GLFW %i.%i.%i\n&quot;</span>, major, minor, revision);</div></div><!-- fragment --><h2><a class="anchor" id="intro_version_string"></a>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> major, minor, revision;</div>
<div class="line"><a class="code" href="group__init.html#ga9f8ffaacf3c269cc48eafbf8b9b71197">glfwGetVersion</a>(&amp;major, &amp;minor, &amp;revision);</div>
<div class="line"> </div>
<div class="line">printf(<span class="stringliteral">&quot;Running against GLFW %i.%i.%i\n&quot;</span>, major, minor, revision);</div>
</div><!-- fragment --><h2><a class="anchor" id="intro_version_string"></a>
Version string</h2>
<p>GLFW 3 also provides a compile-time generated version string that describes the version, platform, compiler and any platform-specific compile-time options. This is primarily intended for submitting bug reports, to allow developers to see which code paths are enabled in a binary.</p>
<p>The version string is returned by <a class="el" href="group__init.html#ga23d47dc013fce2bf58036da66079a657">glfwGetVersionString</a>, a function that may be called regardless of whether GLFW is initialized.</p>
@@ -277,11 +304,24 @@ Version string</h2>
<li>Any additional options or APIs</li>
</ul>
<p>For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL back ends, the version string may look something like this:</p>
<div class="fragment"><div class="line">3.0.0 Win32 WGL MinGW</div></div><!-- fragment --> </div></div><!-- PageDoc -->
</div><!-- contents -->
<div class="fragment"><div class="line">3.0.0 Win32 WGL MinGW</div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- PageDoc -->
<div class="ttc" id="agroup__init_html_ga944986b4ec0b928d488141f92982aa18"><div class="ttname"><a href="group__init.html#ga944986b4ec0b928d488141f92982aa18">glfwGetError</a></div><div class="ttdeci">int glfwGetError(const char **description)</div><div class="ttdoc">Returns and clears the last error for the calling thread.</div></div>
<div class="ttc" id="agroup__init_html_gaaae48c0a18607ea4a4ba951d939f0901"><div class="ttname"><a href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a></div><div class="ttdeci">void glfwTerminate(void)</div><div class="ttdoc">Terminates the GLFW library.</div></div>
<div class="ttc" id="agroup__init_html_ga110fd1d3f0412822b4f1908c026f724a"><div class="ttname"><a href="group__init.html#ga110fd1d3f0412822b4f1908c026f724a">glfwInitHint</a></div><div class="ttdeci">void glfwInitHint(int hint, int value)</div><div class="ttdoc">Sets the specified init hint to the desired value.</div></div>
<div class="ttc" id="agroup__init_html_gac877fe3b627d21ef3a0a23e0a73ba8c5"><div class="ttname"><a href="group__init.html#gac877fe3b627d21ef3a0a23e0a73ba8c5">GLFW_FALSE</a></div><div class="ttdeci">#define GLFW_FALSE</div><div class="ttdoc">Zero.</div><div class="ttdef"><b>Definition:</b> glfw3.h:289</div></div>
<div class="ttc" id="agroup__init_html_gaf80d40f0aea7088ff337606e9c48f7a3"><div class="ttname"><a href="group__init.html#gaf80d40f0aea7088ff337606e9c48f7a3">GLFW_VERSION_MINOR</a></div><div class="ttdeci">#define GLFW_VERSION_MINOR</div><div class="ttdoc">The minor version number of the GLFW library.</div><div class="ttdef"><b>Definition:</b> glfw3.h:262</div></div>
<div class="ttc" id="agroup__init_html_gab72ae2e2035d9ea461abc3495eac0502"><div class="ttname"><a href="group__init.html#gab72ae2e2035d9ea461abc3495eac0502">GLFW_VERSION_REVISION</a></div><div class="ttdeci">#define GLFW_VERSION_REVISION</div><div class="ttdoc">The revision number of the GLFW library.</div><div class="ttdef"><b>Definition:</b> glfw3.h:269</div></div>
<div class="ttc" id="agroup__init_html_gab9c0534709fda03ec8959201da3a9a18"><div class="ttname"><a href="group__init.html#gab9c0534709fda03ec8959201da3a9a18">GLFW_JOYSTICK_HAT_BUTTONS</a></div><div class="ttdeci">#define GLFW_JOYSTICK_HAT_BUTTONS</div><div class="ttdoc">Joystick hat buttons init hint.</div><div class="ttdef"><b>Definition:</b> glfw3.h:1083</div></div>
<div class="ttc" id="agroup__init_html_ga317aac130a235ab08c6db0834907d85e"><div class="ttname"><a href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a></div><div class="ttdeci">int glfwInit(void)</div><div class="ttdoc">Initializes the GLFW library.</div></div>
<div class="ttc" id="agroup__init_html_ga6337d9ea43b22fc529b2bba066b4a576"><div class="ttname"><a href="group__init.html#ga6337d9ea43b22fc529b2bba066b4a576">GLFW_VERSION_MAJOR</a></div><div class="ttdeci">#define GLFW_VERSION_MAJOR</div><div class="ttdoc">The major version number of the GLFW library.</div><div class="ttdef"><b>Definition:</b> glfw3.h:255</div></div>
<div class="ttc" id="agroup__init_html_gaff45816610d53f0b83656092a4034f40"><div class="ttname"><a href="group__init.html#gaff45816610d53f0b83656092a4034f40">glfwSetErrorCallback</a></div><div class="ttdeci">GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun callback)</div><div class="ttdoc">Sets the error callback.</div></div>
<div class="ttc" id="agroup__init_html_ga9f8ffaacf3c269cc48eafbf8b9b71197"><div class="ttname"><a href="group__init.html#ga9f8ffaacf3c269cc48eafbf8b9b71197">glfwGetVersion</a></div><div class="ttdeci">void glfwGetVersion(int *major, int *minor, int *rev)</div><div class="ttdoc">Retrieves the version of the GLFW library.</div></div>
<div class="ttc" id="agroup__errors_html_gafa30deee5db4d69c4c93d116ed87dbf4"><div class="ttname"><a href="group__errors.html#gafa30deee5db4d69c4c93d116ed87dbf4">GLFW_NO_ERROR</a></div><div class="ttdeci">#define GLFW_NO_ERROR</div><div class="ttdoc">No error has occurred.</div><div class="ttdef"><b>Definition:</b> glfw3.h:638</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>