diff options
author | marsunet <marc.sunet@amd.com> | 2021-12-21 17:04:22 -0800 |
---|---|---|
committer | marsunet <marc.sunet@amd.com> | 2021-12-21 17:04:22 -0800 |
commit | fba8184491e0b7ae6fab7ac01b4600d230dc4569 (patch) | |
tree | c13194764867a4ad8f46702356b22dccc1e56dd3 /contrib/glfw/glfw-3.3.5.bin.WIN64/include | |
parent | 8b1583b65d77188ef35a89e75f145f29c3e3b5d7 (diff) |
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.h | 5907 | ||||
-rw-r--r-- | contrib/glfw/glfw-3.3.5.bin.WIN64/include/GLFW/glfw3native.h | 594 |
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 | ||
33 | extern "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 | */ | ||
1148 | typedef 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 | */ | ||
1162 | typedef 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 | */ | ||
1174 | typedef 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 | */ | ||
1186 | typedef 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 | */ | ||
1198 | typedef 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 | */ | ||
1222 | typedef 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 | */ | ||
1245 | typedef 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 | */ | ||
1267 | typedef 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 | */ | ||
1287 | typedef 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 | */ | ||
1307 | typedef 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 | */ | ||
1328 | typedef 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 | */ | ||
1349 | typedef 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 | */ | ||
1370 | typedef 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 | */ | ||
1391 | typedef 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 | */ | ||
1412 | typedef 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 | */ | ||
1438 | typedef 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 | */ | ||
1461 | typedef 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 | */ | ||
1482 | typedef 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 | */ | ||
1503 | typedef 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 | */ | ||
1529 | typedef 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 | */ | ||
1550 | typedef 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 | */ | ||
1577 | typedef 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 | */ | ||
1601 | typedef 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 | */ | ||
1622 | typedef 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 | */ | ||
1643 | typedef 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 | */ | ||
1658 | typedef 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 | */ | ||
1692 | typedef 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 | */ | ||
1721 | typedef 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 | */ | ||
1745 | typedef 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 | */ | ||
1798 | GLFWAPI 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 | */ | ||
1832 | GLFWAPI 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 | */ | ||
1864 | GLFWAPI 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 | */ | ||
1891 | GLFWAPI 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 | */ | ||
1922 | GLFWAPI 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 | */ | ||
1953 | GLFWAPI 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 | */ | ||
1999 | GLFWAPI 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 | */ | ||
2028 | GLFWAPI 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 | */ | ||
2052 | GLFWAPI 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 | */ | ||
2077 | GLFWAPI 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 | */ | ||
2108 | GLFWAPI 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 | */ | ||
2142 | GLFWAPI 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 | */ | ||
2174 | GLFWAPI 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 | */ | ||
2200 | GLFWAPI 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 | */ | ||
2226 | GLFWAPI 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 | */ | ||
2250 | GLFWAPI 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 | */ | ||
2280 | GLFWAPI 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 | */ | ||
2314 | GLFWAPI 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 | */ | ||
2342 | GLFWAPI 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 | */ | ||
2375 | GLFWAPI 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 | */ | ||
2405 | GLFWAPI 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 | */ | ||
2446 | GLFWAPI 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 | */ | ||
2465 | GLFWAPI 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 | */ | ||
2500 | GLFWAPI 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 | */ | ||
2538 | GLFWAPI 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 | */ | ||
2692 | GLFWAPI 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 | */ | ||
2721 | GLFWAPI 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 | */ | ||
2741 | GLFWAPI 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 | */ | ||
2763 | GLFWAPI 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 | */ | ||
2788 | GLFWAPI 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 | */ | ||
2835 | GLFWAPI 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 | */ | ||
2867 | GLFWAPI 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 | */ | ||
2902 | GLFWAPI 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 | */ | ||
2932 | GLFWAPI 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 | */ | ||
2975 | GLFWAPI 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 | */ | ||
3018 | GLFWAPI 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 | */ | ||
3059 | GLFWAPI 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 | */ | ||
3088 | GLFWAPI 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 | */ | ||
3125 | GLFWAPI 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 | */ | ||
3158 | GLFWAPI 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 | */ | ||
3185 | GLFWAPI 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 | */ | ||
3214 | GLFWAPI 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 | */ | ||
3245 | GLFWAPI 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 | */ | ||
3272 | GLFWAPI 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 | */ | ||
3297 | GLFWAPI 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 | */ | ||
3324 | GLFWAPI 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 | */ | ||
3346 | GLFWAPI 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 | */ | ||
3385 | GLFWAPI 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 | */ | ||
3412 | GLFWAPI 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 | */ | ||
3434 | GLFWAPI 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 | */ | ||
3493 | GLFWAPI 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 | */ | ||
3527 | GLFWAPI 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 | */ | ||
3564 | GLFWAPI 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 | */ | ||
3587 | GLFWAPI 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 | */ | ||
3608 | GLFWAPI 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 | */ | ||
3643 | GLFWAPI 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 | */ | ||
3675 | GLFWAPI 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 | */ | ||
3715 | GLFWAPI 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 | */ | ||
3751 | GLFWAPI 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 | */ | ||
3786 | GLFWAPI 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 | */ | ||
3819 | GLFWAPI 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 | */ | ||
3849 | GLFWAPI 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 | */ | ||
3879 | GLFWAPI 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 | */ | ||
3910 | GLFWAPI 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 | */ | ||
3948 | GLFWAPI 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 | */ | ||
3993 | GLFWAPI 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 | */ | ||
4042 | GLFWAPI 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 | */ | ||
4062 | GLFWAPI 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 | */ | ||
4087 | GLFWAPI 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 | */ | ||
4149 | GLFWAPI 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 | */ | ||
4178 | GLFWAPI 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 | */ | ||
4246 | GLFWAPI 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 | */ | ||
4270 | GLFWAPI 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 | */ | ||
4310 | GLFWAPI 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 | */ | ||
4339 | GLFWAPI 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 | */ | ||
4377 | GLFWAPI 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 | */ | ||
4417 | GLFWAPI 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 | */ | ||
4455 | GLFWAPI 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 | */ | ||
4478 | GLFWAPI 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 | */ | ||
4505 | GLFWAPI 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 | */ | ||
4532 | GLFWAPI 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 | */ | ||
4582 | GLFWAPI 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 | */ | ||
4625 | GLFWAPI 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 | */ | ||
4667 | GLFWAPI 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 | */ | ||
4704 | GLFWAPI 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 | */ | ||
4736 | GLFWAPI 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 | */ | ||
4767 | GLFWAPI 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 | */ | ||
4801 | GLFWAPI 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 | */ | ||
4838 | GLFWAPI 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 | */ | ||
4862 | GLFWAPI 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 | */ | ||
4895 | GLFWAPI 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 | */ | ||
4936 | GLFWAPI 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 | */ | ||
4993 | GLFWAPI 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 | */ | ||
5024 | GLFWAPI 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 | */ | ||
5065 | GLFWAPI 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 | */ | ||
5091 | GLFWAPI 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 | */ | ||
5115 | GLFWAPI 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 | */ | ||
5143 | GLFWAPI 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 | */ | ||
5179 | GLFWAPI 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 | */ | ||
5213 | GLFWAPI 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 | */ | ||
5243 | GLFWAPI 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 | */ | ||
5281 | GLFWAPI 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 | */ | ||
5306 | GLFWAPI 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 | */ | ||
5336 | GLFWAPI 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 | */ | ||
5366 | GLFWAPI 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 | */ | ||
5396 | GLFWAPI 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 / 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 | */ | ||
5418 | GLFWAPI 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 | */ | ||
5438 | GLFWAPI 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 | */ | ||
5476 | GLFWAPI 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 | */ | ||
5497 | GLFWAPI 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 | */ | ||
5531 | GLFWAPI 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 | */ | ||
5577 | GLFWAPI 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 | */ | ||
5615 | GLFWAPI 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 | */ | ||
5657 | GLFWAPI 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 | */ | ||
5683 | GLFWAPI 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 | */ | ||
5730 | GLFWAPI 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 | */ | ||
5773 | GLFWAPI 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 | */ | ||
5810 | GLFWAPI 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 | */ | ||
5871 | GLFWAPI 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 | ||
33 | extern "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 | */ | ||
144 | GLFWAPI 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 | */ | ||
161 | GLFWAPI 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 | */ | ||
185 | GLFWAPI 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 | */ | ||
212 | GLFWAPI 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 | */ | ||
230 | GLFWAPI 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 | */ | ||
246 | GLFWAPI 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 | */ | ||
265 | GLFWAPI 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 | */ | ||
283 | GLFWAPI 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 | */ | ||
299 | GLFWAPI 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 | */ | ||
315 | GLFWAPI 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 | */ | ||
331 | GLFWAPI 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 | */ | ||
353 | GLFWAPI 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 | */ | ||
381 | GLFWAPI 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 | */ | ||
400 | GLFWAPI 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 | */ | ||
417 | GLFWAPI 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 | */ | ||
435 | GLFWAPI 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 | */ | ||
451 | GLFWAPI 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 | */ | ||
467 | GLFWAPI 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 | */ | ||
485 | GLFWAPI 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 | */ | ||
502 | GLFWAPI 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 | */ | ||
519 | GLFWAPI 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 | */ | ||
545 | GLFWAPI 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 | */ | ||
569 | GLFWAPI 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 | */ | ||
586 | GLFWAPI OSMesaContext glfwGetOSMesaContext(GLFWwindow* window); | ||
587 | #endif | ||
588 | |||
589 | #ifdef __cplusplus | ||
590 | } | ||
591 | #endif | ||
592 | |||
593 | #endif /* _glfw3_native_h_ */ | ||
594 | |||