ruby-glfw 0.9

data/glfw-src/docs/glfwug.tex

@@ -0,0 +1,2024 @@
+%-------------------------------------------------------------------------
+% GLFW Users Guide
+% API Version: 2.6
+%-------------------------------------------------------------------------
+
+% Document class
+\documentclass[a4paper,11pt,oneside]{report}
+
+% Document title and API version
+\newcommand{\glfwdoctype}[1][0]{Users Guide}
+\newcommand{\glfwapiver}[1][0]{2.6}
+
+% 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{10cm}
+
+\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 A high precision timer.
+\item Multi threading support.
+\item Support for querying and using \OpenGL\ extensions.
+\item 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 completely operating system and
+platform independent, which makes it very simple to port \GLFW\ based \OpenGL\
+applications to a variety of platforms.
+
+Currently supported platforms are:
+\begin{itemize}
+\item Microsoft Windows\textsuperscript{\textregistered} 95/98/ME/NT/2000/XP/.NET Server.
+\item Unix\textsuperscript{\textregistered} or Unix�-like systems running the
+X Window System\texttrademark, e.g. Linux\textsuperscript{\textregistered},
+IRIX\textsuperscript{\textregistered}, FreeBSD\textsuperscript{\textregistered},
+Solaris\texttrademark, QNX\textsuperscript{\textregistered} and
+Mac OS\textsuperscript{\textregistered} X.
+\item Mac OS\textsuperscript{\textregistered} X (Carbon)\footnote{Support for joysticks missing at the time of writing.}
+\end{itemize}
+
+
+%-------------------------------------------------------------------------
+% 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{Initializing GLFW}
+Before using any of the \GLFW\ functions, it is necessary to call
+\textbf{glfwInit}. It initializes internal working variables that are used
+by other \GLFW\ functions. 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}, which makes a clean
+up and places \GLFW\ in a non-initialized state (i.e. it is necessary to
+call \textbf{glfwInit} again before using any \GLFW\ functions). The C
+syntax is:
+
+\begin{lstlisting}
+void glfwTerminate( void )
+\end{lstlisting}
+
+Among other things, \textbf{glfwTerminate} closes the \OpenGL\ window
+unless it was closed manually, and kills any running threads that were
+created using \GLFW .
+
+
+%-------------------------------------------------------------------------
+\section{Opening An OpenGL Window}
+Opening an \OpenGL\ window is done with the function
+\textbf{glfwOpenWindow}. The function takes nine arguments, which are used
+to describe the following properties of the window to open:
+
+\begin{itemize}
+\item Window dimensions (width and height) in pixels.
+\item Color and alpha buffer depth.
+\item Depth buffer (Z-buffer) depth.
+\item Stencil buffer depth.
+\item 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
+s.c. fullscreen window, or a regular window.
+
+If \textit{mode} is GLFW\_FULLSCREEN, the window will cover the entire
+screen and no window borders 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
+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}
+
+
+%-------------------------------------------------------------------------
+\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
+(or 1) if the key is currently held down, or GLFW\_RELEASE (or 0) 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. In
+the following example some error-checking has been omitted for the sake of
+brevity:
+
+\begin{lstlisting}
+#include <GL/glfw.h>
+
+int main( void )
+{
+    int running = GL_TRUE;
+
+    // Initialize GLFW
+    glfwInit();
+
+    // Open an OpenGL window
+    if( !glfwOpenWindow( 300,300, 0,0,0,0,0,0, GLFW_WINDOW ) )
+    {
+        glfwTerminate();
+        return 0;
+    }
+
+    // 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
+    return 0;
+}
+\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 an accumulator buffer,
+auxiliary buffers and stereo rendering 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 accumulator buffer.\\ \hline
+GLFW\_ACCUM\_GREEN\_BITS & 0                & Number of bits for the green channel of the accumulator buffer.\\ \hline
+GLFW\_ACCUM\_BLUE\_BITS  & 0                & Number of bits for the blue channel of the accumulator buffer.\\ \hline
+GLFW\_ACCUM\_ALPHA\_BITS & 0                & Number of bits for the alpha channel of the accumulator 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 (not used for fullscreen windows).\\ \hline
+GLFW\_FSAA\_SAMPLES      & 0                & Number of samples to use for the multisampling buffer. Zero disables multisampling.\\ \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 accumulator 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.
+
+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 accumulator buffer.\\ \hline
+GLFW\_ACCUM\_GREEN\_BITS & Number of bits for the green channel of the accumulator buffer.\\ \hline
+GLFW\_ACCUM\_BLUE\_BITS  & Number of bits for the blue channel of the accumulator buffer.\\ \hline
+GLFW\_ACCUM\_ALPHA\_BITS & Number of bits for the alpha channel of the accumulator buffer.\\ \hline
+GLFW\_AUX\_BUFFERS       & Number of auxiliary buffers.\\ \hline
+GLFW\_STEREO             & GL\_TRUE if stereo rendering is supported, else GL\_FALSE.\\ \hline
+GLFW\_FSAA\_SAMPLES      & Number of multisampling buffer samples. Zero indicated multisampling is disabled.\\ \hline
+GLFW\_WINDOW\_NO\_RESIZE & GL\_TRUE if the window cannot be resized, else GL\_FALSE.\\ \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 WinWidth, WinHeight;
+
+void GLFWCALL WindowResize( int width, int height )
+{
+    WinWidth  = width;
+    WinHeight = 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 \textit{width} and \textit{height} arguments are filled out with the
+current window dimensions.
+
+
+%-------------------------------------------------------------------------
+\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}
+
+Besides swapping the front and back rendering buffers,
+\textbf{glfwSwapBuffers} also 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.
+
+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. 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 actual number of
+video modes detected on the system.
+
+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 does not have to be a concern, since
+\textbf{glfwSwapBuffers} is called every frame, which should be often
+enough (about 10-100 times per second for a normal \OpenGL\ application).
+One exception is when rendering is paused, and then the program waits for
+input to begin animation again. In this case \textbf{glfwPollEvents} has
+to be called repeatedly until any new input events arrive.
+
+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\ gives three options 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, either of the
+methods may be more suitable. The main difference between the two last
+options 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.
+
+An 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.
+
+A callback function can be useful in some situations. For instance it can
+replace multiple \textbf{glfwGetKey} calls with a switch/case statement.
+
+%-------------------------------------------------------------------------
+\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
+character code, 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 read the mouse position, you can use the function
+\textbf{glfwGetMousePos}:
+
+\begin{lstlisting}
+void glfwGetMousePos( int *x, int *y )
+\end{lstlisting}
+
+The arguments \textit{x} and \textit{y} point to integer variables that
+will be updated with the current absolute mouse position. An alternative
+is to use a callback function instead, 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 position changes. The first argument to the callback function is
+the mouse x position, and the second argument is the mouse y position.
+
+
+%-------------------------------------------------------------------------
+\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 one of the following mouse button
+identifiers: 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 mouse buttons appear as held down until the button is checked for
+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, which can be thought of as a third mouse
+axis. 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.
+
+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.
+
+
+%-------------------------------------------------------------------------
+\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, and the
+\textit{pos} argument specifies an array in which all the axis positions
+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, telling if 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 Extension Registry}
+(\url{http://oss.sgi.com/projects/ogl-sample/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.
+
+
+%-------------------------------------------------------------------------
+\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
+    // Update your <GL/gl.h> file!
+#endif
+\end{lstlisting}
+
+
+%-------------------------------------------------------------------------
+\section{Runtime Check}
+Even if the compiler include files have defined all the necessary tokens,
+the target system may not support the extension (perhaps it has a
+different graphic card with a different \OpenGL\ implementation, or it has
+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 ISO~8859-1 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
+    // Update your <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 (not all) require the use of new \OpenGL\ functions, which
+are not necessarily defined by your link libraries. Thus it is necessary
+to get the function pointers dynamically at run time. This is done with
+the \GLFW\ function \textbf{glfwGetProcAddress}:
+
+\begin{lstlisting}
+void * glfwGetProcAddress( const char *procname )
+\end{lstlisting}
+
+The argument \textit{procname} is a null terminated ISO~8859-1 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 with 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 that a
+      compatible \texttt{gl.h} and/or \texttt{glext.h} file is used by
+      your compiler and rely on it to do the type definitions for you, or
+      use a custom type definition naming convention (e.g.
+      \texttt{\textit{xxxx}\_T} or something) and do the type definitions
+      yourself.
+\end{itemize}
+
+Here is an example of how to do it (here we use our own function pointer
+type defintion):
+
+\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}
+
+Please note that the code example is not 100\% complete. First of all,
+the GL\_ARB\_multitexture extension defines many more functions than the
+single function that the code example defines. 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 if the function pointers returned by \textbf{glfwGetProcAddress} are
+non-NULL values.
+
+
+%-------------------------------------------------------------------------
+\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 Extension Registry}). All the functions that are
+defined for 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 the functions looks 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\ include file \texttt{GL/glfw.h}
+always makes sure that \texttt{APIENTRY} is properly defined, regardless
+of which platform the program is compiled on.
+
+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}
+Multi threading may not seem to be related to \OpenGL , and thus it may
+seem to be out of the scope of \GLFW\ to provide multi threading support.
+The initial intent of \GLFW\ was to provide the very basic functionality
+needed to create an \OpenGL\ application, but as \GLFW\ grew to be a
+platform for portable \OpenGL\ applications, it felt natural to include an
+operating system independent multi threading layer in \GLFW . Hopefully
+this will make \GLFW\ more attractive for advanced \OpenGL\ developers, as
+well as inspire more programmers to use multi threading.
+
+In this chapter you will learn about multi threading and how you can use
+\GLFW\ to create multi threaded applications.
+
+
+%-------------------------------------------------------------------------
+\section{Why Use Multi Threading?}
+Multi threading is not a new technology, neither is it an advanced
+technology. In fact, multi threading could be found as early as 1985 in
+consumer computers, namely the Amiga, whose operating system implemented
+preemptive multi threading. During the early and mid 90's, consumer level
+operating systems emerged for Intel based PCs that supported multi
+threading. Still, over a decade later, many programmers, especially game
+programmers, feel reluctant to using threading in their applications.
+Why?
+
+There are probably many reasons that one can think of to avoid multi
+threading, but many of them are based on ignorance and myths. The foremost
+reason for not using multi threading is probably that it requires a new
+way of thinking, but once accepted, threaded programming can take your
+program to new performance levels and solve many problematic timing and
+synchronization issues.
+
+In the following sections a few key reasons for using multi threaded
+programming will be presented.
+
+
+%-------------------------------------------------------------------------
+\subsection{Take advantage of multi processor systems}
+If an application is divided into several threads that can execute
+concurrently, these threads will automatically execute on separate
+processors in parallel on an SMP (symmetric multi-processing) system.
+
+Multi processor platforms are becoming increasingly common, in many
+different forms. The classic multi processor system is based around several
+processor chips that execute in parallel. More recent solutions focus on
+placing several processor cores on a single chip. These cores may be
+a few identical general purpose processors, or they may be several smaller,
+specialized cores, such as in the Cell architecture by IBM, which is
+used in the Playstation~3 game console.
+
+Another emerging technology known as SMT (symmetric multi threading) is
+also becoming more and more popular. In short, it takes a single physical
+processor, and divides it into several logical processors that can execute
+separate threads. The idea behind this is to better utilize all available
+CPU resources by running independent pieces of code on the same physical
+CPU.
+
+The problem with SMP systems is of course that if an application is not
+multi threaded, only one of the available processors will actually be
+used to execute the application. This is probably the most important
+aspect of multi threading. For SMP systems to be really useful, programs
+\emph{must} be multi threaded.
+
+
+%-------------------------------------------------------------------------
+\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\ \OpenGL\ window), waiting for a display
+to be cleared or data to be sent to the graphic 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 program runs as a process, which 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}