glfw/docs/glfwrm.tex

%-------------------------------------------------------------------------
% GLFW Reference Manual
% API Version: 3.0
%-------------------------------------------------------------------------

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

% Document title and API version
\newcommand{\glfwdoctype}[1][0]{Reference Manual}
\newcommand{\glfwapiver}[1][0]{3.0}

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

% PDF specific document settings
\hypersetup{pdftitle={GLFW Reference Manual}}
\hypersetup{pdfauthor={Camilla Berglund}}
\hypersetup{pdfkeywords={GLFW,OpenGL,reference,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 primarily a function reference manual for the \GLFW\ API.
For a description of how to use \GLFW\ you should refer to the
\textit{GLFW Users Guide}.
\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

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


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

%-------------------------------------------------------------------------
% List of tables
%-------------------------------------------------------------------------
\listoftables
\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\ context and its associated window.
\item Keyboard, mouse and joystick input.
\item A high precision timer.
\item Support for querying and using \OpenGL\ extensions.
\end{itemize}

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 looks and behaves the same on all supported
platforms, making 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} (32-bit only).
\item Unix\textsuperscript{\textregistered} or Unix<69>-like systems running
resonably a modern version of the X Window
System\texttrademark\footnote{X11.app on Mac OS X is not supported due to its
incomplete implementation of GLXFBConfigs} e.g.
Linux\textsuperscript{\textregistered},
FreeBSD\textsuperscript{\textregistered} and Solaris\texttrademark (32- and
64-bit).
\item Mac OS\textsuperscript{\textregistered} X, using Cocoa\footnote{Joystick
input is not yet supported on Mac OS X.} (32- and 64-bit).
\end{itemize}



%-------------------------------------------------------------------------
% GLFW Operation
%-------------------------------------------------------------------------
\chapter{GLFW Operation Overview}
\thispagestyle{fancy}


%-------------------------------------------------------------------------
\section{The GLFW Window}
\GLFW\ only supports having one window open at a time. The window can be either
a normal desktop window or a fullscreen window. The latter is completely
undecorated, without window borders, and covers the entire monitor. With a
fullscreen window, it is also possible to select which video mode to use.

When a window is opened, an \OpenGL\ rendering context is created and
attached to the entire client area of the window. When the window is closed,
the \OpenGL\ rendering context is detached and destroyed.

Through a window it is possible to receive user input in the form of
keyboard and mouse input. User input is exposed through the \GLFW\ API
primarily via a set of callback functions. Also, \GLFW\ stores most user input
as internal state that can be queried through different \GLFW\ API functions
(for instance it is possible to query the position of the mouse cursor with the
\textbf{glfwGetMousePos} function).

As for user input, it is possible to receive information about window
state changes, such as window resize or close events, through callback
functions. It is also possible to query some kinds of information about the
window information using \GLFW\ API functions.


%-------------------------------------------------------------------------
\section{The GLFW Event Loop}
The \GLFW\ event loop is an open loop, which means that it is up to the
programmer to design the loop. Events are processed by calling specific
\GLFW\ functions, which in turn query the system for new input and window
events and reports these events back to the program through callback
functions.

The programmer decides when to call the event processing functions and
when to abort the event loop.

In pseudo language, a typical event loop might look like this:

\begin{lstlisting}
  repeat until window is closed
  {
      poll events
      draw OpenGL graphics
  }
\end{lstlisting}

There are two ways to handle events in \GLFW :

\begin{itemize}
  \item Block the event loop while waiting for new events.
  \item Poll for new events and continue the loop regardless of whether there
        are any new events or not.
\end{itemize}

The first method is useful for interactive applications that do not
need to refresh the \OpenGL\ display unless the user interacts with the
application through user input. Typical applications are CAD software
and other kinds of editors.

The second method is useful for applications that need to refresh the
\OpenGL\ display constantly, regardless of user input, such as games,
demos, 3D animations, screen savers and so on.


%-------------------------------------------------------------------------
\section{Callback Functions}
Using callback functions can be a good method for receiving up to date
information about window state and user input. When a window has been
opened, it is possible to register custom callback functions that will
be called when certain events occur.

Callback functions are called from any of the event polling functions
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or
\textbf{glfwSwapBuffers}.

Callback functions should \emph{only} be used to gather information. Since
the callback functions are called from within the internal \GLFW\ event
polling loops, they should not call any \GLFW\ functions that might
result in considerable \GLFW\ state changes, nor stall the event polling
loop for a lengthy period of time.

In other words, most or all \OpenGL\ rendering should be called from the
main application event loop, not from any of the \GLFW\ callback
functions. Also, the only \GLFW\ functions that may be safely called from
callback functions are the different Get functions (e.g.
\textbf{glfwGetKey}, \textbf{glfwGetTime}, \textbf{glfwGetWindowParam}
etc.).


%-------------------------------------------------------------------------
% Function Reference
%-------------------------------------------------------------------------
\chapter{Function Reference}
\thispagestyle{fancy}

%-------------------------------------------------------------------------
\section{GLFW Initialization and Termination}
Before any other \GLFW\ functions can be used, \GLFW\ must be initialized to
ensure proper functionality, and before a program terminates \GLFW\ should be
terminated in order to free allocated resources, memory, etc.


%-------------------------------------------------------------------------
\subsection{glfwInit}

\textbf{C language syntax}
\begin{lstlisting}
int glfwInit(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
If the function succeeds, GL\_TRUE is returned.\\
If the function fails, GL\_FALSE is returned.
\end{refreturn}

\begin{refdescription}
The glfwInit function initializes \GLFW. No other \GLFW\ functions may be
called before this function has succeeded.
\end{refdescription}

\begin{refnotes}
This function may take several seconds to complete on some systems, while
on other systems it may take only a fraction of a second to complete.

This function registers a function calling \textbf{glfwTerminate} with the
atexit facility of the C library.

On Mac OS X, this function will change the current directory of the application
to the \textbf{Contents/Resources} subdirectory of the application's bundle, if
present.  For more information on bundles, see the Bundle Programming Guide
provided by Apple.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwTerminate}

\textbf{C language syntax}
\begin{lstlisting}
void glfwTerminate(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function terminates \GLFW. Among other things it closes the window, if
open.  This function should be called before a program exits.
\end{refdescription}


%-------------------------------------------------------------------------
\subsection{glfwGetVersion}

\textbf{C language syntax}
\begin{lstlisting}
void glfwGetVersion(int* major, int* minor, int* rev)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{major}]\ \\
  Pointer to an integer that will hold the major version number.
\item [\textit{minor}]\ \\
  Pointer to an integer that will hold the minor version number.
\item [\textit{rev}]\ \\
  Pointer to an integer that will hold the revision.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns the major and minor version numbers and the revision
for the currently linked \GLFW\ library.
\end{refreturn}

\begin{refdescription}
This function returns the \GLFW\ library version.
\end{refdescription}


%-------------------------------------------------------------------------
\pagebreak
\section{Window Handling}
The primary purpose of \GLFW\ is to provide a simple interface to
\OpenGL\ context creation and window management. \GLFW\ supports one window at
a time, which can be either a normal desktop window or a fullscreen window.


%-------------------------------------------------------------------------
\subsection{glfwOpenWindow}

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

\begin{refparameters}
\begin{description}
\item [\textit{width}]\ \\
  The width of the window. If \textit{width} is zero, it will be
  calculated as ${width=\frac{4}{3}height}$, if \textit{height} is not
  zero. If both \textit{width} and \textit{height} are zero,
  \textit{width} will be set to 640.
\item [\textit{height}]\ \\
  The height of the window. If \textit{height} is zero, it will be
  calculated as ${height=\frac{3}{4}width}$, if \textit{width} is not
  zero. If both \textit{width} and \textit{height} are zero,
  \textit{height} will be set to 480.
\item [\textit{redbits, greenbits, bluebits}]\ \\
  The number of bits to use for each color component of the color buffer
  (0 means default color depth). For instance, setting \textit{redbits=5,
  greenbits=6 and bluebits=5} will create a 16-<2D>bit color buffer, if
  possible.
\item [\textit{alphabits}]\ \\
  The number of bits to use for the alpha channel of the color buffer (0 means
  no alpha channel).
\item [\textit{depthbits}]\ \\
  The number of bits to use for the depth buffer (0 means no depth
  buffer).
\item [\textit{stencilbits}]\ \\
  The number of bits to use for the stencil buffer (0 means no stencil
  buffer).
\item [\textit{mode}]\ \\
  Selects which type of \OpenGL\ window to use. \textit{mode} must be
  either GLFW\_WINDOW, which will generate a normal desktop window, or
  GLFW\_FULLSCREEN, which will generate a window which covers the entire
  screen. When GLFW\_FULLSCREEN is selected, the video mode will be
  changed to the resolution that closest matches the \textit{width} and
  \textit{height} parameters.
\end{description}
\end{refparameters}

\begin{refreturn}
If the function succeeds, GL\_TRUE is returned.\\
If the function fails, GL\_FALSE is returned.
\end{refreturn}

\begin{refdescription}
This function opens a window that best matches the parameters given to the
function. How well the resulting window matches the desired window depends
mostly on the available hardware and \OpenGL\ drivers. In general,
selecting a fullscreen mode has better chances of generating a close match
of buffers and channel sizes than does a normal desktop window, since \GLFW\
can freely select from all the available video modes. A desktop window is
normally restricted to the video mode of the desktop.
\end{refdescription}

\begin{refnotes}
For additional control of window properties, see
\textbf{glfwOpenWindowHint}.

In fullscreen mode the mouse cursor is hidden by default and the
screensaver is prohibited from starting. In windowed mode the mouse
cursor is visible and screensavers are allowed to start. To change the
visibility of the mouse cursor, use \textbf{glfwEnable} or
\textbf{glfwDisable} with the argument GLFW\_MOUSE\_CURSOR.

In order to determine the actual properties of an opened window, use
\textbf{glfwGetWindowParam} and \textbf{glfwGetWindowSize} (or
\textbf{glfwSetWindowSizeCallback}).

On Microsoft Windows, if the executable has an icon resource named
\textbf{GLFW\_ICON}, it will be set as the icon for the window.  If no such
icon is present, the \textbf{IDI\_WINLOGO} icon will be used instead.

On Mac OS X the \GLFW\ window has no icon, but programs using \GLFW\ will use
the application bundle's icon.  For more information on bundles, see the Bundle
Programming Guide provided by Apple.

For information on how the availability of different platform-specific
extensions affect the behavior of this function, see appendix
\ref{chap:compatibility}.
\end{refnotes}


%-------------------------------------------------------------------------
\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}


%-------------------------------------------------------------------------
\subsection{glfwOpenWindowHint}

\textbf{C language syntax}
\begin{lstlisting}
void glfwOpenWindowHint(int target, int hint)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{target}]\ \\
  Can be any of the tokens in the table \ref{tab:winhints}.
\item [\textit{hint}]\ \\
  An integer giving the value of the corresponding token (see table
  \ref{tab:winhints}).
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets additional properties for a window that is to be opened.
For a hint to be registered, the function must be called before calling
\textbf{glfwOpenWindow}. When the \textbf{glfwOpenWindow} function is
called, any hints that were registered with the \textbf{glfwOpenWindowHint}
function are used for setting the corresponding window properties, and
then all hints are reset to their default values.
\end{refdescription}

\begin{refnotes}
In order to determine the actual properties of an opened window, use
\textbf{glfwGetWindowParam} (after the window has been opened).

GLFW\_STEREO is a hard constraint. If stereo rendering is requested, but no
stereo rendering capable pixel formats / framebuffer configs are available,
\textbf{glfwOpenWindow} will fail.

The GLFW\_REFRESH\_RATE hint should be used with caution. Most
systems have default values for monitor refresh rates that are optimal
for the specific system. Specifying the refresh rate can override these
settings, which can result in suboptimal operation. The monitor may be
unable to display the resulting video signal, or in the worst case it may
even be damaged!

The GLFW\_WINDOW\_NO\_RESIZE hint applies only to manual resizing by the user.
A window created with this hint enabled can still be resized by the application
by calling \textbf{glfwSetWindowSize}.

The GLFW\_OPENGL\_VERSION\_MAJOR and GLFW\_OPENGL\_VERSION\_MINOR hints specify
the \OpenGL\ version that the created context must be compatible with,
\emph{not} the exact version to use.  It is therefore perfectly safe to use the
default of version 1.1 for legacy code and you will still get
backwards-compatible contexts of version 3.0 and above when available.

To make the behavior of the above version hints consistent across both modern
and legacy drivers, \textbf{glfwOpenWindow} will fail if the modern creation
mechanism (as specified in \textbf{WGL\_ARB\_create\_context}
and \textbf{GLX\_ARB\_create\_context}) is unavailable \emph{and} the created
context is of a version lower than the one that was requested.

At the time of release, the exact meaning of what a "debug context" is (as
created using the GLFW\_OPENGL\_DEBUG\_CONTEXT hint) has yet to be defined by
the Khronos ARB WG.

For information on how the availability of different extensions affect the
behavior of this function, see appendix \ref{chap:compatibility}.

For full details on the workings of the \OpenGL\ version, forward-compatibility
and debug hints, see the specifications for \textbf{WGL\_ARB\_create\_context}
and \textbf{GLX\_ARB\_create\_context}, respectively.  The relevant \GLFW\
hints map very closely to their platform-specific counterparts.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwCloseWindow}

\textbf{C language syntax}
\begin{lstlisting}
void glfwCloseWindow(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function closes an opened window and destroys the associated \OpenGL\
context.
\end{refdescription}


%-------------------------------------------------------------------------
\subsection{glfwSetWindowCloseCallback}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetWindowCloseCallback(GLFWwindowclosefun cbfun)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{cbfun}]\ \\
  Pointer to a callback function that will be called when a user requests
  that the window should be closed, typically by clicking the window close
  icon (e.g. the cross in the upper right corner of a window under
  Microsoft Windows), and on Mac OS X also when selecting \textbf{Quit} from
  the application menu. The function should have the following C language
  prototype:

  \texttt{int functionname(void);}

  Where \textit{functionname} is the name of the callback function. The
  return value of the callback function indicates wether or not the window
  close action should continue. If the function returns GL\_TRUE, the
  window will be closed. If the function returns GL\_FALSE, the window
  will not be closed.

  If \textit{cbfun} is NULL, any previously set callback function
  will be unset.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the callback for window close events.

A window has to be opened for this function to have any effect.
\end{refdescription}

\begin{refnotes}
Window close events are recorded continuously, but only reported when
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called.

The \OpenGL\ context is still valid when this function is called.

Note that the window close callback function is not called when
\textbf{glfwCloseWindow} is called, but only when the close request
comes from the window manager.

Do \emph{not} call \textbf{glfwCloseWindow} from a window close
callback function. Close the window by returning GL\_TRUE from the
function.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetWindowTitle}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetWindowTitle(const char* title)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{title}]\ \\
  Pointer to a  null terminated ISO~8859-1 (8-bit Latin~1) string that
  holds the title of the window.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function changes the title of the opened window.
\end{refdescription}

\begin{refnotes}
The title property of a window is often used in situations other than for
the window title, such as the title of an application icon when it is in
iconified state.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetWindowSize}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetWindowSize(int width, int height)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{width}]\ \\
  Width of the window.
\item [\textit{height}]\ \\
  Height of the window.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function changes the size of an opened window. The \textit{width} and
\textit{height} parameters denote the size of the client area of the
window (i.e. excluding any window borders and decorations).

If the window is in fullscreen mode, the video mode will be changed to a
resolution that closest matches the width and height parameters (the
number of color bits will not be changed).
\end{refdescription}

\begin{refnotes}
This function has no effect if the window is iconified.

The \OpenGL\ context is guaranteed to be preserved after calling
\textbf{glfwSetWindowSize}, even if the video mode is changed.

This function is not affected by the value of the GLFW\_WINDOW\_NO\_RESIZE
hint.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetWindowPos}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetWindowPos(int x, int y)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{x}]\ \\
  Horizontal position of the window, relative to the upper left corner
  of the desktop.
\item [\textit{y}]\ \\
  Vertical position of the window, relative to the upper left corner of
  the desktop.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function changes the position of an opened window. It does not have
any effect on a fullscreen window.
\end{refdescription}

\begin{refnotes}
This function has no effect if the window is iconified.

The behaviour of this function on multi-monitor systems is ill-defined.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwGetWindowSize}

\textbf{C language syntax}
\begin{lstlisting}
void glfwGetWindowSize(int* width, int* height)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{width}]\ \\
  Pointer to an integer that will hold the width of the window.
\item [\textit{height}]\ \\
  Pointer to an integer that will hold the height of the window.
\end{description}
\end{refparameters}

\begin{refreturn}
The current width and height of the opened window is returned in the
\textit{width} and \textit{height} parameters, respectively.
\end{refreturn}

\begin{refdescription}
This function is used for determining the size of an opened window.
The returned values are dimensions of the client area of the window
(i.e. excluding any window borders and decorations).
\end{refdescription}

\begin{refnotes}
Even if the size of a fullscreen window does not change once the window
has been opened, it does not necessarily have to be the same as the size
that was requested using \textbf{glfwOpenWindow}. Therefor it is wise to
use this function to determine the true size of the window once it has
been opened.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetWindowSizeCallback}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetWindowSizeCallback(GLFWwindowsizefun cbfun)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{cbfun}]\ \\
  Pointer to a callback function that will be called every time the
  window size changes. The function should have the following C language
  prototype:

  \texttt{void functionname(int width, int height);}

  Where \textit{functionname} is the name of the callback function, and
  \textit{width} and \textit{height} are the dimensions of the window
  client area.

  If \textit{cbfun} is NULL, any previously set callback function
  will be unset.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the callback for window size change events.

A window has to be opened for this function to have any effect.
\end{refdescription}

\begin{refnotes}
Window size changes are recorded continuously, but only reported when
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called.

When a callback function is set, it will be called with the current window
size before this function returns.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwIconifyWindow}

\textbf{C language syntax}
\begin{lstlisting}
void glfwIconifyWindow(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
Iconify a window. If the window is in fullscreen mode, then the desktop
video mode will be restored.
\end{refdescription}


%-------------------------------------------------------------------------
\subsection{glfwRestoreWindow}

\textbf{C language syntax}
\begin{lstlisting}
void glfwRestoreWindow(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
Restore an iconified window. If the window that is restored is in
fullscreen mode, then the fullscreen video mode will be restored.
\end{refdescription}


%-------------------------------------------------------------------------
\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}


%-------------------------------------------------------------------------
\subsection{glfwGetWindowParam}

\textbf{C language syntax}
\begin{lstlisting}
int glfwGetWindowParam(int param)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{param}]\ \\
  A token selecting which parameter the function should return (see
  table \ref{tab:winparams}).
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns the value the window parameter corresponding to the token
\textit{param}.  Table \ref{tab:winparams} lists the available tokens.
\end{refreturn}

\begin{refdescription}
This function is used for acquiring various properties of an opened window.
\end{refdescription}

\begin{refnotes}
GLFW\_ACCELERATED is only supported under Windows. Other systems will
always return GL\_TRUE. Under Windows, GLFW\_ACCELERATED means that the
\OpenGL\ renderer is a 3rd party renderer, rather than the fallback
Microsoft software \OpenGL\ renderer. In other words, it is not a real
guarantee that the \OpenGL\ renderer is actually hardware accelerated.

GLFW\_OPENGL\_VERSION\_MAJOR and GLFW\_OPENGL\_VERSION\_MINOR always return the
same values as those returned by \textbf{glfwGetGLVersion}.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSwapBuffers}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSwapBuffers(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function swaps the back and front color buffers of the window. If
GLFW\_AUTO\_POLL\_EVENTS is enabled (which is the default),
\textbf{glfwPollEvents} is called after swapping the front and back
buffers.
\end{refdescription}

\begin{refnotes}
In previous versions of \GLFW , \textbf{glfwPollEvents} was called
\emph{before} buffer swap.  This was changed in order to decrease input
lag but may affect code that relied on the former behavior.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSwapInterval}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSwapInterval(int interval)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{interval}]\ \\
  Minimum number of monitor vertical retraces between each buffer swap
  performed by \textbf{glfwSwapBuffers}. If \textit{interval} is zero,
  buffer swaps will not be synchronized to the vertical refresh of the
  monitor (also known as 'VSync off').
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function selects the minimum number of monitor vertical retraces that
should occur between two buffer swaps. If the selected swap interval is
one, the rate of buffer swaps will never be higher than the vertical
refresh rate of the monitor. If the selected swap interval is zero, the
rate of buffer swaps is only limited by the speed of the software and
the hardware.
\end{refdescription}

\begin{refnotes}
This function will only have an effect on hardware and drivers that support
user selection of the swap interval.  ATI drivers in particular have been known
to ignore this setting.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetWindowRefreshCallback}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetWindowRefreshCallback(GLFWwindowrefreshfun cbfun)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{cbfun}]\ \\
  Pointer to a callback function that will be called when the window client
  area needs to be refreshed. The function should have the following C
  language prototype:

  \texttt{void functionname(void);}

  Where \textit{functionname} is the name of the callback function.

  If \textit{cbfun} is NULL, any previously set callback function
  will be unset.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the callback for window refresh events, which occurs when
any part of the window client area has been damaged, and needs to be repainted
(for instance, if a part of the window that was previously occluded by another
window has become visible).

A window has to be opened for this function to have any effect.
\end{refdescription}

\begin{refnotes}
Window refresh events are recorded continuously, but only reported when
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called.

Modern windowing systems using hardware compositing, such as Aqua, Aero and
Compiz, very rarely need to refresh the contents of windows, so the specified
callback will very rarely be called on such systems.
\end{refnotes}


%-------------------------------------------------------------------------
\pagebreak
\section{Video Modes}
Since \GLFW\ supports video mode changes when using a fullscreen window,
it also provides functionality for querying which video modes are
supported on a system.


%-------------------------------------------------------------------------
\subsection{glfwGetVideoModes}

\textbf{C language syntax}
\begin{lstlisting}
int glfwGetVideoModes(GLFWvidmode* list, int maxcount)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{list}]\ \\
  A vector of \textit{GLFWvidmode} structures, which will be filled out
  by the function.
\item [\textit{maxcount}]\ \\
  Maximum number of video modes that \textit{list} vector can hold.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns the number of detected video modes (this number
will never exceed \textit{maxcount}). The \textit{list} vector is
filled out with the video modes that are supported by the system.
\end{refreturn}

\begin{refdescription}
This function returns a list of supported video modes. Each video mode is
represented by a \textit{GLFWvidmode} structure, which has the following
definition:

\begin{lstlisting}
typedef struct {
    int Width, Height; // Video resolution
    int RedBits;       // Number of red bits
    int GreenBits;     // Number of green bits
    int BlueBits;      // Number of blue bits
} GLFWvidmode;
\end{lstlisting}
\end{refdescription}

\begin{refnotes}
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.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwGetDesktopMode}

\textbf{C language syntax}
\begin{lstlisting}
void glfwGetDesktopMode(GLFWvidmode* mode)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{mode}]\ \\
  Pointer to a \textit{GLFWvidmode} structure, which will be filled out
  by the function.
\end{description}
\end{refparameters}

\begin{refreturn}
The \textit{GLFWvidmode} structure pointed to by \textit{mode} is filled
out with the desktop video mode.
\end{refreturn}

\begin{refdescription}
This function returns the desktop video mode in a \textit{GLFWvidmode}
structure. See \textbf{glfwGetVideoModes} for a definition of the
\textit{GLFWvidmode} structure.
\end{refdescription}

\begin{refnotes}
The color depth of the desktop display is always reported as the number
of bits for each individual color component (red, green and blue), even
if the desktop is not using an RGB or RGBA color format. For instance, an
indexed 256 color display may report \textit{RedBits} = 3,
\textit{GreenBits} = 3 and \textit{BlueBits} = 2, which adds up to 8 bits
in total.

The desktop video mode is the video mode used by the desktop at the time
the \GLFW\ window was opened, \textit{not} the current video mode (which
may differ from the desktop video mode if the \GLFW\ window is a
fullscreen window).
\end{refnotes}


%-------------------------------------------------------------------------
\pagebreak
\section{Input Handling}
\GLFW\ supports three channels of user input: keyboard input, mouse input
and joystick input.

Keyboard and mouse input can be treated either as events, using callback
functions, or as state, using functions for polling specific keyboard and
mouse states. Regardless of which method is used, all keyboard and mouse
input is collected using window event polling.

Joystick input is asynchronous to the keyboard and mouse input, and does
not require event polling for keeping up to date joystick information.
Also, joystick input is independent of any window, so a window does not
have to be opened for joystick input to be used.


%-------------------------------------------------------------------------
\subsection{glfwPollEvents}

\textbf{C language syntax}
\begin{lstlisting}
void glfwPollEvents(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function is used for polling for events, such as user input and
window resize events. Upon calling this function, all window states,
keyboard states and mouse states are updated. If any related callback
functions are registered, these are called during the call to
\textbf{glfwPollEvents}.
\end{refdescription}

\begin{refnotes}
\textbf{glfwPollEvents} is called implicitly from \textbf{glfwSwapBuffers}
if GLFW\_AUTO\_POLL\_EVENTS is enabled (as it is by default). Thus, if
\textbf{glfwSwapBuffers} is called frequently, which is normally the case,
there is no need to call \textbf{glfwPollEvents}.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwWaitEvents}

\textbf{C language syntax}
\begin{lstlisting}
void glfwWaitEvents(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function is used for waiting for events, such as user input and
window resize events. Upon calling this function, the calling thread will
be put to sleep until any event appears in the event queue. When events
are available, they will be processed just as they are processed by
\textbf{glfwPollEvents}.

If there are any events in the queue when the function is called, the
function will behave exactly like \textbf{glfwPollEvents} (i.e. process
all messages and then return, without blocking the calling thread).
\end{refdescription}

\begin{refnotes}
It is guaranteed that \textbf{glfwWaitEvents} will wake up on any event that
can be processed by \textbf{glfwPollEvents}. However, \GLFW\ receives many
events that are only processed internally and the function may behave
differently on different systems. Do not make any assumptions about when or why
\textbf{glfwWaitEvents} will return.
\end{refnotes}


%-------------------------------------------------------------------------
\begin{table}[p]
\begin{center}
\begin{tabular}{|l|l|} \hline \raggedright
\textbf{Name}             & \textbf{Description} \\ \hline
GLFW\_KEY\_SPACE          & Space\\ \hline
GLFW\_KEY\_ESC            & Escape\\ \hline
GLFW\_KEY\_F\textit{n}    & Function key \textit{n} (\textit{n} can be in the range 1..25)\\ \hline
GLFW\_KEY\_UP             & Cursor up\\ \hline
GLFW\_KEY\_DOWN           & Cursor down\\ \hline
GLFW\_KEY\_LEFT           & Cursor left\\ \hline
GLFW\_KEY\_RIGHT          & Cursor right\\ \hline
GLFW\_KEY\_LSHIFT         & Left shift key\\ \hline
GLFW\_KEY\_RSHIFT         & Right shift key\\ \hline
GLFW\_KEY\_LCTRL          & Left control key\\ \hline
GLFW\_KEY\_RCTRL          & Right control key\\ \hline
GLFW\_KEY\_LALT           & Left alternate function key\\ \hline
GLFW\_KEY\_RALT           & Right alternate function key\\ \hline
GLFW\_KEY\_LSUPER         & Left super key, WinKey, or command key\\ \hline
GLFW\_KEY\_RSUPER         & Right super key, WinKey, or command key\\ \hline
GLFW\_KEY\_TAB            & Tabulator\\ \hline
GLFW\_KEY\_ENTER          & Enter\\ \hline
GLFW\_KEY\_BACKSPACE      & Backspace\\ \hline
GLFW\_KEY\_INSERT         & Insert\\ \hline
GLFW\_KEY\_DEL            & Delete\\ \hline
GLFW\_KEY\_PAGEUP         & Page up\\ \hline
GLFW\_KEY\_PAGEDOWN       & Page down\\ \hline
GLFW\_KEY\_HOME           & Home\\ \hline
GLFW\_KEY\_END            & End\\ \hline
GLFW\_KEY\_KP\_\textit{n} & Keypad numeric key \textit{n} (\textit{n} can be in the range 0..9)\\ \hline
GLFW\_KEY\_KP\_DIVIDE     & Keypad divide ($\div$)\\ \hline
GLFW\_KEY\_KP\_MULTIPLY   & Keypad multiply ($\times$)\\ \hline
GLFW\_KEY\_KP\_SUBTRACT   & Keypad subtract ($-$)\\ \hline
GLFW\_KEY\_KP\_ADD        & Keypad add ($+$)\\ \hline
GLFW\_KEY\_KP\_DECIMAL    & Keypad decimal (. or ,)\\ \hline
GLFW\_KEY\_KP\_EQUAL      & Keypad equal (=)\\ \hline
GLFW\_KEY\_KP\_ENTER      & Keypad enter\\ \hline
GLFW\_KEY\_KP\_NUM\_LOCK  & Keypad num lock\\ \hline
GLFW\_KEY\_CAPS\_LOCK     & Caps lock\\ \hline
GLFW\_KEY\_SCROLL\_LOCK   & Scroll lock\\ \hline
GLFW\_KEY\_PAUSE          & Pause key\\ \hline
GLFW\_KEY\_MENU           & Menu key\\ \hline
\end{tabular}
\end{center}
\caption{Special key identifiers}
\label{tab:keys}
\end{table}


%-------------------------------------------------------------------------
\begin{table}[p]
\begin{center}
\begin{tabular}{|l|l|} \hline \raggedright
\textbf{Name}               & \textbf{Description} \\ \hline
GLFW\_MOUSE\_BUTTON\_LEFT   & Left mouse button (button 1) \\ \hline
GLFW\_MOUSE\_BUTTON\_RIGHT  & Right mouse button (button 2) \\ \hline
GLFW\_MOUSE\_BUTTON\_MIDDLE & Middle mouse button (button 3) \\ \hline
GLFW\_MOUSE\_BUTTON\_\textit{n} & Mouse button \textit{n} (\textit{n} can be in the range 1..8)\\ \hline
\end{tabular}
\end{center}
\caption{Valid mouse button identifiers}
\label{tab:mousebuttons}
\end{table}


%-------------------------------------------------------------------------
\subsection{glfwGetKey}

\textbf{C language syntax}
\begin{lstlisting}
int glfwGetKey(int key)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{key}]\ \\
  A keyboard key identifier, which can be either an uppercase printable
  ISO~8859-1 (Latin~1) character (e.g. 'A', '3' or '.'), or a special key
  identifier. Table \ref{tab:keys} lists valid special key identifiers.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns GLFW\_PRESS if the key is held down, or GLFW\_RELEASE
if the key is not held down.
\end{refreturn}

\begin{refdescription}
This function queries the current state of a specific keyboard key. The
physical location of each key depends on the system keyboard layout
setting.
\end{refdescription}

\begin{refnotes}
The constant GLFW\_KEY\_SPACE is equal to 32, which is the ISO~8859-1 code
for space.  This is the only named \GLFW\ key identifier with a value in the
ISO~8859-1 range.

Not all key codes are supported on all systems. Also, while some keys are
available on some keyboard layouts, they may not be available on other
keyboard layouts.

For systems that do not distinguish between left and right versions of
modifier keys (shift, alt and control), the left version is used (e.g.
GLFW\_KEY\_LSHIFT).

A window must be opened for the function to have any effect, and
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) must be called before any keyboard
events are recorded and reported by \textbf{glfwGetKey}.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwGetMouseButton}

\textbf{C language syntax}
\begin{lstlisting}
int glfwGetMouseButton(int button)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{button}]\ \\
  A mouse button identifier, which can be one of the mouse button
  identifiers listed in table \ref{tab:mousebuttons}.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns GLFW\_PRESS if the mouse button is held down, or
GLFW\_RELEASE if the mouse button is not held down.
\end{refreturn}

\begin{refdescription}
This function queries the current state of a specific mouse button.
\end{refdescription}

\begin{refnotes}
A window must be opened for the function to have any effect, and
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) must be called before any mouse button
events are recorded and reported by \textbf{glfwGetMouseButton}.

GLFW\_MOUSE\_BUTTON\_LEFT is equal to GLFW\_MOUSE\_BUTTON\_1.
GLFW\_MOUSE\_BUTTON\_RIGHT is equal to GLFW\_MOUSE\_BUTTON\_2.
GLFW\_MOUSE\_BUTTON\_MIDDLE is equal to GLFW\_MOUSE\_BUTTON\_3.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwGetMousePos}

\textbf{C language syntax}
\begin{lstlisting}
void glfwGetMousePos(int* xpos, int* ypos)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{xpos}]\ \\
  Pointer to an integer that will be set to the horizontal position of the
  mouse cursor.
\item [\textit{ypos}]\ \\
  Pointer to an integer that will be set to the vertical position of the mouse cursor.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns the current mouse cursor position in \textit{xpos} and
\textit{ypos}.
\end{refreturn}

\begin{refdescription}
This function returns the current mouse position. If the cursor is not
hidden, the mouse position is the cursor position, relative to the upper
left corner of the window and with the Y-axis down.  If the cursor is hidden,
the mouse position is a virtual absolute position, not limited to any
boundaries except to those implied by the maximum number that can be
represented by a signed integer.
\end{refdescription}

\begin{refnotes}
A window must be opened for the function to have any effect, and
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) must be called before any mouse
movements are recorded and reported by \textbf{glfwGetMousePos}.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetMousePos}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetMousePos(int xpos, int ypos)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{xpos}]\ \\
  Horizontal position of the mouse.
\item [\textit{ypos}]\ \\
  Vertical position of the mouse.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function changes the position of the mouse. If the cursor is visible (not
disabled), the cursor will be moved to the specified position, relative to the
upper left corner of the window client area and with the Y-axis down.  If the
cursor is hidden (disabled), only the mouse position that is reported by \GLFW\
is changed.
\end{refdescription}


%-------------------------------------------------------------------------
\subsection{glfwGetMouseWheel}

\textbf{C language syntax}
\begin{lstlisting}
int glfwGetMouseWheel(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
The function returns the current mouse wheel position.
\end{refreturn}

\begin{refdescription}
This function returns the current mouse wheel position. The mouse wheel can
be thought of as a third mouse axis, which is available as a separate
wheel or up/down stick on some mice.
\end{refdescription}

\begin{refnotes}
A window must be opened for the function to have any effect, and
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) must be called before any mouse wheel
movements are recorded and reported by \textbf{glfwGetMouseWheel}.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetMouseWheel}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetMouseWheel(int pos)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{pos}]\ \\
  Position of the mouse wheel.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function changes the position of the mouse wheel.
\end{refdescription}


%-------------------------------------------------------------------------
\subsection{glfwSetKeyCallback}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetKeyCallback(GLFWkeyfun cbfun)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{cbfun}]\ \\
  Pointer to a callback function that will be called every time a key is
  pressed or released. The function should have the following C language
  prototype:

  \texttt{void functionname(int key, int action);}

  Where \textit{functionname} is the name of the callback function,
  \textit{key} is a key identifier, which is an uppercase printable
  ISO~8859-1 character or a special key identifier (see  table
  \ref{tab:keys}), and \textit{action} is either GLFW\_PRESS or
  GLFW\_RELEASE.

  If \textit{cbfun} is NULL, any previously set callback function
  will be unset.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the callback for keyboard key events.  The callback function
is called every time the state of a single key is changed (from released to
pressed or vice versa). The reported keys are unaffected by any modifiers (such
as shift or alt) and each modifier is reported as a separate key.

A window has to be opened for this function to have any effect.
\end{refdescription}

\begin{refnotes}
Keyboard key events are not intended for text input and many languages
will not be able to be input using it.  Use Unicode character events for
text input instead.

Keyboard events are recorded continuously, but only reported when
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetCharCallback}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetCharCallback(GLFWcharfun cbfun)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{cbfun}]\ \\
  Pointer to a callback function that will be called every time a
  printable character is generated by the keyboard. The function should
  have the following C language prototype:

  \texttt{void functionname(int character, int action);}

  Where \textit{functionname} is the name of the callback function,
  \textit{character} is a Unicode (ISO~10646) character, and
  \textit{action} is either GLFW\_PRESS or GLFW\_RELEASE.

  If \textit{cbfun} is NULL, any previously set callback function
  will be unset.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the callback for keyboard character events.  The callback
function is called every time a key that results in a printable Unicode
character is pressed or released.  Characters are affected by modifiers (such
as shift or alt).

A window has to be opened for this function to have any effect.
\end{refdescription}

\begin{refnotes}
Character events are recorded continuously, but only reported when
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called.

Control characters such as tab and carriage return are not reported to
the character callback function, since they are not part of the Unicode
character set. Use the key callback function for such events (see
\textbf{glfwSetKeyCallback}).

The Unicode character set supports character codes above 255, so never
cast a Unicode character to an eight bit data type (e.g. the C language
'char' type) without first checking that the character code is less than
256. Also note that Unicode character codes 0 to 255 are equal to
ISO~8859-1 (Latin~1).
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetMouseButtonCallback}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetMouseButtonCallback(GLFWmousebuttonfun cbfun)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{cbfun}]\ \\
  Pointer to a callback function that will be called every time a mouse
  button is pressed or released. The function should have the following C
  language prototype:

  \texttt{void functionname(int button, int action);}

  Where \textit{functionname} is the name of the callback function,
  \textit{button} is a mouse button identifier (see table
  \ref{tab:mousebuttons} on page \pageref{tab:mousebuttons}), and
  \textit{action} is either GLFW\_PRESS or GLFW\_RELEASE.

  If \textit{cbfun} is NULL, any previously set callback function
  will be unset.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the callback for mouse button events.

A window has to be opened for this function to have any effect.
\end{refdescription}

\begin{refnotes}
Mouse button events are recorded continuously, but only reported when
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called.

GLFW\_MOUSE\_BUTTON\_LEFT is equal to GLFW\_MOUSE\_BUTTON\_1.
GLFW\_MOUSE\_BUTTON\_RIGHT is equal to GLFW\_MOUSE\_BUTTON\_2.
GLFW\_MOUSE\_BUTTON\_MIDDLE is equal to GLFW\_MOUSE\_BUTTON\_3.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetMousePosCallback}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetMousePosCallback(GLFWmouseposfun cbfun)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{cbfun}]\ \\
  Pointer to a callback function that will be called every time the mouse
  is moved. The function should have the following C language prototype:

  \texttt{void functionname(int x, int y);}

  Where \textit{functionname} is the name of the callback function, and
  \textit{x} and \textit{y} are the mouse coordinates (see
  \textbf{glfwGetMousePos} for more information on mouse coordinates).

  If \textit{cbfun} is NULL, any previously set callback function
  will be unset.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the callback for mouse motion events.

A window has to be opened for this function to have any effect.
\end{refdescription}

\begin{refnotes}
Mouse motion events are recorded continuously, but only reported when
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetMouseWheelCallback}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetMouseWheelCallback(GLFWmousewheelfun cbfun)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{cbfun}]\ \\
  Pointer to a callback function that will be called every time the mouse
  wheel is moved. The function should have the following C language
  prototype:

  \texttt{void functionname(int pos);}

  Where \textit{functionname} is the name of the callback function, and
  \textit{pos} is the mouse wheel position.

  If \textit{cbfun} is NULL, any previously set callback function
  will be unset.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the callback for mouse wheel events.

A window has to be opened for this function to have any effect.
\end{refdescription}

\begin{refnotes}
Mouse wheel events are recorded continuously, but only reported when
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called.
\end{refnotes}


%-------------------------------------------------------------------------
\begin{table}[p]
\begin{center}
\begin{tabular}{|l|l|}\hline \raggedright
\textbf{Name} & \textbf{Return value}\\ \hline
GLFW\_PRESENT & GL\_TRUE if the joystick is connected, else GL\_FALSE.\\ \hline
GLFW\_AXES    & Number of axes supported by the joystick.\\ \hline
GLFW\_BUTTONS & Number of buttons supported by the joystick.\\ \hline
\end{tabular}
\end{center}
\caption{Joystick parameters for \textbf{glfwGetJoystickParam}}
\label{tab:joyparams}
\end{table}


%-------------------------------------------------------------------------
\subsection{glfwGetJoystickParam}

\textbf{C language syntax}
\begin{lstlisting}
int glfwGetJoystickParam(int joy, int param)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{joy}]\ \\
  A joystick identifier, which should be GLFW\_JOYSTICK\_\textit{n}, where
  \textit{n} is in the range 1 to 16.
\item [\textit{param}]\ \\
  A token selecting which parameter the function should return (see table
  \ref{tab:joyparams}).
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns different parameters depending on the value of
\textit{param}. Table \ref{tab:joyparams} lists valid \textit{param}
values, and their corresponding return values.
\end{refreturn}

\begin{refdescription}
This function is used for acquiring various properties of a joystick.
\end{refdescription}

\begin{refnotes}
The joystick information is updated every time the function is called.

No window has to be opened for joystick information to be available.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwGetJoystickPos}

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

\begin{refparameters}
\begin{description}
\item [\textit{joy}]\ \\
  A joystick identifier, which should be GLFW\_JOYSTICK\_\textit{n}, where
  \textit{n} is in the range 1 to 16.
\item [\textit{pos}]\ \\
  An array that will hold the positional values for all requested axes.
\item [\textit{numaxes}]\ \\
  Specifies how many axes should be returned.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns the number of actually returned axes. This is the
minimum of \textit{numaxes} and the number of axes supported by the
joystick. If the joystick is not supported or connected, the function will
return 0 (zero).
\end{refreturn}

\begin{refdescription}
This function queries the current position of one or more axes of a
joystick. The positional values are returned in an array, where the first
element represents the first axis of the joystick (normally the X axis).
Each position is in the range -1.0 to 1.0. Where applicable, the positive
direction of an axis is right, forward or up, and the negative direction
is left, back or down.

If \textit{numaxes} exceeds the number of axes supported by the joystick,
or if the joystick is not available, the unused elements in the
\textit{pos} array will be set to 0.0 (zero).
\end{refdescription}

\begin{refnotes}
The joystick state is updated every time the function is called, so there
is no need to call \textbf{glfwPollEvents} or \textbf{glfwWaitEvents} for
joystick state to be updated.

Use \textbf{glfwGetJoystickParam} to retrieve joystick capabilities, such
as joystick availability and number of supported axes.

No window has to be opened for joystick input to be available.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwGetJoystickButtons}

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

\begin{refparameters}
\begin{description}
\item [\textit{joy}]\ \\
  A joystick identifier, which should be GLFW\_JOYSTICK\_\textit{n}, where
  \textit{n} is in the range 1 to 16.
\item [\textit{buttons}]\ \\
  An array that will hold the button states for all requested buttons.
\item [\textit{numbuttons}]\ \\
  Specifies how many buttons should be returned.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns the number of actually returned buttons. This is the
minimum of \textit{numbuttons} and the number of buttons supported by the
joystick. If the joystick is not supported or connected, the function will
return 0 (zero).
\end{refreturn}

\begin{refdescription}
This function queries the current state of one or more buttons of a
joystick. The button states are returned in an array, where the first
element represents the first button of the joystick. Each state can be
either GLFW\_PRESS or GLFW\_RELEASE.

If \textit{numbuttons} exceeds the number of buttons supported by the
joystick, or if the joystick is not available, the unused elements in the
\textit{buttons} array will be set to GLFW\_RELEASE.
\end{refdescription}

\begin{refnotes}
The joystick state is updated every time the function is called, so there
is no need to call \textbf{glfwPollEvents} or \textbf{glfwWaitEvents} for
joystick state to be updated.

Use \textbf{glfwGetJoystickParam} to retrieve joystick capabilities, such
as joystick availability and number of supported buttons.

No window has to be opened for joystick input to be available.
\end{refnotes}


%-------------------------------------------------------------------------
\pagebreak
\section{Timing}

%-------------------------------------------------------------------------
\subsection{glfwGetTime}

\textbf{C language syntax}
\begin{lstlisting}
double glfwGetTime(void)
\end{lstlisting}

\begin{refparameters}
none
\end{refparameters}

\begin{refreturn}
The function returns the value of the high precision timer. The time is
measured in seconds, and is returned as a double precision floating point
value.
\end{refreturn}

\begin{refdescription}
This function returns the state of a high precision timer. Unless the timer
has been set by the \textbf{glfwSetTime} function, the time is measured as
the number of seconds that have passed since \textbf{glfwInit} was called.
\end{refdescription}

\begin{refnotes}
The resolution of the timer depends on which system the program is running
on.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwSetTime}

\textbf{C language syntax}
\begin{lstlisting}
void glfwSetTime(double time)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{time}]\ \\
  Time (in seconds) that the timer should be set to.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
This function sets the current time of the high precision timer to the
specified time. Subsequent calls to \textbf{glfwGetTime} will be relative
to this time. The time is given in seconds.
\end{refdescription}


%-------------------------------------------------------------------------
\pagebreak
\section{OpenGL Extension Support}
One of the great features of \OpenGL\ is its support for extensions, which
allow independent vendors to supply non-standard functionality in their
\OpenGL\ implementations.  As the mechanism for querying extensions varies
among systems, \GLFW\ provides an operating system independent interface for
querying \OpenGL\ version, extensions and entry points.


%-------------------------------------------------------------------------
\subsection{glfwExtensionSupported}

\textbf{C language syntax}
\begin{lstlisting}
int glfwExtensionSupported(const char* extension)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{extension}]\ \\
  A null terminated ISO~8859-1 string containing the name of an \OpenGL\
  extension.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns GL\_TRUE if the extension is supported. Otherwise it
returns GL\_FALSE.
\end{refreturn}

\begin{refdescription}
This function does a string search in the list of supported \OpenGL\
extensions to find if the specified extension is listed.
\end{refdescription}

\begin{refnotes}
An \OpenGL\ context must be created before this function can be called
(i.e. an \OpenGL\ window must have been opened with
\textbf{glfwOpenWindow}).

In addition to checking for \OpenGL\ extensions, \GLFW\ also checks for
extensions in the operating system ``glue API'', such as WGL extensions
under Microsoft Windows and GLX extensions under the X Window System.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwGetProcAddress}

\textbf{C language syntax}
\begin{lstlisting}
void* glfwGetProcAddress(const char* procname)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{procname}]\ \\
  A null terminated ISO~8859-1 string containing the name of an \OpenGL\
  extension function.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns the address of the specified \OpenGL\ function, if it
is available.  Otherwise NULL is returned.
\end{refreturn}

\begin{refdescription}
This function acquires the pointer to an \OpenGL\ extension function. Some
(but not all) \OpenGL\ extensions define new API functions, which are
usually not available through normal linking. It is therefore necessary to
get access to those API functions at runtime.
\end{refdescription}

\begin{refnotes}
An \OpenGL\ context must be created before this function can be called
(i.e. an \OpenGL\ window must have been opened with
\textbf{glfwOpenWindow}).

Some systems do not support dynamic function pointer retrieval, in which
case \textbf{glfwGetProcAddress} will always return NULL.
\end{refnotes}


%-------------------------------------------------------------------------
\subsection{glfwGetGLVersion}

\textbf{C language syntax}
\begin{lstlisting}
void glfwGetGLVersion(int* major, int* minor, int* rev)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{major}]\ \\
  Pointer to an integer that will hold the major version number.
\item [\textit{minor}]\ \\
  Pointer to an integer that will hold the minor version number.
\item [\textit{rev}]\ \\
  Pointer to an integer that will hold the revision.
\end{description}
\end{refparameters}

\begin{refreturn}
The function returns the major and minor version numbers and the revision
for the currently used \OpenGL\ implementation.
\end{refreturn}

\begin{refdescription}
This function returns the \OpenGL\ implementation version. This is a
convenient function that parses the version number information at the beginning
of the string returned by calling \texttt{glGetString(~GL\_VERSION~)}. The
\OpenGL\ version information can be used to determine what functionality is
supported by the used \OpenGL\ implementation.
\end{refdescription}

\begin{refnotes}
An \OpenGL\ context must be created before this function can be called
(i.e. an \OpenGL\ window must have been opened with
\textbf{glfwOpenWindow}).
\end{refnotes}


%-------------------------------------------------------------------------
\pagebreak
\section{Miscellaneous}


%-------------------------------------------------------------------------
\subsection{glfwEnable/glfwDisable}

\textbf{C language syntax}
\begin{lstlisting}
void glfwEnable(int token)
void glfwDisable(int token)
\end{lstlisting}

\begin{refparameters}
\begin{description}
\item [\textit{token}]\ \\
  A value specifying a feature to enable or disable. Valid tokens are
  listed in table \ref{tab:enable}.
\end{description}
\end{refparameters}

\begin{refreturn}
none
\end{refreturn}

\begin{refdescription}
\textbf{glfwEnable} is used to enable a certain feature, while
\textbf{glfwDisable} is used to disable it. Below follows a description of
each feature.
\end{refdescription}


\begin{table}[p]
\begin{center}
\begin{tabular}{|l|p{5.0cm}|p{3.0cm}|} \hline \raggedright
\textbf{Name} & \textbf{Controls} & \textbf{Default}\\ \hline
\hyperlink{lnk:autopollevents}{GLFW\_AUTO\_POLL\_EVENTS}         & Automatic event polling when \textbf{glfwSwapBuffers} is called & Enabled\\ \hline
\hyperlink{lnk:keyrepeat}{GLFW\_KEY\_REPEAT}                     & Keyboard key repeat                                    & Disabled\\ \hline
\hyperlink{lnk:mousecursor}{GLFW\_MOUSE\_CURSOR}                 & Mouse cursor visibility                                & Enabled in windowed mode. Disabled in fullscreen mode.\\ \hline
\hyperlink{lnk:stickykeys}{GLFW\_STICKY\_KEYS}                   & Keyboard key ``stickiness''                            & Disabled\\ \hline
\hyperlink{lnk:stickymousebuttons}{GLFW\_STICKY\_MOUSE\_BUTTONS} & Mouse button ``stickiness''                            & Disabled\\ \hline
\hyperlink{lnk:systemkeys}{GLFW\_SYSTEM\_KEYS}                   & Special system key actions                             & Enabled\\ \hline
\end{tabular}
\end{center}
\caption{Tokens for \textbf{glfwEnable}/\textbf{glfwDisable}}
\label{tab:enable}
\end{table}


\bigskip\begin{mysamepage}\hypertarget{lnk:autopollevents}{}
\textbf{GLFW\_AUTO\_POLL\_EVENTS}\\
When GLFW\_AUTO\_POLL\_EVENTS is enabled, \textbf{glfwPollEvents} is
automatically called each time that \textbf{glfwSwapBuffers} is called,
immediately after the buffer swap itself.

When GLFW\_AUTO\_POLL\_EVENTS is disabled, calling
\textbf{glfwSwapBuffers} will not result in a call to
\textbf{glfwPollEvents}. This can be useful if for example \textbf{glfwSwapBuffers}
needs to be called from within a callback function, since calling
\textbf{glfwPollEvents} from a callback function is not allowed.
\end{mysamepage}


\bigskip\begin{mysamepage}\hypertarget{lnk:keyrepeat}{}
\textbf{GLFW\_KEY\_REPEAT}\\
When GLFW\_KEY\_REPEAT is enabled, the key and character callback
functions are called repeatedly when a key is held down long enough
(according to the system key repeat configuration).

When GLFW\_KEY\_REPEAT is disabled, the key and character callback
functions are only called once when a key is pressed (and once when it is
released).
\end{mysamepage}


\bigskip\begin{mysamepage}\hypertarget{lnk:mousecursor}{}
\textbf{GLFW\_MOUSE\_CURSOR}\\
When GLFW\_MOUSE\_CURSOR is enabled, the mouse cursor is visible, and
mouse coordinates are relative to the upper left corner of the client area
of the \GLFW\ window. The coordinates are limited to the client area of
the window.

When GLFW\_MOUSE\_CURSOR is disabled, the mouse cursor is invisible, and
mouse coordinates are not limited to the drawing area of the window. It is
as if the mouse coordinates are received directly from the mouse, without
being restricted or manipulated by the windowing system.
\end{mysamepage}


\bigskip\begin{mysamepage}\hypertarget{lnk:stickykeys}{}
\textbf{GLFW\_STICKY\_KEYS}\\
When GLFW\_STICKY\_KEYS is enabled, keys which are pressed will not be
released until they are physically released and checked with
\textbf{glfwGetKey}. This behavior makes it possible to catch keys that
were pressed and then released again between two calls to
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or
\textbf{glfwSwapBuffers}, which would otherwise have been reported as
released. Care should be taken when using this mode, since keys that are
not checked with \textbf{glfwGetKey} will never be released. Note also
that enabling GLFW\_STICKY\_KEYS does not affect the behavior of the
keyboard callback functionality.

When GLFW\_STICKY\_KEYS is disabled, the status of a key that is reported
by \textbf{glfwGetKey} is always the physical state of the key. Disabling
GLFW\_STICKY\_KEYS also clears the sticky information for all keys.
\end{mysamepage}


\bigskip\begin{mysamepage}\hypertarget{lnk:stickymousebuttons}{}
\textbf{GLFW\_STICKY\_MOUSE\_BUTTONS}\\
When GLFW\_STICKY\_MOUSE\_BUTTONS is enabled, mouse buttons that are pressed
will not be released until they are physically released and checked with
\textbf{glfwGetMouseButton}. This behavior makes it possible to catch mouse
buttons which were pressed and then released again between two calls to
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers}
(with GLFW\_AUTO\_POLL\_EVENTS enabled), which would otherwise have been
reported as released. Care should be taken when using this mode, since mouse
buttons that are not checked with \textbf{glfwGetMouseButton} will never be
released. Note also that enabling GLFW\_STICKY\_MOUSE\_BUTTONS does not affect
the behavior of the mouse button callback functionality.

When GLFW\_STICKY\_MOUSE\_BUTTONS is disabled, the status of a mouse
button that is reported by \textbf{glfwGetMouseButton} is always the
physical state of the mouse button. Disabling GLFW\_STICKY\_MOUSE\_BUTTONS
also clears the sticky information for all mouse buttons.
\end{mysamepage}


\bigskip\begin{mysamepage}\hypertarget{lnk:systemkeys}{}
\textbf{GLFW\_SYSTEM\_KEYS}\\
When GLFW\_SYSTEM\_KEYS is enabled, pressing standard system key
combinations, such as \texttt{Alt+Tab} under Windows, will give the normal
behavior. Note that when \texttt{Alt+Tab} is issued under Windows in this
mode so that the \GLFW\ application is deselected when \GLFW\ is operating
in fullscreen mode, the \GLFW\ application window will be minimized and
the video mode will be set to the original desktop mode. When the \GLFW\
application is re-selected, the video mode will be set to the \GLFW\ video
mode again.

When GLFW\_SYSTEM\_KEYS is disabled, pressing standard system key
combinations will have no effect, since those key combinations are blocked
by \GLFW . This mode can be useful in situations when the \GLFW\ program
must not be interrupted (normally for games in fullscreen mode).
\end{mysamepage}


%-------------------------------------------------------------------------
% GLFW Standards Conformance
%-------------------------------------------------------------------------
\appendix
\chapter{GLFW Compatibility}
\label{chap:compatibility}
\thispagestyle{fancy}

This chapter describes the various API extensions used by this version of
\GLFW .  It lists what are essentially implementation details, but which are
nonetheless vital knowledge for developers wishing to deploy their applications
on machines with varied specifications.

Note that the information in this appendix is not a part of the API
specification but merely list some of the preconditions for certain parts of
the API to function on a given machine.  As such, any part of it may change in
future versions without this being considered a breaking API change.

%-------------------------------------------------------------------------
\section{ICCCM and EWMH Conformance}

As \GLFW\ uses \textbf{Xlib}, directly, without any intervening toolkit
library, it has sole responsibility for interacting well with the many and
varied window managers in use on Unix-like systems.  In order for applications
and window managers to work well together, a number of standards and
conventions have been developed that regulate behavior outside the scope of the
X11 API; most importantly the \textbf{Inter-Client Communication Conventions
Manual} (ICCCM) and \textbf{Extended Window Manager Hints} (EWMH) standards.

\GLFW\ uses the ICCCM \textbf{WM\_DELETE\_WINDOW} protocol to intercept the user
attempting to close the \GLFW\ window.  If the running window manager does not
support this protocol, the close callback will never be called.

\GLFW\ uses the EWMH \textbf{\_NET\_WM\_PING} protocol, allowing the window
manager notify the user when the application has stopped responding, i.e. when
it has ceased to process events.  If the running window manager does not
support this protocol, the user will not be notified if the application locks
up.

\GLFW\ uses the EWMH \textbf{\_NET\_WM\_STATE} protocol to tell the window
manager to make the \GLFW\ window fullscreen.  If the running window manager
does not support this protocol, fullscreen windows may not work properly.
\GLFW\ has a fallback code path in case this protocol is unavailable, but every
window manager behaves slightly differently in this regard.

%-------------------------------------------------------------------------
\section{GLX Extensions}

The \textbf{GLX} API is used to create \OpenGL\ contexts on Unix-like systems
using the X Window System.

\GLFW\ uses the \textbf{GLXFBConfig} API to enumerate and select framebuffer
pixel formats.  This requires either \textbf{GLX} 1.3 or greater, or the
\textbf{GLX\_SGIX\_fbconfig} extension.  Where both are available, the SGIX
extension is preferred.  If neither is available, \GLFW\ will be unable to open
windows.

% This paragraph repeated almost verbatim below
\GLFW\ uses the \textbf{GLX\_SGI\_swap\_control} extension to provide vertical
retrace synchronization (or ``vsync'').  Where this extension is unavailable,
calling \textbf{glfwSwapInterval} will have no effect.

% This paragraph repeated almost verbatim below
\GLFW\ uses the \textbf{GLX\_ARB\_multisample} extension to create contexts
with multisampling anti-aliasing.  Where this extension is unavailable, the
GLFW\_FSAA\_SAMPLES hint will have no effect.

% This paragraph repeated almost verbatim below
\GLFW\ uses the \textbf{GLX\_ARB\_create\_context} extension when available,
even when creating \OpenGL\ contexts of version 2.1 and below.  Where this
extension is unavailable, the GLFW\_OPENGL\_VERSION\_MAJOR and
GLFW\_OPENGL\_VERSION\_MINOR hints will only be partially supported, the
GLFW\_OPENGL\_DEBUG\_CONTEXT hint will have no effect, and setting the
GLFW\_OPENGL\_PROFILE or GLFW\_FORWARD\_COMPAT hints to a non-zero value will
cause \textbf{glfwOpenWindow} to fail.

% This paragraph repeated almost verbatim below
\GLFW\ uses the \textbf{GLX\_ARB\_create\_context\_profile} extension to
provide support for context profiles.  Where this extension is unavailable,
setting the GLFW\_OPENGL\_PROFILE hint to anything but zero will cause
\textbf{glfwOpenWindow} to fail.

%-------------------------------------------------------------------------
\section{WGL Extensions}

The \textbf{WGL} API is used to create \OpenGL\ contexts on Microsoft Windows
and other implementations of the Win32 API, such as Wine.

\GLFW\ uses either the \textbf{WGL\_EXT\_extension\_string} or the
\textbf{WGL\_ARB\_extension\_string} extension to check for the presence of all
other \textbf{WGL} extensions listed below.  If both are available, the EXT one
is preferred.  If neither is available, no other extensions are used and many
\GLFW\ features related to context creation will have no effect or cause errors
when used.

% This paragraph repeated almost verbatim above
\GLFW\ uses the \textbf{WGL\_EXT\_swap\_control} extension to provide vertical
retrace synchronization (or ``vsync'').  Where this extension is unavailable,
calling \textbf{glfwSwapInterval} will have no effect.

% This paragraph repeated almost verbatim above
\GLFW\ uses the \textbf{WGL\_ARB\_pixel\_format} and
\textbf{WGL\_ARB\_multisample} extensions to create contexts with multisampling
anti-aliasing.  Where these extensions are unavailable, the GLFW\_FSAA\_SAMPLES
hint will have no effect.

% This paragraph repeated almost verbatim above
\GLFW\ uses the \textbf{WGL\_ARB\_create\_context} extension when available,
even when creating \OpenGL\ contexts of version 2.1 and below.  Where this
extension is unavailable, the GLFW\_OPENGL\_VERSION\_MAJOR and
GLFW\_OPENGL\_VERSION\_MINOR hints will only be partially supported, the
GLFW\_OPENGL\_DEBUG\_CONTEXT hint will have no effect, and setting the
GLFW\_OPENGL\_PROFILE or GLFW\_FORWARD\_COMPAT hints to a non-zero value will
cause \textbf{glfwOpenWindow} to fail.

% This paragraph repeated almost verbatim above
\GLFW\ uses the \textbf{WGL\_ARB\_create\_context\_profile} extension to
provide support for context profiles.  Where this extension is unavailable,
setting the GLFW\_OPENGL\_PROFILE hint to anything but zero will cause
\textbf{glfwOpenWindow} to fail.

%-------------------------------------------------------------------------
\section{OpenGL 3.0+ on Mac OS X}

At the time of writing, Mac OS X does not support OpenGL 3.0 or above.
Because of this, the GLFW\_OPENGL\_VERSION\_MAJOR and
GLFW\_OPENGL\_VERSION\_MINOR hints will fail if given a version above 2.1, the
GLFW\_OPENGL\_DEBUG\_CONTEXT hint will have no effect, and setting the
GLFW\_OPENGL\_PROFILE or GLFW\_FORWARD\_COMPAT hints to a non-zero value will
cause \textbf{glfwOpenWindow} to fail.


\end{document}