glfw/docs/intro.dox

/*! 

@page intro Introduction to the GLFW API
 
@tableofcontents

This guide will introduce the basic concepts of GLFW and describes
initialization, error handling and version management.  There are other guides
for the various areas of the GLFW API.

 - @ref window
 - @ref context
 - @ref monitor
 - @ref input


@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.

 - @ref glfwGetVersion
 - @ref glfwGetVersionString
 - @ref glfwSetErrorCallback
 - @ref glfwInit
 - @ref glfwTerminate

Calling any other function before that time will cause a `GLFW_NOT_INITIALIZED`
error. 


@subsection intro_init_init Initializing GLFW

The library is initialized with @ref glfwInit, which returns `GL_FALSE` if an
error occurred.

@code
if (!glfwInit())
{
    // Handle initialization failure
}
@endcode

If any part of initialization fails, all remaining bits are terminated as if
@ref glfwTerminate was called.  The library only needs to be initialized once
and additional calls to an already initialized library will simply return
`GL_TRUE` immediately.

Once the library has been successfully initialized, it should be terminated
before the application exits.


@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 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 had not been successfully initialized or had already been terminated,
additional calls return immediately. 


@section intro_error 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.  Also, far
from all GLFW functions have such 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 before @ref glfwInit and after @ref glfwTerminate.

@code
glfwSetErrorCallback(error_callback);
@endcode

The error callback receives a human-readable description of the error and (when
possible) its cause.  The description is a regular C string using the UTF-8
encoding.  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 `GLFW_NOT_INITIALIZED` has only a single meaning, whereas others like
`GLFW_PLATFORM_ERROR` are used for many different errors.

@note 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.


@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 using.  The GLFW
API is binary-compatible with later minor versions, i.e. an executable using the
3.0 API will be able to use a version 3.2 DLL.

As long as an executable does not use any newer functions, it can also use an
older minor version DLL, although any window hints or other tokens added since
that older version will cause errors to be reported.


@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.


@subsection intro_version_runtime Run-time version

The run-time version can be retrieved with @ref glfwGetVersion, a function that
may be called before @ref glfwInit and after @ref glfwTerminate 

@code
int major, minor, revision;
glfwGetVersion(&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 before @ref glfwInit and after @ref glfwTerminate.

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:

    3.0.0 Win32 WGL MinGW

@note Do not parse the version string to find the GLFW library version.  The
@ref glfwGetVersion function provides the version of the library binary in
numeric form.

*/