1/*! 2 3@page intro_guide Introduction to the API 4 5@tableofcontents 6 7This guide introduces the basic concepts of GLFW and describes initialization, 8error handling and API guarantees and limitations. For a broad but shallow 9tutorial, see @ref quick_guide instead. For details on a specific function in 10this category, see the @ref init. 11 12There are also guides for the other areas of GLFW. 13 14 - @ref window_guide 15 - @ref context_guide 16 - @ref vulkan_guide 17 - @ref monitor_guide 18 - @ref input_guide 19 20 21@section intro_init Initialization and termination 22 23Before most GLFW functions may be called, the library must be initialized. 24This initialization checks what features are available on the machine, 25enumerates monitors and joysticks, initializes the timer and performs any 26required platform-specific initialization. 27 28Only the following functions may be called before the library has been 29successfully initialized, and only from the main thread. 30 31 - @ref glfwGetVersion 32 - @ref glfwGetVersionString 33 - @ref glfwGetError 34 - @ref glfwSetErrorCallback 35 - @ref glfwInitHint 36 - @ref glfwInit 37 - @ref glfwTerminate 38 39Calling any other function before successful initialization will cause a @ref 40GLFW_NOT_INITIALIZED error. 41 42 43@subsection intro_init_init Initializing GLFW 44 45The library is initialized with @ref glfwInit, which returns `GLFW_FALSE` if an 46error occurred. 47 48@code 49if (!glfwInit()) 50{ 51 // Handle initialization failure 52} 53@endcode 54 55If any part of initialization fails, any parts that succeeded are terminated as 56if @ref glfwTerminate had been called. The library only needs to be initialized 57once and additional calls to an already initialized library will return 58`GLFW_TRUE` immediately. 59 60Once the library has been successfully initialized, it should be terminated 61before the application exits. Modern systems are very good at freeing resources 62allocated by programs that exit, but GLFW sometimes has to change global system 63settings and these might not be restored without termination. 64 65 66@subsection init_hints Initialization hints 67 68Initialization hints are set before @ref glfwInit and affect how the library 69behaves until termination. Hints are set with @ref glfwInitHint. 70 71@code 72glfwInitHint(GLFW_JOYSTICK_HAT_BUTTONS, GLFW_FALSE); 73@endcode 74 75The values you set hints to are never reset by GLFW, but they only take effect 76during initialization. Once GLFW has been initialized, any values you set will 77be ignored until the library is terminated and initialized again. 78 79Some hints are platform specific. These may be set on any platform but they 80will only affect their specific platform. Other platforms will ignore them. 81Setting these hints requires no platform specific headers or functions. 82 83 84@subsubsection init_hints_shared Shared init hints 85 86@anchor GLFW_JOYSTICK_HAT_BUTTONS 87__GLFW_JOYSTICK_HAT_BUTTONS__ specifies whether to also expose joystick hats as 88buttons, for compatibility with earlier versions of GLFW that did not have @ref 89glfwGetJoystickHats. Set this with @ref glfwInitHint. 90 91 92@subsubsection init_hints_osx macOS specific init hints 93 94@anchor GLFW_COCOA_CHDIR_RESOURCES_hint 95__GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to 96the application to the `Contents/Resources` subdirectory of the application's 97bundle, if present. Set this with @ref glfwInitHint. 98 99@anchor GLFW_COCOA_MENUBAR_hint 100__GLFW_COCOA_MENUBAR__ specifies whether to create a basic menu bar, either from 101a nib or manually, when the first window is created, which is when AppKit is 102initialized. Set this with @ref glfwInitHint. 103 104 105@subsubsection init_hints_values Supported and default values 106 107Initialization hint | Default value | Supported values 108------------------------------- | ------------- | ---------------- 109@ref GLFW_JOYSTICK_HAT_BUTTONS | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` 110@ref GLFW_COCOA_CHDIR_RESOURCES | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` 111@ref GLFW_COCOA_MENUBAR | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` 112 113 114@subsection intro_init_terminate Terminating GLFW 115 116Before your application exits, you should terminate the GLFW library if it has 117been initialized. This is done with @ref glfwTerminate. 118 119@code 120glfwTerminate(); 121@endcode 122 123This will destroy any remaining window, monitor and cursor objects, restore any 124modified gamma ramps, re-enable the screensaver if it had been disabled and free 125any other resources allocated by GLFW. 126 127Once the library is terminated, it is as if it had never been initialized and 128you will need to initialize it again before being able to use GLFW. If the 129library was not initialized or had already been terminated, it return 130immediately. 131 132 133@section error_handling Error handling 134 135Some GLFW functions have return values that indicate an error, but this is often 136not very helpful when trying to figure out what happened or why it occurred. 137Other functions have no return value reserved for errors, so error notification 138needs a separate channel. Finally, far from all GLFW functions have return 139values. 140 141The last [error code](@ref errors) for the calling thread can be queried at any 142time with @ref glfwGetError. 143 144@code 145int code = glfwGetError(NULL); 146 147if (code != GLFW_NO_ERROR) 148 handle_error(code); 149@endcode 150 151If no error has occurred since the last call, @ref GLFW_NO_ERROR (zero) is 152returned. The error is cleared before the function returns. 153 154The error code indicates the general category of the error. Some error codes, 155such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like 156@ref GLFW_PLATFORM_ERROR are used for many different errors. 157 158GLFW often has more information about an error than its general category. You 159can retrieve a UTF-8 encoded human-readable description along with the error 160code. If no error has occurred since the last call, the description is set to 161`NULL`. 162 163@code 164const char* description; 165int code = glfwGetError(&description); 166 167if (description) 168 display_error_message(code, description); 169@endcode 170 171The retrieved description string is only valid until the next error occurs. 172This means you must make a copy of it if you want to keep it. 173 174You can also set an error callback, which will be called each time an error 175occurs. It is set with @ref glfwSetErrorCallback. 176 177@code 178glfwSetErrorCallback(error_callback); 179@endcode 180 181The error callback receives the same error code and human-readable description 182returned by @ref glfwGetError. 183 184@code 185void error_callback(int code, const char* description) 186{ 187 display_error_message(code, description); 188} 189@endcode 190 191The error callback is called after the error is stored, so calling @ref 192glfwGetError from within the error callback returns the same values as the 193callback argument. 194 195The description string passed to the callback is only valid until the error 196callback returns. This means you must make a copy of it if you want to keep it. 197 198__Reported errors are never fatal.__ As long as GLFW was successfully 199initialized, it will remain initialized and in a safe state until terminated 200regardless of how many errors occur. If an error occurs during initialization 201that causes @ref glfwInit to fail, any part of the library that was initialized 202will be safely terminated. 203 204Do not rely on a currently invalid call to generate a specific error, as in the 205future that same call may generate a different error or become valid. 206 207 208@section coordinate_systems Coordinate systems 209 210GLFW has two primary coordinate systems: the _virtual screen_ and the window 211_content area_ or _content area_. Both use the same unit: _virtual screen 212coordinates_, or just _screen coordinates_, which don't necessarily correspond 213to pixels. 214 215<img src="spaces.svg" width="90%" /> 216 217Both the virtual screen and the content area coordinate systems have the X-axis 218pointing to the right and the Y-axis pointing down. 219 220Window and monitor positions are specified as the position of the upper-left 221corners of their content areas relative to the virtual screen, while cursor 222positions are specified relative to a window's content area. 223 224Because the origin of the window's content area coordinate system is also the 225point from which the window position is specified, you can translate content 226area coordinates to the virtual screen by adding the window position. The 227window frame, when present, extends out from the content area but does not 228affect the window position. 229 230Almost all positions and sizes in GLFW are measured in screen coordinates 231relative to one of the two origins above. This includes cursor positions, 232window positions and sizes, window frame sizes, monitor positions and video mode 233resolutions. 234 235Two exceptions are the [monitor physical size](@ref monitor_size), which is 236measured in millimetres, and [framebuffer size](@ref window_fbsize), which is 237measured in pixels. 238 239Pixels and screen coordinates may map 1:1 on your machine, but they won't on 240every other machine, for example on a Mac with a Retina display. The ratio 241between screen coordinates and pixels may also change at run-time depending on 242which monitor the window is currently considered to be on. 243 244 245@section guarantees_limitations Guarantees and limitations 246 247This section describes the conditions under which GLFW can be expected to 248function, barring bugs in the operating system or drivers. Use of GLFW outside 249of these limits may work on some platforms, or on some machines, or some of the 250time, or on some versions of GLFW, but it may break at any time and this will 251not be considered a bug. 252 253 254@subsection lifetime Pointer lifetimes 255 256GLFW will never free any pointer you provide to it and you must never free any 257pointer it provides to you. 258 259Many GLFW functions return pointers to dynamically allocated structures, strings 260or arrays, and some callbacks are provided with strings or arrays. These are 261always managed by GLFW and should never be freed by the application. The 262lifetime of these pointers is documented for each GLFW function and callback. 263If you need to keep this data, you must copy it before its lifetime expires. 264 265Many GLFW functions accept pointers to structures or strings allocated by the 266application. These are never freed by GLFW and are always the responsibility of 267the application. If GLFW needs to keep the data in these structures or strings, 268it is copied before the function returns. 269 270Pointer lifetimes are guaranteed not to be shortened in future minor or patch 271releases. 272 273 274@subsection reentrancy Reentrancy 275 276GLFW event processing and object destruction are not reentrant. This means that 277the following functions must not be called from any callback function: 278 279 - @ref glfwDestroyWindow 280 - @ref glfwDestroyCursor 281 - @ref glfwPollEvents 282 - @ref glfwWaitEvents 283 - @ref glfwWaitEventsTimeout 284 - @ref glfwTerminate 285 286These functions may be made reentrant in future minor or patch releases, but 287functions not on this list will not be made non-reentrant. 288 289 290@subsection thread_safety Thread safety 291 292Most GLFW functions must only be called from the main thread (the thread that 293calls main), but some may be called from any thread once the library has been 294initialized. Before initialization the whole library is thread-unsafe. 295 296The reference documentation for every GLFW function states whether it is limited 297to the main thread. 298 299Initialization, termination, event processing and the creation and 300destruction of windows, cursors and OpenGL and OpenGL ES contexts are all 301restricted to the main thread due to limitations of one or several platforms. 302 303Because event processing must be performed on the main thread, all callbacks 304except for the error callback will only be called on that thread. The error 305callback may be called on any thread, as any GLFW function may generate errors. 306 307The error code and description may be queried from any thread. 308 309 - @ref glfwGetError 310 311Empty events may be posted from any thread. 312 313 - @ref glfwPostEmptyEvent 314 315The window user pointer and close flag may be read and written from any thread, 316but this is not synchronized by GLFW. 317 318 - @ref glfwGetWindowUserPointer 319 - @ref glfwSetWindowUserPointer 320 - @ref glfwWindowShouldClose 321 - @ref glfwSetWindowShouldClose 322 323These functions for working with OpenGL and OpenGL ES contexts may be called 324from any thread, but the window object is not synchronized by GLFW. 325 326 - @ref glfwMakeContextCurrent 327 - @ref glfwGetCurrentContext 328 - @ref glfwSwapBuffers 329 - @ref glfwSwapInterval 330 - @ref glfwExtensionSupported 331 - @ref glfwGetProcAddress 332 333The raw timer functions may be called from any thread. 334 335 - @ref glfwGetTimerFrequency 336 - @ref glfwGetTimerValue 337 338The regular timer may be used from any thread, but reading and writing the timer 339offset is not synchronized by GLFW. 340 341 - @ref glfwGetTime 342 - @ref glfwSetTime 343 344Library version information may be queried from any thread. 345 346 - @ref glfwGetVersion 347 - @ref glfwGetVersionString 348 349All Vulkan related functions may be called from any thread. 350 351 - @ref glfwVulkanSupported 352 - @ref glfwGetRequiredInstanceExtensions 353 - @ref glfwGetInstanceProcAddress 354 - @ref glfwGetPhysicalDevicePresentationSupport 355 - @ref glfwCreateWindowSurface 356 357GLFW uses synchronization objects internally only to manage the per-thread 358context and error states. Additional synchronization is left to the 359application. 360 361Functions that may currently be called from any thread will always remain so, 362but functions that are currently limited to the main thread may be updated to 363allow calls from any thread in future releases. 364 365 366@subsection compatibility Version compatibility 367 368GLFW uses [Semantic Versioning](https://semver.org/). This guarantees source 369and binary backward compatibility with earlier minor versions of the API. This 370means that you can drop in a newer version of the library and existing programs 371will continue to compile and existing binaries will continue to run. 372 373Once a function or constant has been added, the signature of that function or 374value of that constant will remain unchanged until the next major version of 375GLFW. No compatibility of any kind is guaranteed between major versions. 376 377Undocumented behavior, i.e. behavior that is not described in the documentation, 378may change at any time until it is documented. 379 380If the reference documentation and the implementation differ, the reference 381documentation will almost always take precedence and the implementation will be 382fixed in the next release. The reference documentation will also take 383precedence over anything stated in a guide. 384 385 386@subsection event_order Event order 387 388The order of arrival of related events is not guaranteed to be consistent 389across platforms. The exception is synthetic key and mouse button release 390events, which are always delivered after the window defocus event. 391 392 393@section intro_version Version management 394 395GLFW provides mechanisms for identifying what version of GLFW your application 396was compiled against as well as what version it is currently running against. 397If you are loading GLFW dynamically (not just linking dynamically), you can use 398this to verify that the library binary is compatible with your application. 399 400 401@subsection intro_version_compile Compile-time version 402 403The compile-time version of GLFW is provided by the GLFW header with the 404`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros. 405 406@code 407printf("Compiled against GLFW %i.%i.%i\n", 408 GLFW_VERSION_MAJOR, 409 GLFW_VERSION_MINOR, 410 GLFW_VERSION_REVISION); 411@endcode 412 413 414@subsection intro_version_runtime Run-time version 415 416The run-time version can be retrieved with @ref glfwGetVersion, a function that 417may be called regardless of whether GLFW is initialized. 418 419@code 420int major, minor, revision; 421glfwGetVersion(&major, &minor, &revision); 422 423printf("Running against GLFW %i.%i.%i\n", major, minor, revision); 424@endcode 425 426 427@subsection intro_version_string Version string 428 429GLFW 3 also provides a compile-time generated version string that describes the 430version, platform, compiler and any platform-specific compile-time options. 431This is primarily intended for submitting bug reports, to allow developers to 432see which code paths are enabled in a binary. 433 434The version string is returned by @ref glfwGetVersionString, a function that may 435be called regardless of whether GLFW is initialized. 436 437__Do not use the version string__ to parse the GLFW library version. The @ref 438glfwGetVersion function already provides the version of the running library 439binary. 440 441The format of the string is as follows: 442 - The version of GLFW 443 - The name of the window system API 444 - The name of the context creation API 445 - Any additional options or APIs 446 447For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL 448back ends, the version string may look something like this: 449 450@code 4513.0.0 Win32 WGL MinGW 452@endcode 453 454*/ 455