<p>GLFW is a free, Open Source, multi-platform library for OpenGL, OpenGL ES and Vulkan application development. It provides a simple, platform-independent API for creating windows, contexts and surfaces, reading input, handling events, etc.</p>
<p>See <aclass="el"href="news.html#news_32">New features in 3.2</a> for release highlights or the <ahref="http://www.glfw.org/changelog.html">version history</a> for details.</p>
<p><aclass="el"href="quick_guide.html">Getting started</a> is a guide for users new to GLFW. It takes you through how to write a small but complete program.</p>
<p>There are guides for each section of the API:</p>
<ul>
<li><aclass="el"href="intro_guide.html">Introduction to the API</a> – initialization, error handling and high-level design</li>
<li><aclass="el"href="window_guide.html">Window guide</a> – creating and working with windows and framebuffers</li>
<li><aclass="el"href="context_guide.html">Context guide</a> – working with OpenGL and OpenGL ES contexts</li>
<li><aclass="el"href="vulkan_guide.html">Vulkan guide</a> - working with Vulkan objects and extensions</li>
<li><aclass="el"href="monitor_guide.html">Monitor guide</a> – enumerating and working with monitors and video modes</li>
<li><aclass="el"href="input_guide.html">Input guide</a> – receiving events, polling and processing input</li>
</ul>
<p>Once you have written a program, see <aclass="el"href="compile_guide.html">Compiling GLFW</a> and <aclass="el"href="build_guide.html">Building applications</a>.</p>
<p>The <ahref="modules.html">reference documentation</a> provides more detailed information about specific functions.</p>
<p><aclass="el"href="moving_guide.html">Moving from GLFW 2 to 3</a> explains what has changed and how to update existing code to use the new API.</p>
<p>There is a section on <aclass="el"href="intro_guide.html#guarantees_limitations">Guarantees and limitations</a> for pointer lifetimes, reentrancy, thread safety, event order and backward and forward compatibility.</p>
<p>The <ahref="http://www.glfw.org/faq.html">FAQ</a> answers many common questions about the design, implementation and use of GLFW.</p>
<p>Finally, <aclass="el"href="compat_guide.html">Standards conformance</a> explains what APIs, standards and protocols GLFW uses and what happens when they are not present on a given machine.</p>
<p>This documentation was generated with Doxygen. The sources for it are available in both the <ahref="http://www.glfw.org/download.html">source distribution</a> and <ahref="https://github.com/glfw/glfw">GitHub repository</a>. </p>
<liclass="level1"><ahref="#clipboard">Clipboard input and output</a></li>
<liclass="level1"><ahref="#path_drop">Path drop input</a></li>
</ul>
</div>
<divclass="textblock"><p>This guide introduces the input related functions of GLFW. For details on a specific function in this category, see the <aclass="el"href="group__input.html">Input reference</a>. There are also guides for the other areas of GLFW.</p>
<ul>
<li><aclass="el"href="intro_guide.html">Introduction to the API</a></li>
<p>GLFW provides many kinds of input. While some can only be polled, like time, or only received via callbacks, like scrolling, there are those that provide both callbacks and polling. Where a callback is provided, that is the recommended way to receive that kind of input. The more you can use callbacks the less time your users' machines will need to spend polling.</p>
<p>All input callbacks receive a window handle. By using the <aclass="el"href="window_guide.html#window_userptr">window user pointer</a>, you can access non-global structures or objects from your callbacks.</p>
<p>To get a better feel for how the various events callbacks behave, run the <code>events</code> test program. It register every callback supported by GLFW and prints out all arguments provided for every event, along with time and sequence information.</p>
<h1><aclass="anchor"id="events"></a>
Event processing</h1>
<p>GLFW needs to communicate regularly with the window system both in order to receive events and to show that the application hasn't locked up. Event processing must be done regularly while you have any windows and is normally done each frame after <aclass="el"href="window_guide.html#buffer_swap">buffer swapping</a>. Even when you have no windows, event polling needs to be done in order to receive monitor connection events.</p>
<p>There are two functions for processing pending events. <aclass="el"href="group__window.html#ga37bd57223967b4211d60ca1a0bf3c832">glfwPollEvents</a>, processes only those events that have already been received and then returns immediately.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__window.html#ga37bd57223967b4211d60ca1a0bf3c832">glfwPollEvents</a>();</div></div><!-- fragment --><p>This is the best choice when rendering continually, like most games do.</p>
<p>If you only need to update the contents of the window when you receive new input, <aclass="el"href="group__window.html#ga554e37d781f0a997656c26b2c56c835e">glfwWaitEvents</a> is a better choice.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__window.html#ga554e37d781f0a997656c26b2c56c835e">glfwWaitEvents</a>();</div></div><!-- fragment --><p>It puts the thread to sleep until at least one event has been received and then processes all received events. This saves a great deal of CPU cycles and is useful for, for example, editing tools. There must be at least one GLFW window for this function to sleep.</p>
<p>If you want to wait for events but have UI elements that need periodic updates, call <aclass="el"href="group__window.html#ga605a178db92f1a7f1a925563ef3ea2cf">glfwWaitEventsTimeout</a>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__window.html#ga605a178db92f1a7f1a925563ef3ea2cf">glfwWaitEventsTimeout</a>(0.7);</div></div><!-- fragment --><p>It puts the thread to sleep until at least one event has been received, or until the specified number of seconds have elapsed. It then processes any received events.</p>
<p>If the main thread is sleeping in <aclass="el"href="group__window.html#ga554e37d781f0a997656c26b2c56c835e">glfwWaitEvents</a>, you can wake it from another thread by posting an empty event to the event queue with <aclass="el"href="group__window.html#gab5997a25187e9fd5c6f2ecbbc8dfd7e9">glfwPostEmptyEvent</a>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__window.html#gab5997a25187e9fd5c6f2ecbbc8dfd7e9">glfwPostEmptyEvent</a>();</div></div><!-- fragment --><p>Do not assume that callbacks will <em>only</em> be called through either of the above functions. While it is necessary to process events in the event queue, some window systems will send some events directly to the application, which in turn causes callbacks to be called outside of regular event processing.</p>
<h1><aclass="anchor"id="input_keyboard"></a>
Keyboard input</h1>
<p>GLFW divides keyboard input into two categories; key events and character events. Key events relate to actual physical keyboard keys, whereas character events relate to the Unicode code points generated by pressing some of them.</p>
<p>Keys and characters do not map 1:1. A single key press may produce several characters, and a single character may require several keys to produce. This may not be the case on your machine, but your users are likely not all using the same keyboard layout, input method or even operating system as you.</p>
<h2><aclass="anchor"id="input_key"></a>
Key input</h2>
<p>If you wish to be notified when a physical key is pressed or released or when it repeats, set a key callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#ga7e496507126f35ea72f01b2e6ef6d155">glfwSetKeyCallback</a>(window, key_callback);</div></div><!-- fragment --><p>The callback function receives the <aclass="el"href="group__keys.html">keyboard key</a>, platform-specific scancode, key action and <aclass="el"href="group__mods.html">modifier bits</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> key_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">int</span> key, <spanclass="keywordtype">int</span> scancode, <spanclass="keywordtype">int</span> action, <spanclass="keywordtype">int</span> mods)</div><divclass="line">{</div><divclass="line"><spanclass="keywordflow">if</span> (key == <aclass="code"href="group__keys.html#gabf48fcc3afbe69349df432b470c96ef2">GLFW_KEY_E</a>&& action == <aclass="code"href="group__input.html#ga2485743d0b59df3791c45951c4195265">GLFW_PRESS</a>)</div><divclass="line"> activate_airship();</div><divclass="line">}</div></div><!-- fragment --><p>The action is one of <code>GLFW_PRESS</code>, <code>GLFW_REPEAT</code> or <code>GLFW_RELEASE</code>. The key will be <code>GLFW_KEY_UNKNOWN</code> if GLFW lacks a key token for it, for example <em>E-mail</em> and <em>Play</em> keys.</p>
<p>The scancode is unique for every key, regardless of whether it has a key token. Scancodes are platform-specific but consistent over time, so keys will have different scancodes depending on the platform but they are safe to save to disk.</p>
<p>Key states for <aclass="el"href="group__keys.html">named keys</a> are also saved in per-window state arrays that can be polled with <aclass="el"href="group__input.html#gadd341da06bc8d418b4dc3a3518af9ad2">glfwGetKey</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> state = <aclass="code"href="group__input.html#gadd341da06bc8d418b4dc3a3518af9ad2">glfwGetKey</a>(window, <aclass="code"href="group__keys.html#gabf48fcc3afbe69349df432b470c96ef2">GLFW_KEY_E</a>);</div><divclass="line"><spanclass="keywordflow">if</span> (state == <aclass="code"href="group__input.html#ga2485743d0b59df3791c45951c4195265">GLFW_PRESS</a>)</div><divclass="line"> activate_airship();</div></div><!-- fragment --><p>The returned state is one of <code>GLFW_PRESS</code> or <code>GLFW_RELEASE</code>.</p>
<p>This function only returns cached key event state. It does not poll the system for the current state of the key.</p>
<p>Whenever you poll state, you risk missing the state change you are looking for. If a pressed key is released again before you poll its state, you will have missed the key press. The recommended solution for this is to use a key callback, but there is also the <code>GLFW_STICKY_KEYS</code> input mode.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaa92336e173da9c8834558b54ee80563b">glfwSetInputMode</a>(window, <aclass="code"href="glfw3_8h.html#ae3bbe2315b7691ab088159eb6c9110fc">GLFW_STICKY_KEYS</a>, 1);</div></div><!-- fragment --><p>When sticky keys mode is enabled, the pollable state of a key will remain <code>GLFW_PRESS</code> until the state of that key is polled with <aclass="el"href="group__input.html#gadd341da06bc8d418b4dc3a3518af9ad2">glfwGetKey</a>. Once it has been polled, if a key release event had been processed in the meantime, the state will reset to <code>GLFW_RELEASE</code>, otherwise it will remain <code>GLFW_PRESS</code>.</p>
<p>The <code>GLFW_KEY_LAST</code> constant holds the highest value of any <aclass="el"href="group__keys.html">named key</a>.</p>
<h2><aclass="anchor"id="input_char"></a>
Text input</h2>
<p>GLFW supports text input in the form of a stream of <ahref="https://en.wikipedia.org/wiki/Unicode">Unicode code points</a>, as produced by the operating system text input system. Unlike key input, text input obeys keyboard layouts and modifier keys and supports composing characters using <ahref="https://en.wikipedia.org/wiki/Dead_key">dead keys</a>. Once received, you can encode the code points into <ahref="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a> or any other encoding you prefer.</p>
<p>Because an <code>unsigned int</code> is 32 bits long on all platforms supported by GLFW, you can treat the code point argument as native endian <ahref="https://en.wikipedia.org/wiki/UTF-32">UTF-32</a>.</p>
<p>There are two callbacks for receiving Unicode code points. If you wish to offer regular text input, set a character callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#ga556239421c6a5a243c66fca28da9f742">glfwSetCharCallback</a>(window, character_callback);</div></div><!-- fragment --><p>The callback function receives Unicode code points for key events that would have led to regular text input and generally behaves as a standard text field on that platform.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> character_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">unsigned</span><spanclass="keywordtype">int</span> codepoint)</div><divclass="line">{</div><divclass="line">}</div></div><!-- fragment --><p>If you wish to receive even those Unicode code points generated with modifier key combinations that a plain text field would ignore, or just want to know exactly what modifier keys were used, set a character with modifiers callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#ga3f55ef5dc03a374e567f068b13c94afc">glfwSetCharModsCallback</a>(window, charmods_callback);</div></div><!-- fragment --><p>The callback function receives Unicode code points and <aclass="el"href="group__mods.html">modifier bits</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> charmods_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">unsigned</span><spanclass="keywordtype">int</span> codepoint, <spanclass="keywordtype">int</span> mods)</div><divclass="line">{</div><divclass="line">}</div></div><!-- fragment --><h2><aclass="anchor"id="input_key_name"></a>
Key names</h2>
<p>If you wish to refer to keys by name, you can query the keyboard layout dependent name of printable keys with <aclass="el"href="group__input.html#ga237a182e5ec0b21ce64543f3b5e7e2be">glfwGetKeyName</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keyword">const</span><spanclass="keywordtype">char</span>* key_name = <aclass="code"href="group__input.html#ga237a182e5ec0b21ce64543f3b5e7e2be">glfwGetKeyName</a>(<aclass="code"href="group__keys.html#gaa06a712e6202661fc03da5bdb7b6e545">GLFW_KEY_W</a>, 0);</div><divclass="line">show_tutorial_hint(<spanclass="stringliteral">"Press %s to move forward"</span>, key_name);</div></div><!-- fragment --><p>This function can handle both <aclass="el"href="input_guide.html#input_key">keys and scancodes</a>. If the specified key is <code>GLFW_KEY_UNKNOWN</code> then the scancode is used, otherwise it is ignored. This matches the behavior of the key callback, meaning the callback arguments can always be passed unmodified to this function.</p>
<h1><aclass="anchor"id="input_mouse"></a>
Mouse input</h1>
<p>Mouse input comes in many forms, including cursor motion, button presses and scrolling offsets. The cursor appearance can also be changed, either to a custom image or a standard cursor shape from the system theme.</p>
<h2><aclass="anchor"id="cursor_pos"></a>
Cursor position</h2>
<p>If you wish to be notified when the cursor moves over the window, set a cursor position callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#ga7dad39486f2c7591af7fb25134a2501d">glfwSetCursorPosCallback</a>(window, cursor_pos_callback);</div></div><!-- fragment --><p>The callback functions receives the cursor position, measured in screen coordinates but relative to the top-left corner of the window client area. On platforms that provide it, the full sub-pixel cursor position is passed on.</p>
<divclass="fragment"><divclass="line"><spanclass="keyword">static</span><spanclass="keywordtype">void</span> cursor_position_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">double</span> xpos, <spanclass="keywordtype">double</span> ypos)</div><divclass="line">{</div><divclass="line">}</div></div><!-- fragment --><p>The cursor position is also saved per-window and can be polled with <aclass="el"href="group__input.html#ga01d37b6c40133676b9cea60ca1d7c0cc">glfwGetCursorPos</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">double</span> xpos, ypos;</div><divclass="line"><aclass="code"href="group__input.html#ga01d37b6c40133676b9cea60ca1d7c0cc">glfwGetCursorPos</a>(window, &xpos, &ypos);</div></div><!-- fragment --><h2><aclass="anchor"id="cursor_mode"></a>
Cursor modes</h2>
<p>The <code>GLFW_CURSOR</code> input mode provides several cursor modes for special forms of mouse motion input. By default, the cursor mode is <code>GLFW_CURSOR_NORMAL</code>, meaning the regular arrow cursor (or another cursor set with <aclass="el"href="group__input.html#gad3b4f38c8d5dae036bc8fa959e18343e">glfwSetCursor</a>) is used and cursor motion is not limited.</p>
<p>If you wish to implement mouse motion based camera controls or other input schemes that require unlimited mouse movement, set the cursor mode to <code>GLFW_CURSOR_DISABLED</code>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaa92336e173da9c8834558b54ee80563b">glfwSetInputMode</a>(window, <aclass="code"href="glfw3_8h.html#aade31da5b884a84a7625c6b059b9132c">GLFW_CURSOR</a>, <aclass="code"href="glfw3_8h.html#a2315b99a329ce53e6a13a9d46fd5ca88">GLFW_CURSOR_DISABLED</a>);</div></div><!-- fragment --><p>This will hide the cursor and lock it to the specified window. GLFW will then take care of all the details of cursor re-centering and offset calculation and providing the application with a virtual cursor position. This virtual position is provided normally via both the cursor position callback and through polling.</p>
<dlclass="section note"><dt>Note</dt><dd>You should not implement your own version of this functionality using other features of GLFW. It is not supported and will not work as robustly as <code>GLFW_CURSOR_DISABLED</code>.</dd></dl>
<p>If you just wish the cursor to become hidden when it is over a window, set the cursor mode to <code>GLFW_CURSOR_HIDDEN</code>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaa92336e173da9c8834558b54ee80563b">glfwSetInputMode</a>(window, <aclass="code"href="glfw3_8h.html#aade31da5b884a84a7625c6b059b9132c">GLFW_CURSOR</a>, <aclass="code"href="glfw3_8h.html#ac4d5cb9d78de8573349c58763d53bf11">GLFW_CURSOR_HIDDEN</a>);</div></div><!-- fragment --><p>This mode puts no limit on the motion of the cursor.</p>
<p>To exit out of either of these special modes, restore the <code>GLFW_CURSOR_NORMAL</code> cursor mode.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaa92336e173da9c8834558b54ee80563b">glfwSetInputMode</a>(window, <aclass="code"href="glfw3_8h.html#aade31da5b884a84a7625c6b059b9132c">GLFW_CURSOR</a>, <aclass="code"href="glfw3_8h.html#ae04dd25c8577e19fa8c97368561f6c68">GLFW_CURSOR_NORMAL</a>);</div></div><!-- fragment --><h2><aclass="anchor"id="cursor_object"></a>
Cursor objects</h2>
<p>GLFW supports creating both custom and system theme cursor images, encapsulated as <aclass="el"href="glfw3_8h.html#a89261ae18c75e863aaf2656ecdd238f4">GLFWcursor</a> objects. They are created with <aclass="el"href="group__input.html#gafca356935e10135016aa49ffa464c355">glfwCreateCursor</a> or <aclass="el"href="group__input.html#gaa65f416d03ebbbb5b8db71a489fcb894">glfwCreateStandardCursor</a> and destroyed with <aclass="el"href="group__input.html#ga81b952cd1764274d0db7fb3c5a79ba6a">glfwDestroyCursor</a>, or <aclass="el"href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a>, if any remain.</p>
<h3><aclass="anchor"id="cursor_custom"></a>
Custom cursor creation</h3>
<p>A custom cursor is created with <aclass="el"href="group__input.html#gafca356935e10135016aa49ffa464c355">glfwCreateCursor</a>, which returns a handle to the created cursor object. For example, this creates a 16x16 white square cursor with the hot-spot in the upper-left corner:</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">unsigned</span><spanclass="keywordtype">char</span> pixels[16 * 16 * 4];</div><divclass="line">memset(pixels, 0xff, <spanclass="keyword">sizeof</span>(pixels));</div><divclass="line"></div><divclass="line"><aclass="code"href="structGLFWimage.html">GLFWimage</a> image;</div><divclass="line">image.<aclass="code"href="structGLFWimage.html#af6a71cc999fe6d3aea31dd7e9687d835">width</a> = 16;</div><divclass="line">image.<aclass="code"href="structGLFWimage.html#a0b7d95368f0c80d5e5c9875057c7dbec">height</a> = 16;</div><divclass="line">image.<aclass="code"href="structGLFWimage.html#a0c532a5c2bb715555279b7817daba0fb">pixels</a> = pixels;</div><divclass="line"></div><divclass="line"><aclass="code"href="glfw3_8h.html#a89261ae18c75e863aaf2656ecdd238f4">GLFWcursor</a>* cursor = <aclass="code"href="group__input.html#gafca356935e10135016aa49ffa464c355">glfwCreateCursor</a>(&image, 0, 0);</div></div><!-- fragment --><p>If cursor creation fails, <code>NULL</code> will be returned, so it is necessary to check the return value.</p>
<p>The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits per channel. The pixels are arranged canonically as sequential rows, starting from the top-left corner.</p>
<h3><aclass="anchor"id="cursor_standard"></a>
Standard cursor creation</h3>
<p>A cursor with a <aclass="el"href="group__shapes.html">standard shape</a> from the current system cursor theme can be can be created with <aclass="el"href="group__input.html#gaa65f416d03ebbbb5b8db71a489fcb894">glfwCreateStandardCursor</a>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="glfw3_8h.html#a89261ae18c75e863aaf2656ecdd238f4">GLFWcursor</a>* cursor = <aclass="code"href="group__input.html#gaa65f416d03ebbbb5b8db71a489fcb894">glfwCreateStandardCursor</a>(<aclass="code"href="group__shapes.html#gabb3eb0109f11bb808fc34659177ca962">GLFW_HRESIZE_CURSOR</a>);</div></div><!-- fragment --><p>These cursor objects behave in the exact same way as those created with <aclass="el"href="group__input.html#gafca356935e10135016aa49ffa464c355">glfwCreateCursor</a> except that the system cursor theme provides the actual image.</p>
<h3><aclass="anchor"id="cursor_destruction"></a>
Cursor destruction</h3>
<p>When a cursor is no longer needed, destroy it with <aclass="el"href="group__input.html#ga81b952cd1764274d0db7fb3c5a79ba6a">glfwDestroyCursor</a>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#ga81b952cd1764274d0db7fb3c5a79ba6a">glfwDestroyCursor</a>(cursor);</div></div><!-- fragment --><p>Cursor destruction always succeeds. All cursors remaining when <aclass="el"href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a> is called are destroyed as well.</p>
<h3><aclass="anchor"id="cursor_set"></a>
Cursor setting</h3>
<p>A cursor can be set as current for a window with <aclass="el"href="group__input.html#gad3b4f38c8d5dae036bc8fa959e18343e">glfwSetCursor</a>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gad3b4f38c8d5dae036bc8fa959e18343e">glfwSetCursor</a>(window, cursor);</div></div><!-- fragment --><p>Once set, the cursor image will be used as long as the system cursor is over the client area of the window and the <aclass="el"href="input_guide.html#cursor_mode">cursor mode</a> is set to <code>GLFW_CURSOR_NORMAL</code>.</p>
<p>A single cursor may be set for any number of windows.</p>
<p>To remove a cursor from a window, set the cursor of that window to <code>NULL</code>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gad3b4f38c8d5dae036bc8fa959e18343e">glfwSetCursor</a>(window, NULL);</div></div><!-- fragment --><p>When a cursor is destroyed, it is removed from any window where it is set. This does not affect the cursor modes of those windows.</p>
<h2><aclass="anchor"id="cursor_enter"></a>
Cursor enter/leave events</h2>
<p>If you wish to be notified when the cursor enters or leaves the client area of a window, set a cursor enter/leave callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaa299c41dd0a3d171d166354e01279e04">glfwSetCursorEnterCallback</a>(window, cursor_enter_callback);</div></div><!-- fragment --><p>The callback function receives the new classification of the cursor.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> cursor_enter_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">int</span> entered)</div><divclass="line">{</div><divclass="line"><spanclass="keywordflow">if</span> (entered)</div><divclass="line"> {</div><divclass="line"><spanclass="comment">// The cursor entered the client area of the window</span></div><divclass="line"> }</div><divclass="line"><spanclass="keywordflow">else</span></div><divclass="line"> {</div><divclass="line"><spanclass="comment">// The cursor left the client area of the window</span></div><divclass="line"> }</div><divclass="line">}</div></div><!-- fragment --><h2><aclass="anchor"id="input_mouse_button"></a>
Mouse button input</h2>
<p>If you wish to be notified when a mouse button is pressed or released, set a mouse button callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaef49b72d84d615bca0a6ed65485e035d">glfwSetMouseButtonCallback</a>(window, mouse_button_callback);</div></div><!-- fragment --><p>The callback function receives the <aclass="el"href="group__buttons.html">mouse button</a>, button action and <aclass="el"href="group__mods.html">modifier bits</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> mouse_button_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">int</span> button, <spanclass="keywordtype">int</span> action, <spanclass="keywordtype">int</span> mods)</div><divclass="line">{</div><divclass="line"><spanclass="keywordflow">if</span> (button == <aclass="code"href="group__buttons.html#ga3e2f2cf3c4942df73cc094247d275e74">GLFW_MOUSE_BUTTON_RIGHT</a>&& action == <aclass="code"href="group__input.html#ga2485743d0b59df3791c45951c4195265">GLFW_PRESS</a>)</div><divclass="line"> popup_menu();</div><divclass="line">}</div></div><!-- fragment --><p>The action is one of <code>GLFW_PRESS</code> or <code>GLFW_RELEASE</code>.</p>
<p>Mouse button states for <aclass="el"href="group__buttons.html">named buttons</a> are also saved in per-window state arrays that can be polled with <aclass="el"href="group__input.html#gac1473feacb5996c01a7a5a33b5066704">glfwGetMouseButton</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> state = <aclass="code"href="group__input.html#gac1473feacb5996c01a7a5a33b5066704">glfwGetMouseButton</a>(window, <aclass="code"href="group__buttons.html#gaf37100431dcd5082d48f95ee8bc8cd56">GLFW_MOUSE_BUTTON_LEFT</a>);</div><divclass="line"><spanclass="keywordflow">if</span> (state == <aclass="code"href="group__input.html#ga2485743d0b59df3791c45951c4195265">GLFW_PRESS</a>)</div><divclass="line"> upgrade_cow();</div></div><!-- fragment --><p>The returned state is one of <code>GLFW_PRESS</code> or <code>GLFW_RELEASE</code>.</p>
<p>This function only returns cached mouse button event state. It does not poll the system for the current state of the mouse button.</p>
<p>Whenever you poll state, you risk missing the state change you are looking for. If a pressed mouse button is released again before you poll its state, you will have missed the button press. The recommended solution for this is to use a mouse button callback, but there is also the <code>GLFW_STICKY_MOUSE_BUTTONS</code> input mode.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaa92336e173da9c8834558b54ee80563b">glfwSetInputMode</a>(window, <aclass="code"href="glfw3_8h.html#a4d7ce8ce71030c3b04e2b78145bc59d1">GLFW_STICKY_MOUSE_BUTTONS</a>, 1);</div></div><!-- fragment --><p>When sticky mouse buttons mode is enabled, the pollable state of a mouse button will remain <code>GLFW_PRESS</code> until the state of that button is polled with <aclass="el"href="group__input.html#gac1473feacb5996c01a7a5a33b5066704">glfwGetMouseButton</a>. Once it has been polled, if a mouse button release event had been processed in the meantime, the state will reset to <code>GLFW_RELEASE</code>, otherwise it will remain <code>GLFW_PRESS</code>.</p>
<p>The <code>GLFW_MOUSE_BUTTON_LAST</code> constant holds the highest value of any <aclass="el"href="group__buttons.html">named button</a>.</p>
<h2><aclass="anchor"id="scrolling"></a>
Scroll input</h2>
<p>If you wish to be notified when the user scrolls, whether with a mouse wheel or touchpad gesture, set a scroll callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gacf02eb10504352f16efda4593c3ce60e">glfwSetScrollCallback</a>(window, scroll_callback);</div></div><!-- fragment --><p>The callback function receives two-dimensional scroll offsets.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> scroll_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">double</span> xoffset, <spanclass="keywordtype">double</span> yoffset)</div><divclass="line">{</div><divclass="line">}</div></div><!-- fragment --><p>A simple mouse wheel, being vertical, provides offsets along the Y-axis.</p>
<h1><aclass="anchor"id="joystick"></a>
Joystick input</h1>
<p>The joystick functions expose connected joysticks and controllers, with both referred to as joysticks. It supports up to sixteen joysticks, ranging from <code>GLFW_JOYSTICK_1</code>, <code>GLFW_JOYSTICK_2</code> up to <code>GLFW_JOYSTICK_LAST</code>. You can test whether a <aclass="el"href="group__joysticks.html">joystick</a> is present with <aclass="el"href="group__input.html#gaffcbd9ac8ee737fcdd25475123a3c790">glfwJoystickPresent</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> present = <aclass="code"href="group__input.html#gaffcbd9ac8ee737fcdd25475123a3c790">glfwJoystickPresent</a>(<aclass="code"href="group__joysticks.html#ga34a0443d059e9f22272cd4669073f73d">GLFW_JOYSTICK_1</a>);</div></div><!-- fragment --><p>When GLFW is initialized, detected joysticks are added to to the beginning of the array, starting with <code>GLFW_JOYSTICK_1</code>. Once a joystick is detected, it keeps its assigned index until it is disconnected, so as joysticks are connected and disconnected, they will become spread out.</p>
<p>Joystick state is updated as needed when a joystick function is called and does not require a window to be created or <aclass="el"href="group__window.html#ga37bd57223967b4211d60ca1a0bf3c832">glfwPollEvents</a> or <aclass="el"href="group__window.html#ga554e37d781f0a997656c26b2c56c835e">glfwWaitEvents</a> to be called.</p>
<h2><aclass="anchor"id="joystick_axis"></a>
Joystick axis states</h2>
<p>The positions of all axes of a joystick are returned by <aclass="el"href="group__input.html#ga6271d46a5901ec2c99601ccf4dd14731">glfwGetJoystickAxes</a>. See the reference documentation for the lifetime of the returned array.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> count;</div><divclass="line"><spanclass="keyword">const</span><spanclass="keywordtype">float</span>* axes = <aclass="code"href="group__input.html#ga6271d46a5901ec2c99601ccf4dd14731">glfwGetJoystickAxes</a>(<aclass="code"href="group__joysticks.html#ga34a0443d059e9f22272cd4669073f73d">GLFW_JOYSTICK_1</a>, &count);</div></div><!-- fragment --><p>Each element in the returned array is a value between -1.0 and 1.0.</p>
<h2><aclass="anchor"id="joystick_button"></a>
Joystick button states</h2>
<p>The states of all buttons of a joystick are returned by <aclass="el"href="group__input.html#gace54cd930dcd502e118fe4021384ce1b">glfwGetJoystickButtons</a>. See the reference documentation for the lifetime of the returned array.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> count;</div><divclass="line"><spanclass="keyword">const</span><spanclass="keywordtype">unsigned</span><spanclass="keywordtype">char</span>* axes = <aclass="code"href="group__input.html#gace54cd930dcd502e118fe4021384ce1b">glfwGetJoystickButtons</a>(<aclass="code"href="group__joysticks.html#ga34a0443d059e9f22272cd4669073f73d">GLFW_JOYSTICK_1</a>, &count);</div></div><!-- fragment --><p>Each element in the returned array is either <code>GLFW_PRESS</code> or <code>GLFW_RELEASE</code>.</p>
<h2><aclass="anchor"id="joystick_name"></a>
Joystick name</h2>
<p>The human-readable, UTF-8 encoded name of a joystick is returned by <aclass="el"href="group__input.html#gac8d7f6107e05cfd106cfba973ab51e19">glfwGetJoystickName</a>. See the reference documentation for the lifetime of the returned string.</p>
<divclass="fragment"><divclass="line"><spanclass="keyword">const</span><spanclass="keywordtype">char</span>* name = <aclass="code"href="group__input.html#gac8d7f6107e05cfd106cfba973ab51e19">glfwGetJoystickName</a>(<aclass="code"href="group__joysticks.html#ga34a0443d059e9f22272cd4669073f73d">GLFW_JOYSTICK_1</a>);</div></div><!-- fragment --><p>Joystick names are not guaranteed to be unique. Two joysticks of the same model and make may have the same name. Only the <aclass="el"href="group__joysticks.html">joystick token</a> is guaranteed to be unique, and only until that joystick is disconnected.</p>
<h2><aclass="anchor"id="joystick_event"></a>
Joystick configuration changes</h2>
<p>If you wish to be notified when a joystick is connected or disconnected, set a joystick callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gab1dc8379f1b82bb660a6b9c9fa06ca07">glfwSetJoystickCallback</a>(joystick_callback);</div></div><!-- fragment --><p>The callback function receives the ID of the joystick that has been connected and disconnected and the event that occurred.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> joystick_callback(<spanclass="keywordtype">int</span> joy, <spanclass="keywordtype">int</span> event)</div><divclass="line">{</div><divclass="line"><spanclass="keywordflow">if</span> (event == <aclass="code"href="glfw3_8h.html#abe11513fd1ffbee5bb9b173f06028b9e">GLFW_CONNECTED</a>)</div><divclass="line"> {</div><divclass="line"><spanclass="comment">// The joystick was connected</span></div><divclass="line"> }</div><divclass="line"><spanclass="keywordflow">else</span><spanclass="keywordflow">if</span> (event == <aclass="code"href="glfw3_8h.html#aab64b25921ef21d89252d6f0a71bfc32">GLFW_DISCONNECTED</a>)</div><divclass="line"> {</div><divclass="line"><spanclass="comment">// The joystick was disconnected</span></div><divclass="line"> }</div><divclass="line">}</div></div><!-- fragment --><h1><aclass="anchor"id="time"></a>
Time input</h1>
<p>GLFW provides high-resolution time input, in seconds, with <aclass="el"href="group__input.html#gaa6cf4e7a77158a3b8fd00328b1720a4a">glfwGetTime</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">double</span> seconds = <aclass="code"href="group__input.html#gaa6cf4e7a77158a3b8fd00328b1720a4a">glfwGetTime</a>();</div></div><!-- fragment --><p>It returns the number of seconds since the timer was started when the library was initialized with <aclass="el"href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a>. The platform-specific time sources used usually have micro- or nanosecond resolution.</p>
<p>You can modify the reference time with <aclass="el"href="group__input.html#gaf59589ef6e8b8c8b5ad184b25afd4dc0">glfwSetTime</a>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaf59589ef6e8b8c8b5ad184b25afd4dc0">glfwSetTime</a>(4.0);</div></div><!-- fragment --><p>This sets the timer to the specified time, in seconds.</p>
<p>You can also access the raw timer value, measured in 1 / frequency seconds, with <aclass="el"href="group__input.html#ga09b2bd37d328e0b9456c7ec575cc26aa">glfwGetTimerValue</a>.</p>
<divclass="fragment"><divclass="line">uint64_t value = <aclass="code"href="group__input.html#ga09b2bd37d328e0b9456c7ec575cc26aa">glfwGetTimerValue</a>();</div></div><!-- fragment --><p>The frequency of the raw timer varies depending on what time sources are available on the machine. You can query its frequency, in Hz, with <aclass="el"href="group__input.html#ga3289ee876572f6e91f06df3a24824443">glfwGetTimerFrequency</a>.</p>
<divclass="fragment"><divclass="line">uint64_t freqency = <aclass="code"href="group__input.html#ga3289ee876572f6e91f06df3a24824443">glfwGetTimerFrequency</a>();</div></div><!-- fragment --><h1><aclass="anchor"id="clipboard"></a>
Clipboard input and output</h1>
<p>If the system clipboard contains a UTF-8 encoded string or if it can be converted to one, you can retrieve it with <aclass="el"href="group__input.html#ga5aba1d704d9ab539282b1fbe9f18bb94">glfwGetClipboardString</a>. See the reference documentation for the lifetime of the returned string.</p>
<divclass="fragment"><divclass="line"><spanclass="keyword">const</span><spanclass="keywordtype">char</span>* text = <aclass="code"href="group__input.html#ga5aba1d704d9ab539282b1fbe9f18bb94">glfwGetClipboardString</a>(window);</div><divclass="line"><spanclass="keywordflow">if</span> (text)</div><divclass="line"> insert_text(text);</div></div><!-- fragment --><p>If the clipboard is empty or if its contents could not be converted, <code>NULL</code> is returned.</p>
<p>The contents of the system clipboard can be set to a UTF-8 encoded string with <aclass="el"href="group__input.html#gaba1f022c5eb07dfac421df34cdcd31dd">glfwSetClipboardString</a>.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#gaba1f022c5eb07dfac421df34cdcd31dd">glfwSetClipboardString</a>(window, <spanclass="stringliteral">"A string with words in it"</span>);</div></div><!-- fragment --><p>The clipboard functions take a window handle argument because some window systems require a window to communicate with the system clipboard. Any valid window may be used.</p>
<h1><aclass="anchor"id="path_drop"></a>
Path drop input</h1>
<p>If you wish to receive the paths of files and/or directories dropped on a window, set a file drop callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__input.html#ga41291bf15dd3ff564b3143aa6dc74a4b">glfwSetDropCallback</a>(window, drop_callback);</div></div><!-- fragment --><p>The callback function receives an array of paths encoded as UTF-8.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> drop_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">int</span> count, <spanclass="keyword">const</span><spanclass="keywordtype">char</span>** paths)</div><divclass="line">{</div><divclass="line"><spanclass="keywordtype">int</span> i;</div><divclass="line"><spanclass="keywordflow">for</span> (i = 0; i < count; i++)</div><divclass="line"> handle_dropped_file(paths[i]);</div><divclass="line">}</div></div><!-- fragment --><p>The path array and its strings are only valid until the file drop callback returns, as they may have been generated specifically for that event. You need to make a deep copy of the array if you want to keep the paths. </p>
<!-- iframe showing the search results (closed by default) -->
<divid="MSearchResultsWindow">
<iframesrc="javascript:void(0)"frameborder="0"
name="MSearchResults"id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<divclass="header">
<divclass="headertitle">
<divclass="title">Introduction to the API </div></div>
</div><!--header-->
<divclass="contents">
<divclass="toc"><h3>Table of Contents</h3>
<ul><liclass="level1"><ahref="#intro_init">Initialization and termination</a><ul><liclass="level2"><ahref="#intro_init_init">Initializing GLFW</a></li>
<divclass="textblock"><p>This guide introduces the basic concepts of GLFW and describes initialization, error handling and API guarantees and limitations. For a broad but shallow tutorial, see <aclass="el"href="quick_guide.html">Getting started</a> instead. For details on a specific function in this category, see the <aclass="el"href="group__init.html">Initialization, version and error reference</a>.</p>
<p>There are also guides for the other areas of GLFW.</p>
<p>Before most GLFW functions may be called, the library must be initialized. This initialization checks what features are available on the machine, enumerates monitors and joysticks, initializes the timer and performs any required platform-specific initialization.</p>
<p>Only the following functions may be called before the library has been successfully initialized, and only from the main thread.</p>
<p>Calling any other function before successful initialization will cause a <aclass="el"href="group__errors.html#ga2374ee02c177f12e1fa76ff3ed15e14a">GLFW_NOT_INITIALIZED</a> error.</p>
<h2><aclass="anchor"id="intro_init_init"></a>
Initializing GLFW</h2>
<p>The library is initialized with <aclass="el"href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a>, which returns <code>GLFW_FALSE</code> if an error occurred.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordflow">if</span> (!<aclass="code"href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a>())</div><divclass="line">{</div><divclass="line"><spanclass="comment">// Handle initialization failure</span></div><divclass="line">}</div></div><!-- fragment --><p>If any part of initialization fails, any parts that succeeded are terminated as if <aclass="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 simply 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 simply exit, but GLFW sometimes has to change global system settings and these might not be restored without termination.</p>
<p>Before your application exits, you should terminate the GLFW library if it has been initialized. This is done with <aclass="el"href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a>.</p>
<divclass="fragment"><divclass="line"><aclass="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><aclass="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 <em>why</em> the error occurred. Some functions also return otherwise valid values on error. Finally, far from all GLFW functions have return values.</p>
<p>This is where the error callback comes in. This callback is called whenever an error occurs. It is set with <aclass="el"href="group__init.html#gaa5d796c3cf7c1a7f02f845486333fb5f">glfwSetErrorCallback</a>, a function that may be called regardless of whether GLFW is initialized.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__init.html#gaa5d796c3cf7c1a7f02f845486333fb5f">glfwSetErrorCallback</a>(error_callback);</div></div><!-- fragment --><p>The error callback receives a human-readable description of the error and (when possible) its cause. The description encoded as UTF-8. The callback is also provided with an <aclass="el"href="group__errors.html">error code</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> error_callback(<spanclass="keywordtype">int</span> error, <spanclass="keyword">const</span><spanclass="keywordtype">char</span>* description)</div><divclass="line">{</div><divclass="line"> puts(description);</div><divclass="line">}</div></div><!-- fragment --><p>The error code indicates the general category of the error. Some error codes, such as <aclass="el"href="group__errors.html#ga2374ee02c177f12e1fa76ff3ed15e14a">GLFW_NOT_INITIALIZED</a> has only a single meaning, whereas others like <aclass="el"href="group__errors.html#gad44162d78100ea5e87cdd38426b8c7a1">GLFW_PLATFORM_ERROR</a> are used for many different errors.</p>
<p>The description string is only valid until the error callback returns, as it may have been generated specifically for that error. This lets GLFW provide much more specific error descriptions but means you must make a copy if you want to keep the description string.</p>
<dlclass="section note"><dt>Note</dt><dd>Relying on erroneous behavior is not forward compatible. In other words, do not rely on a currently invalid call to generate a specific error, as that same call may in future versions generate a different error or become valid.</dd></dl>
<h1><aclass="anchor"id="coordinate_systems"></a>
Coordinate systems</h1>
<p>GLFW has two primary coordinate systems: the <em>virtual screen</em> and the window <em>client 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>
<divclass="image">
<imgsrc="spaces.svg"width="90%"/>
</div>
<p>Both the virtual screen and the client 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 client area.</p>
<p>Because the origin of the window's client area coordinate system is also the point from which the window position is specified, you can translate client area coordinates to the virtual screen by adding the window position. The window frame, when present, extends out from the client area but does not affect the window position.</p>
<p>Almost all positions and sizes in GLFW are measured in screen coordinates relative to one of the two origins above. This includes cursor positions, window positions and sizes, window frame sizes, monitor positions and video mode resolutions.</p>
<p>Two exceptions are the <aclass="el"href="monitor_guide.html#monitor_size">monitor physical size</a>, which is measured in millimetres, and <aclass="el"href="window_guide.html#window_fbsize">framebuffer size</a>, which is measured in pixels.</p>
<p>Pixels and screen coordinates may map 1:1 on your machine, but they won't on every other machine, for example on a Mac with a Retina display. The ratio between screen coordinates and pixels may also change at run-time depending on which monitor the window is currently considered to be on.</p>
<p>This section describes the conditions under which GLFW can be expected to function, barring bugs in the operating system or drivers. Use of GLFW outside of these limits may work on some platforms, or on some machines, or some of the time, or on some versions of GLFW, but it may break at any time and this will not be considered a bug.</p>
<h2><aclass="anchor"id="lifetime"></a>
Pointer lifetimes</h2>
<p>GLFW will never free any pointer you provide to it and you must never free any pointer it provides to you.</p>
<p>Many GLFW functions return pointers to dynamically allocated structures, strings or arrays, and some callbacks are provided with strings or arrays. These are always managed by GLFW and should never be freed by the application. The lifetime of these pointers is documented for each GLFW function and callback. If you need to keep this data, you must copy it before its lifetime expires.</p>
<p>Many GLFW functions accept pointers to structures or strings allocated by the application. These are never freed by GLFW and are always the responsibility of the application. If GLFW needs to keep the data in these structures or strings, it is copied before the function returns.</p>
<p>Pointer lifetimes are guaranteed not to be shortened in future minor or patch releases.</p>
<h2><aclass="anchor"id="reentrancy"></a>
Reentrancy</h2>
<p>GLFW event processing and object creation and destruction are not reentrant. This means that the following functions must not be called from any callback function:</p>
<p>These functions may be made reentrant in future minor or patch releases, but functions not on this list will not be made non-reentrant.</p>
<h2><aclass="anchor"id="thread_safety"></a>
Thread safety</h2>
<p>Most GLFW functions must only be called from the main thread, but some may be called from any thread. However, no GLFW function may be called from any thread but the main thread until GLFW has been successfully initialized, including functions that may called before initialization.</p>
<p>The reference documentation for every GLFW function states whether it is limited to the main thread.</p>
<p>Initialization and termination, event processing and the creation and destruction of windows, contexts and cursors are all limited to the main thread due to limitations of one or several platforms.</p>
<p>Because event processing must be performed on the main thread, all callbacks except for the error callback will only be called on that thread. The error callback may be called on any thread, as any GLFW function may generate errors.</p>
<p>The posting of empty events may be done from any thread. The window user pointer and close flag may also be accessed and modified from any thread, but this is not synchronized by GLFW. The following window related functions may be called from any thread:</p>
<p>The regular timer may be used from any thread, but the reading and writing of the timer offset is not synchronized by GLFW. The following timer related functions may be called from any thread:</p>
<p>GLFW uses no synchronization objects internally except for thread-local storage to keep track of the current context for each thread. Synchronization is left to the application.</p>
<p>Functions that may currently be called from any thread will always remain so, but functions that are currently limited to the main thread may be updated to allow calls from any thread in future releases.</p>
<h2><aclass="anchor"id="compatibility"></a>
Version compatibility</h2>
<p>GLFW guarantees source and binary backward compatibility with earlier minor versions of the API. This means that you can drop in a newer version of the library and existing programs will continue to compile and existing binaries will continue to run.</p>
<p>Once a function or constant has been added, the signature of that function or value of that constant will remain unchanged until the next major version of GLFW. No compatibility of any kind is guaranteed between major versions.</p>
<p>Undocumented behavior, i.e. behavior that is not described in the documentation, may change at any time until it is documented.</p>
<p>If the reference documentation and the implementation differ, the reference documentation is correct and the implementation will be fixed in the next release.</p>
<h2><aclass="anchor"id="event_order"></a>
Event order</h2>
<p>The order of arrival of related events is not guaranteed to be consistent across platforms. The exception is synthetic key and mouse button release events, which are always delivered after the window defocus event.</p>
<h1><aclass="anchor"id="intro_version"></a>
Version management</h1>
<p>GLFW provides mechanisms for identifying what version of GLFW your application was compiled against as well as what version it is currently running against. If you are loading GLFW dynamically (not just linking dynamically), you can use this to verify that the library binary is compatible with your application.</p>
<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>
<divclass="fragment"><divclass="line">printf(<spanclass="stringliteral">"Compiled against GLFW %i.%i.%i\n"</span>,</div><divclass="line"><aclass="code"href="group__init.html#ga6337d9ea43b22fc529b2bba066b4a576">GLFW_VERSION_MAJOR</a>,</div><divclass="line"><aclass="code"href="group__init.html#gaf80d40f0aea7088ff337606e9c48f7a3">GLFW_VERSION_MINOR</a>,</div><divclass="line"><aclass="code"href="group__init.html#gab72ae2e2035d9ea461abc3495eac0502">GLFW_VERSION_REVISION</a>);</div></div><!-- fragment --><h2><aclass="anchor"id="intro_version_runtime"></a>
Run-time version</h2>
<p>The run-time version can be retrieved with <aclass="el"href="group__init.html#ga9f8ffaacf3c269cc48eafbf8b9b71197">glfwGetVersion</a>, a function that may be called regardless of whether GLFW is initialized.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> major, minor, revision;</div><divclass="line"><aclass="code"href="group__init.html#ga9f8ffaacf3c269cc48eafbf8b9b71197">glfwGetVersion</a>(&major, &minor, &revision);</div><divclass="line"></div><divclass="line">printf(<spanclass="stringliteral">"Running against GLFW %i.%i.%i\n"</span>, major, minor, revision);</div></div><!-- fragment --><h2><aclass="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 <aclass="el"href="group__init.html#ga23d47dc013fce2bf58036da66079a657">glfwGetVersionString</a>, a function that may be called regardless of whether GLFW is initialized.</p>
<p><b>Do not use the version string</b> to parse the GLFW library version. The <aclass="el"href="group__init.html#ga9f8ffaacf3c269cc48eafbf8b9b71197">glfwGetVersion</a> function already provides the version of the running library binary.</p>
<p>The format of the string is as follows:</p><ul>
<li>The version of GLFW</li>
<li>The name of the window system API</li>
<li>The name of the context creation API</li>
<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>
<divclass="fragment"><divclass="line">3.0.0 Win32 WGL MinGW</div></div><!-- fragment --></div></div><!-- contents -->
<trid="row_1_"><tdclass="entry"><spanstyle="width:0px;display:inline-block;"> </span><spanid="arr_1_"class="arrow"onclick="toggleFolder('1_')">▼</span><aclass="el"href="group__init.html"target="_self">Initialization, version and error reference</a></td><tdclass="desc"></td></tr>
<divclass="textblock"><p>This guide introduces the monitor related functions of GLFW. For details on a specific function in this category, see the <aclass="el"href="group__monitor.html">Monitor reference</a>. There are also guides for the other areas of GLFW.</p>
<ul>
<li><aclass="el"href="intro_guide.html">Introduction to the API</a></li>
<p>A monitor object represents a currently connected monitor and is represented as a pointer to the <ahref="https://en.wikipedia.org/wiki/Opaque_data_type">opaque</a> type <aclass="el"href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>. Monitor objects cannot be created or destroyed by the application and retain their addresses until the monitors they represent are disconnected or until the library is <aclass="el"href="intro_guide.html#intro_init_terminate">terminated</a>.</p>
<p>Each monitor has a current video mode, a list of supported video modes, a virtual position, a human-readable name, an estimated physical size and a gamma ramp. One of the monitors is the primary monitor.</p>
<p>The virtual position of a monitor is in <aclass="el"href="intro_guide.html#coordinate_systems">screen coordinates</a> and, together with the current video mode, describes the viewports that the connected monitors provide into the virtual desktop that spans them.</p>
<p>To see how GLFW views your monitor setup and its available video modes, run the <code>monitors</code> test program.</p>
<h2><aclass="anchor"id="monitor_monitors"></a>
Retrieving monitors</h2>
<p>The primary monitor is returned by <aclass="el"href="group__monitor.html#ga721867d84c6d18d6790d64d2847ca0b1">glfwGetPrimaryMonitor</a>. It is the user's preferred monitor and is usually the one with global UI elements like task bar or menu bar.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>* primary = <aclass="code"href="group__monitor.html#ga721867d84c6d18d6790d64d2847ca0b1">glfwGetPrimaryMonitor</a>();</div></div><!-- fragment --><p>You can retrieve all currently connected monitors with <aclass="el"href="group__monitor.html#ga3fba51c8bd36491d4712aa5bd074a537">glfwGetMonitors</a>. See the reference documentation for the lifetime of the returned array.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> count;</div><divclass="line"><aclass="code"href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>** monitors = <aclass="code"href="group__monitor.html#ga3fba51c8bd36491d4712aa5bd074a537">glfwGetMonitors</a>(&count);</div></div><!-- fragment --><p>The primary monitor is always the first monitor in the returned array, but other monitors may be moved to a different index when a monitor is connected or disconnected.</p>
<h2><aclass="anchor"id="monitor_event"></a>
Monitor configuration changes</h2>
<p>If you wish to be notified when a monitor is connected or disconnected, set a monitor callback.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__monitor.html#gac3fe0f647f68b731f99756cd81897378">glfwSetMonitorCallback</a>(monitor_callback);</div></div><!-- fragment --><p>The callback function receives the handle for the monitor that has been connected or disconnected and the event that occurred.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> monitor_callback(<aclass="code"href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>* monitor, <spanclass="keywordtype">int</span> event)</div><divclass="line">{</div><divclass="line"><spanclass="keywordflow">if</span> (event == <aclass="code"href="glfw3_8h.html#abe11513fd1ffbee5bb9b173f06028b9e">GLFW_CONNECTED</a>)</div><divclass="line"> {</div><divclass="line"><spanclass="comment">// The monitor was connected</span></div><divclass="line"> }</div><divclass="line"><spanclass="keywordflow">else</span><spanclass="keywordflow">if</span> (event == <aclass="code"href="glfw3_8h.html#aab64b25921ef21d89252d6f0a71bfc32">GLFW_DISCONNECTED</a>)</div><divclass="line"> {</div><divclass="line"><spanclass="comment">// The monitor was disconnected</span></div><divclass="line"> }</div><divclass="line">}</div></div><!-- fragment --><p>If a monitor is disconnected, any windows that are full screen on it get forced into windowed mode.</p>
<h1><aclass="anchor"id="monitor_properties"></a>
Monitor properties</h1>
<p>Each monitor has a current video mode, a list of supported video modes, a virtual position, a human-readable name, an estimated physical size and a gamma ramp.</p>
<h2><aclass="anchor"id="monitor_modes"></a>
Video modes</h2>
<p>GLFW generally does a good job selecting a suitable video mode when you create a full screen window, change its video mode or or make a windowed one full screen, but it is sometimes useful to know exactly which video modes are supported.</p>
<p>Video modes are represented as <aclass="el"href="structGLFWvidmode.html">GLFWvidmode</a> structures. You can get an array of the video modes supported by a monitor with <aclass="el"href="group__monitor.html#ga820b0ce9a5237d645ea7cbb4bd383458">glfwGetVideoModes</a>. See the reference documentation for the lifetime of the returned array.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> count;</div><divclass="line"><aclass="code"href="structGLFWvidmode.html">GLFWvidmode</a>* modes = <aclass="code"href="group__monitor.html#ga820b0ce9a5237d645ea7cbb4bd383458">glfwGetVideoModes</a>(monitor, &count);</div></div><!-- fragment --><p>To get the current video mode of a monitor call <aclass="el"href="group__monitor.html#gafc1bb972a921ad5b3bd5d63a95fc2d52">glfwGetVideoMode</a>. See the reference documentation for the lifetime of the returned pointer.</p>
<divclass="fragment"><divclass="line"><spanclass="keyword">const</span><aclass="code"href="structGLFWvidmode.html">GLFWvidmode</a>* mode = <aclass="code"href="group__monitor.html#gafc1bb972a921ad5b3bd5d63a95fc2d52">glfwGetVideoMode</a>(monitor);</div></div><!-- fragment --><p>The resolution of a video mode is specified in <aclass="el"href="intro_guide.html#coordinate_systems">screen coordinates</a>, not pixels.</p>
<h2><aclass="anchor"id="monitor_size"></a>
Physical size</h2>
<p>The physical size of a monitor in millimetres, or an estimation of it, can be retrieved with <aclass="el"href="group__monitor.html#ga7d8bffc6c55539286a6bd20d32a8d7ea">glfwGetMonitorPhysicalSize</a>. This has no relation to its current <em>resolution</em>, i.e. the width and height of its current <aclass="el"href="monitor_guide.html#monitor_modes">video mode</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> widthMM, heightMM;</div><divclass="line"><aclass="code"href="group__monitor.html#ga7d8bffc6c55539286a6bd20d32a8d7ea">glfwGetMonitorPhysicalSize</a>(monitor, &widthMM, &heightMM);</div></div><!-- fragment --><p>This can, for example, be used together with the current video mode to calculate the DPI of a monitor.</p>
<divclass="fragment"><divclass="line"><spanclass="keyword">const</span><spanclass="keywordtype">double</span> dpi = mode-><aclass="code"href="structGLFWvidmode.html#a698dcb200562051a7249cb6ae154c71d">width</a> / (widthMM / 25.4);</div></div><!-- fragment --><h2><aclass="anchor"id="monitor_pos"></a>
Virtual position</h2>
<p>The position of the monitor on the virtual desktop, in <aclass="el"href="intro_guide.html#coordinate_systems">screen coordinates</a>, can be retrieved with <aclass="el"href="group__monitor.html#ga102f54e7acc9149edbcf0997152df8c9">glfwGetMonitorPos</a>.</p>
<divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> xpos, ypos;</div><divclass="line"><aclass="code"href="group__monitor.html#ga102f54e7acc9149edbcf0997152df8c9">glfwGetMonitorPos</a>(monitor, &xpos, &ypos);</div></div><!-- fragment --><h2><aclass="anchor"id="monitor_name"></a>
Human-readable name</h2>
<p>The human-readable, UTF-8 encoded name of a monitor is returned by <aclass="el"href="group__monitor.html#ga79a34ee22ff080ca954a9663e4679daf">glfwGetMonitorName</a>. See the reference documentation for the lifetime of the returned string.</p>
<divclass="fragment"><divclass="line"><spanclass="keyword">const</span><spanclass="keywordtype">char</span>* name = <aclass="code"href="group__monitor.html#ga79a34ee22ff080ca954a9663e4679daf">glfwGetMonitorName</a>(monitor);</div></div><!-- fragment --><p>Monitor names are not guaranteed to be unique. Two monitors of the same model and make may have the same name. Only the monitor handle is guaranteed to be unique, and only until that monitor is disconnected.</p>
<h2><aclass="anchor"id="monitor_gamma"></a>
Gamma ramp</h2>
<p>The gamma ramp of a monitor can be set with <aclass="el"href="group__monitor.html#ga583f0ffd0d29613d8cd172b996bbf0dd">glfwSetGammaRamp</a>, which accepts a monitor handle and a pointer to a <aclass="el"href="structGLFWgammaramp.html">GLFWgammaramp</a> structure.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="structGLFWgammaramp.html">GLFWgammaramp</a> ramp;</div><divclass="line"><spanclass="keywordtype">unsigned</span><spanclass="keywordtype">short</span> red[256], green[256], blue[256];</div><divclass="line"></div><divclass="line">ramp.<aclass="code"href="structGLFWgammaramp.html#ad620e1cffbff9a32c51bca46301b59a5">size</a> = 256;</div><divclass="line">ramp.<aclass="code"href="structGLFWgammaramp.html#a2cce5d968734b685623eef913e635138">red</a> = red;</div><divclass="line">ramp.<aclass="code"href="structGLFWgammaramp.html#affccc6f5df47820b6562d709da3a5a3a">green</a> = green;</div><divclass="line">ramp.<aclass="code"href="structGLFWgammaramp.html#acf0c836d0efe29c392fe8d1a1042744b">blue</a> = blue;</div><divclass="line"></div><divclass="line"><spanclass="keywordflow">for</span> (i = 0; i < ramp.<aclass="code"href="structGLFWgammaramp.html#ad620e1cffbff9a32c51bca46301b59a5">size</a>; i++)</div><divclass="line">{</div><divclass="line"><spanclass="comment">// Fill out gamma ramp arrays as desired</span></div><divclass="line">}</div><divclass="line"></div><divclass="line"><aclass="code"href="group__monitor.html#ga583f0ffd0d29613d8cd172b996bbf0dd">glfwSetGammaRamp</a>(monitor, &ramp);</div></div><!-- fragment --><p>The gamma ramp data is copied before the function returns, so there is no need to keep it around once the ramp has been set.</p>
<dlclass="section note"><dt>Note</dt><dd>It is recommended to use gamma ramps of size 256, as that is the size supported by all graphics cards on all platforms.</dd></dl>
<p>The current gamma ramp for a monitor is returned by <aclass="el"href="group__monitor.html#gab7c41deb2219bde3e1eb756ddaa9ec80">glfwGetGammaRamp</a>. See the reference documentation for the lifetime of the returned structure.</p>
<divclass="fragment"><divclass="line"><spanclass="keyword">const</span><aclass="code"href="structGLFWgammaramp.html">GLFWgammaramp</a>* ramp = <aclass="code"href="group__monitor.html#gab7c41deb2219bde3e1eb756ddaa9ec80">glfwGetGammaRamp</a>(monitor);</div></div><!-- fragment --><p>If you wish to set a regular gamma ramp, you can have GLFW calculate it for you from the desired exponent with <aclass="el"href="group__monitor.html#ga6ac582625c990220785ddd34efa3169a">glfwSetGamma</a>, which in turn calls <aclass="el"href="group__monitor.html#ga583f0ffd0d29613d8cd172b996bbf0dd">glfwSetGammaRamp</a> with the resulting ramp.</p>
<divclass="fragment"><divclass="line"><aclass="code"href="group__monitor.html#ga6ac582625c990220785ddd34efa3169a">glfwSetGamma</a>(monitor, 1.0);</div></div><!-- fragment --></div></div><!-- contents -->
<!-- iframe showing the search results (closed by default) -->
<divid="MSearchResultsWindow">
<iframesrc="javascript:void(0)"frameborder="0"
name="MSearchResults"id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<divclass="header">
<divclass="headertitle">
<divclass="title">Moving from GLFW 2 to 3 </div></div>
</div><!--header-->
<divclass="contents">
<divclass="toc"><h3>Table of Contents</h3>
<ul><liclass="level1"><ahref="#moving_removed">Changed and removed features</a><ul><liclass="level2"><ahref="#moving_renamed_files">Renamed library and header file</a></li>
<liclass="level2"><ahref="#moving_threads">Removal of threading functions</a></li>
<liclass="level2"><ahref="#moving_image">Removal of image and texture loading</a></li>
<liclass="level2"><ahref="#moving_stdcall">Removal of GLFWCALL macro</a></li>
<divclass="textblock"><p>This is a transition guide for moving from GLFW 2 to 3. It describes what has changed or been removed, but does <em>not</em> include <aclass="el"href="news.html">new features</a> unless they are required when moving an existing code base onto the new API. For example, the new multi-monitor functions are required to create full screen windows with GLFW 3.</p>
<p>The GLFW 3 header is named <aclass="el"href="glfw3_8h.html">glfw3.h</a> and moved to the <code>GLFW</code> directory, to avoid collisions with the headers of other major versions. Similarly, the GLFW 3 library is named <code>glfw3,</code> except when it's installed as a shared library on Unix-like systems, where it uses the <ahref="https://en.wikipedia.org/wiki/soname">soname</a><code>libglfw.so.3</code>.</p>
<dlclass="section user"><dt>Old syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="preprocessor">#include <GL/glfw.h></span></div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="preprocessor">#include <<aclass="code"href="glfw3_8h.html">GLFW/glfw3.h</a>></span></div></div><!-- fragment --></dd></dl>
<h2><aclass="anchor"id="moving_threads"></a>
Removal of threading functions</h2>
<p>The threading functions have been removed, including the per-thread sleep function. They were fairly primitive, under-used, poorly integrated and took time away from the focus of GLFW (i.e. context, input and window). There are better threading libraries available and native threading support is available in both <ahref="http://en.cppreference.com/w/cpp/thread">C++11</a> and <ahref="http://en.cppreference.com/w/c/thread">C11</a>, both of which are gaining traction.</p>
<p>If you wish to use the C++11 or C11 facilities but your compiler doesn't yet support them, see the <ahref="https://gitorious.org/tinythread/tinythreadpp">TinyThread++</a> and <ahref="https://github.com/tinycthread/tinycthread">TinyCThread</a> projects created by the original author of GLFW. These libraries implement a usable subset of the threading APIs in C++11 and C11, and in fact some GLFW 3 test programs use TinyCThread.</p>
<p>However, GLFW 3 has better support for <em>use from multiple threads</em> than GLFW 2 had. Contexts can be made current on any thread, although only a single thread at a time, and the documentation explicitly states which functions may be used from any thread and which must only be used from the main thread.</p>
<p>The image and texture loading functions have been removed. They only supported the Targa image format, making them mostly useful for beginner level examples. To become of sufficiently high quality to warrant keeping them in GLFW 3, they would need not only to support other formats, but also modern extensions to OpenGL texturing. This would either add a number of external dependencies (libjpeg, libpng, etc.), or force GLFW to ship with inline versions of these libraries.</p>
<p>As there already are libraries doing this, it is unnecessary both to duplicate the work and to tie the duplicate to GLFW. The resulting library would also be platform-independent, as both OpenGL and stdio are available wherever GLFW is.</p>
<dlclass="section user"><dt>Removed functions</dt><dd><code>glfwReadImage</code>, <code>glfwReadMemoryImage</code>, <code>glfwFreeImage</code>, <code>glfwLoadTexture2D</code>, <code>glfwLoadMemoryTexture2D</code> and <code>glfwLoadTextureImage2D</code>.</dd></dl>
<h2><aclass="anchor"id="moving_stdcall"></a>
Removal of GLFWCALL macro</h2>
<p>The <code>GLFWCALL</code> macro, which made callback functions use <ahref="http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx">__stdcall</a> on Windows, has been removed. GLFW is written in C, not Pascal. Removing this macro means there's one less thing for application programmers to remember, i.e. the requirement to mark all callback functions with <code>GLFWCALL</code>. It also simplifies the creation of DLLs and DLL link libraries, as there's no need to explicitly disable <code>@n</code> entry point suffixes.</p>
<dlclass="section user"><dt>Old syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> GLFWCALL callback_function(...);</div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> callback_function(...);</div></div><!-- fragment --></dd></dl>
<p>Because GLFW 3 supports multiple windows, window handle parameters have been added to all window-related GLFW functions and callbacks. The handle of a newly created window is returned by <aclass="el"href="group__window.html#ga5c336fddf2cbb5b92f65f10fb6043344">glfwCreateWindow</a> (formerly <code>glfwOpenWindow</code>). Window handles are pointers to the <ahref="https://en.wikipedia.org/wiki/Opaque_data_type">opaque</a> type <aclass="el"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>.</p>
<dlclass="section user"><dt>Old syntax</dt><dd><divclass="fragment"><divclass="line"><aclass="code"href="group__window.html#ga5d877f09e968cef7a360b513306f17ff">glfwSetWindowTitle</a>(<spanclass="stringliteral">"New Window Title"</span>);</div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New syntax</dt><dd><divclass="fragment"><divclass="line"><aclass="code"href="group__window.html#ga5d877f09e968cef7a360b513306f17ff">glfwSetWindowTitle</a>(window, <spanclass="stringliteral">"New Window Title"</span>);</div></div><!-- fragment --></dd></dl>
<h2><aclass="anchor"id="moving_monitor"></a>
Explicit monitor selection</h2>
<p>GLFW 3 provides support for multiple monitors. To request a full screen mode window, instead of passing <code>GLFW_FULLSCREEN</code> you specify which monitor you wish the window to use. The <aclass="el"href="group__monitor.html#ga721867d84c6d18d6790d64d2847ca0b1">glfwGetPrimaryMonitor</a> function returns the monitor that GLFW 2 would have selected, but there are many other <aclass="el"href="monitor_guide.html">monitor functions</a>. Monitor handles are pointers to the <ahref="https://en.wikipedia.org/wiki/Opaque_data_type">opaque</a> type <aclass="el"href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>.</p>
<dlclass="section user"><dt>Old basic full screen</dt><dd><divclass="fragment"><divclass="line">glfwOpenWindow(640, 480, 8, 8, 8, 0, 24, 0, GLFW_FULLSCREEN);</div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New basic full screen</dt><dd><divclass="fragment"><divclass="line">window = <aclass="code"href="group__window.html#ga5c336fddf2cbb5b92f65f10fb6043344">glfwCreateWindow</a>(640, 480, <spanclass="stringliteral">"My Window"</span>, <aclass="code"href="group__monitor.html#ga721867d84c6d18d6790d64d2847ca0b1">glfwGetPrimaryMonitor</a>(), NULL);</div></div><!-- fragment --></dd></dl>
<dlclass="section note"><dt>Note</dt><dd>The framebuffer bit depth parameters of <code>glfwOpenWindow</code> have been turned into <aclass="el"href="window_guide.html#window_hints">window hints</a>, but as they have been given <aclass="el"href="window_guide.html#window_hints_values">sane defaults</a> you rarely need to set these hints.</dd></dl>
<h2><aclass="anchor"id="moving_autopoll"></a>
Removal of automatic event polling</h2>
<p>GLFW 3 does not automatically poll for events in <aclass="el"href="group__window.html#ga15a5a1ee5b3c2ca6b15ca209a12efd14">glfwSwapBuffers</a>, meaning you need to call <aclass="el"href="group__window.html#ga37bd57223967b4211d60ca1a0bf3c832">glfwPollEvents</a> or <aclass="el"href="group__window.html#ga554e37d781f0a997656c26b2c56c835e">glfwWaitEvents</a> yourself. Unlike buffer swap, which acts on a single window, the event processing functions act on all windows at once.</p>
<dlclass="section user"><dt>Old basic main loop</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordflow">while</span> (...)</div><divclass="line">{</div><divclass="line"><spanclass="comment">// Process input</span></div><divclass="line"><spanclass="comment">// Render output</span></div><divclass="line"><aclass="code"href="group__window.html#ga15a5a1ee5b3c2ca6b15ca209a12efd14">glfwSwapBuffers</a>();</div><divclass="line">}</div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New basic main loop</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordflow">while</span> (...)</div><divclass="line">{</div><divclass="line"><spanclass="comment">// Process input</span></div><divclass="line"><spanclass="comment">// Render output</span></div><divclass="line"><aclass="code"href="group__window.html#ga15a5a1ee5b3c2ca6b15ca209a12efd14">glfwSwapBuffers</a>(window);</div><divclass="line"><aclass="code"href="group__window.html#ga37bd57223967b4211d60ca1a0bf3c832">glfwPollEvents</a>();</div><divclass="line">}</div></div><!-- fragment --></dd></dl>
<h2><aclass="anchor"id="moving_context"></a>
Explicit context management</h2>
<p>Each GLFW 3 window has its own OpenGL context and only you, the application programmer, can know which context should be current on which thread at any given time. Therefore, GLFW 3 leaves that decision to you.</p>
<p>This means that you need to call <aclass="el"href="group__context.html#ga1c04dc242268f827290fe40aa1c91157">glfwMakeContextCurrent</a> after creating a window before you can call any OpenGL functions.</p>
<h2><aclass="anchor"id="moving_hidpi"></a>
Separation of window and framebuffer sizes</h2>
<p>Window positions and sizes now use screen coordinates, which may not be the same as pixels on machines with high-DPI monitors. This is important as OpenGL uses pixels, not screen coordinates. For example, the rectangle specified with <code>glViewport</code> needs to use pixels. Therefore, framebuffer size functions have been added. You can retrieve the size of the framebuffer of a window with <aclass="el"href="group__window.html#ga0e2637a4161afb283f5300c7f94785c9">glfwGetFramebufferSize</a> function. A framebuffer size callback has also been added, which can be set with <aclass="el"href="group__window.html#ga3203461a5303bf289f2e05f854b2f7cf">glfwSetFramebufferSizeCallback</a>.</p>
<p>The <code>GLFW_OPENED</code> window parameter has been removed. As long as the window has not been destroyed, whether through <aclass="el"href="group__window.html#gacdf43e51376051d2c091662e9fe3d7b2">glfwDestroyWindow</a> or <aclass="el"href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a>, the window is "open".</p>
<p>A user attempting to close a window is now just an event like any other. Unlike GLFW 2, windows and contexts created with GLFW 3 will never be destroyed unless you choose them to be. Each window now has a close flag that is set to <code>GLFW_TRUE</code> when the user attempts to close that window. By default, nothing else happens and the window stays visible. It is then up to you to either destroy the window, take some other action or simply ignore the request.</p>
<p>You can query the close flag at any time with <aclass="el"href="group__window.html#ga24e02fbfefbb81fc45320989f8140ab5">glfwWindowShouldClose</a> and set it at any time with <aclass="el"href="group__window.html#ga49c449dde2a6f87d996f4daaa09d6708">glfwSetWindowShouldClose</a>.</p>
<dlclass="section user"><dt>Old basic main loop</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordflow">while</span> (glfwGetWindowParam(GLFW_OPENED))</div><divclass="line">{</div><divclass="line"> ...</div><divclass="line">}</div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New basic main loop</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordflow">while</span> (!<aclass="code"href="group__window.html#ga24e02fbfefbb81fc45320989f8140ab5">glfwWindowShouldClose</a>(window))</div><divclass="line">{</div><divclass="line"> ...</div><divclass="line">}</div></div><!-- fragment --></dd></dl>
<p>The close callback no longer returns a value. Instead, it is called after the close flag has been set so it can override its value, if it chooses to, before event processing completes. You may however not call <aclass="el"href="group__window.html#gacdf43e51376051d2c091662e9fe3d7b2">glfwDestroyWindow</a> from the close callback (or any other window related callback).</p>
<dlclass="section user"><dt>Old syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordtype">int</span> GLFWCALL window_close_callback(<spanclass="keywordtype">void</span>);</div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> window_close_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window);</div></div><!-- fragment --></dd></dl>
<dlclass="section note"><dt>Note</dt><dd>GLFW never clears the close flag to <code>GLFW_FALSE</code>, meaning you can use it for other reasons to close the window as well, for example the user choosing Quit from an in-game menu.</dd></dl>
<h2><aclass="anchor"id="moving_hints"></a>
Persistent window hints</h2>
<p>The <code>glfwOpenWindowHint</code> function has been renamed to <aclass="el"href="group__window.html#ga7d9c8c62384b1e2821c4dc48952d2033">glfwWindowHint</a>.</p>
<p>Window hints are no longer reset to their default values on window creation, but instead retain their values until modified by <aclass="el"href="group__window.html#ga7d9c8c62384b1e2821c4dc48952d2033">glfwWindowHint</a> or <aclass="el"href="group__window.html#gaa77c4898dfb83344a6b4f76aa16b9a4a">glfwDefaultWindowHints</a>, or until the library is terminated and re-initialized.</p>
<h2><aclass="anchor"id="moving_video_modes"></a>
Video mode enumeration</h2>
<p>Video mode enumeration is now per-monitor. The <aclass="el"href="group__monitor.html#ga820b0ce9a5237d645ea7cbb4bd383458">glfwGetVideoModes</a> function now returns all available modes for a specific monitor instead of requiring you to guess how large an array you need. The <code>glfwGetDesktopMode</code> function, which had poorly defined behavior, has been replaced by <aclass="el"href="group__monitor.html#gafc1bb972a921ad5b3bd5d63a95fc2d52">glfwGetVideoMode</a>, which returns the current mode of a monitor.</p>
<h2><aclass="anchor"id="moving_char_up"></a>
Removal of character actions</h2>
<p>The action parameter of the <aclass="el"href="group__input.html#gabf24451c7ceb1952bc02b17a0d5c3e5f">character callback</a> has been removed. This was an artefact of the origin of GLFW, i.e. being developed in English by a Swede. However, many keyboard layouts require more than one key to produce characters with diacritical marks. Even the Swedish keyboard layout requires this for uncommon cases like ü.</p>
<dlclass="section user"><dt>Old syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> GLFWCALL character_callback(<spanclass="keywordtype">int</span> character, <spanclass="keywordtype">int</span> action);</div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> character_callback(<aclass="code"href="group__window.html#ga3c96d80d363e67d13a41b5d1821f3242">GLFWwindow</a>* window, <spanclass="keywordtype">int</span> character);</div></div><!-- fragment --></dd></dl>
<h2><aclass="anchor"id="moving_cursorpos"></a>
Cursor position changes</h2>
<p>The <code>glfwGetMousePos</code> function has been renamed to <aclass="el"href="group__input.html#ga01d37b6c40133676b9cea60ca1d7c0cc">glfwGetCursorPos</a>, <code>glfwSetMousePos</code> to <aclass="el"href="group__input.html#ga04b03af936d906ca123c8f4ee08b39e7">glfwSetCursorPos</a> and <code>glfwSetMousePosCallback</code> to <aclass="el"href="group__input.html#ga7dad39486f2c7591af7fb25134a2501d">glfwSetCursorPosCallback</a>.</p>
<p>The cursor position is now <code>double</code> instead of <code>int</code>, both for the direct functions and for the callback. Some platforms can provide sub-pixel cursor movement and this data is now passed on to the application where available. On platforms where this is not provided, the decimal part is zero.</p>
<p>GLFW 3 only allows you to position the cursor within a window using <aclass="el"href="group__input.html#ga04b03af936d906ca123c8f4ee08b39e7">glfwSetCursorPos</a> (formerly <code>glfwSetMousePos</code>) when that window is active. Unless the window is active, the function fails silently.</p>
<h2><aclass="anchor"id="moving_wheel"></a>
Wheel position replaced by scroll offsets</h2>
<p>The <code>glfwGetMouseWheel</code> function has been removed. Scrolling is the input of offsets and has no absolute position. The mouse wheel callback has been replaced by a <aclass="el"href="group__input.html#ga4687e2199c60a18a8dd1da532e6d75c9">scroll callback</a> that receives two-dimensional floating point scroll offsets. This allows you to receive precise scroll data from for example modern touchpads.</p>
<dlclass="section user"><dt>Old syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="keywordtype">void</span> GLFWCALL mouse_wheel_callback(<spanclass="keywordtype">int</span> position);</div></div><!-- fragment --></dd></dl>
<p>The <code>GLFW_KEY_REPEAT</code> enable has been removed and key repeat is always enabled for both keys and characters. A new key action, <code>GLFW_REPEAT</code>, has been added to allow the <aclass="el"href="group__input.html#ga0192a232a41e4e82948217c8ba94fdfd">key callback</a> to distinguish an initial key press from a repeat. Note that <aclass="el"href="group__input.html#gadd341da06bc8d418b4dc3a3518af9ad2">glfwGetKey</a> still returns only <code>GLFW_PRESS</code> or <code>GLFW_RELEASE</code>.</p>
<h2><aclass="anchor"id="moving_keys"></a>
Physical key input</h2>
<p>GLFW 3 key tokens map to physical keys, unlike in GLFW 2 where they mapped to the values generated by the current keyboard layout. The tokens are named according to the values they would have using the standard US layout, but this is only a convenience, as most programmers are assumed to know that layout. This means that (for example) <code>GLFW_KEY_LEFT_BRACKET</code> is always a single key and is the same key in the same place regardless of what keyboard layouts the users of your program has.</p>
<p>The key input facility was never meant for text input, although using it that way worked slightly better in GLFW 2. If you were using it to input text, you should be using the character callback instead, on both GLFW 2 and 3. This will give you the characters being input, as opposed to the keys being pressed.</p>
<p>GLFW 3 has key tokens for all keys on a standard 105 key keyboard, so instead of having to remember whether to check for <code>'a'</code> or <code>'A'</code>, you now check for <code>GLFW_KEY_A</code>.</p>
<h2><aclass="anchor"id="moving_joystick"></a>
Joystick function changes</h2>
<p>The <code>glfwGetJoystickPos</code> function has been renamed to <aclass="el"href="group__input.html#ga6271d46a5901ec2c99601ccf4dd14731">glfwGetJoystickAxes</a>.</p>
<p>The <code>glfwGetJoystickParam</code> function and the <code>GLFW_PRESENT</code>, <code>GLFW_AXES</code> and <code>GLFW_BUTTONS</code> tokens have been replaced by the <aclass="el"href="group__input.html#gaffcbd9ac8ee737fcdd25475123a3c790">glfwJoystickPresent</a> function as well as axis and button counts returned by the <aclass="el"href="group__input.html#ga6271d46a5901ec2c99601ccf4dd14731">glfwGetJoystickAxes</a> and <aclass="el"href="group__input.html#gace54cd930dcd502e118fe4021384ce1b">glfwGetJoystickButtons</a> functions.</p>
<h2><aclass="anchor"id="moving_mbcs"></a>
Win32 MBCS support</h2>
<p>The Win32 port of GLFW 3 will not compile in <ahref="http://msdn.microsoft.com/en-us/library/5z097dxa.aspx">MBCS mode</a>. However, because the use of the Unicode version of the Win32 API doesn't affect the process as a whole, but only those windows created using it, it's perfectly possible to call MBCS functions from other parts of the same application. Therefore, even if an application using GLFW has MBCS mode code, there's no need for GLFW itself to support it.</p>
<h2><aclass="anchor"id="moving_windows"></a>
Support for versions of Windows older than XP</h2>
<p>All explicit support for version of Windows older than XP has been removed. There is no code that actively prevents GLFW 3 from running on these earlier versions, but it uses Win32 functions that those versions lack.</p>
<p>Windows XP was released in 2001, and by now (January 2015) it has not only replaced almost all earlier versions of Windows, but is itself rapidly being replaced by Windows 7 and 8. The MSDN library doesn't even provide documentation for version older than Windows 2000, making it difficult to maintain compatibility with these versions even if it was deemed worth the effort.</p>
<p>The Win32 API has also not stood still, and GLFW 3 uses many functions only present on Windows XP or later. Even supporting an OS as new as XP (new from the perspective of GLFW 2, which still supports Windows 95) requires runtime checking for a number of functions that are present only on modern version of Windows.</p>
<h2><aclass="anchor"id="moving_syskeys"></a>
Capture of system-wide hotkeys</h2>
<p>The ability to disable and capture system-wide hotkeys like Alt+Tab has been removed. Modern applications, whether they're games, scientific visualisations or something else, are nowadays expected to be good desktop citizens and allow these hotkeys to function even when running in full screen mode.</p>
<h2><aclass="anchor"id="moving_terminate"></a>
Automatic termination</h2>
<p>GLFW 3 does not register <aclass="el"href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a> with <code>atexit</code> at initialization, because <code>exit</code> calls registered functions from the calling thread and while it is permitted to call <code>exit</code> from any thread, <aclass="el"href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a> must only be called from the main thread.</p>
<p>To release all resources allocated by GLFW, you should call <aclass="el"href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a> yourself, from the main thread, before the program terminates. Note that this destroys all windows not already destroyed with <aclass="el"href="group__window.html#gacdf43e51376051d2c091662e9fe3d7b2">glfwDestroyWindow</a>, invalidating any window handles you may still have.</p>
<h2><aclass="anchor"id="moving_glu"></a>
GLU header inclusion</h2>
<p>GLFW 3 does not by default include the GLU header and GLU itself has been deprecated by <ahref="https://en.wikipedia.org/wiki/Khronos_Group">Khronos</a>. <b>New projects should not use GLU</b>, but if you need it for legacy code that has been moved to GLFW 3, you can request that the GLFW header includes it by defining <code>GLFW_INCLUDE_GLU</code> before the inclusion of the GLFW header.</p>
<dlclass="section user"><dt>Old syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="preprocessor">#include <GL/glfw.h></span></div></div><!-- fragment --></dd></dl>
<dlclass="section user"><dt>New syntax</dt><dd><divclass="fragment"><divclass="line"><spanclass="preprocessor">#define GLFW_INCLUDE_GLU</span></div><divclass="line"><spanclass="preprocessor">#include <GLFW/glfw3.h></span></div></div><!-- fragment --></dd></dl>
<td><code>glfwOpenWindow</code></td><td><aclass="el"href="group__window.html#ga5c336fddf2cbb5b92f65f10fb6043344">glfwCreateWindow</a></td><td>All channel bit depths are now hints </td></tr>
<td><code>glfwGetGLVersion</code></td><td><aclass="el"href="group__window.html#gacccb29947ea4b16860ebef42c2cb9337">glfwGetWindowAttrib</a></td><td>Use <code>GLFW_CONTEXT_VERSION_MAJOR</code>, <code>GLFW_CONTEXT_VERSION_MINOR</code> and <code>GLFW_CONTEXT_REVISION</code></td></tr>
<tr>
<td><code>glfwGetDesktopMode</code></td><td><aclass="el"href="group__monitor.html#gafc1bb972a921ad5b3bd5d63a95fc2d52">glfwGetVideoMode</a></td><td>Returns the current mode of a monitor </td></tr>
<tr>
<td><code>glfwGetJoystickParam</code></td><td><aclass="el"href="group__input.html#gaffcbd9ac8ee737fcdd25475123a3c790">glfwJoystickPresent</a></td><td>The axis and button counts are provided by <aclass="el"href="group__input.html#ga6271d46a5901ec2c99601ccf4dd14731">glfwGetJoystickAxes</a> and <aclass="el"href="group__input.html#gace54cd930dcd502e118fe4021384ce1b">glfwGetJoystickButtons</a></td></tr>
<td><code>GLFW_OPENGL_VERSION_MAJOR</code></td><td><code>GLFW_CONTEXT_VERSION_MAJOR</code></td><td>Renamed as it applies to OpenGL ES as well </td></tr>
<tr>
<td><code>GLFW_OPENGL_VERSION_MINOR</code></td><td><code>GLFW_CONTEXT_VERSION_MINOR</code></td><td>Renamed as it applies to OpenGL ES as well </td></tr>
<tr>
<td><code>GLFW_FSAA_SAMPLES</code></td><td><code>GLFW_SAMPLES</code></td><td>Renamed to match the OpenGL API </td></tr>
<tr>
<td><code>GLFW_ACTIVE</code></td><td><code>GLFW_FOCUSED</code></td><td>Renamed to match the window focus callback </td></tr>
<tr>
<td><code>GLFW_WINDOW_NO_RESIZE</code></td><td><code>GLFW_RESIZABLE</code></td><td>The default has been inverted </td></tr>
<tr>
<td><code>GLFW_MOUSE_CURSOR</code></td><td><code>GLFW_CURSOR</code></td><td>Used with <aclass="el"href="group__input.html#gaa92336e173da9c8834558b54ee80563b">glfwSetInputMode</a></td></tr>
<p>GLFW now supports basic integration with Vulkan with <aclass="el"href="group__vulkan.html#ga2e7f30931e02464b5bc8d0d4b6f9fe2b">glfwVulkanSupported</a>, <aclass="el"href="group__vulkan.html#ga1abcbe61033958f22f63ef82008874b1">glfwGetRequiredInstanceExtensions</a>, <aclass="el"href="group__vulkan.html#gadf228fac94c5fd8f12423ec9af9ff1e9">glfwGetInstanceProcAddress</a>, <aclass="el"href="group__vulkan.html#gaff3823355cdd7e2f3f9f4d9ea9518d92">glfwGetPhysicalDevicePresentationSupport</a> and <aclass="el"href="group__vulkan.html#ga1a24536bec3f80b08ead18e28e6ae965">glfwCreateWindowSurface</a>. Vulkan header inclusion can be selected with <aclass="el"href="build_guide.html#build_macros">GLFW_INCLUDE_VULKAN</a>.</p>
<p>GLFW now supports switching between windowed and full screen modes and updating the monitor and desired resolution and refresh rate of full screen windows with <aclass="el"href="group__window.html#ga81c76c418af80a1cce7055bccb0ae0a7">glfwSetWindowMonitor</a>.</p>
<h2><aclass="anchor"id="news_32_maximize"></a>
Window maxmimization support</h2>
<p>GLFW now supports window maximization with <aclass="el"href="group__window.html#ga3f541387449d911274324ae7f17ec56b">glfwMaximizeWindow</a> and the <aclass="el"href="window_guide.html#window_attribs_wnd">GLFW_MAXIMIZED</a> window hint and attribute.</p>
<h2><aclass="anchor"id="news_32_focus"></a>
Window input focus control</h2>
<p>GLFW now supports giving windows input focus with <aclass="el"href="group__window.html#ga873780357abd3f3a081d71a40aae45a1">glfwFocusWindow</a>.</p>
<h2><aclass="anchor"id="news_32_sizelimits"></a>
Window size limit support</h2>
<p>GLFW now supports setting both absolute and relative window size limits with <aclass="el"href="group__window.html#gac314fa6cec7d2d307be9963e2709cc90">glfwSetWindowSizeLimits</a> and <aclass="el"href="group__window.html#ga72ac8cb1ee2e312a878b55153d81b937">glfwSetWindowAspectRatio</a>.</p>
<h2><aclass="anchor"id="news_32_keyname"></a>
Localized key names</h2>
<p>GLFW now supports querying the localized name of printable keys with <aclass="el"href="group__input.html#ga237a182e5ec0b21ce64543f3b5e7e2be">glfwGetKeyName</a>, either by key token or by scancode.</p>
<h2><aclass="anchor"id="news_32_waittimeout"></a>
Wait for events with timeout</h2>
<p>GLFW now supports waiting for events for a set amount of time with <aclass="el"href="group__window.html#ga605a178db92f1a7f1a925563ef3ea2cf">glfwWaitEventsTimeout</a>.</p>
<h2><aclass="anchor"id="news_32_icon"></a>
Window icon support</h2>
<p>GLFW now supports setting the icon of windows with <aclass="el"href="group__window.html#gadd7ccd39fe7a7d1f0904666ae5932dc5">glfwSetWindowIcon</a>.</p>
<h2><aclass="anchor"id="news_32_timer"></a>
Raw timer access</h2>
<p>GLFW now supports raw timer values with <aclass="el"href="group__input.html#ga09b2bd37d328e0b9456c7ec575cc26aa">glfwGetTimerValue</a> and <aclass="el"href="group__input.html#ga3289ee876572f6e91f06df3a24824443">glfwGetTimerFrequency</a>.</p>
<h2><aclass="anchor"id="news_32_joystick"></a>
Joystick connection callback</h2>
<p>GLFW now supports notifying when a joystick has been connected or disconnected with <aclass="el"href="group__input.html#gab1dc8379f1b82bb660a6b9c9fa06ca07">glfwSetJoystickCallback</a>.</p>
<h2><aclass="anchor"id="news_32_noapi"></a>
Context-less windows</h2>
<p>GLFW now supports creating windows without a OpenGL or OpenGL ES context with <aclass="el"href="window_guide.html#window_hints_ctx">GLFW_NO_API</a>.</p>
<h2><aclass="anchor"id="news_32_contextapi"></a>
Run-time context creation API selection</h2>
<p>GLFW now supports selecting the context creation API at run-time with the <aclass="el"href="window_guide.html#window_hints_ctx">GLFW_CONTEXT_CREATION_API</a> window hint value.</p>
<h2><aclass="anchor"id="news_32_noerror"></a>
Error-free context creation</h2>
<p>GLFW now supports creating OpenGL and OpenGL ES contexts that do not emit errors with the <aclass="el"href="window_guide.html#window_hints_ctx">GLFW_CONTEXT_NO_ERROR</a> window hint, provided the machine supports the <code>GL_KHR_no_error</code> extension.</p>
<h2><aclass="anchor"id="news_32_cmake"></a>
CMake config-file package support</h2>
<p>GLFW now supports being used as a <aclass="el"href="build_guide.html#build_link_cmake_package">config-file package</a> from other projects for easy linking with the library and its dependencies.</p>
<h1><aclass="anchor"id="news_31"></a>
New features in 3.1</h1>
<p>These are the release highlights. For a full list of changes see the <ahref="http://www.glfw.org/changelog.html">version history</a>.</p>
<h2><aclass="anchor"id="news_31_cursor"></a>
Custom mouse cursor images</h2>
<p>GLFW now supports creating and setting both custom cursor images and standard cursor shapes. They are created with <aclass="el"href="group__input.html#gafca356935e10135016aa49ffa464c355">glfwCreateCursor</a> or <aclass="el"href="group__input.html#gaa65f416d03ebbbb5b8db71a489fcb894">glfwCreateStandardCursor</a>, set with <aclass="el"href="group__input.html#gad3b4f38c8d5dae036bc8fa959e18343e">glfwSetCursor</a> and destroyed with <aclass="el"href="group__input.html#ga81b952cd1764274d0db7fb3c5a79ba6a">glfwDestroyCursor</a>.</p>
<p>GLFW now provides a callback for receiving the paths of files and directories dropped onto GLFW windows. The callback is set with <aclass="el"href="group__input.html#ga41291bf15dd3ff564b3143aa6dc74a4b">glfwSetDropCallback</a>.</p>
<dlclass="section see"><dt>See also</dt><dd><aclass="el"href="input_guide.html#path_drop">Path drop input</a></dd></dl>
<h2><aclass="anchor"id="news_31_emptyevent"></a>
Main thread wake-up</h2>
<p>GLFW now provides the <aclass="el"href="group__window.html#gab5997a25187e9fd5c6f2ecbbc8dfd7e9">glfwPostEmptyEvent</a> function for posting an empty event from another thread to the main thread event queue, causing <aclass="el"href="group__window.html#ga554e37d781f0a997656c26b2c56c835e">glfwWaitEvents</a> to return.</p>
<p>GLFW now supports querying the size, on each side, of the frame around the client area of a window, with <aclass="el"href="group__window.html#ga1a9fd382058c53101b21cf211898f1f1">glfwGetWindowFrameSize</a>.</p>
<p>GLFW now supports disabling auto-iconification of full screen windows with the <aclass="el"href="window_guide.html#window_hints_wnd">GLFW_AUTO_ICONIFY</a> window hint. This is intended for people building multi-monitor installations, where you need windows to stay in full screen despite losing input focus.</p>
<h2><aclass="anchor"id="news_31_floating"></a>
Floating windows</h2>
<p>GLFW now supports floating windows, also called topmost or always on top, for easier debugging with the <aclass="el"href="window_guide.html#window_hints_wnd">GLFW_FLOATING</a> window hint.</p>
<h2><aclass="anchor"id="news_31_focused"></a>
Initially unfocused windows</h2>
<p>GLFW now supports preventing a windowed mode window from gaining input focus on creation, with the <aclass="el"href="window_guide.html#window_hints_wnd">GLFW_FOCUSED</a> window hint.</p>
<h2><aclass="anchor"id="news_31_direct"></a>
Direct access for window attributes and cursor position</h2>
<p>GLFW now queries the window input focus, visibility and iconification attributes and the cursor position directly instead of returning cached data.</p>
<h2><aclass="anchor"id="news_31_charmods"></a>
Character with modifiers callback</h2>
<p>GLFW now provides a callback for character events with modifier key bits. The callback is set with <aclass="el"href="group__input.html#ga3f55ef5dc03a374e567f068b13c94afc">glfwSetCharModsCallback</a>. Unlike the regular character callback, this will report character events that will not result in a character being input, for example if the Control key is held down.</p>
<p>GLFW now supports the creation of single buffered windows, with the <aclass="el"href="window_guide.html#window_hints_fb">GLFW_DOUBLEBUFFER</a> window hint.</p>
<h2><aclass="anchor"id="news_31_glext"></a>
Macro for including extension header</h2>
<p>GLFW now includes the extension header appropriate for the chosen OpenGL or OpenGL ES header when <aclass="el"href="build_guide.html#build_macros">GLFW_INCLUDE_GLEXT</a> is defined. GLFW does not provide these headers. They must be provided by your development environment or your OpenGL or OpenGL ES SDK.</p>
<h2><aclass="anchor"id="news_31_release"></a>
Context release behaviors</h2>
<p>GLFW now supports controlling whether the pipeline is flushed when a context is made non-current, with the <aclass="el"href="window_guide.html#window_hints_ctx">GLFW_CONTEXT_RELEASE_BEHAVIOR</a> window hint, provided the machine supports the <code>GL_KHR_context_flush_control</code> extension.</p>
<h2><aclass="anchor"id="news_31_wayland"></a>
(Experimental) Wayland support</h2>
<p>GLFW now has an <em>experimental</em> Wayland display protocol backend that can be selected on Linux with a CMake option.</p>
<h2><aclass="anchor"id="news_31_mir"></a>
(Experimental) Mir support</h2>
<p>GLFW now has an <em>experimental</em> Mir display server backend that can be selected on Linux with a CMake option.</p>
<h1><aclass="anchor"id="news_30"></a>
New features in 3.0</h1>
<p>These are the release highlights. For a full list of changes see the <ahref="http://www.glfw.org/changelog.html">version history</a>.</p>
<h2><aclass="anchor"id="news_30_cmake"></a>
CMake build system</h2>
<p>GLFW now uses the CMake build system instead of the various makefiles and project files used by earlier versions. CMake is available for all platforms supported by GLFW, is present in most package systems and can generate makefiles and/or project files for most popular development environments.</p>
<p>For more information on how to use CMake, see the <ahref="http://cmake.org/cmake/help/documentation.html">CMake manual</a>.</p>
<h2><aclass="anchor"id="news_30_multiwnd"></a>
Multi-window support</h2>
<p>GLFW now supports the creation of multiple windows, each with their own OpenGL or OpenGL ES context, and all window functions now take a window handle. Event callbacks are now per-window and are provided with the handle of the window that received the event. The <aclass="el"href="group__context.html#ga1c04dc242268f827290fe40aa1c91157">glfwMakeContextCurrent</a> function has been added to select which context is current on a given thread.</p>
<h2><aclass="anchor"id="news_30_multimon"></a>
Multi-monitor support</h2>
<p>GLFW now explicitly supports multiple monitors. They can be enumerated with <aclass="el"href="group__monitor.html#ga3fba51c8bd36491d4712aa5bd074a537">glfwGetMonitors</a>, queried with <aclass="el"href="group__monitor.html#ga820b0ce9a5237d645ea7cbb4bd383458">glfwGetVideoModes</a>, <aclass="el"href="group__monitor.html#ga102f54e7acc9149edbcf0997152df8c9">glfwGetMonitorPos</a>, <aclass="el"href="group__monitor.html#ga79a34ee22ff080ca954a9663e4679daf">glfwGetMonitorName</a> and <aclass="el"href="group__monitor.html#ga7d8bffc6c55539286a6bd20d32a8d7ea">glfwGetMonitorPhysicalSize</a>, and specified at window creation to make the newly created window full screen on that specific monitor.</p>
<h2><aclass="anchor"id="news_30_unicode"></a>
Unicode support</h2>
<p>All string arguments to GLFW functions and all strings returned by GLFW now use the UTF-8 encoding. This includes the window title, error string, clipboard text, monitor and joystick names as well as the extension function arguments (as ASCII is a subset of UTF-8).</p>
<h2><aclass="anchor"id="news_30_clipboard"></a>
Clipboard text I/O</h2>
<p>GLFW now supports reading and writing plain text to and from the system clipboard, with the <aclass="el"href="group__input.html#ga5aba1d704d9ab539282b1fbe9f18bb94">glfwGetClipboardString</a> and <aclass="el"href="group__input.html#gaba1f022c5eb07dfac421df34cdcd31dd">glfwSetClipboardString</a> functions.</p>
<h2><aclass="anchor"id="news_30_gamma"></a>
Gamma ramp support</h2>
<p>GLFW now supports setting and reading back the gamma ramp of monitors, with the <aclass="el"href="group__monitor.html#gab7c41deb2219bde3e1eb756ddaa9ec80">glfwGetGammaRamp</a> and <aclass="el"href="group__monitor.html#ga583f0ffd0d29613d8cd172b996bbf0dd">glfwSetGammaRamp</a> functions. There is also <aclass="el"href="group__monitor.html#ga6ac582625c990220785ddd34efa3169a">glfwSetGamma</a>, which generates a ramp from a gamma value and then sets it.</p>
<h2><aclass="anchor"id="news_30_gles"></a>
OpenGL ES support</h2>
<p>GLFW now supports the creation of OpenGL ES contexts, by setting the <code>GLFW_CLIENT_API</code> window hint to <code>GLFW_OPENGL_ES_API</code>, where creation of such contexts are supported. Note that GLFW <em>does not implement</em> OpenGL ES, so your driver must provide support in a way usable by GLFW. Modern Nvidia and Intel drivers support creation of OpenGL ES context using the GLX and WGL APIs, while AMD provides an EGL implementation instead.</p>
<h2><aclass="anchor"id="news_30_egl"></a>
(Experimental) EGL support</h2>
<p>GLFW now has an experimental EGL context creation back end that can be selected through CMake options.</p>
<h2><aclass="anchor"id="news_30_hidpi"></a>
High-DPI support</h2>
<p>GLFW now supports high-DPI monitors on both Windows and OS X, giving windows full resolution framebuffers where other UI elements are scaled up. To achieve this, <aclass="el"href="group__window.html#ga0e2637a4161afb283f5300c7f94785c9">glfwGetFramebufferSize</a> and <aclass="el"href="group__window.html#ga3203461a5303bf289f2e05f854b2f7cf">glfwSetFramebufferSizeCallback</a> have been added. These work with pixels, while the rest of the GLFW API works with screen coordinates. This is important as OpenGL uses pixels, not screen coordinates.</p>
<h2><aclass="anchor"id="news_30_error"></a>
Error callback</h2>
<p>GLFW now has an error callback, which can provide your application with much more detailed diagnostics than was previously possible. The callback is passed an error code and a description string.</p>
<h2><aclass="anchor"id="news_30_wndptr"></a>
Per-window user pointer</h2>
<p>Each window now has a user-defined pointer, retrieved with <aclass="el"href="group__window.html#ga17807ce0f45ac3f8bb50d6dcc59a4e06">glfwGetWindowUserPointer</a> and set with <aclass="el"href="group__window.html#ga3d2fc6026e690ab31a13f78bc9fd3651">glfwSetWindowUserPointer</a>, to make it easier to integrate GLFW into C++ code.</p>
<h2><aclass="anchor"id="news_30_iconifyfun"></a>
Window iconification callback</h2>
<p>Each window now has a callback for iconification and restoration events, which is set with <aclass="el"href="group__window.html#gab1ea7263081c0e073b8d5b91d6ffd367">glfwSetWindowIconifyCallback</a>.</p>
<h2><aclass="anchor"id="news_30_wndposfun"></a>
Window position callback</h2>
<p>Each window now has a callback for position events, which is set with <aclass="el"href="group__window.html#ga2837d4d240659feb4268fcb6530a6ba1">glfwSetWindowPosCallback</a>.</p>
<h2><aclass="anchor"id="news_30_wndpos"></a>
Window position query</h2>
<p>The position of a window can now be retrieved using <aclass="el"href="group__window.html#ga73cb526c000876fd8ddf571570fdb634">glfwGetWindowPos</a>.</p>
<h2><aclass="anchor"id="news_30_focusfun"></a>
Window focus callback</h2>
<p>Each windows now has a callback for focus events, which is set with <aclass="el"href="group__window.html#ga25d1c584edb375d7711c5c3548ba711f">glfwSetWindowFocusCallback</a>.</p>
<h2><aclass="anchor"id="news_30_enterleave"></a>
Cursor enter/leave callback</h2>
<p>Each window now has a callback for when the mouse cursor enters or leaves its client area, which is set with <aclass="el"href="group__input.html#gaa299c41dd0a3d171d166354e01279e04">glfwSetCursorEnterCallback</a>.</p>
<h2><aclass="anchor"id="news_30_wndtitle"></a>
Initial window title</h2>
<p>The title of a window is now specified at creation time, as one of the arguments to <aclass="el"href="group__window.html#ga5c336fddf2cbb5b92f65f10fb6043344">glfwCreateWindow</a>.</p>
<h2><aclass="anchor"id="news_30_hidden"></a>
Hidden windows</h2>
<p>Windows can now be hidden with <aclass="el"href="group__window.html#ga49401f82a1ba5f15db5590728314d47c">glfwHideWindow</a>, shown using <aclass="el"href="group__window.html#ga61be47917b72536a148300f46494fc66">glfwShowWindow</a> and created initially hidden with the <code>GLFW_VISIBLE</code> window hint. This allows for off-screen rendering in a way compatible with most drivers, as well as moving a window to a specific position before showing it.</p>
<h2><aclass="anchor"id="news_30_undecorated"></a>
Undecorated windows</h2>
<p>Windowed mode windows can now be created without decorations, e.g. things like a frame, a title bar, with the <code>GLFW_DECORATED</code> window hint. This allows for the creation of things like splash screens.</p>
<h2><aclass="anchor"id="news_30_keymods"></a>
Modifier key bit masks</h2>
<p><aclass="el"href="group__mods.html">Modifier key bit mask</a> parameters have been added to the <aclass="el"href="group__input.html#ga39893a4a7e7c3239c98d29c9e084350c">mouse button</a> and <aclass="el"href="group__input.html#ga0192a232a41e4e82948217c8ba94fdfd">key</a> callbacks.</p>
<h2><aclass="anchor"id="news_30_scancode"></a>
Platform-specific scancodes</h2>
<p>A scancode parameter has been added to the <aclass="el"href="group__input.html#ga0192a232a41e4e82948217c8ba94fdfd">key callback</a>. Keys that don't have a <aclass="el"href="group__keys.html">key token</a> still get passed on with the key parameter set to <code>GLFW_KEY_UNKNOWN</code>. These scancodes will vary between machines and are intended to be used for key bindings.</p>
<h2><aclass="anchor"id="news_30_jsname"></a>
Joystick names</h2>
<p>The name of a joystick can now be retrieved using <aclass="el"href="group__input.html#gac8d7f6107e05cfd106cfba973ab51e19">glfwGetJoystickName</a>.</p>
<trid="row_1_"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="moving_guide.html"target="_self">Moving from GLFW 2 to 3</a></td><tdclass="desc"></td></tr>
<trid="row_5_"><tdclass="entry"><spanstyle="width:16px;display:inline-block;"> </span><aclass="el"href="intro_guide.html"target="_self">Introduction to the API</a></td><tdclass="desc"></td></tr>
