aboutsummaryrefslogtreecommitdiff
path: root/contrib/glfw/glfw-3.3.5.bin.WIN64/include
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/glfw/glfw-3.3.5.bin.WIN64/include')
-rw-r--r--contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3.h5907
-rw-r--r--contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3native.h594
2 files changed, 6501 insertions, 0 deletions
diff --git a/contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3.h b/contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3.h
new file mode 100644
index 0000000..9503dd0
--- /dev/null
+++ b/contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3.h
@@ -0,0 +1,5907 @@
1/*************************************************************************
2 * GLFW 3.3 - www.glfw.org
3 * A library for OpenGL, window and input
4 *------------------------------------------------------------------------
5 * Copyright (c) 2002-2006 Marcus Geelnard
6 * Copyright (c) 2006-2019 Camilla Löwy <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 * @brief Functions and types related to OpenGL and OpenGL ES contexts.
51 *
52 * This is the reference documentation for OpenGL and OpenGL ES context related
53 * functions. For more task-oriented information, see the @ref context_guide.
54 */
55/*! @defgroup vulkan Vulkan support reference
56 * @brief Functions and types related to Vulkan.
57 *
58 * This is the reference documentation for Vulkan related functions and types.
59 * For more task-oriented information, see the @ref vulkan_guide.
60 */
61/*! @defgroup init Initialization, version and error reference
62 * @brief Functions and types related to initialization and error handling.
63 *
64 * This is the reference documentation for initialization and termination of
65 * the library, version management and error handling. For more task-oriented
66 * information, see the @ref intro_guide.
67 */
68/*! @defgroup input Input reference
69 * @brief Functions and types related to input handling.
70 *
71 * This is the reference documentation for input related functions and types.
72 * For more task-oriented information, see the @ref input_guide.
73 */
74/*! @defgroup monitor Monitor reference
75 * @brief Functions and types related to monitors.
76 *
77 * This is the reference documentation for monitor related functions and types.
78 * For more task-oriented information, see the @ref monitor_guide.
79 */
80/*! @defgroup window Window reference
81 * @brief Functions and types related to windows.
82 *
83 * This is the reference documentation for window related functions and types,
84 * including creation, deletion and event polling. For more task-oriented
85 * information, see the @ref window_guide.
86 */
87
88
89/*************************************************************************
90 * Compiler- and platform-specific preprocessor work
91 *************************************************************************/
92
93/* If we are we on Windows, we want a single define for it.
94 */
95#if !defined(_WIN32) && (defined(__WIN32__) || defined(WIN32) || defined(__MINGW32__))
96 #define _WIN32
97#endif /* _WIN32 */
98
99/* Include because most Windows GLU headers need wchar_t and
100 * the macOS OpenGL header blocks the definition of ptrdiff_t by glext.h.
101 * Include it unconditionally to avoid surprising side-effects.
102 */
103#include <stddef.h>
104
105/* Include because it is needed by Vulkan and related functions.
106 * Include it unconditionally to avoid surprising side-effects.
107 */
108#include <stdint.h>
109
110#if defined(GLFW_INCLUDE_VULKAN)
111 #include <vulkan/vulkan.h>
112#endif /* Vulkan header */
113
114/* The Vulkan header may have indirectly included windows.h (because of
115 * VK_USE_PLATFORM_WIN32_KHR) so we offer our replacement symbols after it.
116 */
117
118/* It is customary to use APIENTRY for OpenGL function pointer declarations on
119 * all platforms. Additionally, the Windows OpenGL header needs APIENTRY.
120 */
121#if !defined(APIENTRY)
122 #if defined(_WIN32)
123 #define APIENTRY __stdcall
124 #else
125 #define APIENTRY
126 #endif
127 #define GLFW_APIENTRY_DEFINED
128#endif /* APIENTRY */
129
130/* Some Windows OpenGL headers need this.
131 */
132#if !defined(WINGDIAPI) && defined(_WIN32)
133 #define WINGDIAPI __declspec(dllimport)
134 #define GLFW_WINGDIAPI_DEFINED
135#endif /* WINGDIAPI */
136
137/* Some Windows GLU headers need this.
138 */
139#if !defined(CALLBACK) && defined(_WIN32)
140 #define CALLBACK __stdcall
141 #define GLFW_CALLBACK_DEFINED
142#endif /* CALLBACK */
143
144/* Include the chosen OpenGL or OpenGL ES headers.
145 */
146#if defined(GLFW_INCLUDE_ES1)
147
148 #include <GLES/gl.h>
149 #if defined(GLFW_INCLUDE_GLEXT)
150 #include <GLES/glext.h>
151 #endif
152
153#elif defined(GLFW_INCLUDE_ES2)
154
155 #include <GLES2/gl2.h>
156 #if defined(GLFW_INCLUDE_GLEXT)
157 #include <GLES2/gl2ext.h>
158 #endif
159
160#elif defined(GLFW_INCLUDE_ES3)
161
162 #include <GLES3/gl3.h>
163 #if defined(GLFW_INCLUDE_GLEXT)
164 #include <GLES2/gl2ext.h>
165 #endif
166
167#elif defined(GLFW_INCLUDE_ES31)
168
169 #include <GLES3/gl31.h>
170 #if defined(GLFW_INCLUDE_GLEXT)
171 #include <GLES2/gl2ext.h>
172 #endif
173
174#elif defined(GLFW_INCLUDE_ES32)
175
176 #include <GLES3/gl32.h>
177 #if defined(GLFW_INCLUDE_GLEXT)
178 #include <GLES2/gl2ext.h>
179 #endif
180
181#elif defined(GLFW_INCLUDE_GLCOREARB)
182
183 #if defined(__APPLE__)
184
185 #include <OpenGL/gl3.h>
186 #if defined(GLFW_INCLUDE_GLEXT)
187 #include <OpenGL/gl3ext.h>
188 #endif /*GLFW_INCLUDE_GLEXT*/
189
190 #else /*__APPLE__*/
191
192 #include <GL/glcorearb.h>
193 #if defined(GLFW_INCLUDE_GLEXT)
194 #include <GL/glext.h>
195 #endif
196
197 #endif /*__APPLE__*/
198
199#elif defined(GLFW_INCLUDE_GLU)
200
201 #if defined(__APPLE__)
202
203 #if defined(GLFW_INCLUDE_GLU)
204 #include <OpenGL/glu.h>
205 #endif
206
207 #else /*__APPLE__*/
208
209 #if defined(GLFW_INCLUDE_GLU)
210 #include <GL/glu.h>
211 #endif
212
213 #endif /*__APPLE__*/
214
215#elif !defined(GLFW_INCLUDE_NONE) && \
216 !defined(__gl_h_) && \
217 !defined(__gles1_gl_h_) && \
218 !defined(__gles2_gl2_h_) && \
219 !defined(__gles2_gl3_h_) && \
220 !defined(__gles2_gl31_h_) && \
221 !defined(__gles2_gl32_h_) && \
222 !defined(__gl_glcorearb_h_) && \
223 !defined(__gl2_h_) /*legacy*/ && \
224 !defined(__gl3_h_) /*legacy*/ && \
225 !defined(__gl31_h_) /*legacy*/ && \
226 !defined(__gl32_h_) /*legacy*/ && \
227 !defined(__glcorearb_h_) /*legacy*/ && \
228 !defined(__GL_H__) /*non-standard*/ && \
229 !defined(__gltypes_h_) /*non-standard*/ && \
230 !defined(__glee_h_) /*non-standard*/
231
232 #if defined(__APPLE__)
233
234 #if !defined(GLFW_INCLUDE_GLEXT)
235 #define GL_GLEXT_LEGACY
236 #endif
237 #include <OpenGL/gl.h>
238
239 #else /*__APPLE__*/
240
241 #include <GL/gl.h>
242 #if defined(GLFW_INCLUDE_GLEXT)
243 #include <GL/glext.h>
244 #endif
245
246 #endif /*__APPLE__*/
247
248#endif /* OpenGL and OpenGL ES headers */
249
250#if defined(GLFW_DLL) && defined(_GLFW_BUILD_DLL)
251 /* GLFW_DLL must be defined by applications that are linking against the DLL
252 * version of the GLFW library. _GLFW_BUILD_DLL is defined by the GLFW
253 * configuration header when compiling the DLL version of the library.
254 */
255 #error "You must not have both GLFW_DLL and _GLFW_BUILD_DLL defined"
256#endif
257
258/* GLFWAPI is used to declare public API functions for export
259 * from the DLL / shared library / dynamic library.
260 */
261#if defined(_WIN32) && defined(_GLFW_BUILD_DLL)
262 /* We are building GLFW as a Win32 DLL */
263 #define GLFWAPI __declspec(dllexport)
264#elif defined(_WIN32) && defined(GLFW_DLL)
265 /* We are calling GLFW as a Win32 DLL */
266 #define GLFWAPI __declspec(dllimport)
267#elif defined(__GNUC__) && defined(_GLFW_BUILD_DLL)
268 /* We are building GLFW as a shared / dynamic library */
269 #define GLFWAPI __attribute__((visibility("default")))
270#else
271 /* We are building or calling GLFW as a static library */
272 #define GLFWAPI
273#endif
274
275
276/*************************************************************************
277 * GLFW API tokens
278 *************************************************************************/
279
280/*! @name GLFW version macros
281 * @{ */
282/*! @brief The major version number of the GLFW header.
283 *
284 * The major version number of the GLFW header. This is incremented when the
285 * API is changed in non-compatible ways.
286 * @ingroup init
287 */
288#define GLFW_VERSION_MAJOR 3
289/*! @brief The minor version number of the GLFW header.
290 *
291 * The minor version number of the GLFW header. This is incremented when
292 * features are added to the API but it remains backward-compatible.
293 * @ingroup init
294 */
295#define GLFW_VERSION_MINOR 3
296/*! @brief The revision number of the GLFW header.
297 *
298 * The revision number of the GLFW header. This is incremented when a bug fix
299 * release is made that does not contain any API changes.
300 * @ingroup init
301 */
302#define GLFW_VERSION_REVISION 5
303/*! @} */
304
305/*! @brief One.
306 *
307 * This is only semantic sugar for the number 1. You can instead use `1` or
308 * `true` or `_True` or `GL_TRUE` or `VK_TRUE` or anything else that is equal
309 * to one.
310 *
311 * @ingroup init
312 */
313#define GLFW_TRUE 1
314/*! @brief Zero.
315 *
316 * This is only semantic sugar for the number 0. You can instead use `0` or
317 * `false` or `_False` or `GL_FALSE` or `VK_FALSE` or anything else that is
318 * equal to zero.
319 *
320 * @ingroup init
321 */
322#define GLFW_FALSE 0
323
324/*! @name Key and button actions
325 * @{ */
326/*! @brief The key or mouse button was released.
327 *
328 * The key or mouse button was released.
329 *
330 * @ingroup input
331 */
332#define GLFW_RELEASE 0
333/*! @brief The key or mouse button was pressed.
334 *
335 * The key or mouse button was pressed.
336 *
337 * @ingroup input
338 */
339#define GLFW_PRESS 1
340/*! @brief The key was held down until it repeated.
341 *
342 * The key was held down until it repeated.
343 *
344 * @ingroup input
345 */
346#define GLFW_REPEAT 2
347/*! @} */
348
349/*! @defgroup hat_state Joystick hat states
350 * @brief Joystick hat states.
351 *
352 * See [joystick hat input](@ref joystick_hat) for how these are used.
353 *
354 * @ingroup input
355 * @{ */
356#define GLFW_HAT_CENTERED 0
357#define GLFW_HAT_UP 1
358#define GLFW_HAT_RIGHT 2
359#define GLFW_HAT_DOWN 4
360#define GLFW_HAT_LEFT 8
361#define GLFW_HAT_RIGHT_UP (GLFW_HAT_RIGHT | GLFW_HAT_UP)
362#define GLFW_HAT_RIGHT_DOWN (GLFW_HAT_RIGHT | GLFW_HAT_DOWN)
363#define GLFW_HAT_LEFT_UP (GLFW_HAT_LEFT | GLFW_HAT_UP)
364#define GLFW_HAT_LEFT_DOWN (GLFW_HAT_LEFT | GLFW_HAT_DOWN)
365/*! @} */
366
367/*! @defgroup keys Keyboard keys
368 * @brief Keyboard key IDs.
369 *
370 * See [key input](@ref input_key) for how these are used.
371 *
372 * These key codes are inspired by the _USB HID Usage Tables v1.12_ (p. 53-60),
373 * but re-arranged to map to 7-bit ASCII for printable keys (function keys are
374 * put in the 256+ range).
375 *
376 * The naming of the key codes follow these rules:
377 * - The US keyboard layout is used
378 * - Names of printable alpha-numeric characters are used (e.g. "A", "R",
379 * "3", etc.)
380 * - For non-alphanumeric characters, Unicode:ish names are used (e.g.
381 * "COMMA", "LEFT_SQUARE_BRACKET", etc.). Note that some names do not
382 * correspond to the Unicode standard (usually for brevity)
383 * - Keys that lack a clear US mapping are named "WORLD_x"
384 * - For non-printable keys, custom names are used (e.g. "F4",
385 * "BACKSPACE", etc.)
386 *
387 * @ingroup input
388 * @{
389 */
390
391/* The unknown key */
392#define GLFW_KEY_UNKNOWN -1
393
394/* Printable keys */
395#define GLFW_KEY_SPACE 32
396#define GLFW_KEY_APOSTROPHE 39 /* ' */
397#define GLFW_KEY_COMMA 44 /* , */
398#define GLFW_KEY_MINUS 45 /* - */
399#define GLFW_KEY_PERIOD 46 /* . */
400#define GLFW_KEY_SLASH 47 /* / */
401#define GLFW_KEY_0 48
402#define GLFW_KEY_1 49
403#define GLFW_KEY_2 50
404#define GLFW_KEY_3 51
405#define GLFW_KEY_4 52
406#define GLFW_KEY_5 53
407#define GLFW_KEY_6 54
408#define GLFW_KEY_7 55
409#define GLFW_KEY_8 56
410#define GLFW_KEY_9 57
411#define GLFW_KEY_SEMICOLON 59 /* ; */
412#define GLFW_KEY_EQUAL 61 /* = */
413#define GLFW_KEY_A 65
414#define GLFW_KEY_B 66
415#define GLFW_KEY_C 67
416#define GLFW_KEY_D 68
417#define GLFW_KEY_E 69
418#define GLFW_KEY_F 70
419#define GLFW_KEY_G 71
420#define GLFW_KEY_H 72
421#define GLFW_KEY_I 73
422#define GLFW_KEY_J 74
423#define GLFW_KEY_K 75
424#define GLFW_KEY_L 76
425#define GLFW_KEY_M 77
426#define GLFW_KEY_N 78
427#define GLFW_KEY_O 79
428#define GLFW_KEY_P 80
429#define GLFW_KEY_Q 81
430#define GLFW_KEY_R 82
431#define GLFW_KEY_S 83
432#define GLFW_KEY_T 84
433#define GLFW_KEY_U 85
434#define GLFW_KEY_V 86
435#define GLFW_KEY_W 87
436#define GLFW_KEY_X 88
437#define GLFW_KEY_Y 89
438#define GLFW_KEY_Z 90
439#define GLFW_KEY_LEFT_BRACKET 91 /* [ */
440#define GLFW_KEY_BACKSLASH 92 /* \ */
441#define GLFW_KEY_RIGHT_BRACKET 93 /* ] */
442#define GLFW_KEY_GRAVE_ACCENT 96 /* ` */
443#define GLFW_KEY_WORLD_1 161 /* non-US #1 */
444#define GLFW_KEY_WORLD_2 162 /* non-US #2 */
445
446/* Function keys */
447#define GLFW_KEY_ESCAPE 256
448#define GLFW_KEY_ENTER 257
449#define GLFW_KEY_TAB 258
450#define GLFW_KEY_BACKSPACE 259
451#define GLFW_KEY_INSERT 260
452#define GLFW_KEY_DELETE 261
453#define GLFW_KEY_RIGHT 262
454#define GLFW_KEY_LEFT 263
455#define GLFW_KEY_DOWN 264
456#define GLFW_KEY_UP 265
457#define GLFW_KEY_PAGE_UP 266
458#define GLFW_KEY_PAGE_DOWN 267
459#define GLFW_KEY_HOME 268
460#define GLFW_KEY_END 269
461#define GLFW_KEY_CAPS_LOCK 280
462#define GLFW_KEY_SCROLL_LOCK 281
463#define GLFW_KEY_NUM_LOCK 282
464#define GLFW_KEY_PRINT_SCREEN 283
465#define GLFW_KEY_PAUSE 284
466#define GLFW_KEY_F1 290
467#define GLFW_KEY_F2 291
468#define GLFW_KEY_F3 292
469#define GLFW_KEY_F4 293
470#define GLFW_KEY_F5 294
471#define GLFW_KEY_F6 295
472#define GLFW_KEY_F7 296
473#define GLFW_KEY_F8 297
474#define GLFW_KEY_F9 298
475#define GLFW_KEY_F10 299
476#define GLFW_KEY_F11 300
477#define GLFW_KEY_F12 301
478#define GLFW_KEY_F13 302
479#define GLFW_KEY_F14 303
480#define GLFW_KEY_F15 304
481#define GLFW_KEY_F16 305
482#define GLFW_KEY_F17 306
483#define GLFW_KEY_F18 307
484#define GLFW_KEY_F19 308
485#define GLFW_KEY_F20 309
486#define GLFW_KEY_F21 310
487#define GLFW_KEY_F22 311
488#define GLFW_KEY_F23 312
489#define GLFW_KEY_F24 313
490#define GLFW_KEY_F25 314
491#define GLFW_KEY_KP_0 320
492#define GLFW_KEY_KP_1 321
493#define GLFW_KEY_KP_2 322
494#define GLFW_KEY_KP_3 323
495#define GLFW_KEY_KP_4 324
496#define GLFW_KEY_KP_5 325
497#define GLFW_KEY_KP_6 326
498#define GLFW_KEY_KP_7 327
499#define GLFW_KEY_KP_8 328
500#define GLFW_KEY_KP_9 329
501#define GLFW_KEY_KP_DECIMAL 330
502#define GLFW_KEY_KP_DIVIDE 331
503#define GLFW_KEY_KP_MULTIPLY 332
504#define GLFW_KEY_KP_SUBTRACT 333
505#define GLFW_KEY_KP_ADD 334
506#define GLFW_KEY_KP_ENTER 335
507#define GLFW_KEY_KP_EQUAL 336
508#define GLFW_KEY_LEFT_SHIFT 340
509#define GLFW_KEY_LEFT_CONTROL 341
510#define GLFW_KEY_LEFT_ALT 342
511#define GLFW_KEY_LEFT_SUPER 343
512#define GLFW_KEY_RIGHT_SHIFT 344
513#define GLFW_KEY_RIGHT_CONTROL 345
514#define GLFW_KEY_RIGHT_ALT 346
515#define GLFW_KEY_RIGHT_SUPER 347
516#define GLFW_KEY_MENU 348
517
518#define GLFW_KEY_LAST GLFW_KEY_MENU
519
520/*! @} */
521
522/*! @defgroup mods Modifier key flags
523 * @brief Modifier key flags.
524 *
525 * See [key input](@ref input_key) for how these are used.
526 *
527 * @ingroup input
528 * @{ */
529
530/*! @brief If this bit is set one or more Shift keys were held down.
531 *
532 * If this bit is set one or more Shift keys were held down.
533 */
534#define GLFW_MOD_SHIFT 0x0001
535/*! @brief If this bit is set one or more Control keys were held down.
536 *
537 * If this bit is set one or more Control keys were held down.
538 */
539#define GLFW_MOD_CONTROL 0x0002
540/*! @brief If this bit is set one or more Alt keys were held down.
541 *
542 * If this bit is set one or more Alt keys were held down.
543 */
544#define GLFW_MOD_ALT 0x0004
545/*! @brief If this bit is set one or more Super keys were held down.
546 *
547 * If this bit is set one or more Super keys were held down.
548 */
549#define GLFW_MOD_SUPER 0x0008
550/*! @brief If this bit is set the Caps Lock key is enabled.
551 *
552 * If this bit is set the Caps Lock key is enabled and the @ref
553 * GLFW_LOCK_KEY_MODS input mode is set.
554 */
555#define GLFW_MOD_CAPS_LOCK 0x0010
556/*! @brief If this bit is set the Num Lock key is enabled.
557 *
558 * If this bit is set the Num Lock key is enabled and the @ref
559 * GLFW_LOCK_KEY_MODS input mode is set.
560 */
561#define GLFW_MOD_NUM_LOCK 0x0020
562
563/*! @} */
564
565/*! @defgroup buttons Mouse buttons
566 * @brief Mouse button IDs.
567 *
568 * See [mouse button input](@ref input_mouse_button) for how these are used.
569 *
570 * @ingroup input
571 * @{ */
572#define GLFW_MOUSE_BUTTON_1 0
573#define GLFW_MOUSE_BUTTON_2 1
574#define GLFW_MOUSE_BUTTON_3 2
575#define GLFW_MOUSE_BUTTON_4 3
576#define GLFW_MOUSE_BUTTON_5 4
577#define GLFW_MOUSE_BUTTON_6 5
578#define GLFW_MOUSE_BUTTON_7 6
579#define GLFW_MOUSE_BUTTON_8 7
580#define GLFW_MOUSE_BUTTON_LAST GLFW_MOUSE_BUTTON_8
581#define GLFW_MOUSE_BUTTON_LEFT GLFW_MOUSE_BUTTON_1
582#define GLFW_MOUSE_BUTTON_RIGHT GLFW_MOUSE_BUTTON_2
583#define GLFW_MOUSE_BUTTON_MIDDLE GLFW_MOUSE_BUTTON_3
584/*! @} */
585
586/*! @defgroup joysticks Joysticks
587 * @brief Joystick IDs.
588 *
589 * See [joystick input](@ref joystick) for how these are used.
590 *
591 * @ingroup input
592 * @{ */
593#define GLFW_JOYSTICK_1 0
594#define GLFW_JOYSTICK_2 1
595#define GLFW_JOYSTICK_3 2
596#define GLFW_JOYSTICK_4 3
597#define GLFW_JOYSTICK_5 4
598#define GLFW_JOYSTICK_6 5
599#define GLFW_JOYSTICK_7 6
600#define GLFW_JOYSTICK_8 7
601#define GLFW_JOYSTICK_9 8
602#define GLFW_JOYSTICK_10 9
603#define GLFW_JOYSTICK_11 10
604#define GLFW_JOYSTICK_12 11
605#define GLFW_JOYSTICK_13 12
606#define GLFW_JOYSTICK_14 13
607#define GLFW_JOYSTICK_15 14
608#define GLFW_JOYSTICK_16 15
609#define GLFW_JOYSTICK_LAST GLFW_JOYSTICK_16
610/*! @} */
611
612/*! @defgroup gamepad_buttons Gamepad buttons
613 * @brief Gamepad buttons.
614 *
615 * See @ref gamepad for how these are used.
616 *
617 * @ingroup input
618 * @{ */
619#define GLFW_GAMEPAD_BUTTON_A 0
620#define GLFW_GAMEPAD_BUTTON_B 1
621#define GLFW_GAMEPAD_BUTTON_X 2
622#define GLFW_GAMEPAD_BUTTON_Y 3
623#define GLFW_GAMEPAD_BUTTON_LEFT_BUMPER 4
624#define GLFW_GAMEPAD_BUTTON_RIGHT_BUMPER 5
625#define GLFW_GAMEPAD_BUTTON_BACK 6
626#define GLFW_GAMEPAD_BUTTON_START 7
627#define GLFW_GAMEPAD_BUTTON_GUIDE 8
628#define GLFW_GAMEPAD_BUTTON_LEFT_THUMB 9
629#define GLFW_GAMEPAD_BUTTON_RIGHT_THUMB 10
630#define GLFW_GAMEPAD_BUTTON_DPAD_UP 11
631#define GLFW_GAMEPAD_BUTTON_DPAD_RIGHT 12
632#define GLFW_GAMEPAD_BUTTON_DPAD_DOWN 13
633#define GLFW_GAMEPAD_BUTTON_DPAD_LEFT 14
634#define GLFW_GAMEPAD_BUTTON_LAST GLFW_GAMEPAD_BUTTON_DPAD_LEFT
635
636#define GLFW_GAMEPAD_BUTTON_CROSS GLFW_GAMEPAD_BUTTON_A
637#define GLFW_GAMEPAD_BUTTON_CIRCLE GLFW_GAMEPAD_BUTTON_B
638#define GLFW_GAMEPAD_BUTTON_SQUARE GLFW_GAMEPAD_BUTTON_X
639#define GLFW_GAMEPAD_BUTTON_TRIANGLE GLFW_GAMEPAD_BUTTON_Y
640/*! @} */
641
642/*! @defgroup gamepad_axes Gamepad axes
643 * @brief Gamepad axes.
644 *
645 * See @ref gamepad for how these are used.
646 *
647 * @ingroup input
648 * @{ */
649#define GLFW_GAMEPAD_AXIS_LEFT_X 0
650#define GLFW_GAMEPAD_AXIS_LEFT_Y 1
651#define GLFW_GAMEPAD_AXIS_RIGHT_X 2
652#define GLFW_GAMEPAD_AXIS_RIGHT_Y 3
653#define GLFW_GAMEPAD_AXIS_LEFT_TRIGGER 4
654#define GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER 5
655#define GLFW_GAMEPAD_AXIS_LAST GLFW_GAMEPAD_AXIS_RIGHT_TRIGGER
656/*! @} */
657
658/*! @defgroup errors Error codes
659 * @brief Error codes.
660 *
661 * See [error handling](@ref error_handling) for how these are used.
662 *
663 * @ingroup init
664 * @{ */
665/*! @brief No error has occurred.
666 *
667 * No error has occurred.
668 *
669 * @analysis Yay.
670 */
671#define GLFW_NO_ERROR 0
672/*! @brief GLFW has not been initialized.
673 *
674 * This occurs if a GLFW function was called that must not be called unless the
675 * library is [initialized](@ref intro_init).
676 *
677 * @analysis Application programmer error. Initialize GLFW before calling any
678 * function that requires initialization.
679 */
680#define GLFW_NOT_INITIALIZED 0x00010001
681/*! @brief No context is current for this thread.
682 *
683 * This occurs if a GLFW function was called that needs and operates on the
684 * current OpenGL or OpenGL ES context but no context is current on the calling
685 * thread. One such function is @ref glfwSwapInterval.
686 *
687 * @analysis Application programmer error. Ensure a context is current before
688 * calling functions that require a current context.
689 */
690#define GLFW_NO_CURRENT_CONTEXT 0x00010002
691/*! @brief One of the arguments to the function was an invalid enum value.
692 *
693 * One of the arguments to the function was an invalid enum value, for example
694 * requesting @ref GLFW_RED_BITS with @ref glfwGetWindowAttrib.
695 *
696 * @analysis Application programmer error. Fix the offending call.
697 */
698#define GLFW_INVALID_ENUM 0x00010003
699/*! @brief One of the arguments to the function was an invalid value.
700 *
701 * One of the arguments to the function was an invalid value, for example
702 * requesting a non-existent OpenGL or OpenGL ES version like 2.7.
703 *
704 * Requesting a valid but unavailable OpenGL or OpenGL ES version will instead
705 * result in a @ref GLFW_VERSION_UNAVAILABLE error.
706 *
707 * @analysis Application programmer error. Fix the offending call.
708 */
709#define GLFW_INVALID_VALUE 0x00010004
710/*! @brief A memory allocation failed.
711 *
712 * A memory allocation failed.
713 *
714 * @analysis A bug in GLFW or the underlying operating system. Report the bug
715 * to our [issue tracker](https://github.com/glfw/glfw/issues).
716 */
717#define GLFW_OUT_OF_MEMORY 0x00010005
718/*! @brief GLFW could not find support for the requested API on the system.
719 *
720 * GLFW could not find support for the requested API on the system.
721 *
722 * @analysis The installed graphics driver does not support the requested
723 * API, or does not support it via the chosen context creation backend.
724 * Below are a few examples.
725 *
726 * @par
727 * Some pre-installed Windows graphics drivers do not support OpenGL. AMD only
728 * supports OpenGL ES via EGL, while Nvidia and Intel only support it via
729 * a WGL or GLX extension. macOS does not provide OpenGL ES at all. The Mesa
730 * EGL, OpenGL and OpenGL ES libraries do not interface with the Nvidia binary
731 * driver. Older graphics drivers do not support Vulkan.
732 */
733#define GLFW_API_UNAVAILABLE 0x00010006
734/*! @brief The requested OpenGL or OpenGL ES version is not available.
735 *
736 * The requested OpenGL or OpenGL ES version (including any requested context
737 * or framebuffer hints) is not available on this machine.
738 *
739 * @analysis The machine does not support your requirements. If your
740 * application is sufficiently flexible, downgrade your requirements and try
741 * again. Otherwise, inform the user that their machine does not match your
742 * requirements.
743 *
744 * @par
745 * Future invalid OpenGL and OpenGL ES versions, for example OpenGL 4.8 if 5.0
746 * comes out before the 4.x series gets that far, also fail with this error and
747 * not @ref GLFW_INVALID_VALUE, because GLFW cannot know what future versions
748 * will exist.
749 */
750#define GLFW_VERSION_UNAVAILABLE 0x00010007
751/*! @brief A platform-specific error occurred that does not match any of the
752 * more specific categories.
753 *
754 * A platform-specific error occurred that does not match any of the more
755 * specific categories.
756 *
757 * @analysis A bug or configuration error in GLFW, the underlying operating
758 * system or its drivers, or a lack of required resources. Report the issue to
759 * our [issue tracker](https://github.com/glfw/glfw/issues).
760 */
761#define GLFW_PLATFORM_ERROR 0x00010008
762/*! @brief The requested format is not supported or available.
763 *
764 * If emitted during window creation, the requested pixel format is not
765 * supported.
766 *
767 * If emitted when querying the clipboard, the contents of the clipboard could
768 * not be converted to the requested format.
769 *
770 * @analysis If emitted during window creation, one or more
771 * [hard constraints](@ref window_hints_hard) did not match any of the
772 * available pixel formats. If your application is sufficiently flexible,
773 * downgrade your requirements and try again. Otherwise, inform the user that
774 * their machine does not match your requirements.
775 *
776 * @par
777 * If emitted when querying the clipboard, ignore the error or report it to
778 * the user, as appropriate.
779 */
780#define GLFW_FORMAT_UNAVAILABLE 0x00010009
781/*! @brief The specified window does not have an OpenGL or OpenGL ES context.
782 *
783 * A window that does not have an OpenGL or OpenGL ES context was passed to
784 * a function that requires it to have one.
785 *
786 * @analysis Application programmer error. Fix the offending call.
787 */
788#define GLFW_NO_WINDOW_CONTEXT 0x0001000A
789/*! @} */
790
791/*! @addtogroup window
792 * @{ */
793/*! @brief Input focus window hint and attribute
794 *
795 * Input focus [window hint](@ref GLFW_FOCUSED_hint) or
796 * [window attribute](@ref GLFW_FOCUSED_attrib).
797 */
798#define GLFW_FOCUSED 0x00020001
799/*! @brief Window iconification window attribute
800 *
801 * Window iconification [window attribute](@ref GLFW_ICONIFIED_attrib).
802 */
803#define GLFW_ICONIFIED 0x00020002
804/*! @brief Window resize-ability window hint and attribute
805 *
806 * Window resize-ability [window hint](@ref GLFW_RESIZABLE_hint) and
807 * [window attribute](@ref GLFW_RESIZABLE_attrib).
808 */
809#define GLFW_RESIZABLE 0x00020003
810/*! @brief Window visibility window hint and attribute
811 *
812 * Window visibility [window hint](@ref GLFW_VISIBLE_hint) and
813 * [window attribute](@ref GLFW_VISIBLE_attrib).
814 */
815#define GLFW_VISIBLE 0x00020004
816/*! @brief Window decoration window hint and attribute
817 *
818 * Window decoration [window hint](@ref GLFW_DECORATED_hint) and
819 * [window attribute](@ref GLFW_DECORATED_attrib).
820 */
821#define GLFW_DECORATED 0x00020005
822/*! @brief Window auto-iconification window hint and attribute
823 *
824 * Window auto-iconification [window hint](@ref GLFW_AUTO_ICONIFY_hint) and
825 * [window attribute](@ref GLFW_AUTO_ICONIFY_attrib).
826 */
827#define GLFW_AUTO_ICONIFY 0x00020006
828/*! @brief Window decoration window hint and attribute
829 *
830 * Window decoration [window hint](@ref GLFW_FLOATING_hint) and
831 * [window attribute](@ref GLFW_FLOATING_attrib).
832 */
833#define GLFW_FLOATING 0x00020007
834/*! @brief Window maximization window hint and attribute
835 *
836 * Window maximization [window hint](@ref GLFW_MAXIMIZED_hint) and
837 * [window attribute](@ref GLFW_MAXIMIZED_attrib).
838 */
839#define GLFW_MAXIMIZED 0x00020008
840/*! @brief Cursor centering window hint
841 *
842 * Cursor centering [window hint](@ref GLFW_CENTER_CURSOR_hint).
843 */
844#define GLFW_CENTER_CURSOR 0x00020009
845/*! @brief Window framebuffer transparency hint and attribute
846 *
847 * Window framebuffer transparency
848 * [window hint](@ref GLFW_TRANSPARENT_FRAMEBUFFER_hint) and
849 * [window attribute](@ref GLFW_TRANSPARENT_FRAMEBUFFER_attrib).
850 */
851#define GLFW_TRANSPARENT_FRAMEBUFFER 0x0002000A
852/*! @brief Mouse cursor hover window attribute.
853 *
854 * Mouse cursor hover [window attribute](@ref GLFW_HOVERED_attrib).
855 */
856#define GLFW_HOVERED 0x0002000B
857/*! @brief Input focus on calling show window hint and attribute
858 *
859 * Input focus [window hint](@ref GLFW_FOCUS_ON_SHOW_hint) or
860 * [window attribute](@ref GLFW_FOCUS_ON_SHOW_attrib).
861 */
862#define GLFW_FOCUS_ON_SHOW 0x0002000C
863
864/*! @brief Framebuffer bit depth hint.
865 *
866 * Framebuffer bit depth [hint](@ref GLFW_RED_BITS).
867 */
868#define GLFW_RED_BITS 0x00021001
869/*! @brief Framebuffer bit depth hint.
870 *
871 * Framebuffer bit depth [hint](@ref GLFW_GREEN_BITS).
872 */
873#define GLFW_GREEN_BITS 0x00021002
874/*! @brief Framebuffer bit depth hint.
875 *
876 * Framebuffer bit depth [hint](@ref GLFW_BLUE_BITS).
877 */
878#define GLFW_BLUE_BITS 0x00021003
879/*! @brief Framebuffer bit depth hint.
880 *
881 * Framebuffer bit depth [hint](@ref GLFW_ALPHA_BITS).
882 */
883#define GLFW_ALPHA_BITS 0x00021004
884/*! @brief Framebuffer bit depth hint.
885 *
886 * Framebuffer bit depth [hint](@ref GLFW_DEPTH_BITS).
887 */
888#define GLFW_DEPTH_BITS 0x00021005
889/*! @brief Framebuffer bit depth hint.
890 *
891 * Framebuffer bit depth [hint](@ref GLFW_STENCIL_BITS).
892 */
893#define GLFW_STENCIL_BITS 0x00021006
894/*! @brief Framebuffer bit depth hint.
895 *
896 * Framebuffer bit depth [hint](@ref GLFW_ACCUM_RED_BITS).
897 */
898#define GLFW_ACCUM_RED_BITS 0x00021007
899/*! @brief Framebuffer bit depth hint.
900 *
901 * Framebuffer bit depth [hint](@ref GLFW_ACCUM_GREEN_BITS).
902 */
903#define GLFW_ACCUM_GREEN_BITS 0x00021008
904/*! @brief Framebuffer bit depth hint.
905 *
906 * Framebuffer bit depth [hint](@ref GLFW_ACCUM_BLUE_BITS).
907 */
908#define GLFW_ACCUM_BLUE_BITS 0x00021009
909/*! @brief Framebuffer bit depth hint.
910 *
911 * Framebuffer bit depth [hint](@ref GLFW_ACCUM_ALPHA_BITS).
912 */
913#define GLFW_ACCUM_ALPHA_BITS 0x0002100A
914/*! @brief Framebuffer auxiliary buffer hint.
915 *
916 * Framebuffer auxiliary buffer [hint](@ref GLFW_AUX_BUFFERS).
917 */
918#define GLFW_AUX_BUFFERS 0x0002100B
919/*! @brief OpenGL stereoscopic rendering hint.
920 *
921 * OpenGL stereoscopic rendering [hint](@ref GLFW_STEREO).
922 */
923#define GLFW_STEREO 0x0002100C
924/*! @brief Framebuffer MSAA samples hint.
925 *
926 * Framebuffer MSAA samples [hint](@ref GLFW_SAMPLES).
927 */
928#define GLFW_SAMPLES 0x0002100D
929/*! @brief Framebuffer sRGB hint.
930 *
931 * Framebuffer sRGB [hint](@ref GLFW_SRGB_CAPABLE).
932 */
933#define GLFW_SRGB_CAPABLE 0x0002100E
934/*! @brief Monitor refresh rate hint.
935 *
936 * Monitor refresh rate [hint](@ref GLFW_REFRESH_RATE).
937 */
938#define GLFW_REFRESH_RATE 0x0002100F
939/*! @brief Framebuffer double buffering hint.
940 *
941 * Framebuffer double buffering [hint](@ref GLFW_DOUBLEBUFFER).
942 */
943#define GLFW_DOUBLEBUFFER 0x00021010
944
945/*! @brief Context client API hint and attribute.
946 *
947 * Context client API [hint](@ref GLFW_CLIENT_API_hint) and
948 * [attribute](@ref GLFW_CLIENT_API_attrib).
949 */
950#define GLFW_CLIENT_API 0x00022001
951/*! @brief Context client API major version hint and attribute.
952 *
953 * Context client API major version [hint](@ref GLFW_CONTEXT_VERSION_MAJOR_hint)
954 * and [attribute](@ref GLFW_CONTEXT_VERSION_MAJOR_attrib).
955 */
956#define GLFW_CONTEXT_VERSION_MAJOR 0x00022002
957/*! @brief Context client API minor version hint and attribute.
958 *
959 * Context client API minor version [hint](@ref GLFW_CONTEXT_VERSION_MINOR_hint)
960 * and [attribute](@ref GLFW_CONTEXT_VERSION_MINOR_attrib).
961 */
962#define GLFW_CONTEXT_VERSION_MINOR 0x00022003
963/*! @brief Context client API revision number hint and attribute.
964 *
965 * Context client API revision number
966 * [attribute](@ref GLFW_CONTEXT_REVISION_attrib).
967 */
968#define GLFW_CONTEXT_REVISION 0x00022004
969/*! @brief Context robustness hint and attribute.
970 *
971 * Context client API revision number [hint](@ref GLFW_CONTEXT_ROBUSTNESS_hint)
972 * and [attribute](@ref GLFW_CONTEXT_ROBUSTNESS_attrib).
973 */
974#define GLFW_CONTEXT_ROBUSTNESS 0x00022005
975/*! @brief OpenGL forward-compatibility hint and attribute.
976 *
977 * OpenGL forward-compatibility [hint](@ref GLFW_OPENGL_FORWARD_COMPAT_hint)
978 * and [attribute](@ref GLFW_OPENGL_FORWARD_COMPAT_attrib).
979 */
980#define GLFW_OPENGL_FORWARD_COMPAT 0x00022006
981/*! @brief Debug mode context hint and attribute.
982 *
983 * Debug mode context [hint](@ref GLFW_OPENGL_DEBUG_CONTEXT_hint) and
984 * [attribute](@ref GLFW_OPENGL_DEBUG_CONTEXT_attrib).
985 */
986#define GLFW_OPENGL_DEBUG_CONTEXT 0x00022007
987/*! @brief OpenGL profile hint and attribute.
988 *
989 * OpenGL profile [hint](@ref GLFW_OPENGL_PROFILE_hint) and
990 * [attribute](@ref GLFW_OPENGL_PROFILE_attrib).
991 */
992#define GLFW_OPENGL_PROFILE 0x00022008
993/*! @brief Context flush-on-release hint and attribute.
994 *
995 * Context flush-on-release [hint](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint) and
996 * [attribute](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_attrib).
997 */
998#define GLFW_CONTEXT_RELEASE_BEHAVIOR 0x00022009
999/*! @brief Context error suppression hint and attribute.
1000 *
1001 * Context error suppression [hint](@ref GLFW_CONTEXT_NO_ERROR_hint) and
1002 * [attribute](@ref GLFW_CONTEXT_NO_ERROR_attrib).
1003 */
1004#define GLFW_CONTEXT_NO_ERROR 0x0002200A
1005/*! @brief Context creation API hint and attribute.
1006 *
1007 * Context creation API [hint](@ref GLFW_CONTEXT_CREATION_API_hint) and
1008 * [attribute](@ref GLFW_CONTEXT_CREATION_API_attrib).
1009 */
1010#define GLFW_CONTEXT_CREATION_API 0x0002200B
1011/*! @brief Window content area scaling window
1012 * [window hint](@ref GLFW_SCALE_TO_MONITOR).
1013 */
1014#define GLFW_SCALE_TO_MONITOR 0x0002200C
1015/*! @brief macOS specific
1016 * [window hint](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint).
1017 */
1018#define GLFW_COCOA_RETINA_FRAMEBUFFER 0x00023001
1019/*! @brief macOS specific
1020 * [window hint](@ref GLFW_COCOA_FRAME_NAME_hint).
1021 */
1022#define GLFW_COCOA_FRAME_NAME 0x00023002
1023/*! @brief macOS specific
1024 * [window hint](@ref GLFW_COCOA_GRAPHICS_SWITCHING_hint).
1025 */
1026#define GLFW_COCOA_GRAPHICS_SWITCHING 0x00023003
1027/*! @brief X11 specific
1028 * [window hint](@ref GLFW_X11_CLASS_NAME_hint).
1029 */
1030#define GLFW_X11_CLASS_NAME 0x00024001
1031/*! @brief X11 specific
1032 * [window hint](@ref GLFW_X11_CLASS_NAME_hint).
1033 */
1034#define GLFW_X11_INSTANCE_NAME 0x00024002
1035/*! @} */
1036
1037#define GLFW_NO_API 0
1038#define GLFW_OPENGL_API 0x00030001
1039#define GLFW_OPENGL_ES_API 0x00030002
1040
1041#define GLFW_NO_ROBUSTNESS 0
1042#define GLFW_NO_RESET_NOTIFICATION 0x00031001
1043#define GLFW_LOSE_CONTEXT_ON_RESET 0x00031002
1044
1045#define GLFW_OPENGL_ANY_PROFILE 0
1046#define GLFW_OPENGL_CORE_PROFILE 0x00032001
1047#define GLFW_OPENGL_COMPAT_PROFILE 0x00032002
1048
1049#define GLFW_CURSOR 0x00033001
1050#define GLFW_STICKY_KEYS 0x00033002
1051#define GLFW_STICKY_MOUSE_BUTTONS 0x00033003
1052#define GLFW_LOCK_KEY_MODS 0x00033004
1053#define GLFW_RAW_MOUSE_MOTION 0x00033005
1054
1055#define GLFW_CURSOR_NORMAL 0x00034001
1056#define GLFW_CURSOR_HIDDEN 0x00034002
1057#define GLFW_CURSOR_DISABLED 0x00034003
1058
1059#define GLFW_ANY_RELEASE_BEHAVIOR 0
1060#define GLFW_RELEASE_BEHAVIOR_FLUSH 0x00035001
1061#define GLFW_RELEASE_BEHAVIOR_NONE 0x00035002
1062
1063#define GLFW_NATIVE_CONTEXT_API 0x00036001
1064#define GLFW_EGL_CONTEXT_API 0x00036002
1065#define GLFW_OSMESA_CONTEXT_API 0x00036003
1066
1067/*! @defgroup shapes Standard cursor shapes
1068 * @brief Standard system cursor shapes.
1069 *
1070 * See [standard cursor creation](@ref cursor_standard) for how these are used.
1071 *
1072 * @ingroup input
1073 * @{ */
1074
1075/*! @brief The regular arrow cursor shape.
1076 *
1077 * The regular arrow cursor.
1078 */
1079#define GLFW_ARROW_CURSOR 0x00036001
1080/*! @brief The text input I-beam cursor shape.
1081 *
1082 * The text input I-beam cursor shape.
1083 */
1084#define GLFW_IBEAM_CURSOR 0x00036002
1085/*! @brief The crosshair shape.
1086 *
1087 * The crosshair shape.
1088 */
1089#define GLFW_CROSSHAIR_CURSOR 0x00036003
1090/*! @brief The hand shape.
1091 *
1092 * The hand shape.
1093 */
1094#define GLFW_HAND_CURSOR 0x00036004
1095/*! @brief The horizontal resize arrow shape.
1096 *
1097 * The horizontal resize arrow shape.
1098 */
1099#define GLFW_HRESIZE_CURSOR 0x00036005
1100/*! @brief The vertical resize arrow shape.
1101 *
1102 * The vertical resize arrow shape.
1103 */
1104#define GLFW_VRESIZE_CURSOR 0x00036006
1105/*! @} */
1106
1107#define GLFW_CONNECTED 0x00040001
1108#define GLFW_DISCONNECTED 0x00040002
1109
1110/*! @addtogroup init
1111 * @{ */
1112/*! @brief Joystick hat buttons init hint.
1113 *
1114 * Joystick hat buttons [init hint](@ref GLFW_JOYSTICK_HAT_BUTTONS).
1115 */
1116#define GLFW_JOYSTICK_HAT_BUTTONS 0x00050001
1117/*! @brief macOS specific init hint.
1118 *
1119 * macOS specific [init hint](@ref GLFW_COCOA_CHDIR_RESOURCES_hint).
1120 */
1121#define GLFW_COCOA_CHDIR_RESOURCES 0x00051001
1122/*! @brief macOS specific init hint.
1123 *
1124 * macOS specific [init hint](@ref GLFW_COCOA_MENUBAR_hint).
1125 */
1126#define GLFW_COCOA_MENUBAR 0x00051002
1127/*! @} */
1128
1129#define GLFW_DONT_CARE -1
1130
1131
1132/*************************************************************************
1133 * GLFW API types
1134 *************************************************************************/
1135
1136/*! @brief Client API function pointer type.
1137 *
1138 * Generic function pointer used for returning client API function pointers
1139 * without forcing a cast from a regular pointer.
1140 *
1141 * @sa @ref context_glext
1142 * @sa @ref glfwGetProcAddress
1143 *
1144 * @since Added in version 3.0.
1145 *
1146 * @ingroup context
1147 */
1148typedef void (*GLFWglproc)(void);
1149
1150/*! @brief Vulkan API function pointer type.
1151 *
1152 * Generic function pointer used for returning Vulkan API function pointers
1153 * without forcing a cast from a regular pointer.
1154 *
1155 * @sa @ref vulkan_proc
1156 * @sa @ref glfwGetInstanceProcAddress
1157 *
1158 * @since Added in version 3.2.
1159 *
1160 * @ingroup vulkan
1161 */
1162typedef void (*GLFWvkproc)(void);
1163
1164/*! @brief Opaque monitor object.
1165 *
1166 * Opaque monitor object.
1167 *
1168 * @see @ref monitor_object
1169 *
1170 * @since Added in version 3.0.
1171 *
1172 * @ingroup monitor
1173 */
1174typedef struct GLFWmonitor GLFWmonitor;
1175
1176/*! @brief Opaque window object.
1177 *
1178 * Opaque window object.
1179 *
1180 * @see @ref window_object
1181 *
1182 * @since Added in version 3.0.
1183 *
1184 * @ingroup window
1185 */
1186typedef struct GLFWwindow GLFWwindow;
1187
1188/*! @brief Opaque cursor object.
1189 *
1190 * Opaque cursor object.
1191 *
1192 * @see @ref cursor_object
1193 *
1194 * @since Added in version 3.1.
1195 *
1196 * @ingroup input
1197 */
1198typedef struct GLFWcursor GLFWcursor;
1199
1200/*! @brief The function pointer type for error callbacks.
1201 *
1202 * This is the function pointer type for error callbacks. An error callback
1203 * function has the following signature:
1204 * @code
1205 * void callback_name(int error_code, const char* description)
1206 * @endcode
1207 *
1208 * @param[in] error_code An [error code](@ref errors). Future releases may add
1209 * more error codes.
1210 * @param[in] description A UTF-8 encoded string describing the error.
1211 *
1212 * @pointer_lifetime The error description string is valid until the callback
1213 * function returns.
1214 *
1215 * @sa @ref error_handling
1216 * @sa @ref glfwSetErrorCallback
1217 *
1218 * @since Added in version 3.0.
1219 *
1220 * @ingroup init
1221 */
1222typedef void (* GLFWerrorfun)(int error_code, const char* description);
1223
1224/*! @brief The function pointer type for window position callbacks.
1225 *
1226 * This is the function pointer type for window position callbacks. A window
1227 * position callback function has the following signature:
1228 * @code
1229 * void callback_name(GLFWwindow* window, int xpos, int ypos)
1230 * @endcode
1231 *
1232 * @param[in] window The window that was moved.
1233 * @param[in] xpos The new x-coordinate, in screen coordinates, of the
1234 * upper-left corner of the content area of the window.
1235 * @param[in] ypos The new y-coordinate, in screen coordinates, of the
1236 * upper-left corner of the content area of the window.
1237 *
1238 * @sa @ref window_pos
1239 * @sa @ref glfwSetWindowPosCallback
1240 *
1241 * @since Added in version 3.0.
1242 *
1243 * @ingroup window
1244 */
1245typedef void (* GLFWwindowposfun)(GLFWwindow* window, int xpos, int ypos);
1246
1247/*! @brief The function pointer type for window size callbacks.
1248 *
1249 * This is the function pointer type for window size callbacks. A window size
1250 * callback function has the following signature:
1251 * @code
1252 * void callback_name(GLFWwindow* window, int width, int height)
1253 * @endcode
1254 *
1255 * @param[in] window The window that was resized.
1256 * @param[in] width The new width, in screen coordinates, of the window.
1257 * @param[in] height The new height, in screen coordinates, of the window.
1258 *
1259 * @sa @ref window_size
1260 * @sa @ref glfwSetWindowSizeCallback
1261 *
1262 * @since Added in version 1.0.
1263 * @glfw3 Added window handle parameter.
1264 *
1265 * @ingroup window
1266 */
1267typedef void (* GLFWwindowsizefun)(GLFWwindow* window, int width, int height);
1268
1269/*! @brief The function pointer type for window close callbacks.
1270 *
1271 * This is the function pointer type for window close callbacks. A window
1272 * close callback function has the following signature:
1273 * @code
1274 * void function_name(GLFWwindow* window)
1275 * @endcode
1276 *
1277 * @param[in] window The window that the user attempted to close.
1278 *
1279 * @sa @ref window_close
1280 * @sa @ref glfwSetWindowCloseCallback
1281 *
1282 * @since Added in version 2.5.
1283 * @glfw3 Added window handle parameter.
1284 *
1285 * @ingroup window
1286 */
1287typedef void (* GLFWwindowclosefun)(GLFWwindow* window);
1288
1289/*! @brief The function pointer type for window content refresh callbacks.
1290 *
1291 * This is the function pointer type for window content refresh callbacks.
1292 * A window content refresh callback function has the following signature:
1293 * @code
1294 * void function_name(GLFWwindow* window);
1295 * @endcode
1296 *
1297 * @param[in] window The window whose content needs to be refreshed.
1298 *
1299 * @sa @ref window_refresh
1300 * @sa @ref glfwSetWindowRefreshCallback
1301 *
1302 * @since Added in version 2.5.
1303 * @glfw3 Added window handle parameter.
1304 *
1305 * @ingroup window
1306 */
1307typedef void (* GLFWwindowrefreshfun)(GLFWwindow* window);
1308
1309/*! @brief The function pointer type for window focus callbacks.
1310 *
1311 * This is the function pointer type for window focus callbacks. A window
1312 * focus callback function has the following signature:
1313 * @code
1314 * void function_name(GLFWwindow* window, int focused)
1315 * @endcode
1316 *
1317 * @param[in] window The window that gained or lost input focus.
1318 * @param[in] focused `GLFW_TRUE` if the window was given input focus, or
1319 * `GLFW_FALSE` if it lost it.
1320 *
1321 * @sa @ref window_focus
1322 * @sa @ref glfwSetWindowFocusCallback
1323 *
1324 * @since Added in version 3.0.
1325 *
1326 * @ingroup window
1327 */
1328typedef void (* GLFWwindowfocusfun)(GLFWwindow* window, int focused);
1329
1330/*! @brief The function pointer type for window iconify callbacks.
1331 *
1332 * This is the function pointer type for window iconify callbacks. A window
1333 * iconify callback function has the following signature:
1334 * @code
1335 * void function_name(GLFWwindow* window, int iconified)
1336 * @endcode
1337 *
1338 * @param[in] window The window that was iconified or restored.
1339 * @param[in] iconified `GLFW_TRUE` if the window was iconified, or
1340 * `GLFW_FALSE` if it was restored.
1341 *
1342 * @sa @ref window_iconify
1343 * @sa @ref glfwSetWindowIconifyCallback
1344 *
1345 * @since Added in version 3.0.
1346 *
1347 * @ingroup window
1348 */
1349typedef void (* GLFWwindowiconifyfun)(GLFWwindow* window, int iconified);
1350
1351/*! @brief The function pointer type for window maximize callbacks.
1352 *
1353 * This is the function pointer type for window maximize callbacks. A window
1354 * maximize callback function has the following signature:
1355 * @code
1356 * void function_name(GLFWwindow* window, int maximized)
1357 * @endcode
1358 *
1359 * @param[in] window The window that was maximized or restored.
1360 * @param[in] maximized `GLFW_TRUE` if the window was maximized, or
1361 * `GLFW_FALSE` if it was restored.
1362 *
1363 * @sa @ref window_maximize
1364 * @sa glfwSetWindowMaximizeCallback
1365 *
1366 * @since Added in version 3.3.
1367 *
1368 * @ingroup window
1369 */
1370typedef void (* GLFWwindowmaximizefun)(GLFWwindow* window, int maximized);
1371
1372/*! @brief The function pointer type for framebuffer size callbacks.
1373 *
1374 * This is the function pointer type for framebuffer size callbacks.
1375 * A framebuffer size callback function has the following signature:
1376 * @code
1377 * void function_name(GLFWwindow* window, int width, int height)
1378 * @endcode
1379 *
1380 * @param[in] window The window whose framebuffer was resized.
1381 * @param[in] width The new width, in pixels, of the framebuffer.
1382 * @param[in] height The new height, in pixels, of the framebuffer.
1383 *
1384 * @sa @ref window_fbsize
1385 * @sa @ref glfwSetFramebufferSizeCallback
1386 *
1387 * @since Added in version 3.0.
1388 *
1389 * @ingroup window
1390 */
1391typedef void (* GLFWframebuffersizefun)(GLFWwindow* window, int width, int height);
1392
1393/*! @brief The function pointer type for window content scale callbacks.
1394 *
1395 * This is the function pointer type for window content scale callbacks.
1396 * A window content scale callback function has the following signature:
1397 * @code
1398 * void function_name(GLFWwindow* window, float xscale, float yscale)
1399 * @endcode
1400 *
1401 * @param[in] window The window whose content scale changed.
1402 * @param[in] xscale The new x-axis content scale of the window.
1403 * @param[in] yscale The new y-axis content scale of the window.
1404 *
1405 * @sa @ref window_scale
1406 * @sa @ref glfwSetWindowContentScaleCallback
1407 *
1408 * @since Added in version 3.3.
1409 *
1410 * @ingroup window
1411 */
1412typedef void (* GLFWwindowcontentscalefun)(GLFWwindow* window, float xscale, float yscale);
1413
1414/*! @brief The function pointer type for mouse button callbacks.
1415 *
1416 * This is the function pointer type for mouse button callback functions.
1417 * A mouse button callback function has the following signature:
1418 * @code
1419 * void function_name(GLFWwindow* window, int button, int action, int mods)
1420 * @endcode
1421 *
1422 * @param[in] window The window that received the event.
1423 * @param[in] button The [mouse button](@ref buttons) that was pressed or
1424 * released.
1425 * @param[in] action One of `GLFW_PRESS` or `GLFW_RELEASE`. Future releases
1426 * may add more actions.
1427 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
1428 * held down.
1429 *
1430 * @sa @ref input_mouse_button
1431 * @sa @ref glfwSetMouseButtonCallback
1432 *
1433 * @since Added in version 1.0.
1434 * @glfw3 Added window handle and modifier mask parameters.
1435 *
1436 * @ingroup input
1437 */
1438typedef void (* GLFWmousebuttonfun)(GLFWwindow* window, int button, int action, int mods);
1439
1440/*! @brief The function pointer type for cursor position callbacks.
1441 *
1442 * This is the function pointer type for cursor position callbacks. A cursor
1443 * position callback function has the following signature:
1444 * @code
1445 * void function_name(GLFWwindow* window, double xpos, double ypos);
1446 * @endcode
1447 *
1448 * @param[in] window The window that received the event.
1449 * @param[in] xpos The new cursor x-coordinate, relative to the left edge of
1450 * the content area.
1451 * @param[in] ypos The new cursor y-coordinate, relative to the top edge of the
1452 * content area.
1453 *
1454 * @sa @ref cursor_pos
1455 * @sa @ref glfwSetCursorPosCallback
1456 *
1457 * @since Added in version 3.0. Replaces `GLFWmouseposfun`.
1458 *
1459 * @ingroup input
1460 */
1461typedef void (* GLFWcursorposfun)(GLFWwindow* window, double xpos, double ypos);
1462
1463/*! @brief The function pointer type for cursor enter/leave callbacks.
1464 *
1465 * This is the function pointer type for cursor enter/leave callbacks.
1466 * A cursor enter/leave callback function has the following signature:
1467 * @code
1468 * void function_name(GLFWwindow* window, int entered)
1469 * @endcode
1470 *
1471 * @param[in] window The window that received the event.
1472 * @param[in] entered `GLFW_TRUE` if the cursor entered the window's content
1473 * area, or `GLFW_FALSE` if it left it.
1474 *
1475 * @sa @ref cursor_enter
1476 * @sa @ref glfwSetCursorEnterCallback
1477 *
1478 * @since Added in version 3.0.
1479 *
1480 * @ingroup input
1481 */
1482typedef void (* GLFWcursorenterfun)(GLFWwindow* window, int entered);
1483
1484/*! @brief The function pointer type for scroll callbacks.
1485 *
1486 * This is the function pointer type for scroll callbacks. A scroll callback
1487 * function has the following signature:
1488 * @code
1489 * void function_name(GLFWwindow* window, double xoffset, double yoffset)
1490 * @endcode
1491 *
1492 * @param[in] window The window that received the event.
1493 * @param[in] xoffset The scroll offset along the x-axis.
1494 * @param[in] yoffset The scroll offset along the y-axis.
1495 *
1496 * @sa @ref scrolling
1497 * @sa @ref glfwSetScrollCallback
1498 *
1499 * @since Added in version 3.0. Replaces `GLFWmousewheelfun`.
1500 *
1501 * @ingroup input
1502 */
1503typedef void (* GLFWscrollfun)(GLFWwindow* window, double xoffset, double yoffset);
1504
1505/*! @brief The function pointer type for keyboard key callbacks.
1506 *
1507 * This is the function pointer type for keyboard key callbacks. A keyboard
1508 * key callback function has the following signature:
1509 * @code
1510 * void function_name(GLFWwindow* window, int key, int scancode, int action, int mods)
1511 * @endcode
1512 *
1513 * @param[in] window The window that received the event.
1514 * @param[in] key The [keyboard key](@ref keys) that was pressed or released.
1515 * @param[in] scancode The system-specific scancode of the key.
1516 * @param[in] action `GLFW_PRESS`, `GLFW_RELEASE` or `GLFW_REPEAT`. Future
1517 * releases may add more actions.
1518 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
1519 * held down.
1520 *
1521 * @sa @ref input_key
1522 * @sa @ref glfwSetKeyCallback
1523 *
1524 * @since Added in version 1.0.
1525 * @glfw3 Added window handle, scancode and modifier mask parameters.
1526 *
1527 * @ingroup input
1528 */
1529typedef void (* GLFWkeyfun)(GLFWwindow* window, int key, int scancode, int action, int mods);
1530
1531/*! @brief The function pointer type for Unicode character callbacks.
1532 *
1533 * This is the function pointer type for Unicode character callbacks.
1534 * A Unicode character callback function has the following signature:
1535 * @code
1536 * void function_name(GLFWwindow* window, unsigned int codepoint)
1537 * @endcode
1538 *
1539 * @param[in] window The window that received the event.
1540 * @param[in] codepoint The Unicode code point of the character.
1541 *
1542 * @sa @ref input_char
1543 * @sa @ref glfwSetCharCallback
1544 *
1545 * @since Added in version 2.4.
1546 * @glfw3 Added window handle parameter.
1547 *
1548 * @ingroup input
1549 */
1550typedef void (* GLFWcharfun)(GLFWwindow* window, unsigned int codepoint);
1551
1552/*! @brief The function pointer type for Unicode character with modifiers
1553 * callbacks.
1554 *
1555 * This is the function pointer type for Unicode character with modifiers
1556 * callbacks. It is called for each input character, regardless of what
1557 * modifier keys are held down. A Unicode character with modifiers callback
1558 * function has the following signature:
1559 * @code
1560 * void function_name(GLFWwindow* window, unsigned int codepoint, int mods)
1561 * @endcode
1562 *
1563 * @param[in] window The window that received the event.
1564 * @param[in] codepoint The Unicode code point of the character.
1565 * @param[in] mods Bit field describing which [modifier keys](@ref mods) were
1566 * held down.
1567 *
1568 * @sa @ref input_char
1569 * @sa @ref glfwSetCharModsCallback
1570 *
1571 * @deprecated Scheduled for removal in version 4.0.
1572 *
1573 * @since Added in version 3.1.
1574 *
1575 * @ingroup input
1576 */
1577typedef void (* GLFWcharmodsfun)(GLFWwindow* window, unsigned int codepoint, int mods);
1578
1579/*! @brief The function pointer type for path drop callbacks.
1580 *
1581 * This is the function pointer type for path drop callbacks. A path drop
1582 * callback function has the following signature:
1583 * @code
1584 * void function_name(GLFWwindow* window, int path_count, const char* paths[])
1585 * @endcode
1586 *
1587 * @param[in] window The window that received the event.
1588 * @param[in] path_count The number of dropped paths.
1589 * @param[in] paths The UTF-8 encoded file and/or directory path names.
1590 *
1591 * @pointer_lifetime The path array and its strings are valid until the
1592 * callback function returns.
1593 *
1594 * @sa @ref path_drop
1595 * @sa @ref glfwSetDropCallback
1596 *
1597 * @since Added in version 3.1.
1598 *
1599 * @ingroup input
1600 */
1601typedef void (* GLFWdropfun)(GLFWwindow* window, int path_count, const char* paths[]);
1602
1603/*! @brief The function pointer type for monitor configuration callbacks.
1604 *
1605 * This is the function pointer type for monitor configuration callbacks.
1606 * A monitor callback function has the following signature:
1607 * @code
1608 * void function_name(GLFWmonitor* monitor, int event)
1609 * @endcode
1610 *
1611 * @param[in] monitor The monitor that was connected or disconnected.
1612 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future
1613 * releases may add more events.
1614 *
1615 * @sa @ref monitor_event
1616 * @sa @ref glfwSetMonitorCallback
1617 *
1618 * @since Added in version 3.0.
1619 *
1620 * @ingroup monitor
1621 */
1622typedef void (* GLFWmonitorfun)(GLFWmonitor* monitor, int event);
1623
1624/*! @brief The function pointer type for joystick configuration callbacks.
1625 *
1626 * This is the function pointer type for joystick configuration callbacks.
1627 * A joystick configuration callback function has the following signature:
1628 * @code
1629 * void function_name(int jid, int event)
1630 * @endcode
1631 *
1632 * @param[in] jid The joystick that was connected or disconnected.
1633 * @param[in] event One of `GLFW_CONNECTED` or `GLFW_DISCONNECTED`. Future
1634 * releases may add more events.
1635 *
1636 * @sa @ref joystick_event
1637 * @sa @ref glfwSetJoystickCallback
1638 *
1639 * @since Added in version 3.2.
1640 *
1641 * @ingroup input
1642 */
1643typedef void (* GLFWjoystickfun)(int jid, int event);
1644
1645/*! @brief Video mode type.
1646 *
1647 * This describes a single video mode.
1648 *
1649 * @sa @ref monitor_modes
1650 * @sa @ref glfwGetVideoMode
1651 * @sa @ref glfwGetVideoModes
1652 *
1653 * @since Added in version 1.0.
1654 * @glfw3 Added refresh rate member.
1655 *
1656 * @ingroup monitor
1657 */
1658typedef struct GLFWvidmode
1659{
1660 /*! The width, in screen coordinates, of the video mode.
1661 */
1662 int width;
1663 /*! The height, in screen coordinates, of the video mode.
1664 */
1665 int height;
1666 /*! The bit depth of the red channel of the video mode.
1667 */
1668 int redBits;
1669 /*! The bit depth of the green channel of the video mode.
1670 */
1671 int greenBits;
1672 /*! The bit depth of the blue channel of the video mode.
1673 */
1674 int blueBits;
1675 /*! The refresh rate, in Hz, of the video mode.
1676 */
1677 int refreshRate;
1678} GLFWvidmode;
1679
1680/*! @brief Gamma ramp.
1681 *
1682 * This describes the gamma ramp for a monitor.
1683 *
1684 * @sa @ref monitor_gamma
1685 * @sa @ref glfwGetGammaRamp
1686 * @sa @ref glfwSetGammaRamp
1687 *
1688 * @since Added in version 3.0.
1689 *
1690 * @ingroup monitor
1691 */
1692typedef struct GLFWgammaramp
1693{
1694 /*! An array of value describing the response of the red channel.
1695 */
1696 unsigned short* red;
1697 /*! An array of value describing the response of the green channel.
1698 */
1699 unsigned short* green;
1700 /*! An array of value describing the response of the blue channel.
1701 */
1702 unsigned short* blue;
1703 /*! The number of elements in each array.
1704 */
1705 unsigned int size;
1706} GLFWgammaramp;
1707
1708/*! @brief Image data.
1709 *
1710 * This describes a single 2D image. See the documentation for each related
1711 * function what the expected pixel format is.
1712 *
1713 * @sa @ref cursor_custom
1714 * @sa @ref window_icon
1715 *
1716 * @since Added in version 2.1.
1717 * @glfw3 Removed format and bytes-per-pixel members.
1718 *
1719 * @ingroup window
1720 */
1721typedef struct GLFWimage
1722{
1723 /*! The width, in pixels, of this image.
1724 */
1725 int width;
1726 /*! The height, in pixels, of this image.
1727 */
1728 int height;
1729 /*! The pixel data of this image, arranged left-to-right, top-to-bottom.
1730 */
1731 unsigned char* pixels;
1732} GLFWimage;
1733
1734/*! @brief Gamepad input state
1735 *
1736 * This describes the input state of a gamepad.
1737 *
1738 * @sa @ref gamepad
1739 * @sa @ref glfwGetGamepadState
1740 *
1741 * @since Added in version 3.3.
1742 *
1743 * @ingroup input
1744 */
1745typedef struct GLFWgamepadstate
1746{
1747 /*! The states of each [gamepad button](@ref gamepad_buttons), `GLFW_PRESS`
1748 * or `GLFW_RELEASE`.
1749 */
1750 unsigned char buttons[15];
1751 /*! The states of each [gamepad axis](@ref gamepad_axes), in the range -1.0
1752 * to 1.0 inclusive.
1753 */
1754 float axes[6];
1755} GLFWgamepadstate;
1756
1757
1758/*************************************************************************
1759 * GLFW API functions
1760 *************************************************************************/
1761
1762/*! @brief Initializes the GLFW library.
1763 *
1764 * This function initializes the GLFW library. Before most GLFW functions can
1765 * be used, GLFW must be initialized, and before an application terminates GLFW
1766 * should be terminated in order to free any resources allocated during or
1767 * after initialization.
1768 *
1769 * If this function fails, it calls @ref glfwTerminate before returning. If it
1770 * succeeds, you should call @ref glfwTerminate before the application exits.
1771 *
1772 * Additional calls to this function after successful initialization but before
1773 * termination will return `GLFW_TRUE` immediately.
1774 *
1775 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
1776 * [error](@ref error_handling) occurred.
1777 *
1778 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR.
1779 *
1780 * @remark @macos This function will change the current directory of the
1781 * application to the `Contents/Resources` subdirectory of the application's
1782 * bundle, if present. This can be disabled with the @ref
1783 * GLFW_COCOA_CHDIR_RESOURCES init hint.
1784 *
1785 * @remark @x11 This function will set the `LC_CTYPE` category of the
1786 * application locale according to the current environment if that category is
1787 * still "C". This is because the "C" locale breaks Unicode text input.
1788 *
1789 * @thread_safety This function must only be called from the main thread.
1790 *
1791 * @sa @ref intro_init
1792 * @sa @ref glfwTerminate
1793 *
1794 * @since Added in version 1.0.
1795 *
1796 * @ingroup init
1797 */
1798GLFWAPI int glfwInit(void);
1799
1800/*! @brief Terminates the GLFW library.
1801 *
1802 * This function destroys all remaining windows and cursors, restores any
1803 * modified gamma ramps and frees any other allocated resources. Once this
1804 * function is called, you must again call @ref glfwInit successfully before
1805 * you will be able to use most GLFW functions.
1806 *
1807 * If GLFW has been successfully initialized, this function should be called
1808 * before the application exits. If initialization fails, there is no need to
1809 * call this function, as it is called by @ref glfwInit before it returns
1810 * failure.
1811 *
1812 * This function has no effect if GLFW is not initialized.
1813 *
1814 * @errors Possible errors include @ref GLFW_PLATFORM_ERROR.
1815 *
1816 * @remark This function may be called before @ref glfwInit.
1817 *
1818 * @warning The contexts of any remaining windows must not be current on any
1819 * other thread when this function is called.
1820 *
1821 * @reentrancy This function must not be called from a callback.
1822 *
1823 * @thread_safety This function must only be called from the main thread.
1824 *
1825 * @sa @ref intro_init
1826 * @sa @ref glfwInit
1827 *
1828 * @since Added in version 1.0.
1829 *
1830 * @ingroup init
1831 */
1832GLFWAPI void glfwTerminate(void);
1833
1834/*! @brief Sets the specified init hint to the desired value.
1835 *
1836 * This function sets hints for the next initialization of GLFW.
1837 *
1838 * The values you set hints to are never reset by GLFW, but they only take
1839 * effect during initialization. Once GLFW has been initialized, any values
1840 * you set will be ignored until the library is terminated and initialized
1841 * again.
1842 *
1843 * Some hints are platform specific. These may be set on any platform but they
1844 * will only affect their specific platform. Other platforms will ignore them.
1845 * Setting these hints requires no platform specific headers or functions.
1846 *
1847 * @param[in] hint The [init hint](@ref init_hints) to set.
1848 * @param[in] value The new value of the init hint.
1849 *
1850 * @errors Possible errors include @ref GLFW_INVALID_ENUM and @ref
1851 * GLFW_INVALID_VALUE.
1852 *
1853 * @remarks This function may be called before @ref glfwInit.
1854 *
1855 * @thread_safety This function must only be called from the main thread.
1856 *
1857 * @sa init_hints
1858 * @sa glfwInit
1859 *
1860 * @since Added in version 3.3.
1861 *
1862 * @ingroup init
1863 */
1864GLFWAPI void glfwInitHint(int hint, int value);
1865
1866/*! @brief Retrieves the version of the GLFW library.
1867 *
1868 * This function retrieves the major, minor and revision numbers of the GLFW
1869 * library. It is intended for when you are using GLFW as a shared library and
1870 * want to ensure that you are using the minimum required version.
1871 *
1872 * Any or all of the version arguments may be `NULL`.
1873 *
1874 * @param[out] major Where to store the major version number, or `NULL`.
1875 * @param[out] minor Where to store the minor version number, or `NULL`.
1876 * @param[out] rev Where to store the revision number, or `NULL`.
1877 *
1878 * @errors None.
1879 *
1880 * @remark This function may be called before @ref glfwInit.
1881 *
1882 * @thread_safety This function may be called from any thread.
1883 *
1884 * @sa @ref intro_version
1885 * @sa @ref glfwGetVersionString
1886 *
1887 * @since Added in version 1.0.
1888 *
1889 * @ingroup init
1890 */
1891GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
1892
1893/*! @brief Returns a string describing the compile-time configuration.
1894 *
1895 * This function returns the compile-time generated
1896 * [version string](@ref intro_version_string) of the GLFW library binary. It
1897 * describes the version, platform, compiler and any platform-specific
1898 * compile-time options. It should not be confused with the OpenGL or OpenGL
1899 * ES version string, queried with `glGetString`.
1900 *
1901 * __Do not use the version string__ to parse the GLFW library version. The
1902 * @ref glfwGetVersion function provides the version of the running library
1903 * binary in numerical format.
1904 *
1905 * @return The ASCII encoded GLFW version string.
1906 *
1907 * @errors None.
1908 *
1909 * @remark This function may be called before @ref glfwInit.
1910 *
1911 * @pointer_lifetime The returned string is static and compile-time generated.
1912 *
1913 * @thread_safety This function may be called from any thread.
1914 *
1915 * @sa @ref intro_version
1916 * @sa @ref glfwGetVersion
1917 *
1918 * @since Added in version 3.0.
1919 *
1920 * @ingroup init
1921 */
1922GLFWAPI const char* glfwGetVersionString(void);
1923
1924/*! @brief Returns and clears the last error for the calling thread.
1925 *
1926 * This function returns and clears the [error code](@ref errors) of the last
1927 * error that occurred on the calling thread, and optionally a UTF-8 encoded
1928 * human-readable description of it. If no error has occurred since the last
1929 * call, it returns @ref GLFW_NO_ERROR (zero) and the description pointer is
1930 * set to `NULL`.
1931 *
1932 * @param[in] description Where to store the error description pointer, or `NULL`.
1933 * @return The last error code for the calling thread, or @ref GLFW_NO_ERROR
1934 * (zero).
1935 *
1936 * @errors None.
1937 *
1938 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
1939 * should not free it yourself. It is guaranteed to be valid only until the
1940 * next error occurs or the library is terminated.
1941 *
1942 * @remark This function may be called before @ref glfwInit.
1943 *
1944 * @thread_safety This function may be called from any thread.
1945 *
1946 * @sa @ref error_handling
1947 * @sa @ref glfwSetErrorCallback
1948 *
1949 * @since Added in version 3.3.
1950 *
1951 * @ingroup init
1952 */
1953GLFWAPI int glfwGetError(const char** description);
1954
1955/*! @brief Sets the error callback.
1956 *
1957 * This function sets the error callback, which is called with an error code
1958 * and a human-readable description each time a GLFW error occurs.
1959 *
1960 * The error code is set before the callback is called. Calling @ref
1961 * glfwGetError from the error callback will return the same value as the error
1962 * code argument.
1963 *
1964 * The error callback is called on the thread where the error occurred. If you
1965 * are using GLFW from multiple threads, your error callback needs to be
1966 * written accordingly.
1967 *
1968 * Because the description string may have been generated specifically for that
1969 * error, it is not guaranteed to be valid after the callback has returned. If
1970 * you wish to use it after the callback returns, you need to make a copy.
1971 *
1972 * Once set, the error callback remains set even after the library has been
1973 * terminated.
1974 *
1975 * @param[in] callback The new callback, or `NULL` to remove the currently set
1976 * callback.
1977 * @return The previously set callback, or `NULL` if no callback was set.
1978 *
1979 * @callback_signature
1980 * @code
1981 * void callback_name(int error_code, const char* description)
1982 * @endcode
1983 * For more information about the callback parameters, see the
1984 * [callback pointer type](@ref GLFWerrorfun).
1985 *
1986 * @errors None.
1987 *
1988 * @remark This function may be called before @ref glfwInit.
1989 *
1990 * @thread_safety This function must only be called from the main thread.
1991 *
1992 * @sa @ref error_handling
1993 * @sa @ref glfwGetError
1994 *
1995 * @since Added in version 3.0.
1996 *
1997 * @ingroup init
1998 */
1999GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun callback);
2000
2001/*! @brief Returns the currently connected monitors.
2002 *
2003 * This function returns an array of handles for all currently connected
2004 * monitors. The primary monitor is always first in the returned array. If no
2005 * monitors were found, this function returns `NULL`.
2006 *
2007 * @param[out] count Where to store the number of monitors in the returned
2008 * array. This is set to zero if an error occurred.
2009 * @return An array of monitor handles, or `NULL` if no monitors were found or
2010 * if an [error](@ref error_handling) occurred.
2011 *
2012 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2013 *
2014 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
2015 * should not free it yourself. It is guaranteed to be valid only until the
2016 * monitor configuration changes or the library is terminated.
2017 *
2018 * @thread_safety This function must only be called from the main thread.
2019 *
2020 * @sa @ref monitor_monitors
2021 * @sa @ref monitor_event
2022 * @sa @ref glfwGetPrimaryMonitor
2023 *
2024 * @since Added in version 3.0.
2025 *
2026 * @ingroup monitor
2027 */
2028GLFWAPI GLFWmonitor** glfwGetMonitors(int* count);
2029
2030/*! @brief Returns the primary monitor.
2031 *
2032 * This function returns the primary monitor. This is usually the monitor
2033 * where elements like the task bar or global menu bar are located.
2034 *
2035 * @return The primary monitor, or `NULL` if no monitors were found or if an
2036 * [error](@ref error_handling) occurred.
2037 *
2038 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2039 *
2040 * @thread_safety This function must only be called from the main thread.
2041 *
2042 * @remark The primary monitor is always first in the array returned by @ref
2043 * glfwGetMonitors.
2044 *
2045 * @sa @ref monitor_monitors
2046 * @sa @ref glfwGetMonitors
2047 *
2048 * @since Added in version 3.0.
2049 *
2050 * @ingroup monitor
2051 */
2052GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void);
2053
2054/*! @brief Returns the position of the monitor's viewport on the virtual screen.
2055 *
2056 * This function returns the position, in screen coordinates, of the upper-left
2057 * corner of the specified monitor.
2058 *
2059 * Any or all of the position arguments may be `NULL`. If an error occurs, all
2060 * non-`NULL` position arguments will be set to zero.
2061 *
2062 * @param[in] monitor The monitor to query.
2063 * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`.
2064 * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`.
2065 *
2066 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2067 * GLFW_PLATFORM_ERROR.
2068 *
2069 * @thread_safety This function must only be called from the main thread.
2070 *
2071 * @sa @ref monitor_properties
2072 *
2073 * @since Added in version 3.0.
2074 *
2075 * @ingroup monitor
2076 */
2077GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos);
2078
2079/*! @brief Retrieves the work area of the monitor.
2080 *
2081 * This function returns the position, in screen coordinates, of the upper-left
2082 * corner of the work area of the specified monitor along with the work area
2083 * size in screen coordinates. The work area is defined as the area of the
2084 * monitor not occluded by the operating system task bar where present. If no
2085 * task bar exists then the work area is the monitor resolution in screen
2086 * coordinates.
2087 *
2088 * Any or all of the position and size arguments may be `NULL`. If an error
2089 * occurs, all non-`NULL` position and size arguments will be set to zero.
2090 *
2091 * @param[in] monitor The monitor to query.
2092 * @param[out] xpos Where to store the monitor x-coordinate, or `NULL`.
2093 * @param[out] ypos Where to store the monitor y-coordinate, or `NULL`.
2094 * @param[out] width Where to store the monitor width, or `NULL`.
2095 * @param[out] height Where to store the monitor height, or `NULL`.
2096 *
2097 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2098 * GLFW_PLATFORM_ERROR.
2099 *
2100 * @thread_safety This function must only be called from the main thread.
2101 *
2102 * @sa @ref monitor_workarea
2103 *
2104 * @since Added in version 3.3.
2105 *
2106 * @ingroup monitor
2107 */
2108GLFWAPI void glfwGetMonitorWorkarea(GLFWmonitor* monitor, int* xpos, int* ypos, int* width, int* height);
2109
2110/*! @brief Returns the physical size of the monitor.
2111 *
2112 * This function returns the size, in millimetres, of the display area of the
2113 * specified monitor.
2114 *
2115 * Some systems do not provide accurate monitor size information, either
2116 * because the monitor
2117 * [EDID](https://en.wikipedia.org/wiki/Extended_display_identification_data)
2118 * data is incorrect or because the driver does not report it accurately.
2119 *
2120 * Any or all of the size arguments may be `NULL`. If an error occurs, all
2121 * non-`NULL` size arguments will be set to zero.
2122 *
2123 * @param[in] monitor The monitor to query.
2124 * @param[out] widthMM Where to store the width, in millimetres, of the
2125 * monitor's display area, or `NULL`.
2126 * @param[out] heightMM Where to store the height, in millimetres, of the
2127 * monitor's display area, or `NULL`.
2128 *
2129 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2130 *
2131 * @remark @win32 On Windows 8 and earlier the physical size is calculated from
2132 * the current resolution and system DPI instead of querying the monitor EDID data.
2133 *
2134 * @thread_safety This function must only be called from the main thread.
2135 *
2136 * @sa @ref monitor_properties
2137 *
2138 * @since Added in version 3.0.
2139 *
2140 * @ingroup monitor
2141 */
2142GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int* heightMM);
2143
2144/*! @brief Retrieves the content scale for the specified monitor.
2145 *
2146 * This function retrieves the content scale for the specified monitor. The
2147 * content scale is the ratio between the current DPI and the platform's
2148 * default DPI. This is especially important for text and any UI elements. If
2149 * the pixel dimensions of your UI scaled by this look appropriate on your
2150 * machine then it should appear at a reasonable size on other machines
2151 * regardless of their DPI and scaling settings. This relies on the system DPI
2152 * and scaling settings being somewhat correct.
2153 *
2154 * The content scale may depend on both the monitor resolution and pixel
2155 * density and on user settings. It may be very different from the raw DPI
2156 * calculated from the physical size and current resolution.
2157 *
2158 * @param[in] monitor The monitor to query.
2159 * @param[out] xscale Where to store the x-axis content scale, or `NULL`.
2160 * @param[out] yscale Where to store the y-axis content scale, or `NULL`.
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 monitor_scale
2168 * @sa @ref glfwGetWindowContentScale
2169 *
2170 * @since Added in version 3.3.
2171 *
2172 * @ingroup monitor
2173 */
2174GLFWAPI void glfwGetMonitorContentScale(GLFWmonitor* monitor, float* xscale, float* yscale);
2175
2176/*! @brief Returns the name of the specified monitor.
2177 *
2178 * This function returns a human-readable name, encoded as UTF-8, of the
2179 * specified monitor. The name typically reflects the make and model of the
2180 * monitor and is not guaranteed to be unique among the connected monitors.
2181 *
2182 * @param[in] monitor The monitor to query.
2183 * @return The UTF-8 encoded name of the monitor, or `NULL` if an
2184 * [error](@ref error_handling) occurred.
2185 *
2186 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2187 *
2188 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
2189 * should not free it yourself. It is valid until the specified monitor is
2190 * disconnected or the library is terminated.
2191 *
2192 * @thread_safety This function must only be called from the main thread.
2193 *
2194 * @sa @ref monitor_properties
2195 *
2196 * @since Added in version 3.0.
2197 *
2198 * @ingroup monitor
2199 */
2200GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
2201
2202/*! @brief Sets the user pointer of the specified monitor.
2203 *
2204 * This function sets the user-defined pointer of the specified monitor. The
2205 * current value is retained until the monitor is disconnected. The initial
2206 * value is `NULL`.
2207 *
2208 * This function may be called from the monitor callback, even for a monitor
2209 * that is being disconnected.
2210 *
2211 * @param[in] monitor The monitor whose pointer to set.
2212 * @param[in] pointer The new value.
2213 *
2214 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2215 *
2216 * @thread_safety This function may be called from any thread. Access is not
2217 * synchronized.
2218 *
2219 * @sa @ref monitor_userptr
2220 * @sa @ref glfwGetMonitorUserPointer
2221 *
2222 * @since Added in version 3.3.
2223 *
2224 * @ingroup monitor
2225 */
2226GLFWAPI void glfwSetMonitorUserPointer(GLFWmonitor* monitor, void* pointer);
2227
2228/*! @brief Returns the user pointer of the specified monitor.
2229 *
2230 * This function returns the current value of the user-defined pointer of the
2231 * specified monitor. The initial value is `NULL`.
2232 *
2233 * This function may be called from the monitor callback, even for a monitor
2234 * that is being disconnected.
2235 *
2236 * @param[in] monitor The monitor whose pointer to return.
2237 *
2238 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2239 *
2240 * @thread_safety This function may be called from any thread. Access is not
2241 * synchronized.
2242 *
2243 * @sa @ref monitor_userptr
2244 * @sa @ref glfwSetMonitorUserPointer
2245 *
2246 * @since Added in version 3.3.
2247 *
2248 * @ingroup monitor
2249 */
2250GLFWAPI void* glfwGetMonitorUserPointer(GLFWmonitor* monitor);
2251
2252/*! @brief Sets the monitor configuration callback.
2253 *
2254 * This function sets the monitor configuration callback, or removes the
2255 * currently set callback. This is called when a monitor is connected to or
2256 * disconnected from the system.
2257 *
2258 * @param[in] callback The new callback, or `NULL` to remove the currently set
2259 * callback.
2260 * @return The previously set callback, or `NULL` if no callback was set or the
2261 * library had not been [initialized](@ref intro_init).
2262 *
2263 * @callback_signature
2264 * @code
2265 * void function_name(GLFWmonitor* monitor, int event)
2266 * @endcode
2267 * For more information about the callback parameters, see the
2268 * [function pointer type](@ref GLFWmonitorfun).
2269 *
2270 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2271 *
2272 * @thread_safety This function must only be called from the main thread.
2273 *
2274 * @sa @ref monitor_event
2275 *
2276 * @since Added in version 3.0.
2277 *
2278 * @ingroup monitor
2279 */
2280GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun callback);
2281
2282/*! @brief Returns the available video modes for the specified monitor.
2283 *
2284 * This function returns an array of all video modes supported by the specified
2285 * monitor. The returned array is sorted in ascending order, first by color
2286 * bit depth (the sum of all channel depths), then by resolution area (the
2287 * product of width and height), then resolution width and finally by refresh
2288 * rate.
2289 *
2290 * @param[in] monitor The monitor to query.
2291 * @param[out] count Where to store the number of video modes in the returned
2292 * array. This is set to zero if an error occurred.
2293 * @return An array of video modes, or `NULL` if an
2294 * [error](@ref error_handling) occurred.
2295 *
2296 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2297 * GLFW_PLATFORM_ERROR.
2298 *
2299 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
2300 * should not free it yourself. It is valid until the specified monitor is
2301 * disconnected, this function is called again for that monitor or the library
2302 * is terminated.
2303 *
2304 * @thread_safety This function must only be called from the main thread.
2305 *
2306 * @sa @ref monitor_modes
2307 * @sa @ref glfwGetVideoMode
2308 *
2309 * @since Added in version 1.0.
2310 * @glfw3 Changed to return an array of modes for a specific monitor.
2311 *
2312 * @ingroup monitor
2313 */
2314GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count);
2315
2316/*! @brief Returns the current mode of the specified monitor.
2317 *
2318 * This function returns the current video mode of the specified monitor. If
2319 * you have created a full screen window for that monitor, the return value
2320 * will depend on whether that window is iconified.
2321 *
2322 * @param[in] monitor The monitor to query.
2323 * @return The current mode of the monitor, or `NULL` if an
2324 * [error](@ref error_handling) occurred.
2325 *
2326 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2327 * GLFW_PLATFORM_ERROR.
2328 *
2329 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
2330 * should not free it yourself. It is valid until the specified monitor is
2331 * disconnected or the library is terminated.
2332 *
2333 * @thread_safety This function must only be called from the main thread.
2334 *
2335 * @sa @ref monitor_modes
2336 * @sa @ref glfwGetVideoModes
2337 *
2338 * @since Added in version 3.0. Replaces `glfwGetDesktopMode`.
2339 *
2340 * @ingroup monitor
2341 */
2342GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
2343
2344/*! @brief Generates a gamma ramp and sets it for the specified monitor.
2345 *
2346 * This function generates an appropriately sized gamma ramp from the specified
2347 * exponent and then calls @ref glfwSetGammaRamp with it. The value must be
2348 * a finite number greater than zero.
2349 *
2350 * The software controlled gamma ramp is applied _in addition_ to the hardware
2351 * gamma correction, which today is usually an approximation of sRGB gamma.
2352 * This means that setting a perfectly linear ramp, or gamma 1.0, will produce
2353 * the default (usually sRGB-like) behavior.
2354 *
2355 * For gamma correct rendering with OpenGL or OpenGL ES, see the @ref
2356 * GLFW_SRGB_CAPABLE hint.
2357 *
2358 * @param[in] monitor The monitor whose gamma ramp to set.
2359 * @param[in] gamma The desired exponent.
2360 *
2361 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2362 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
2363 *
2364 * @remark @wayland Gamma handling is a privileged protocol, this function
2365 * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR.
2366 *
2367 * @thread_safety This function must only be called from the main thread.
2368 *
2369 * @sa @ref monitor_gamma
2370 *
2371 * @since Added in version 3.0.
2372 *
2373 * @ingroup monitor
2374 */
2375GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma);
2376
2377/*! @brief Returns the current gamma ramp for the specified monitor.
2378 *
2379 * This function returns the current gamma ramp of the specified monitor.
2380 *
2381 * @param[in] monitor The monitor to query.
2382 * @return The current gamma ramp, or `NULL` if an
2383 * [error](@ref error_handling) occurred.
2384 *
2385 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2386 * GLFW_PLATFORM_ERROR.
2387 *
2388 * @remark @wayland Gamma handling is a privileged protocol, this function
2389 * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR while
2390 * returning `NULL`.
2391 *
2392 * @pointer_lifetime The returned structure and its arrays are allocated and
2393 * freed by GLFW. You should not free them yourself. They are valid until the
2394 * specified monitor is disconnected, this function is called again for that
2395 * monitor or the library is terminated.
2396 *
2397 * @thread_safety This function must only be called from the main thread.
2398 *
2399 * @sa @ref monitor_gamma
2400 *
2401 * @since Added in version 3.0.
2402 *
2403 * @ingroup monitor
2404 */
2405GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor);
2406
2407/*! @brief Sets the current gamma ramp for the specified monitor.
2408 *
2409 * This function sets the current gamma ramp for the specified monitor. The
2410 * original gamma ramp for that monitor is saved by GLFW the first time this
2411 * function is called and is restored by @ref glfwTerminate.
2412 *
2413 * The software controlled gamma ramp is applied _in addition_ to the hardware
2414 * gamma correction, which today is usually an approximation of sRGB gamma.
2415 * This means that setting a perfectly linear ramp, or gamma 1.0, will produce
2416 * the default (usually sRGB-like) behavior.
2417 *
2418 * For gamma correct rendering with OpenGL or OpenGL ES, see the @ref
2419 * GLFW_SRGB_CAPABLE hint.
2420 *
2421 * @param[in] monitor The monitor whose gamma ramp to set.
2422 * @param[in] ramp The gamma ramp to use.
2423 *
2424 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2425 * GLFW_PLATFORM_ERROR.
2426 *
2427 * @remark The size of the specified gamma ramp should match the size of the
2428 * current ramp for that monitor.
2429 *
2430 * @remark @win32 The gamma ramp size must be 256.
2431 *
2432 * @remark @wayland Gamma handling is a privileged protocol, this function
2433 * will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR.
2434 *
2435 * @pointer_lifetime The specified gamma ramp is copied before this function
2436 * returns.
2437 *
2438 * @thread_safety This function must only be called from the main thread.
2439 *
2440 * @sa @ref monitor_gamma
2441 *
2442 * @since Added in version 3.0.
2443 *
2444 * @ingroup monitor
2445 */
2446GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp);
2447
2448/*! @brief Resets all window hints to their default values.
2449 *
2450 * This function resets all window hints to their
2451 * [default values](@ref window_hints_values).
2452 *
2453 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2454 *
2455 * @thread_safety This function must only be called from the main thread.
2456 *
2457 * @sa @ref window_hints
2458 * @sa @ref glfwWindowHint
2459 * @sa @ref glfwWindowHintString
2460 *
2461 * @since Added in version 3.0.
2462 *
2463 * @ingroup window
2464 */
2465GLFWAPI void glfwDefaultWindowHints(void);
2466
2467/*! @brief Sets the specified window hint to the desired value.
2468 *
2469 * This function sets hints for the next call to @ref glfwCreateWindow. The
2470 * hints, once set, retain their values until changed by a call to this
2471 * function or @ref glfwDefaultWindowHints, or until the library is terminated.
2472 *
2473 * Only integer value hints can be set with this function. String value hints
2474 * are set with @ref glfwWindowHintString.
2475 *
2476 * This function does not check whether the specified hint values are valid.
2477 * If you set hints to invalid values this will instead be reported by the next
2478 * call to @ref glfwCreateWindow.
2479 *
2480 * Some hints are platform specific. These may be set on any platform but they
2481 * will only affect their specific platform. Other platforms will ignore them.
2482 * Setting these hints requires no platform specific headers or functions.
2483 *
2484 * @param[in] hint The [window hint](@ref window_hints) to set.
2485 * @param[in] value The new value of the window hint.
2486 *
2487 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2488 * GLFW_INVALID_ENUM.
2489 *
2490 * @thread_safety This function must only be called from the main thread.
2491 *
2492 * @sa @ref window_hints
2493 * @sa @ref glfwWindowHintString
2494 * @sa @ref glfwDefaultWindowHints
2495 *
2496 * @since Added in version 3.0. Replaces `glfwOpenWindowHint`.
2497 *
2498 * @ingroup window
2499 */
2500GLFWAPI void glfwWindowHint(int hint, int value);
2501
2502/*! @brief Sets the specified window hint to the desired value.
2503 *
2504 * This function sets hints for the next call to @ref glfwCreateWindow. The
2505 * hints, once set, retain their values until changed by a call to this
2506 * function or @ref glfwDefaultWindowHints, or until the library is terminated.
2507 *
2508 * Only string type hints can be set with this function. Integer value hints
2509 * are set with @ref glfwWindowHint.
2510 *
2511 * This function does not check whether the specified hint values are valid.
2512 * If you set hints to invalid values this will instead be reported by the next
2513 * call to @ref glfwCreateWindow.
2514 *
2515 * Some hints are platform specific. These may be set on any platform but they
2516 * will only affect their specific platform. Other platforms will ignore them.
2517 * Setting these hints requires no platform specific headers or functions.
2518 *
2519 * @param[in] hint The [window hint](@ref window_hints) to set.
2520 * @param[in] value The new value of the window hint.
2521 *
2522 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2523 * GLFW_INVALID_ENUM.
2524 *
2525 * @pointer_lifetime The specified string is copied before this function
2526 * returns.
2527 *
2528 * @thread_safety This function must only be called from the main thread.
2529 *
2530 * @sa @ref window_hints
2531 * @sa @ref glfwWindowHint
2532 * @sa @ref glfwDefaultWindowHints
2533 *
2534 * @since Added in version 3.3.
2535 *
2536 * @ingroup window
2537 */
2538GLFWAPI void glfwWindowHintString(int hint, const char* value);
2539
2540/*! @brief Creates a window and its associated context.
2541 *
2542 * This function creates a window and its associated OpenGL or OpenGL ES
2543 * context. Most of the options controlling how the window and its context
2544 * should be created are specified with [window hints](@ref window_hints).
2545 *
2546 * Successful creation does not change which context is current. Before you
2547 * can use the newly created context, you need to
2548 * [make it current](@ref context_current). For information about the `share`
2549 * parameter, see @ref context_sharing.
2550 *
2551 * The created window, framebuffer and context may differ from what you
2552 * requested, as not all parameters and hints are
2553 * [hard constraints](@ref window_hints_hard). This includes the size of the
2554 * window, especially for full screen windows. To query the actual attributes
2555 * of the created window, framebuffer and context, see @ref
2556 * glfwGetWindowAttrib, @ref glfwGetWindowSize and @ref glfwGetFramebufferSize.
2557 *
2558 * To create a full screen window, you need to specify the monitor the window
2559 * will cover. If no monitor is specified, the window will be windowed mode.
2560 * Unless you have a way for the user to choose a specific monitor, it is
2561 * recommended that you pick the primary monitor. For more information on how
2562 * to query connected monitors, see @ref monitor_monitors.
2563 *
2564 * For full screen windows, the specified size becomes the resolution of the
2565 * window's _desired video mode_. As long as a full screen window is not
2566 * iconified, the supported video mode most closely matching the desired video
2567 * mode is set for the specified monitor. For more information about full
2568 * screen windows, including the creation of so called _windowed full screen_
2569 * or _borderless full screen_ windows, see @ref window_windowed_full_screen.
2570 *
2571 * Once you have created the window, you can switch it between windowed and
2572 * full screen mode with @ref glfwSetWindowMonitor. This will not affect its
2573 * OpenGL or OpenGL ES context.
2574 *
2575 * By default, newly created windows use the placement recommended by the
2576 * window system. To create the window at a specific position, make it
2577 * initially invisible using the [GLFW_VISIBLE](@ref GLFW_VISIBLE_hint) window
2578 * hint, set its [position](@ref window_pos) and then [show](@ref window_hide)
2579 * it.
2580 *
2581 * As long as at least one full screen window is not iconified, the screensaver
2582 * is prohibited from starting.
2583 *
2584 * Window systems put limits on window sizes. Very large or very small window
2585 * dimensions may be overridden by the window system on creation. Check the
2586 * actual [size](@ref window_size) after creation.
2587 *
2588 * The [swap interval](@ref buffer_swap) is not set during window creation and
2589 * the initial value may vary depending on driver settings and defaults.
2590 *
2591 * @param[in] width The desired width, in screen coordinates, of the window.
2592 * This must be greater than zero.
2593 * @param[in] height The desired height, in screen coordinates, of the window.
2594 * This must be greater than zero.
2595 * @param[in] title The initial, UTF-8 encoded window title.
2596 * @param[in] monitor The monitor to use for full screen mode, or `NULL` for
2597 * windowed mode.
2598 * @param[in] share The window whose context to share resources with, or `NULL`
2599 * to not share resources.
2600 * @return The handle of the created window, or `NULL` if an
2601 * [error](@ref error_handling) occurred.
2602 *
2603 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2604 * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_API_UNAVAILABLE, @ref
2605 * GLFW_VERSION_UNAVAILABLE, @ref GLFW_FORMAT_UNAVAILABLE and @ref
2606 * GLFW_PLATFORM_ERROR.
2607 *
2608 * @remark @win32 Window creation will fail if the Microsoft GDI software
2609 * OpenGL implementation is the only one available.
2610 *
2611 * @remark @win32 If the executable has an icon resource named `GLFW_ICON,` it
2612 * will be set as the initial icon for the window. If no such icon is present,
2613 * the `IDI_APPLICATION` icon will be used instead. To set a different icon,
2614 * see @ref glfwSetWindowIcon.
2615 *
2616 * @remark @win32 The context to share resources with must not be current on
2617 * any other thread.
2618 *
2619 * @remark @macos The OS only supports forward-compatible core profile contexts
2620 * for OpenGL versions 3.2 and later. Before creating an OpenGL context of
2621 * version 3.2 or later you must set the
2622 * [GLFW_OPENGL_FORWARD_COMPAT](@ref GLFW_OPENGL_FORWARD_COMPAT_hint) and
2623 * [GLFW_OPENGL_PROFILE](@ref GLFW_OPENGL_PROFILE_hint) hints accordingly.
2624 * OpenGL 3.0 and 3.1 contexts are not supported at all on macOS.
2625 *
2626 * @remark @macos The GLFW window has no icon, as it is not a document
2627 * window, but the dock icon will be the same as the application bundle's icon.
2628 * For more information on bundles, see the
2629 * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
2630 * in the Mac Developer Library.
2631 *
2632 * @remark @macos The first time a window is created the menu bar is created.
2633 * If GLFW finds a `MainMenu.nib` it is loaded and assumed to contain a menu
2634 * bar. Otherwise a minimal menu bar is created manually with common commands
2635 * like Hide, Quit and About. The About entry opens a minimal about dialog
2636 * with information from the application's bundle. Menu bar creation can be
2637 * disabled entirely with the @ref GLFW_COCOA_MENUBAR init hint.
2638 *
2639 * @remark @macos On OS X 10.10 and later the window frame will not be rendered
2640 * at full resolution on Retina displays unless the
2641 * [GLFW_COCOA_RETINA_FRAMEBUFFER](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint)
2642 * hint is `GLFW_TRUE` and the `NSHighResolutionCapable` key is enabled in the
2643 * application bundle's `Info.plist`. For more information, see
2644 * [High Resolution Guidelines for OS X](https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html)
2645 * in the Mac Developer Library. The GLFW test and example programs use
2646 * a custom `Info.plist` template for this, which can be found as
2647 * `CMake/MacOSXBundleInfo.plist.in` in the source tree.
2648 *
2649 * @remark @macos When activating frame autosaving with
2650 * [GLFW_COCOA_FRAME_NAME](@ref GLFW_COCOA_FRAME_NAME_hint), the specified
2651 * window size and position may be overridden by previously saved values.
2652 *
2653 * @remark @x11 Some window managers will not respect the placement of
2654 * initially hidden windows.
2655 *
2656 * @remark @x11 Due to the asynchronous nature of X11, it may take a moment for
2657 * a window to reach its requested state. This means you may not be able to
2658 * query the final size, position or other attributes directly after window
2659 * creation.
2660 *
2661 * @remark @x11 The class part of the `WM_CLASS` window property will by
2662 * default be set to the window title passed to this function. The instance
2663 * part will use the contents of the `RESOURCE_NAME` environment variable, if
2664 * present and not empty, or fall back to the window title. Set the
2665 * [GLFW_X11_CLASS_NAME](@ref GLFW_X11_CLASS_NAME_hint) and
2666 * [GLFW_X11_INSTANCE_NAME](@ref GLFW_X11_INSTANCE_NAME_hint) window hints to
2667 * override this.
2668 *
2669 * @remark @wayland Compositors should implement the xdg-decoration protocol
2670 * for GLFW to decorate the window properly. If this protocol isn't
2671 * supported, or if the compositor prefers client-side decorations, a very
2672 * simple fallback frame will be drawn using the wp_viewporter protocol. A
2673 * compositor can still emit close, maximize or fullscreen events, using for
2674 * instance a keybind mechanism. If neither of these protocols is supported,
2675 * the window won't be decorated.
2676 *
2677 * @remark @wayland A full screen window will not attempt to change the mode,
2678 * no matter what the requested size or refresh rate.
2679 *
2680 * @remark @wayland Screensaver inhibition requires the idle-inhibit protocol
2681 * to be implemented in the user's compositor.
2682 *
2683 * @thread_safety This function must only be called from the main thread.
2684 *
2685 * @sa @ref window_creation
2686 * @sa @ref glfwDestroyWindow
2687 *
2688 * @since Added in version 3.0. Replaces `glfwOpenWindow`.
2689 *
2690 * @ingroup window
2691 */
2692GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share);
2693
2694/*! @brief Destroys the specified window and its context.
2695 *
2696 * This function destroys the specified window and its context. On calling
2697 * this function, no further callbacks will be called for that window.
2698 *
2699 * If the context of the specified window is current on the main thread, it is
2700 * detached before being destroyed.
2701 *
2702 * @param[in] window The window to destroy.
2703 *
2704 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2705 * GLFW_PLATFORM_ERROR.
2706 *
2707 * @note The context of the specified window must not be current on any other
2708 * thread when this function is called.
2709 *
2710 * @reentrancy This function must not be called from a callback.
2711 *
2712 * @thread_safety This function must only be called from the main thread.
2713 *
2714 * @sa @ref window_creation
2715 * @sa @ref glfwCreateWindow
2716 *
2717 * @since Added in version 3.0. Replaces `glfwCloseWindow`.
2718 *
2719 * @ingroup window
2720 */
2721GLFWAPI void glfwDestroyWindow(GLFWwindow* window);
2722
2723/*! @brief Checks the close flag of the specified window.
2724 *
2725 * This function returns the value of the close flag of the specified window.
2726 *
2727 * @param[in] window The window to query.
2728 * @return The value of the close flag.
2729 *
2730 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2731 *
2732 * @thread_safety This function may be called from any thread. Access is not
2733 * synchronized.
2734 *
2735 * @sa @ref window_close
2736 *
2737 * @since Added in version 3.0.
2738 *
2739 * @ingroup window
2740 */
2741GLFWAPI int glfwWindowShouldClose(GLFWwindow* window);
2742
2743/*! @brief Sets the close flag of the specified window.
2744 *
2745 * This function sets the value of the close flag of the specified window.
2746 * This can be used to override the user's attempt to close the window, or
2747 * to signal that it should be closed.
2748 *
2749 * @param[in] window The window whose flag to change.
2750 * @param[in] value The new value.
2751 *
2752 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
2753 *
2754 * @thread_safety This function may be called from any thread. Access is not
2755 * synchronized.
2756 *
2757 * @sa @ref window_close
2758 *
2759 * @since Added in version 3.0.
2760 *
2761 * @ingroup window
2762 */
2763GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value);
2764
2765/*! @brief Sets the title of the specified window.
2766 *
2767 * This function sets the window title, encoded as UTF-8, of the specified
2768 * window.
2769 *
2770 * @param[in] window The window whose title to change.
2771 * @param[in] title The UTF-8 encoded window title.
2772 *
2773 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2774 * GLFW_PLATFORM_ERROR.
2775 *
2776 * @remark @macos The window title will not be updated until the next time you
2777 * process events.
2778 *
2779 * @thread_safety This function must only be called from the main thread.
2780 *
2781 * @sa @ref window_title
2782 *
2783 * @since Added in version 1.0.
2784 * @glfw3 Added window handle parameter.
2785 *
2786 * @ingroup window
2787 */
2788GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title);
2789
2790/*! @brief Sets the icon for the specified window.
2791 *
2792 * This function sets the icon of the specified window. If passed an array of
2793 * candidate images, those of or closest to the sizes desired by the system are
2794 * selected. If no images are specified, the window reverts to its default
2795 * icon.
2796 *
2797 * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight
2798 * bits per channel with the red channel first. They are arranged canonically
2799 * as packed sequential rows, starting from the top-left corner.
2800 *
2801 * The desired image sizes varies depending on platform and system settings.
2802 * The selected images will be rescaled as needed. Good sizes include 16x16,
2803 * 32x32 and 48x48.
2804 *
2805 * @param[in] window The window whose icon to set.
2806 * @param[in] count The number of images in the specified array, or zero to
2807 * revert to the default window icon.
2808 * @param[in] images The images to create the icon from. This is ignored if
2809 * count is zero.
2810 *
2811 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2812 * GLFW_PLATFORM_ERROR.
2813 *
2814 * @pointer_lifetime The specified image data is copied before this function
2815 * returns.
2816 *
2817 * @remark @macos The GLFW window has no icon, as it is not a document
2818 * window, so this function does nothing. The dock icon will be the same as
2819 * the application bundle's icon. For more information on bundles, see the
2820 * [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
2821 * in the Mac Developer Library.
2822 *
2823 * @remark @wayland There is no existing protocol to change an icon, the
2824 * window will thus inherit the one defined in the application's desktop file.
2825 * This function always emits @ref GLFW_PLATFORM_ERROR.
2826 *
2827 * @thread_safety This function must only be called from the main thread.
2828 *
2829 * @sa @ref window_icon
2830 *
2831 * @since Added in version 3.2.
2832 *
2833 * @ingroup window
2834 */
2835GLFWAPI void glfwSetWindowIcon(GLFWwindow* window, int count, const GLFWimage* images);
2836
2837/*! @brief Retrieves the position of the content area of the specified window.
2838 *
2839 * This function retrieves the position, in screen coordinates, of the
2840 * upper-left corner of the content area of the specified window.
2841 *
2842 * Any or all of the position arguments may be `NULL`. If an error occurs, all
2843 * non-`NULL` position arguments will be set to zero.
2844 *
2845 * @param[in] window The window to query.
2846 * @param[out] xpos Where to store the x-coordinate of the upper-left corner of
2847 * the content area, or `NULL`.
2848 * @param[out] ypos Where to store the y-coordinate of the upper-left corner of
2849 * the content area, or `NULL`.
2850 *
2851 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2852 * GLFW_PLATFORM_ERROR.
2853 *
2854 * @remark @wayland There is no way for an application to retrieve the global
2855 * position of its windows, this function will always emit @ref
2856 * GLFW_PLATFORM_ERROR.
2857 *
2858 * @thread_safety This function must only be called from the main thread.
2859 *
2860 * @sa @ref window_pos
2861 * @sa @ref glfwSetWindowPos
2862 *
2863 * @since Added in version 3.0.
2864 *
2865 * @ingroup window
2866 */
2867GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
2868
2869/*! @brief Sets the position of the content area of the specified window.
2870 *
2871 * This function sets the position, in screen coordinates, of the upper-left
2872 * corner of the content area of the specified windowed mode window. If the
2873 * window is a full screen window, this function does nothing.
2874 *
2875 * __Do not use this function__ to move an already visible window unless you
2876 * have very good reasons for doing so, as it will confuse and annoy the user.
2877 *
2878 * The window manager may put limits on what positions are allowed. GLFW
2879 * cannot and should not override these limits.
2880 *
2881 * @param[in] window The window to query.
2882 * @param[in] xpos The x-coordinate of the upper-left corner of the content area.
2883 * @param[in] ypos The y-coordinate of the upper-left corner of the content area.
2884 *
2885 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2886 * GLFW_PLATFORM_ERROR.
2887 *
2888 * @remark @wayland There is no way for an application to set the global
2889 * position of its windows, this function will always emit @ref
2890 * GLFW_PLATFORM_ERROR.
2891 *
2892 * @thread_safety This function must only be called from the main thread.
2893 *
2894 * @sa @ref window_pos
2895 * @sa @ref glfwGetWindowPos
2896 *
2897 * @since Added in version 1.0.
2898 * @glfw3 Added window handle parameter.
2899 *
2900 * @ingroup window
2901 */
2902GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
2903
2904/*! @brief Retrieves the size of the content area of the specified window.
2905 *
2906 * This function retrieves the size, in screen coordinates, of the content area
2907 * of the specified window. If you wish to retrieve the size of the
2908 * framebuffer of the window in pixels, see @ref glfwGetFramebufferSize.
2909 *
2910 * Any or all of the size arguments may be `NULL`. If an error occurs, all
2911 * non-`NULL` size arguments will be set to zero.
2912 *
2913 * @param[in] window The window whose size to retrieve.
2914 * @param[out] width Where to store the width, in screen coordinates, of the
2915 * content area, or `NULL`.
2916 * @param[out] height Where to store the height, in screen coordinates, of the
2917 * content area, or `NULL`.
2918 *
2919 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
2920 * GLFW_PLATFORM_ERROR.
2921 *
2922 * @thread_safety This function must only be called from the main thread.
2923 *
2924 * @sa @ref window_size
2925 * @sa @ref glfwSetWindowSize
2926 *
2927 * @since Added in version 1.0.
2928 * @glfw3 Added window handle parameter.
2929 *
2930 * @ingroup window
2931 */
2932GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
2933
2934/*! @brief Sets the size limits of the specified window.
2935 *
2936 * This function sets the size limits of the content area of the specified
2937 * window. If the window is full screen, the size limits only take effect
2938 * once it is made windowed. If the window is not resizable, this function
2939 * does nothing.
2940 *
2941 * The size limits are applied immediately to a windowed mode window and may
2942 * cause it to be resized.
2943 *
2944 * The maximum dimensions must be greater than or equal to the minimum
2945 * dimensions and all must be greater than or equal to zero.
2946 *
2947 * @param[in] window The window to set limits for.
2948 * @param[in] minwidth The minimum width, in screen coordinates, of the content
2949 * area, or `GLFW_DONT_CARE`.
2950 * @param[in] minheight The minimum height, in screen coordinates, of the
2951 * content area, or `GLFW_DONT_CARE`.
2952 * @param[in] maxwidth The maximum width, in screen coordinates, of the content
2953 * area, or `GLFW_DONT_CARE`.
2954 * @param[in] maxheight The maximum height, in screen coordinates, of the
2955 * content area, or `GLFW_DONT_CARE`.
2956 *
2957 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
2958 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
2959 *
2960 * @remark If you set size limits and an aspect ratio that conflict, the
2961 * results are undefined.
2962 *
2963 * @remark @wayland The size limits will not be applied until the window is
2964 * actually resized, either by the user or by the compositor.
2965 *
2966 * @thread_safety This function must only be called from the main thread.
2967 *
2968 * @sa @ref window_sizelimits
2969 * @sa @ref glfwSetWindowAspectRatio
2970 *
2971 * @since Added in version 3.2.
2972 *
2973 * @ingroup window
2974 */
2975GLFWAPI void glfwSetWindowSizeLimits(GLFWwindow* window, int minwidth, int minheight, int maxwidth, int maxheight);
2976
2977/*! @brief Sets the aspect ratio of the specified window.
2978 *
2979 * This function sets the required aspect ratio of the content area of the
2980 * specified window. If the window is full screen, the aspect ratio only takes
2981 * effect once it is made windowed. If the window is not resizable, this
2982 * function does nothing.
2983 *
2984 * The aspect ratio is specified as a numerator and a denominator and both
2985 * values must be greater than zero. For example, the common 16:9 aspect ratio
2986 * is specified as 16 and 9, respectively.
2987 *
2988 * If the numerator and denominator is set to `GLFW_DONT_CARE` then the aspect
2989 * ratio limit is disabled.
2990 *
2991 * The aspect ratio is applied immediately to a windowed mode window and may
2992 * cause it to be resized.
2993 *
2994 * @param[in] window The window to set limits for.
2995 * @param[in] numer The numerator of the desired aspect ratio, or
2996 * `GLFW_DONT_CARE`.
2997 * @param[in] denom The denominator of the desired aspect ratio, or
2998 * `GLFW_DONT_CARE`.
2999 *
3000 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3001 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
3002 *
3003 * @remark If you set size limits and an aspect ratio that conflict, the
3004 * results are undefined.
3005 *
3006 * @remark @wayland The aspect ratio will not be applied until the window is
3007 * actually resized, either by the user or by the compositor.
3008 *
3009 * @thread_safety This function must only be called from the main thread.
3010 *
3011 * @sa @ref window_sizelimits
3012 * @sa @ref glfwSetWindowSizeLimits
3013 *
3014 * @since Added in version 3.2.
3015 *
3016 * @ingroup window
3017 */
3018GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom);
3019
3020/*! @brief Sets the size of the content area of the specified window.
3021 *
3022 * This function sets the size, in screen coordinates, of the content area of
3023 * the specified window.
3024 *
3025 * For full screen windows, this function updates the resolution of its desired
3026 * video mode and switches to the video mode closest to it, without affecting
3027 * the window's context. As the context is unaffected, the bit depths of the
3028 * framebuffer remain unchanged.
3029 *
3030 * If you wish to update the refresh rate of the desired video mode in addition
3031 * to its resolution, see @ref glfwSetWindowMonitor.
3032 *
3033 * The window manager may put limits on what sizes are allowed. GLFW cannot
3034 * and should not override these limits.
3035 *
3036 * @param[in] window The window to resize.
3037 * @param[in] width The desired width, in screen coordinates, of the window
3038 * content area.
3039 * @param[in] height The desired height, in screen coordinates, of the window
3040 * content area.
3041 *
3042 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3043 * GLFW_PLATFORM_ERROR.
3044 *
3045 * @remark @wayland A full screen window will not attempt to change the mode,
3046 * no matter what the requested size.
3047 *
3048 * @thread_safety This function must only be called from the main thread.
3049 *
3050 * @sa @ref window_size
3051 * @sa @ref glfwGetWindowSize
3052 * @sa @ref glfwSetWindowMonitor
3053 *
3054 * @since Added in version 1.0.
3055 * @glfw3 Added window handle parameter.
3056 *
3057 * @ingroup window
3058 */
3059GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
3060
3061/*! @brief Retrieves the size of the framebuffer of the specified window.
3062 *
3063 * This function retrieves the size, in pixels, of the framebuffer of the
3064 * specified window. If you wish to retrieve the size of the window in screen
3065 * coordinates, see @ref glfwGetWindowSize.
3066 *
3067 * Any or all of the size arguments may be `NULL`. If an error occurs, all
3068 * non-`NULL` size arguments will be set to zero.
3069 *
3070 * @param[in] window The window whose framebuffer to query.
3071 * @param[out] width Where to store the width, in pixels, of the framebuffer,
3072 * or `NULL`.
3073 * @param[out] height Where to store the height, in pixels, of the framebuffer,
3074 * or `NULL`.
3075 *
3076 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3077 * GLFW_PLATFORM_ERROR.
3078 *
3079 * @thread_safety This function must only be called from the main thread.
3080 *
3081 * @sa @ref window_fbsize
3082 * @sa @ref glfwSetFramebufferSizeCallback
3083 *
3084 * @since Added in version 3.0.
3085 *
3086 * @ingroup window
3087 */
3088GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height);
3089
3090/*! @brief Retrieves the size of the frame of the window.
3091 *
3092 * This function retrieves the size, in screen coordinates, of each edge of the
3093 * frame of the specified window. This size includes the title bar, if the
3094 * window has one. The size of the frame may vary depending on the
3095 * [window-related hints](@ref window_hints_wnd) used to create it.
3096 *
3097 * Because this function retrieves the size of each window frame edge and not
3098 * the offset along a particular coordinate axis, the retrieved values will
3099 * always be zero or positive.
3100 *
3101 * Any or all of the size arguments may be `NULL`. If an error occurs, all
3102 * non-`NULL` size arguments will be set to zero.
3103 *
3104 * @param[in] window The window whose frame size to query.
3105 * @param[out] left Where to store the size, in screen coordinates, of the left
3106 * edge of the window frame, or `NULL`.
3107 * @param[out] top Where to store the size, in screen coordinates, of the top
3108 * edge of the window frame, or `NULL`.
3109 * @param[out] right Where to store the size, in screen coordinates, of the
3110 * right edge of the window frame, or `NULL`.
3111 * @param[out] bottom Where to store the size, in screen coordinates, of the
3112 * bottom edge of the window frame, or `NULL`.
3113 *
3114 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3115 * GLFW_PLATFORM_ERROR.
3116 *
3117 * @thread_safety This function must only be called from the main thread.
3118 *
3119 * @sa @ref window_size
3120 *
3121 * @since Added in version 3.1.
3122 *
3123 * @ingroup window
3124 */
3125GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int* right, int* bottom);
3126
3127/*! @brief Retrieves the content scale for the specified window.
3128 *
3129 * This function retrieves the content scale for the specified window. The
3130 * content scale is the ratio between the current DPI and the platform's
3131 * default DPI. This is especially important for text and any UI elements. If
3132 * the pixel dimensions of your UI scaled by this look appropriate on your
3133 * machine then it should appear at a reasonable size on other machines
3134 * regardless of their DPI and scaling settings. This relies on the system DPI
3135 * and scaling settings being somewhat correct.
3136 *
3137 * On systems where each monitors can have its own content scale, the window
3138 * content scale will depend on which monitor the system considers the window
3139 * to be on.
3140 *
3141 * @param[in] window The window to query.
3142 * @param[out] xscale Where to store the x-axis content scale, or `NULL`.
3143 * @param[out] yscale Where to store the y-axis content scale, or `NULL`.
3144 *
3145 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3146 * GLFW_PLATFORM_ERROR.
3147 *
3148 * @thread_safety This function must only be called from the main thread.
3149 *
3150 * @sa @ref window_scale
3151 * @sa @ref glfwSetWindowContentScaleCallback
3152 * @sa @ref glfwGetMonitorContentScale
3153 *
3154 * @since Added in version 3.3.
3155 *
3156 * @ingroup window
3157 */
3158GLFWAPI void glfwGetWindowContentScale(GLFWwindow* window, float* xscale, float* yscale);
3159
3160/*! @brief Returns the opacity of the whole window.
3161 *
3162 * This function returns the opacity of the window, including any decorations.
3163 *
3164 * The opacity (or alpha) value is a positive finite number between zero and
3165 * one, where zero is fully transparent and one is fully opaque. If the system
3166 * does not support whole window transparency, this function always returns one.
3167 *
3168 * The initial opacity value for newly created windows is one.
3169 *
3170 * @param[in] window The window to query.
3171 * @return The opacity value of the specified window.
3172 *
3173 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3174 * GLFW_PLATFORM_ERROR.
3175 *
3176 * @thread_safety This function must only be called from the main thread.
3177 *
3178 * @sa @ref window_transparency
3179 * @sa @ref glfwSetWindowOpacity
3180 *
3181 * @since Added in version 3.3.
3182 *
3183 * @ingroup window
3184 */
3185GLFWAPI float glfwGetWindowOpacity(GLFWwindow* window);
3186
3187/*! @brief Sets the opacity of the whole window.
3188 *
3189 * This function sets the opacity of the window, including any decorations.
3190 *
3191 * The opacity (or alpha) value is a positive finite number between zero and
3192 * one, where zero is fully transparent and one is fully opaque.
3193 *
3194 * The initial opacity value for newly created windows is one.
3195 *
3196 * A window created with framebuffer transparency may not use whole window
3197 * transparency. The results of doing this are undefined.
3198 *
3199 * @param[in] window The window to set the opacity for.
3200 * @param[in] opacity The desired opacity of the specified window.
3201 *
3202 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3203 * GLFW_PLATFORM_ERROR.
3204 *
3205 * @thread_safety This function must only be called from the main thread.
3206 *
3207 * @sa @ref window_transparency
3208 * @sa @ref glfwGetWindowOpacity
3209 *
3210 * @since Added in version 3.3.
3211 *
3212 * @ingroup window
3213 */
3214GLFWAPI void glfwSetWindowOpacity(GLFWwindow* window, float opacity);
3215
3216/*! @brief Iconifies the specified window.
3217 *
3218 * This function iconifies (minimizes) the specified window if it was
3219 * previously restored. If the window is already iconified, this function does
3220 * nothing.
3221 *
3222 * If the specified window is a full screen window, the original monitor
3223 * resolution is restored until the window is restored.
3224 *
3225 * @param[in] window The window to iconify.
3226 *
3227 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3228 * GLFW_PLATFORM_ERROR.
3229 *
3230 * @remark @wayland There is no concept of iconification in wl_shell, this
3231 * function will emit @ref GLFW_PLATFORM_ERROR when using this deprecated
3232 * protocol.
3233 *
3234 * @thread_safety This function must only be called from the main thread.
3235 *
3236 * @sa @ref window_iconify
3237 * @sa @ref glfwRestoreWindow
3238 * @sa @ref glfwMaximizeWindow
3239 *
3240 * @since Added in version 2.1.
3241 * @glfw3 Added window handle parameter.
3242 *
3243 * @ingroup window
3244 */
3245GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
3246
3247/*! @brief Restores the specified window.
3248 *
3249 * This function restores the specified window if it was previously iconified
3250 * (minimized) or maximized. If the window is already restored, this function
3251 * does nothing.
3252 *
3253 * If the specified window is a full screen window, the resolution chosen for
3254 * the window is restored on the selected monitor.
3255 *
3256 * @param[in] window The window to restore.
3257 *
3258 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3259 * GLFW_PLATFORM_ERROR.
3260 *
3261 * @thread_safety This function must only be called from the main thread.
3262 *
3263 * @sa @ref window_iconify
3264 * @sa @ref glfwIconifyWindow
3265 * @sa @ref glfwMaximizeWindow
3266 *
3267 * @since Added in version 2.1.
3268 * @glfw3 Added window handle parameter.
3269 *
3270 * @ingroup window
3271 */
3272GLFWAPI void glfwRestoreWindow(GLFWwindow* window);
3273
3274/*! @brief Maximizes the specified window.
3275 *
3276 * This function maximizes the specified window if it was previously not
3277 * maximized. If the window is already maximized, this function does nothing.
3278 *
3279 * If the specified window is a full screen window, this function does nothing.
3280 *
3281 * @param[in] window The window to maximize.
3282 *
3283 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3284 * GLFW_PLATFORM_ERROR.
3285 *
3286 * @par Thread Safety
3287 * This function may only be called from the main thread.
3288 *
3289 * @sa @ref window_iconify
3290 * @sa @ref glfwIconifyWindow
3291 * @sa @ref glfwRestoreWindow
3292 *
3293 * @since Added in GLFW 3.2.
3294 *
3295 * @ingroup window
3296 */
3297GLFWAPI void glfwMaximizeWindow(GLFWwindow* window);
3298
3299/*! @brief Makes the specified window visible.
3300 *
3301 * This function makes the specified window visible if it was previously
3302 * hidden. If the window is already visible or is in full screen mode, this
3303 * function does nothing.
3304 *
3305 * By default, windowed mode windows are focused when shown
3306 * Set the [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) window hint
3307 * to change this behavior for all newly created windows, or change the
3308 * behavior for an existing window with @ref glfwSetWindowAttrib.
3309 *
3310 * @param[in] window The window to make visible.
3311 *
3312 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3313 * GLFW_PLATFORM_ERROR.
3314 *
3315 * @thread_safety This function must only be called from the main thread.
3316 *
3317 * @sa @ref window_hide
3318 * @sa @ref glfwHideWindow
3319 *
3320 * @since Added in version 3.0.
3321 *
3322 * @ingroup window
3323 */
3324GLFWAPI void glfwShowWindow(GLFWwindow* window);
3325
3326/*! @brief Hides the specified window.
3327 *
3328 * This function hides the specified window if it was previously visible. If
3329 * the window is already hidden or is in full screen mode, this function does
3330 * nothing.
3331 *
3332 * @param[in] window The window to hide.
3333 *
3334 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3335 * GLFW_PLATFORM_ERROR.
3336 *
3337 * @thread_safety This function must only be called from the main thread.
3338 *
3339 * @sa @ref window_hide
3340 * @sa @ref glfwShowWindow
3341 *
3342 * @since Added in version 3.0.
3343 *
3344 * @ingroup window
3345 */
3346GLFWAPI void glfwHideWindow(GLFWwindow* window);
3347
3348/*! @brief Brings the specified window to front and sets input focus.
3349 *
3350 * This function brings the specified window to front and sets input focus.
3351 * The window should already be visible and not iconified.
3352 *
3353 * By default, both windowed and full screen mode windows are focused when
3354 * initially created. Set the [GLFW_FOCUSED](@ref GLFW_FOCUSED_hint) to
3355 * disable this behavior.
3356 *
3357 * Also by default, windowed mode windows are focused when shown
3358 * with @ref glfwShowWindow. Set the
3359 * [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_hint) to disable this behavior.
3360 *
3361 * __Do not use this function__ to steal focus from other applications unless
3362 * you are certain that is what the user wants. Focus stealing can be
3363 * extremely disruptive.
3364 *
3365 * For a less disruptive way of getting the user's attention, see
3366 * [attention requests](@ref window_attention).
3367 *
3368 * @param[in] window The window to give input focus.
3369 *
3370 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3371 * GLFW_PLATFORM_ERROR.
3372 *
3373 * @remark @wayland It is not possible for an application to bring its windows
3374 * to front, this function will always emit @ref GLFW_PLATFORM_ERROR.
3375 *
3376 * @thread_safety This function must only be called from the main thread.
3377 *
3378 * @sa @ref window_focus
3379 * @sa @ref window_attention
3380 *
3381 * @since Added in version 3.2.
3382 *
3383 * @ingroup window
3384 */
3385GLFWAPI void glfwFocusWindow(GLFWwindow* window);
3386
3387/*! @brief Requests user attention to the specified window.
3388 *
3389 * This function requests user attention to the specified window. On
3390 * platforms where this is not supported, attention is requested to the
3391 * application as a whole.
3392 *
3393 * Once the user has given attention, usually by focusing the window or
3394 * application, the system will end the request automatically.
3395 *
3396 * @param[in] window The window to request attention to.
3397 *
3398 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3399 * GLFW_PLATFORM_ERROR.
3400 *
3401 * @remark @macos Attention is requested to the application as a whole, not the
3402 * specific window.
3403 *
3404 * @thread_safety This function must only be called from the main thread.
3405 *
3406 * @sa @ref window_attention
3407 *
3408 * @since Added in version 3.3.
3409 *
3410 * @ingroup window
3411 */
3412GLFWAPI void glfwRequestWindowAttention(GLFWwindow* window);
3413
3414/*! @brief Returns the monitor that the window uses for full screen mode.
3415 *
3416 * This function returns the handle of the monitor that the specified window is
3417 * in full screen on.
3418 *
3419 * @param[in] window The window to query.
3420 * @return The monitor, or `NULL` if the window is in windowed mode or an
3421 * [error](@ref error_handling) occurred.
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 window_monitor
3428 * @sa @ref glfwSetWindowMonitor
3429 *
3430 * @since Added in version 3.0.
3431 *
3432 * @ingroup window
3433 */
3434GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
3435
3436/*! @brief Sets the mode, monitor, video mode and placement of a window.
3437 *
3438 * This function sets the monitor that the window uses for full screen mode or,
3439 * if the monitor is `NULL`, makes it windowed mode.
3440 *
3441 * When setting a monitor, this function updates the width, height and refresh
3442 * rate of the desired video mode and switches to the video mode closest to it.
3443 * The window position is ignored when setting a monitor.
3444 *
3445 * When the monitor is `NULL`, the position, width and height are used to
3446 * place the window content area. The refresh rate is ignored when no monitor
3447 * is specified.
3448 *
3449 * If you only wish to update the resolution of a full screen window or the
3450 * size of a windowed mode window, see @ref glfwSetWindowSize.
3451 *
3452 * When a window transitions from full screen to windowed mode, this function
3453 * restores any previous window settings such as whether it is decorated,
3454 * floating, resizable, has size or aspect ratio limits, etc.
3455 *
3456 * @param[in] window The window whose monitor, size or video mode to set.
3457 * @param[in] monitor The desired monitor, or `NULL` to set windowed mode.
3458 * @param[in] xpos The desired x-coordinate of the upper-left corner of the
3459 * content area.
3460 * @param[in] ypos The desired y-coordinate of the upper-left corner of the
3461 * content area.
3462 * @param[in] width The desired with, in screen coordinates, of the content
3463 * area or video mode.
3464 * @param[in] height The desired height, in screen coordinates, of the content
3465 * area or video mode.
3466 * @param[in] refreshRate The desired refresh rate, in Hz, of the video mode,
3467 * or `GLFW_DONT_CARE`.
3468 *
3469 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3470 * GLFW_PLATFORM_ERROR.
3471 *
3472 * @remark The OpenGL or OpenGL ES context will not be destroyed or otherwise
3473 * affected by any resizing or mode switching, although you may need to update
3474 * your viewport if the framebuffer size has changed.
3475 *
3476 * @remark @wayland The desired window position is ignored, as there is no way
3477 * for an application to set this property.
3478 *
3479 * @remark @wayland Setting the window to full screen will not attempt to
3480 * change the mode, no matter what the requested size or refresh rate.
3481 *
3482 * @thread_safety This function must only be called from the main thread.
3483 *
3484 * @sa @ref window_monitor
3485 * @sa @ref window_full_screen
3486 * @sa @ref glfwGetWindowMonitor
3487 * @sa @ref glfwSetWindowSize
3488 *
3489 * @since Added in version 3.2.
3490 *
3491 * @ingroup window
3492 */
3493GLFWAPI void glfwSetWindowMonitor(GLFWwindow* window, GLFWmonitor* monitor, int xpos, int ypos, int width, int height, int refreshRate);
3494
3495/*! @brief Returns an attribute of the specified window.
3496 *
3497 * This function returns the value of an attribute of the specified window or
3498 * its OpenGL or OpenGL ES context.
3499 *
3500 * @param[in] window The window to query.
3501 * @param[in] attrib The [window attribute](@ref window_attribs) whose value to
3502 * return.
3503 * @return The value of the attribute, or zero if an
3504 * [error](@ref error_handling) occurred.
3505 *
3506 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3507 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
3508 *
3509 * @remark Framebuffer related hints are not window attributes. See @ref
3510 * window_attribs_fb for more information.
3511 *
3512 * @remark Zero is a valid value for many window and context related
3513 * attributes so you cannot use a return value of zero as an indication of
3514 * errors. However, this function should not fail as long as it is passed
3515 * valid arguments and the library has been [initialized](@ref intro_init).
3516 *
3517 * @thread_safety This function must only be called from the main thread.
3518 *
3519 * @sa @ref window_attribs
3520 * @sa @ref glfwSetWindowAttrib
3521 *
3522 * @since Added in version 3.0. Replaces `glfwGetWindowParam` and
3523 * `glfwGetGLVersion`.
3524 *
3525 * @ingroup window
3526 */
3527GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib);
3528
3529/*! @brief Sets an attribute of the specified window.
3530 *
3531 * This function sets the value of an attribute of the specified window.
3532 *
3533 * The supported attributes are [GLFW_DECORATED](@ref GLFW_DECORATED_attrib),
3534 * [GLFW_RESIZABLE](@ref GLFW_RESIZABLE_attrib),
3535 * [GLFW_FLOATING](@ref GLFW_FLOATING_attrib),
3536 * [GLFW_AUTO_ICONIFY](@ref GLFW_AUTO_ICONIFY_attrib) and
3537 * [GLFW_FOCUS_ON_SHOW](@ref GLFW_FOCUS_ON_SHOW_attrib).
3538 *
3539 * Some of these attributes are ignored for full screen windows. The new
3540 * value will take effect if the window is later made windowed.
3541 *
3542 * Some of these attributes are ignored for windowed mode windows. The new
3543 * value will take effect if the window is later made full screen.
3544 *
3545 * @param[in] window The window to set the attribute for.
3546 * @param[in] attrib A supported window attribute.
3547 * @param[in] value `GLFW_TRUE` or `GLFW_FALSE`.
3548 *
3549 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
3550 * GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
3551 *
3552 * @remark Calling @ref glfwGetWindowAttrib will always return the latest
3553 * value, even if that value is ignored by the current mode of the window.
3554 *
3555 * @thread_safety This function must only be called from the main thread.
3556 *
3557 * @sa @ref window_attribs
3558 * @sa @ref glfwGetWindowAttrib
3559 *
3560 * @since Added in version 3.3.
3561 *
3562 * @ingroup window
3563 */
3564GLFWAPI void glfwSetWindowAttrib(GLFWwindow* window, int attrib, int value);
3565
3566/*! @brief Sets the user pointer of the specified window.
3567 *
3568 * This function sets the user-defined pointer of the specified window. The
3569 * current value is retained until the window is destroyed. The initial value
3570 * is `NULL`.
3571 *
3572 * @param[in] window The window whose pointer to set.
3573 * @param[in] pointer The new value.
3574 *
3575 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3576 *
3577 * @thread_safety This function may be called from any thread. Access is not
3578 * synchronized.
3579 *
3580 * @sa @ref window_userptr
3581 * @sa @ref glfwGetWindowUserPointer
3582 *
3583 * @since Added in version 3.0.
3584 *
3585 * @ingroup window
3586 */
3587GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer);
3588
3589/*! @brief Returns the user pointer of the specified window.
3590 *
3591 * This function returns the current value of the user-defined pointer of the
3592 * specified window. The initial value is `NULL`.
3593 *
3594 * @param[in] window The window whose pointer to return.
3595 *
3596 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3597 *
3598 * @thread_safety This function may be called from any thread. Access is not
3599 * synchronized.
3600 *
3601 * @sa @ref window_userptr
3602 * @sa @ref glfwSetWindowUserPointer
3603 *
3604 * @since Added in version 3.0.
3605 *
3606 * @ingroup window
3607 */
3608GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
3609
3610/*! @brief Sets the position callback for the specified window.
3611 *
3612 * This function sets the position callback of the specified window, which is
3613 * called when the window is moved. The callback is provided with the
3614 * position, in screen coordinates, of the upper-left corner of the content
3615 * area of the window.
3616 *
3617 * @param[in] window The window whose callback to set.
3618 * @param[in] callback The new callback, or `NULL` to remove the currently set
3619 * callback.
3620 * @return The previously set callback, or `NULL` if no callback was set or the
3621 * library had not been [initialized](@ref intro_init).
3622 *
3623 * @callback_signature
3624 * @code
3625 * void function_name(GLFWwindow* window, int xpos, int ypos)
3626 * @endcode
3627 * For more information about the callback parameters, see the
3628 * [function pointer type](@ref GLFWwindowposfun).
3629 *
3630 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3631 *
3632 * @remark @wayland This callback will never be called, as there is no way for
3633 * an application to know its global position.
3634 *
3635 * @thread_safety This function must only be called from the main thread.
3636 *
3637 * @sa @ref window_pos
3638 *
3639 * @since Added in version 3.0.
3640 *
3641 * @ingroup window
3642 */
3643GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun callback);
3644
3645/*! @brief Sets the size callback for the specified window.
3646 *
3647 * This function sets the size callback of the specified window, which is
3648 * called when the window is resized. The callback is provided with the size,
3649 * in screen coordinates, of the content area of the window.
3650 *
3651 * @param[in] window The window whose callback to set.
3652 * @param[in] callback The new callback, or `NULL` to remove the currently set
3653 * callback.
3654 * @return The previously set callback, or `NULL` if no callback was set or the
3655 * library had not been [initialized](@ref intro_init).
3656 *
3657 * @callback_signature
3658 * @code
3659 * void function_name(GLFWwindow* window, int width, int height)
3660 * @endcode
3661 * For more information about the callback parameters, see the
3662 * [function pointer type](@ref GLFWwindowsizefun).
3663 *
3664 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3665 *
3666 * @thread_safety This function must only be called from the main thread.
3667 *
3668 * @sa @ref window_size
3669 *
3670 * @since Added in version 1.0.
3671 * @glfw3 Added window handle parameter and return value.
3672 *
3673 * @ingroup window
3674 */
3675GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun callback);
3676
3677/*! @brief Sets the close callback for the specified window.
3678 *
3679 * This function sets the close callback of the specified window, which is
3680 * called when the user attempts to close the window, for example by clicking
3681 * the close widget in the title bar.
3682 *
3683 * The close flag is set before this callback is called, but you can modify it
3684 * at any time with @ref glfwSetWindowShouldClose.
3685 *
3686 * The close callback is not triggered by @ref glfwDestroyWindow.
3687 *
3688 * @param[in] window The window whose callback to set.
3689 * @param[in] callback The new callback, or `NULL` to remove the currently set
3690 * callback.
3691 * @return The previously set callback, or `NULL` if no callback was set or the
3692 * library had not been [initialized](@ref intro_init).
3693 *
3694 * @callback_signature
3695 * @code
3696 * void function_name(GLFWwindow* window)
3697 * @endcode
3698 * For more information about the callback parameters, see the
3699 * [function pointer type](@ref GLFWwindowclosefun).
3700 *
3701 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3702 *
3703 * @remark @macos Selecting Quit from the application menu will trigger the
3704 * close callback for all windows.
3705 *
3706 * @thread_safety This function must only be called from the main thread.
3707 *
3708 * @sa @ref window_close
3709 *
3710 * @since Added in version 2.5.
3711 * @glfw3 Added window handle parameter and return value.
3712 *
3713 * @ingroup window
3714 */
3715GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun callback);
3716
3717/*! @brief Sets the refresh callback for the specified window.
3718 *
3719 * This function sets the refresh callback of the specified window, which is
3720 * called when the content area of the window needs to be redrawn, for example
3721 * if the window has been exposed after having been covered by another window.
3722 *
3723 * On compositing window systems such as Aero, Compiz, Aqua or Wayland, where
3724 * the window contents are saved off-screen, this callback may be called only
3725 * very infrequently or never at all.
3726 *
3727 * @param[in] window The window whose callback to set.
3728 * @param[in] callback The new callback, or `NULL` to remove the currently set
3729 * callback.
3730 * @return The previously set callback, or `NULL` if no callback was set or the
3731 * library had not been [initialized](@ref intro_init).
3732 *
3733 * @callback_signature
3734 * @code
3735 * void function_name(GLFWwindow* window);
3736 * @endcode
3737 * For more information about the callback parameters, see the
3738 * [function pointer type](@ref GLFWwindowrefreshfun).
3739 *
3740 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3741 *
3742 * @thread_safety This function must only be called from the main thread.
3743 *
3744 * @sa @ref window_refresh
3745 *
3746 * @since Added in version 2.5.
3747 * @glfw3 Added window handle parameter and return value.
3748 *
3749 * @ingroup window
3750 */
3751GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun callback);
3752
3753/*! @brief Sets the focus callback for the specified window.
3754 *
3755 * This function sets the focus callback of the specified window, which is
3756 * called when the window gains or loses input focus.
3757 *
3758 * After the focus callback is called for a window that lost input focus,
3759 * synthetic key and mouse button release events will be generated for all such
3760 * that had been pressed. For more information, see @ref glfwSetKeyCallback
3761 * and @ref glfwSetMouseButtonCallback.
3762 *
3763 * @param[in] window The window whose callback to set.
3764 * @param[in] callback The new callback, or `NULL` to remove the currently set
3765 * callback.
3766 * @return The previously set callback, or `NULL` if no callback was set or the
3767 * library had not been [initialized](@ref intro_init).
3768 *
3769 * @callback_signature
3770 * @code
3771 * void function_name(GLFWwindow* window, int focused)
3772 * @endcode
3773 * For more information about the callback parameters, see the
3774 * [function pointer type](@ref GLFWwindowfocusfun).
3775 *
3776 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3777 *
3778 * @thread_safety This function must only be called from the main thread.
3779 *
3780 * @sa @ref window_focus
3781 *
3782 * @since Added in version 3.0.
3783 *
3784 * @ingroup window
3785 */
3786GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun callback);
3787
3788/*! @brief Sets the iconify callback for the specified window.
3789 *
3790 * This function sets the iconification callback of the specified window, which
3791 * is called when the window is iconified or restored.
3792 *
3793 * @param[in] window The window whose callback to set.
3794 * @param[in] callback The new callback, or `NULL` to remove the currently set
3795 * callback.
3796 * @return The previously set callback, or `NULL` if no callback was set or the
3797 * library had not been [initialized](@ref intro_init).
3798 *
3799 * @callback_signature
3800 * @code
3801 * void function_name(GLFWwindow* window, int iconified)
3802 * @endcode
3803 * For more information about the callback parameters, see the
3804 * [function pointer type](@ref GLFWwindowiconifyfun).
3805 *
3806 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3807 *
3808 * @remark @wayland The wl_shell protocol has no concept of iconification,
3809 * this callback will never be called when using this deprecated protocol.
3810 *
3811 * @thread_safety This function must only be called from the main thread.
3812 *
3813 * @sa @ref window_iconify
3814 *
3815 * @since Added in version 3.0.
3816 *
3817 * @ingroup window
3818 */
3819GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun callback);
3820
3821/*! @brief Sets the maximize callback for the specified window.
3822 *
3823 * This function sets the maximization callback of the specified window, which
3824 * is called when the window is maximized or restored.
3825 *
3826 * @param[in] window The window whose callback to set.
3827 * @param[in] callback The new callback, or `NULL` to remove the currently set
3828 * callback.
3829 * @return The previously set callback, or `NULL` if no callback was set or the
3830 * library had not been [initialized](@ref intro_init).
3831 *
3832 * @callback_signature
3833 * @code
3834 * void function_name(GLFWwindow* window, int maximized)
3835 * @endcode
3836 * For more information about the callback parameters, see the
3837 * [function pointer type](@ref GLFWwindowmaximizefun).
3838 *
3839 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3840 *
3841 * @thread_safety This function must only be called from the main thread.
3842 *
3843 * @sa @ref window_maximize
3844 *
3845 * @since Added in version 3.3.
3846 *
3847 * @ingroup window
3848 */
3849GLFWAPI GLFWwindowmaximizefun glfwSetWindowMaximizeCallback(GLFWwindow* window, GLFWwindowmaximizefun callback);
3850
3851/*! @brief Sets the framebuffer resize callback for the specified window.
3852 *
3853 * This function sets the framebuffer resize callback of the specified window,
3854 * which is called when the framebuffer of the specified window is resized.
3855 *
3856 * @param[in] window The window whose callback to set.
3857 * @param[in] callback The new callback, or `NULL` to remove the currently set
3858 * callback.
3859 * @return The previously set callback, or `NULL` if no callback was set or the
3860 * library had not been [initialized](@ref intro_init).
3861 *
3862 * @callback_signature
3863 * @code
3864 * void function_name(GLFWwindow* window, int width, int height)
3865 * @endcode
3866 * For more information about the callback parameters, see the
3867 * [function pointer type](@ref GLFWframebuffersizefun).
3868 *
3869 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3870 *
3871 * @thread_safety This function must only be called from the main thread.
3872 *
3873 * @sa @ref window_fbsize
3874 *
3875 * @since Added in version 3.0.
3876 *
3877 * @ingroup window
3878 */
3879GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun callback);
3880
3881/*! @brief Sets the window content scale callback for the specified window.
3882 *
3883 * This function sets the window content scale callback of the specified window,
3884 * which is called when the content scale of the specified window changes.
3885 *
3886 * @param[in] window The window whose callback to set.
3887 * @param[in] callback The new callback, or `NULL` to remove the currently set
3888 * callback.
3889 * @return The previously set callback, or `NULL` if no callback was set or the
3890 * library had not been [initialized](@ref intro_init).
3891 *
3892 * @callback_signature
3893 * @code
3894 * void function_name(GLFWwindow* window, float xscale, float yscale)
3895 * @endcode
3896 * For more information about the callback parameters, see the
3897 * [function pointer type](@ref GLFWwindowcontentscalefun).
3898 *
3899 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
3900 *
3901 * @thread_safety This function must only be called from the main thread.
3902 *
3903 * @sa @ref window_scale
3904 * @sa @ref glfwGetWindowContentScale
3905 *
3906 * @since Added in version 3.3.
3907 *
3908 * @ingroup window
3909 */
3910GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow* window, GLFWwindowcontentscalefun callback);
3911
3912/*! @brief Processes all pending events.
3913 *
3914 * This function processes only those events that are already in the event
3915 * queue and then returns immediately. Processing events will cause the window
3916 * and input callbacks associated with those events to be called.
3917 *
3918 * On some platforms, a window move, resize or menu operation will cause event
3919 * processing to block. This is due to how event processing is designed on
3920 * those platforms. You can use the
3921 * [window refresh callback](@ref window_refresh) to redraw the contents of
3922 * your window when necessary during such operations.
3923 *
3924 * Do not assume that callbacks you set will _only_ be called in response to
3925 * event processing functions like this one. While it is necessary to poll for
3926 * events, window systems that require GLFW to register callbacks of its own
3927 * can pass events to GLFW in response to many window system function calls.
3928 * GLFW will pass those events on to the application callbacks before
3929 * returning.
3930 *
3931 * Event processing is not required for joystick input to work.
3932 *
3933 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3934 * GLFW_PLATFORM_ERROR.
3935 *
3936 * @reentrancy This function must not be called from a callback.
3937 *
3938 * @thread_safety This function must only be called from the main thread.
3939 *
3940 * @sa @ref events
3941 * @sa @ref glfwWaitEvents
3942 * @sa @ref glfwWaitEventsTimeout
3943 *
3944 * @since Added in version 1.0.
3945 *
3946 * @ingroup window
3947 */
3948GLFWAPI void glfwPollEvents(void);
3949
3950/*! @brief Waits until events are queued and processes them.
3951 *
3952 * This function puts the calling thread to sleep until at least one event is
3953 * available in the event queue. Once one or more events are available,
3954 * it behaves exactly like @ref glfwPollEvents, i.e. the events in the queue
3955 * are processed and the function then returns immediately. Processing events
3956 * will cause the window and input callbacks associated with those events to be
3957 * called.
3958 *
3959 * Since not all events are associated with callbacks, this function may return
3960 * without a callback having been called even if you are monitoring all
3961 * callbacks.
3962 *
3963 * On some platforms, a window move, resize or menu operation will cause event
3964 * processing to block. This is due to how event processing is designed on
3965 * those platforms. You can use the
3966 * [window refresh callback](@ref window_refresh) to redraw the contents of
3967 * your window when necessary during such operations.
3968 *
3969 * Do not assume that callbacks you set will _only_ be called in response to
3970 * event processing functions like this one. While it is necessary to poll for
3971 * events, window systems that require GLFW to register callbacks of its own
3972 * can pass events to GLFW in response to many window system function calls.
3973 * GLFW will pass those events on to the application callbacks before
3974 * returning.
3975 *
3976 * Event processing is not required for joystick input to work.
3977 *
3978 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
3979 * GLFW_PLATFORM_ERROR.
3980 *
3981 * @reentrancy This function must not be called from a callback.
3982 *
3983 * @thread_safety This function must only be called from the main thread.
3984 *
3985 * @sa @ref events
3986 * @sa @ref glfwPollEvents
3987 * @sa @ref glfwWaitEventsTimeout
3988 *
3989 * @since Added in version 2.5.
3990 *
3991 * @ingroup window
3992 */
3993GLFWAPI void glfwWaitEvents(void);
3994
3995/*! @brief Waits with timeout until events are queued and processes them.
3996 *
3997 * This function puts the calling thread to sleep until at least one event is
3998 * available in the event queue, or until the specified timeout is reached. If
3999 * one or more events are available, it behaves exactly like @ref
4000 * glfwPollEvents, i.e. the events in the queue are processed and the function
4001 * then returns immediately. Processing events will cause the window and input
4002 * callbacks associated with those events to be called.
4003 *
4004 * The timeout value must be a positive finite number.
4005 *
4006 * Since not all events are associated with callbacks, this function may return
4007 * without a callback having been called even if you are monitoring all
4008 * callbacks.
4009 *
4010 * On some platforms, a window move, resize or menu operation will cause event
4011 * processing to block. This is due to how event processing is designed on
4012 * those platforms. You can use the
4013 * [window refresh callback](@ref window_refresh) to redraw the contents of
4014 * your window when necessary during such operations.
4015 *
4016 * Do not assume that callbacks you set will _only_ be called in response to
4017 * event processing functions like this one. While it is necessary to poll for
4018 * events, window systems that require GLFW to register callbacks of its own
4019 * can pass events to GLFW in response to many window system function calls.
4020 * GLFW will pass those events on to the application callbacks before
4021 * returning.
4022 *
4023 * Event processing is not required for joystick input to work.
4024 *
4025 * @param[in] timeout The maximum amount of time, in seconds, to wait.
4026 *
4027 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4028 * GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
4029 *
4030 * @reentrancy This function must not be called from a callback.
4031 *
4032 * @thread_safety This function must only be called from the main thread.
4033 *
4034 * @sa @ref events
4035 * @sa @ref glfwPollEvents
4036 * @sa @ref glfwWaitEvents
4037 *
4038 * @since Added in version 3.2.
4039 *
4040 * @ingroup window
4041 */
4042GLFWAPI void glfwWaitEventsTimeout(double timeout);
4043
4044/*! @brief Posts an empty event to the event queue.
4045 *
4046 * This function posts an empty event from the current thread to the event
4047 * queue, causing @ref glfwWaitEvents or @ref glfwWaitEventsTimeout to return.
4048 *
4049 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4050 * GLFW_PLATFORM_ERROR.
4051 *
4052 * @thread_safety This function may be called from any thread.
4053 *
4054 * @sa @ref events
4055 * @sa @ref glfwWaitEvents
4056 * @sa @ref glfwWaitEventsTimeout
4057 *
4058 * @since Added in version 3.1.
4059 *
4060 * @ingroup window
4061 */
4062GLFWAPI void glfwPostEmptyEvent(void);
4063
4064/*! @brief Returns the value of an input option for the specified window.
4065 *
4066 * This function returns the value of an input option for the specified window.
4067 * The mode must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS,
4068 * @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or
4069 * @ref GLFW_RAW_MOUSE_MOTION.
4070 *
4071 * @param[in] window The window to query.
4072 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`,
4073 * `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or
4074 * `GLFW_RAW_MOUSE_MOTION`.
4075 *
4076 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4077 * GLFW_INVALID_ENUM.
4078 *
4079 * @thread_safety This function must only be called from the main thread.
4080 *
4081 * @sa @ref glfwSetInputMode
4082 *
4083 * @since Added in version 3.0.
4084 *
4085 * @ingroup input
4086 */
4087GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
4088
4089/*! @brief Sets an input option for the specified window.
4090 *
4091 * This function sets an input mode option for the specified window. The mode
4092 * must be one of @ref GLFW_CURSOR, @ref GLFW_STICKY_KEYS,
4093 * @ref GLFW_STICKY_MOUSE_BUTTONS, @ref GLFW_LOCK_KEY_MODS or
4094 * @ref GLFW_RAW_MOUSE_MOTION.
4095 *
4096 * If the mode is `GLFW_CURSOR`, the value must be one of the following cursor
4097 * modes:
4098 * - `GLFW_CURSOR_NORMAL` makes the cursor visible and behaving normally.
4099 * - `GLFW_CURSOR_HIDDEN` makes the cursor invisible when it is over the
4100 * content area of the window but does not restrict the cursor from leaving.
4101 * - `GLFW_CURSOR_DISABLED` hides and grabs the cursor, providing virtual
4102 * and unlimited cursor movement. This is useful for implementing for
4103 * example 3D camera controls.
4104 *
4105 * If the mode is `GLFW_STICKY_KEYS`, the value must be either `GLFW_TRUE` to
4106 * enable sticky keys, or `GLFW_FALSE` to disable it. If sticky keys are
4107 * enabled, a key press will ensure that @ref glfwGetKey returns `GLFW_PRESS`
4108 * the next time it is called even if the key had been released before the
4109 * call. This is useful when you are only interested in whether keys have been
4110 * pressed but not when or in which order.
4111 *
4112 * If the mode is `GLFW_STICKY_MOUSE_BUTTONS`, the value must be either
4113 * `GLFW_TRUE` to enable sticky mouse buttons, or `GLFW_FALSE` to disable it.
4114 * If sticky mouse buttons are enabled, a mouse button press will ensure that
4115 * @ref glfwGetMouseButton returns `GLFW_PRESS` the next time it is called even
4116 * if the mouse button had been released before the call. This is useful when
4117 * you are only interested in whether mouse buttons have been pressed but not
4118 * when or in which order.
4119 *
4120 * If the mode is `GLFW_LOCK_KEY_MODS`, the value must be either `GLFW_TRUE` to
4121 * enable lock key modifier bits, or `GLFW_FALSE` to disable them. If enabled,
4122 * callbacks that receive modifier bits will also have the @ref
4123 * GLFW_MOD_CAPS_LOCK bit set when the event was generated with Caps Lock on,
4124 * and the @ref GLFW_MOD_NUM_LOCK bit when Num Lock was on.
4125 *
4126 * If the mode is `GLFW_RAW_MOUSE_MOTION`, the value must be either `GLFW_TRUE`
4127 * to enable raw (unscaled and unaccelerated) mouse motion when the cursor is
4128 * disabled, or `GLFW_FALSE` to disable it. If raw motion is not supported,
4129 * attempting to set this will emit @ref GLFW_PLATFORM_ERROR. Call @ref
4130 * glfwRawMouseMotionSupported to check for support.
4131 *
4132 * @param[in] window The window whose input mode to set.
4133 * @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS`,
4134 * `GLFW_STICKY_MOUSE_BUTTONS`, `GLFW_LOCK_KEY_MODS` or
4135 * `GLFW_RAW_MOUSE_MOTION`.
4136 * @param[in] value The new value of the specified input mode.
4137 *
4138 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4139 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4140 *
4141 * @thread_safety This function must only be called from the main thread.
4142 *
4143 * @sa @ref glfwGetInputMode
4144 *
4145 * @since Added in version 3.0. Replaces `glfwEnable` and `glfwDisable`.
4146 *
4147 * @ingroup input
4148 */
4149GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
4150
4151/*! @brief Returns whether raw mouse motion is supported.
4152 *
4153 * This function returns whether raw mouse motion is supported on the current
4154 * system. This status does not change after GLFW has been initialized so you
4155 * only need to check this once. If you attempt to enable raw motion on
4156 * a system that does not support it, @ref GLFW_PLATFORM_ERROR will be emitted.
4157 *
4158 * Raw mouse motion is closer to the actual motion of the mouse across
4159 * a surface. It is not affected by the scaling and acceleration applied to
4160 * the motion of the desktop cursor. That processing is suitable for a cursor
4161 * while raw motion is better for controlling for example a 3D camera. Because
4162 * of this, raw mouse motion is only provided when the cursor is disabled.
4163 *
4164 * @return `GLFW_TRUE` if raw mouse motion is supported on the current machine,
4165 * or `GLFW_FALSE` otherwise.
4166 *
4167 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4168 *
4169 * @thread_safety This function must only be called from the main thread.
4170 *
4171 * @sa @ref raw_mouse_motion
4172 * @sa @ref glfwSetInputMode
4173 *
4174 * @since Added in version 3.3.
4175 *
4176 * @ingroup input
4177 */
4178GLFWAPI int glfwRawMouseMotionSupported(void);
4179
4180/*! @brief Returns the layout-specific name of the specified printable key.
4181 *
4182 * This function returns the name of the specified printable key, encoded as
4183 * UTF-8. This is typically the character that key would produce without any
4184 * modifier keys, intended for displaying key bindings to the user. For dead
4185 * keys, it is typically the diacritic it would add to a character.
4186 *
4187 * __Do not use this function__ for [text input](@ref input_char). You will
4188 * break text input for many languages even if it happens to work for yours.
4189 *
4190 * If the key is `GLFW_KEY_UNKNOWN`, the scancode is used to identify the key,
4191 * otherwise the scancode is ignored. If you specify a non-printable key, or
4192 * `GLFW_KEY_UNKNOWN` and a scancode that maps to a non-printable key, this
4193 * function returns `NULL` but does not emit an error.
4194 *
4195 * This behavior allows you to always pass in the arguments in the
4196 * [key callback](@ref input_key) without modification.
4197 *
4198 * The printable keys are:
4199 * - `GLFW_KEY_APOSTROPHE`
4200 * - `GLFW_KEY_COMMA`
4201 * - `GLFW_KEY_MINUS`
4202 * - `GLFW_KEY_PERIOD`
4203 * - `GLFW_KEY_SLASH`
4204 * - `GLFW_KEY_SEMICOLON`
4205 * - `GLFW_KEY_EQUAL`
4206 * - `GLFW_KEY_LEFT_BRACKET`
4207 * - `GLFW_KEY_RIGHT_BRACKET`
4208 * - `GLFW_KEY_BACKSLASH`
4209 * - `GLFW_KEY_WORLD_1`
4210 * - `GLFW_KEY_WORLD_2`
4211 * - `GLFW_KEY_0` to `GLFW_KEY_9`
4212 * - `GLFW_KEY_A` to `GLFW_KEY_Z`
4213 * - `GLFW_KEY_KP_0` to `GLFW_KEY_KP_9`
4214 * - `GLFW_KEY_KP_DECIMAL`
4215 * - `GLFW_KEY_KP_DIVIDE`
4216 * - `GLFW_KEY_KP_MULTIPLY`
4217 * - `GLFW_KEY_KP_SUBTRACT`
4218 * - `GLFW_KEY_KP_ADD`
4219 * - `GLFW_KEY_KP_EQUAL`
4220 *
4221 * Names for printable keys depend on keyboard layout, while names for
4222 * non-printable keys are the same across layouts but depend on the application
4223 * language and should be localized along with other user interface text.
4224 *
4225 * @param[in] key The key to query, or `GLFW_KEY_UNKNOWN`.
4226 * @param[in] scancode The scancode of the key to query.
4227 * @return The UTF-8 encoded, layout-specific name of the key, or `NULL`.
4228 *
4229 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4230 * GLFW_PLATFORM_ERROR.
4231 *
4232 * @remark The contents of the returned string may change when a keyboard
4233 * layout change event is received.
4234 *
4235 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
4236 * should not free it yourself. It is valid until the library is terminated.
4237 *
4238 * @thread_safety This function must only be called from the main thread.
4239 *
4240 * @sa @ref input_key_name
4241 *
4242 * @since Added in version 3.2.
4243 *
4244 * @ingroup input
4245 */
4246GLFWAPI const char* glfwGetKeyName(int key, int scancode);
4247
4248/*! @brief Returns the platform-specific scancode of the specified key.
4249 *
4250 * This function returns the platform-specific scancode of the specified key.
4251 *
4252 * If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
4253 * method will return `-1`.
4254 *
4255 * @param[in] key Any [named key](@ref keys).
4256 * @return The platform-specific scancode for the key, or `-1` if an
4257 * [error](@ref error_handling) occurred.
4258 *
4259 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4260 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4261 *
4262 * @thread_safety This function may be called from any thread.
4263 *
4264 * @sa @ref input_key
4265 *
4266 * @since Added in version 3.3.
4267 *
4268 * @ingroup input
4269 */
4270GLFWAPI int glfwGetKeyScancode(int key);
4271
4272/*! @brief Returns the last reported state of a keyboard key for the specified
4273 * window.
4274 *
4275 * This function returns the last state reported for the specified key to the
4276 * specified window. The returned state is one of `GLFW_PRESS` or
4277 * `GLFW_RELEASE`. The higher-level action `GLFW_REPEAT` is only reported to
4278 * the key callback.
4279 *
4280 * If the @ref GLFW_STICKY_KEYS input mode is enabled, this function returns
4281 * `GLFW_PRESS` the first time you call it for a key that was pressed, even if
4282 * that key has already been released.
4283 *
4284 * The key functions deal with physical keys, with [key tokens](@ref keys)
4285 * named after their use on the standard US keyboard layout. If you want to
4286 * input text, use the Unicode character callback instead.
4287 *
4288 * The [modifier key bit masks](@ref mods) are not key tokens and cannot be
4289 * used with this function.
4290 *
4291 * __Do not use this function__ to implement [text input](@ref input_char).
4292 *
4293 * @param[in] window The desired window.
4294 * @param[in] key The desired [keyboard key](@ref keys). `GLFW_KEY_UNKNOWN` is
4295 * not a valid key for this function.
4296 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
4297 *
4298 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4299 * GLFW_INVALID_ENUM.
4300 *
4301 * @thread_safety This function must only be called from the main thread.
4302 *
4303 * @sa @ref input_key
4304 *
4305 * @since Added in version 1.0.
4306 * @glfw3 Added window handle parameter.
4307 *
4308 * @ingroup input
4309 */
4310GLFWAPI int glfwGetKey(GLFWwindow* window, int key);
4311
4312/*! @brief Returns the last reported state of a mouse button for the specified
4313 * window.
4314 *
4315 * This function returns the last state reported for the specified mouse button
4316 * to the specified window. The returned state is one of `GLFW_PRESS` or
4317 * `GLFW_RELEASE`.
4318 *
4319 * If the @ref GLFW_STICKY_MOUSE_BUTTONS input mode is enabled, this function
4320 * returns `GLFW_PRESS` the first time you call it for a mouse button that was
4321 * pressed, even if that mouse button has already been released.
4322 *
4323 * @param[in] window The desired window.
4324 * @param[in] button The desired [mouse button](@ref buttons).
4325 * @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
4326 *
4327 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4328 * GLFW_INVALID_ENUM.
4329 *
4330 * @thread_safety This function must only be called from the main thread.
4331 *
4332 * @sa @ref input_mouse_button
4333 *
4334 * @since Added in version 1.0.
4335 * @glfw3 Added window handle parameter.
4336 *
4337 * @ingroup input
4338 */
4339GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);
4340
4341/*! @brief Retrieves the position of the cursor relative to the content area of
4342 * the window.
4343 *
4344 * This function returns the position of the cursor, in screen coordinates,
4345 * relative to the upper-left corner of the content area of the specified
4346 * window.
4347 *
4348 * If the cursor is disabled (with `GLFW_CURSOR_DISABLED`) then the cursor
4349 * position is unbounded and limited only by the minimum and maximum values of
4350 * a `double`.
4351 *
4352 * The coordinate can be converted to their integer equivalents with the
4353 * `floor` function. Casting directly to an integer type works for positive
4354 * coordinates, but fails for negative ones.
4355 *
4356 * Any or all of the position arguments may be `NULL`. If an error occurs, all
4357 * non-`NULL` position arguments will be set to zero.
4358 *
4359 * @param[in] window The desired window.
4360 * @param[out] xpos Where to store the cursor x-coordinate, relative to the
4361 * left edge of the content area, or `NULL`.
4362 * @param[out] ypos Where to store the cursor y-coordinate, relative to the to
4363 * top edge of the content area, or `NULL`.
4364 *
4365 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4366 * GLFW_PLATFORM_ERROR.
4367 *
4368 * @thread_safety This function must only be called from the main thread.
4369 *
4370 * @sa @ref cursor_pos
4371 * @sa @ref glfwSetCursorPos
4372 *
4373 * @since Added in version 3.0. Replaces `glfwGetMousePos`.
4374 *
4375 * @ingroup input
4376 */
4377GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
4378
4379/*! @brief Sets the position of the cursor, relative to the content area of the
4380 * window.
4381 *
4382 * This function sets the position, in screen coordinates, of the cursor
4383 * relative to the upper-left corner of the content area of the specified
4384 * window. The window must have input focus. If the window does not have
4385 * input focus when this function is called, it fails silently.
4386 *
4387 * __Do not use this function__ to implement things like camera controls. GLFW
4388 * already provides the `GLFW_CURSOR_DISABLED` cursor mode that hides the
4389 * cursor, transparently re-centers it and provides unconstrained cursor
4390 * motion. See @ref glfwSetInputMode for more information.
4391 *
4392 * If the cursor mode is `GLFW_CURSOR_DISABLED` then the cursor position is
4393 * unconstrained and limited only by the minimum and maximum values of
4394 * a `double`.
4395 *
4396 * @param[in] window The desired window.
4397 * @param[in] xpos The desired x-coordinate, relative to the left edge of the
4398 * content area.
4399 * @param[in] ypos The desired y-coordinate, relative to the top edge of the
4400 * content area.
4401 *
4402 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4403 * GLFW_PLATFORM_ERROR.
4404 *
4405 * @remark @wayland This function will only work when the cursor mode is
4406 * `GLFW_CURSOR_DISABLED`, otherwise it will do nothing.
4407 *
4408 * @thread_safety This function must only be called from the main thread.
4409 *
4410 * @sa @ref cursor_pos
4411 * @sa @ref glfwGetCursorPos
4412 *
4413 * @since Added in version 3.0. Replaces `glfwSetMousePos`.
4414 *
4415 * @ingroup input
4416 */
4417GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
4418
4419/*! @brief Creates a custom cursor.
4420 *
4421 * Creates a new custom cursor image that can be set for a window with @ref
4422 * glfwSetCursor. The cursor can be destroyed with @ref glfwDestroyCursor.
4423 * Any remaining cursors are destroyed by @ref glfwTerminate.
4424 *
4425 * The pixels are 32-bit, little-endian, non-premultiplied RGBA, i.e. eight
4426 * bits per channel with the red channel first. They are arranged canonically
4427 * as packed sequential rows, starting from the top-left corner.
4428 *
4429 * The cursor hotspot is specified in pixels, relative to the upper-left corner
4430 * of the cursor image. Like all other coordinate systems in GLFW, the X-axis
4431 * points to the right and the Y-axis points down.
4432 *
4433 * @param[in] image The desired cursor image.
4434 * @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot.
4435 * @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot.
4436 * @return The handle of the created cursor, or `NULL` if an
4437 * [error](@ref error_handling) occurred.
4438 *
4439 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4440 * GLFW_PLATFORM_ERROR.
4441 *
4442 * @pointer_lifetime The specified image data is copied before this function
4443 * returns.
4444 *
4445 * @thread_safety This function must only be called from the main thread.
4446 *
4447 * @sa @ref cursor_object
4448 * @sa @ref glfwDestroyCursor
4449 * @sa @ref glfwCreateStandardCursor
4450 *
4451 * @since Added in version 3.1.
4452 *
4453 * @ingroup input
4454 */
4455GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot);
4456
4457/*! @brief Creates a cursor with a standard shape.
4458 *
4459 * Returns a cursor with a [standard shape](@ref shapes), that can be set for
4460 * a window with @ref glfwSetCursor.
4461 *
4462 * @param[in] shape One of the [standard shapes](@ref shapes).
4463 * @return A new cursor ready to use or `NULL` if an
4464 * [error](@ref error_handling) occurred.
4465 *
4466 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4467 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4468 *
4469 * @thread_safety This function must only be called from the main thread.
4470 *
4471 * @sa @ref cursor_object
4472 * @sa @ref glfwCreateCursor
4473 *
4474 * @since Added in version 3.1.
4475 *
4476 * @ingroup input
4477 */
4478GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape);
4479
4480/*! @brief Destroys a cursor.
4481 *
4482 * This function destroys a cursor previously created with @ref
4483 * glfwCreateCursor. Any remaining cursors will be destroyed by @ref
4484 * glfwTerminate.
4485 *
4486 * If the specified cursor is current for any window, that window will be
4487 * reverted to the default cursor. This does not affect the cursor mode.
4488 *
4489 * @param[in] cursor The cursor object to destroy.
4490 *
4491 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4492 * GLFW_PLATFORM_ERROR.
4493 *
4494 * @reentrancy This function must not be called from a callback.
4495 *
4496 * @thread_safety This function must only be called from the main thread.
4497 *
4498 * @sa @ref cursor_object
4499 * @sa @ref glfwCreateCursor
4500 *
4501 * @since Added in version 3.1.
4502 *
4503 * @ingroup input
4504 */
4505GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor);
4506
4507/*! @brief Sets the cursor for the window.
4508 *
4509 * This function sets the cursor image to be used when the cursor is over the
4510 * content area of the specified window. The set cursor will only be visible
4511 * when the [cursor mode](@ref cursor_mode) of the window is
4512 * `GLFW_CURSOR_NORMAL`.
4513 *
4514 * On some platforms, the set cursor may not be visible unless the window also
4515 * has input focus.
4516 *
4517 * @param[in] window The window to set the cursor for.
4518 * @param[in] cursor The cursor to set, or `NULL` to switch back to the default
4519 * arrow cursor.
4520 *
4521 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
4522 * GLFW_PLATFORM_ERROR.
4523 *
4524 * @thread_safety This function must only be called from the main thread.
4525 *
4526 * @sa @ref cursor_object
4527 *
4528 * @since Added in version 3.1.
4529 *
4530 * @ingroup input
4531 */
4532GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
4533
4534/*! @brief Sets the key callback.
4535 *
4536 * This function sets the key callback of the specified window, which is called
4537 * when a key is pressed, repeated or released.
4538 *
4539 * The key functions deal with physical keys, with layout independent
4540 * [key tokens](@ref keys) named after their values in the standard US keyboard
4541 * layout. If you want to input text, use the
4542 * [character callback](@ref glfwSetCharCallback) instead.
4543 *
4544 * When a window loses input focus, it will generate synthetic key release
4545 * events for all pressed keys. You can tell these events from user-generated
4546 * events by the fact that the synthetic ones are generated after the focus
4547 * loss event has been processed, i.e. after the
4548 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
4549 *
4550 * The scancode of a key is specific to that platform or sometimes even to that
4551 * machine. Scancodes are intended to allow users to bind keys that don't have
4552 * a GLFW key token. Such keys have `key` set to `GLFW_KEY_UNKNOWN`, their
4553 * state is not saved and so it cannot be queried with @ref glfwGetKey.
4554 *
4555 * Sometimes GLFW needs to generate synthetic key events, in which case the
4556 * scancode may be zero.
4557 *
4558 * @param[in] window The window whose callback to set.
4559 * @param[in] callback The new key callback, or `NULL` to remove the currently
4560 * set callback.
4561 * @return The previously set callback, or `NULL` if no callback was set or the
4562 * library had not been [initialized](@ref intro_init).
4563 *
4564 * @callback_signature
4565 * @code
4566 * void function_name(GLFWwindow* window, int key, int scancode, int action, int mods)
4567 * @endcode
4568 * For more information about the callback parameters, see the
4569 * [function pointer type](@ref GLFWkeyfun).
4570 *
4571 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4572 *
4573 * @thread_safety This function must only be called from the main thread.
4574 *
4575 * @sa @ref input_key
4576 *
4577 * @since Added in version 1.0.
4578 * @glfw3 Added window handle parameter and return value.
4579 *
4580 * @ingroup input
4581 */
4582GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun callback);
4583
4584/*! @brief Sets the Unicode character callback.
4585 *
4586 * This function sets the character callback of the specified window, which is
4587 * called when a Unicode character is input.
4588 *
4589 * The character callback is intended for Unicode text input. As it deals with
4590 * characters, it is keyboard layout dependent, whereas the
4591 * [key callback](@ref glfwSetKeyCallback) is not. Characters do not map 1:1
4592 * to physical keys, as a key may produce zero, one or more characters. If you
4593 * want to know whether a specific physical key was pressed or released, see
4594 * the key callback instead.
4595 *
4596 * The character callback behaves as system text input normally does and will
4597 * not be called if modifier keys are held down that would prevent normal text
4598 * input on that platform, for example a Super (Command) key on macOS or Alt key
4599 * on Windows.
4600 *
4601 * @param[in] window The window whose callback to set.
4602 * @param[in] callback The new callback, or `NULL` to remove the currently set
4603 * callback.
4604 * @return The previously set callback, or `NULL` if no callback was set or the
4605 * library had not been [initialized](@ref intro_init).
4606 *
4607 * @callback_signature
4608 * @code
4609 * void function_name(GLFWwindow* window, unsigned int codepoint)
4610 * @endcode
4611 * For more information about the callback parameters, see the
4612 * [function pointer type](@ref GLFWcharfun).
4613 *
4614 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4615 *
4616 * @thread_safety This function must only be called from the main thread.
4617 *
4618 * @sa @ref input_char
4619 *
4620 * @since Added in version 2.4.
4621 * @glfw3 Added window handle parameter and return value.
4622 *
4623 * @ingroup input
4624 */
4625GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun callback);
4626
4627/*! @brief Sets the Unicode character with modifiers callback.
4628 *
4629 * This function sets the character with modifiers callback of the specified
4630 * window, which is called when a Unicode character is input regardless of what
4631 * modifier keys are used.
4632 *
4633 * The character with modifiers callback is intended for implementing custom
4634 * Unicode character input. For regular Unicode text input, see the
4635 * [character callback](@ref glfwSetCharCallback). Like the character
4636 * callback, the character with modifiers callback deals with characters and is
4637 * keyboard layout dependent. Characters do not map 1:1 to physical keys, as
4638 * a key may produce zero, one or more characters. If you want to know whether
4639 * a specific physical key was pressed or released, see the
4640 * [key callback](@ref glfwSetKeyCallback) instead.
4641 *
4642 * @param[in] window The window whose callback to set.
4643 * @param[in] callback The new callback, or `NULL` to remove the currently set
4644 * callback.
4645 * @return The previously set callback, or `NULL` if no callback was set or an
4646 * [error](@ref error_handling) occurred.
4647 *
4648 * @callback_signature
4649 * @code
4650 * void function_name(GLFWwindow* window, unsigned int codepoint, int mods)
4651 * @endcode
4652 * For more information about the callback parameters, see the
4653 * [function pointer type](@ref GLFWcharmodsfun).
4654 *
4655 * @deprecated Scheduled for removal in version 4.0.
4656 *
4657 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4658 *
4659 * @thread_safety This function must only be called from the main thread.
4660 *
4661 * @sa @ref input_char
4662 *
4663 * @since Added in version 3.1.
4664 *
4665 * @ingroup input
4666 */
4667GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmodsfun callback);
4668
4669/*! @brief Sets the mouse button callback.
4670 *
4671 * This function sets the mouse button callback of the specified window, which
4672 * is called when a mouse button is pressed or released.
4673 *
4674 * When a window loses input focus, it will generate synthetic mouse button
4675 * release events for all pressed mouse buttons. You can tell these events
4676 * from user-generated events by the fact that the synthetic ones are generated
4677 * after the focus loss event has been processed, i.e. after the
4678 * [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
4679 *
4680 * @param[in] window The window whose callback to set.
4681 * @param[in] callback The new callback, or `NULL` to remove the currently set
4682 * callback.
4683 * @return The previously set callback, or `NULL` if no callback was set or the
4684 * library had not been [initialized](@ref intro_init).
4685 *
4686 * @callback_signature
4687 * @code
4688 * void function_name(GLFWwindow* window, int button, int action, int mods)
4689 * @endcode
4690 * For more information about the callback parameters, see the
4691 * [function pointer type](@ref GLFWmousebuttonfun).
4692 *
4693 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4694 *
4695 * @thread_safety This function must only be called from the main thread.
4696 *
4697 * @sa @ref input_mouse_button
4698 *
4699 * @since Added in version 1.0.
4700 * @glfw3 Added window handle parameter and return value.
4701 *
4702 * @ingroup input
4703 */
4704GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmousebuttonfun callback);
4705
4706/*! @brief Sets the cursor position callback.
4707 *
4708 * This function sets the cursor position callback of the specified window,
4709 * which is called when the cursor is moved. The callback is provided with the
4710 * position, in screen coordinates, relative to the upper-left corner of the
4711 * content area of the window.
4712 *
4713 * @param[in] window The window whose callback to set.
4714 * @param[in] callback The new callback, or `NULL` to remove the currently set
4715 * callback.
4716 * @return The previously set callback, or `NULL` if no callback was set or the
4717 * library had not been [initialized](@ref intro_init).
4718 *
4719 * @callback_signature
4720 * @code
4721 * void function_name(GLFWwindow* window, double xpos, double ypos);
4722 * @endcode
4723 * For more information about the callback parameters, see the
4724 * [function pointer type](@ref GLFWcursorposfun).
4725 *
4726 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4727 *
4728 * @thread_safety This function must only be called from the main thread.
4729 *
4730 * @sa @ref cursor_pos
4731 *
4732 * @since Added in version 3.0. Replaces `glfwSetMousePosCallback`.
4733 *
4734 * @ingroup input
4735 */
4736GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursorposfun callback);
4737
4738/*! @brief Sets the cursor enter/leave callback.
4739 *
4740 * This function sets the cursor boundary crossing callback of the specified
4741 * window, which is called when the cursor enters or leaves the content area of
4742 * the window.
4743 *
4744 * @param[in] window The window whose callback to set.
4745 * @param[in] callback The new callback, or `NULL` to remove the currently set
4746 * callback.
4747 * @return The previously set callback, or `NULL` if no callback was set or the
4748 * library had not been [initialized](@ref intro_init).
4749 *
4750 * @callback_signature
4751 * @code
4752 * void function_name(GLFWwindow* window, int entered)
4753 * @endcode
4754 * For more information about the callback parameters, see the
4755 * [function pointer type](@ref GLFWcursorenterfun).
4756 *
4757 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4758 *
4759 * @thread_safety This function must only be called from the main thread.
4760 *
4761 * @sa @ref cursor_enter
4762 *
4763 * @since Added in version 3.0.
4764 *
4765 * @ingroup input
4766 */
4767GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcursorenterfun callback);
4768
4769/*! @brief Sets the scroll callback.
4770 *
4771 * This function sets the scroll callback of the specified window, which is
4772 * called when a scrolling device is used, such as a mouse wheel or scrolling
4773 * area of a touchpad.
4774 *
4775 * The scroll callback receives all scrolling input, like that from a mouse
4776 * wheel or a touchpad scrolling area.
4777 *
4778 * @param[in] window The window whose callback to set.
4779 * @param[in] callback The new scroll callback, or `NULL` to remove the
4780 * currently set callback.
4781 * @return The previously set callback, or `NULL` if no callback was set or the
4782 * library had not been [initialized](@ref intro_init).
4783 *
4784 * @callback_signature
4785 * @code
4786 * void function_name(GLFWwindow* window, double xoffset, double yoffset)
4787 * @endcode
4788 * For more information about the callback parameters, see the
4789 * [function pointer type](@ref GLFWscrollfun).
4790 *
4791 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4792 *
4793 * @thread_safety This function must only be called from the main thread.
4794 *
4795 * @sa @ref scrolling
4796 *
4797 * @since Added in version 3.0. Replaces `glfwSetMouseWheelCallback`.
4798 *
4799 * @ingroup input
4800 */
4801GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun callback);
4802
4803/*! @brief Sets the path drop callback.
4804 *
4805 * This function sets the path drop callback of the specified window, which is
4806 * called when one or more dragged paths are dropped on the window.
4807 *
4808 * Because the path array and its strings may have been generated specifically
4809 * for that event, they are not guaranteed to be valid after the callback has
4810 * returned. If you wish to use them after the callback returns, you need to
4811 * make a deep copy.
4812 *
4813 * @param[in] window The window whose callback to set.
4814 * @param[in] callback The new file drop callback, or `NULL` to remove the
4815 * currently set callback.
4816 * @return The previously set callback, or `NULL` if no callback was set or the
4817 * library had not been [initialized](@ref intro_init).
4818 *
4819 * @callback_signature
4820 * @code
4821 * void function_name(GLFWwindow* window, int path_count, const char* paths[])
4822 * @endcode
4823 * For more information about the callback parameters, see the
4824 * [function pointer type](@ref GLFWdropfun).
4825 *
4826 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
4827 *
4828 * @remark @wayland File drop is currently unimplemented.
4829 *
4830 * @thread_safety This function must only be called from the main thread.
4831 *
4832 * @sa @ref path_drop
4833 *
4834 * @since Added in version 3.1.
4835 *
4836 * @ingroup input
4837 */
4838GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun callback);
4839
4840/*! @brief Returns whether the specified joystick is present.
4841 *
4842 * This function returns whether the specified joystick is present.
4843 *
4844 * There is no need to call this function before other functions that accept
4845 * a joystick ID, as they all check for presence before performing any other
4846 * work.
4847 *
4848 * @param[in] jid The [joystick](@ref joysticks) to query.
4849 * @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise.
4850 *
4851 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4852 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4853 *
4854 * @thread_safety This function must only be called from the main thread.
4855 *
4856 * @sa @ref joystick
4857 *
4858 * @since Added in version 3.0. Replaces `glfwGetJoystickParam`.
4859 *
4860 * @ingroup input
4861 */
4862GLFWAPI int glfwJoystickPresent(int jid);
4863
4864/*! @brief Returns the values of all axes of the specified joystick.
4865 *
4866 * This function returns the values of all axes of the specified joystick.
4867 * Each element in the array is a value between -1.0 and 1.0.
4868 *
4869 * If the specified joystick is not present this function will return `NULL`
4870 * but will not generate an error. This can be used instead of first calling
4871 * @ref glfwJoystickPresent.
4872 *
4873 * @param[in] jid The [joystick](@ref joysticks) to query.
4874 * @param[out] count Where to store the number of axis values in the returned
4875 * array. This is set to zero if the joystick is not present or an error
4876 * occurred.
4877 * @return An array of axis values, or `NULL` if the joystick is not present or
4878 * an [error](@ref error_handling) occurred.
4879 *
4880 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4881 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4882 *
4883 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
4884 * should not free it yourself. It is valid until the specified joystick is
4885 * disconnected or the library is terminated.
4886 *
4887 * @thread_safety This function must only be called from the main thread.
4888 *
4889 * @sa @ref joystick_axis
4890 *
4891 * @since Added in version 3.0. Replaces `glfwGetJoystickPos`.
4892 *
4893 * @ingroup input
4894 */
4895GLFWAPI const float* glfwGetJoystickAxes(int jid, int* count);
4896
4897/*! @brief Returns the state of all buttons of the specified joystick.
4898 *
4899 * This function returns the state of all buttons of the specified joystick.
4900 * Each element in the array is either `GLFW_PRESS` or `GLFW_RELEASE`.
4901 *
4902 * For backward compatibility with earlier versions that did not have @ref
4903 * glfwGetJoystickHats, the button array also includes all hats, each
4904 * represented as four buttons. The hats are in the same order as returned by
4905 * __glfwGetJoystickHats__ and are in the order _up_, _right_, _down_ and
4906 * _left_. To disable these extra buttons, set the @ref
4907 * GLFW_JOYSTICK_HAT_BUTTONS init hint before initialization.
4908 *
4909 * If the specified joystick is not present this function will return `NULL`
4910 * but will not generate an error. This can be used instead of first calling
4911 * @ref glfwJoystickPresent.
4912 *
4913 * @param[in] jid The [joystick](@ref joysticks) to query.
4914 * @param[out] count Where to store the number of button states in the returned
4915 * array. This is set to zero if the joystick is not present or an error
4916 * occurred.
4917 * @return An array of button states, or `NULL` if the joystick is not present
4918 * or an [error](@ref error_handling) occurred.
4919 *
4920 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4921 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4922 *
4923 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
4924 * should not free it yourself. It is valid until the specified joystick is
4925 * disconnected or the library is terminated.
4926 *
4927 * @thread_safety This function must only be called from the main thread.
4928 *
4929 * @sa @ref joystick_button
4930 *
4931 * @since Added in version 2.2.
4932 * @glfw3 Changed to return a dynamic array.
4933 *
4934 * @ingroup input
4935 */
4936GLFWAPI const unsigned char* glfwGetJoystickButtons(int jid, int* count);
4937
4938/*! @brief Returns the state of all hats of the specified joystick.
4939 *
4940 * This function returns the state of all hats of the specified joystick.
4941 * Each element in the array is one of the following values:
4942 *
4943 * Name | Value
4944 * ---- | -----
4945 * `GLFW_HAT_CENTERED` | 0
4946 * `GLFW_HAT_UP` | 1
4947 * `GLFW_HAT_RIGHT` | 2
4948 * `GLFW_HAT_DOWN` | 4
4949 * `GLFW_HAT_LEFT` | 8
4950 * `GLFW_HAT_RIGHT_UP` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_UP`
4951 * `GLFW_HAT_RIGHT_DOWN` | `GLFW_HAT_RIGHT` \| `GLFW_HAT_DOWN`
4952 * `GLFW_HAT_LEFT_UP` | `GLFW_HAT_LEFT` \| `GLFW_HAT_UP`
4953 * `GLFW_HAT_LEFT_DOWN` | `GLFW_HAT_LEFT` \| `GLFW_HAT_DOWN`
4954 *
4955 * The diagonal directions are bitwise combinations of the primary (up, right,
4956 * down and left) directions and you can test for these individually by ANDing
4957 * it with the corresponding direction.
4958 *
4959 * @code
4960 * if (hats[2] & GLFW_HAT_RIGHT)
4961 * {
4962 * // State of hat 2 could be right-up, right or right-down
4963 * }
4964 * @endcode
4965 *
4966 * If the specified joystick is not present this function will return `NULL`
4967 * but will not generate an error. This can be used instead of first calling
4968 * @ref glfwJoystickPresent.
4969 *
4970 * @param[in] jid The [joystick](@ref joysticks) to query.
4971 * @param[out] count Where to store the number of hat states in the returned
4972 * array. This is set to zero if the joystick is not present or an error
4973 * occurred.
4974 * @return An array of hat states, or `NULL` if the joystick is not present
4975 * or an [error](@ref error_handling) occurred.
4976 *
4977 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
4978 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
4979 *
4980 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
4981 * should not free it yourself. It is valid until the specified joystick is
4982 * disconnected, this function is called again for that joystick or the library
4983 * is terminated.
4984 *
4985 * @thread_safety This function must only be called from the main thread.
4986 *
4987 * @sa @ref joystick_hat
4988 *
4989 * @since Added in version 3.3.
4990 *
4991 * @ingroup input
4992 */
4993GLFWAPI const unsigned char* glfwGetJoystickHats(int jid, int* count);
4994
4995/*! @brief Returns the name of the specified joystick.
4996 *
4997 * This function returns the name, encoded as UTF-8, of the specified joystick.
4998 * The returned string is allocated and freed by GLFW. You should not free it
4999 * yourself.
5000 *
5001 * If the specified joystick is not present this function will return `NULL`
5002 * but will not generate an error. This can be used instead of first calling
5003 * @ref glfwJoystickPresent.
5004 *
5005 * @param[in] jid The [joystick](@ref joysticks) to query.
5006 * @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick
5007 * is not present or an [error](@ref error_handling) occurred.
5008 *
5009 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5010 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
5011 *
5012 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
5013 * should not free it yourself. It is valid until the specified joystick is
5014 * disconnected or the library is terminated.
5015 *
5016 * @thread_safety This function must only be called from the main thread.
5017 *
5018 * @sa @ref joystick_name
5019 *
5020 * @since Added in version 3.0.
5021 *
5022 * @ingroup input
5023 */
5024GLFWAPI const char* glfwGetJoystickName(int jid);
5025
5026/*! @brief Returns the SDL compatible GUID of the specified joystick.
5027 *
5028 * This function returns the SDL compatible GUID, as a UTF-8 encoded
5029 * hexadecimal string, of the specified joystick. The returned string is
5030 * allocated and freed by GLFW. You should not free it yourself.
5031 *
5032 * The GUID is what connects a joystick to a gamepad mapping. A connected
5033 * joystick will always have a GUID even if there is no gamepad mapping
5034 * assigned to it.
5035 *
5036 * If the specified joystick is not present this function will return `NULL`
5037 * but will not generate an error. This can be used instead of first calling
5038 * @ref glfwJoystickPresent.
5039 *
5040 * The GUID uses the format introduced in SDL 2.0.5. This GUID tries to
5041 * uniquely identify the make and model of a joystick but does not identify
5042 * a specific unit, e.g. all wired Xbox 360 controllers will have the same
5043 * GUID on that platform. The GUID for a unit may vary between platforms
5044 * depending on what hardware information the platform specific APIs provide.
5045 *
5046 * @param[in] jid The [joystick](@ref joysticks) to query.
5047 * @return The UTF-8 encoded GUID of the joystick, or `NULL` if the joystick
5048 * is not present or an [error](@ref error_handling) occurred.
5049 *
5050 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5051 * GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
5052 *
5053 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
5054 * should not free it yourself. It is valid until the specified joystick is
5055 * disconnected or the library is terminated.
5056 *
5057 * @thread_safety This function must only be called from the main thread.
5058 *
5059 * @sa @ref gamepad
5060 *
5061 * @since Added in version 3.3.
5062 *
5063 * @ingroup input
5064 */
5065GLFWAPI const char* glfwGetJoystickGUID(int jid);
5066
5067/*! @brief Sets the user pointer of the specified joystick.
5068 *
5069 * This function sets the user-defined pointer of the specified joystick. The
5070 * current value is retained until the joystick is disconnected. The initial
5071 * value is `NULL`.
5072 *
5073 * This function may be called from the joystick callback, even for a joystick
5074 * that is being disconnected.
5075 *
5076 * @param[in] jid The joystick whose pointer to set.
5077 * @param[in] pointer The new value.
5078 *
5079 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5080 *
5081 * @thread_safety This function may be called from any thread. Access is not
5082 * synchronized.
5083 *
5084 * @sa @ref joystick_userptr
5085 * @sa @ref glfwGetJoystickUserPointer
5086 *
5087 * @since Added in version 3.3.
5088 *
5089 * @ingroup input
5090 */
5091GLFWAPI void glfwSetJoystickUserPointer(int jid, void* pointer);
5092
5093/*! @brief Returns the user pointer of the specified joystick.
5094 *
5095 * This function returns the current value of the user-defined pointer of the
5096 * specified joystick. The initial value is `NULL`.
5097 *
5098 * This function may be called from the joystick callback, even for a joystick
5099 * that is being disconnected.
5100 *
5101 * @param[in] jid The joystick whose pointer to return.
5102 *
5103 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5104 *
5105 * @thread_safety This function may be called from any thread. Access is not
5106 * synchronized.
5107 *
5108 * @sa @ref joystick_userptr
5109 * @sa @ref glfwSetJoystickUserPointer
5110 *
5111 * @since Added in version 3.3.
5112 *
5113 * @ingroup input
5114 */
5115GLFWAPI void* glfwGetJoystickUserPointer(int jid);
5116
5117/*! @brief Returns whether the specified joystick has a gamepad mapping.
5118 *
5119 * This function returns whether the specified joystick is both present and has
5120 * a gamepad mapping.
5121 *
5122 * If the specified joystick is present but does not have a gamepad mapping
5123 * this function will return `GLFW_FALSE` but will not generate an error. Call
5124 * @ref glfwJoystickPresent to check if a joystick is present regardless of
5125 * whether it has a mapping.
5126 *
5127 * @param[in] jid The [joystick](@ref joysticks) to query.
5128 * @return `GLFW_TRUE` if a joystick is both present and has a gamepad mapping,
5129 * or `GLFW_FALSE` otherwise.
5130 *
5131 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5132 * GLFW_INVALID_ENUM.
5133 *
5134 * @thread_safety This function must only be called from the main thread.
5135 *
5136 * @sa @ref gamepad
5137 * @sa @ref glfwGetGamepadState
5138 *
5139 * @since Added in version 3.3.
5140 *
5141 * @ingroup input
5142 */
5143GLFWAPI int glfwJoystickIsGamepad(int jid);
5144
5145/*! @brief Sets the joystick configuration callback.
5146 *
5147 * This function sets the joystick configuration callback, or removes the
5148 * currently set callback. This is called when a joystick is connected to or
5149 * disconnected from the system.
5150 *
5151 * For joystick connection and disconnection events to be delivered on all
5152 * platforms, you need to call one of the [event processing](@ref events)
5153 * functions. Joystick disconnection may also be detected and the callback
5154 * called by joystick functions. The function will then return whatever it
5155 * returns if the joystick is not present.
5156 *
5157 * @param[in] callback The new callback, or `NULL` to remove the currently set
5158 * callback.
5159 * @return The previously set callback, or `NULL` if no callback was set or the
5160 * library had not been [initialized](@ref intro_init).
5161 *
5162 * @callback_signature
5163 * @code
5164 * void function_name(int jid, int event)
5165 * @endcode
5166 * For more information about the callback parameters, see the
5167 * [function pointer type](@ref GLFWjoystickfun).
5168 *
5169 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5170 *
5171 * @thread_safety This function must only be called from the main thread.
5172 *
5173 * @sa @ref joystick_event
5174 *
5175 * @since Added in version 3.2.
5176 *
5177 * @ingroup input
5178 */
5179GLFWAPI GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun callback);
5180
5181/*! @brief Adds the specified SDL_GameControllerDB gamepad mappings.
5182 *
5183 * This function parses the specified ASCII encoded string and updates the
5184 * internal list with any gamepad mappings it finds. This string may
5185 * contain either a single gamepad mapping or many mappings separated by
5186 * newlines. The parser supports the full format of the `gamecontrollerdb.txt`
5187 * source file including empty lines and comments.
5188 *
5189 * See @ref gamepad_mapping for a description of the format.
5190 *
5191 * If there is already a gamepad mapping for a given GUID in the internal list,
5192 * it will be replaced by the one passed to this function. If the library is
5193 * terminated and re-initialized the internal list will revert to the built-in
5194 * default.
5195 *
5196 * @param[in] string The string containing the gamepad mappings.
5197 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
5198 * [error](@ref error_handling) occurred.
5199 *
5200 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5201 * GLFW_INVALID_VALUE.
5202 *
5203 * @thread_safety This function must only be called from the main thread.
5204 *
5205 * @sa @ref gamepad
5206 * @sa @ref glfwJoystickIsGamepad
5207 * @sa @ref glfwGetGamepadName
5208 *
5209 * @since Added in version 3.3.
5210 *
5211 * @ingroup input
5212 */
5213GLFWAPI int glfwUpdateGamepadMappings(const char* string);
5214
5215/*! @brief Returns the human-readable gamepad name for the specified joystick.
5216 *
5217 * This function returns the human-readable name of the gamepad from the
5218 * gamepad mapping assigned to the specified joystick.
5219 *
5220 * If the specified joystick is not present or does not have a gamepad mapping
5221 * this function will return `NULL` but will not generate an error. Call
5222 * @ref glfwJoystickPresent to check whether it is present regardless of
5223 * whether it has a mapping.
5224 *
5225 * @param[in] jid The [joystick](@ref joysticks) to query.
5226 * @return The UTF-8 encoded name of the gamepad, or `NULL` if the
5227 * joystick is not present, does not have a mapping or an
5228 * [error](@ref error_handling) occurred.
5229 *
5230 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
5231 * should not free it yourself. It is valid until the specified joystick is
5232 * disconnected, the gamepad mappings are updated or the library is terminated.
5233 *
5234 * @thread_safety This function must only be called from the main thread.
5235 *
5236 * @sa @ref gamepad
5237 * @sa @ref glfwJoystickIsGamepad
5238 *
5239 * @since Added in version 3.3.
5240 *
5241 * @ingroup input
5242 */
5243GLFWAPI const char* glfwGetGamepadName(int jid);
5244
5245/*! @brief Retrieves the state of the specified joystick remapped as a gamepad.
5246 *
5247 * This function retrieves the state of the specified joystick remapped to
5248 * an Xbox-like gamepad.
5249 *
5250 * If the specified joystick is not present or does not have a gamepad mapping
5251 * this function will return `GLFW_FALSE` but will not generate an error. Call
5252 * @ref glfwJoystickPresent to check whether it is present regardless of
5253 * whether it has a mapping.
5254 *
5255 * The Guide button may not be available for input as it is often hooked by the
5256 * system or the Steam client.
5257 *
5258 * Not all devices have all the buttons or axes provided by @ref
5259 * GLFWgamepadstate. Unavailable buttons and axes will always report
5260 * `GLFW_RELEASE` and 0.0 respectively.
5261 *
5262 * @param[in] jid The [joystick](@ref joysticks) to query.
5263 * @param[out] state The gamepad input state of the joystick.
5264 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if no joystick is
5265 * connected, it has no gamepad mapping or an [error](@ref error_handling)
5266 * occurred.
5267 *
5268 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5269 * GLFW_INVALID_ENUM.
5270 *
5271 * @thread_safety This function must only be called from the main thread.
5272 *
5273 * @sa @ref gamepad
5274 * @sa @ref glfwUpdateGamepadMappings
5275 * @sa @ref glfwJoystickIsGamepad
5276 *
5277 * @since Added in version 3.3.
5278 *
5279 * @ingroup input
5280 */
5281GLFWAPI int glfwGetGamepadState(int jid, GLFWgamepadstate* state);
5282
5283/*! @brief Sets the clipboard to the specified string.
5284 *
5285 * This function sets the system clipboard to the specified, UTF-8 encoded
5286 * string.
5287 *
5288 * @param[in] window Deprecated. Any valid window or `NULL`.
5289 * @param[in] string A UTF-8 encoded string.
5290 *
5291 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5292 * GLFW_PLATFORM_ERROR.
5293 *
5294 * @pointer_lifetime The specified string is copied before this function
5295 * returns.
5296 *
5297 * @thread_safety This function must only be called from the main thread.
5298 *
5299 * @sa @ref clipboard
5300 * @sa @ref glfwGetClipboardString
5301 *
5302 * @since Added in version 3.0.
5303 *
5304 * @ingroup input
5305 */
5306GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string);
5307
5308/*! @brief Returns the contents of the clipboard as a string.
5309 *
5310 * This function returns the contents of the system clipboard, if it contains
5311 * or is convertible to a UTF-8 encoded string. If the clipboard is empty or
5312 * if its contents cannot be converted, `NULL` is returned and a @ref
5313 * GLFW_FORMAT_UNAVAILABLE error is generated.
5314 *
5315 * @param[in] window Deprecated. Any valid window or `NULL`.
5316 * @return The contents of the clipboard as a UTF-8 encoded string, or `NULL`
5317 * if an [error](@ref error_handling) occurred.
5318 *
5319 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5320 * GLFW_PLATFORM_ERROR.
5321 *
5322 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
5323 * should not free it yourself. It is valid until the next call to @ref
5324 * glfwGetClipboardString or @ref glfwSetClipboardString, or until the library
5325 * is terminated.
5326 *
5327 * @thread_safety This function must only be called from the main thread.
5328 *
5329 * @sa @ref clipboard
5330 * @sa @ref glfwSetClipboardString
5331 *
5332 * @since Added in version 3.0.
5333 *
5334 * @ingroup input
5335 */
5336GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window);
5337
5338/*! @brief Returns the GLFW time.
5339 *
5340 * This function returns the current GLFW time, in seconds. Unless the time
5341 * has been set using @ref glfwSetTime it measures time elapsed since GLFW was
5342 * initialized.
5343 *
5344 * This function and @ref glfwSetTime are helper functions on top of @ref
5345 * glfwGetTimerFrequency and @ref glfwGetTimerValue.
5346 *
5347 * The resolution of the timer is system dependent, but is usually on the order
5348 * of a few micro- or nanoseconds. It uses the highest-resolution monotonic
5349 * time source on each supported platform.
5350 *
5351 * @return The current time, in seconds, or zero if an
5352 * [error](@ref error_handling) occurred.
5353 *
5354 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5355 *
5356 * @thread_safety This function may be called from any thread. Reading and
5357 * writing of the internal base time is not atomic, so it needs to be
5358 * externally synchronized with calls to @ref glfwSetTime.
5359 *
5360 * @sa @ref time
5361 *
5362 * @since Added in version 1.0.
5363 *
5364 * @ingroup input
5365 */
5366GLFWAPI double glfwGetTime(void);
5367
5368/*! @brief Sets the GLFW time.
5369 *
5370 * This function sets the current GLFW time, in seconds. The value must be
5371 * a positive finite number less than or equal to 18446744073.0, which is
5372 * approximately 584.5 years.
5373 *
5374 * This function and @ref glfwGetTime are helper functions on top of @ref
5375 * glfwGetTimerFrequency and @ref glfwGetTimerValue.
5376 *
5377 * @param[in] time The new value, in seconds.
5378 *
5379 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5380 * GLFW_INVALID_VALUE.
5381 *
5382 * @remark The upper limit of GLFW time is calculated as
5383 * floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations
5384 * storing nanoseconds in 64 bits. The limit may be increased in the future.
5385 *
5386 * @thread_safety This function may be called from any thread. Reading and
5387 * writing of the internal base time is not atomic, so it needs to be
5388 * externally synchronized with calls to @ref glfwGetTime.
5389 *
5390 * @sa @ref time
5391 *
5392 * @since Added in version 2.2.
5393 *
5394 * @ingroup input
5395 */
5396GLFWAPI void glfwSetTime(double time);
5397
5398/*! @brief Returns the current value of the raw timer.
5399 *
5400 * This function returns the current value of the raw timer, measured in
5401 * 1&nbsp;/&nbsp;frequency seconds. To get the frequency, call @ref
5402 * glfwGetTimerFrequency.
5403 *
5404 * @return The value of the timer, or zero if an
5405 * [error](@ref error_handling) occurred.
5406 *
5407 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5408 *
5409 * @thread_safety This function may be called from any thread.
5410 *
5411 * @sa @ref time
5412 * @sa @ref glfwGetTimerFrequency
5413 *
5414 * @since Added in version 3.2.
5415 *
5416 * @ingroup input
5417 */
5418GLFWAPI uint64_t glfwGetTimerValue(void);
5419
5420/*! @brief Returns the frequency, in Hz, of the raw timer.
5421 *
5422 * This function returns the frequency, in Hz, of the raw timer.
5423 *
5424 * @return The frequency of the timer, in Hz, or zero if an
5425 * [error](@ref error_handling) occurred.
5426 *
5427 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5428 *
5429 * @thread_safety This function may be called from any thread.
5430 *
5431 * @sa @ref time
5432 * @sa @ref glfwGetTimerValue
5433 *
5434 * @since Added in version 3.2.
5435 *
5436 * @ingroup input
5437 */
5438GLFWAPI uint64_t glfwGetTimerFrequency(void);
5439
5440/*! @brief Makes the context of the specified window current for the calling
5441 * thread.
5442 *
5443 * This function makes the OpenGL or OpenGL ES context of the specified window
5444 * current on the calling thread. A context must only be made current on
5445 * a single thread at a time and each thread can have only a single current
5446 * context at a time.
5447 *
5448 * When moving a context between threads, you must make it non-current on the
5449 * old thread before making it current on the new one.
5450 *
5451 * By default, making a context non-current implicitly forces a pipeline flush.
5452 * On machines that support `GL_KHR_context_flush_control`, you can control
5453 * whether a context performs this flush by setting the
5454 * [GLFW_CONTEXT_RELEASE_BEHAVIOR](@ref GLFW_CONTEXT_RELEASE_BEHAVIOR_hint)
5455 * hint.
5456 *
5457 * The specified window must have an OpenGL or OpenGL ES context. Specifying
5458 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
5459 * error.
5460 *
5461 * @param[in] window The window whose context to make current, or `NULL` to
5462 * detach the current context.
5463 *
5464 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5465 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
5466 *
5467 * @thread_safety This function may be called from any thread.
5468 *
5469 * @sa @ref context_current
5470 * @sa @ref glfwGetCurrentContext
5471 *
5472 * @since Added in version 3.0.
5473 *
5474 * @ingroup context
5475 */
5476GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window);
5477
5478/*! @brief Returns the window whose context is current on the calling thread.
5479 *
5480 * This function returns the window whose OpenGL or OpenGL ES context is
5481 * current on the calling thread.
5482 *
5483 * @return The window whose context is current, or `NULL` if no window's
5484 * context is current.
5485 *
5486 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5487 *
5488 * @thread_safety This function may be called from any thread.
5489 *
5490 * @sa @ref context_current
5491 * @sa @ref glfwMakeContextCurrent
5492 *
5493 * @since Added in version 3.0.
5494 *
5495 * @ingroup context
5496 */
5497GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
5498
5499/*! @brief Swaps the front and back buffers of the specified window.
5500 *
5501 * This function swaps the front and back buffers of the specified window when
5502 * rendering with OpenGL or OpenGL ES. If the swap interval is greater than
5503 * zero, the GPU driver waits the specified number of screen updates before
5504 * swapping the buffers.
5505 *
5506 * The specified window must have an OpenGL or OpenGL ES context. Specifying
5507 * a window without a context will generate a @ref GLFW_NO_WINDOW_CONTEXT
5508 * error.
5509 *
5510 * This function does not apply to Vulkan. If you are rendering with Vulkan,
5511 * see `vkQueuePresentKHR` instead.
5512 *
5513 * @param[in] window The window whose buffers to swap.
5514 *
5515 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5516 * GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
5517 *
5518 * @remark __EGL:__ The context of the specified window must be current on the
5519 * calling thread.
5520 *
5521 * @thread_safety This function may be called from any thread.
5522 *
5523 * @sa @ref buffer_swap
5524 * @sa @ref glfwSwapInterval
5525 *
5526 * @since Added in version 1.0.
5527 * @glfw3 Added window handle parameter.
5528 *
5529 * @ingroup window
5530 */
5531GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
5532
5533/*! @brief Sets the swap interval for the current context.
5534 *
5535 * This function sets the swap interval for the current OpenGL or OpenGL ES
5536 * context, i.e. the number of screen updates to wait from the time @ref
5537 * glfwSwapBuffers was called before swapping the buffers and returning. This
5538 * is sometimes called _vertical synchronization_, _vertical retrace
5539 * synchronization_ or just _vsync_.
5540 *
5541 * A context that supports either of the `WGL_EXT_swap_control_tear` and
5542 * `GLX_EXT_swap_control_tear` extensions also accepts _negative_ swap
5543 * intervals, which allows the driver to swap immediately even if a frame
5544 * arrives a little bit late. You can check for these extensions with @ref
5545 * glfwExtensionSupported.
5546 *
5547 * A context must be current on the calling thread. Calling this function
5548 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
5549 *
5550 * This function does not apply to Vulkan. If you are rendering with Vulkan,
5551 * see the present mode of your swapchain instead.
5552 *
5553 * @param[in] interval The minimum number of screen updates to wait for
5554 * until the buffers are swapped by @ref glfwSwapBuffers.
5555 *
5556 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5557 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR.
5558 *
5559 * @remark This function is not called during context creation, leaving the
5560 * swap interval set to whatever is the default on that platform. This is done
5561 * because some swap interval extensions used by GLFW do not allow the swap
5562 * interval to be reset to zero once it has been set to a non-zero value.
5563 *
5564 * @remark Some GPU drivers do not honor the requested swap interval, either
5565 * because of a user setting that overrides the application's request or due to
5566 * bugs in the driver.
5567 *
5568 * @thread_safety This function may be called from any thread.
5569 *
5570 * @sa @ref buffer_swap
5571 * @sa @ref glfwSwapBuffers
5572 *
5573 * @since Added in version 1.0.
5574 *
5575 * @ingroup context
5576 */
5577GLFWAPI void glfwSwapInterval(int interval);
5578
5579/*! @brief Returns whether the specified extension is available.
5580 *
5581 * This function returns whether the specified
5582 * [API extension](@ref context_glext) is supported by the current OpenGL or
5583 * OpenGL ES context. It searches both for client API extension and context
5584 * creation API extensions.
5585 *
5586 * A context must be current on the calling thread. Calling this function
5587 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
5588 *
5589 * As this functions retrieves and searches one or more extension strings each
5590 * call, it is recommended that you cache its results if it is going to be used
5591 * frequently. The extension strings will not change during the lifetime of
5592 * a context, so there is no danger in doing this.
5593 *
5594 * This function does not apply to Vulkan. If you are using Vulkan, see @ref
5595 * glfwGetRequiredInstanceExtensions, `vkEnumerateInstanceExtensionProperties`
5596 * and `vkEnumerateDeviceExtensionProperties` instead.
5597 *
5598 * @param[in] extension The ASCII encoded name of the extension.
5599 * @return `GLFW_TRUE` if the extension is available, or `GLFW_FALSE`
5600 * otherwise.
5601 *
5602 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5603 * GLFW_NO_CURRENT_CONTEXT, @ref GLFW_INVALID_VALUE and @ref
5604 * GLFW_PLATFORM_ERROR.
5605 *
5606 * @thread_safety This function may be called from any thread.
5607 *
5608 * @sa @ref context_glext
5609 * @sa @ref glfwGetProcAddress
5610 *
5611 * @since Added in version 1.0.
5612 *
5613 * @ingroup context
5614 */
5615GLFWAPI int glfwExtensionSupported(const char* extension);
5616
5617/*! @brief Returns the address of the specified function for the current
5618 * context.
5619 *
5620 * This function returns the address of the specified OpenGL or OpenGL ES
5621 * [core or extension function](@ref context_glext), if it is supported
5622 * by the current context.
5623 *
5624 * A context must be current on the calling thread. Calling this function
5625 * without a current context will cause a @ref GLFW_NO_CURRENT_CONTEXT error.
5626 *
5627 * This function does not apply to Vulkan. If you are rendering with Vulkan,
5628 * see @ref glfwGetInstanceProcAddress, `vkGetInstanceProcAddr` and
5629 * `vkGetDeviceProcAddr` instead.
5630 *
5631 * @param[in] procname The ASCII encoded name of the function.
5632 * @return The address of the function, or `NULL` if an
5633 * [error](@ref error_handling) occurred.
5634 *
5635 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5636 * GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR.
5637 *
5638 * @remark The address of a given function is not guaranteed to be the same
5639 * between contexts.
5640 *
5641 * @remark This function may return a non-`NULL` address despite the
5642 * associated version or extension not being available. Always check the
5643 * context version or extension string first.
5644 *
5645 * @pointer_lifetime The returned function pointer is valid until the context
5646 * is destroyed or the library is terminated.
5647 *
5648 * @thread_safety This function may be called from any thread.
5649 *
5650 * @sa @ref context_glext
5651 * @sa @ref glfwExtensionSupported
5652 *
5653 * @since Added in version 1.0.
5654 *
5655 * @ingroup context
5656 */
5657GLFWAPI GLFWglproc glfwGetProcAddress(const char* procname);
5658
5659/*! @brief Returns whether the Vulkan loader and an ICD have been found.
5660 *
5661 * This function returns whether the Vulkan loader and any minimally functional
5662 * ICD have been found.
5663 *
5664 * The availability of a Vulkan loader and even an ICD does not by itself guarantee that
5665 * surface creation or even instance creation is possible. Call @ref
5666 * glfwGetRequiredInstanceExtensions to check whether the extensions necessary for Vulkan
5667 * surface creation are available and @ref glfwGetPhysicalDevicePresentationSupport to
5668 * check whether a queue family of a physical device supports image presentation.
5669 *
5670 * @return `GLFW_TRUE` if Vulkan is minimally available, or `GLFW_FALSE`
5671 * otherwise.
5672 *
5673 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
5674 *
5675 * @thread_safety This function may be called from any thread.
5676 *
5677 * @sa @ref vulkan_support
5678 *
5679 * @since Added in version 3.2.
5680 *
5681 * @ingroup vulkan
5682 */
5683GLFWAPI int glfwVulkanSupported(void);
5684
5685/*! @brief Returns the Vulkan instance extensions required by GLFW.
5686 *
5687 * This function returns an array of names of Vulkan instance extensions required
5688 * by GLFW for creating Vulkan surfaces for GLFW windows. If successful, the
5689 * list will always contain `VK_KHR_surface`, so if you don't require any
5690 * additional extensions you can pass this list directly to the
5691 * `VkInstanceCreateInfo` struct.
5692 *
5693 * If Vulkan is not available on the machine, this function returns `NULL` and
5694 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
5695 * to check whether Vulkan is at least minimally available.
5696 *
5697 * If Vulkan is available but no set of extensions allowing window surface
5698 * creation was found, this function returns `NULL`. You may still use Vulkan
5699 * for off-screen rendering and compute work.
5700 *
5701 * @param[out] count Where to store the number of extensions in the returned
5702 * array. This is set to zero if an error occurred.
5703 * @return An array of ASCII encoded extension names, or `NULL` if an
5704 * [error](@ref error_handling) occurred.
5705 *
5706 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5707 * GLFW_API_UNAVAILABLE.
5708 *
5709 * @remark Additional extensions may be required by future versions of GLFW.
5710 * You should check if any extensions you wish to enable are already in the
5711 * returned array, as it is an error to specify an extension more than once in
5712 * the `VkInstanceCreateInfo` struct.
5713 *
5714 * @remark @macos GLFW currently supports both the `VK_MVK_macos_surface` and
5715 * the newer `VK_EXT_metal_surface` extensions.
5716 *
5717 * @pointer_lifetime The returned array is allocated and freed by GLFW. You
5718 * should not free it yourself. It is guaranteed to be valid only until the
5719 * library is terminated.
5720 *
5721 * @thread_safety This function may be called from any thread.
5722 *
5723 * @sa @ref vulkan_ext
5724 * @sa @ref glfwCreateWindowSurface
5725 *
5726 * @since Added in version 3.2.
5727 *
5728 * @ingroup vulkan
5729 */
5730GLFWAPI const char** glfwGetRequiredInstanceExtensions(uint32_t* count);
5731
5732#if defined(VK_VERSION_1_0)
5733
5734/*! @brief Returns the address of the specified Vulkan instance function.
5735 *
5736 * This function returns the address of the specified Vulkan core or extension
5737 * function for the specified instance. If instance is set to `NULL` it can
5738 * return any function exported from the Vulkan loader, including at least the
5739 * following functions:
5740 *
5741 * - `vkEnumerateInstanceExtensionProperties`
5742 * - `vkEnumerateInstanceLayerProperties`
5743 * - `vkCreateInstance`
5744 * - `vkGetInstanceProcAddr`
5745 *
5746 * If Vulkan is not available on the machine, this function returns `NULL` and
5747 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
5748 * to check whether Vulkan is at least minimally available.
5749 *
5750 * This function is equivalent to calling `vkGetInstanceProcAddr` with
5751 * a platform-specific query of the Vulkan loader as a fallback.
5752 *
5753 * @param[in] instance The Vulkan instance to query, or `NULL` to retrieve
5754 * functions related to instance creation.
5755 * @param[in] procname The ASCII encoded name of the function.
5756 * @return The address of the function, or `NULL` if an
5757 * [error](@ref error_handling) occurred.
5758 *
5759 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
5760 * GLFW_API_UNAVAILABLE.
5761 *
5762 * @pointer_lifetime The returned function pointer is valid until the library
5763 * is terminated.
5764 *
5765 * @thread_safety This function may be called from any thread.
5766 *
5767 * @sa @ref vulkan_proc
5768 *
5769 * @since Added in version 3.2.
5770 *
5771 * @ingroup vulkan
5772 */
5773GLFWAPI GLFWvkproc glfwGetInstanceProcAddress(VkInstance instance, const char* procname);
5774
5775/*! @brief Returns whether the specified queue family can present images.
5776 *
5777 * This function returns whether the specified queue family of the specified
5778 * physical device supports presentation to the platform GLFW was built for.
5779 *
5780 * If Vulkan or the required window surface creation instance extensions are
5781 * not available on the machine, or if the specified instance was not created
5782 * with the required extensions, this function returns `GLFW_FALSE` and
5783 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported
5784 * to check whether Vulkan is at least minimally available and @ref
5785 * glfwGetRequiredInstanceExtensions to check what instance extensions are
5786 * required.
5787 *
5788 * @param[in] instance The instance that the physical device belongs to.
5789 * @param[in] device The physical device that the queue family belongs to.
5790 * @param[in] queuefamily The index of the queue family to query.
5791 * @return `GLFW_TRUE` if the queue family supports presentation, or
5792 * `GLFW_FALSE` otherwise.
5793 *
5794 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5795 * GLFW_API_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR.
5796 *
5797 * @remark @macos This function currently always returns `GLFW_TRUE`, as the
5798 * `VK_MVK_macos_surface` and `VK_EXT_metal_surface` extensions do not provide
5799 * a `vkGetPhysicalDevice*PresentationSupport` type function.
5800 *
5801 * @thread_safety This function may be called from any thread. For
5802 * synchronization details of Vulkan objects, see the Vulkan specification.
5803 *
5804 * @sa @ref vulkan_present
5805 *
5806 * @since Added in version 3.2.
5807 *
5808 * @ingroup vulkan
5809 */
5810GLFWAPI int glfwGetPhysicalDevicePresentationSupport(VkInstance instance, VkPhysicalDevice device, uint32_t queuefamily);
5811
5812/*! @brief Creates a Vulkan surface for the specified window.
5813 *
5814 * This function creates a Vulkan surface for the specified window.
5815 *
5816 * If the Vulkan loader or at least one minimally functional ICD were not found,
5817 * this function returns `VK_ERROR_INITIALIZATION_FAILED` and generates a @ref
5818 * GLFW_API_UNAVAILABLE error. Call @ref glfwVulkanSupported to check whether
5819 * Vulkan is at least minimally available.
5820 *
5821 * If the required window surface creation instance extensions are not
5822 * available or if the specified instance was not created with these extensions
5823 * enabled, this function returns `VK_ERROR_EXTENSION_NOT_PRESENT` and
5824 * generates a @ref GLFW_API_UNAVAILABLE error. Call @ref
5825 * glfwGetRequiredInstanceExtensions to check what instance extensions are
5826 * required.
5827 *
5828 * The window surface cannot be shared with another API so the window must
5829 * have been created with the [client api hint](@ref GLFW_CLIENT_API_attrib)
5830 * set to `GLFW_NO_API` otherwise it generates a @ref GLFW_INVALID_VALUE error
5831 * and returns `VK_ERROR_NATIVE_WINDOW_IN_USE_KHR`.
5832 *
5833 * The window surface must be destroyed before the specified Vulkan instance.
5834 * It is the responsibility of the caller to destroy the window surface. GLFW
5835 * does not destroy it for you. Call `vkDestroySurfaceKHR` to destroy the
5836 * surface.
5837 *
5838 * @param[in] instance The Vulkan instance to create the surface in.
5839 * @param[in] window The window to create the surface for.
5840 * @param[in] allocator The allocator to use, or `NULL` to use the default
5841 * allocator.
5842 * @param[out] surface Where to store the handle of the surface. This is set
5843 * to `VK_NULL_HANDLE` if an error occurred.
5844 * @return `VK_SUCCESS` if successful, or a Vulkan error code if an
5845 * [error](@ref error_handling) occurred.
5846 *
5847 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
5848 * GLFW_API_UNAVAILABLE, @ref GLFW_PLATFORM_ERROR and @ref GLFW_INVALID_VALUE
5849 *
5850 * @remark If an error occurs before the creation call is made, GLFW returns
5851 * the Vulkan error code most appropriate for the error. Appropriate use of
5852 * @ref glfwVulkanSupported and @ref glfwGetRequiredInstanceExtensions should
5853 * eliminate almost all occurrences of these errors.
5854 *
5855 * @remark @macos This function currently only supports the
5856 * `VK_MVK_macos_surface` extension from MoltenVK.
5857 *
5858 * @remark @macos This function creates and sets a `CAMetalLayer` instance for
5859 * the window content view, which is required for MoltenVK to function.
5860 *
5861 * @thread_safety This function may be called from any thread. For
5862 * synchronization details of Vulkan objects, see the Vulkan specification.
5863 *
5864 * @sa @ref vulkan_surface
5865 * @sa @ref glfwGetRequiredInstanceExtensions
5866 *
5867 * @since Added in version 3.2.
5868 *
5869 * @ingroup vulkan
5870 */
5871GLFWAPI VkResult glfwCreateWindowSurface(VkInstance instance, GLFWwindow* window, const VkAllocationCallbacks* allocator, VkSurfaceKHR* surface);
5872
5873#endif /*VK_VERSION_1_0*/
5874
5875
5876/*************************************************************************
5877 * Global definition cleanup
5878 *************************************************************************/
5879
5880/* ------------------- BEGIN SYSTEM/COMPILER SPECIFIC -------------------- */
5881
5882#ifdef GLFW_WINGDIAPI_DEFINED
5883 #undef WINGDIAPI
5884 #undef GLFW_WINGDIAPI_DEFINED
5885#endif
5886
5887#ifdef GLFW_CALLBACK_DEFINED
5888 #undef CALLBACK
5889 #undef GLFW_CALLBACK_DEFINED
5890#endif
5891
5892/* Some OpenGL related headers need GLAPIENTRY, but it is unconditionally
5893 * defined by some gl.h variants (OpenBSD) so define it after if needed.
5894 */
5895#ifndef GLAPIENTRY
5896 #define GLAPIENTRY APIENTRY
5897#endif
5898
5899/* -------------------- END SYSTEM/COMPILER SPECIFIC --------------------- */
5900
5901
5902#ifdef __cplusplus
5903}
5904#endif
5905
5906#endif /* _glfw3_h_ */
5907
diff --git a/contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3native.h b/contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3native.h
new file mode 100644
index 0000000..fe74c73
--- /dev/null
+++ b/contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3native.h
@@ -0,0 +1,594 @@
1/*************************************************************************
2 * GLFW 3.3 - www.glfw.org
3 * A library for OpenGL, window and input
4 *------------------------------------------------------------------------
5 * Copyright (c) 2002-2006 Marcus Geelnard
6 * Copyright (c) 2006-2018 Camilla Löwy <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_native_h_
30#define _glfw3_native_h_
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36
37/*************************************************************************
38 * Doxygen documentation
39 *************************************************************************/
40
41/*! @file glfw3native.h
42 * @brief The header of the native access functions.
43 *
44 * This is the header file of the native access functions. See @ref native for
45 * more information.
46 */
47/*! @defgroup native Native access
48 * @brief Functions related to accessing native handles.
49 *
50 * **By using the native access functions you assert that you know what you're
51 * doing and how to fix problems caused by using them. If you don't, you
52 * shouldn't be using them.**
53 *
54 * Before the inclusion of @ref glfw3native.h, you may define zero or more
55 * window system API macro and zero or more context creation API macros.
56 *
57 * The chosen backends must match those the library was compiled for. Failure
58 * to do this will cause a link-time error.
59 *
60 * The available window API macros are:
61 * * `GLFW_EXPOSE_NATIVE_WIN32`
62 * * `GLFW_EXPOSE_NATIVE_COCOA`
63 * * `GLFW_EXPOSE_NATIVE_X11`
64 * * `GLFW_EXPOSE_NATIVE_WAYLAND`
65 *
66 * The available context API macros are:
67 * * `GLFW_EXPOSE_NATIVE_WGL`
68 * * `GLFW_EXPOSE_NATIVE_NSGL`
69 * * `GLFW_EXPOSE_NATIVE_GLX`
70 * * `GLFW_EXPOSE_NATIVE_EGL`
71 * * `GLFW_EXPOSE_NATIVE_OSMESA`
72 *
73 * These macros select which of the native access functions that are declared
74 * and which platform-specific headers to include. It is then up your (by
75 * definition platform-specific) code to handle which of these should be
76 * defined.
77 */
78
79
80/*************************************************************************
81 * System headers and types
82 *************************************************************************/
83
84#if defined(GLFW_EXPOSE_NATIVE_WIN32) || defined(GLFW_EXPOSE_NATIVE_WGL)
85 // This is a workaround for the fact that glfw3.h needs to export APIENTRY (for
86 // example to allow applications to correctly declare a GL_KHR_debug callback)
87 // but windows.h assumes no one will define APIENTRY before it does
88 #if defined(GLFW_APIENTRY_DEFINED)
89 #undef APIENTRY
90 #undef GLFW_APIENTRY_DEFINED
91 #endif
92 #include <windows.h>
93#elif defined(GLFW_EXPOSE_NATIVE_COCOA) || defined(GLFW_EXPOSE_NATIVE_NSGL)
94 #if defined(__OBJC__)
95 #import <Cocoa/Cocoa.h>
96 #else
97 #include <ApplicationServices/ApplicationServices.h>
98 typedef void* id;
99 #endif
100#elif defined(GLFW_EXPOSE_NATIVE_X11) || defined(GLFW_EXPOSE_NATIVE_GLX)
101 #include <X11/Xlib.h>
102 #include <X11/extensions/Xrandr.h>
103#elif defined(GLFW_EXPOSE_NATIVE_WAYLAND)
104 #include <wayland-client.h>
105#endif
106
107#if defined(GLFW_EXPOSE_NATIVE_WGL)
108 /* WGL is declared by windows.h */
109#endif
110#if defined(GLFW_EXPOSE_NATIVE_NSGL)
111 /* NSGL is declared by Cocoa.h */
112#endif
113#if defined(GLFW_EXPOSE_NATIVE_GLX)
114 #include <GL/glx.h>
115#endif
116#if defined(GLFW_EXPOSE_NATIVE_EGL)
117 #include <EGL/egl.h>
118#endif
119#if defined(GLFW_EXPOSE_NATIVE_OSMESA)
120 #include <GL/osmesa.h>
121#endif
122
123
124/*************************************************************************
125 * Functions
126 *************************************************************************/
127
128#if defined(GLFW_EXPOSE_NATIVE_WIN32)
129/*! @brief Returns the adapter device name of the specified monitor.
130 *
131 * @return The UTF-8 encoded adapter device name (for example `\\.\DISPLAY1`)
132 * of the specified monitor, or `NULL` if an [error](@ref error_handling)
133 * occurred.
134 *
135 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
136 *
137 * @thread_safety This function may be called from any thread. Access is not
138 * synchronized.
139 *
140 * @since Added in version 3.1.
141 *
142 * @ingroup native
143 */
144GLFWAPI const char* glfwGetWin32Adapter(GLFWmonitor* monitor);
145
146/*! @brief Returns the display device name of the specified monitor.
147 *
148 * @return The UTF-8 encoded display device name (for example
149 * `\\.\DISPLAY1\Monitor0`) of the specified monitor, or `NULL` if an
150 * [error](@ref error_handling) occurred.
151 *
152 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
153 *
154 * @thread_safety This function may be called from any thread. Access is not
155 * synchronized.
156 *
157 * @since Added in version 3.1.
158 *
159 * @ingroup native
160 */
161GLFWAPI const char* glfwGetWin32Monitor(GLFWmonitor* monitor);
162
163/*! @brief Returns the `HWND` of the specified window.
164 *
165 * @return The `HWND` of the specified window, or `NULL` if an
166 * [error](@ref error_handling) occurred.
167 *
168 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
169 *
170 * @remark The `HDC` associated with the window can be queried with the
171 * [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc)
172 * function.
173 * @code
174 * HDC dc = GetDC(glfwGetWin32Window(window));
175 * @endcode
176 * This DC is private and does not need to be released.
177 *
178 * @thread_safety This function may be called from any thread. Access is not
179 * synchronized.
180 *
181 * @since Added in version 3.0.
182 *
183 * @ingroup native
184 */
185GLFWAPI HWND glfwGetWin32Window(GLFWwindow* window);
186#endif
187
188#if defined(GLFW_EXPOSE_NATIVE_WGL)
189/*! @brief Returns the `HGLRC` of the specified window.
190 *
191 * @return The `HGLRC` of the specified window, or `NULL` if an
192 * [error](@ref error_handling) occurred.
193 *
194 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
195 * GLFW_NOT_INITIALIZED.
196 *
197 * @remark The `HDC` associated with the window can be queried with the
198 * [GetDC](https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-getdc)
199 * function.
200 * @code
201 * HDC dc = GetDC(glfwGetWin32Window(window));
202 * @endcode
203 * This DC is private and does not need to be released.
204 *
205 * @thread_safety This function may be called from any thread. Access is not
206 * synchronized.
207 *
208 * @since Added in version 3.0.
209 *
210 * @ingroup native
211 */
212GLFWAPI HGLRC glfwGetWGLContext(GLFWwindow* window);
213#endif
214
215#if defined(GLFW_EXPOSE_NATIVE_COCOA)
216/*! @brief Returns the `CGDirectDisplayID` of the specified monitor.
217 *
218 * @return The `CGDirectDisplayID` of the specified monitor, or
219 * `kCGNullDirectDisplay` if an [error](@ref error_handling) occurred.
220 *
221 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
222 *
223 * @thread_safety This function may be called from any thread. Access is not
224 * synchronized.
225 *
226 * @since Added in version 3.1.
227 *
228 * @ingroup native
229 */
230GLFWAPI CGDirectDisplayID glfwGetCocoaMonitor(GLFWmonitor* monitor);
231
232/*! @brief Returns the `NSWindow` of the specified window.
233 *
234 * @return The `NSWindow` of the specified window, or `nil` if an
235 * [error](@ref error_handling) occurred.
236 *
237 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
238 *
239 * @thread_safety This function may be called from any thread. Access is not
240 * synchronized.
241 *
242 * @since Added in version 3.0.
243 *
244 * @ingroup native
245 */
246GLFWAPI id glfwGetCocoaWindow(GLFWwindow* window);
247#endif
248
249#if defined(GLFW_EXPOSE_NATIVE_NSGL)
250/*! @brief Returns the `NSOpenGLContext` of the specified window.
251 *
252 * @return The `NSOpenGLContext` of the specified window, or `nil` if an
253 * [error](@ref error_handling) occurred.
254 *
255 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
256 * GLFW_NOT_INITIALIZED.
257 *
258 * @thread_safety This function may be called from any thread. Access is not
259 * synchronized.
260 *
261 * @since Added in version 3.0.
262 *
263 * @ingroup native
264 */
265GLFWAPI id glfwGetNSGLContext(GLFWwindow* window);
266#endif
267
268#if defined(GLFW_EXPOSE_NATIVE_X11)
269/*! @brief Returns the `Display` used by GLFW.
270 *
271 * @return The `Display` used by GLFW, or `NULL` if an
272 * [error](@ref error_handling) occurred.
273 *
274 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
275 *
276 * @thread_safety This function may be called from any thread. Access is not
277 * synchronized.
278 *
279 * @since Added in version 3.0.
280 *
281 * @ingroup native
282 */
283GLFWAPI Display* glfwGetX11Display(void);
284
285/*! @brief Returns the `RRCrtc` of the specified monitor.
286 *
287 * @return The `RRCrtc` of the specified monitor, or `None` if an
288 * [error](@ref error_handling) occurred.
289 *
290 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
291 *
292 * @thread_safety This function may be called from any thread. Access is not
293 * synchronized.
294 *
295 * @since Added in version 3.1.
296 *
297 * @ingroup native
298 */
299GLFWAPI RRCrtc glfwGetX11Adapter(GLFWmonitor* monitor);
300
301/*! @brief Returns the `RROutput` of the specified monitor.
302 *
303 * @return The `RROutput` of the specified monitor, or `None` if an
304 * [error](@ref error_handling) occurred.
305 *
306 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
307 *
308 * @thread_safety This function may be called from any thread. Access is not
309 * synchronized.
310 *
311 * @since Added in version 3.1.
312 *
313 * @ingroup native
314 */
315GLFWAPI RROutput glfwGetX11Monitor(GLFWmonitor* monitor);
316
317/*! @brief Returns the `Window` of the specified window.
318 *
319 * @return The `Window` of the specified window, or `None` if an
320 * [error](@ref error_handling) occurred.
321 *
322 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
323 *
324 * @thread_safety This function may be called from any thread. Access is not
325 * synchronized.
326 *
327 * @since Added in version 3.0.
328 *
329 * @ingroup native
330 */
331GLFWAPI Window glfwGetX11Window(GLFWwindow* window);
332
333/*! @brief Sets the current primary selection to the specified string.
334 *
335 * @param[in] string A UTF-8 encoded string.
336 *
337 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
338 * GLFW_PLATFORM_ERROR.
339 *
340 * @pointer_lifetime The specified string is copied before this function
341 * returns.
342 *
343 * @thread_safety This function must only be called from the main thread.
344 *
345 * @sa @ref clipboard
346 * @sa glfwGetX11SelectionString
347 * @sa glfwSetClipboardString
348 *
349 * @since Added in version 3.3.
350 *
351 * @ingroup native
352 */
353GLFWAPI void glfwSetX11SelectionString(const char* string);
354
355/*! @brief Returns the contents of the current primary selection as a string.
356 *
357 * If the selection is empty or if its contents cannot be converted, `NULL`
358 * is returned and a @ref GLFW_FORMAT_UNAVAILABLE error is generated.
359 *
360 * @return The contents of the selection as a UTF-8 encoded string, or `NULL`
361 * if an [error](@ref error_handling) occurred.
362 *
363 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
364 * GLFW_PLATFORM_ERROR.
365 *
366 * @pointer_lifetime The returned string is allocated and freed by GLFW. You
367 * should not free it yourself. It is valid until the next call to @ref
368 * glfwGetX11SelectionString or @ref glfwSetX11SelectionString, or until the
369 * library is terminated.
370 *
371 * @thread_safety This function must only be called from the main thread.
372 *
373 * @sa @ref clipboard
374 * @sa glfwSetX11SelectionString
375 * @sa glfwGetClipboardString
376 *
377 * @since Added in version 3.3.
378 *
379 * @ingroup native
380 */
381GLFWAPI const char* glfwGetX11SelectionString(void);
382#endif
383
384#if defined(GLFW_EXPOSE_NATIVE_GLX)
385/*! @brief Returns the `GLXContext` of the specified window.
386 *
387 * @return The `GLXContext` of the specified window, or `NULL` if an
388 * [error](@ref error_handling) occurred.
389 *
390 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
391 * GLFW_NOT_INITIALIZED.
392 *
393 * @thread_safety This function may be called from any thread. Access is not
394 * synchronized.
395 *
396 * @since Added in version 3.0.
397 *
398 * @ingroup native
399 */
400GLFWAPI GLXContext glfwGetGLXContext(GLFWwindow* window);
401
402/*! @brief Returns the `GLXWindow` of the specified window.
403 *
404 * @return The `GLXWindow` of the specified window, or `None` if an
405 * [error](@ref error_handling) occurred.
406 *
407 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
408 * GLFW_NOT_INITIALIZED.
409 *
410 * @thread_safety This function may be called from any thread. Access is not
411 * synchronized.
412 *
413 * @since Added in version 3.2.
414 *
415 * @ingroup native
416 */
417GLFWAPI GLXWindow glfwGetGLXWindow(GLFWwindow* window);
418#endif
419
420#if defined(GLFW_EXPOSE_NATIVE_WAYLAND)
421/*! @brief Returns the `struct wl_display*` used by GLFW.
422 *
423 * @return The `struct wl_display*` used by GLFW, or `NULL` if an
424 * [error](@ref error_handling) occurred.
425 *
426 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
427 *
428 * @thread_safety This function may be called from any thread. Access is not
429 * synchronized.
430 *
431 * @since Added in version 3.2.
432 *
433 * @ingroup native
434 */
435GLFWAPI struct wl_display* glfwGetWaylandDisplay(void);
436
437/*! @brief Returns the `struct wl_output*` of the specified monitor.
438 *
439 * @return The `struct wl_output*` of the specified monitor, or `NULL` if an
440 * [error](@ref error_handling) occurred.
441 *
442 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
443 *
444 * @thread_safety This function may be called from any thread. Access is not
445 * synchronized.
446 *
447 * @since Added in version 3.2.
448 *
449 * @ingroup native
450 */
451GLFWAPI struct wl_output* glfwGetWaylandMonitor(GLFWmonitor* monitor);
452
453/*! @brief Returns the main `struct wl_surface*` of the specified window.
454 *
455 * @return The main `struct wl_surface*` of the specified window, or `NULL` if
456 * an [error](@ref error_handling) occurred.
457 *
458 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
459 *
460 * @thread_safety This function may be called from any thread. Access is not
461 * synchronized.
462 *
463 * @since Added in version 3.2.
464 *
465 * @ingroup native
466 */
467GLFWAPI struct wl_surface* glfwGetWaylandWindow(GLFWwindow* window);
468#endif
469
470#if defined(GLFW_EXPOSE_NATIVE_EGL)
471/*! @brief Returns the `EGLDisplay` used by GLFW.
472 *
473 * @return The `EGLDisplay` used by GLFW, or `EGL_NO_DISPLAY` if an
474 * [error](@ref error_handling) occurred.
475 *
476 * @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
477 *
478 * @thread_safety This function may be called from any thread. Access is not
479 * synchronized.
480 *
481 * @since Added in version 3.0.
482 *
483 * @ingroup native
484 */
485GLFWAPI EGLDisplay glfwGetEGLDisplay(void);
486
487/*! @brief Returns the `EGLContext` of the specified window.
488 *
489 * @return The `EGLContext` of the specified window, or `EGL_NO_CONTEXT` if an
490 * [error](@ref error_handling) occurred.
491 *
492 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
493 * GLFW_NOT_INITIALIZED.
494 *
495 * @thread_safety This function may be called from any thread. Access is not
496 * synchronized.
497 *
498 * @since Added in version 3.0.
499 *
500 * @ingroup native
501 */
502GLFWAPI EGLContext glfwGetEGLContext(GLFWwindow* window);
503
504/*! @brief Returns the `EGLSurface` of the specified window.
505 *
506 * @return The `EGLSurface` of the specified window, or `EGL_NO_SURFACE` if an
507 * [error](@ref error_handling) occurred.
508 *
509 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
510 * GLFW_NOT_INITIALIZED.
511 *
512 * @thread_safety This function may be called from any thread. Access is not
513 * synchronized.
514 *
515 * @since Added in version 3.0.
516 *
517 * @ingroup native
518 */
519GLFWAPI EGLSurface glfwGetEGLSurface(GLFWwindow* window);
520#endif
521
522#if defined(GLFW_EXPOSE_NATIVE_OSMESA)
523/*! @brief Retrieves the color buffer associated with the specified window.
524 *
525 * @param[in] window The window whose color buffer to retrieve.
526 * @param[out] width Where to store the width of the color buffer, or `NULL`.
527 * @param[out] height Where to store the height of the color buffer, or `NULL`.
528 * @param[out] format Where to store the OSMesa pixel format of the color
529 * buffer, or `NULL`.
530 * @param[out] buffer Where to store the address of the color buffer, or
531 * `NULL`.
532 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
533 * [error](@ref error_handling) occurred.
534 *
535 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
536 * GLFW_NOT_INITIALIZED.
537 *
538 * @thread_safety This function may be called from any thread. Access is not
539 * synchronized.
540 *
541 * @since Added in version 3.3.
542 *
543 * @ingroup native
544 */
545GLFWAPI int glfwGetOSMesaColorBuffer(GLFWwindow* window, int* width, int* height, int* format, void** buffer);
546
547/*! @brief Retrieves the depth buffer associated with the specified window.
548 *
549 * @param[in] window The window whose depth buffer to retrieve.
550 * @param[out] width Where to store the width of the depth buffer, or `NULL`.
551 * @param[out] height Where to store the height of the depth buffer, or `NULL`.
552 * @param[out] bytesPerValue Where to store the number of bytes per depth
553 * buffer element, or `NULL`.
554 * @param[out] buffer Where to store the address of the depth buffer, or
555 * `NULL`.
556 * @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
557 * [error](@ref error_handling) occurred.
558 *
559 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
560 * GLFW_NOT_INITIALIZED.
561 *
562 * @thread_safety This function may be called from any thread. Access is not
563 * synchronized.
564 *
565 * @since Added in version 3.3.
566 *
567 * @ingroup native
568 */
569GLFWAPI int glfwGetOSMesaDepthBuffer(GLFWwindow* window, int* width, int* height, int* bytesPerValue, void** buffer);
570
571/*! @brief Returns the `OSMesaContext` of the specified window.
572 *
573 * @return The `OSMesaContext` of the specified window, or `NULL` if an
574 * [error](@ref error_handling) occurred.
575 *
576 * @errors Possible errors include @ref GLFW_NO_WINDOW_CONTEXT and @ref
577 * GLFW_NOT_INITIALIZED.
578 *
579 * @thread_safety This function may be called from any thread. Access is not
580 * synchronized.
581 *
582 * @since Added in version 3.3.
583 *
584 * @ingroup native
585 */
586GLFWAPI OSMesaContext glfwGetOSMesaContext(GLFWwindow* window);
587#endif
588
589#ifdef __cplusplus
590}
591#endif
592
593#endif /* _glfw3_native_h_ */
594