Initial Commit

1 files changed, 372 insertions, 0 deletions

diff --git a/glfw-3.2.1/docs/intro.dox b/glfw-3.2.1/docs/intro.dox
new file mode 100644
index 0000000..f784080
--- /dev/null
+++ b/glfw-3.2.1/docs/intro.dox
@@ -0,0 +1,372 @@
+/*! 
+
+@page intro_guide Introduction to the API
+ 
+@tableofcontents
+
+This guide introduces the basic concepts of GLFW and describes initialization,
+error handling and API guarantees and limitations.  For a broad but shallow
+tutorial, see @ref quick_guide instead.  For details on a specific function in
+this category, see the @ref init.
+
+There are also guides for the other areas of GLFW.
+
+ - @ref window_guide
+ - @ref context_guide
+ - @ref vulkan_guide
+ - @ref monitor_guide
+ - @ref input_guide
+
+
+@section intro_init Initialization and termination
+
+Before most GLFW functions may be called, the library must be initialized.
+This initialization checks what features are available on the machine,
+enumerates monitors and joysticks, initializes the timer and performs any
+required platform-specific initialization.
+
+Only the following functions may be called before the library has been
+successfully initialized, and only from the main thread.
+
+ - @ref glfwGetVersion
+ - @ref glfwGetVersionString
+ - @ref glfwSetErrorCallback
+ - @ref glfwInit
+ - @ref glfwTerminate
+
+Calling any other function before successful initialization will cause a @ref
+GLFW_NOT_INITIALIZED error.
+
+
+@subsection intro_init_init Initializing GLFW
+
+The library is initialized with @ref glfwInit, which returns `GLFW_FALSE` if an
+error occurred.
+
+@code
+if (!glfwInit())
+{
+    // Handle initialization failure
+}
+@endcode
+
+If any part of initialization fails, any parts that succeeded are terminated as
+if @ref glfwTerminate had been called.  The library only needs to be initialized
+once and additional calls to an already initialized library will simply return
+`GLFW_TRUE` immediately.
+
+Once the library has been successfully initialized, it should be terminated
+before the application exits.  Modern systems are very good at freeing resources
+allocated by programs that simply exit, but GLFW sometimes has to change global
+system settings and these might not be restored without termination.
+
+
+@subsection intro_init_terminate Terminating GLFW
+
+Before your application exits, you should terminate the GLFW library if it has
+been initialized.  This is done with @ref glfwTerminate.
+
+@code
+glfwTerminate();
+@endcode
+
+This will destroy any remaining window, monitor and cursor objects, restore any
+modified gamma ramps, re-enable the screensaver if it had been disabled and free
+any other resources allocated by GLFW.
+
+Once the library is terminated, it is as if it had never been initialized and
+you will need to initialize it again before being able to use GLFW.  If the
+library was not initialized or had already been terminated, it return
+immediately. 
+
+
+@section error_handling Error handling
+
+Some GLFW functions have return values that indicate an error, but this is often
+not very helpful when trying to figure out _why_ the error occurred.  Some
+functions also return otherwise valid values on error.  Finally, far from all
+GLFW functions have return values.
+
+This is where the error callback comes in.  This callback is called whenever an
+error occurs.  It is set with @ref glfwSetErrorCallback, a function that may be
+called regardless of whether GLFW is initialized.
+
+@code
+glfwSetErrorCallback(error_callback);
+@endcode
+
+The error callback receives a human-readable description of the error and (when
+possible) its cause.  The description encoded as UTF-8.  The callback is also
+provided with an [error code](@ref errors). 
+
+@code
+void error_callback(int error, const char* description)
+{
+    puts(description);
+}
+@endcode
+
+The error code indicates the general category of the error.  Some error codes,
+such as @ref GLFW_NOT_INITIALIZED has only a single meaning, whereas others like
+@ref GLFW_PLATFORM_ERROR are used for many different errors.
+
+The description string is only valid until the error callback returns, as it may
+have been generated specifically for that error.  This lets GLFW provide much
+more specific error descriptions but means you must make a copy if you want to
+keep the description string.
+
+@note Relying on erroneous behavior is not forward compatible.  In other words,
+do not rely on a currently invalid call to generate a specific error, as that
+same call may in future versions generate a different error or become valid.
+
+
+@section coordinate_systems Coordinate systems
+
+GLFW has two primary coordinate systems: the _virtual screen_ and the window
+_client area_ or _content area_.  Both use the same unit: _virtual screen
+coordinates_, or just _screen coordinates_, which don't necessarily correspond
+to pixels.
+
+<img src="spaces.svg" width="90%" />
+
+Both the virtual screen and the client area coordinate systems have the X-axis
+pointing to the right and the Y-axis pointing down.
+
+Window and monitor positions are specified as the position of the upper-left
+corners of their content areas relative to the virtual screen, while cursor
+positions are specified relative to a window's client area.
+
+Because the origin of the window's client area coordinate system is also the
+point from which the window position is specified, you can translate client area
+coordinates to the virtual screen by adding the window position.  The window
+frame, when present, extends out from the client area but does not affect the
+window position.
+
+Almost all positions and sizes in GLFW are measured in screen coordinates
+relative to one of the two origins above.  This includes cursor positions,
+window positions and sizes, window frame sizes, monitor positions and video mode
+resolutions.
+
+Two exceptions are the [monitor physical size](@ref monitor_size), which is
+measured in millimetres, and [framebuffer size](@ref window_fbsize), which is
+measured in pixels.
+
+Pixels and screen coordinates may map 1:1 on your machine, but they won't on
+every other machine, for example on a Mac with a Retina display.  The ratio
+between screen coordinates and pixels may also change at run-time depending on
+which monitor the window is currently considered to be on.
+
+
+@section guarantees_limitations Guarantees and limitations
+
+This section describes the conditions under which GLFW can be expected to
+function, barring bugs in the operating system or drivers.  Use of GLFW outside
+of these limits may work on some platforms, or on some machines, or some of the
+time, or on some versions of GLFW, but it may break at any time and this will
+not be considered a bug.
+
+
+@subsection lifetime Pointer lifetimes
+
+GLFW will never free any pointer you provide to it and you must never free any
+pointer it provides to you.
+
+Many GLFW functions return pointers to dynamically allocated structures, strings
+or arrays, and some callbacks are provided with strings or arrays.  These are
+always managed by GLFW and should never be freed by the application.  The
+lifetime of these pointers is documented for each GLFW function and callback.
+If you need to keep this data, you must copy it before its lifetime expires.
+
+Many GLFW functions accept pointers to structures or strings allocated by the
+application.  These are never freed by GLFW and are always the responsibility of
+the application.  If GLFW needs to keep the data in these structures or strings,
+it is copied before the function returns.
+
+Pointer lifetimes are guaranteed not to be shortened in future minor or patch
+releases.
+
+
+@subsection reentrancy Reentrancy
+
+GLFW event processing and object creation and destruction are not reentrant.
+This means that the following functions must not be called from any callback
+function:
+
+ - @ref glfwCreateWindow
+ - @ref glfwDestroyWindow
+ - @ref glfwCreateCursor
+ - @ref glfwCreateStandardCursor
+ - @ref glfwDestroyCursor
+ - @ref glfwPollEvents
+ - @ref glfwWaitEvents
+ - @ref glfwWaitEventsTimeout
+ - @ref glfwTerminate
+
+These functions may be made reentrant in future minor or patch releases, but
+functions not on this list will not be made non-reentrant.
+
+
+@subsection thread_safety Thread safety
+
+Most GLFW functions must only be called from the main thread, but some may be
+called from any thread.  However, no GLFW function may be called from any thread
+but the main thread until GLFW has been successfully initialized, including
+functions that may called before initialization.
+
+The reference documentation for every GLFW function states whether it is limited
+to the main thread.                                                        
+
+Initialization and termination, event processing and the creation and
+destruction of windows, contexts and cursors are all limited to the main thread
+due to limitations of one or several platforms.
+
+Because event processing must be performed on the main thread, all callbacks
+except for the error callback will only be called on that thread.  The error
+callback may be called on any thread, as any GLFW function may generate errors.
+
+The posting of empty events may be done from any thread.  The window user
+pointer and close flag may also be accessed and modified from any thread, but
+this is not synchronized by GLFW.  The following window related functions may
+be called from any thread:
+
+ - @ref glfwPostEmptyEvent
+ - @ref glfwGetWindowUserPointer
+ - @ref glfwSetWindowUserPointer
+ - @ref glfwWindowShouldClose
+ - @ref glfwSetWindowShouldClose
+
+Rendering may be done on any thread.  The following context related functions
+may be called from any thread:
+
+ - @ref glfwMakeContextCurrent
+ - @ref glfwGetCurrentContext
+ - @ref glfwSwapBuffers
+ - @ref glfwSwapInterval
+ - @ref glfwExtensionSupported
+ - @ref glfwGetProcAddress
+
+The raw timer may be queried from any thread.  The following raw timer related
+functions may be called from any thread:
+
+ - @ref glfwGetTimerFrequency
+ - @ref glfwGetTimerValue
+
+The regular timer may be used from any thread, but the reading and writing of
+the timer offset is not synchronized by GLFW.  The following timer related
+functions may be called from any thread:
+
+ - @ref glfwGetTime
+ - @ref glfwSetTime
+
+Library version information may be queried from any thread.  The following
+version related functions may be called from any thread:
+
+ - @ref glfwGetVersion
+ - @ref glfwGetVersionString
+
+Vulkan objects may be created and information queried from any thread.  The
+following Vulkan related functions may be called from any thread:
+
+ - @ref glfwVulkanSupported
+ - @ref glfwGetRequiredInstanceExtensions
+ - @ref glfwGetInstanceProcAddress
+ - @ref glfwGetPhysicalDevicePresentationSupport
+ - @ref glfwCreateWindowSurface
+
+GLFW uses no synchronization objects internally except for thread-local storage
+to keep track of the current context for each thread.  Synchronization is left
+to the application.
+
+Functions that may currently be called from any thread will always remain so,
+but functions that are currently limited to the main thread may be updated to
+allow calls from any thread in future releases.
+
+
+@subsection compatibility Version compatibility
+
+GLFW guarantees source and binary backward compatibility with earlier minor
+versions of the API.  This means that you can drop in a newer version of the
+library and existing programs will continue to compile and existing binaries
+will continue to run.
+
+Once a function or constant has been added, the signature of that function or
+value of that constant will remain unchanged until the next major version of
+GLFW.  No compatibility of any kind is guaranteed between major versions.
+
+Undocumented behavior, i.e. behavior that is not described in the documentation,
+may change at any time until it is documented.
+
+If the reference documentation and the implementation differ, the reference
+documentation is correct and the implementation will be fixed in the next
+release.
+
+
+@subsection event_order Event order
+
+The order of arrival of related events is not guaranteed to be consistent
+across platforms.  The exception is synthetic key and mouse button release
+events, which are always delivered after the window defocus event.
+
+
+@section intro_version Version management
+
+GLFW provides mechanisms for identifying what version of GLFW your application
+was compiled against as well as what version it is currently running against.
+If you are loading GLFW dynamically (not just linking dynamically), you can use
+this to verify that the library binary is compatible with your application.
+
+
+@subsection intro_version_compile Compile-time version
+
+The compile-time version of GLFW is provided by the GLFW header with the
+`GLFW_VERSION_MAJOR`, `GLFW_VERSION_MINOR` and `GLFW_VERSION_REVISION` macros.
+
+@code
+printf("Compiled against GLFW %i.%i.%i\n",
+       GLFW_VERSION_MAJOR,
+       GLFW_VERSION_MINOR,
+       GLFW_VERSION_REVISION);
+@endcode
+
+
+@subsection intro_version_runtime Run-time version
+
+The run-time version can be retrieved with @ref glfwGetVersion, a function that
+may be called regardless of whether GLFW is initialized.
+
+@code
+int major, minor, revision;
+glfwGetVersion(&major, &minor, &revision);
+
+printf("Running against GLFW %i.%i.%i\n", major, minor, revision);
+@endcode
+
+
+@subsection intro_version_string Version string
+
+GLFW 3 also provides a compile-time generated version string that describes the
+version, platform, compiler and any platform-specific compile-time options.
+This is primarily intended for submitting bug reports, to allow developers to
+see which code paths are enabled in a binary.
+
+The version string is returned by @ref glfwGetVersionString, a function that may
+be called regardless of whether GLFW is initialized.
+
+__Do not use the version string__ to parse the GLFW library version.  The @ref
+glfwGetVersion function already provides the version of the running library
+binary.
+
+The format of the string is as follows:
+ - The version of GLFW
+ - The name of the window system API
+ - The name of the context creation API
+ - Any additional options or APIs
+
+For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL
+back ends, the version string may look something like this:
+
+@code
+3.0.0 Win32 WGL MinGW
+@endcode
+
+*/