1/*************************************************************************
2 * GLFW 3.2 - www.glfw.org
3 * A library for OpenGL, window and input
4 *------------------------------------------------------------------------
5 * Copyright (c) 2002-2006 Marcus Geelnard
6 * Copyright (c) 2006-2016 Camilla Berglund <elmindreda@glfw.org>
7 *
8 * This software is provided 'as-is', without any express or implied
9 * warranty. In no event will the authors be held liable for any damages
10 * arising from the use of this software.
11 *
12 * Permission is granted to anyone to use this software for any purpose,
13 * including commercial applications, and to alter it and redistribute it
14 * freely, subject to the following restrictions:
15 *
16 * 1. The origin of this software must not be misrepresented; you must not
17 * claim that you wrote the original software. If you use this software
18 * in a product, an acknowledgment in the product documentation would
19 * be appreciated but is not required.
20 *
21 * 2. Altered source versions must be plainly marked as such, and must not
22 * be misrepresented as being the original software.
23 *
24 * 3. This notice may not be removed or altered from any source
25 * distribution.
26 *
27 *************************************************************************/
28
29#ifndef _glfw3_h_
30#define _glfw3_h_
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36
37/*************************************************************************
38 * Doxygen documentation
39 *************************************************************************/
40
41/*! @file glfw3.h
42 * @brief The header of the GLFW 3 API.
43 *
44 * This is the header file of the GLFW 3 API. It defines all its types and
45 * declares all its functions.
46 *
47 * For more information about how to use this file, see @ref build_include.
48 */
49/*! @defgroup context Context reference
50 *
51 * This is the reference documentation for OpenGL and OpenGL ES context related
52 * functions. For more task-oriented information, see the @ref context_guide.
53 */
54/*! @defgroup vulkan Vulkan reference
55 *
56 * This is the reference documentation for Vulkan related functions and types.
57 * For more task-oriented information, see the @ref vulkan_guide.
58 */
59/*! @defgroup init Initialization, version and error reference
60 *
61 * This is the reference documentation for initialization and termination of
62 * the library, version management and error handling. For more task-oriented
63 * information, see the @ref intro_guide.
64 */
65/*! @defgroup input Input reference
66 *
67 * This is the reference documentation for input related functions and types.
68 * For more task-oriented information, see the @ref input_guide.
69 */
70/*! @defgroup monitor Monitor reference
71 *
72 * This is the reference documentation for monitor related functions and types.
73 * For more task-oriented information, see the @ref monitor_guide.
74 */
75/*! @defgroup window Window reference
76 *
77 * This is the reference documentation for window related functions and types,
78 * including creation, deletion and event polling. For more task-oriented
79 * information, see the @ref window_guide.
80 */
81
82
83/*************************************************************************
84 * Compiler- and platform-specific preprocessor work
85 *************************************************************************/
86
87/* If we are we on Windows, we want a single define for it.
88 */
89#if !defined(_WIN32) && (defined(__WIN32__) || defined(WIN32) || defined(__MINGW32__))
90 #define _WIN32
91#endif /* _WIN32 */
92
93/* It is customary to use APIENTRY for OpenGL function pointer declarations on
94 * all platforms. Additionally, the Windows OpenGL header needs APIENTRY.
95 */
96#ifndef APIENTRY
97 #ifdef _WIN32
98 #define APIENTRY __stdcall
99 #else
100 #define APIENTRY
101 #endif
102#endif /* APIENTRY */
103
104/* Some Windows OpenGL headers need this.
105 */
106#if !defined(WINGDIAPI) && defined(_WIN32)
107 #define WINGDIAPI __declspec(dllimport)
108 #define GLFW_WINGDIAPI_DEFINED
109#endif /* WINGDIAPI */
110
111/* Some Windows GLU headers need this.
112 */
113#if !defined(CALLBACK) && defined(_WIN32)
114 #define CALLBACK __stdcall
115 #define GLFW_CALLBACK_DEFINED
116#endif /* CALLBACK */
117
118/* Include because most Windows GLU headers need wchar_t and
119 * the OS X OpenGL header blocks the definition of ptrdiff_t by glext.h.
120 * Include it unconditionally to avoid surprising side-effects.
121 */
122#include <stddef.h>
123
124/* Include because it is needed by Vulkan and related functions.
125 */
126#include <stdint.h>
127
128/* Include the chosen client API headers.
129 */
130#if defined(__APPLE__)
131 #if defined(GLFW_INCLUDE_GLCOREARB)
132 #include <OpenGL/gl3.h>
133 #if defined(GLFW_INCLUDE_GLEXT)
134 #include <OpenGL/gl3ext.h>
135 #endif
136 #elif !defined(GLFW_INCLUDE_NONE)
137 #if !defined(GLFW_INCLUDE_GLEXT)
138 #define GL_GLEXT_LEGACY
139 #endif
140 #include <OpenGL/gl.h>
141 #endif
142 #if defined(GLFW_INCLUDE_GLU)
143 #include <OpenGL/glu.h>
144 #endif
145#else
146 #if defined(GLFW_INCLUDE_GLCOREARB)
147 #include <GL/glcorearb.h>
148 #elif defined(GLFW_INCLUDE_ES1)
149 #include <GLES/gl.h>
150 #if defined(GLFW_INCLUDE_GLEXT)
151 #include <GLES/glext.h>
152 #endif
153 #elif defined(GLFW_INCLUDE_ES2)
154 #include <GLES2/gl2.h>
155 #if defined(GLFW_INCLUDE_GLEXT)
156 #include <GLES2/gl2ext.h>
157 #endif
158 #elif defined(GLFW_INCLUDE_ES3)
159 #include <GLES3/gl3.h>
160 #if defined(GLFW_INCLUDE_GLEXT)
161 #include <GLES2/gl2ext.h>
162 #endif
163 #elif defined(GLFW_INCLUDE_ES31)
164 #include <GLES3/gl31.h>
165 #if defined(GLFW_INCLUDE_GLEXT)
166 #include <GLES2/gl2ext.h>
167 #endif
168 #elif defined(GLFW_INCLUDE_VULKAN)
169 #include <vulkan/vulkan.h>
170 #elif !defined(GLFW_INCLUDE_NONE)
171 #include <GL/gl.h>
172 #if defined(GLFW_INCLUDE_GLEXT)
173 #include <GL/glext.h>
174 #endif
175 #endif
176 #if defined(GLFW_INCLUDE_GLU)
177 #include <GL/glu.h>
178 #endif
179#endif
180
181#if defined(GLFW_DLL) && defined(_GLFW_BUILD_DLL)
182 /* GLFW_DLL must be defined by applications that are linking against the DLL
183 * version of the GLFW library. _GLFW_BUILD_DLL is defined by the GLFW
184 * configuration header when compiling the DLL version of the library.
185 */
186 #error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
187#endif
188
189/* GLFWAPI is used to declare public API functions for export
190 * from the DLL / shared library / dynamic library.
191 */
192#if defined(_WIN32) && defined(_GLFW_BUILD_DLL)
193 /* We are building GLFW as a Win32 DLL */
194 #define GLFWAPI __declspec(dllexport)
195#elif defined(_WIN32) && defined(GLFW_DLL)
196 /* We are calling GLFW as a Win32 DLL */
197 #define GLFWAPI __declspec(dllimport)
198#elif defined(__GNUC__) && defined(_GLFW_BUILD_DLL)
199 /* We are building GLFW as a shared / dynamic library */
200 #define GLFWAPI __attribute__((visibility("default")))
201#else
202 /* We are building or calling GLFW as a static library */
203 #define GLFWAPI
204#endif
205
206
207/*************************************************************************
208 * GLFW API tokens
209 *************************************************************************/
210
211/*! @name GLFW version macros
212 * @{ */
213/*! @brief The major version number of the GLFW library.
214 *
215 * This is incremented when the API is changed in non-compatible ways.
216 * @ingroup init
217 */
218#define GLFW_VERSION_MAJOR 3
219/*! @brief The minor version number of the GLFW library.
220 *
221 * This is incremented when features are added to the API but it remains
222 * backward-compatible.
223 * @ingroup init
224 */
225#define GLFW_VERSION_MINOR 2
226/*! @brief The revision number of the GLFW library.
227 *
228 * This is incremented when a bug fix release is made that does not contain any
229 * API changes.
230 * @ingroup init
231 */
232#define GLFW_VERSION_REVISION 1
233/*! @} */
234
235/*! @name Boolean values
236 * @{ */
237/*! @brief One.
238 *
239 * One. Seriously. You don't _need_ to use this symbol in your code. It's
240 * just semantic sugar for the number 1. You can use `1` or `true` or `_True`
241 * or `GL_TRUE` or whatever you want.
242 */
243#define GLFW_TRUE 1
244/*! @brief Zero.
245 *
246 * Zero. Seriously. You don't _need_ to use this symbol in your code. It's
247 * just just semantic sugar for the number 0. You can use `0` or `false` or
248 * `_False` or `GL_FALSE` or whatever you want.
249 */
250#define GLFW_FALSE 0
251/*! @} */
252
253/*! @name Key and button actions
254 * @{ */
255/*! @brief The key or mouse button was released.
256 *
257 * The key or mouse button was released.
258 *
259 * @ingroup input
260 */
261#define GLFW_RELEASE 0
262/*! @brief The key or mouse button was pressed.
263 *
264 * The key or mouse button was pressed.
265 *
266 * @ingroup input
267 */
268#define GLFW_PRESS 1
269/*! @brief The key was held down until it repeated.
270 *
271 * The key was held down until it repeated.
272 *
273 * @ingroup input
274 */
275#define GLFW_REPEAT 2
276/*! @} */
277
278/*! @defgroup keys Keyboard keys
279 *
280 * See [key input](@ref input_key) for how these are used.
281 *
282 * These key codes are inspired by the _USB HID Usage Tables v1.12_ (p. 53-60),
283 * but re-arranged to map to 7-bit ASCII for printable keys (function keys are
284 * put in the 256+ range).
285 *
286 * The naming of the key codes follow these rules:
287 * - The US keyboard layout is used
288 * - Names of printable alpha-numeric characters are used (e.g. "A", "R",
289 * "3", etc.)
290 * - For non-alphanumeric characters, Unicode:ish names are used (e.g.
291 * "COMMA", "LEFT_SQUARE_BRACKET", etc.). Note that some names do not
292 * correspond to the Unicode standard (usually for brevity)
293 * - Keys that lack a clear US mapping are named "WORLD_x"
294 * - For non-printable keys, custom names are used (e.g. "F4",
295 * "BACKSPACE", etc.)
296 *
297 * @ingroup input
298 * @{
299 */
300
301/* The unknown key */
302#define GLFW_KEY_UNKNOWN -1
303
304/* Printable keys */
305#define GLFW_KEY_SPACE 32
306#define GLFW_KEY_APOSTROPHE 39 /* ' */
307#define GLFW_KEY_COMMA 44 /* , */
308#define GLFW_KEY_MINUS 45 /* - */
309#define GLFW_KEY_PERIOD 46 /* . */
310#define GLFW_KEY_SLASH 47 /* / */
311#define GLFW_KEY_0 48
312#define GLFW_KEY_1 49
313#define GLFW_KEY_2 50
314#define GLFW_KEY_3 51
315#define GLFW_KEY_4 52
316#define GLFW_KEY_5 53
317#define GLFW_KEY_6 54
318#define GLFW_KEY_7 55
319#define GLFW_KEY_8 56
320#define GLFW_KEY_9 57
321#define GLFW_KEY_SEMICOLON 59 /* ; */
322#define GLFW_KEY_EQUAL 61 /* = */
323#define GLFW_KEY_A 65
324#define GLFW_KEY_B 66
325#define GLFW_KEY_C 67
326#define GLFW_KEY_D 68
327#define GLFW_KEY_E 69
328#define GLFW_KEY_F 70
329#define GLFW_KEY_G 71
330#define GLFW_KEY_H 72
331#define GLFW_KEY_I 73
332#define GLFW_KEY_J 74
333#define GLFW_KEY_K 75
334#define GLFW_KEY_L 76
335#define GLFW_KEY_M 77
336#define GLFW_KEY_N 78
337#define GLFW_KEY_O 79
338#define GLFW_KEY_P 80
339#define GLFW_KEY_Q 81
340#define GLFW_KEY_R 82
341#define GLFW_KEY_S 83
342#define GLFW_KEY_T 84
343#define GLFW_KEY_U 85
344#define GLFW_KEY_V 86
345#define GLFW_KEY_W 87
346#define GLFW_KEY_X 88
347#define GLFW_KEY_Y 89
348#define GLFW_KEY_Z 90
349#define GLFW_KEY_LEFT_BRACKET 91 /* [ */
350#define GLFW_KEY_BACKSLASH 92 /* \ */
351#define GLFW_KEY_RIGHT_BRACKET 93 /* ] */
352#define GLFW_KEY_GRAVE_ACCENT 96 /* ` */
353#define GLFW_KEY_WORLD_1 161 /* non-US #1 */
354#define GLFW_KEY_WORLD_2 162 /* non-US #2 */
355
356/* Function keys */
357#define GLFW_KEY_ESCAPE 256
358#define GLFW_KEY_ENTER 257
359#define GLFW_KEY_TAB 258
360#define GLFW_KEY_BACKSPACE 259
361#define GLFW_KEY_INSERT 260
362#define GLFW_KEY_DELETE 261
363#define GLFW_KEY_RIGHT 262
364#define GLFW_KEY_LEFT 263
365#define GLFW_KEY_DOWN 264
366#define GLFW_KEY_UP 265
367#define GLFW_KEY_PAGE_UP 266
368#define GLFW_KEY_PAGE_DOWN 267
369#define GLFW_KEY_HOME 268
370#define GLFW_KEY_END 269
371#define GLFW_KEY_CAPS_LOCK 280
372#define GLFW_KEY_SCROLL_LOCK 281
373#define GLFW_KEY_NUM_LOCK 282
374#define GLFW_KEY_PRINT_SCREEN 283
375#define GLFW_KEY_PAUSE 284
376#define GLFW_KEY_F1 290
377#define GLFW_KEY_F2 291
378#define GLFW_KEY_F3 292
379#define GLFW_KEY_F4 293
380#define GLFW_KEY_F5 294
381#define GLFW_KEY_F6 295
382#define GLFW_KEY_F7 296
383#define GLFW_KEY_F8 297
384#define GLFW_KEY_F9 298
385#define GLFW_KEY_F10 299
386#define GLFW_KEY_F11 300
387#define GLFW_KEY_F12 301
388#define GLFW_KEY_F13 302
389#define GLFW_KEY_F14 303
390#define GLFW_KEY_F15 304
391#define GLFW_KEY_F16 305
392#define GLFW_KEY_F17 306
393#define GLFW_KEY_F18 307
394#define GLFW_KEY_F19 308
395#define GLFW_KEY_F20 309
396#define GLFW_KEY_F21 310
397#define GLFW_KEY_F22 311
398#define GLFW_KEY_F23 312
399#define GLFW_KEY_F24 313
400#define GLFW_KEY_F25 314
401#define GLFW_KEY_KP_0 320
402#define GLFW_KEY_KP_1 321
403#define GLFW_KEY_KP_2 322
404#define GLFW_KEY_KP_3 323
405#define GLFW_KEY_KP_4 324
406#define GLFW_KEY_KP_5 325
407#define GLFW_KEY_KP_6 326
408#define GLFW_KEY_KP_7 327
409#define GLFW_KEY_KP_8 328
410#define GLFW_KEY_KP_9 329
411#define GLFW_KEY_KP_DECIMAL 330
412#define GLFW_KEY_KP_DIVIDE 331
413#define GLFW_KEY_KP_MULTIPLY 332
414#define GLFW_KEY_KP_SUBTRACT 333
415#define GLFW_KEY_KP_ADD 334
416#define GLFW_KEY_KP_ENTER 335
417#define GLFW_KEY_KP_EQUAL 336
418#define GLFW_KEY_LEFT_SHIFT 340
419#define GLFW_KEY_LEFT_CONTROL 341
420#define GLFW_KEY_LEFT_ALT 342
421#define GLFW_KEY_LEFT_SUPER 343
422#define GLFW_KEY_RIGHT_SHIFT 344
423#define GLFW_KEY_RIGHT_CONTROL 345
424#define GLFW_KEY_RIGHT_ALT 346
425#define GLFW_KEY_RIGHT_SUPER 347
426#define GLFW_KEY_MENU 348
427
428#define GLFW_KEY_LAST GLFW_KEY_MENU
429
430/*! @} */
431
432/*! @defgroup mods Modifier key flags
433 *
434 * See [key input](@ref input_key) for how these are used.
435 *
436 * @ingroup input
437 * @{ */
438
439/*! @brief If this bit is set one or more Shift keys were held down.
440 */
441#define GLFW_MOD_SHIFT 0x0001
442/*! @brief If this bit is set one or more Control keys were held down.
443 */
444#define GLFW_MOD_CONTROL 0x0002
445/*! @brief If this bit is set one or more Alt keys were held down.
446 */
447#define GLFW_MOD_ALT 0x0004
448/*! @brief If this bit is set one or more Super keys were held down.
449 */
450#define GLFW_MOD_SUPER 0x0008
451
452/*! @} */
453
454/*! @defgroup buttons Mouse buttons
455 *
456 * See [mouse button input](@ref input_mouse_button) for how these are used.
457 *
458 * @ingroup input
459 * @{ */
460#define GLFW_MOUSE_BUTTON_1 0
461#define GLFW_MOUSE_BUTTON_2 1
462#define GLFW_MOUSE_BUTTON_3 2
463#define GLFW_MOUSE_BUTTON_4 3
464#define GLFW_MOUSE_BUTTON_5 4
465#define GLFW_MOUSE_BUTTON_6 5
466#define GLFW_MOUSE_BUTTON_7 6
467#define GLFW_MOUSE_BUTTON_8 7
468#define GLFW_MOUSE_BUTTON_LAST GLFW_MOUSE_BUTTON_8
469#define GLFW_MOUSE_BUTTON_LEFT GLFW_MOUSE_BUTTON_1
470#define GLFW_MOUSE_BUTTON_RIGHT GLFW_MOUSE_BUTTON_2
471#define GLFW_MOUSE_BUTTON_MIDDLE GLFW_MOUSE_BUTTON_3
472/*! @} */
473
474/*! @defgroup joysticks Joysticks
475 *
476 * See [joystick input](@ref joystick) for how these are used.
477 *
478 * @ingroup input
479 * @{ */
480#define GLFW_JOYSTICK_1 0
481#define GLFW_JOYSTICK_2 1
482#define GLFW_JOYSTICK_3 2
483#define GLFW_JOYSTICK_4 3
484#define GLFW_JOYSTICK_5 4
485#define GLFW_JOYSTICK_6 5
486#define GLFW_JOYSTICK_7 6
487#define GLFW_JOYSTICK_8 7
488#define GLFW_JOYSTICK_9 8
489#define GLFW_JOYSTICK_10 9
490#define GLFW_JOYSTICK_11 10
491#define GLFW_JOYSTICK_12 11
492#define GLFW_JOYSTICK_13 12
493#define GLFW_JOYSTICK_14 13
494#define GLFW_JOYSTICK_15 14
495#define GLFW_JOYSTICK_16 15
496#define GLFW_JOYSTICK_LAST GLFW_JOYSTICK_16
497/*! @} */
498
499/*! @defgroup errors Error codes
500 *
501 * See [error handling](@ref error_handling) for how these are used.
502 *
503 * @ingroup init
504 * @{ */
505/*! @brief GLFW has not been initialized.
506 *
507 * This occurs if a GLFW function was called that must not be called unless the
508 * library is [initialized](@ref intro_init).
509 *
510 * @analysis Application programmer error. Initialize GLFW before calling any
511 * function that requires initialization.
512 */
513#define GLFW_NOT_INITIALIZED 0x00010001
514/*! @brief No context is current for this thread.
515 *
516 * This occurs if a GLFW function was called that needs and operates on the
517 * current OpenGL or OpenGL ES context but no context is current on the calling
518 * thread. One such function is @ref glfwSwapInterval.
519 *
520 * @analysis Application programmer error. Ensure a context is current before
521 * calling functions that require a current context.
522 */
523#define GLFW_NO_CURRENT_CONTEXT 0x00010002
524/*! @brief One of the arguments to the function was an invalid enum value.
525 *
526 * One of the arguments to the function was an invalid enum value, for example
527 * requesting [GLFW_RED_BITS](@ref window_hints_fb) with @ref
528 * glfwGetWindowAttrib.
529 *
530 * @analysis Application programmer error. Fix the offending call.
531 */
532#define GLFW_INVALID_ENUM 0x00010003
533/*! @brief One of the arguments to the function was an invalid value.
534 *
535 * One of the arguments to the function was an invalid value, for example
536 * requesting a non-existent OpenGL or OpenGL ES version like 2.7.
537 *
538 * Requesting a valid but unavailable OpenGL or OpenGL ES version will instead
539 * result in a @ref GLFW_VERSION_UNAVAILABLE error.
540 *
541 * @analysis Application programmer error. Fix the offending call.
542 */
543#define GLFW_INVALID_VALUE 0x00010004
544/*! @brief A memory allocation failed.
545 *
546 * A memory allocation failed.
547 *
548 * @analysis A bug in GLFW or the underlying operating system. Report the bug
549 * to our [issue tracker](https://github.com/glfw/glfw/issues).
550 */
551#define GLFW_OUT_OF_MEMORY 0x00010005
552/*! @brief GLFW could not find support for the requested API on the system.
553 *
554 * GLFW could not find support for the requested API on the system.
555 *
556 * @analysis The installed graphics driver does not support the requested
557 * API, or does not support it via the chosen context creation backend.
558 * Below are a few examples.
559 *
560 * @par
561 * Some pre-installed Windows graphics drivers do not support OpenGL. AMD only
562 * supports OpenGL ES via EGL, while Nvidia and Intel only support it via
563 * a WGL or GLX extension. OS X does not provide OpenGL ES at all. The Mesa
564 * EGL, OpenGL and OpenGL ES libraries do not interface with the Nvidia binary
565 * driver. Older graphics drivers do not support Vulkan.
566 */
567#define GLFW_API_UNAVAILABLE 0x00010006
568/*! @brief The requested OpenGL or OpenGL ES version is not available.
569 *
570 * The requested OpenGL or OpenGL ES version (including any requested context
571 * or framebuffer hints) is not available on this machine.
572 *
573 * @analysis The machine does not support your requirements. If your
574 * application is sufficiently flexible, downgrade your requirements and try
575 * again. Otherwise, inform the user that their machine does not match your
576 * requirements.
577 *
578 * @par
579 * Future invalid OpenGL and OpenGL ES versions, for example OpenGL 4.8 if 5.0
580 * comes out before the 4.x series gets that far, also fail with this error and
581 * not @ref GLFW_INVALID_VALUE, because GLFW cannot know what future versions
582 * will exist.
583 */
584#define GLFW_VERSION_UNAVAILABLE 0x00010007
585/*! @brief A platform-specific error occurred that does not match any of the
586 * more specific categories.
587 *
588 * A platform-specific error occurred that does not match any of the more
589 * specific categories.
590 *
591 * @analysis A bug or configuration error in GLFW, the underlying operating
592 * system or its drivers, or a lack of required resources. Report the issue to
593 * our [issue tracker](https://github.com/glfw/glfw/issues).
594 */
595#define GLFW_PLATFORM_ERROR 0x00010008
596/*! @brief The requested format is not supported or available.
597 *
598 * If emitted during window creation, the requested pixel format is not
599 * supported.
600 *
601 * If emitted when querying the clipboard, the contents of the clipboard could
602 * not be converted to the requested format.
603 *
604 * @analysis If emitted during window creation, one or more
605 * [hard constraints](@ref window_hints_hard) did not match any of the
606 * available pixel formats. If your application is sufficiently flexible,
607 * downgrade your requirements and try again. Otherwise, inform the user that
608 * their machine does not match your requirements.
609 *
610 * @par
611 * If emitted when querying the clipboard, ignore the error or report it to
612 * the user, as appropriate.
613 */
614#define GLFW_FORMAT_UNAVAILABLE 0x00010009
615/*! @brief The specified window does not have an OpenGL or OpenGL ES context.
616 *
617 * A window that does not have an OpenGL or OpenGL ES context was passed to
618 * a function that requires it to have one.
619 *
620 * @analysis Application programmer error. Fix the offending call.
621 */
622#define GLFW_NO_WINDOW_CONTEXT 0x0001000A
623/*! @} */
624
625#define GLFW_FOCUSED 0x00020001
626#define GLFW_ICONIFIED 0x00020002
627#define GLFW_RESIZABLE 0x00020003
628#define GLFW_VISIBLE 0x00020004
629#define GLFW_DECORATED 0x00020005
630#define GLFW_AUTO_ICONIFY 0x00020006
631#define GLFW_FLOATING 0x00020007
632#define GLFW_MAXIMIZED 0x00020008
633
634#define GLFW_RED_BITS 0x00021001
635#define GLFW_GREEN_BITS 0x00021002
636#define GLFW_BLUE_BITS 0x00021003
637#define GLFW_ALPHA_BITS 0x00021004
638#define GLFW_DEPTH_BITS 0x00021005
639#define GLFW_STENCIL_BITS 0x00021006
640#define GLFW_ACCUM_RED_BITS 0x00021007
641#define GLFW_ACCUM_GREEN_BITS 0x00021008
642#define GLFW_ACCUM_BLUE_BITS 0x00021009
643#define GLFW_ACCUM_ALPHA_BITS 0x0002100A
644#define GLFW_AUX_BUFFERS 0x0002100B
645#define GLFW_STEREO 0x0002100C
646#define GLFW_SAMPLES 0x0002100D
647#define GLFW_SRGB_CAPABLE 0x0002100E
648#define GLFW_REFRESH_RATE 0x0002100F
649#define GLFW_DOUBLEBUFFER 0x00021010
650
651#define GLFW_CLIENT_API 0x00022001
652#define GLFW_CONTEXT_VERSION_MAJOR 0x00022002
653#define GLFW_CONTEXT_VERSION_MINOR 0x00022003
654#define GLFW_CONTEXT_REVISION 0x00022004
655#define GLFW_CONTEXT_ROBUSTNESS 0x00022005
656#define GLFW_OPENGL_FORWARD_COMPAT 0x00022006
657#define GLFW_OPENGL_DEBUG_CONTEXT 0x00022007
658#define GLFW_OPENGL_PROFILE 0x00022008
659#define GLFW_CONTEXT_RELEASE_BEHAVIOR 0x00022009
660#define GLFW_CONTEXT_NO_ERROR 0x0002200A
661#define GLFW_CONTEXT_CREATION_API 0x0002200B
662
663#define GLFW_NO_API 0
664#define GLFW_OPENGL_API 0x00030001
665#define GLFW_OPENGL_ES_API 0x00030002
666
667#define GLFW_NO_ROBUSTNESS 0
668#define GLFW_NO_RESET_NOTIFICATION 0x00031001
669#define GLFW_LOSE_CONTEXT_ON_RESET 0x00031002
670
671#define GLFW_OPENGL_ANY_PROFILE 0
672#define GLFW_OPENGL_CORE_PROFILE 0x00032001
673#define GLFW_OPENGL_COMPAT_PROFILE 0x00032002
674
675#define GLFW_CURSOR 0x00033001
676#define GLFW_STICKY_KEYS 0x00033002
677#define GLFW_STICKY_MOUSE_BUTTONS 0x00033003
678
679#define GLFW_CURSOR_NORMAL 0x00034001
680#define GLFW_CURSOR_HIDDEN 0x00034002
681#define GLFW_CURSOR_DISABLED 0x00034003
682
683#define GLFW_ANY_RELEASE_BEHAVIOR 0
684#define GLFW_RELEASE_BEHAVIOR_FLUSH 0x00035001
685#define GLFW_RELEASE_BEHAVIOR_NONE 0x00035002
686
687#define GLFW_NATIVE_CONTEXT_API 0x00036001
688#define GLFW_EGL_CONTEXT_API 0x00036002
689
690/*! @defgroup shapes Standard cursor shapes
691 *
692 * See [standard cursor creation](@ref cursor_standard) for how these are used.
693 *
694 * @ingroup input
695 * @{ */
696
697/*! @brief The regular arrow cursor shape.
698 *
699 * The regular arrow cursor.
700 */
701#define GLFW_ARROW_CURSOR 0x00036001
702/*! @brief The text input I-beam cursor shape.
703 *
704 * The text input I-beam cursor shape.
705 */
706#define GLFW_IBEAM_CURSOR 0x00036002
707/*! @brief The crosshair shape.
708 *
709 * The crosshair shape.
710 */
711#define GLFW_CROSSHAIR_CURSOR 0x00036003
712/*! @brief The hand shape.
713 *
714 * The hand shape.
715 */
716#define GLFW_HAND_CURSOR 0x00036004
717/*! @brief The horizontal resize arrow shape.
718 *
719 * The horizontal resize arrow shape.
720 */
721#define GLFW_HRESIZE_CURSOR 0x00036005
722/*! @brief The vertical resize arrow shape.
723 *
724 * The vertical resize arrow shape.
725 */
726#define GLFW_VRESIZE_CURSOR 0x00036006
727/*! @} */
728
729#define GLFW_CONNECTED 0x00040001
730#define GLFW_DISCONNECTED 0x00040002
731
732#define GLFW_DONT_CARE -1
733
734
735/*************************************************************************
736 * GLFW API types
737 *************************************************************************/
738
739/*! @brief Client API function pointer type.
740 *
741 * Generic function pointer used for returning client API function pointers
742 * without forcing a cast from a regular pointer.
743 *
744 * @sa @ref context_glext
745 * @sa glfwGetProcAddress
746 *
747 * @since Added in version 3.0.
748
749 * @ingroup context
750 */
751typedef void (*GLFWglproc)(void);
752
753/*! @brief Vulkan API function pointer type.
754 *
755 * Generic function pointer used for returning Vulkan API function pointers
756 * without forcing a cast from a regular pointer.
757 *
758 * @sa @ref vulkan_proc
759 * @sa glfwGetInstanceProcAddress
760 *
761 * @since Added in version 3.2.
762 *
763 * @ingroup vulkan
764 */
765typedef void (*GLFWvkproc)(void);
766
767/*! @brief Opaque monitor object.
768 *
769 * Opaque monitor object.
770 *
771 * @see @ref monitor_object
772 *
773 * @since Added in version 3.0.
774 *
775 * @ingroup monitor
776 */
777typedef struct GLFWmonitor GLFWmonitor;
778
779/*! @brief Opaque window object.
780 *
781 * Opaque window object.
782 *
783 * @see @ref window_object
784 *
785 * @since Added in version 3.0.
786 *
787 * @ingroup window
788 */
789typedef struct GLFWwindow GLFWwindow;
790
791/*! @brief Opaque cursor object.
792 *
793 * Opaque cursor object.
794 *
795 * @see @ref cursor_object
796 *
797 * @since Added in version 3.1.
798 *
799 * @ingroup cursor
800 */
801typedef struct GLFWcursor GLFWcursor;
802
803/*! @brief The function signature for error callbacks.
804 *
805 * This is the function signature for error callback functions.
806 *
807 * @param[in] error An [error code](@ref errors).
808 * @param[in] description A UTF-8 encoded string describing the error.
809 *
810 * @sa @ref error_handling
811 * @sa glfwSetErrorCallback
812 *
813 * @since Added in version 3.0.
814 *
815 * @ingroup init
816 */
817typedef void (* GLFWerrorfun)(int,const char*);
818
819/*! @brief The function signature for window position callbacks.
820 *
821 * This is the function signature for window position callback functions.
822 *
823 * @param[in] window The window that was moved.
824 * @param[in] xpos The new x-coordinate, in screen coordinates, of the
825 * upper-left corner of the client area of the window.
826 * @param[in] ypos The new y-coordinate, in screen coordinates, of the
827 * upper-left corner of the client area of the window.
828 *
829 * @sa @ref window_pos
830 * @sa glfwSetWindowPosCallback
831 *
832 * @since Added in version 3.0.
833 *
834 * @ingroup window
835 */
836typedef void (* GLFWwindowposfun)(GLFWwindow*,int,int);
837
838/*! @brief The function signature for window resize callbacks.
839 *
840 * This is the function signature for window size callback functions.
841 *
842 * @param[in] window The window that was resized.
843 * @param[in] width The new width, in screen coordinates, of the window.
844 * @param[in] height The new height, in screen coordinates, of the window.
845 *
846 * @sa @ref window_size
847 * @sa glfwSetWindowSizeCallback
848 *
849 * @since Added in version 1.0.
850 * @glfw3 Added window handle parameter.
851 *
852 * @ingroup window
853 */
854typedef void (* GLFWwindowsizefun)(GLFWwindow*,int,int);
855
856/*! @brief The function signature for window close callbacks.
857 *
858 * This is the function signature for window close callback functions.
859 *
860 * @param[in] window The window that the user attempted to close.
861 *
862 * @sa @ref window_close
863 * @sa glfwSetWindowCloseCallback
864 *
865 * @since Added in version 2.5.
866 * @glfw3 Added window handle parameter.
867 *
868 * @ingroup window
869 */
870typedef void (* GLFWwindowclosefun)(GLFWwindow*);
871
872/*! @brief The function signature for window content refresh callbacks.
873 *
874 * This is the function signature for window refresh callback functions.
875 *
876 * @param[in] window The window whose content needs to be refreshed.
877 *
878 * @sa @ref window_refresh
879 * @sa glfwSetWindowRefreshCallback
880 *
881 * @since Added in version 2.5.
882 * @glfw3 Added window handle parameter.
883 *
884 * @ingroup window
885 */
886typedef void (* GLFWwindowrefreshfun)(GLFWwindow*);
887
888/*! @brief The function signature for window focus/defocus callbacks.
889 *
890 * This is the function signature for window focus callback functions.
891 *
892 * @param[in] window The window that gained or lost input focus.
893 * @param[in] focused `GLFW_TRUE` if the window was given input focus, or
894 * `GLFW_FALSE` if it lost it.
895 *
896 * @sa @ref window_focus
897 * @sa glfwSetWindowFocusCallback
898 *
899 * @since Added in version 3.0.
900 *
901 * @ingroup window
902 */
903typedef void (* GLFWwindowfocusfun)(GLFWwindow*,int);
904
905/*! @brief The function signature for window iconify/restore callbacks.
906 *
907 * This is the function signature for window iconify/restore callback
908 * functions.
909 *
910 * @param[in] window The window that was iconified or restored.
911 * @param[in] iconified `GLFW_TRUE` if the window was iconified, or
912 * `GLFW_FALSE` if it was restored.
913 *
914 * @sa @ref window_iconify
915 * @sa glfwSetWindowIconifyCallback
916 *
917 * @since Added in version 3.0.
918 *
919 * @ingroup window
920 */
921typedef void (* GLFWwindowiconifyfun)(GLFWwindow*,int);
922
923/*! @brief The function signature for framebuffer resize callbacks.
924 *
925 * This is the function signature for framebuffer resize callback
926 * functions.
927 *
928 * @param[in] window The window whose framebuffer was resized.
929 * @param[in] width The new width, in pixels, of the framebuffer.
930 * @param[in] height The new height, in pixels, of the framebuffer.
931 *
932 * @sa @ref window_fbsize
933 * @sa glfwSetFramebufferSizeCallback
934 *
935 * @since Added in version 3.0.
936 *
937 * @ingroup window
938 */
939typedef void (* GLFWframebuffersizefun)(GLFWwindow*,int,int);
940
941/*! @brief The function signature for mouse button callbacks.
942 *
943 * This is the function signature for mouse button callback functions.
944 *
945 * @param[in] window The window that received the event.
946 * @param[in] button The [mouse button](@ref buttons) that was pressed or
947 * released.
948 * @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`.
949 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
950 * held down.
951 *
952 * @sa @ref input_mouse_button
953 * @sa glfwSetMouseButtonCallback
954 *
955 * @since Added in version 1.0.
956 * @glfw3 Added window handle and modifier mask parameters.
957 *
958 * @ingroup input
959 */
960typedef void (* GLFWmousebuttonfun)(GLFWwindow*,int,int,int);
961
962/*! @brief The function signature for cursor position callbacks.
963 *
964 * This is the function signature for cursor position callback functions.
965 *
966 * @param[in] window The window that received the event.
967 * @param[in] xpos The new cursor x-coordinate, relative to the left edge of
968 * the client area.
969 * @param[in] ypos The new cursor y-coordinate, relative to the top edge of the
970 * client area.
971 *
972 * @sa @ref cursor_pos
973 * @sa glfwSetCursorPosCallback
974 *
975 * @since Added in version 3.0. Replaces `GLFWmouseposfun`.
976 *
977 * @ingroup input
978 */
979typedef void (* GLFWcursorposfun)(GLFWwindow*,double,double);
980
981/*! @brief The function signature for cursor enter/leave callbacks.
982 *
983 * This is the function signature for cursor enter/leave callback functions.
984 *
985 * @param[in] window The window that received the event.
986 * @param[in] entered `GLFW_TRUE` if the cursor entered the window's client
987 * area, or `GLFW_FALSE` if it left it.
988 *
989 * @sa @ref cursor_enter
990 * @sa glfwSetCursorEnterCallback
991 *
992 * @since Added in version 3.0.
993 *
994 * @ingroup input
995 */
996typedef void (* GLFWcursorenterfun)(GLFWwindow*,int);
997
998/*! @brief The function signature for scroll callbacks.
999 *
1000 * This is the function signature for scroll callback functions.
1001 *
1002 * @param[in] window The window that received the event.
1003 * @param[in] xoffset The scroll offset along the x-axis.
1004 * @param[in] yoffset The scroll offset along the y-axis.
1005 *
1006 * @sa @ref scrolling
1007 * @sa glfwSetScrollCallback
1008 *
1009 * @since Added in version 3.0. Replaces `GLFWmousewheelfun`.
1010 *
1011 * @ingroup input
1012 */
1013typedef void (* GLFWscrollfun)(GLFWwindow*,double,double);
1014
1015/*! @brief The function signature for keyboard key callbacks.
1016 *
1017 * This is the function signature for keyboard key callback functions.
1018 *
1019 * @param[in] window The window that received the event.
1020 * @param[in] key The [keyboard key](@ref keys) that was pressed or released.
1021 * @param[in] scancode The system-specific scancode of the key.
1022 * @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`.
1023 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
1024 * held down.
1025 *
1026 * @sa @ref input_key
1027 * @sa glfwSetKeyCallback
1028 *
1029 * @since Added in version 1.0.
1030 * @glfw3 Added window handle, scancode and modifier mask parameters.
1031 *
1032 * @ingroup input
1033 */
1034typedef void (* GLFWkeyfun)(GLFWwindow*,int,int,int,int);
1035
1036/*! @brief The function signature for Unicode character callbacks.
1037 *
1038 * This is the function signature for Unicode character callback functions.
1039 *
1040 * @param[in] window The window that received the event.
1041 * @param[in] codepoint The Unicode code point of the character.
1042 *
1043 * @sa @ref input_char
1044 * @sa glfwSetCharCallback
1045 *
1046 * @since Added in version 2.4.
1047 * @glfw3 Added window handle parameter.
1048 *
1049 * @ingroup input
1050 */
1051typedef void (* GLFWcharfun)(GLFWwindow*,unsigned int);
1052
1053/*! @brief The function signature for Unicode character with modifiers
1054 * callbacks.
1055 *
1056 * This is the function signature for Unicode character with modifiers callback
1057 * functions. It is called for each input character, regardless of what
1058 * modifier keys are held down.
1059 *
1060 * @param[in] window The window that received the event.
1061 * @param[in] codepoint The Unicode code point of the character.
1062 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
1063 * held down.
1064 *
1065 * @sa @ref input_char
1066 * @sa glfwSetCharModsCallback
1067 *
1068 * @since Added in version 3.1.
1069 *
1070 * @ingroup input
1071 */
1072typedef void (* GLFWcharmodsfun)(GLFWwindow*,unsigned int,int);
1073
1074/*! @brief The function signature for file drop callbacks.
1075 *
1076 * This is the function signature for file drop callbacks.
1077 *
1078 * @param[in] window The window that received the event.
1079 * @param[in] count The number of dropped files.
1080 * @param[in] paths The UTF-8 encoded file and/or directory path names.
1081 *
1082 * @sa @ref path_drop
1083 * @sa glfwSetDropCallback
1084 *
1085 * @since Added in version 3.1.
1086 *
1087 * @ingroup input
1088 */
1089typedef void (* GLFWdropfun)(GLFWwindow*,int,const char**);
1090
1091/*! @brief The function signature for monitor configuration callbacks.
1092 *
1093 * This is the function signature for monitor configuration callback functions.
1094 *
1095 * @param[in] monitor The monitor that was connected or disconnected.
1096 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
1097 *
1098 * @sa @ref monitor_event
1099 * @sa glfwSetMonitorCallback
1100 *
1101 * @since Added in version 3.0.
1102 *
1103 * @ingroup monitor
1104 */
1105typedef void (* GLFWmonitorfun)(GLFWmonitor*,int);
1106
1107/*! @brief The function signature for joystick configuration callbacks.
1108 *
1109 * This is the function signature for joystick configuration callback
1110 * functions.
1111 *
1112 * @param[in] joy The joystick that was connected or disconnected.
1113 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`.
1114 *
1115 * @sa @ref joystick_event
1116 * @sa glfwSetJoystickCallback
1117 *
1118 * @since Added in version 3.2.
1119 *
1120 * @ingroup input
1121 */
1122typedef void (* GLFWjoystickfun)(int,int);
1123
1124/*! @brief Video mode type.
1125 *
1126 * This describes a single video mode.
1127 *
1128 * @sa @ref monitor_modes
1129 * @sa glfwGetVideoMode glfwGetVideoModes
1130 *
1131 * @since Added in version 1.0.
1132 * @glfw3 Added refresh rate member.
1133 *
1134 * @ingroup monitor
1135 */
1136typedef struct GLFWvidmode
1137{
1138 /*! The width, in screen coordinates, of the video mode.
1139 */
1140 int width;
1141 /*! The height, in screen coordinates, of the video mode.
1142 */
1143 int height;
1144 /*! The bit depth of the red channel of the video mode.
1145 */
1146 int redBits;
1147 /*! The bit depth of the green channel of the video mode.
1148 */
1149 int greenBits;
1150 /*! The bit depth of the blue channel of the video mode.
1151 */
1152 int blueBits;
1153 /*! The refresh rate, in Hz, of the video mode.
1154 */
1155 int refreshRate;
1156} GLFWvidmode;
1157
1158/*! @brief Gamma ramp.
1159 *
1160 * This describes the gamma ramp for a monitor.
1161 *
1162 * @sa @ref monitor_gamma
1163 * @sa glfwGetGammaRamp glfwSetGammaRamp
1164 *
1165 * @since Added in version 3.0.
1166 *
1167 * @ingroup monitor
1168 */
1169typedef struct GLFWgammaramp
1170{
1171 /*! An array of value describing the response of the red channel.
1172 */
1173 unsigned short* red;
1174 /*! An array of value describing the response of the green channel.
1175 */
1176 unsigned short* green;
1177 /*! An array of value describing the response of the blue channel.
1178 */
1179 unsigned short* blue;
1180 /*! The number of elements in each array.
1181 */
1182 unsigned int size;
1183} GLFWgammaramp;
1184
1185/*! @brief Image data.
1186 *
1187 * @sa @ref cursor_custom
1188 * @sa @ref window_icon
1189 *
1190 * @since Added in version 2.1.
1191 * @glfw3 Removed format and bytes-per-pixel members.
1192 */
1193typedef struct GLFWimage
1194{
1195 /*! The width, in pixels, of this image.
1196 */
1197 int width;
1198 /*! The height, in pixels, of this image.
1199 */
1200 int height;
1201 /*! The pixel data of this image, arranged left-to-right, top-to-bottom.
1202 */
1203 unsigned char* pixels;
1204} GLFWimage;
1205
1206
1207/*************************************************************************
1208 * GLFW API functions
1209 *************************************************************************/
1210
1211/*! @brief Initializes the GLFW library.
1212 *
1213 * This function initializes the GLFW library. Before most GLFW functions can
1214 * be used, GLFW must be initialized, and before an application terminates GLFW
1215 * should be terminated in order to free any resources allocated during or
1216 * after initialization.
1217 *
1218 * If this function fails, it calls @ref glfwTerminate before returning. If it
1219 * succeeds, you should call @ref glfwTerminate before the application exits.
1220 *
1221 * Additional calls to this function after successful initialization but before
1222 * termination will return `GLFW_TRUE` immediately.
1223 *
1224 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
1225 * [error](@ref error_handling) occurred.
1226 *
1227 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR.
1228 *
1229 * @remark @osx This function will change the current directory of the
1230 * application to the `Contents/Resources` subdirectory of the application's
1231 * bundle, if present. This can be disabled with a
1232 * [compile-time option](@ref compile_options_osx).
1233 *
1234 * @thread_safety This function must only be called from the main thread.
1235 *
1236 * @sa @ref intro_init
1237 * @sa glfwTerminate
1238 *
1239 * @since Added in version 1.0.
1240 *
1241 * @ingroup init
1242 */
1243GLFWAPI int glfwInit(void);
1244
1245/*! @brief Terminates the GLFW library.
1246 *
1247 * This function destroys all remaining windows and cursors, restores any
1248 * modified gamma ramps and frees any other allocated resources. Once this
1249 * function is called, you must again call @ref glfwInit successfully before
1250 * you will be able to use most GLFW functions.
1251 *
1252 * If GLFW has been successfully initialized, this function should be called
1253 * before the application exits. If initialization fails, there is no need to
1254 * call this function, as it is called by @ref glfwInit before it returns
1255 * failure.
1256 *
1257 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR.
1258 *
1259 * @remark This function may be called before @ref glfwInit.
1260 *
1261 * @warning The contexts of any remaining windows must not be current on any
1262 * other thread when this function is called.
1263 *
1264 * @reentrancy This function must not be called from a callback.
1265 *
1266 * @thread_safety This function must only be called from the main thread.
1267 *
1268 * @sa @ref intro_init
1269 * @sa glfwInit
1270 *
1271 * @since Added in version 1.0.
1272 *
1273 * @ingroup init
1274 */
1275GLFWAPI void glfwTerminate(void);
1276
1277/*! @brief Retrieves the version of the GLFW library.
1278 *
1279 * This function retrieves the major, minor and revision numbers of the GLFW
1280 * library. It is intended for when you are using GLFW as a shared library and
1281 * want to ensure that you are using the minimum required version.
1282 *
1283 * Any or all of the version arguments may be `NULL`.
1284 *
1285 * @param[out] major Where to store the major version number, or `NULL`.
1286 * @param[out] minor Where to store the minor version number, or `NULL`.
1287 * @param[out] rev Where to store the revision number, or `NULL`.
1288 *
1289 * @errors None.
1290 *
1291 * @remark This function may be called before @ref glfwInit.
1292 *
1293 * @thread_safety This function may be called from any thread.
1294 *
1295 * @sa @ref intro_version
1296 * @sa glfwGetVersionString
1297 *
1298 * @since Added in version 1.0.
1299 *
1300 * @ingroup init
1301 */
1302GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
1303
1304/*! @brief Returns a string describing the compile-time configuration.
1305 *
1306 * This function returns the compile-time generated
1307 * [version string](@ref intro_version_string) of the GLFW library binary. It
1308 * describes the version, platform, compiler and any platform-specific
1309 * compile-time options. It should not be confused with the OpenGL or OpenGL
1310 * ES version string, queried with `glGetString`.
1311 *
1312 * __Do not use the version string__ to parse the GLFW library version. The
1313 * @ref glfwGetVersion function provides the version of the running library
1314 * binary in numerical format.
1315 *
1316 * @return The ASCII encoded GLFW version string.
1317 *
1318 * @errors None.
1319 *
1320 * @remark This function may be called before @ref glfwInit.
1321 *
1322 * @pointer_lifetime The returned string is static and compile-time generated.
1323 *
1324 * @thread_safety This function may be called from any thread.
1325 *
1326 * @sa @ref intro_version
1327 * @sa glfwGetVersion
1328 *
1329 * @since Added in version 3.0.
1330 *
1331 * @ingroup init
1332 */
1333GLFWAPI const char* glfwGetVersionString(void);
1334
1335/*! @brief Sets the error callback.
1336 *
1337 * This function sets the error callback, which is called with an error code
1338 * and a human-readable description each time a GLFW error occurs.
1339 *
1340 * The error callback is called on the thread where the error occurred. If you
1341 * are using GLFW from multiple threads, your error callback needs to be
1342 * written accordingly.
1343 *
1344 * Because the description string may have been generated specifically for that
1345 * error, it is not guaranteed to be valid after the callback has returned. If
1346 * you wish to use it after the callback returns, you need to make a copy.
1347 *
1348 * Once set, the error callback remains set even after the library has been
1349 * terminated.
1350 *
1351 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
1352 * callback.
1353 * @return The previously set callback, or `NULL` if no callback was set.
1354 *
1355 * @errors None.
1356 *
1357 * @remark This function may be called before @ref glfwInit.
1358 *
1359 * @thread_safety This function must only be called from the main thread.
1360 *
1361 * @sa @ref error_handling
1362 *
1363 * @since Added in version 3.0.
1364 *
1365 * @ingroup init
1366 */
1367GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun);
1368
1369/*! @brief Returns the currently connected monitors.
1370 *
1371 * This function returns an array of handles for all currently connected
1372 * monitors. The primary monitor is always first in the returned array. If no
1373 * monitors were found, this function returns `NULL`.
1374 *
1375 * @param[out] count Where to store the number of monitors in the returned
1376 * array. This is set to zero if an error occurred.
1377 * @return An array of monitor handles, or `NULL` if no monitors were found or
1378 * if an [error](@ref error_handling) occurred.
1379 *
1380 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1381 *
1382 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
1383 * should not free it yourself. It is guaranteed to be valid only until the
1384 * monitor configuration changes or the library is terminated.
1385 *
1386 * @thread_safety This function must only be called from the main thread.
1387 *
1388 * @sa @ref monitor_monitors
1389 * @sa @ref monitor_event
1390 * @sa glfwGetPrimaryMonitor
1391 *
1392 * @since Added in version 3.0.
1393 *
1394 * @ingroup monitor
1395 */
1396GLFWAPI GLFWmonitor** glfwGetMonitors(int* count);
1397
1398/*! @brief Returns the primary monitor.
1399 *
1400 * This function returns the primary monitor. This is usually the monitor
1401 * where elements like the task bar or global menu bar are located.
1402 *
1403 * @return The primary monitor, or `NULL` if no monitors were found or if an
1404 * [error](@ref error_handling) occurred.
1405 *
1406 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1407 *
1408 * @thread_safety This function must only be called from the main thread.
1409 *
1410 * @remark The primary monitor is always first in the array returned by @ref
1411 * glfwGetMonitors.
1412 *
1413 * @sa @ref monitor_monitors
1414 * @sa glfwGetMonitors
1415 *
1416 * @since Added in version 3.0.
1417 *
1418 * @ingroup monitor
1419 */
1420GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void);
1421
1422/*! @brief Returns the position of the monitor's viewport on the virtual screen.
1423 *
1424 * This function returns the position, in screen coordinates, of the upper-left
1425 * corner of the specified monitor.
1426 *
1427 * Any or all of the position arguments may be `NULL`. If an error occurs, all
1428 * non-`NULL` position arguments will be set to zero.
1429 *
1430 * @param[in] monitor The monitor to query.
1431 * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`.
1432 * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`.
1433 *
1434 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1435 * GLFW_PLATFORM_ERROR.
1436 *
1437 * @thread_safety This function must only be called from the main thread.
1438 *
1439 * @sa @ref monitor_properties
1440 *
1441 * @since Added in version 3.0.
1442 *
1443 * @ingroup monitor
1444 */
1445GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos);
1446
1447/*! @brief Returns the physical size of the monitor.
1448 *
1449 * This function returns the size, in millimetres, of the display area of the
1450 * specified monitor.
1451 *
1452 * Some systems do not provide accurate monitor size information, either
1453 * because the monitor
1454 * [EDID](https://en.wikipedia.org/wiki/Extended_display_identification_data)
1455 * data is incorrect or because the driver does not report it accurately.
1456 *
1457 * Any or all of the size arguments may be `NULL`. If an error occurs, all
1458 * non-`NULL` size arguments will be set to zero.
1459 *
1460 * @param[in] monitor The monitor to query.
1461 * @param[out] widthMM Where to store the width, in millimetres, of the
1462 * monitor's display area, or `NULL`.
1463 * @param[out] heightMM Where to store the height, in millimetres, of the
1464 * monitor's display area, or `NULL`.
1465 *
1466 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1467 *
1468 * @remark @win32 calculates the returned physical size from the
1469 * current resolution and system DPI instead of querying the monitor EDID data.
1470 *
1471 * @thread_safety This function must only be called from the main thread.
1472 *
1473 * @sa @ref monitor_properties
1474 *
1475 * @since Added in version 3.0.
1476 *
1477 * @ingroup monitor
1478 */
1479GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* heightMM);
1480
1481/*! @brief Returns the name of the specified monitor.
1482 *
1483 * This function returns a human-readable name, encoded as UTF-8, of the
1484 * specified monitor. The name typically reflects the make and model of the
1485 * monitor and is not guaranteed to be unique among the connected monitors.
1486 *
1487 * @param[in] monitor The monitor to query.
1488 * @return The UTF-8 encoded name of the monitor, or `NULL` if an
1489 * [error](@ref error_handling) occurred.
1490 *
1491 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1492 *
1493 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
1494 * should not free it yourself. It is valid until the specified monitor is
1495 * disconnected or the library is terminated.
1496 *
1497 * @thread_safety This function must only be called from the main thread.
1498 *
1499 * @sa @ref monitor_properties
1500 *
1501 * @since Added in version 3.0.
1502 *
1503 * @ingroup monitor
1504 */
1505GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
1506
1507/*! @brief Sets the monitor configuration callback.
1508 *
1509 * This function sets the monitor configuration callback, or removes the
1510 * currently set callback. This is called when a monitor is connected to or
1511 * disconnected from the system.
1512 *
1513 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
1514 * callback.
1515 * @return The previously set callback, or `NULL` if no callback was set or the
1516 * library had not been [initialized](@ref intro_init).
1517 *
1518 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1519 *
1520 * @thread_safety This function must only be called from the main thread.
1521 *
1522 * @sa @ref monitor_event
1523 *
1524 * @since Added in version 3.0.
1525 *
1526 * @ingroup monitor
1527 */
1528GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
1529
1530/*! @brief Returns the available video modes for the specified monitor.
1531 *
1532 * This function returns an array of all video modes supported by the specified
1533 * monitor. The returned array is sorted in ascending order, first by color
1534 * bit depth (the sum of all channel depths) and then by resolution area (the
1535 * product of width and height).
1536 *
1537 * @param[in] monitor The monitor to query.
1538 * @param[out] count Where to store the number of video modes in the returned
1539 * array. This is set to zero if an error occurred.
1540 * @return An array of video modes, or `NULL` if an
1541 * [error](@ref error_handling) occurred.
1542 *
1543 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1544 * GLFW_PLATFORM_ERROR.
1545 *
1546 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
1547 * should not free it yourself. It is valid until the specified monitor is
1548 * disconnected, this function is called again for that monitor or the library
1549 * is terminated.
1550 *
1551 * @thread_safety This function must only be called from the main thread.
1552 *
1553 * @sa @ref monitor_modes
1554 * @sa glfwGetVideoMode
1555 *
1556 * @since Added in version 1.0.
1557 * @glfw3 Changed to return an array of modes for a specific monitor.
1558 *
1559 * @ingroup monitor
1560 */
1561GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count);
1562
1563/*! @brief Returns the current mode of the specified monitor.
1564 *
1565 * This function returns the current video mode of the specified monitor. If
1566 * you have created a full screen window for that monitor, the return value
1567 * will depend on whether that window is iconified.
1568 *
1569 * @param[in] monitor The monitor to query.
1570 * @return The current mode of the monitor, or `NULL` if an
1571 * [error](@ref error_handling) occurred.
1572 *
1573 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1574 * GLFW_PLATFORM_ERROR.
1575 *
1576 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
1577 * should not free it yourself. It is valid until the specified monitor is
1578 * disconnected or the library is terminated.
1579 *
1580 * @thread_safety This function must only be called from the main thread.
1581 *
1582 * @sa @ref monitor_modes
1583 * @sa glfwGetVideoModes
1584 *
1585 * @since Added in version 3.0. Replaces `glfwGetDesktopMode`.
1586 *
1587 * @ingroup monitor
1588 */
1589GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
1590
1591/*! @brief Generates a gamma ramp and sets it for the specified monitor.
1592 *
1593 * This function generates a 256-element gamma ramp from the specified exponent
1594 * and then calls @ref glfwSetGammaRamp with it. The value must be a finite
1595 * number greater than zero.
1596 *
1597 * @param[in] monitor The monitor whose gamma ramp to set.
1598 * @param[in] gamma The desired exponent.
1599 *
1600 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
1601 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
1602 *
1603 * @thread_safety This function must only be called from the main thread.
1604 *
1605 * @sa @ref monitor_gamma
1606 *
1607 * @since Added in version 3.0.
1608 *
1609 * @ingroup monitor
1610 */
1611GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma);
1612
1613/*! @brief Returns the current gamma ramp for the specified monitor.
1614 *
1615 * This function returns the current gamma ramp of the specified monitor.
1616 *
1617 * @param[in] monitor The monitor to query.
1618 * @return The current gamma ramp, or `NULL` if an
1619 * [error](@ref error_handling) occurred.
1620 *
1621 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1622 * GLFW_PLATFORM_ERROR.
1623 *
1624 * @pointer_lifetime The returned structure and its arrays are allocated and
1625 * freed by GLFW. You should not free them yourself. They are valid until the
1626 * specified monitor is disconnected, this function is called again for that
1627 * monitor or the library is terminated.
1628 *
1629 * @thread_safety This function must only be called from the main thread.
1630 *
1631 * @sa @ref monitor_gamma
1632 *
1633 * @since Added in version 3.0.
1634 *
1635 * @ingroup monitor
1636 */
1637GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor);
1638
1639/*! @brief Sets the current gamma ramp for the specified monitor.
1640 *
1641 * This function sets the current gamma ramp for the specified monitor. The
1642 * original gamma ramp for that monitor is saved by GLFW the first time this
1643 * function is called and is restored by @ref glfwTerminate.
1644 *
1645 * @param[in] monitor The monitor whose gamma ramp to set.
1646 * @param[in] ramp The gamma ramp to use.
1647 *
1648 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1649 * GLFW_PLATFORM_ERROR.
1650 *
1651 * @remark Gamma ramp sizes other than 256 are not supported by all platforms
1652 * or graphics hardware.
1653 *
1654 * @remark @win32 The gamma ramp size must be 256.
1655 *
1656 * @pointer_lifetime The specified gamma ramp is copied before this function
1657 * returns.
1658 *
1659 * @thread_safety This function must only be called from the main thread.
1660 *
1661 * @sa @ref monitor_gamma
1662 *
1663 * @since Added in version 3.0.
1664 *
1665 * @ingroup monitor
1666 */
1667GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp);
1668
1669/*! @brief Resets all window hints to their default values.
1670 *
1671 * This function resets all window hints to their
1672 * [default values](@ref window_hints_values).
1673 *
1674 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1675 *
1676 * @thread_safety This function must only be called from the main thread.
1677 *
1678 * @sa @ref window_hints
1679 * @sa glfwWindowHint
1680 *
1681 * @since Added in version 3.0.
1682 *
1683 * @ingroup window
1684 */
1685GLFWAPI void glfwDefaultWindowHints(void);
1686
1687/*! @brief Sets the specified window hint to the desired value.
1688 *
1689 * This function sets hints for the next call to @ref glfwCreateWindow. The
1690 * hints, once set, retain their values until changed by a call to @ref
1691 * glfwWindowHint or @ref glfwDefaultWindowHints, or until the library is
1692 * terminated.
1693 *
1694 * This function does not check whether the specified hint values are valid.
1695 * If you set hints to invalid values this will instead be reported by the next
1696 * call to @ref glfwCreateWindow.
1697 *
1698 * @param[in] hint The [window hint](@ref window_hints) to set.
1699 * @param[in] value The new value of the window hint.
1700 *
1701 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1702 * GLFW_INVALID_ENUM.
1703 *
1704 * @thread_safety This function must only be called from the main thread.
1705 *
1706 * @sa @ref window_hints
1707 * @sa glfwDefaultWindowHints
1708 *
1709 * @since Added in version 3.0. Replaces `glfwOpenWindowHint`.
1710 *
1711 * @ingroup window
1712 */
1713GLFWAPI void glfwWindowHint(int hint, int value);
1714
1715/*! @brief Creates a window and its associated context.
1716 *
1717 * This function creates a window and its associated OpenGL or OpenGL ES
1718 * context. Most of the options controlling how the window and its context
1719 * should be created are specified with [window hints](@ref window_hints).
1720 *
1721 * Successful creation does not change which context is current. Before you
1722 * can use the newly created context, you need to
1723 * [make it current](@ref context_current). For information about the `share`
1724 * parameter, see @ref context_sharing.
1725 *
1726 * The created window, framebuffer and context may differ from what you
1727 * requested, as not all parameters and hints are
1728 * [hard constraints](@ref window_hints_hard). This includes the size of the
1729 * window, especially for full screen windows. To query the actual attributes
1730 * of the created window, framebuffer and context, see @ref
1731 * glfwGetWindowAttrib, @ref glfwGetWindowSize and @ref glfwGetFramebufferSize.
1732 *
1733 * To create a full screen window, you need to specify the monitor the window
1734 * will cover. If no monitor is specified, the window will be windowed mode.
1735 * Unless you have a way for the user to choose a specific monitor, it is
1736 * recommended that you pick the primary monitor. For more information on how
1737 * to query connected monitors, see @ref monitor_monitors.
1738 *
1739 * For full screen windows, the specified size becomes the resolution of the
1740 * window's _desired video mode_. As long as a full screen window is not
1741 * iconified, the supported video mode most closely matching the desired video
1742 * mode is set for the specified monitor. For more information about full
1743 * screen windows, including the creation of so called _windowed full screen_
1744 * or _borderless full screen_ windows, see @ref window_windowed_full_screen.
1745 *
1746 * Once you have created the window, you can switch it between windowed and
1747 * full screen mode with @ref glfwSetWindowMonitor. If the window has an
1748 * OpenGL or OpenGL ES context, it will be unaffected.
1749 *
1750 * By default, newly created windows use the placement recommended by the
1751 * window system. To create the window at a specific position, make it
1752 * initially invisible using the [GLFW_VISIBLE](@ref window_hints_wnd) window
1753 * hint, set its [position](@ref window_pos) and then [show](@ref window_hide)
1754 * it.
1755 *
1756 * As long as at least one full screen window is not iconified, the screensaver
1757 * is prohibited from starting.
1758 *
1759 * Window systems put limits on window sizes. Very large or very small window
1760 * dimensions may be overridden by the window system on creation. Check the
1761 * actual [size](@ref window_size) after creation.
1762 *
1763 * The [swap interval](@ref buffer_swap) is not set during window creation and
1764 * the initial value may vary depending on driver settings and defaults.
1765 *
1766 * @param[in] width The desired width, in screen coordinates, of the window.
1767 * This must be greater than zero.
1768 * @param[in] height The desired height, in screen coordinates, of the window.
1769 * This must be greater than zero.
1770 * @param[in] title The initial, UTF-8 encoded window title.
1771 * @param[in] monitor The monitor to use for full screen mode, or `NULL` for
1772 * windowed mode.
1773 * @param[in] share The window whose context to share resources with, or `NULL`
1774 * to not share resources.
1775 * @return The handle of the created window, or `NULL` if an
1776 * [error](@ref error_handling) occurred.
1777 *
1778 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
1779 * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_API_UNAVAILABLE, @ref
1780 * GLFW_VERSION_UNAVAILABLE, @ref GLFW_FORMAT_UNAVAILABLE and @ref
1781 * GLFW_PLATFORM_ERROR.
1782 *
1783 * @remark @win32 Window creation will fail if the Microsoft GDI software
1784 * OpenGL implementation is the only one available.
1785 *
1786 * @remark @win32 If the executable has an icon resource named `GLFW_ICON,` it
1787 * will be set as the initial icon for the window. If no such icon is present,
1788 * the `IDI_WINLOGO` icon will be used instead. To set a different icon, see
1789 * @ref glfwSetWindowIcon.
1790 *
1791 * @remark @win32 The context to share resources with must not be current on
1792 * any other thread.
1793 *
1794 * @remark @osx The GLFW window has no icon, as it is not a document
1795 * window, but the dock icon will be the same as the application bundle's icon.
1796 * For more information on bundles, see the
1797 * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
1798 * in the Mac Developer Library.
1799 *
1800 * @remark @osx The first time a window is created the menu bar is populated
1801 * with common commands like Hide, Quit and About. The About entry opens
1802 * a minimal about dialog with information from the application's bundle. The
1803 * menu bar can be disabled with a
1804 * [compile-time option](@ref compile_options_osx).
1805 *
1806 * @remark @osx On OS X 10.10 and later the window frame will not be rendered
1807 * at full resolution on Retina displays unless the `NSHighResolutionCapable`
1808 * key is enabled in the application bundle's `Info.plist`. For more
1809 * information, see
1810 * [High Resolution Guidelines for OS X](https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html)
1811 * in the Mac Developer Library. The GLFW test and example programs use
1812 * a custom `Info.plist` template for this, which can be found as
1813 * `CMake/MacOSXBundleInfo.plist.in` in the source tree.
1814 *
1815 * @remark @x11 Some window managers will not respect the placement of
1816 * initially hidden windows.
1817 *
1818 * @remark @x11 Due to the asynchronous nature of X11, it may take a moment for
1819 * a window to reach its requested state. This means you may not be able to
1820 * query the final size, position or other attributes directly after window
1821 * creation.
1822 *
1823 * @reentrancy This function must not be called from a callback.
1824 *
1825 * @thread_safety This function must only be called from the main thread.
1826 *
1827 * @sa @ref window_creation
1828 * @sa glfwDestroyWindow
1829 *
1830 * @since Added in version 3.0. Replaces `glfwOpenWindow`.
1831 *
1832 * @ingroup window
1833 */
1834GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share);
1835
1836/*! @brief Destroys the specified window and its context.
1837 *
1838 * This function destroys the specified window and its context. On calling
1839 * this function, no further callbacks will be called for that window.
1840 *
1841 * If the context of the specified window is current on the main thread, it is
1842 * detached before being destroyed.
1843 *
1844 * @param[in] window The window to destroy.
1845 *
1846 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1847 * GLFW_PLATFORM_ERROR.
1848 *
1849 * @note The context of the specified window must not be current on any other
1850 * thread when this function is called.
1851 *
1852 * @reentrancy This function must not be called from a callback.
1853 *
1854 * @thread_safety This function must only be called from the main thread.
1855 *
1856 * @sa @ref window_creation
1857 * @sa glfwCreateWindow
1858 *
1859 * @since Added in version 3.0. Replaces `glfwCloseWindow`.
1860 *
1861 * @ingroup window
1862 */
1863GLFWAPI void glfwDestroyWindow(GLFWwindow* window);
1864
1865/*! @brief Checks the close flag of the specified window.
1866 *
1867 * This function returns the value of the close flag of the specified window.
1868 *
1869 * @param[in] window The window to query.
1870 * @return The value of the close flag.
1871 *
1872 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1873 *
1874 * @thread_safety This function may be called from any thread. Access is not
1875 * synchronized.
1876 *
1877 * @sa @ref window_close
1878 *
1879 * @since Added in version 3.0.
1880 *
1881 * @ingroup window
1882 */
1883GLFWAPI int glfwWindowShouldClose(GLFWwindow* window);
1884
1885/*! @brief Sets the close flag of the specified window.
1886 *
1887 * This function sets the value of the close flag of the specified window.
1888 * This can be used to override the user's attempt to close the window, or
1889 * to signal that it should be closed.
1890 *
1891 * @param[in] window The window whose flag to change.
1892 * @param[in] value The new value.
1893 *
1894 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
1895 *
1896 * @thread_safety This function may be called from any thread. Access is not
1897 * synchronized.
1898 *
1899 * @sa @ref window_close
1900 *
1901 * @since Added in version 3.0.
1902 *
1903 * @ingroup window
1904 */
1905GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value);
1906
1907/*! @brief Sets the title of the specified window.
1908 *
1909 * This function sets the window title, encoded as UTF-8, of the specified
1910 * window.
1911 *
1912 * @param[in] window The window whose title to change.
1913 * @param[in] title The UTF-8 encoded window title.
1914 *
1915 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1916 * GLFW_PLATFORM_ERROR.
1917 *
1918 * @remark @osx The window title will not be updated until the next time you
1919 * process events.
1920 *
1921 * @thread_safety This function must only be called from the main thread.
1922 *
1923 * @sa @ref window_title
1924 *
1925 * @since Added in version 1.0.
1926 * @glfw3 Added window handle parameter.
1927 *
1928 * @ingroup window
1929 */
1930GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title);
1931
1932/*! @brief Sets the icon for the specified window.
1933 *
1934 * This function sets the icon of the specified window. If passed an array of
1935 * candidate images, those of or closest to the sizes desired by the system are
1936 * selected. If no images are specified, the window reverts to its default
1937 * icon.
1938 *
1939 * The desired image sizes varies depending on platform and system settings.
1940 * The selected images will be rescaled as needed. Good sizes include 16x16,
1941 * 32x32 and 48x48.
1942 *
1943 * @param[in] window The window whose icon to set.
1944 * @param[in] count The number of images in the specified array, or zero to
1945 * revert to the default window icon.
1946 * @param[in] images The images to create the icon from. This is ignored if
1947 * count is zero.
1948 *
1949 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1950 * GLFW_PLATFORM_ERROR.
1951 *
1952 * @pointer_lifetime The specified image data is copied before this function
1953 * returns.
1954 *
1955 * @remark @osx The GLFW window has no icon, as it is not a document
1956 * window, so this function does nothing. The dock icon will be the same as
1957 * the application bundle's icon. For more information on bundles, see the
1958 * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
1959 * in the Mac Developer Library.
1960 *
1961 * @thread_safety This function must only be called from the main thread.
1962 *
1963 * @sa @ref window_icon
1964 *
1965 * @since Added in version 3.2.
1966 *
1967 * @ingroup window
1968 */
1969GLFWAPI void glfwSetWindowIcon(GLFWwindow* window, int count, const GLFWimage* images);
1970
1971/*! @brief Retrieves the position of the client area of the specified window.
1972 *
1973 * This function retrieves the position, in screen coordinates, of the
1974 * upper-left corner of the client area of the specified window.
1975 *
1976 * Any or all of the position arguments may be `NULL`. If an error occurs, all
1977 * non-`NULL` position arguments will be set to zero.
1978 *
1979 * @param[in] window The window to query.
1980 * @param[out] xpos Where to store the x-coordinate of the upper-left corner of
1981 * the client area, or `NULL`.
1982 * @param[out] ypos Where to store the y-coordinate of the upper-left corner of
1983 * the client area, or `NULL`.
1984 *
1985 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
1986 * GLFW_PLATFORM_ERROR.
1987 *
1988 * @thread_safety This function must only be called from the main thread.
1989 *
1990 * @sa @ref window_pos
1991 * @sa glfwSetWindowPos
1992 *
1993 * @since Added in version 3.0.
1994 *
1995 * @ingroup window
1996 */
1997GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
1998
1999/*! @brief Sets the position of the client area of the specified window.
2000 *
2001 * This function sets the position, in screen coordinates, of the upper-left
2002 * corner of the client area of the specified windowed mode window. If the
2003 * window is a full screen window, this function does nothing.
2004 *
2005 * __Do not use this function__ to move an already visible window unless you
2006 * have very good reasons for doing so, as it will confuse and annoy the user.
2007 *
2008 * The window manager may put limits on what positions are allowed. GLFW
2009 * cannot and should not override these limits.
2010 *
2011 * @param[in] window The window to query.
2012 * @param[in] xpos The x-coordinate of the upper-left corner of the client area.
2013 * @param[in] ypos The y-coordinate of the upper-left corner of the client area.
2014 *
2015 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2016 * GLFW_PLATFORM_ERROR.
2017 *
2018 * @thread_safety This function must only be called from the main thread.
2019 *
2020 * @sa @ref window_pos
2021 * @sa glfwGetWindowPos
2022 *
2023 * @since Added in version 1.0.
2024 * @glfw3 Added window handle parameter.
2025 *
2026 * @ingroup window
2027 */
2028GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
2029
2030/*! @brief Retrieves the size of the client area of the specified window.
2031 *
2032 * This function retrieves the size, in screen coordinates, of the client area
2033 * of the specified window. If you wish to retrieve the size of the
2034 * framebuffer of the window in pixels, see @ref glfwGetFramebufferSize.
2035 *
2036 * Any or all of the size arguments may be `NULL`. If an error occurs, all
2037 * non-`NULL` size arguments will be set to zero.
2038 *
2039 * @param[in] window The window whose size to retrieve.
2040 * @param[out] width Where to store the width, in screen coordinates, of the
2041 * client area, or `NULL`.
2042 * @param[out] height Where to store the height, in screen coordinates, of the
2043 * client area, or `NULL`.
2044 *
2045 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2046 * GLFW_PLATFORM_ERROR.
2047 *
2048 * @thread_safety This function must only be called from the main thread.
2049 *
2050 * @sa @ref window_size
2051 * @sa glfwSetWindowSize
2052 *
2053 * @since Added in version 1.0.
2054 * @glfw3 Added window handle parameter.
2055 *
2056 * @ingroup window
2057 */
2058GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
2059
2060/*! @brief Sets the size limits of the specified window.
2061 *
2062 * This function sets the size limits of the client area of the specified
2063 * window. If the window is full screen, the size limits only take effect
2064 * once it is made windowed. If the window is not resizable, this function
2065 * does nothing.
2066 *
2067 * The size limits are applied immediately to a windowed mode window and may
2068 * cause it to be resized.
2069 *
2070 * The maximum dimensions must be greater than or equal to the minimum
2071 * dimensions and all must be greater than or equal to zero.
2072 *
2073 * @param[in] window The window to set limits for.
2074 * @param[in] minwidth The minimum width, in screen coordinates, of the client
2075 * area, or `GLFW_DONT_CARE`.
2076 * @param[in] minheight The minimum height, in screen coordinates, of the
2077 * client area, or `GLFW_DONT_CARE`.
2078 * @param[in] maxwidth The maximum width, in screen coordinates, of the client
2079 * area, or `GLFW_DONT_CARE`.
2080 * @param[in] maxheight The maximum height, in screen coordinates, of the
2081 * client area, or `GLFW_DONT_CARE`.
2082 *
2083 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2084 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
2085 *
2086 * @remark If you set size limits and an aspect ratio that conflict, the
2087 * results are undefined.
2088 *
2089 * @thread_safety This function must only be called from the main thread.
2090 *
2091 * @sa @ref window_sizelimits
2092 * @sa glfwSetWindowAspectRatio
2093 *
2094 * @since Added in version 3.2.
2095 *
2096 * @ingroup window
2097 */
2098GLFWAPI void glfwSetWindowSizeLimits(GLFWwindow* window, int minwidth, int minheight, int maxwidth, int maxheight);
2099
2100/*! @brief Sets the aspect ratio of the specified window.
2101 *
2102 * This function sets the required aspect ratio of the client area of the
2103 * specified window. If the window is full screen, the aspect ratio only takes
2104 * effect once it is made windowed. If the window is not resizable, this
2105 * function does nothing.
2106 *
2107 * The aspect ratio is specified as a numerator and a denominator and both
2108 * values must be greater than zero. For example, the common 16:9 aspect ratio
2109 * is specified as 16 and 9, respectively.
2110 *
2111 * If the numerator and denominator is set to `GLFW_DONT_CARE` then the aspect
2112 * ratio limit is disabled.
2113 *
2114 * The aspect ratio is applied immediately to a windowed mode window and may
2115 * cause it to be resized.
2116 *
2117 * @param[in] window The window to set limits for.
2118 * @param[in] numer The numerator of the desired aspect ratio, or
2119 * `GLFW_DONT_CARE`.
2120 * @param[in] denom The denominator of the desired aspect ratio, or
2121 * `GLFW_DONT_CARE`.
2122 *
2123 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2124 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
2125 *
2126 * @remark If you set size limits and an aspect ratio that conflict, the
2127 * results are undefined.
2128 *
2129 * @thread_safety This function must only be called from the main thread.
2130 *
2131 * @sa @ref window_sizelimits
2132 * @sa glfwSetWindowSizeLimits
2133 *
2134 * @since Added in version 3.2.
2135 *
2136 * @ingroup window
2137 */
2138GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom);
2139
2140/*! @brief Sets the size of the client area of the specified window.
2141 *
2142 * This function sets the size, in screen coordinates, of the client area of
2143 * the specified window.
2144 *
2145 * For full screen windows, this function updates the resolution of its desired
2146 * video mode and switches to the video mode closest to it, without affecting
2147 * the window's context. As the context is unaffected, the bit depths of the
2148 * framebuffer remain unchanged.
2149 *
2150 * If you wish to update the refresh rate of the desired video mode in addition
2151 * to its resolution, see @ref glfwSetWindowMonitor.
2152 *
2153 * The window manager may put limits on what sizes are allowed. GLFW cannot
2154 * and should not override these limits.
2155 *
2156 * @param[in] window The window to resize.
2157 * @param[in] width The desired width, in screen coordinates, of the window
2158 * client area.
2159 * @param[in] height The desired height, in screen coordinates, of the window
2160 * client area.
2161 *
2162 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2163 * GLFW_PLATFORM_ERROR.
2164 *
2165 * @thread_safety This function must only be called from the main thread.
2166 *
2167 * @sa @ref window_size
2168 * @sa glfwGetWindowSize
2169 * @sa glfwSetWindowMonitor
2170 *
2171 * @since Added in version 1.0.
2172 * @glfw3 Added window handle parameter.
2173 *
2174 * @ingroup window
2175 */
2176GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
2177
2178/*! @brief Retrieves the size of the framebuffer of the specified window.
2179 *
2180 * This function retrieves the size, in pixels, of the framebuffer of the
2181 * specified window. If you wish to retrieve the size of the window in screen
2182 * coordinates, see @ref glfwGetWindowSize.
2183 *
2184 * Any or all of the size arguments may be `NULL`. If an error occurs, all
2185 * non-`NULL` size arguments will be set to zero.
2186 *
2187 * @param[in] window The window whose framebuffer to query.
2188 * @param[out] width Where to store the width, in pixels, of the framebuffer,
2189 * or `NULL`.
2190 * @param[out] height Where to store the height, in pixels, of the framebuffer,
2191 * or `NULL`.
2192 *
2193 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2194 * GLFW_PLATFORM_ERROR.
2195 *
2196 * @thread_safety This function must only be called from the main thread.
2197 *
2198 * @sa @ref window_fbsize
2199 * @sa glfwSetFramebufferSizeCallback
2200 *
2201 * @since Added in version 3.0.
2202 *
2203 * @ingroup window
2204 */
2205GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height);
2206
2207/*! @brief Retrieves the size of the frame of the window.
2208 *
2209 * This function retrieves the size, in screen coordinates, of each edge of the
2210 * frame of the specified window. This size includes the title bar, if the
2211 * window has one. The size of the frame may vary depending on the
2212 * [window-related hints](@ref window_hints_wnd) used to create it.
2213 *
2214 * Because this function retrieves the size of each window frame edge and not
2215 * the offset along a particular coordinate axis, the retrieved values will
2216 * always be zero or positive.
2217 *
2218 * Any or all of the size arguments may be `NULL`. If an error occurs, all
2219 * non-`NULL` size arguments will be set to zero.
2220 *
2221 * @param[in] window The window whose frame size to query.
2222 * @param[out] left Where to store the size, in screen coordinates, of the left
2223 * edge of the window frame, or `NULL`.
2224 * @param[out] top Where to store the size, in screen coordinates, of the top
2225 * edge of the window frame, or `NULL`.
2226 * @param[out] right Where to store the size, in screen coordinates, of the
2227 * right edge of the window frame, or `NULL`.
2228 * @param[out] bottom Where to store the size, in screen coordinates, of the
2229 * bottom edge of the window frame, or `NULL`.
2230 *
2231 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2232 * GLFW_PLATFORM_ERROR.
2233 *
2234 * @thread_safety This function must only be called from the main thread.
2235 *
2236 * @sa @ref window_size
2237 *
2238 * @since Added in version 3.1.
2239 *
2240 * @ingroup window
2241 */
2242GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int* right, int* bottom);
2243
2244/*! @brief Iconifies the specified window.
2245 *
2246 * This function iconifies (minimizes) the specified window if it was
2247 * previously restored. If the window is already iconified, this function does
2248 * nothing.
2249 *
2250 * If the specified window is a full screen window, the original monitor
2251 * resolution is restored until the window is restored.
2252 *
2253 * @param[in] window The window to iconify.
2254 *
2255 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2256 * GLFW_PLATFORM_ERROR.
2257 *
2258 * @thread_safety This function must only be called from the main thread.
2259 *
2260 * @sa @ref window_iconify
2261 * @sa glfwRestoreWindow
2262 * @sa glfwMaximizeWindow
2263 *
2264 * @since Added in version 2.1.
2265 * @glfw3 Added window handle parameter.
2266 *
2267 * @ingroup window
2268 */
2269GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
2270
2271/*! @brief Restores the specified window.
2272 *
2273 * This function restores the specified window if it was previously iconified
2274 * (minimized) or maximized. If the window is already restored, this function
2275 * does nothing.
2276 *
2277 * If the specified window is a full screen window, the resolution chosen for
2278 * the window is restored on the selected monitor.
2279 *
2280 * @param[in] window The window to restore.
2281 *
2282 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2283 * GLFW_PLATFORM_ERROR.
2284 *
2285 * @thread_safety This function must only be called from the main thread.
2286 *
2287 * @sa @ref window_iconify
2288 * @sa glfwIconifyWindow
2289 * @sa glfwMaximizeWindow
2290 *
2291 * @since Added in version 2.1.
2292 * @glfw3 Added window handle parameter.
2293 *
2294 * @ingroup window
2295 */
2296GLFWAPI void glfwRestoreWindow(GLFWwindow* window);
2297
2298/*! @brief Maximizes the specified window.
2299 *
2300 * This function maximizes the specified window if it was previously not
2301 * maximized. If the window is already maximized, this function does nothing.
2302 *
2303 * If the specified window is a full screen window, this function does nothing.
2304 *
2305 * @param[in] window The window to maximize.
2306 *
2307 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2308 * GLFW_PLATFORM_ERROR.
2309 *
2310 * @par Thread Safety
2311 * This function may only be called from the main thread.
2312 *
2313 * @sa @ref window_iconify
2314 * @sa glfwIconifyWindow
2315 * @sa glfwRestoreWindow
2316 *
2317 * @since Added in GLFW 3.2.
2318 *
2319 * @ingroup window
2320 */
2321GLFWAPI void glfwMaximizeWindow(GLFWwindow* window);
2322
2323/*! @brief Makes the specified window visible.
2324 *
2325 * This function makes the specified window visible if it was previously
2326 * hidden. If the window is already visible or is in full screen mode, this
2327 * function does nothing.
2328 *
2329 * @param[in] window The window to make visible.
2330 *
2331 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2332 * GLFW_PLATFORM_ERROR.
2333 *
2334 * @thread_safety This function must only be called from the main thread.
2335 *
2336 * @sa @ref window_hide
2337 * @sa glfwHideWindow
2338 *
2339 * @since Added in version 3.0.
2340 *
2341 * @ingroup window
2342 */
2343GLFWAPI void glfwShowWindow(GLFWwindow* window);
2344
2345/*! @brief Hides the specified window.
2346 *
2347 * This function hides the specified window if it was previously visible. If
2348 * the window is already hidden or is in full screen mode, this function does
2349 * nothing.
2350 *
2351 * @param[in] window The window to hide.
2352 *
2353 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2354 * GLFW_PLATFORM_ERROR.
2355 *
2356 * @thread_safety This function must only be called from the main thread.
2357 *
2358 * @sa @ref window_hide
2359 * @sa glfwShowWindow
2360 *
2361 * @since Added in version 3.0.
2362 *
2363 * @ingroup window
2364 */
2365GLFWAPI void glfwHideWindow(GLFWwindow* window);
2366
2367/*! @brief Brings the specified window to front and sets input focus.
2368 *
2369 * This function brings the specified window to front and sets input focus.
2370 * The window should already be visible and not iconified.
2371 *
2372 * By default, both windowed and full screen mode windows are focused when
2373 * initially created. Set the [GLFW_FOCUSED](@ref window_hints_wnd) to disable
2374 * this behavior.
2375 *
2376 * __Do not use this function__ to steal focus from other applications unless
2377 * you are certain that is what the user wants. Focus stealing can be
2378 * extremely disruptive.
2379 *
2380 * @param[in] window The window to give input focus.
2381 *
2382 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2383 * GLFW_PLATFORM_ERROR.
2384 *
2385 * @thread_safety This function must only be called from the main thread.
2386 *
2387 * @sa @ref window_focus
2388 *
2389 * @since Added in version 3.2.
2390 *
2391 * @ingroup window
2392 */
2393GLFWAPI void glfwFocusWindow(GLFWwindow* window);
2394
2395/*! @brief Returns the monitor that the window uses for full screen mode.
2396 *
2397 * This function returns the handle of the monitor that the specified window is
2398 * in full screen on.
2399 *
2400 * @param[in] window The window to query.
2401 * @return The monitor, or `NULL` if the window is in windowed mode or an
2402 * [error](@ref error_handling) occurred.
2403 *
2404 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2405 *
2406 * @thread_safety This function must only be called from the main thread.
2407 *
2408 * @sa @ref window_monitor
2409 * @sa glfwSetWindowMonitor
2410 *
2411 * @since Added in version 3.0.
2412 *
2413 * @ingroup window
2414 */
2415GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
2416
2417/*! @brief Sets the mode, monitor, video mode and placement of a window.
2418 *
2419 * This function sets the monitor that the window uses for full screen mode or,
2420 * if the monitor is `NULL`, makes it windowed mode.
2421 *
2422 * When setting a monitor, this function updates the width, height and refresh
2423 * rate of the desired video mode and switches to the video mode closest to it.
2424 * The window position is ignored when setting a monitor.
2425 *
2426 * When the monitor is `NULL`, the position, width and height are used to
2427 * place the window client area. The refresh rate is ignored when no monitor
2428 * is specified.
2429 *
2430 * If you only wish to update the resolution of a full screen window or the
2431 * size of a windowed mode window, see @ref glfwSetWindowSize.
2432 *
2433 * When a window transitions from full screen to windowed mode, this function
2434 * restores any previous window settings such as whether it is decorated,
2435 * floating, resizable, has size or aspect ratio limits, etc..
2436 *
2437 * @param[in] window The window whose monitor, size or video mode to set.
2438 * @param[in] monitor The desired monitor, or `NULL` to set windowed mode.
2439 * @param[in] xpos The desired x-coordinate of the upper-left corner of the
2440 * client area.
2441 * @param[in] ypos The desired y-coordinate of the upper-left corner of the
2442 * client area.
2443 * @param[in] width The desired with, in screen coordinates, of the client area
2444 * or video mode.
2445 * @param[in] height The desired height, in screen coordinates, of the client
2446 * area or video mode.
2447 * @param[in] refreshRate The desired refresh rate, in Hz, of the video mode,
2448 * or `GLFW_DONT_CARE`.
2449 *
2450 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2451 * GLFW_PLATFORM_ERROR.
2452 *
2453 * @thread_safety This function must only be called from the main thread.
2454 *
2455 * @sa @ref window_monitor
2456 * @sa @ref window_full_screen
2457 * @sa glfwGetWindowMonitor
2458 * @sa glfwSetWindowSize
2459 *
2460 * @since Added in version 3.2.
2461 *
2462 * @ingroup window
2463 */
2464GLFWAPI void glfwSetWindowMonitor(GLFWwindow* window, GLFWmonitor* monitor, int xpos, int ypos, int width, int height, int refreshRate);
2465
2466/*! @brief Returns an attribute of the specified window.
2467 *
2468 * This function returns the value of an attribute of the specified window or
2469 * its OpenGL or OpenGL ES context.
2470 *
2471 * @param[in] window The window to query.
2472 * @param[in] attrib The [window attribute](@ref window_attribs) whose value to
2473 * return.
2474 * @return The value of the attribute, or zero if an
2475 * [error](@ref error_handling) occurred.
2476 *
2477 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2478 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
2479 *
2480 * @remark Framebuffer related hints are not window attributes. See @ref
2481 * window_attribs_fb for more information.
2482 *
2483 * @remark Zero is a valid value for many window and context related
2484 * attributes so you cannot use a return value of zero as an indication of
2485 * errors. However, this function should not fail as long as it is passed
2486 * valid arguments and the library has been [initialized](@ref intro_init).
2487 *
2488 * @thread_safety This function must only be called from the main thread.
2489 *
2490 * @sa @ref window_attribs
2491 *
2492 * @since Added in version 3.0. Replaces `glfwGetWindowParam` and
2493 * `glfwGetGLVersion`.
2494 *
2495 * @ingroup window
2496 */
2497GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib);
2498
2499/*! @brief Sets the user pointer of the specified window.
2500 *
2501 * This function sets the user-defined pointer of the specified window. The
2502 * current value is retained until the window is destroyed. The initial value
2503 * is `NULL`.
2504 *
2505 * @param[in] window The window whose pointer to set.
2506 * @param[in] pointer The new value.
2507 *
2508 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2509 *
2510 * @thread_safety This function may be called from any thread. Access is not
2511 * synchronized.
2512 *
2513 * @sa @ref window_userptr
2514 * @sa glfwGetWindowUserPointer
2515 *
2516 * @since Added in version 3.0.
2517 *
2518 * @ingroup window
2519 */
2520GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer);
2521
2522/*! @brief Returns the user pointer of the specified window.
2523 *
2524 * This function returns the current value of the user-defined pointer of the
2525 * specified window. The initial value is `NULL`.
2526 *
2527 * @param[in] window The window whose pointer to return.
2528 *
2529 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2530 *
2531 * @thread_safety This function may be called from any thread. Access is not
2532 * synchronized.
2533 *
2534 * @sa @ref window_userptr
2535 * @sa glfwSetWindowUserPointer
2536 *
2537 * @since Added in version 3.0.
2538 *
2539 * @ingroup window
2540 */
2541GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
2542
2543/*! @brief Sets the position callback for the specified window.
2544 *
2545 * This function sets the position callback of the specified window, which is
2546 * called when the window is moved. The callback is provided with the screen
2547 * position of the upper-left corner of the client area of the window.
2548 *
2549 * @param[in] window The window whose callback to set.
2550 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
2551 * callback.
2552 * @return The previously set callback, or `NULL` if no callback was set or the
2553 * library had not been [initialized](@ref intro_init).
2554 *
2555 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2556 *
2557 * @thread_safety This function must only be called from the main thread.
2558 *
2559 * @sa @ref window_pos
2560 *
2561 * @since Added in version 3.0.
2562 *
2563 * @ingroup window
2564 */
2565GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun);
2566
2567/*! @brief Sets the size callback for the specified window.
2568 *
2569 * This function sets the size callback of the specified window, which is
2570 * called when the window is resized. The callback is provided with the size,
2571 * in screen coordinates, of the client area of the window.
2572 *
2573 * @param[in] window The window whose callback to set.
2574 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
2575 * callback.
2576 * @return The previously set callback, or `NULL` if no callback was set or the
2577 * library had not been [initialized](@ref intro_init).
2578 *
2579 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2580 *
2581 * @thread_safety This function must only be called from the main thread.
2582 *
2583 * @sa @ref window_size
2584 *
2585 * @since Added in version 1.0.
2586 * @glfw3 Added window handle parameter and return value.
2587 *
2588 * @ingroup window
2589 */
2590GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun cbfun);
2591
2592/*! @brief Sets the close callback for the specified window.
2593 *
2594 * This function sets the close callback of the specified window, which is
2595 * called when the user attempts to close the window, for example by clicking
2596 * the close widget in the title bar.
2597 *
2598 * The close flag is set before this callback is called, but you can modify it
2599 * at any time with @ref glfwSetWindowShouldClose.
2600 *
2601 * The close callback is not triggered by @ref glfwDestroyWindow.
2602 *
2603 * @param[in] window The window whose callback to set.
2604 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
2605 * callback.
2606 * @return The previously set callback, or `NULL` if no callback was set or the
2607 * library had not been [initialized](@ref intro_init).
2608 *
2609 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2610 *
2611 * @remark @osx Selecting Quit from the application menu will trigger the close
2612 * callback for all windows.
2613 *
2614 * @thread_safety This function must only be called from the main thread.
2615 *
2616 * @sa @ref window_close
2617 *
2618 * @since Added in version 2.5.
2619 * @glfw3 Added window handle parameter and return value.
2620 *
2621 * @ingroup window
2622 */
2623GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun cbfun);
2624
2625/*! @brief Sets the refresh callback for the specified window.
2626 *
2627 * This function sets the refresh callback of the specified window, which is
2628 * called when the client area of the window needs to be redrawn, for example
2629 * if the window has been exposed after having been covered by another window.
2630 *
2631 * On compositing window systems such as Aero, Compiz or Aqua, where the window
2632 * contents are saved off-screen, this callback may be called only very
2633 * infrequently or never at all.
2634 *
2635 * @param[in] window The window whose callback to set.
2636 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
2637 * callback.
2638 * @return The previously set callback, or `NULL` if no callback was set or the
2639 * library had not been [initialized](@ref intro_init).
2640 *
2641 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2642 *
2643 * @thread_safety This function must only be called from the main thread.
2644 *
2645 * @sa @ref window_refresh
2646 *
2647 * @since Added in version 2.5.
2648 * @glfw3 Added window handle parameter and return value.
2649 *
2650 * @ingroup window
2651 */
2652GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun cbfun);
2653
2654/*! @brief Sets the focus callback for the specified window.
2655 *
2656 * This function sets the focus callback of the specified window, which is
2657 * called when the window gains or loses input focus.
2658 *
2659 * After the focus callback is called for a window that lost input focus,
2660 * synthetic key and mouse button release events will be generated for all such
2661 * that had been pressed. For more information, see @ref glfwSetKeyCallback
2662 * and @ref glfwSetMouseButtonCallback.
2663 *
2664 * @param[in] window The window whose callback to set.
2665 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
2666 * callback.
2667 * @return The previously set callback, or `NULL` if no callback was set or the
2668 * library had not been [initialized](@ref intro_init).
2669 *
2670 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2671 *
2672 * @thread_safety This function must only be called from the main thread.
2673 *
2674 * @sa @ref window_focus
2675 *
2676 * @since Added in version 3.0.
2677 *
2678 * @ingroup window
2679 */
2680GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun cbfun);
2681
2682/*! @brief Sets the iconify callback for the specified window.
2683 *
2684 * This function sets the iconification callback of the specified window, which
2685 * is called when the window is iconified or restored.
2686 *
2687 * @param[in] window The window whose callback to set.
2688 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
2689 * callback.
2690 * @return The previously set callback, or `NULL` if no callback was set or the
2691 * library had not been [initialized](@ref intro_init).
2692 *
2693 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2694 *
2695 * @thread_safety This function must only be called from the main thread.
2696 *
2697 * @sa @ref window_iconify
2698 *
2699 * @since Added in version 3.0.
2700 *
2701 * @ingroup window
2702 */
2703GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun cbfun);
2704
2705/*! @brief Sets the framebuffer resize callback for the specified window.
2706 *
2707 * This function sets the framebuffer resize callback of the specified window,
2708 * which is called when the framebuffer of the specified window is resized.
2709 *
2710 * @param[in] window The window whose callback to set.
2711 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
2712 * callback.
2713 * @return The previously set callback, or `NULL` if no callback was set or the
2714 * library had not been [initialized](@ref intro_init).
2715 *
2716 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2717 *
2718 * @thread_safety This function must only be called from the main thread.
2719 *
2720 * @sa @ref window_fbsize
2721 *
2722 * @since Added in version 3.0.
2723 *
2724 * @ingroup window
2725 */
2726GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun cbfun);
2727
2728/*! @brief Processes all pending events.
2729 *
2730 * This function processes only those events that are already in the event
2731 * queue and then returns immediately. Processing events will cause the window
2732 * and input callbacks associated with those events to be called.
2733 *
2734 * On some platforms, a window move, resize or menu operation will cause event
2735 * processing to block. This is due to how event processing is designed on
2736 * those platforms. You can use the
2737 * [window refresh callback](@ref window_refresh) to redraw the contents of
2738 * your window when necessary during such operations.
2739 *
2740 * On some platforms, certain events are sent directly to the application
2741 * without going through the event queue, causing callbacks to be called
2742 * outside of a call to one of the event processing functions.
2743 *
2744 * Event processing is not required for joystick input to work.
2745 *
2746 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2747 * GLFW_PLATFORM_ERROR.
2748 *
2749 * @reentrancy This function must not be called from a callback.
2750 *
2751 * @thread_safety This function must only be called from the main thread.
2752 *
2753 * @sa @ref events
2754 * @sa glfwWaitEvents
2755 * @sa glfwWaitEventsTimeout
2756 *
2757 * @since Added in version 1.0.
2758 *
2759 * @ingroup window
2760 */
2761GLFWAPI void glfwPollEvents(void);
2762
2763/*! @brief Waits until events are queued and processes them.
2764 *
2765 * This function puts the calling thread to sleep until at least one event is
2766 * available in the event queue. Once one or more events are available,
2767 * it behaves exactly like @ref glfwPollEvents, i.e. the events in the queue
2768 * are processed and the function then returns immediately. Processing events
2769 * will cause the window and input callbacks associated with those events to be
2770 * called.
2771 *
2772 * Since not all events are associated with callbacks, this function may return
2773 * without a callback having been called even if you are monitoring all
2774 * callbacks.
2775 *
2776 * On some platforms, a window move, resize or menu operation will cause event
2777 * processing to block. This is due to how event processing is designed on
2778 * those platforms. You can use the
2779 * [window refresh callback](@ref window_refresh) to redraw the contents of
2780 * your window when necessary during such operations.
2781 *
2782 * On some platforms, certain callbacks may be called outside of a call to one
2783 * of the event processing functions.
2784 *
2785 * If no windows exist, this function returns immediately. For synchronization
2786 * of threads in applications that do not create windows, use your threading
2787 * library of choice.
2788 *
2789 * Event processing is not required for joystick input to work.
2790 *
2791 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2792 * GLFW_PLATFORM_ERROR.
2793 *
2794 * @reentrancy This function must not be called from a callback.
2795 *
2796 * @thread_safety This function must only be called from the main thread.
2797 *
2798 * @sa @ref events
2799 * @sa glfwPollEvents
2800 * @sa glfwWaitEventsTimeout
2801 *
2802 * @since Added in version 2.5.
2803 *
2804 * @ingroup window
2805 */
2806GLFWAPI void glfwWaitEvents(void);
2807
2808/*! @brief Waits with timeout until events are queued and processes them.
2809 *
2810 * This function puts the calling thread to sleep until at least one event is
2811 * available in the event queue, or until the specified timeout is reached. If
2812 * one or more events are available, it behaves exactly like @ref
2813 * glfwPollEvents, i.e. the events in the queue are processed and the function
2814 * then returns immediately. Processing events will cause the window and input
2815 * callbacks associated with those events to be called.
2816 *
2817 * The timeout value must be a positive finite number.
2818 *
2819 * Since not all events are associated with callbacks, this function may return
2820 * without a callback having been called even if you are monitoring all
2821 * callbacks.
2822 *
2823 * On some platforms, a window move, resize or menu operation will cause event
2824 * processing to block. This is due to how event processing is designed on
2825 * those platforms. You can use the
2826 * [window refresh callback](@ref window_refresh) to redraw the contents of
2827 * your window when necessary during such operations.
2828 *
2829 * On some platforms, certain callbacks may be called outside of a call to one
2830 * of the event processing functions.
2831 *
2832 * If no windows exist, this function returns immediately. For synchronization
2833 * of threads in applications that do not create windows, use your threading
2834 * library of choice.
2835 *
2836 * Event processing is not required for joystick input to work.
2837 *
2838 * @param[in] timeout The maximum amount of time, in seconds, to wait.
2839 *
2840 * @reentrancy This function must not be called from a callback.
2841 *
2842 * @thread_safety This function must only be called from the main thread.
2843 *
2844 * @sa @ref events
2845 * @sa glfwPollEvents
2846 * @sa glfwWaitEvents
2847 *
2848 * @since Added in version 3.2.
2849 *
2850 * @ingroup window
2851 */
2852GLFWAPI void glfwWaitEventsTimeout(double timeout);
2853
2854/*! @brief Posts an empty event to the event queue.
2855 *
2856 * This function posts an empty event from the current thread to the event
2857 * queue, causing @ref glfwWaitEvents or @ref glfwWaitEventsTimeout to return.
2858 *
2859 * If no windows exist, this function returns immediately. For synchronization
2860 * of threads in applications that do not create windows, use your threading
2861 * library of choice.
2862 *
2863 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2864 * GLFW_PLATFORM_ERROR.
2865 *
2866 * @thread_safety This function may be called from any thread.
2867 *
2868 * @sa @ref events
2869 * @sa glfwWaitEvents
2870 * @sa glfwWaitEventsTimeout
2871 *
2872 * @since Added in version 3.1.
2873 *
2874 * @ingroup window
2875 */
2876GLFWAPI void glfwPostEmptyEvent(void);
2877
2878/*! @brief Returns the value of an input option for the specified window.
2879 *
2880 * This function returns the value of an input option for the specified window.
2881 * The mode must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
2882 * `GLFW_STICKY_MOUSE_BUTTONS`.
2883 *
2884 * @param[in] window The window to query.
2885 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
2886 * `GLFW_STICKY_MOUSE_BUTTONS`.
2887 *
2888 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2889 * GLFW_INVALID_ENUM.
2890 *
2891 * @thread_safety This function must only be called from the main thread.
2892 *
2893 * @sa glfwSetInputMode
2894 *
2895 * @since Added in version 3.0.
2896 *
2897 * @ingroup input
2898 */
2899GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
2900
2901/*! @brief Sets an input option for the specified window.
2902 *
2903 * This function sets an input mode option for the specified window. The mode
2904 * must be one of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
2905 * `GLFW_STICKY_MOUSE_BUTTONS`.
2906 *
2907 * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor
2908 * modes:
2909 * - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally.
2910 * - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the client
2911 * area of the window but does not restrict the cursor from leaving.
2912 * - `GLFW_CURSOR_DISABLED` hides and grabs the cursor, providing virtual
2913 * and unlimited cursor movement. This is useful for implementing for
2914 * example 3D camera controls.
2915 *
2916 * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GLFW_TRUE` to
2917 * enable sticky keys, or `GLFW_FALSE` to disable it. If sticky keys are
2918 * enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS`
2919 * the next time it is called even if the key had been released before the
2920 * call. This is useful when you are only interested in whether keys have been
2921 * pressed but not when or in which order.
2922 *
2923 * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either
2924 * `GLFW_TRUE` to enable sticky mouse buttons, or `GLFW_FALSE` to disable it.
2925 * If sticky mouse buttons are enabled, a mouse button press will ensure that
2926 * @ref glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even
2927 * if the mouse button had been released before the call. This is useful when
2928 * you are only interested in whether mouse buttons have been pressed but not
2929 * when or in which order.
2930 *
2931 * @param[in] window The window whose input mode to set.
2932 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
2933 * `GLFW_STICKY_MOUSE_BUTTONS`.
2934 * @param[in] value The new value of the specified input mode.
2935 *
2936 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2937 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
2938 *
2939 * @thread_safety This function must only be called from the main thread.
2940 *
2941 * @sa glfwGetInputMode
2942 *
2943 * @since Added in version 3.0. Replaces `glfwEnable` and `glfwDisable`.
2944 *
2945 * @ingroup input
2946 */
2947GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
2948
2949/*! @brief Returns the localized name of the specified printable key.
2950 *
2951 * This function returns the localized name of the specified printable key.
2952 * This is intended for displaying key bindings to the user.
2953 *
2954 * If the key is `GLFW_KEY_UNKNOWN`, the scancode is used instead, otherwise
2955 * the scancode is ignored. If a non-printable key or (if the key is
2956 * `GLFW_KEY_UNKNOWN`) a scancode that maps to a non-printable key is
2957 * specified, this function returns `NULL`.
2958 *
2959 * This behavior allows you to pass in the arguments passed to the
2960 * [key callback](@ref input_key) without modification.
2961 *
2962 * The printable keys are:
2963 * - `GLFW_KEY_APOSTROPHE`
2964 * - `GLFW_KEY_COMMA`
2965 * - `GLFW_KEY_MINUS`
2966 * - `GLFW_KEY_PERIOD`
2967 * - `GLFW_KEY_SLASH`
2968 * - `GLFW_KEY_SEMICOLON`
2969 * - `GLFW_KEY_EQUAL`
2970 * - `GLFW_KEY_LEFT_BRACKET`
2971 * - `GLFW_KEY_RIGHT_BRACKET`
2972 * - `GLFW_KEY_BACKSLASH`
2973 * - `GLFW_KEY_WORLD_1`
2974 * - `GLFW_KEY_WORLD_2`
2975 * - `GLFW_KEY_0` to `GLFW_KEY_9`
2976 * - `GLFW_KEY_A` to `GLFW_KEY_Z`
2977 * - `GLFW_KEY_KP_0` to `GLFW_KEY_KP_9`
2978 * - `GLFW_KEY_KP_DECIMAL`
2979 * - `GLFW_KEY_KP_DIVIDE`
2980 * - `GLFW_KEY_KP_MULTIPLY`
2981 * - `GLFW_KEY_KP_SUBTRACT`
2982 * - `GLFW_KEY_KP_ADD`
2983 * - `GLFW_KEY_KP_EQUAL`
2984 *
2985 * @param[in] key The key to query, or `GLFW_KEY_UNKNOWN`.
2986 * @param[in] scancode The scancode of the key to query.
2987 * @return The localized name of the key, or `NULL`.
2988 *
2989 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2990 * GLFW_PLATFORM_ERROR.
2991 *
2992 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
2993 * should not free it yourself. It is valid until the next call to @ref
2994 * glfwGetKeyName, or until the library is terminated.
2995 *
2996 * @thread_safety This function must only be called from the main thread.
2997 *
2998 * @sa @ref input_key_name
2999 *
3000 * @since Added in version 3.2.
3001 *
3002 * @ingroup input
3003 */
3004GLFWAPI const char* glfwGetKeyName(int key, int scancode);
3005
3006/*! @brief Returns the last reported state of a keyboard key for the specified
3007 * window.
3008 *
3009 * This function returns the last state reported for the specified key to the
3010 * specified window. The returned state is one of `GLFW_PRESS` or
3011 * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to
3012 * the key callback.
3013 *
3014 * If the `GLFW_STICKY_KEYS` input mode is enabled, this function returns
3015 * `GLFW_PRESS` the first time you call it for a key that was pressed, even if
3016 * that key has already been released.
3017 *
3018 * The key functions deal with physical keys, with [key tokens](@ref keys)
3019 * named after their use on the standard US keyboard layout. If you want to
3020 * input text, use the Unicode character callback instead.
3021 *
3022 * The [modifier key bit masks](@ref mods) are not key tokens and cannot be
3023 * used with this function.
3024 *
3025 * __Do not use this function__ to implement [text input](@ref input_char).
3026 *
3027 * @param[in] window The desired window.
3028 * @param[in] key The desired [keyboard key](@ref keys). `GLFW_KEY_UNKNOWN` is
3029 * not a valid key for this function.
3030 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
3031 *
3032 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3033 * GLFW_INVALID_ENUM.
3034 *
3035 * @thread_safety This function must only be called from the main thread.
3036 *
3037 * @sa @ref input_key
3038 *
3039 * @since Added in version 1.0.
3040 * @glfw3 Added window handle parameter.
3041 *
3042 * @ingroup input
3043 */
3044GLFWAPI int glfwGetKey(GLFWwindow* window, int key);
3045
3046/*! @brief Returns the last reported state of a mouse button for the specified
3047 * window.
3048 *
3049 * This function returns the last state reported for the specified mouse button
3050 * to the specified window. The returned state is one of `GLFW_PRESS` or
3051 * `GLFW_RELEASE`.
3052 *
3053 * If the `GLFW_STICKY_MOUSE_BUTTONS` input mode is enabled, this function
3054 * `GLFW_PRESS` the first time you call it for a mouse button that was pressed,
3055 * even if that mouse button has already been released.
3056 *
3057 * @param[in] window The desired window.
3058 * @param[in] button The desired [mouse button](@ref buttons).
3059 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
3060 *
3061 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3062 * GLFW_INVALID_ENUM.
3063 *
3064 * @thread_safety This function must only be called from the main thread.
3065 *
3066 * @sa @ref input_mouse_button
3067 *
3068 * @since Added in version 1.0.
3069 * @glfw3 Added window handle parameter.
3070 *
3071 * @ingroup input
3072 */
3073GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);
3074
3075/*! @brief Retrieves the position of the cursor relative to the client area of
3076 * the window.
3077 *
3078 * This function returns the position of the cursor, in screen coordinates,
3079 * relative to the upper-left corner of the client area of the specified
3080 * window.
3081 *
3082 * If the cursor is disabled (with `GLFW_CURSOR_DISABLED`) then the cursor
3083 * position is unbounded and limited only by the minimum and maximum values of
3084 * a `double`.
3085 *
3086 * The coordinate can be converted to their integer equivalents with the
3087 * `floor` function. Casting directly to an integer type works for positive
3088 * coordinates, but fails for negative ones.
3089 *
3090 * Any or all of the position arguments may be `NULL`. If an error occurs, all
3091 * non-`NULL` position arguments will be set to zero.
3092 *
3093 * @param[in] window The desired window.
3094 * @param[out] xpos Where to store the cursor x-coordinate, relative to the
3095 * left edge of the client area, or `NULL`.
3096 * @param[out] ypos Where to store the cursor y-coordinate, relative to the to
3097 * top edge of the client area, or `NULL`.
3098 *
3099 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3100 * GLFW_PLATFORM_ERROR.
3101 *
3102 * @thread_safety This function must only be called from the main thread.
3103 *
3104 * @sa @ref cursor_pos
3105 * @sa glfwSetCursorPos
3106 *
3107 * @since Added in version 3.0. Replaces `glfwGetMousePos`.
3108 *
3109 * @ingroup input
3110 */
3111GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
3112
3113/*! @brief Sets the position of the cursor, relative to the client area of the
3114 * window.
3115 *
3116 * This function sets the position, in screen coordinates, of the cursor
3117 * relative to the upper-left corner of the client area of the specified
3118 * window. The window must have input focus. If the window does not have
3119 * input focus when this function is called, it fails silently.
3120 *
3121 * __Do not use this function__ to implement things like camera controls. GLFW
3122 * already provides the `GLFW_CURSOR_DISABLED` cursor mode that hides the
3123 * cursor, transparently re-centers it and provides unconstrained cursor
3124 * motion. See @ref glfwSetInputMode for more information.
3125 *
3126 * If the cursor mode is `GLFW_CURSOR_DISABLED` then the cursor position is
3127 * unconstrained and limited only by the minimum and maximum values of
3128 * a `double`.
3129 *
3130 * @param[in] window The desired window.
3131 * @param[in] xpos The desired x-coordinate, relative to the left edge of the
3132 * client area.
3133 * @param[in] ypos The desired y-coordinate, relative to the top edge of the
3134 * client area.
3135 *
3136 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3137 * GLFW_PLATFORM_ERROR.
3138 *
3139 * @thread_safety This function must only be called from the main thread.
3140 *
3141 * @sa @ref cursor_pos
3142 * @sa glfwGetCursorPos
3143 *
3144 * @since Added in version 3.0. Replaces `glfwSetMousePos`.
3145 *
3146 * @ingroup input
3147 */
3148GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
3149
3150/*! @brief Creates a custom cursor.
3151 *
3152 * Creates a new custom cursor image that can be set for a window with @ref
3153 * glfwSetCursor. The cursor can be destroyed with @ref glfwDestroyCursor.
3154 * Any remaining cursors are destroyed by @ref glfwTerminate.
3155 *
3156 * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight
3157 * bits per channel. They are arranged canonically as packed sequential rows,
3158 * starting from the top-left corner.
3159 *
3160 * The cursor hotspot is specified in pixels, relative to the upper-left corner
3161 * of the cursor image. Like all other coordinate systems in GLFW, the X-axis
3162 * points to the right and the Y-axis points down.
3163 *
3164 * @param[in] image The desired cursor image.
3165 * @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot.
3166 * @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot.
3167 * @return The handle of the created cursor, or `NULL` if an
3168 * [error](@ref error_handling) occurred.
3169 *
3170 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3171 * GLFW_PLATFORM_ERROR.
3172 *
3173 * @pointer_lifetime The specified image data is copied before this function
3174 * returns.
3175 *
3176 * @reentrancy This function must not be called from a callback.
3177 *
3178 * @thread_safety This function must only be called from the main thread.
3179 *
3180 * @sa @ref cursor_object
3181 * @sa glfwDestroyCursor
3182 * @sa glfwCreateStandardCursor
3183 *
3184 * @since Added in version 3.1.
3185 *
3186 * @ingroup input
3187 */
3188GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot);
3189
3190/*! @brief Creates a cursor with a standard shape.
3191 *
3192 * Returns a cursor with a [standard shape](@ref shapes), that can be set for
3193 * a window with @ref glfwSetCursor.
3194 *
3195 * @param[in] shape One of the [standard shapes](@ref shapes).
3196 * @return A new cursor ready to use or `NULL` if an
3197 * [error](@ref error_handling) occurred.
3198 *
3199 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3200 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
3201 *
3202 * @reentrancy This function must not be called from a callback.
3203 *
3204 * @thread_safety This function must only be called from the main thread.
3205 *
3206 * @sa @ref cursor_object
3207 * @sa glfwCreateCursor
3208 *
3209 * @since Added in version 3.1.
3210 *
3211 * @ingroup input
3212 */
3213GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape);
3214
3215/*! @brief Destroys a cursor.
3216 *
3217 * This function destroys a cursor previously created with @ref
3218 * glfwCreateCursor. Any remaining cursors will be destroyed by @ref
3219 * glfwTerminate.
3220 *
3221 * @param[in] cursor The cursor object to destroy.
3222 *
3223 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3224 * GLFW_PLATFORM_ERROR.
3225 *
3226 * @reentrancy This function must not be called from a callback.
3227 *
3228 * @thread_safety This function must only be called from the main thread.
3229 *
3230 * @sa @ref cursor_object
3231 * @sa glfwCreateCursor
3232 *
3233 * @since Added in version 3.1.
3234 *
3235 * @ingroup input
3236 */
3237GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor);
3238
3239/*! @brief Sets the cursor for the window.
3240 *
3241 * This function sets the cursor image to be used when the cursor is over the
3242 * client area of the specified window. The set cursor will only be visible
3243 * when the [cursor mode](@ref cursor_mode) of the window is
3244 * `GLFW_CURSOR_NORMAL`.
3245 *
3246 * On some platforms, the set cursor may not be visible unless the window also
3247 * has input focus.
3248 *
3249 * @param[in] window The window to set the cursor for.
3250 * @param[in] cursor The cursor to set, or `NULL` to switch back to the default
3251 * arrow cursor.
3252 *
3253 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3254 * GLFW_PLATFORM_ERROR.
3255 *
3256 * @thread_safety This function must only be called from the main thread.
3257 *
3258 * @sa @ref cursor_object
3259 *
3260 * @since Added in version 3.1.
3261 *
3262 * @ingroup input
3263 */
3264GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
3265
3266/*! @brief Sets the key callback.
3267 *
3268 * This function sets the key callback of the specified window, which is called
3269 * when a key is pressed, repeated or released.
3270 *
3271 * The key functions deal with physical keys, with layout independent
3272 * [key tokens](@ref keys) named after their values in the standard US keyboard
3273 * layout. If you want to input text, use the
3274 * [character callback](@ref glfwSetCharCallback) instead.
3275 *
3276 * When a window loses input focus, it will generate synthetic key release
3277 * events for all pressed keys. You can tell these events from user-generated
3278 * events by the fact that the synthetic ones are generated after the focus
3279 * loss event has been processed, i.e. after the
3280 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
3281 *
3282 * The scancode of a key is specific to that platform or sometimes even to that
3283 * machine. Scancodes are intended to allow users to bind keys that don't have
3284 * a GLFW key token. Such keys have `key` set to `GLFW_KEY_UNKNOWN`, their
3285 * state is not saved and so it cannot be queried with @ref glfwGetKey.
3286 *
3287 * Sometimes GLFW needs to generate synthetic key events, in which case the
3288 * scancode may be zero.
3289 *
3290 * @param[in] window The window whose callback to set.
3291 * @param[in] cbfun The new key callback, or `NULL` to remove the currently
3292 * set callback.
3293 * @return The previously set callback, or `NULL` if no callback was set or the
3294 * library had not been [initialized](@ref intro_init).
3295 *
3296 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3297 *
3298 * @thread_safety This function must only be called from the main thread.
3299 *
3300 * @sa @ref input_key
3301 *
3302 * @since Added in version 1.0.
3303 * @glfw3 Added window handle parameter and return value.
3304 *
3305 * @ingroup input
3306 */
3307GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
3308
3309/*! @brief Sets the Unicode character callback.
3310 *
3311 * This function sets the character callback of the specified window, which is
3312 * called when a Unicode character is input.
3313 *
3314 * The character callback is intended for Unicode text input. As it deals with
3315 * characters, it is keyboard layout dependent, whereas the
3316 * [key callback](@ref glfwSetKeyCallback) is not. Characters do not map 1:1
3317 * to physical keys, as a key may produce zero, one or more characters. If you
3318 * want to know whether a specific physical key was pressed or released, see
3319 * the key callback instead.
3320 *
3321 * The character callback behaves as system text input normally does and will
3322 * not be called if modifier keys are held down that would prevent normal text
3323 * input on that platform, for example a Super (Command) key on OS X or Alt key
3324 * on Windows. There is a
3325 * [character with modifiers callback](@ref glfwSetCharModsCallback) that
3326 * receives these events.
3327 *
3328 * @param[in] window The window whose callback to set.
3329 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
3330 * callback.
3331 * @return The previously set callback, or `NULL` if no callback was set or the
3332 * library had not been [initialized](@ref intro_init).
3333 *
3334 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3335 *
3336 * @thread_safety This function must only be called from the main thread.
3337 *
3338 * @sa @ref input_char
3339 *
3340 * @since Added in version 2.4.
3341 * @glfw3 Added window handle parameter and return value.
3342 *
3343 * @ingroup input
3344 */
3345GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
3346
3347/*! @brief Sets the Unicode character with modifiers callback.
3348 *
3349 * This function sets the character with modifiers callback of the specified
3350 * window, which is called when a Unicode character is input regardless of what
3351 * modifier keys are used.
3352 *
3353 * The character with modifiers callback is intended for implementing custom
3354 * Unicode character input. For regular Unicode text input, see the
3355 * [character callback](@ref glfwSetCharCallback). Like the character
3356 * callback, the character with modifiers callback deals with characters and is
3357 * keyboard layout dependent. Characters do not map 1:1 to physical keys, as
3358 * a key may produce zero, one or more characters. If you want to know whether
3359 * a specific physical key was pressed or released, see the
3360 * [key callback](@ref glfwSetKeyCallback) instead.
3361 *
3362 * @param[in] window The window whose callback to set.
3363 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
3364 * callback.
3365 * @return The previously set callback, or `NULL` if no callback was set or an
3366 * [error](@ref error_handling) occurred.
3367 *
3368 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3369 *
3370 * @thread_safety This function must only be called from the main thread.
3371 *
3372 * @sa @ref input_char
3373 *
3374 * @since Added in version 3.1.
3375 *
3376 * @ingroup input
3377 */
3378GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun cbfun);
3379
3380/*! @brief Sets the mouse button callback.
3381 *
3382 * This function sets the mouse button callback of the specified window, which
3383 * is called when a mouse button is pressed or released.
3384 *
3385 * When a window loses input focus, it will generate synthetic mouse button
3386 * release events for all pressed mouse buttons. You can tell these events
3387 * from user-generated events by the fact that the synthetic ones are generated
3388 * after the focus loss event has been processed, i.e. after the
3389 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
3390 *
3391 * @param[in] window The window whose callback to set.
3392 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
3393 * callback.
3394 * @return The previously set callback, or `NULL` if no callback was set or the
3395 * library had not been [initialized](@ref intro_init).
3396 *
3397 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3398 *
3399 * @thread_safety This function must only be called from the main thread.
3400 *
3401 * @sa @ref input_mouse_button
3402 *
3403 * @since Added in version 1.0.
3404 * @glfw3 Added window handle parameter and return value.
3405 *
3406 * @ingroup input
3407 */
3408GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun cbfun);
3409
3410/*! @brief Sets the cursor position callback.
3411 *
3412 * This function sets the cursor position callback of the specified window,
3413 * which is called when the cursor is moved. The callback is provided with the
3414 * position, in screen coordinates, relative to the upper-left corner of the
3415 * client area of the window.
3416 *
3417 * @param[in] window The window whose callback to set.
3418 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
3419 * callback.
3420 * @return The previously set callback, or `NULL` if no callback was set or the
3421 * library had not been [initialized](@ref intro_init).
3422 *
3423 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3424 *
3425 * @thread_safety This function must only be called from the main thread.
3426 *
3427 * @sa @ref cursor_pos
3428 *
3429 * @since Added in version 3.0. Replaces `glfwSetMousePosCallback`.
3430 *
3431 * @ingroup input
3432 */
3433GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun cbfun);
3434
3435/*! @brief Sets the cursor enter/exit callback.
3436 *
3437 * This function sets the cursor boundary crossing callback of the specified
3438 * window, which is called when the cursor enters or leaves the client area of
3439 * the window.
3440 *
3441 * @param[in] window The window whose callback to set.
3442 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
3443 * callback.
3444 * @return The previously set callback, or `NULL` if no callback was set or the
3445 * library had not been [initialized](@ref intro_init).
3446 *
3447 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3448 *
3449 * @thread_safety This function must only be called from the main thread.
3450 *
3451 * @sa @ref cursor_enter
3452 *
3453 * @since Added in version 3.0.
3454 *
3455 * @ingroup input
3456 */
3457GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun cbfun);
3458
3459/*! @brief Sets the scroll callback.
3460 *
3461 * This function sets the scroll callback of the specified window, which is
3462 * called when a scrolling device is used, such as a mouse wheel or scrolling
3463 * area of a touchpad.
3464 *
3465 * The scroll callback receives all scrolling input, like that from a mouse
3466 * wheel or a touchpad scrolling area.
3467 *
3468 * @param[in] window The window whose callback to set.
3469 * @param[in] cbfun The new scroll callback, or `NULL` to remove the currently
3470 * set callback.
3471 * @return The previously set callback, or `NULL` if no callback was set or the
3472 * library had not been [initialized](@ref intro_init).
3473 *
3474 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3475 *
3476 * @thread_safety This function must only be called from the main thread.
3477 *
3478 * @sa @ref scrolling
3479 *
3480 * @since Added in version 3.0. Replaces `glfwSetMouseWheelCallback`.
3481 *
3482 * @ingroup input
3483 */
3484GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cbfun);
3485
3486/*! @brief Sets the file drop callback.
3487 *
3488 * This function sets the file drop callback of the specified window, which is
3489 * called when one or more dragged files are dropped on the window.
3490 *
3491 * Because the path array and its strings may have been generated specifically
3492 * for that event, they are not guaranteed to be valid after the callback has
3493 * returned. If you wish to use them after the callback returns, you need to
3494 * make a deep copy.
3495 *
3496 * @param[in] window The window whose callback to set.
3497 * @param[in] cbfun The new file drop callback, or `NULL` to remove the
3498 * currently set callback.
3499 * @return The previously set callback, or `NULL` if no callback was set or the
3500 * library had not been [initialized](@ref intro_init).
3501 *
3502 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3503 *
3504 * @thread_safety This function must only be called from the main thread.
3505 *
3506 * @sa @ref path_drop
3507 *
3508 * @since Added in version 3.1.
3509 *
3510 * @ingroup input
3511 */
3512GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun);
3513
3514/*! @brief Returns whether the specified joystick is present.
3515 *
3516 * This function returns whether the specified joystick is present.
3517 *
3518 * @param[in] joy The [joystick](@ref joysticks) to query.
3519 * @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise.
3520 *
3521 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3522 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
3523 *
3524 * @thread_safety This function must only be called from the main thread.
3525 *
3526 * @sa @ref joystick
3527 *
3528 * @since Added in version 3.0. Replaces `glfwGetJoystickParam`.
3529 *
3530 * @ingroup input
3531 */
3532GLFWAPI int glfwJoystickPresent(int joy);
3533
3534/*! @brief Returns the values of all axes of the specified joystick.
3535 *
3536 * This function returns the values of all axes of the specified joystick.
3537 * Each element in the array is a value between -1.0 and 1.0.
3538 *
3539 * Querying a joystick slot with no device present is not an error, but will
3540 * cause this function to return `NULL`. Call @ref glfwJoystickPresent to
3541 * check device presence.
3542 *
3543 * @param[in] joy The [joystick](@ref joysticks) to query.
3544 * @param[out] count Where to store the number of axis values in the returned
3545 * array. This is set to zero if the joystick is not present or an error
3546 * occurred.
3547 * @return An array of axis values, or `NULL` if the joystick is not present or
3548 * an [error](@ref error_handling) occurred.
3549 *
3550 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3551 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
3552 *
3553 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
3554 * should not free it yourself. It is valid until the specified joystick is
3555 * disconnected, this function is called again for that joystick or the library
3556 * is terminated.
3557 *
3558 * @thread_safety This function must only be called from the main thread.
3559 *
3560 * @sa @ref joystick_axis
3561 *
3562 * @since Added in version 3.0. Replaces `glfwGetJoystickPos`.
3563 *
3564 * @ingroup input
3565 */
3566GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count);
3567
3568/*! @brief Returns the state of all buttons of the specified joystick.
3569 *
3570 * This function returns the state of all buttons of the specified joystick.
3571 * Each element in the array is either `GLFW_PRESS` or `GLFW_RELEASE`.
3572 *
3573 * Querying a joystick slot with no device present is not an error, but will
3574 * cause this function to return `NULL`. Call @ref glfwJoystickPresent to
3575 * check device presence.
3576 *
3577 * @param[in] joy The [joystick](@ref joysticks) to query.
3578 * @param[out] count Where to store the number of button states in the returned
3579 * array. This is set to zero if the joystick is not present or an error
3580 * occurred.
3581 * @return An array of button states, or `NULL` if the joystick is not present
3582 * or an [error](@ref error_handling) occurred.
3583 *
3584 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3585 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
3586 *
3587 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
3588 * should not free it yourself. It is valid until the specified joystick is
3589 * disconnected, this function is called again for that joystick or the library
3590 * is terminated.
3591 *
3592 * @thread_safety This function must only be called from the main thread.
3593 *
3594 * @sa @ref joystick_button
3595 *
3596 * @since Added in version 2.2.
3597 * @glfw3 Changed to return a dynamic array.
3598 *
3599 * @ingroup input
3600 */
3601GLFWAPI const unsigned char* glfwGetJoystickButtons(int joy, int* count);
3602
3603/*! @brief Returns the name of the specified joystick.
3604 *
3605 * This function returns the name, encoded as UTF-8, of the specified joystick.
3606 * The returned string is allocated and freed by GLFW. You should not free it
3607 * yourself.
3608 *
3609 * Querying a joystick slot with no device present is not an error, but will
3610 * cause this function to return `NULL`. Call @ref glfwJoystickPresent to
3611 * check device presence.
3612 *
3613 * @param[in] joy The [joystick](@ref joysticks) to query.
3614 * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick
3615 * is not present or an [error](@ref error_handling) occurred.
3616 *
3617 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3618 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
3619 *
3620 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
3621 * should not free it yourself. It is valid until the specified joystick is
3622 * disconnected, this function is called again for that joystick or the library
3623 * is terminated.
3624 *
3625 * @thread_safety This function must only be called from the main thread.
3626 *
3627 * @sa @ref joystick_name
3628 *
3629 * @since Added in version 3.0.
3630 *
3631 * @ingroup input
3632 */
3633GLFWAPI const char* glfwGetJoystickName(int joy);
3634
3635/*! @brief Sets the joystick configuration callback.
3636 *
3637 * This function sets the joystick configuration callback, or removes the
3638 * currently set callback. This is called when a joystick is connected to or
3639 * disconnected from the system.
3640 *
3641 * @param[in] cbfun The new callback, or `NULL` to remove the currently set
3642 * callback.
3643 * @return The previously set callback, or `NULL` if no callback was set or the
3644 * library had not been [initialized](@ref intro_init).
3645 *
3646 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3647 *
3648 * @thread_safety This function must only be called from the main thread.
3649 *
3650 * @sa @ref joystick_event
3651 *
3652 * @since Added in version 3.2.
3653 *
3654 * @ingroup input
3655 */
3656GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun);
3657
3658/*! @brief Sets the clipboard to the specified string.
3659 *
3660 * This function sets the system clipboard to the specified, UTF-8 encoded
3661 * string.
3662 *
3663 * @param[in] window The window that will own the clipboard contents.
3664 * @param[in] string A UTF-8 encoded string.
3665 *
3666 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3667 * GLFW_PLATFORM_ERROR.
3668 *
3669 * @pointer_lifetime The specified string is copied before this function
3670 * returns.
3671 *
3672 * @thread_safety This function must only be called from the main thread.
3673 *
3674 * @sa @ref clipboard
3675 * @sa glfwGetClipboardString
3676 *
3677 * @since Added in version 3.0.
3678 *
3679 * @ingroup input
3680 */
3681GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string);
3682
3683/*! @brief Returns the contents of the clipboard as a string.
3684 *
3685 * This function returns the contents of the system clipboard, if it contains
3686 * or is convertible to a UTF-8 encoded string. If the clipboard is empty or
3687 * if its contents cannot be converted, `NULL` is returned and a @ref
3688 * GLFW_FORMAT_UNAVAILABLE error is generated.
3689 *
3690 * @param[in] window The window that will request the clipboard contents.
3691 * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL`
3692 * if an [error](@ref error_handling) occurred.
3693 *
3694 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3695 * GLFW_PLATFORM_ERROR.
3696 *
3697 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
3698 * should not free it yourself. It is valid until the next call to @ref
3699 * glfwGetClipboardString or @ref glfwSetClipboardString, or until the library
3700 * is terminated.
3701 *
3702 * @thread_safety This function must only be called from the main thread.
3703 *
3704 * @sa @ref clipboard
3705 * @sa glfwSetClipboardString
3706 *
3707 * @since Added in version 3.0.
3708 *
3709 * @ingroup input
3710 */
3711GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window);
3712
3713/*! @brief Returns the value of the GLFW timer.
3714 *
3715 * This function returns the value of the GLFW timer. Unless the timer has
3716 * been set using @ref glfwSetTime, the timer measures time elapsed since GLFW
3717 * was initialized.
3718 *
3719 * The resolution of the timer is system dependent, but is usually on the order
3720 * of a few micro- or nanoseconds. It uses the highest-resolution monotonic
3721 * time source on each supported platform.
3722 *
3723 * @return The current value, in seconds, or zero if an
3724 * [error](@ref error_handling) occurred.
3725 *
3726 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3727 *
3728 * @thread_safety This function may be called from any thread. Reading and
3729 * writing of the internal timer offset is not atomic, so it needs to be
3730 * externally synchronized with calls to @ref glfwSetTime.
3731 *
3732 * @sa @ref time
3733 *
3734 * @since Added in version 1.0.
3735 *
3736 * @ingroup input
3737 */
3738GLFWAPI double glfwGetTime(void);
3739
3740/*! @brief Sets the GLFW timer.
3741 *
3742 * This function sets the value of the GLFW timer. It then continues to count
3743 * up from that value. The value must be a positive finite number less than
3744 * or equal to 18446744073.0, which is approximately 584.5 years.
3745 *
3746 * @param[in] time The new value, in seconds.
3747 *
3748 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3749 * GLFW_INVALID_VALUE.
3750 *
3751 * @remark The upper limit of the timer is calculated as
3752 * floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations
3753 * storing nanoseconds in 64 bits. The limit may be increased in the future.
3754 *
3755 * @thread_safety This function may be called from any thread. Reading and
3756 * writing of the internal timer offset is not atomic, so it needs to be
3757 * externally synchronized with calls to @ref glfwGetTime.
3758 *
3759 * @sa @ref time
3760 *
3761 * @since Added in version 2.2.
3762 *
3763 * @ingroup input
3764 */
3765GLFWAPI void glfwSetTime(double time);
3766
3767/*! @brief Returns the current value of the raw timer.
3768 *
3769 * This function returns the current value of the raw timer, measured in
3770 * 1&nbsp;/&nbsp;frequency seconds. To get the frequency, call @ref
3771 * glfwGetTimerFrequency.
3772 *
3773 * @return The value of the timer, or zero if an
3774 * [error](@ref error_handling) occurred.
3775 *
3776 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3777 *
3778 * @thread_safety This function may be called from any thread.
3779 *
3780 * @sa @ref time
3781 * @sa glfwGetTimerFrequency
3782 *
3783 * @since Added in version 3.2.
3784 *
3785 * @ingroup input
3786 */
3787GLFWAPI uint64_t glfwGetTimerValue(void);
3788
3789/*! @brief Returns the frequency, in Hz, of the raw timer.
3790 *
3791 * This function returns the frequency, in Hz, of the raw timer.
3792 *
3793 * @return The frequency of the timer, in Hz, or zero if an
3794 * [error](@ref error_handling) occurred.
3795 *
3796 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3797 *
3798 * @thread_safety This function may be called from any thread.
3799 *
3800 * @sa @ref time
3801 * @sa glfwGetTimerValue
3802 *
3803 * @since Added in version 3.2.
3804 *
3805 * @ingroup input
3806 */
3807GLFWAPI uint64_t glfwGetTimerFrequency(void);
3808
3809/*! @brief Makes the context of the specified window current for the calling
3810 * thread.
3811 *
3812 * This function makes the OpenGL or OpenGL ES context of the specified window
3813 * current on the calling thread. A context can only be made current on
3814 * a single thread at a time and each thread can have only a single current
3815 * context at a time.
3816 *
3817 * By default, making a context non-current implicitly forces a pipeline flush.
3818 * On machines that support `GL_KHR_context_flush_control`, you can control
3819 * whether a context performs this flush by setting the
3820 * [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref window_hints_ctx) window hint.
3821 *
3822 * The specified window must have an OpenGL or OpenGL ES context. Specifying
3823 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
3824 * error.
3825 *
3826 * @param[in] window The window whose context to make current, or `NULL` to
3827 * detach the current context.
3828 *
3829 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3830 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
3831 *
3832 * @thread_safety This function may be called from any thread.
3833 *
3834 * @sa @ref context_current
3835 * @sa glfwGetCurrentContext
3836 *
3837 * @since Added in version 3.0.
3838 *
3839 * @ingroup context
3840 */
3841GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window);
3842
3843/*! @brief Returns the window whose context is current on the calling thread.
3844 *
3845 * This function returns the window whose OpenGL or OpenGL ES context is
3846 * current on the calling thread.
3847 *
3848 * @return The window whose context is current, or `NULL` if no window's
3849 * context is current.
3850 *
3851 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3852 *
3853 * @thread_safety This function may be called from any thread.
3854 *
3855 * @sa @ref context_current
3856 * @sa glfwMakeContextCurrent
3857 *
3858 * @since Added in version 3.0.
3859 *
3860 * @ingroup context
3861 */
3862GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
3863
3864/*! @brief Swaps the front and back buffers of the specified window.
3865 *
3866 * This function swaps the front and back buffers of the specified window when
3867 * rendering with OpenGL or OpenGL ES. If the swap interval is greater than
3868 * zero, the GPU driver waits the specified number of screen updates before
3869 * swapping the buffers.
3870 *
3871 * The specified window must have an OpenGL or OpenGL ES context. Specifying
3872 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
3873 * error.
3874 *
3875 * This function does not apply to Vulkan. If you are rendering with Vulkan,
3876 * see `vkQueuePresentKHR` instead.
3877 *
3878 * @param[in] window The window whose buffers to swap.
3879 *
3880 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3881 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
3882 *
3883 * @remark __EGL:__ The context of the specified window must be current on the
3884 * calling thread.
3885 *
3886 * @thread_safety This function may be called from any thread.
3887 *
3888 * @sa @ref buffer_swap
3889 * @sa glfwSwapInterval
3890 *
3891 * @since Added in version 1.0.
3892 * @glfw3 Added window handle parameter.
3893 *
3894 * @ingroup window
3895 */
3896GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
3897
3898/*! @brief Sets the swap interval for the current context.
3899 *
3900 * This function sets the swap interval for the current OpenGL or OpenGL ES
3901 * context, i.e. the number of screen updates to wait from the time @ref
3902 * glfwSwapBuffers was called before swapping the buffers and returning. This
3903 * is sometimes called _vertical synchronization_, _vertical retrace
3904 * synchronization_ or just _vsync_.
3905 *
3906 * Contexts that support either of the `WGL_EXT_swap_control_tear` and
3907 * `GLX_EXT_swap_control_tear` extensions also accept negative swap intervals,
3908 * which allow the driver to swap even if a frame arrives a little bit late.
3909 * You can check for the presence of these extensions using @ref
3910 * glfwExtensionSupported. For more information about swap tearing, see the
3911 * extension specifications.
3912 *
3913 * A context must be current on the calling thread. Calling this function
3914 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
3915 *
3916 * This function does not apply to Vulkan. If you are rendering with Vulkan,
3917 * see the present mode of your swapchain instead.
3918 *
3919 * @param[in] interval The minimum number of screen updates to wait for
3920 * until the buffers are swapped by @ref glfwSwapBuffers.
3921 *
3922 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3923 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR.
3924 *
3925 * @remark This function is not called during context creation, leaving the
3926 * swap interval set to whatever is the default on that platform. This is done
3927 * because some swap interval extensions used by GLFW do not allow the swap
3928 * interval to be reset to zero once it has been set to a non-zero value.
3929 *
3930 * @remark Some GPU drivers do not honor the requested swap interval, either
3931 * because of a user setting that overrides the application's request or due to
3932 * bugs in the driver.
3933 *
3934 * @thread_safety This function may be called from any thread.
3935 *
3936 * @sa @ref buffer_swap
3937 * @sa glfwSwapBuffers
3938 *
3939 * @since Added in version 1.0.
3940 *
3941 * @ingroup context
3942 */
3943GLFWAPI void glfwSwapInterval(int interval);
3944
3945/*! @brief Returns whether the specified extension is available.
3946 *
3947 * This function returns whether the specified
3948 * [API extension](@ref context_glext) is supported by the current OpenGL or
3949 * OpenGL ES context. It searches both for client API extension and context
3950 * creation API extensions.
3951 *
3952 * A context must be current on the calling thread. Calling this function
3953 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
3954 *
3955 * As this functions retrieves and searches one or more extension strings each
3956 * call, it is recommended that you cache its results if it is going to be used
3957 * frequently. The extension strings will not change during the lifetime of
3958 * a context, so there is no danger in doing this.
3959 *
3960 * This function does not apply to Vulkan. If you are using Vulkan, see @ref
3961 * glfwGetRequiredInstanceExtensions, `vkEnumerateInstanceExtensionProperties`
3962 * and `vkEnumerateDeviceExtensionProperties` instead.
3963 *
3964 * @param[in] extension The ASCII encoded name of the extension.
3965 * @return `GLFW_TRUE` if the extension is available, or `GLFW_FALSE`
3966 * otherwise.
3967 *
3968 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3969 * GLFW_NO_CURRENT_CONTEXT, @ref GLFW_INVALID_VALUE and @ref
3970 * GLFW_PLATFORM_ERROR.
3971 *
3972 * @thread_safety This function may be called from any thread.
3973 *
3974 * @sa @ref context_glext
3975 * @sa glfwGetProcAddress
3976 *
3977 * @since Added in version 1.0.
3978 *
3979 * @ingroup context
3980 */
3981GLFWAPI int glfwExtensionSupported(const char* extension);
3982
3983/*! @brief Returns the address of the specified function for the current
3984 * context.
3985 *
3986 * This function returns the address of the specified OpenGL or OpenGL ES
3987 * [core or extension function](@ref context_glext), if it is supported
3988 * by the current context.
3989 *
3990 * A context must be current on the calling thread. Calling this function
3991 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
3992 *
3993 * This function does not apply to Vulkan. If you are rendering with Vulkan,
3994 * see @ref glfwGetInstanceProcAddress, `vkGetInstanceProcAddr` and
3995 * `vkGetDeviceProcAddr` instead.
3996 *
3997 * @param[in] procname The ASCII encoded name of the function.
3998 * @return The address of the function, or `NULL` if an
3999 * [error](@ref error_handling) occurred.
4000 *
4001 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4002 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR.
4003 *
4004 * @remark The address of a given function is not guaranteed to be the same
4005 * between contexts.
4006 *
4007 * @remark This function may return a non-`NULL` address despite the
4008 * associated version or extension not being available. Always check the
4009 * context version or extension string first.
4010 *
4011 * @pointer_lifetime The returned function pointer is valid until the context
4012 * is destroyed or the library is terminated.
4013 *
4014 * @thread_safety This function may be called from any thread.
4015 *
4016 * @sa @ref context_glext
4017 * @sa glfwExtensionSupported
4018 *
4019 * @since Added in version 1.0.
4020 *
4021 * @ingroup context
4022 */
4023GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname);
4024
4025/*! @brief Returns whether the Vulkan loader has been found.
4026 *
4027 * This function returns whether the Vulkan loader has been found. This check
4028 * is performed by @ref glfwInit.
4029 *
4030 * The availability of a Vulkan loader does not by itself guarantee that window
4031 * surface creation or even device creation is possible. Call @ref
4032 * glfwGetRequiredInstanceExtensions to check whether the extensions necessary
4033 * for Vulkan surface creation are available and @ref
4034 * glfwGetPhysicalDevicePresentationSupport to check whether a queue family of
4035 * a physical device supports image presentation.
4036 *
4037 * @return `GLFW_TRUE` if Vulkan is available, or `GLFW_FALSE` otherwise.
4038 *
4039 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4040 *
4041 * @thread_safety This function may be called from any thread.
4042 *
4043 * @sa @ref vulkan_support
4044 *
4045 * @since Added in version 3.2.
4046 *
4047 * @ingroup vulkan
4048 */
4049GLFWAPI int glfwVulkanSupported(void);
4050
4051/*! @brief Returns the Vulkan instance extensions required by GLFW.
4052 *
4053 * This function returns an array of names of Vulkan instance extensions required
4054 * by GLFW for creating Vulkan surfaces for GLFW windows. If successful, the
4055 * list will always contains `VK_KHR_surface`, so if you don't require any
4056 * additional extensions you can pass this list directly to the
4057 * `VkInstanceCreateInfo` struct.
4058 *
4059 * If Vulkan is not available on the machine, this function returns `NULL` and
4060 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
4061 * to check whether Vulkan is available.
4062 *
4063 * If Vulkan is available but no set of extensions allowing window surface
4064 * creation was found, this function returns `NULL`. You may still use Vulkan
4065 * for off-screen rendering and compute work.
4066 *
4067 * @param[out] count Where to store the number of extensions in the returned
4068 * array. This is set to zero if an error occurred.
4069 * @return An array of ASCII encoded extension names, or `NULL` if an
4070 * [error](@ref error_handling) occurred.
4071 *
4072 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4073 * GLFW_API_UNAVAILABLE.
4074 *
4075 * @remarks Additional extensions may be required by future versions of GLFW.
4076 * You should check if any extensions you wish to enable are already in the
4077 * returned array, as it is an error to specify an extension more than once in
4078 * the `VkInstanceCreateInfo` struct.
4079 *
4080 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
4081 * should not free it yourself. It is guaranteed to be valid only until the
4082 * library is terminated.
4083 *
4084 * @thread_safety This function may be called from any thread.
4085 *
4086 * @sa @ref vulkan_ext
4087 * @sa glfwCreateWindowSurface
4088 *
4089 * @since Added in version 3.2.
4090 *
4091 * @ingroup vulkan
4092 */
4093GLFWAPI const char** glfwGetRequiredInstanceExtensions(uint32_t* count);
4094
4095#if defined(VK_VERSION_1_0)
4096
4097/*! @brief Returns the address of the specified Vulkan instance function.
4098 *
4099 * This function returns the address of the specified Vulkan core or extension
4100 * function for the specified instance. If instance is set to `NULL` it can
4101 * return any function exported from the Vulkan loader, including at least the
4102 * following functions:
4103 *
4104 * - `vkEnumerateInstanceExtensionProperties`
4105 * - `vkEnumerateInstanceLayerProperties`
4106 * - `vkCreateInstance`
4107 * - `vkGetInstanceProcAddr`
4108 *
4109 * If Vulkan is not available on the machine, this function returns `NULL` and
4110 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
4111 * to check whether Vulkan is available.
4112 *
4113 * This function is equivalent to calling `vkGetInstanceProcAddr` with
4114 * a platform-specific query of the Vulkan loader as a fallback.
4115 *
4116 * @param[in] instance The Vulkan instance to query, or `NULL` to retrieve
4117 * functions related to instance creation.
4118 * @param[in] procname The ASCII encoded name of the function.
4119 * @return The address of the function, or `NULL` if an
4120 * [error](@ref error_handling) occurred.
4121 *
4122 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4123 * GLFW_API_UNAVAILABLE.
4124 *
4125 * @pointer_lifetime The returned function pointer is valid until the library
4126 * is terminated.
4127 *
4128 * @thread_safety This function may be called from any thread.
4129 *
4130 * @sa @ref vulkan_proc
4131 *
4132 * @since Added in version 3.2.
4133 *
4134 * @ingroup vulkan
4135 */
4136GLFWAPI GLFWvkproc glfwGetInstanceProcAddress(VkInstance instance, const char* procname);
4137
4138/*! @brief Returns whether the specified queue family can present images.
4139 *
4140 * This function returns whether the specified queue family of the specified
4141 * physical device supports presentation to the platform GLFW was built for.
4142 *
4143 * If Vulkan or the required window surface creation instance extensions are
4144 * not available on the machine, or if the specified instance was not created
4145 * with the required extensions, this function returns `GLFW_FALSE` and
4146 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
4147 * to check whether Vulkan is available and @ref
4148 * glfwGetRequiredInstanceExtensions to check what instance extensions are
4149 * required.
4150 *
4151 * @param[in] instance The instance that the physical device belongs to.
4152 * @param[in] device The physical device that the queue family belongs to.
4153 * @param[in] queuefamily The index of the queue family to query.
4154 * @return `GLFW_TRUE` if the queue family supports presentation, or
4155 * `GLFW_FALSE` otherwise.
4156 *
4157 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4158 * GLFW_API_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR.
4159 *
4160 * @thread_safety This function may be called from any thread. For
4161 * synchronization details of Vulkan objects, see the Vulkan specification.
4162 *
4163 * @sa @ref vulkan_present
4164 *
4165 * @since Added in version 3.2.
4166 *
4167 * @ingroup vulkan
4168 */
4169GLFWAPI int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily);
4170
4171/*! @brief Creates a Vulkan surface for the specified window.
4172 *
4173 * This function creates a Vulkan surface for the specified window.
4174 *
4175 * If the Vulkan loader was not found at initialization, this function returns
4176 * `VK_ERROR_INITIALIZATION_FAILED` and generates a @ref GLFW_API_UNAVAILABLE
4177 * error. Call @ref glfwVulkanSupported to check whether the Vulkan loader was
4178 * found.
4179 *
4180 * If the required window surface creation instance extensions are not
4181 * available or if the specified instance was not created with these extensions
4182 * enabled, this function returns `VK_ERROR_EXTENSION_NOT_PRESENT` and
4183 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref
4184 * glfwGetRequiredInstanceExtensions to check what instance extensions are
4185 * required.
4186 *
4187 * The window surface must be destroyed before the specified Vulkan instance.
4188 * It is the responsibility of the caller to destroy the window surface. GLFW
4189 * does not destroy it for you. Call `vkDestroySurfaceKHR` to destroy the
4190 * surface.
4191 *
4192 * @param[in] instance The Vulkan instance to create the surface in.
4193 * @param[in] window The window to create the surface for.
4194 * @param[in] allocator The allocator to use, or `NULL` to use the default
4195 * allocator.
4196 * @param[out] surface Where to store the handle of the surface. This is set
4197 * to `VK_NULL_HANDLE` if an error occurred.
4198 * @return `VK_SUCCESS` if successful, or a Vulkan error code if an
4199 * [error](@ref error_handling) occurred.
4200 *
4201 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4202 * GLFW_API_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR.
4203 *
4204 * @remarks If an error occurs before the creation call is made, GLFW returns
4205 * the Vulkan error code most appropriate for the error. Appropriate use of
4206 * @ref glfwVulkanSupported and @ref glfwGetRequiredInstanceExtensions should
4207 * eliminate almost all occurrences of these errors.
4208 *
4209 * @thread_safety This function may be called from any thread. For
4210 * synchronization details of Vulkan objects, see the Vulkan specification.
4211 *
4212 * @sa @ref vulkan_surface
4213 * @sa glfwGetRequiredInstanceExtensions
4214 *
4215 * @since Added in version 3.2.
4216 *
4217 * @ingroup vulkan
4218 */
4219GLFWAPI VkResult glfwCreateWindowSurface(VkInstance instance, GLFWwindow* window, const VkAllocationCallbacks* allocator, VkSurfaceKHR* surface);
4220
4221#endif /*VK_VERSION_1_0*/
4222
4223
4224/*************************************************************************
4225 * Global definition cleanup
4226 *************************************************************************/
4227
4228/* ------------------- BEGIN SYSTEM/COMPILER SPECIFIC -------------------- */
4229
4230#ifdef GLFW_WINGDIAPI_DEFINED
4231 #undef WINGDIAPI
4232 #undef GLFW_WINGDIAPI_DEFINED
4233#endif
4234
4235#ifdef GLFW_CALLBACK_DEFINED
4236 #undef CALLBACK
4237 #undef GLFW_CALLBACK_DEFINED
4238#endif
4239
4240/* -------------------- END SYSTEM/COMPILER SPECIFIC --------------------- */
4241
4242
4243#ifdef __cplusplus
4244}
4245#endif
4246
4247#endif /* _glfw3_h_ */
4248
4249