%-------------------------------------------------------------------------
% GLFW Users Guide
% API Version: 2.7
%-------------------------------------------------------------------------

% Document class
\documentclass[a4paper,11pt,oneside]{report}

% Document title and API version
\newcommand{\glfwdoctype}[1][0]{Users Guide}
\newcommand{\glfwapiver}[1][0]{2.7}

% Common document settings and macros
\input{glfwdoc.sty}

% PDF specific document settings
\hypersetup{pdftitle={GLFW Users Guide}}
\hypersetup{pdfauthor={Marcus Geelnard}}
\hypersetup{pdfkeywords={GLFW,OpenGL,guide,manual}}


%-------------------------------------------------------------------------
% Document body
%-------------------------------------------------------------------------

\begin{document}

\pagestyle{plain}

% Title page
\glfwmaketitle

% Summary, trademarks and table of contents
\pagenumbering{roman}
\setcounter{page}{1}

%-------------------------------------------------------------------------
% Summary and Trademarks
%-------------------------------------------------------------------------
\chapter*{Summary}

This document is a users guide for the \GLFW\ API that gives a practical
introduction to using \GLFW . For a more detailed description of the
\GLFW\ API you should refer to the \textit{GLFW Reference Manual}.
\vspace{5cm}

\large
Trademarks

\small
OpenGL and IRIX are registered trademarks of Silicon Graphics, Inc.\linebreak
Microsoft and Windows are registered trademarks of Microsoft Corporation.\linebreak
Mac OS is a registered trademark of Apple Computer, Inc.\linebreak
Linux is a registered trademark of Linus Torvalds.\linebreak
FreeBSD is a registered trademark of Wind River Systems, Inc.\linebreak
Solaris is a trademark of Sun Microsystems, Inc.\linebreak
UNIX is a registered trademark of The Open Group.\linebreak
X Window System is a trademark of The Open Group.\linebreak
POSIX is a trademark of IEEE.\linebreak
Truevision, TARGA and TGA are registered trademarks of Truevision, Inc.\linebreak
IBM is a registered trademark of IBM Corporation.\linebreak

All other trademarks mentioned in this document are the property of their respective owners.
\normalsize


%-------------------------------------------------------------------------
% Table of contents
%-------------------------------------------------------------------------
\tableofcontents
\pagebreak


% Document chapters starts here...
\pagenumbering{arabic}
\setcounter{page}{1}

\pagestyle{fancy}


%-------------------------------------------------------------------------
% Introduction
%-------------------------------------------------------------------------
\chapter{Introduction}
\thispagestyle{fancy}
\GLFW\ is a portable API (Application Program Interface) that handles
operating system specific tasks related to \OpenGL\ programming. While
\OpenGL\ in general is portable, easy to use and often results in tidy and
compact code, the operating system specific mechanisms that are required
to set up and manage an \OpenGL\ window are quite the opposite. \GLFW\ tries
to remedy this by providing the following functionality:

\begin{itemize}
\item Opening and managing an \OpenGL\ window.
\item Keyboard, mouse and joystick input.
\item High precision time input.
\item Multi-threading support.
\item Support for querying and using \OpenGL\ extensions.
\item Rudimentary image file loading support.
\end{itemize}
\vspace{18pt}

All this functionality is implemented as a set of easy-to-use functions,
which makes it possible to write an \OpenGL\ application framework in just a
few lines of code. The \GLFW\ API is operating system and platform independent,
making it very simple to port \GLFW\ based \OpenGL\ applications between the
supported platforms.

Currently supported platforms are:
\begin{itemize}
\item Microsoft Windows\textsuperscript{\textregistered}
\item Unix\textsuperscript{\textregistered} or Unix�-like systems running the
X Window System\texttrademark with GLX version 1.3 or later
\item Mac OS X\textsuperscript{\textregistered} 10.5 and later, using Cocoa\footnote{Support for joysticks missing at the time of writing.}
\end{itemize}

There is also deprecated support for Mac OS X versions 10.3 and 10.4, using the Carbon API.


%-------------------------------------------------------------------------
% Getting Started
%-------------------------------------------------------------------------
\chapter{Getting Started}
\thispagestyle{fancy}
In this chapter you will learn how to write a simple \OpenGL\ application
using \GLFW . We start by initializing \GLFW , then we open a window and
read some user keyboard input.


%-------------------------------------------------------------------------
\section{Including the GLFW header}
The usual way of including the \GLFW\ header is:
\begin{lstlisting}
#include <GL/glfw.h>
\end{lstlisting}

This header defines all the constants, types and function prototypes of the
\GLFW\ API.  It also by default includes the \OpenGL\ and GLU header files
provided by your development environment and defines all the necessary constants
and types that are necessary for these headers to work on that particular
platform.

By default, the regular \textbf{gl.h} header is included. If you wish to include
the draft \textbf{gl3.h} header instead, define \textbf{GLFW\_INCLUDE\_GL3}
before the inclusion of the GLFW header.

Also by default, the \textbf{glu.h} header is included.  If you wish to avoid this,
define \textbf{GLFW\_NO\_GLU} before the inclusion of the GLFW header.


%-------------------------------------------------------------------------
\section{Initializing GLFW}
Before using any of the \GLFW\ functions, it is necessary to call
\textbf{glfwInit}. It initializes the parts of \GLFW\ that are not dependent on
a window, such as threading, timer and joystick input. The C syntax is:

\begin{lstlisting}
int glfwInit( void )
\end{lstlisting}

\textbf{glfwInit} returns GL\_TRUE if initialization succeeded, or
GL\_FALSE if it failed.

When your application is done using \GLFW , typically at the very end of
the program, you should call \textbf{glfwTerminate}.  The C syntax is:

\begin{lstlisting}
void glfwTerminate( void )
\end{lstlisting}

This releases any resources allocated by GLFW, closes the window if it is open
and kills any secondary threads created by \GLFW\.  After this call, you must
call \textbf{glfwInit} again before using any \GLFW\ functions).

%-------------------------------------------------------------------------
\section{Opening An OpenGL Window}
Opening an \OpenGL\ window is done with the \textbf{glfwOpenWindow} function.
The function takes nine arguments, which are used to describe the following
properties of the requested window:

\begin{itemize}
\item Window dimensions (width and height) in pixels.
\item Color and alpha buffer bit depth.
\item Depth buffer (Z-buffer) bit depth.
\item Stencil buffer bit depth.
\item Whether to use fullscreen or windowed mode.
\end{itemize}

The C language syntax for \textbf{glfwOpenWindow} is:
\begin{lstlisting}
int glfwOpenWindow( int width, int height,
    int redbits, int greenbits, int bluebits,
    int alphabits, int depthbits, int stencilbits,
    int mode )
\end{lstlisting}

\textbf{glfwOpenWindow} returns GL\_TRUE if the window was opened
correctly, or GL\_FALSE if \GLFW\ failed to open the window.

\GLFW\ tries to open a window that best matches the requested parameters.
Some parameters may be omitted by setting them to zero, which will result
in \GLFW\ either using a default value, or the related functionality to be
disabled. For instance, if \textit{width} and \textit{height} are both
zero, \GLFW\ will use a window resolution of 640x480. If
\textit{depthbits} is zero, the opened window may not have a depth buffer.

The \textit{mode} argument is used to specify if the window is to be a
fullscreen window or a regular window.

If \textit{mode} is GLFW\_FULLSCREEN, the window will cover the entire
screen and no window border or decorations will be visible. If possible, the
video mode will be changed to the mode that closest matches the \textit{width},
\textit{height}, \textit{redbits}, \textit{greenbits}, \textit{bluebits} and
\textit{alphabits} arguments. Furthermore, the mouse pointer will be hidden,
and screensavers are prohibited. This is usually the best mode for games and
demos.

If \textit{mode} is GLFW\_WINDOW, the window will be opened as a normal,
decorated window on the desktop. The mouse pointer will not be hidden and
screensavers are allowed to be activated.

To close the window, you can either use \textbf{glfwTerminate}, as
described earlier, or you can use the more explicit approach by calling
\textbf{glfwCloseWindow}, which has the C syntax:

\begin{lstlisting}
void glfwCloseWindow( void )
\end{lstlisting}

Note that you do not need to call \textbf{glfwTerminate} and \textbf{glfwInit}
before opening a new window after having closed the current one using
\textbf{glfwCloseWindow}.


%-------------------------------------------------------------------------
\section{Using Keyboard Input}
\GLFW\ provides several means for receiving user input, which will be
discussed in more detail in chapter \ref{par:inputhandling}. One of the
simplest ways of checking for keyboard input is to use the function
\textbf{glfwGetKey}:

\begin{lstlisting}
int glfwGetKey( int key )
\end{lstlisting}

It queries the current status of individual keyboard keys. The argument
\textit{key} specifies which key to check, and it can be either an
uppercase printable ISO 8859-1 (Latin 1) character (e.g. `A', `3' or `.'),
or a special key identifier (see the \textit{GLFW Reference Manual} for a
list of special key identifiers). \textbf{glfwGetKey} returns GLFW\_PRESS
if the key is currently held down, or GLFW\_RELEASE if the key is not being
held down. For example:

\begin{lstlisting}
A_pressed = glfwGetKey( 'A' );
esc_pressed = glfwGetKey( GLFW_KEY_ESC );
\end{lstlisting}

In order for \textbf{glfwGetKey} to have any effect, you need to poll for
input events on a regular basis. This can be done in one of two ways:

\begin{enumerate}
\item Implicitly by calling \textbf{glfwSwapBuffers} often.
\item Explicitly by calling \textbf{glfwPollEvents} often.
\end{enumerate}

In general you do not have to care about this, since you will normally
call \textbf{glfwSwapBuffers} to swap front and back rendering buffers
every animation frame anyway. If, however, this is not the case, you
should call \textbf{glfwPollEvents} in the order of 10-100 times per
second in order for \GLFW\ to maintain an up to date input state.


%-------------------------------------------------------------------------
\section{Putting It Together: A Minimal GLFW Application}
Now that you know how to initialize \GLFW , open a window and poll for
keyboard input, let us exemplify this with a simple \OpenGL\ program:

\begin{lstlisting}
#include <GL/glfw.h>
#include <stdlib.h>

int main( void )
{
    int running = GL_TRUE;

    // Initialize GLFW
    if( !glfwInit() )
    {
        exit( EXIT_FAILURE );
    }

    // Open an OpenGL window
    if( !glfwOpenWindow( 300,300, 0,0,0,0,0,0, GLFW_WINDOW ) )
    {
        glfwTerminate();
        exit( EXIT_FAILURE );
    }

    // Main loop
    while( running )
    {
        // OpenGL rendering goes here...
        glClear( GL_COLOR_BUFFER_BIT );

        // Swap front and back rendering buffers
        glfwSwapBuffers();

        // Check if ESC key was pressed or window was closed
        running = !glfwGetKey( GLFW_KEY_ESC ) &&
                  glfwGetWindowParam( GLFW_OPENED );
    }

    // Close window and terminate GLFW
    glfwTerminate();

    // Exit program
    exit( EXIT_SUCCESS );
}
\end{lstlisting}

The program opens a 300x300 window and runs in a loop until the escape key
is pressed, or the window was closed. All the \OpenGL\ ``rendering'' that
is done in this example is to clear the window.


%-------------------------------------------------------------------------
% Window Operations
%-------------------------------------------------------------------------
\chapter{Window Operations}
\thispagestyle{fancy}
In this chapter, you will learn more about window related \GLFW\
functionality, including setting and getting window properties, buffer
swap control and video mode querying.


%-------------------------------------------------------------------------
\section{Setting Window Properties}
In the previous chapter the \textbf{glfwOpenWindow} function was
described, which specifies the sizes of the color, alpha, depth and
stencil buffers. It is also possible to request a specific minimum OpenGL
version, multisampling anti-aliasing, an accumulation buffer, stereo
rendering and more by using the \textbf{glfwOpenWindowHint} function:

\begin{lstlisting}
void glfwOpenWindowHint( int target, int hint )
\end{lstlisting}

The \textit{target} argument can be one of the constants listed in table~
\ref{tab:winhints}, and \textit{hint} is the value to assign to the
specified target.

%-------------------------------------------------------------------------
\begin{table}[p]
\begin{center}
\begin{tabular}{|l|l|p{7.0cm}|} \hline \raggedright
\textbf{Name}            & \textbf{Default} & \textbf{Description} \\ \hline
GLFW\_REFRESH\_RATE      & 0                & Vertical monitor refresh rate in Hz (only used for fullscreen windows). Zero means system default.\\ \hline
GLFW\_ACCUM\_RED\_BITS   & 0                & Number of bits for the red channel of the accumulation buffer.\\ \hline
GLFW\_ACCUM\_GREEN\_BITS & 0                & Number of bits for the green channel of the accumulation buffer.\\ \hline
GLFW\_ACCUM\_BLUE\_BITS  & 0                & Number of bits for the blue channel of the accumulation buffer.\\ \hline
GLFW\_ACCUM\_ALPHA\_BITS & 0                & Number of bits for the alpha channel of the accumulation buffer.\\ \hline
GLFW\_AUX\_BUFFERS       & 0                & Number of auxiliary buffers.\\ \hline
GLFW\_STEREO             & GL\_FALSE        & Specify if stereo rendering should be supported (can be GL\_TRUE or GL\_FALSE).\\ \hline
GLFW\_WINDOW\_NO\_RESIZE & GL\_FALSE        & Specify whether the window can be resized by the user (not used for fullscreen windows).\\ \hline
GLFW\_FSAA\_SAMPLES      & 0                & Number of samples to use for the multisampling buffer. Zero disables multisampling.\\ \hline
GLFW\_OPENGL\_VERSION\_MAJOR & 1	        & Major number of the desired minimum OpenGL version.\\ \hline
GLFW\_OPENGL\_VERSION\_MINOR & 1	        & Minor number of the desired minimum OpenGL version.\\ \hline
GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_FALSE   & Specify whether the OpenGL context should be forward-compatible (i.e. disallow legacy functionality).
                                              This should only be used when requesting OpenGL version 3.0 or above.\\ \hline
GLFW\_OPENGL\_DEBUG\_CONTEXT & GL\_FALSE    & Specify whether a debug context should be created.\\ \hline
GLFW\_OPENGL\_PROFILE    & 0                & The OpenGL profile the context should implement, or zero to let the system choose.
                                              Available profiles are GLFW\_OPENGL\_CORE\_PROFILE and GLFW\_OPENGL\_COMPAT\_PROFILE.\\ \hline
\end{tabular}
\end{center}
\caption{Targets for \textbf{glfwOpenWindowHint}}
\label{tab:winhints}
\end{table}
%-------------------------------------------------------------------------

For a hint to have any effect, the \textbf{glfwOpenWindowHint} function
must be called before opening the window with the \textbf{glfwOpenWindow}
function.

To request an accumulation buffer, set the GLFW\_ACCUM\_x\_BITS targets to
values greater than zero (usually eight or sixteen bits per component).
To request auxiliary buffers, set the GLFW\_AUX\_BUFFERS target to a value
greater than zero. To request a stereo rendering capable window, set the
GLFW\_STEREO target to GL\_TRUE.

If you want to enable fullscreen antialiasing, set the GLFW\_FSAA\_SAMPLES
target to a value greater than zero. If the windowing system is unable to
fulfil the request, \GLFW\ will degrade gracefully and disable FSAA if necessary.

The GLFW\_REFRESH\_RATE target should be used with caution, since it may
result in suboptimal operation, or even a blank or damaged screen.

If you want to create a forward-compatible \OpenGL\ context, set the
GLFW\_OPENGL\_FORWARD\_COMPAT hint to GL\_TRUE.  Note that such contexts are
only available for \OpenGL\ version 3.0 and above, so you will need to specify
a valid minimum version using the GLFW\_OPENGL\_VERSION\_MAJOR and
GLFW\_OPENGL\_VERSION\_MINOR hints.

If you want to create a context using the core profile as available in \OpenGL\
version 3.2 and above, set the GLFW\_OPENGL\_PROFILE hint accordingly.  Note that
as above you have to set a valid minimum version for this to work.

Note that versions of Mac OS X before 10.7 does not support \OpenGL\ 3.0 or
later, and that at the time of this release, Mac OS X 10.7 only supports 
forward-compatible \OpenGL\ 3.2 core profile contexts.  Due to the way default
values work in \GLFW\, you do not need to specify either GLFW\_FORWARD\_COMPAT
or GLFW\_OPENGL\_PROFILE for this to work.

Besides the parameters that are given with the \textbf{glfwOpenWindow} and
\textbf{glfwOpenWindowHint} functions, a few more properties of a window
can be changed after the window has been opened, namely the window title,
window size, and window position.

To change the window title of an open window, use the
\textbf{glfwSetWindowTitle} function:

\begin{lstlisting}
void glfwSetWindowTitle( const char *title )
\end{lstlisting}

\textit{title} is a null terminated ISO~8859-1 (8-bit Latin~1) string that
will be used as the window title. It will also be used as the application
name (for instance in the application list when using \texttt{Alt+Tab}
under Windows, or as the icon name when the window is iconified under
the X Window System). The default window name is ``GLFW Window'', which
will be used unless \textbf{glfwSetWindowTitle} is called after the window
has been opened.

To change the size of a window, call \textbf{glfwSetWindowSize}:

\begin{lstlisting}
void glfwSetWindowSize( int width, int height )
\end{lstlisting}

Where \textit{width} and \textit{height} are the new dimensions of the
window.

To change the position of a window, call \textbf{glfwSetWindowPos}:

\begin{lstlisting}
void glfwSetWindowPos( int x, int y )
\end{lstlisting}

Where \textit{x} and \textit{y} are the new desktop coordinates of the
window. This function does not have any effect when in fullscreen mode.


%-------------------------------------------------------------------------
\section{Getting Window Properties}
When opening a window, the opened window will not necessarily have the
requested properties, so you should always check the parameters that your
application relies on (e.g. number of stencil bits) using
\textbf{glfwGetWindowParam}, which has the C syntax:

\begin{lstlisting}
int glfwGetWindowParam( int param )
\end{lstlisting}

The argument \textit{param} can be one of the tokens listed in table
\ref{tab:winparams}, and the return value is an integer holding the
requested value.

%-------------------------------------------------------------------------
\begin{table}[p]
\begin{center}
\begin{tabular}{|l|p{9.5cm}|} \hline \raggedright
\textbf{Name}            & \textbf{Description} \\ \hline
GLFW\_OPENED             & GL\_TRUE if window is opened, else GL\_FALSE.\\ \hline
GLFW\_ACTIVE             & GL\_TRUE if window has focus, else GL\_FALSE.\\ \hline
GLFW\_ICONIFIED          & GL\_TRUE if window is iconified, else GL\_FALSE.\\ \hline
GLFW\_ACCELERATED        & GL\_TRUE if window is hardware accelerated, else GL\_FALSE.\\ \hline
GLFW\_RED\_BITS          & Number of bits for the red color component.\\ \hline
GLFW\_GREEN\_BITS        & Number of bits for the green color component.\\ \hline
GLFW\_BLUE\_BITS         & Number of bits for the blue color component.\\ \hline
GLFW\_ALPHA\_BITS        & Number of bits for the alpha buffer.\\ \hline
GLFW\_DEPTH\_BITS        & Number of bits for the depth buffer.\\ \hline
GLFW\_STENCIL\_BITS      & Number of bits for the stencil buffer.\\ \hline
GLFW\_REFRESH\_RATE      & Vertical monitor refresh rate in Hz. Zero indicates an unknown or a default refresh rate.\\ \hline
GLFW\_ACCUM\_RED\_BITS   & Number of bits for the red channel of the accumulation buffer.\\ \hline
GLFW\_ACCUM\_GREEN\_BITS & Number of bits for the green channel of the accumulation buffer.\\ \hline
GLFW\_ACCUM\_BLUE\_BITS  & Number of bits for the blue channel of the accumulation buffer.\\ \hline
GLFW\_ACCUM\_ALPHA\_BITS & Number of bits for the alpha channel of the accumulation buffer.\\ \hline
GLFW\_AUX\_BUFFERS       & Number of auxiliary buffers.\\ \hline
GLFW\_STEREO             & GL\_TRUE if stereo rendering is supported, else GL\_FALSE.\\ \hline
GLFW\_WINDOW\_NO\_RESIZE & GL\_TRUE if the window cannot be resized by the user, else GL\_FALSE.\\ \hline
GLFW\_FSAA\_SAMPLES      & Number of multisampling buffer samples. Zero indicated multisampling is disabled.\\ \hline
GLFW\_OPENGL\_VERSION\_MAJOR & Major number of the actual version of the context.\\ \hline
GLFW\_OPENGL\_VERSION\_MINOR & Minor number of the actual version of the context.\\ \hline
GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_TRUE if the context is forward-compatible, else GL\_FALSE.\\ \hline
GLFW\_OPENGL\_DEBUG\_CONTEXT & GL\_TRUE if the context is a debug context.\\ \hline
GLFW\_OPENGL\_PROFILE    & The profile implemented by the context, or zero.\\ \hline
\end{tabular}
\end{center}
\caption{Window parameters for \textbf{glfwGetWindowParam}}
\label{tab:winparams}
\end{table}
%-------------------------------------------------------------------------

Another useful function is \textbf{glfwSetWindowSizeCallback}, which
specifies a user function that will be called every time the window size
has changed. The C syntax is:

\begin{lstlisting}
void glfwSetWindowSizeCallback( GLFWwindowsizefun cbfun )
\end{lstlisting}

The user function \textit{fun} should be of the type:

\begin{lstlisting}
void GLFWCALL fun( int width, int height )
\end{lstlisting}

The first argument passed to the user function is the width of the window,
and the second argument is the height of the window. Here is an example
of how to use a window size callback function:

\begin{lstlisting}
int windowWidth, windowHeight;

void GLFWCALL WindowResize( int width, int height )
{
    windowWidth  = width;
    windowHeight = height;
}

int main( void )
{
    ...
    glfwSetWindowSizeCallback( WindowResize );
    ...
}
\end{lstlisting}

Using a callback function for getting the window size is mostly useful for
windowed applications, since the window size may be changed at any time by
the user. It can also be used to determine the actual fullscreen
resolution.

An alternative to using a callback function for getting the window size,
is to use the function \textbf{glfwGetWindowSize}:

\begin{lstlisting}
void glfwGetWindowSize( int *width, int *height )
\end{lstlisting}

The variables pointed to by \textit{width} and \textit{height} are set to the
current window dimensions.  Note that either of these may be NULL; that
argument is then ignored.


%-------------------------------------------------------------------------
\section{Buffer Swapping}
\GLFW\ windows are always double buffered. That means that you have two
rendering buffers; a front buffer and a back buffer. The front buffer is
the buffer that is being displayed, and the back buffer is not displayed.
\OpenGL\ lets you select which of these two buffers you want to render to
(with the \textbf{glDrawBuffer} command), but the default (and preferred)
rendering buffer is the back buffer. This way you will avoid flickering
and artifacts caused by graphics being only partly drawn at the same time
as the video raster beam is displaying the graphics on the monitor.

When an entire frame has been rendered to the back buffer, it is time to
swap the back and the front buffers in order to display the rendered
frame, and begin rendering a new frame. This is done with the command
\textbf{glfwSwapBuffers}. The C syntax is:

\begin{lstlisting}
void glfwSwapBuffers( void )
\end{lstlisting}

After swapping the front and back rendering buffers, \textbf{glfwSwapBuffers}
by default calls \textbf{glfwPollEvents}\footnote{This behavior can be disabled
by calling \textbf{glfwDisable} with the argument GLFW\_AUTO\_POLL\_EVENTS.}.
This is to ensure frequent polling of events, such as keyboard and mouse input,
and window reshaping events.  Even if a given application does not use input
events, without frequent polling of events (at \emph{least} once every few
seconds), most modern window systems will flag the application as unresponsive
and may suggest that the user terminate it.

Sometimes it can be useful to select when the buffer swap will occur. With
the function \textbf{glfwSwapInterval} it is possible to select the
minimum number of vertical retraces the video raster line should do before
swapping the buffers:

\begin{lstlisting}
void glfwSwapInterval( int interval )
\end{lstlisting}

If \textit{interval} is zero, the swap will take place immediately when
\textbf{glfwSwapBuffers} is called, without waiting for a vertical retrace
(also known as ``vsync off''). Otherwise at least \textit{interval}
retraces will pass between each buffer swap (also known as ``vsync on'').
Using a swap interval of zero can be useful for benchmarking purposes,
when it is not desirable to measure the time it takes to wait for the
vertical retrace. However, a swap interval of 1 generally gives better
visual quality.

It should be noted that not all \OpenGL\ implementations and hardware support
this function, in which case \textbf{glfwSwapInterval} will have no effect.  ATI
Radeon cards under Microsoft Windows are especially notorious in this regard.
Sometimes it is only possible to affect the swap interval through driver
settings (e.g.  the display settings under Windows, or as an environment
variable setting under Unix).


%-------------------------------------------------------------------------
\section{Querying Video Modes}
Although \GLFW\ generally does a good job at selecting a suitable video
mode for you when you open a fullscreen window, it is sometimes useful to
know exactly which modes are available on a certain system. For example,
you may want to present the user with a list of video modes to select
from. To get a list of available video modes, you can use the function
\textbf{glfwGetVideoModes}:

\begin{lstlisting}
int glfwGetVideoModes( GLFWvidmode *list, int maxcount )
\end{lstlisting}

The argument \textit{list} is a vector of GLFWvidmode structures, and
\textit{maxcount} is the maximum number of video modes that your vector can
hold. \textbf{glfwGetVideoModes} will return the number of video modes detected
on the system, up to \textit{maxcount}.

The GLFWvidmode structure looks like this:

\begin{lstlisting}
typedef struct {
   int Width, Height;   // Video resolution
   int RedBits;         // Red bits per pixel
   int GreenBits;       // Green bits per pixel
   int BlueBits;        // Blue bits per pixel
} GLFWvidmode;
\end{lstlisting}

Here is an example of retrieving all available video modes:

\begin{lstlisting}
int nummodes;
GLFWvidmode list[ 200 ];
nummodes = glfwGetVideoModes( list, 200 );
\end{lstlisting}

The returned list is sorted, first by color depth ($RedBits + GreenBits +
BlueBits$), and then by resolution ($Width\times Height$), with the
lowest resolution, fewest bits per pixel mode first.

To get the desktop video mode, use the function
\textbf{glfwGetDesktopMode}:

\begin{lstlisting}
void glfwGetDesktopMode( GLFWvidmode *mode )
\end{lstlisting}

The function returns the resolution and color depth of the user desktop in
the mode structure. Note that the user desktop mode is independent of the
current video mode if a \GLFW\ fullscreen window has been opened.


%-------------------------------------------------------------------------
% Input Handling
%-------------------------------------------------------------------------
\chapter{Input Handling}
\label{par:inputhandling}
\thispagestyle{fancy}
In this chapter you will learn how to use keyboard, mouse and joystick
input, using either polling or callback functions.


%-------------------------------------------------------------------------
\section{Event Polling}
The first thing to know about input handling in \GLFW\ is that all
keyboard and mouse input is collected by checking for input events. This
has do be done manually by calling either \textbf{glfwPollEvents} or
\textbf{glfwSwapBuffers} (which implicitly calls \textbf{glfwPollEvents}
for you). Normally this is not a cause for concern, as
\textbf{glfwSwapBuffers} is called every frame, which should be often
enough (about 10-100 times per second for a normal \OpenGL\ application) that
the window will feel responsive.

One exception is when an application is updating its view only in response to input.
In this case the \textbf{glfwWaitEvents} is useful, as it blocks the calling
thread until an event arrives.  The refresh callback, set with
\textbf{glfwSetWindowRefreshCallback}, may also be useful for such
applications, especially on unbuffered window systems.

If it is not desirable that \textbf{glfwPollEvents is} called implicitly
from \textbf{glfwSwapBuffers}, call \textbf{glfwDisable} with the argument
GLFW\_AUTO\_POLL\_EVENTS.

Note that event polling is not needed for joystick input, since all
relevant joystick state is gathered every time a joystick function is
called.


%-------------------------------------------------------------------------
\section{Keyboard Input}
\GLFW\ provides three mechanisms for getting keyboard input:

\begin{itemize}
\item Manually polling the state of individual keys.
\item Automatically receive new key state for any key, using a callback
      function.
\item Automatically receive characters, using a callback function.
\end{itemize}

Depending on what the keyboard input will be used for, different methods may be
preferred. The main difference between the two last methods is that while
characters are affected by modifier keys (such as shift), key state is
independent of any modifier keys. Also, special keys (such as function keys,
cursor keys and modifier keys) are not reported to the character callback
function.

%-------------------------------------------------------------------------
\subsection{Key state}
To check if a key is held down or not at any given moment, use the
function \textbf{glfwGetKey}:

\begin{lstlisting}
int glfwGetKey( int key )
\end{lstlisting}

It queries the current status of individual keyboard keys. The argument
\textit{key} specifies which key to check, and it can be either an
uppercase ISO~8859-1 character, or a special key identifier.
\textbf{glfwGetKey} returns GLFW\_PRESS (or 1) if the key is currently
held down, or GLFW\_RELEASE (or 0) if the key is not being held down.

In most situations, it may be useful to know if a key has been pressed and
released between two calls to \textbf{glfwGetKey} (especially if the
animation is fairly slow, which may allow the user to press and release a
key between two calls to \textbf{glfwGetKey}). This can be accomplished by
enabling sticky keys, which is done by calling \textbf{glfwEnable} with
the argument GLFW\_STICKY\_KEYS, as in the following example:

\begin{lstlisting}
glfwEnable( GLFW_STICKY_KEYS );
\end{lstlisting}

When sticky keys are enabled, a key will not be released until it is
checked with \textbf{glfwGetKey}. To disable sticky keys, call
\textbf{glfwDisable} witht the argument GLFW\_STICKY\_KEYS. Then all keys
that are not currently held down will be released and future key releases
will take place immediately when the user releases the key without
waiting for \textbf{glfwGetKey} to check the key. By default sticky keys
are disabled.

Sticky keys are often very useful and should be used in most cases where
\textbf{glfwGetKey} is used. There is however a danger involved with
enabling sticky keys, and that is that keys that are pressed by the user
but are not checked with \textbf{glfwGetKey}, may remain ``pressed'' for a
very long time. A typical situation where this may be dangerous is in a
program that consists of two or more sections (e.g. a menu section and a
game section). If the first section enables sticky keys but does not check
for keys which the second section checks for, there is a potential of
recording many key presses in the first section that will be detected in
the second section. To avoid this problem, always disable sticky keys
before leaving a section of a program.

A usually better alternative to using \textbf{glfwGetKey} is to register a
keyboard input callback function with \textbf{glfwSetKeyCallback}:

\begin{lstlisting}
void glfwSetKeyCallback( GLFWkeyfun cbfun )
\end{lstlisting}

The argument \textit{fun} is a pointer to a callback function. The
callback function shall take two integer arguments. The first is the key
identifier, and the second is the new key state, which can be GLFW\_PRESS
or GLFW\_RELEASE. To unregister a callback function, call
\textbf{glfwSetKeyCallback} with \textit{fun} = NULL.

Using the callback function, you can be sure not to miss any key press or
release events, regardless of how many may have occurred during the last frame.
It also encourages event-based design, where the application responds only to
actual events instead of having to poll for every supported event.

%-------------------------------------------------------------------------
\subsection{Character input}
If the keyboard is to be used as a text input device (e.g. in a user
dialog) rather than as a set of independent buttons, a character callback
function is more suitable. To register a character callback function, use
\textbf{glfwSetCharCallback}:

\begin{lstlisting}
void glfwSetCharCallback( GLFWcharfun cbfun )
\end{lstlisting}

The argument \textit{fun} is a pointer to a callback function. The
callback function shall take two integer arguments. The first is a Unicode
code point, and the second is  GLFW\_PRESS if the key that generated
the character was pressed, or GLFW\_RELEASE if it was released. To
unregister a callback function, call \textbf{glfwSetCharCallback} with
\textit{fun} = NULL.

The Unicode character set is an international standard for encoding
characters. It is much more comprehensive than seven or eight bit
character sets (e.g. US-ASCII and Latin~1), and includes characters for
most written languages in the world. It should be noted that Unicode
character codes 0 to 255 are the same as for ISO~8859-1 (Latin~1), so as
long as a proper range check is performed on the Unicode character code,
it can be used just as an eight bit Latin~1 character code (which can be
useful if full Unicode support is not possible).


%-------------------------------------------------------------------------
\subsection{Key repeat}
By default, \GLFW\ does not report key repeats when a key is held down.
To activate key repeat, call \textbf{glfwEnable} with the argument
GLFW\_KEY\_REPEAT:

\begin{lstlisting}
glfwEnable( GLFW_KEY_REPEAT );
\end{lstlisting}

This will let a registered key or character callback function receive key
repeat events when a key is held down.


%-------------------------------------------------------------------------
\subsection{Special system keys}
On most systems there are some special system keys that are normally not
intercepted by an application. For instance, under Windows it is possible
to switch programs by pressing \texttt{ALT+TAB}, which brings up a list of
running programs to select from. In certain situations it can be desirable
to prevent such special system keys from interfering with the program.
With \GLFW\ it is possible to do by calling \textbf{glfwDisable} with the
argument GLFW\_SYSTEM\_KEYS:

\begin{lstlisting}
glfwDisable( GLFW_SYSTEM_KEYS );
\end{lstlisting}

By doing so, most system keys will have no effect and will not interfere
with your program. System keys can be re-enabled by calling
\textbf{glfwEnable} with the argument GLFW\_SYSTEM\_KEYS. By default,
system keys are enabled.


%-------------------------------------------------------------------------
\section{Mouse Input}
Just like for keyboard input, mouse input can be realized with either
polling or callback functions.


%-------------------------------------------------------------------------
\subsection{Mouse position}
To query the position of the mouse cursor, call \textbf{glfwGetMousePos}:

\begin{lstlisting}
void glfwGetMousePos( int *x, int *y )
\end{lstlisting}

The variables pointed to by \textit{x} and \textit{y} will be updated with the
current position of the mouse cursor relative to the upper-left corner of the
client area of the \GLFW\ window.

An alternative is to use a callback function, which can be set with
\textbf{glfwSetMousePosCallback}:

\begin{lstlisting}
void glfwSetMousePosCallback( GLFWmouseposfun cbfun )
\end{lstlisting}

The function that \textit{fun} points to will be called every time the
mouse cursor moves.  The first argument to the callback function is
the cursor x-coordinate and the second the cursor y-coordinate, both relative
to the upper-left corner of the client area of the \GLFW\ window.

Note that while the \textbf{glfwGetMousePos} function only reports the final
position after cursor movement events have been processed, using a callback
function lets the application see each and every such event.


%-------------------------------------------------------------------------
\subsection{Mouse buttons}
To query the state of a mouse button, call \textbf{glfwGetMouseButton}:

\begin{lstlisting}
int glfwGetMouseButton( int button )
\end{lstlisting}

The argument \textit{button} can be any \GLFW\ mouse button token, i.e.
GLFW\_MOUSE\_BUTTON\_1 through GLFW\_MOUSE\_BUTTON\_8 or one of
GLFW\_MOUSE\_BUTTON\_LEFT, GLFW\_MOUSE\_BUTTON\_RIGHT or
GLFW\_MOUSE\_BUTTON\_MIDDLE. \textbf{glfwGetMouseButton} will return
GLFW\_PRESS (which is a non-zero value) if the corresponding mouse button is
held down, otherwise it will return GLFW\_RELEASE (which is equal to zero).

Just as it is possible to make keys ``sticky'', it is also possible to make
each mouse button appear as held down until it is checked with
\textbf{glfwGetMouseButton}.  To enable sticky mouse buttons, call
\textbf{glfwEnable} with the argument GLFW\_STICKY\_MOUSE\_BUTTONS.

When sticky mouse buttons are enabled, a mouse button will not be released
until it is checked with \textbf{glfwGetMouseButton}. To disable sticky
mouse buttons, call \textbf{glfwDisable} with the argument
GLFW\_STICKY\_MOUSE\_BUTTONS. Then all mouse buttons that are not
currently held down will be released and future mouse button releases
will take place immediately when the user releases the mouse button
without waiting for \textbf{glfwGetMouseButton} to check for the mouse
button. By default sticky mouse buttons are disabled.

There is also a callback function for mouse button activities, which can
be set with \textbf{glfwSetMouseButtonCallback}:

\begin{lstlisting}
void glfwSetMouseButtonCallback( GLFWmousebuttonfun fun )
\end{lstlisting}

The argument \textit{fun} specifies a function that will be called
whenever a mouse button is pressed or released, or NULL to unregister a
callback function. The first argument to the callback function is a mouse
button identifier, and the second is either GLFW\_PRESS or GLFW\_RELEASE,
depending on the new state of the corresponding mouse button.


%-------------------------------------------------------------------------
\subsection{Mouse wheel}
Some mice have a mouse wheel, most commonly used for vertical scrolling.  Also,
most modern touchpads allow the user to scroll at least vertically, either by
reserving an area for scrolling or through multi-finger gestures. To get the
position of the mouse wheel, call \textbf{glfwGetMouseWheel}:

\begin{lstlisting}
int glfwGetMouseWheel( void )
\end{lstlisting}

The function returns an integer that represents the position of the mouse
wheel. When the user turns the wheel, the wheel position will increase or
decrease.  Note that since scrolling hardware has no absolute position, \GLFW\
simply sets the position to zero when the window is opened.

It is also possible to register a callback function for mouse wheel events
with the \textbf{glfwSetMouseWheelCallback} function:

\begin{lstlisting}
void glfwSetMouseWheelCallback( GLFWmousewheelfun fun )
\end{lstlisting}

The argument \textit{fun} specifies a function that will be called
whenever the mouse wheel is moved, or NULL to unregister a callback
function. The argument to the callback function is the position of the
mouse wheel.


%-------------------------------------------------------------------------
\subsection{Hiding the mouse cursor}
It is possible to hide the mouse cursor with the function call:

\begin{lstlisting}
glfwDisable( GLFW_MOUSE_CURSOR );
\end{lstlisting}

Hiding the mouse cursor has three effects:

\begin{enumerate}
\item The cursor becomes invisible.
\item The cursor is guaranteed to be confined to the window.
\item Mouse coordinates are not limited to the window size.
\end{enumerate}

To show the mouse cursor again, call \textbf{glfwEnable} with the
argument GLFW\_MOUSE\_CURSOR:

\begin{lstlisting}
glfwEnable( GLFW_MOUSE_CURSOR );
\end{lstlisting}

By default the mouse cursor is hidden if a window is opened in fullscreen
mode, otherwise it is not hidden.


%-------------------------------------------------------------------------
\section{Joystick Input}
\GLFW\ has support for up to sixteen joysticks, and an infinite\footnote{%
There are of course actual limitations posed by the underlying hardware,
drivers and operation system.} number of axes and buttons per joystick.
Unlike keyboard and mouse input, joystick input does not need an opened
window, and \textbf{glfwPollEvents} or \textbf{glfwSwapBuffers} does not
have to be called in order for joystick state to be updated.


%-------------------------------------------------------------------------
\subsection{Joystick capabilities}
First, it is often necessary to determine if a joystick is connected and
what its capabilities are. To get this information the function
\textbf{glfwGetJoystickParam} can be used:

\begin{lstlisting}
int glfwGetJoystickParam( int joy, int param )
\end{lstlisting}

The \textit{joy} argument specifies which joystick to retrieve the
parameter from, and it should be GLFW\_JOYSTICK\_\textit{n}, where
\textit{n} is in the range 1 to 16. The \textit{param} argument specifies
which parameter to retrieve. To determine if a joystick is connected,
\textit{param} should be GLFW\_PRESENT, which will cause the function to
return GL\_TRUE if the joystick is connected, or GL\_FALSE if it is not.
To determine the number of axes or buttons that are supported by the
joystick, \textit{param} should be GLFW\_AXES or GLFW\_BUTTONS,
respectively.

Note that \GLFW\ supports both D-pads and POVs, even though they are not
explicitly mentioned in the API.  D-pads are exposed as a set of four buttons
and POVs are as two axes.


%-------------------------------------------------------------------------
\subsection{Joystick position}
To get the current axis positions of the joystick, the
\textbf{glfwGetJoystickPos} is used:

\begin{lstlisting}
int glfwGetJoystickPos( int joy, float *pos, int numaxes )
\end{lstlisting}

As with \textbf{glfwGetJoystickParam}, the \textit{joy} argument
specifies which joystick to retrieve information from. The
\textit{numaxes} argument specifies how many axes to return positions for and the
\textit{pos} argument specifies an array in which they
are stored. The function returns the actual number of axes that were
returned, which could be less than \textit{numaxes} if the joystick does
not support all the requested axes, or if the joystick is not connected.

For instance, to get the position of the first two axes (the X and Y axes)
of joystick 1, the following code can be used:

\begin{lstlisting}
float position[ 2 ];

glfwGetJoystickPos( GLFW_JOYSTICK_1, position, 2 );
\end{lstlisting}

After this call, the first element of the \textit{position} array will
hold the X axis position of the joystick, and the second element will hold
the Y axis position. In this example we do not use the information about
how many axes were really returned.

The position of an axis can be in the range -1.0 to 1.0, where positive
values represent right, forward or up directions, while negative values
represent left, back or down directions. If a requested axis is not
supported by the joystick, the corresponding array element will be set
to zero. The same goes for the situation when the joystick is not
connected (all axes are treated as unsupported).


%-------------------------------------------------------------------------
\subsection{Joystick buttons}
A function similar to the \textbf{glfwGetJoystickPos} function is
available for querying the state of joystick buttons, namely the
\textbf{glfwGetJoystickButtons} function:

\begin{lstlisting}
int glfwGetJoystickButtons( int joy, unsigned char *buttons,
                            int numbuttons )
\end{lstlisting}

The function works just like the \textbf{glfwGetJoystickAxis} function, except
that it returns the state of joystick buttons instead of axis positions. Each
button in the array specified by the \textit{buttons} argument can be either
GLFW\_PRESS or GLFW\_RELEASE, indicating whether the corresponding button is
currently held down or not. Unsupported buttons will have the value
GLFW\_RELEASE.


%-------------------------------------------------------------------------
% Timing
%-------------------------------------------------------------------------
\chapter{Timing}
\thispagestyle{fancy}

%-------------------------------------------------------------------------
\section{High Resolution Timer}
In most applications, it is useful to know exactly how much time has
passed between point $A$ and point $B$ in a program. A typical situation
is in a game, where you need to know how much time has passed between two
rendered frames in order to calculate the correct movement and physics
etc. Another example is when you want to benchmark a certain piece of
code.

\GLFW\ provides a high-resolution timer, which reports a double precision
floating point value representing the number of seconds that have passed
since \textbf{glfwInit} was called. The timer is accessed with the
function \textbf{glfwGetTime}:

\begin{lstlisting}
double glfwGetTime( void )
\end{lstlisting}

The precision of the timer depends on which computer and operating
system you are running, but it is almost guaranteed to be better than
$10~ms$, and in most cases it is much better than $1~ms$ (on a modern PC
you can get resolutions in the order of $1~ns$).

It is possible to set the value of the high precision timer using the
\textbf{glfwSetTime} function:

\begin{lstlisting}
void glfwSetTime( double time )
\end{lstlisting}

The argument \textit{time} is the time, in seconds, that the timer should
be set to.


%-------------------------------------------------------------------------
\section{Sleep}
Sometimes it can be useful to put a program to sleep for a short time. It
can be used to reduce the CPU load in various situations. For this
purpose, there is a function called \textbf{glfwSleep}, which has the
following C syntax:

\begin{lstlisting}
void glfwSleep( double time )
\end{lstlisting}

The function will put the calling thread to sleep for the time specified
with the argument \textit{time}, which has the unit seconds. When
\textbf{glfwSleep} is called, the calling thread will be put in waiting
state, and thus will not consume any CPU time.

Note that there is generally a minimum sleep time that will be recognized
by the operating system, which is usually coupled to the task-switching
interval. This minimum time is often in the range $5~-~20 ms$, and it is
not possible to make a thread sleep for less than that time. Specifying a
very small sleep time may result in \textbf{glfwSleep} returning
immediately, without putting the thread to sleep.


%-------------------------------------------------------------------------
% Image and Texture Import
%-------------------------------------------------------------------------
\chapter{Image and Texture Import}
\thispagestyle{fancy}
In many, if not most, \OpenGL\ applications you want to use pre-generated
2D images for surface textures, light maps, transparency maps etc.
Typically these images are stored with a standard image format in a file,
which requires the program to decode and load the image(s) from file(s),
which can require much work from the programmer.

To make life easier for \OpenGL\ developers, \GLFW\ has built-in support
for loading images from files.


%-------------------------------------------------------------------------
\section{Texture Loading}
To load a texture from a file, you can use the function
\textbf{glfwLoadTexture2D}:

\begin{lstlisting}
int glfwLoadTexture2D( const char *name, int flags )
\end{lstlisting}

This function reads a 2D image from a Truevision Targa format file (.TGA)
with the name given by \textit{name}, and uploads it to texture memory.
It is similar to the \OpenGL\ function \textbf{glTexImage2D}, except that
the image data is read from a file instead of from main memory, and all
the pixel format and data storage flags are handled automatically. The
\textit{flags} argument can be used to control how the texture is
loaded.

If \textit{flags} is GLFW\_ORIGIN\_UL\_BIT, the origin of the
texture will be the upper left corner (otherwise it is the lower left
corner). If \textit{flags} is GLFW\_BUILD\_MIPMAPS\_BIT, all mipmap levels
will be generated and uploaded to texture memory (otherwise only one
mipmap level is loaded). If \textit{flags} is GLFW\_ALPHA\_MAP\_BIT, then
any gray scale images will be loaded as alpha maps rather than luminance
maps.

To make combinations of the flags, or them together (e.g. like this:
\texttt{GLFW\_ORIGIN\_UL\_BIT | GLFW\_BUILD\_MIPMAPS\_BIT}).

Here is an example of how to upload a texture from a file to \OpenGL\
texture memory, and configure the texture for trilinear interpolation
(assuming an \OpenGL\ window has been opened successfully):

\begin{mysamepage}[10]
\begin{lstlisting}
    // Load texture from file, and build all mipmap levels
    glfwLoadTexture2D( "mytexture.tga", GLFW_BUILD_MIPMAPS_BIT );

    // Use trilinear interpolation for minification
    glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER,
                     GL_LINEAR_MIPMAP_LINEAR );

    // Use bilinear interpolation for magnification
    glTexParameteri( GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER,
                     GL_LINEAR );

    // Enable texturing
    glEnable( GL_TEXTURE_2D );
\end{lstlisting}
\end{mysamepage}

As you can see, \textbf{glfwLoadTexture2D} is very easy to use. Since it
can also automatically create mipmaps when required, it is also a very
powerful function.


%-------------------------------------------------------------------------
\section{Image Loading}
In certain cases it may be useful to be able to load an image into client
memory (application memory), without directly uploading the image to
\OpenGL\ texture memory. For example, one may wish to retain a copy of the
texture in local memory for future use. Another example is when the image
is not to be used as a texture at all, e.g. if it is to be used as a
height map.

\GLFW\ also offers the possibility to load an image to application memory,
using the \textbf{glfwReadImage} function:

\begin{lstlisting}
int glfwReadImage( const char *name, GLFWimage *img, int flags )
\end{lstlisting}

The function reads the image given by the argument \textit{name}, and upon
success stores the relevant image information and pixel data in the
GLFWimage structure \textit{img}. The GLFWimage structure is defined as:

\begin{lstlisting}
typedef struct {
    int Width, Height;    // Image dimensions
    int Format;           // OpenGL pixel format
    int BytesPerPixel;    // Number of bytes per pixel
    unsigned char *Data;  // Pointer to pixel data
} GLFWimage;
\end{lstlisting}

\textit{Data} points to the loaded pixel data. If the function loaded the
image successfully, GL\_TRUE is returned, otherwise GL\_FALSE is returned.

Possible flags for the \textit{flags} argument are GLFW\_ORIGIN\_UL\_BIT,
GLFW\_NO\_RESCALE\_BIT and GLFW\_ALPHA\_MAP\_BIT. GLFW\_ORIGIN\_UL\_BIT
and GLFW\_ALPHA\_MAP\_BIT work as described for the \textbf{glfwLoadTexture2D}
function. If the GLFW\_NO\_RESCALE\_BIT flag is set, the image will not be
rescaled to the closest larger $2^m\times 2^n$ resolution, which is
otherwise the default action for images with non-power-of-two dimenstions.

When an image that was loaded with the \textbf{glfwReadImage} function is
not used anymore (e.g. when it has been uploaded to texture memory), you
should use the function \textbf{glfwFreeImage} to free the allocated
memory:

\begin{lstlisting}
void glfwFreeImage( GLFWimage *img )
\end{lstlisting}


%-------------------------------------------------------------------------
% OpenGL Extension Support
%-------------------------------------------------------------------------
\chapter{OpenGL Extension Support}
\thispagestyle{fancy}
One of the benefits of \OpenGL\ is that it is extensible. Independent
hardware vendors (IHVs) may include functionality in their \OpenGL\
implementations that exceed that of the \OpenGL\ standard.

An extension is defined by:

\begin{enumerate}
\item An extension name (e.g. GL\_ARB\_multitexture).
\item New OpenGL tokens (e.g. GL\_TEXTURE1\_ARB).
\item New OpenGL functions (e.g. \textbf{glActiveTextureARB}).
\end{enumerate}

A list of official extensions, together with their definitions, can be
found at the \textit{OpenGL Registry}
(\url{http://www.opengl.org/registry/}).

To use a certain extension, the following steps must be performed:

\begin{enumerate}
\item A compile time check for the support of the extension.
\item A run time check for the support of the extension.
\item Fetch function pointers for the extended \OpenGL\ functions (done at
      run time).
\end{enumerate}

How this is done using \GLFW\ is described in the following sections.
Please note that this chapter covers some advanced topics, and is quite
specific to the C programming language.

For a much easier way to get access to \OpenGL\ extensions, you should probably
use a dedicated extension loading library such as GLEW or GLee.  This kind of
library greatly reduces the amount of work necessary to use \OpenGL\
extensions.  GLEW in particular has been extensively tested with and works well
with \GLFW .


%-------------------------------------------------------------------------
\section{Compile Time Check}
The compile time check is necessary to perform in order to know if the
compiler include files have defined the necessary tokens. It is very easy
to do. The include file \texttt{GL/gl.h} will define a constant with the
same name as the extension, if all the extension tokens are defined. Here
is an example of how to check for the extension GL\_ARB\_multitexture:

\begin{lstlisting}
#ifdef GL_ARB_multitexture
    // Extension is supported by the include files
#else
    // Extension is not supported by the include files
    // Get a more up-to-date <GL/gl.h> file!
#endif
\end{lstlisting}


%-------------------------------------------------------------------------
\section{Runtime Check}
Even if the compiler include files have defined all the necessary tokens, a
given machine may not actually support the extension (it may have a graphics
card with a different \OpenGL\ implementation, or an older driver). That is why
it is necessary to do a run time check for the extension support as well. This
is done with the \GLFW\ function \textbf{glfwExtensionSupported}, which has the
C syntax:

\begin{lstlisting}
int glfwExtensionSupported( const char *extension )
\end{lstlisting}

The argument \textit{extension} is a null terminated ASCII string
with the extension name. \textbf{glfwExtensionSupported} returns GL\_TRUE
if the extension is supported, otherwise it returns GL\_FALSE.

Let us extend the previous example of checking for support of the
extension GL\_ARB\_multitexture. This time we add a run time check, and a
variable which we set to GL\_TRUE if the extension is supported, or
GL\_FALSE if it is not supported.

\begin{lstlisting}
int multitexture_supported;

#ifdef GL_ARB_multitexture
    // Check if extension is supported at run time
    multitexture_supported =
        glfwExtensionSupported( "GL_ARB_multitexture" );
#else
    // Extension is not supported by the include files
    // Get a more up-to-date <GL/gl.h> file!
    multitexture_supported = GL_FALSE;
#endif
\end{lstlisting}

Now it is easy to check for the extension within the program, simply do:

\begin{lstlisting}
    if( multitexture_supported )
    {
        // Use multi texturing
    }
    else
    {
        // Use some other solution (or fail)
    }
\end{lstlisting}


%-------------------------------------------------------------------------
\section{Fetching Function Pointers}
Some extensions, though not all, require the use of new \OpenGL\ functions.
These entry points are not necessarily exposed by your link libraries, making
it necessary to find them dynamically at run time.  You can retrieve these
entry points using the \textbf{glfwGetProcAddress} function:

\begin{lstlisting}
void * glfwGetProcAddress( const char *procname )
\end{lstlisting}

The argument \textit{procname} is a null terminated ASCII string
holding the name of the \OpenGL\ function. \textbf{glfwGetProcAddress}
returns the address to the function if the function is available,
otherwise NULL is returned.

Obviously, fetching the function pointer is trivial. For instance, if we
want to obtain the pointer to \textbf{glActiveTextureARB}, we simply call:

\begin{lstlisting}
glActiveTextureARB = glfwGetProcAddress( "glActiveTextureARB" );
\end{lstlisting}

However, there are many possible naming and type definition conflicts
involved with such an operation, which may result in compiler warnings or
errors. My proposed solution is the following:

\begin{itemize}
\item Do not use the function name for the variable name. Use something
      similar, perhaps by adding a prefix or suffix, and then use
      \texttt{\#define} to map the function name to your variable.
\item The standard type definition naming convention for function pointers
      is \texttt{PFN\textit{xxxx}PROC}, where \texttt{\textit{xxxx}} is
      the uppercase version of the function name (e.g.
      \texttt{PFNGLACTIVETEXTUREARBPROC}). Either make sure your compiler uses
      a compatible \texttt{gl.h} and/or \texttt{glext.h} file and rely on it to
      define these types, or use define the types yourself using a different
      naming convention (for example  \texttt{\textit{xxxx}\_T}) and do the
      type definitions yourself.
\end{itemize}

Here is a slightly longer example of how to use an extension, this time using
our own function pointer type definition):

\begin{lstlisting}
// Type definition of the function pointer
typedef void (APIENTRY * GLACTIVETEXTUREARB_T) (GLenum texture);

// Function pointer
GLACTIVETEXTUREARB_T _ActiveTextureARB;
#define glActiveTextureARB _ActiveTextureARB

// Extension availability flag
int multitexture_supported;

#ifdef GL_ARB_multitexture
    // Check if extension is supported at run time
    if( glfwExtensionSupported( "GL_ARB_multitexture" ) )
    {
        // Get the function pointer
        glActiveTextureARB = (GLACTIVETEXTUREARB_T)
            glfwGetProcAddress( "glActiveTextureARB" );

        multitexture_supported = GL_TRUE;
    }
    else
    {
        multitexture_supported = GL_FALSE;
    }
#else
    // Extension is not supported by the include files
    multitexture_supported = GL_FALSE;
#endif
\end{lstlisting}

Even this example leaves some things to be desired. First of all, the
GL\_ARB\_multitexture extension defines many more functions than the single
function used above.  Secondly, checking if an extension is supported using
\textbf{glfwExtensionSupported} is not enough to ensure that the corresponding
functions will be valid.  You also need to check that the all function pointers
returned by \textbf{glfwGetProcAddress} are non-NULL.


%-------------------------------------------------------------------------
\subsection{Function pointer type definitions}
To make a function pointer type definition, you need to know the function
prototype. This can often be found in the extension definitions (e.g. at
the \textit{OpenGL Registry}).  All the entry points that are defined by an
extension are listed with their C prototype definitions under the section
\textit{New Procedures and Functions} in the extension definition.

For instance, if we look at the definition of the
GL\_ARB\_texture\_compression extension, we find a list of new functions.
One of these is declared like this:

\begin{lstlisting}
void GetCompressedTexImageARB(enum target, int lod, void *img);
\end{lstlisting}

Like in most official \OpenGL\ documentation, all the \texttt{GL} and
\texttt{gl} prefixes have been left out. In other words, the real function
prototype would look like this:

\begin{lstlisting}
void glGetCompressedTexImageARB(GLenum target, GLint lod, void *img);
\end{lstlisting}

All we have to do to turn this prototype definition into a function
pointer type definition, is to replace the function name with
\texttt{(APIENTRY * \textit{xxxx}\_T)}, where \textit{xxxx} is the
uppercase version of the name (according to the proposed naming
convention). The keyword \texttt{APIENTRY} is needed to be compatible
between different platforms. The \GLFW\ header file \texttt{GL/glfw.h}
ensures that \texttt{APIENTRY} is properly defined on all supported platforms.

In other words, for the function \textbf{glGetCompressedTexImageARB} we
get:

\begin{lstlisting}
typedef void (APIENTRY * GLGETCOMPRESSEDTEXIMAGEARB_T)
             (GLenum target, GLint level, void *img);
\end{lstlisting}



%-------------------------------------------------------------------------
% Multi Threading
%-------------------------------------------------------------------------
\chapter{Multi-threading}
\thispagestyle{fancy}

The initial intent of \GLFW\ was to provide only the basic functionality
needed to create an \OpenGL\ application, but as \GLFW\ grew to be a
platform for portable \OpenGL\ applications, it came to include a basic
operating system independent multi-threading layer.

However, this layer is fairly isolated from the rest of \GLFW\ and most of the
rest of the API is \emph{not} thread-safe.  This is important to keep in mind
when using \GLFW\ in a multi-threaded application.


%-------------------------------------------------------------------------
\section{Why Use Multi-threading?}
Most computers being sold today have at least two CPU cores and many have four
or more.  Even the cheapest netbooks have a semblance of multi-core in the form
of hyper-threading.  With the individual cores not getting much faster,
increased performance can only be had by using the additional CPU cores.

However, the \OpenGL\ API itself is single-threaded and a given context should
only be used by a single thread at a time.  This means that the primary use for
multi-threading in the area of computer graphics isn't to distribute rendering
across multiple threads, but rather to relieve the render thread from doing
other kinds of work.  Examples include collision and dynamics ticks, audio
processing and playback, networking and even rendering steps that don't involve
calling \OpenGL .

The downside of using multi-threading is the added complexity that comes from
making a program non-sequential and to ensure that one thread does not
interfere with the data being used by another.  Whether or not it is worth
making a given application multi-threaded is a complex question and as always,
there is no substitute for data and experience.  Profile, measure and
experiment.


%-------------------------------------------------------------------------
\subsection{Avoid unnecessary waiting}
In many situations, an application is placed in a wait state, waiting for
a task to complete. Examples of such situations are: waiting for a file to
load from disk, waiting for a vertical retrace (when using a double
buffered display, such as a \GLFW\ window), waiting for a display
to be cleared or data to be sent to the graphics card.

Some or all of these operations can be done asynchronously, if the
conditions are right and the operating system supports it, but a simple
and efficient way of avoiding unnecessary waits is to use multi threading.
If there are several active threads in an application, a thread that was
waiting for CPU time can start running as soon as another thread enters a
wait state. This will speed up an application on both single and multi
processor systems.


%-------------------------------------------------------------------------
\subsection{Improve real time performance}
It is a known fact that an application becomes more responsive and
exhibits less timing problems if different jobs are assigned to separate
threads.

A typical example is streaming audio: when an audio buffer is empty, it
has to be filled with new sound again within a limited amount of time, or
strange sound loops or clicks may be the result. If a program is
displaying graphics, loading files and playing audio at the same time (a
typical game), it is very difficult to guarantee that the program will
update the audio buffers in time if everything is performed in a single
thread. On the other hand, if the audio buffer is updated from a separate
thread, it becomes a very simple task.


%-------------------------------------------------------------------------
\section{How To Use Multi Threading}
In general, every process, i.e. instance of a program, has its own memory
space and its own set of resources, such as opened files etc. As a
consequence, each process is coupled with a fairly large set of state.
When the processor changes the execution from one process to another
process, all this state has to be changed too (this is often referred to
as a context switch), which can be quite costly.

Threads are sometimes referred to as ``lightweight processes'', which
gives you a clue of what they are. In contrast to a process, a thread is a
separate execution path within a process, which shares the same memory
area and resources. This means that very little state has to be changed
when switching execution between different threads (basically only the
stack pointer and the processor registers). It also means that data
exchange between threads is very simple, and there is little or no
overhead in exchanging data, since program variables and data areas can be
shared between threads.

Writing threaded applications may be very awkward before you get used to
it, but there are a few key rules that are fairly simple to follow:

\begin{enumerate}
\item ALWAYS assure exclusive access to data that is shared between threads!
\item Make sure that threads are synchronized properly!
\item NEVER busy wait!
\end{enumerate}

In the following sections you will learn how to use the functionality of
\GLFW\ to create threads and meet these rules, and hopefully you will find
that it is not very difficult to write a multi threaded application.


%-------------------------------------------------------------------------
\section{Creating Threads}
Creating a thread in \GLFW\ is very simple. You just call the function
\textbf{glfwCreateThread}:

\begin{lstlisting}
GLFWthread glfwCreateThread( GLFWthreadfun fun, void *arg )
\end{lstlisting}

The argument \textit{fun} is a pointer to a function that will be
executed by the new thread, and \textit{arg} is an argument that is passed
to the thread. \textbf{glfwCreateThread} returns a positive thread ID
number if the thread was created successfully, or a negative number if the
thread could not be created.

When the thread function returns, the thread will die. In most cases, you
want to know when the thread has finished. A thread can wait for another
thread to die with the command \textbf{glfwWaitThread}:

\begin{lstlisting}
int glfwWaitThread( GLFWthread ID, int waitmode )
\end{lstlisting}

The argument \textit{ID} is the thread handle that was obtained when
creating the thread. If \textit{waitmode} is GLFW\_NOWAIT,
\textbf{glfwWaitThread} will return immediately with the value GL\_TRUE if
the thread died, or GL\_FALSE if it is still alive. This can be useful if
you only want to check if the thread is alive. If \textit{waitmode} is
GLFW\_WAIT, \textbf{glfwWaitThread} will wait until the specified thread
has died. Regardless of what \textit{waitmode} is, \textbf{glfwWaitThread}
will return immediately if the thread does not exist (e.g. if the thread
has already died or if ID is an invalid thread handle).

In some situations, you may want to brutally kill a thread without waiting
for it to finish. This can be done with \textbf{glfwDestroyThread}:

\begin{lstlisting}
void glfwDestroyThread( GLFWthread ID )
\end{lstlisting}

It should be noted that \textbf{glfwDestroyThread} is a very dangerous
operation, which may interrupt a thread in the middle of an important
operation, which can result in lost data or deadlocks (when a thread is
waiting for a condition to be raised, which can never be raised). In other
words, do not use this function unless you really have to do it, and if
you really know what you are doing (and what the thread that you are
killing is doing)!

To sum up what we have learned so far, here is an example program which
will print ``Hello world!'' (error checking has been left out for
brevity):

\begin{mysamepage}[20]
\begin{lstlisting}
#include <stdio.h>
#include <GL/glfw.h>

void GLFWCALL HelloFun( void *arg )
{
    printf( "Hello " );
}

int main( void )
{
    GLFWthread thread;

    glfwInit();
    thread = glfwCreateThread( HelloFun, NULL );
    glfwWaitThread( thread, GLFW_WAIT );
    printf( "world!\n" );
    glfwTerminate();

    return 0;
}
\end{lstlisting}
\end{mysamepage}

The program starts by initializing \GLFW , as always, and then it goes on
by creating a thread that will execute the function \texttt{HelloFun}. The
main thread then waits for the created thread to do its work and finish.
Finally the main thread prints ``world!'', terminates \GLFW\ and exits.
The result is that ``Hello world!'' will be printed in the console window.

You may have noticed that we have already used a simple form of thread
synchronization, by waiting for the child thread to die before we print
``world!''. If we would have placed the wait command after the print
command, there would be no way of knowing which word would be printed
first (``Hello'' or ``world!''). Our program would then suffer from a race
condition, which is a term used to describe a situation where two (or
more) threads are competing to complete a task first.

In section \ref{par:condvar} you will learn how to do advanced thread
synchronization using condition variables, which let threads wait for
certain conditions before continuing execution.


%-------------------------------------------------------------------------
\section{Data Sharing Using Mutex Objects}
In many situations you need to protect a certain data area while reading
or modifying it, so that other threads do not start changing or reading
the data while you are only half way through.

For instance, consider that you have a vector \textit{vec}, and a variable
\textit{N} telling how many elements there are in the vector. What happens
if thread $A$ adds an element to the vector at the same time as thread $B$
is removing an element from the vector? Figure \ref{fig:nomutex} shows a
possible scenario.

\begin{figure}[p]
\begin{center}
\begin{tabular}{cc}
\textbf{Thread A} & \textbf{Thread B}\\
\begin{minipage}{7cm}
\lstset{backgroundcolor=\color{codeA}}
\vspace{0.5\baselineskip}
\begin{lstlisting}
N ++;
\end{lstlisting}
\end{minipage}
&
\textit{waiting to exectue}
\\

\textit{waiting to exectue}
&
\begin{minipage}{7cm}
\vspace{0.5\baselineskip}
\lstset{backgroundcolor=\color{codeB}}
\begin{lstlisting}
x = vec[ N-1 ];
N --;
\end{lstlisting}
\end{minipage}
\\

\begin{minipage}{7cm}
\vspace{0.5\baselineskip}
\lstset{backgroundcolor=\color{codeA}}
\begin{lstlisting}
vec[ N-1 ] = y;
\end{lstlisting}
\end{minipage}
&
\textit{waiting to exectue}
\end{tabular}
\end{center}
\caption{Data sharing without mutex protection}
\label{fig:nomutex}
\end{figure}

We have created a possible race condition. The result in this case is that
thread $B$ reads an invalid element from the vector, and thread $A$
overwrites an already existing element, which is not what we wanted.

The solution is to only let one thread have access to the vector at a
time. This is done with mutex objects (mutex stands for \textit{mutual
exclusion}). The proper use of mutexes eliminates race conditions. To
create a mutex object in \GLFW , you use the function
\textbf{glfwCreateMutex}:

\begin{lstlisting}
GLFWmutex glfwCreateMutex( void )
\end{lstlisting}

\textbf{glfwCreateMutex} returns NULL if a mutex object could not be
created, otherwise a mutex handle is returned. To destroy a mutex object
that is no longer in use, call \textbf{glfwDestroyMutex}:

\begin{lstlisting}
void glfwDestroyMutex( GLFWmutex mutex )
\end{lstlisting}

Mutex objects by themselves do not contain any useful data. They act as a
lock to any arbitrary data. Any thread can lock access to the data using
the function \textbf{glfwLockMutex}:

\begin{lstlisting}
void glfwLockMutex( GLFWmutex mutex )
\end{lstlisting}

The argument \textit{mutex} is the mutex handle that was obtained when
creating the mutex. \textbf{glfwLockMutex} will block the calling thread
until the specified mutex is available (which will be immediately, if no
other thread has locked it).

Once a mutex has been locked, no other thread is allowed to lock the
mutex. Only one thread at a time can get access to the mutex, and only the
thread that has locked the mutex may use or manipulate the data which the
mutex protects. To unlock a mutex, the thread calls
\textbf{glfwUnlockMutex}:

\begin{lstlisting}
void glfwUnlockMutex( GLFWmutex mutex )
\end{lstlisting}

As soon as \textbf{glfwUnlockMutex} has been called, other threads may
lock it again.

Figure \ref{fig:withmutex} shows the scenario with the two threads
trying to access the same vector, but this time they use a mutex object
(\textit{vecmutex}).

\begin{figure}[p]
\begin{center}
\begin{tabular}{cc}
\textbf{Thread A} & \textbf{Thread B}\\
\begin{minipage}{7cm}
\lstset{backgroundcolor=\color{codeA}}
\vspace{0.5\baselineskip}
\begin{lstlisting}
glfwLockMutex( vecmutex );
N ++;
\end{lstlisting}
\end{minipage}
&
\textit{waiting to exectue}
\\

\textit{waiting to exectue}
&
\begin{minipage}{7cm}
\vspace{0.5\baselineskip}
\lstset{backgroundcolor=\color{codeB}}
\begin{lstlisting}
glfwLockMutex( vecmutex );
\end{lstlisting}
\end{minipage}
\\

\begin{minipage}{7cm}
\vspace{0.5\baselineskip}
\lstset{backgroundcolor=\color{codeA}}
\begin{lstlisting}
vec[ N-1 ] = y;
glfwUnlockMutex( vecmutex );
\end{lstlisting}
\end{minipage}
&
\textit{waiting to exectue}
\\

\textit{waiting to exectue}
&
\begin{minipage}{7cm}
\vspace{0.5\baselineskip}
\lstset{backgroundcolor=\color{codeB}}
\begin{lstlisting}
x = vec[ N-1 ];
N --;
glfwUnlockMutex( vecmutex );
\end{lstlisting}
\end{minipage}
\end{tabular}
\end{center}
\caption{Data sharing with mutex protection}
\label{fig:withmutex}
\end{figure}

In this example, thread $A$ successfully obtains a lock on the mutex and
directly starts modifying the vector data. Next, thread $B$ \textit{tries}
to get a lock on the mutex, but is placed on hold since thread $A$ has
already locked the mutex. Thread $A$ is free to continue its work, and
when it is done it unlocks the mutex. \textit{Now} thread $B$ locks the
mutex and gains exclusive access to the vector data, performs its work,
and finally unlocks the mutex.

The race condition has been avoided, and the code performs as expected.


%-------------------------------------------------------------------------
\section{Thread Synchronization Using Condition Variables}
\label{par:condvar}
Now you know how to create threads and how to safely exchange data between
threads, but there is one important thing left to solve for multi threaded
programs: conditional waits. Very often it is necessary for one thread to
wait for a condition that will be satisfied by another thread.

For instance, a thread~$A$ may need to wait for both thread~$B$ and
thread~$C$ to finish a certain task before it can continue. For starters,
we can create a mutex protecting a variable holding the number of
completed threads:

\begin{lstlisting}
GLFWmutex mutex;
int threadsdone;
\end{lstlisting}

Now, thread~$B$ and $C$ will lock the mutex and increase the
\textit{threadsdone} variable by one when they are done, and then unlock
the mutex again. Thread~$A$ can lock the mutex and check if threadsdone
is equal to 2.

If we assume that \textit{mutex} has been created successfully, the code
for the three threads ($A$, $B$ and $C$) could be the following:

\begin{mysamepage}[8]
Thread~$A$: Wait for both thread~$B$ and $C$ to finish.
\lstset{backgroundcolor=\color{codeA}}
\begin{lstlisting}
do
{
    glfwLockMutex( mutex );
    done = (threadsdone == 2);
    glfwUnlockMutex( mutex );
}
while( !done );
\end{lstlisting}
\end{mysamepage}

\begin{mysamepage}[4]
Thread~$B$ and $C$: Tell thread~$A$ that I am done.
\lstset{backgroundcolor=\color{codeB}}
\begin{lstlisting}
glfwLockMutex( mutex );
threadsdone ++;
glfwUnlockMutex( mutex );
\end{lstlisting}
\lstset{backgroundcolor=\color{code}}
\end{mysamepage}

The problem is that when thread~$A$ discovers that thread~$B$ and $C$ are
not done, it needs to check \textit{threadsdone} over and over again until
\textit{threadsdone} is 2. We have created a busy waiting loop!

The method will work without a doubt, but thread~$A$ will consume a lot of
CPU power doing nothing. What we need is a way for thread~$A$ to halt
until thread~$B$ or $C$ tells it to re-evaluate the conditions again. This
is exactly what condition variables do.

\GLFW\ supports three condition variable operations: wait, signal and
broadcast. One or more threads may wait to be woken up on a condition, and
one or more threads may signal or broadcast a condition. The difference
between signal and broadcast is that broadcasting a condition wakes up all
waiting threads (in an unspecified order, which is decided by task
scheduling rules), while signaling a condition only wakes up one waiting
thread (again, which one is unspecified).

An important property of condition variables, which separates them from
other signaling objects such as events, is that only \textit{currently
waiting} threads are affected by a condition. A condition is ``forgotten''
as soon as it has been signaled or broadcasted. That is why a condition
variable is always associated with a mutex, which protects additional
condition information, such as the ``done'' variable construct described
above.

This may all be confusing at first, but you will see that condition
variables are both simple and powerful. They can be used to construct more
abstract objects such as semaphores, events or gates (which is why \GLFW\
does not support semaphores natively, for instance).

Before we go on by solving the busy waiting scenario, let us go through
the \GLFW\ condition variable functions. Just like for mutexes, you can
create and destroy condition variable objects. The functions for doing
this are \textbf{glfwCreateCond} and \textbf{glfwDestroyCond}:

\begin{lstlisting}
GLFWcond glfwCreateCond( void )
\end{lstlisting}

\begin{lstlisting}
void glfwDestroyCond( GLFWcond cond )
\end{lstlisting}

\textbf{glfwCreateCond} returns NULL if a condition variable object could
not be created, otherwise a condition variable handle is returned. To
destroy a condition variable that is no longer in use, call
\textbf{glfwDestroyCond}.

To wait for a condition variable, you use \textbf{glfwWaitCond}, which has
the C syntax:

\begin{lstlisting}
void glfwWaitCond( GLFWcond cond, GLFWmutex mutex, double timeout )
\end{lstlisting}

When \textbf{glfwWaitCond} is called, the locked mutex specified by
\textit{mutex} will be unlocked, and the thread will be placed in a wait
state until it receives the condition \textit{cond}. As soon as the
waiting thread is woken up, the mutex \textit{mutex} will be locked again.
If \textit{timeout} is GLFW\_INFINITY, \textbf{glfwWaitCond} will wait
until the condition \textit{cond} is received. If \textit{timemout} is a
positive time (in seconds), \textbf{glfwWaitCond} will wait until the
condition cond is received or the specified time has passed.

To signal or broadcast a condition variable, you use the functions
\textbf{glfwSignalCond} and \textbf{glfwBroadcastCond}, respectively:

\begin{lstlisting}
void glfwSignalCond( GLFWcond cond )
\end{lstlisting}

\begin{lstlisting}
void glfwBroadcastCond( GLFWcond cond )
\end{lstlisting}

\textbf{glfwSignalCond} will wake up one threads that is waiting for the
condition \textit{cond}. \textbf{glfwBroadcastCond} will wake up all
threads that are waiting for the condition cond.

Now that we have the tools, let us see what we can do to solve the busy
waiting situation. First, we add a condition variable to our data set:

\begin{lstlisting}
GLFWcond  cond;
GLFWmutex mutex;
int threadsdone;
\end{lstlisting}

If we assume that \textit{mutex} and \textit{cond} have been created
successfully, the code for the three threads ($A$, $B$ and $C$) could be
the following:

\begin{mysamepage}[12]
Thread~$A$: Wait for both thread~$B$ and $C$ to finish.
\lstset{backgroundcolor=\color{codeA}}
\begin{lstlisting}
glfwLockMutex( mutex );
do
{
    done = (threadsdone == 2);
    if( !done )
    {
        glfwWaitCond( cond, mutex, GLFW_INFINITY );
    }
}
while( !done );
glfwUnlockMutex( mutex );
\end{lstlisting}
\end{mysamepage}

\begin{mysamepage}[6]
Thread~$B$ and $C$: Tell thread~$A$ that I am done.
\lstset{backgroundcolor=\color{codeB}}
\begin{lstlisting}
glfwLockMutex( mutex );
threadsdone ++;
glfwUnlockMutex( mutex );
glfwSignalCond( cond );
\end{lstlisting}
\lstset{backgroundcolor=\color{code}}
\end{mysamepage}

With the addition of a condition variable, the busy waiting loop turned
into a nice condition waiting loop, and thread~$A$ no longer wastes any
CPU time. Also note that the mutex locking and unlocking is moved outside
of the waiting loop. This is because \textbf{glfwWaitCond} effectively
performs the necessary mutex locking and unlocking for us.


%-------------------------------------------------------------------------
\section{Calling GLFW Functions From Multiple Threads}
The current release of \GLFW\ is not 100\% thread safe. In other words,
most \GLFW\ functions may cause conflicts and undefined behaviour if they
are called from different threads.

To avoid conflicts, only the following \GLFW\ API functions should be
regarded as thread safe (i.e. they can be called from any thread at any
time):

\begin{enumerate}
\item All functions that deal with threads, mutexes and condition
      variables (e.g. \textbf{glfwCreateThread}, \textbf{glfwLockMutex}
      etc).
\item The timing function \textbf{glfwSleep}.
\end{enumerate}

All other \GLFW\ API function calls should be done from a single thread.
This also makes for better future compatibility, since future versions of
\GLFW\ may implement per thread window contexts (much in the same way as
\OpenGL\ has per thread rendering contexts), for instance.


%-------------------------------------------------------------------------
% Index
%-------------------------------------------------------------------------
% ...

\end{document}
