gwm17/glfw
1
0
Fork 0
mirror of https://github.com/gwm17/glfw.git synced 2025-02-19 20:18:50 -05:00
Code Issues Projects Releases Wiki Activity

Refreshed Reference Manual and User's Guide from 2.7, with updates for 3.0.

Browse Source
This commit is contained in:
Camilla Berglund 2010-09-08 16:21:12 +02:00
parent 61cc652a2f
commit 15c5fa8506
3 changed files with 797 additions and 553 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/glfwdoc.sty
View File

@ -16,8 +16,8 @@
\usepackage{times} \usepackage{times}
% Logo macros % Logo macros
\newcommand{\OpenGL}[1][0]{\textbf{OpenGL}\texttrademark} \newcommand{\OpenGL}[1][0]{OpenGL\textsuperscript{\textregistered}}
\newcommand{\GLFW}[1][0]{\textbf{GLFW}} \newcommand{\GLFW}[1][0]{GLFW}
% Encoding % Encoding
\usepackage[latin1]{inputenc} \usepackage[latin1]{inputenc}
@ -50,7 +50,8 @@
\vspace{0.5cm}{\LARGE\textbf{\glfwdoctype}}\\% \vspace{0.5cm}{\LARGE\textbf{\glfwdoctype}}\\%
\vspace{0.8cm}{\large\textbf{API version \glfwapiver}}\\% \vspace{0.8cm}{\large\textbf{API version \glfwapiver}}\\%
\textit{\today}\\% \textit{\today}\\%
\vspace{1.5cm}\textbf{\textcopyright2002-2007 Camilla Berglund}\\% \vspace{1.5cm}\textbf{\textcopyright2002-2006 Marcus Geelnard}\\
\textbf{\textcopyright2006-2010 Camilla Berglund}\\%
\end{center}\end{titlepage}\newpage} \end{center}\end{titlepage}\newpage}
% Colors % Colors

712
docs/glfwrm.tex
View File

File diff suppressed because it is too large Load Diff

409
docs/glfwug.tex
View File

@ -42,7 +42,7 @@
This document is a users guide for the \GLFW\ API that gives a practical 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 introduction to using \GLFW . For a more detailed description of the
\GLFW\ API you should refer to the \textit{GLFW Reference Manual}. \GLFW\ API you should refer to the \textit{GLFW Reference Manual}.
\vspace{10cm} \vspace{5cm}
\large \large
Trademarks Trademarks
@ -93,28 +93,27 @@ to remedy this by providing the following functionality:
\begin{itemize} \begin{itemize}
\item Opening and managing an \OpenGL\ window. \item Opening and managing an \OpenGL\ window.
\item Keyboard, mouse and joystick input. \item Keyboard, mouse and joystick input.
\item A high precision timer. \item High precision time input.
\item Support for querying and using \OpenGL\ extensions. \item Support for querying and using \OpenGL\ extensions.
\end{itemize} \end{itemize}
\vspace{18pt} \vspace{18pt}
All this functionality is implemented as a set of easy-to-use functions, 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 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 few lines of code. The \GLFW\ API is operating system and platform independent,
platform independent, which makes it very simple to port \GLFW\ based \OpenGL\ making it very simple to port \GLFW\ based \OpenGL\ applications between the
applications to a variety of platforms. supported platforms.
Currently supported platforms are: Currently supported platforms are:
\begin{itemize} \begin{itemize}
\item Microsoft Windows\textsuperscript{\textregistered} 95/98/ME/NT/2000/XP/.NET Server. \item Microsoft Windows\textsuperscript{\textregistered}
\item Unix\textsuperscript{\textregistered} or Unix­-like systems running the \item Unix\textsuperscript{\textregistered} or Unix­-like systems running the
X Window System\texttrademark, e.g. Linux\textsuperscript{\textregistered}, X Window System\texttrademark with GLX version 1.3 or later
IRIX\textsuperscript{\textregistered}, FreeBSD\textsuperscript{\textregistered}, \item Mac OS X\textsuperscript{\textregistered} 10.5 and later, using Cocoa\footnote{Support for joysticks missing at the time of writing.}
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} \end{itemize}
There is also deprecated support for Mac OS X versions 10.3 and 10.4, using the Carbon API.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
% Getting Started % Getting Started
@ -129,8 +128,8 @@ read some user keyboard input.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\section{Initializing GLFW} \section{Initializing GLFW}
Before using any of the \GLFW\ functions, it is necessary to call Before using any of the \GLFW\ functions, it is necessary to call
\textbf{glfwInit}. It initializes internal working variables that are used \textbf{glfwInit}. It initializes the parts of \GLFW\ that are not dependent on
by other \GLFW\ functions. The C syntax is: a window, such as time and joystick input. The C syntax is:
\begin{lstlisting} \begin{lstlisting}
int glfwInit(void) int glfwInit(void)
@ -140,31 +139,28 @@ int glfwInit( void )
GL\_FALSE if it failed. GL\_FALSE if it failed.
When your application is done using \GLFW , typically at the very end of When your application is done using \GLFW , typically at the very end of
the program, you should call \textbf{glfwTerminate}, which makes a clean the program, you should call \textbf{glfwTerminate}. The C syntax is:
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} \begin{lstlisting}
void glfwTerminate(void) void glfwTerminate(void)
\end{lstlisting} \end{lstlisting}
Among other things, \textbf{glfwTerminate} closes the \OpenGL\ window This releases any resources allocated by GLFW and closes the window if it is
unless it was closed manually. open. After this call, you must call \textbf{glfwInit} again before using any
\GLFW\ functions).
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\section{Opening An OpenGL Window} \section{Opening An OpenGL Window}
Opening an \OpenGL\ window is done with the function Opening an \OpenGL\ window is done with the \textbf{glfwOpenWindow} function.
\textbf{glfwOpenWindow}. The function takes nine arguments, which are used The function takes nine arguments, which are used to describe the following
to describe the following properties of the window to open: properties of the requested window:
\begin{itemize} \begin{itemize}
\item Window dimensions (width and height) in pixels. \item Window dimensions (width and height) in pixels.
\item Color and alpha buffer depth. \item Color and alpha buffer bit depth.
\item Depth buffer (Z-buffer) depth. \item Depth buffer (Z-buffer) bit depth.
\item Stencil buffer depth. \item Stencil buffer bit depth.
\item Fullscreen or windowed mode. \item Whether to use fullscreen or windowed mode.
\end{itemize} \end{itemize}
The C language syntax for \textbf{glfwOpenWindow} is: The C language syntax for \textbf{glfwOpenWindow} is:
@ -189,15 +185,15 @@ The \textit{mode} argument is used to specify if the window is to be a
s.c. fullscreen window, or a regular window. s.c. fullscreen window, or a regular window.
If \textit{mode} is GLFW\_FULLSCREEN, the window will cover the entire 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 screen and no window border or decorations will be visible. If possible, the
will be changed to the mode that closest matches the \textit{width}, video mode will be changed to the mode that closest matches the \textit{width},
\textit{height}, \textit{redbits}, \textit{greenbits}, \textit{bluebits} \textit{height}, \textit{redbits}, \textit{greenbits}, \textit{bluebits} and
and \textit{alphabits} arguments. Furthermore, the mouse pointer will be \textit{alphabits} arguments. Furthermore, the mouse pointer will be hidden,
hidden, and screensavers are prohibited. This is usually the best mode for and screensavers are prohibited. This is usually the best mode for games and
games and demos. demos.
If \textit{mode} is GLFW\_WINDOW, the window will be opened as a normal 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 decorated window on the desktop. The mouse pointer will not be hidden and
screensavers are allowed to be activated. screensavers are allowed to be activated.
To close the window, you can either use \textbf{glfwTerminate}, as To close the window, you can either use \textbf{glfwTerminate}, as
@ -208,6 +204,10 @@ described earlier, or you can use the more explicit approach by calling
void glfwCloseWindow(void) void glfwCloseWindow(void)
\end{lstlisting} \end{lstlisting}
Note that you do not need to call \textbf{glfwTerminate} and \textbf{glfwInit}
before opening a new window after having closed the current one using
\textbf{glfwCloseWindow}.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\section{Using Keyboard Input} \section{Using Keyboard Input}
@ -225,8 +225,8 @@ It queries the current status of individual keyboard keys. The argument
uppercase printable ISO 8859-1 (Latin 1) character (e.g. `A', `3' or `.'), 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 or a special key identifier (see the \textit{GLFW Reference Manual} for a
list of special key identifiers). \textbf{glfwGetKey} returns GLFW\_PRESS 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 if the key is currently held down, or GLFW\_RELEASE if the key is not being
key is not being held down. For example: held down. For example:
\begin{lstlisting} \begin{lstlisting}
A_pressed = glfwGetKey('A'); A_pressed = glfwGetKey('A');
@ -251,25 +251,25 @@ second in order for \GLFW\ to maintain an up to date input state.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\section{Putting It Together: A Minimal GLFW Application} \section{Putting It Together: A Minimal GLFW Application}
Now that you know how to initialize \GLFW , open a window and poll for 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 keyboard input, let us exemplify this with a simple \OpenGL\ program:
the following example some error-checking has been omitted for the sake of
brevity:
\begin{lstlisting} \begin{lstlisting}
#include <GL/glfw.h> #include <GL/glfw.h>
#include <stdlib.h>
int main(void) int main(void)
{ {
int running = GL_TRUE; int running = GL_TRUE;
// Initialize GLFW // Initialize GLFW
glfwInit(); if (!glfwInit())
exit(EXIT_FAILURE);
// Open an OpenGL window // Open an OpenGL window
if (!glfwOpenWindow(300,300, 0,0,0,0,0,0, GLFW_WINDOW)) if (!glfwOpenWindow(300,300, 0,0,0,0,0,0, GLFW_WINDOW))
{ {
glfwTerminate(); glfwTerminate();
return 0; exit(EXIT_FAILURE);
} }
// Main loop // Main loop
@ -290,7 +290,7 @@ int main( void )
glfwTerminate(); glfwTerminate();
// Exit program // Exit program
return 0; exit(EXIT_SUCCESS);
} }
\end{lstlisting} \end{lstlisting}
@ -305,7 +305,7 @@ is done in this example is to clear the window.
\chapter{Window Operations} \chapter{Window Operations}
\thispagestyle{fancy} \thispagestyle{fancy}
In this chapter, you will learn more about window related \GLFW\ In this chapter, you will learn more about window related \GLFW\
functionality, including: setting and getting window properties, buffer functionality, including setting and getting window properties, buffer
swap control and video mode querying. swap control and video mode querying.
@ -313,9 +313,9 @@ swap control and video mode querying.
\section{Setting Window Properties} \section{Setting Window Properties}
In the previous chapter the \textbf{glfwOpenWindow} function was In the previous chapter the \textbf{glfwOpenWindow} function was
described, which specifies the sizes of the color, alpha, depth and described, which specifies the sizes of the color, alpha, depth and
stencil buffers. It is also possible to request an accumulator buffer, stencil buffers. It is also possible to request a specific minimum OpenGL
auxiliary buffers and stereo rendering by using the version, multisampling anti-aliasing, an accumulation buffer, stereo
\textbf{glfwOpenWindowHint} function: rendering and more by using the \textbf{glfwOpenWindowHint} function:
\begin{lstlisting} \begin{lstlisting}
void glfwOpenWindowHint(int target, int hint) void glfwOpenWindowHint(int target, int hint)
@ -331,20 +331,21 @@ specified target.
\begin{tabular}{|l|l|p{7.0cm}|} \hline \raggedright \begin{tabular}{|l|l|p{7.0cm}|} \hline \raggedright
\textbf{Name} & \textbf{Default} & \textbf{Description} \\ \hline \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\_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\_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 accumulator 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 accumulator 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 accumulator 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\_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\_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\_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\_FSAA\_SAMPLES & 0 & Number of samples to use for the multisampling buffer. Zero disables multisampling.\\ \hline
GLFW\_OPENGL\_VERSION\_MAJOR & 0 & Major number of the desired OpenGL version. GLFW\_OPENGL\_VERSION\_MAJOR & 1 & Major number of the desired minimum OpenGL version.\\ \hline
The default requests the highest OpenGL version equal to or lower than 2.1.\\ \hline GLFW\_OPENGL\_VERSION\_MINOR & 1 & Minor number of the desired minimum OpenGL version.\\ \hline
GLFW\_OPENGL\_VERSION\_MINOR & 0 & Minor number of the desired OpenGL version. GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_FALSE & Specify whether the OpenGL context should be forward-compatible (i.e. disallow legacy functionality).
The default requests the highest OpenGL version equal to or lower than 2.1.\\ \hline This should only be used when requesting OpenGL version 3.0 or above.\\ \hline
GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_FALSE & Specify whether the OpenGL context should be forward compatible (i.e. disallow legacy functionality). GLFW\_OPENGL\_DEBUG\_CONTEXT & GL\_FALSE & Specify whether a debug context should be created.\\ \hline
This hint is ignored for OpenGL version 2.1 and below.\\ \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{tabular}
\end{center} \end{center}
\caption{Targets for \textbf{glfwOpenWindowHint}} \caption{Targets for \textbf{glfwOpenWindowHint}}
@ -356,7 +357,7 @@ For a hint to have any effect, the \textbf{glfwOpenWindowHint} function
must be called before opening the window with the \textbf{glfwOpenWindow} must be called before opening the window with the \textbf{glfwOpenWindow}
function. function.
To request an accumulator buffer, set the GLFW\_ACCUM\_x\_BITS targets to To request an accumulation buffer, set the GLFW\_ACCUM\_x\_BITS targets to
values greater than zero (usually eight or sixteen bits per component). values greater than zero (usually eight or sixteen bits per component).
To request auxiliary buffers, set the GLFW\_AUX\_BUFFERS target to a value 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 greater than zero. To request a stereo rendering capable window, set the
@ -369,10 +370,19 @@ 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 The GLFW\_REFRESH\_RATE target should be used with caution, since it may
result in suboptimal operation, or even a blank or damaged screen. result in suboptimal operation, or even a blank or damaged screen.
If you want to create a context with OpenGL version 3.0 or above you have to If you want to create a forward-compatible \OpenGL\ context, set the
set the GLFW\_OPENGL\_VERSION\_MAJOR and GLFW\_OPENGL\_VERSION\_MINOR hints GLFW\_OPENGL\_FORWARD\_COMPAT hint to GL\_TRUE. Note that such contexts are
accordingly. If you don't do this, the highest OpenGL version available for a only available for \OpenGL\ version 3.0 and above, so you will need to specify
context is 2.1 or lower. a valid minimum version using the GLFW\_OPENGL\_VERSION\_MAJOR and
GLFW\_OPENGL\_VERSION\_MINOR hints.
If you want to create a context using the core profile as available in \OpenGL\
version 3.2 and above, set the GLFW\_OPENGL\_PROFILE hint accordingly. Note that
as above you have to set a valid minimum version for this to work.
Also note that at the time of this release, Mac OS X did not support \OpenGL\
version 3.0 or above; thus GLFW cannot create contexts of versions above 2.1
on that platform.
Besides the parameters that are given with the \textbf{glfwOpenWindow} and Besides the parameters that are given with the \textbf{glfwOpenWindow} and
\textbf{glfwOpenWindowHint} functions, a few more properties of a window \textbf{glfwOpenWindowHint} functions, a few more properties of a window
@ -388,7 +398,7 @@ void glfwSetWindowTitle( const char *title )
\textit{title} is a null terminated ISO~8859-1 (8-bit Latin~1) string that \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 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} 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 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 the X Window System). The default window name is ``GLFW Window'', which
will be used unless \textbf{glfwSetWindowTitle} is called after the window will be used unless \textbf{glfwSetWindowTitle} is called after the window
@ -444,18 +454,19 @@ GLFW\_ALPHA\_BITS & Number of bits for the alpha buffer.\\ \hline
GLFW\_DEPTH\_BITS & Number of bits for the depth 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\_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\_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\_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 accumulator 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 accumulator 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 accumulator 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\_AUX\_BUFFERS & Number of auxiliary buffers.\\ \hline
GLFW\_STEREO & GL\_TRUE if stereo rendering is supported, else GL\_FALSE.\\ \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, 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\_FSAA\_SAMPLES & Number of multisampling buffer samples. Zero indicated multisampling is disabled.\\ \hline
GLFW\_OPENGL\_VERSION\_MAJOR & Major number of the desired OpenGL version.\\ \hline GLFW\_OPENGL\_VERSION\_MAJOR & Major number of the actual version of the context.\\ \hline
GLFW\_OPENGL\_VERSION\_MINOR & Minor number of the desired OpenGL version.\\ \hline GLFW\_OPENGL\_VERSION\_MINOR & Minor number of the actual version of the context.\\ \hline
GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_TRUE if the OpenGL context is forward compatible (i.e. disallows legacy functionality), else GL\_FALSE. GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_TRUE if the context is forward-compatible, else GL\_FALSE.\\ \hline
This is always GL\_FALSE for OpenGL version 2.1 and below.\\ \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{tabular}
\end{center} \end{center}
\caption{Window parameters for \textbf{glfwGetWindowParam}} \caption{Window parameters for \textbf{glfwGetWindowParam}}
@ -474,7 +485,7 @@ void glfwSetWindowSizeCallback( GLFWwindowsizefun cbfun )
The user function \textit{fun} should be of the type: The user function \textit{fun} should be of the type:
\begin{lstlisting} \begin{lstlisting}
void GLFWCALL fun( int width, int height ) void fun(int width, int height)
\end{lstlisting} \end{lstlisting}
The first argument passed to the user function is the width of the window, The first argument passed to the user function is the width of the window,
@ -482,12 +493,12 @@ and the second argument is the height of the window. Here is an example
of how to use a window size callback function: of how to use a window size callback function:
\begin{lstlisting} \begin{lstlisting}
int WinWidth, WinHeight; int windowWidth, windowHeight;
void GLFWCALL WindowResize( int width, int height ) void WindowResize(int width, int height)
{ {
WinWidth = width; windowWidth = width;
WinHeight = height; windowHeight = height;
} }
int main(void) int main(void)
@ -510,8 +521,9 @@ is to use the function \textbf{glfwGetWindowSize}:
void glfwGetWindowSize(int* width, int* height) void glfwGetWindowSize(int* width, int* height)
\end{lstlisting} \end{lstlisting}
The \textit{width} and \textit{height} arguments are filled out with the The variables pointed to by \textit{width} and \textit{height} are set to the
current window dimensions. current window dimensions. Note that either of these may be NULL; that
argument is then ignored.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
@ -534,11 +546,14 @@ frame, and begin rendering a new frame. This is done with the command
void glfwSwapBuffers(void) void glfwSwapBuffers(void)
\end{lstlisting} \end{lstlisting}
Besides swapping the front and back rendering buffers, After swapping the front and back rendering buffers, \textbf{glfwSwapBuffers}
\textbf{glfwSwapBuffers} also calls \textbf{glfwPollEvents}\footnote{This by default calls \textbf{glfwPollEvents}\footnote{This behavior can be disabled
behavior can be disabled by calling \textbf{glfwDisable} with the argument by calling \textbf{glfwDisable} with the argument GLFW\_AUTO\_POLL\_EVENTS.}.
GLFW\_AUTO\_POLL\_EVENTS.}. This is to ensure frequent polling of events, This is to ensure frequent polling of events, such as keyboard and mouse input,
such as keyboard and mouse input, and window reshaping events. and window reshaping events. Even if a given application does not use input
events, without frequent polling of events (at \emph{least} once every few
seconds), most modern window systems will flag the application as unresponsive
and may suggest that the user terminate it.
Sometimes it can be useful to select when the buffer swap will occur. With Sometimes it can be useful to select when the buffer swap will occur. With
the function \textbf{glfwSwapInterval} it is possible to select the the function \textbf{glfwSwapInterval} it is possible to select the
@ -558,11 +573,12 @@ 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 vertical retrace. However, a swap interval of 1 generally gives better
visual quality. visual quality.
It should be noted that not all \OpenGL\ implementations and hardware It should be noted that not all \OpenGL\ implementations and hardware support
support this function, in which case \textbf{glfwSwapInterval} will have this function, in which case \textbf{glfwSwapInterval} will have no effect. ATI
no effect. Sometimes it is only possible to affect the swap interval Radeon cards under Microsoft Windows are especially notorious in this regard.
through driver settings (e.g. the display settings under Windows, or as an Sometimes it is only possible to affect the swap interval through driver
environment variable setting under Unix). settings (e.g. the display settings under Windows, or as an environment
variable setting under Unix).
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
@ -579,9 +595,9 @@ int glfwGetVideoModes( GLFWvidmode *list, int maxcount )
\end{lstlisting} \end{lstlisting}
The argument \textit{list} is a vector of GLFWvidmode structures, and The argument \textit{list} is a vector of GLFWvidmode structures, and
\textit{maxcount} is the maximum number of video modes that your vector \textit{maxcount} is the maximum number of video modes that your vector can
can hold. \textbf{glfwGetVideoModes} will return the actual number of hold. \textbf{glfwGetVideoModes} will return the number of video modes detected
video modes detected on the system. on the system, up to \textit{maxcount}.
The GLFWvidmode structure looks like this: The GLFWvidmode structure looks like this:
@ -634,12 +650,16 @@ 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 keyboard and mouse input is collected by checking for input events. This
has do be done manually by calling either \textbf{glfwPollEvents} or has do be done manually by calling either \textbf{glfwPollEvents} or
\textbf{glfwSwapBuffers} (which implicitly calls \textbf{glfwPollEvents} \textbf{glfwSwapBuffers} (which implicitly calls \textbf{glfwPollEvents}
for you). Normally this does not have to be a concern, since for you). Normally this is not a cause for concern, as
\textbf{glfwSwapBuffers} is called every frame, which should be often \textbf{glfwSwapBuffers} is called every frame, which should be often
enough (about 10-100 times per second for a normal \OpenGL\ application). enough (about 10-100 times per second for a normal \OpenGL\ application) that
One exception is when rendering is paused, and then the program waits for the window will feel responsive.
input to begin animation again. In this case \textbf{glfwPollEvents} has
to be called repeatedly until any new input events arrive. One exception is when an application is updating its view only in response to input.
In this case the \textbf{glfwWaitEvents} is useful, as it blocks the calling
thread until an event arrives. The refresh callback, set with
\textbf{glfwSetWindowRefreshCallback}, may also be useful for such
applications, especially on unbuffered window systems.
If it is not desirable that \textbf{glfwPollEvents is} called implicitly If it is not desirable that \textbf{glfwPollEvents is} called implicitly
from \textbf{glfwSwapBuffers}, call \textbf{glfwDisable} with the argument from \textbf{glfwSwapBuffers}, call \textbf{glfwDisable} with the argument
@ -652,7 +672,7 @@ called.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\section{Keyboard Input} \section{Keyboard Input}
\GLFW\ gives three options for getting keyboard input: \GLFW\ provides three mechanisms for getting keyboard input:
\begin{itemize} \begin{itemize}
\item Manually polling the state of individual keys. \item Manually polling the state of individual keys.
@ -661,12 +681,12 @@ called.
\item Automatically receive characters, using a callback function. \item Automatically receive characters, using a callback function.
\end{itemize} \end{itemize}
Depending on what the keyboard input will be used for, either of the Depending on what the keyboard input will be used for, different methods may be
methods may be more suitable. The main difference between the two last preferred. The main difference between the two last methods is that while
options is that while characters are affected by modifier keys (such as characters are affected by modifier keys (such as shift), key state is
shift), key state is independent of any modifier keys. Also, special keys independent of any modifier keys. Also, special keys (such as function keys,
(such as function keys, cursor keys and modifier keys) are not reported to cursor keys and modifier keys) are not reported to the character callback
the character callback function. function.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\subsection{Key state} \subsection{Key state}
@ -697,8 +717,8 @@ glfwEnable( GLFW_STICKY_KEYS );
When sticky keys are enabled, a key will not be released until it is When sticky keys are enabled, a key will not be released until it is
checked with \textbf{glfwGetKey}. To disable sticky keys, call checked with \textbf{glfwGetKey}. To disable sticky keys, call
\textbf{glfwDisable} witht the argument GLFW\_STICKY\_KEYS. Then all keys \textbf{glfwDisable} witht the argument GLFW\_STICKY\_KEYS. Then all keys
that are not currently held down will be released, and future key releases that are not currently held down will be released and future key releases
will take place immediately when the user releases the key, without will take place immediately when the user releases the key without
waiting for \textbf{glfwGetKey} to check the key. By default sticky keys waiting for \textbf{glfwGetKey} to check the key. By default sticky keys
are disabled. are disabled.
@ -714,8 +734,8 @@ recording many key presses in the first section that will be detected in
the second section. To avoid this problem, always disable sticky keys the second section. To avoid this problem, always disable sticky keys
before leaving a section of a program. before leaving a section of a program.
An alternative to using \textbf{glfwGetKey} is to register a keyboard A usually better alternative to using \textbf{glfwGetKey} is to register a
input callback function with \textbf{glfwSetKeyCallback}: keyboard input callback function with \textbf{glfwSetKeyCallback}:
\begin{lstlisting} \begin{lstlisting}
void glfwSetKeyCallback(GLFWkeyfun cbfun) void glfwSetKeyCallback(GLFWkeyfun cbfun)
@ -727,8 +747,10 @@ identifier, and the second is the new key state, which can be GLFW\_PRESS
or GLFW\_RELEASE. To unregister a callback function, call or GLFW\_RELEASE. To unregister a callback function, call
\textbf{glfwSetKeyCallback} with \textit{fun} = NULL. \textbf{glfwSetKeyCallback} with \textit{fun} = NULL.
A callback function can be useful in some situations. For instance it can Using the callback function, you can be sure not to miss any key press or
replace multiple \textbf{glfwGetKey} calls with a switch/case statement. release events, regardless of how many may have occurred during the last frame.
It also encourages event-based design, where the application responds only to
actual events instead of having to poll for every supported event.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\subsection{Character input} \subsection{Character input}
@ -743,7 +765,7 @@ void glfwSetCharCallback( GLFWcharfun cbfun )
The argument \textit{fun} is a pointer to a callback function. The The argument \textit{fun} is a pointer to a callback function. The
callback function shall take two integer arguments. The first is a Unicode 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 code point, and the second is GLFW\_PRESS if the key that generated
the character was pressed, or GLFW\_RELEASE if it was released. To the character was pressed, or GLFW\_RELEASE if it was released. To
unregister a callback function, call \textbf{glfwSetCharCallback} with unregister a callback function, call \textbf{glfwSetCharCallback} with
\textit{fun} = NULL. \textit{fun} = NULL.
@ -800,16 +822,17 @@ polling or callback functions.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\subsection{Mouse position} \subsection{Mouse position}
To read the mouse position, you can use the function To query the position of the mouse cursor, call \textbf{glfwGetMousePos}:
\textbf{glfwGetMousePos}:
\begin{lstlisting} \begin{lstlisting}
void glfwGetMousePos(int* x, int* y) void glfwGetMousePos(int* x, int* y)
\end{lstlisting} \end{lstlisting}
The arguments \textit{x} and \textit{y} point to integer variables that The variables pointed to by \textit{x} and \textit{y} will be updated with the
will be updated with the current absolute mouse position. An alternative current position of the mouse cursor relative to the upper-left corner of the
is to use a callback function instead, which can be set with client area of the \GLFW\ window.
An alternative is to use a callback function, which can be set with
\textbf{glfwSetMousePosCallback}: \textbf{glfwSetMousePosCallback}:
\begin{lstlisting} \begin{lstlisting}
@ -817,8 +840,13 @@ void glfwSetMousePosCallback( GLFWmouseposfun cbfun )
\end{lstlisting} \end{lstlisting}
The function that \textit{fun} points to will be called every time the The function that \textit{fun} points to will be called every time the
mouse position changes. The first argument to the callback function is mouse cursor moves. The first argument to the callback function is
the mouse x position, and the second argument is the mouse y position. the cursor x-coordinate and the second the cursor y-coordinate, both relative
to the upper-left corner of the client area of the \GLFW\ window.
Note that while the \textbf{glfwGetMousePos} function only reports the final
position after cursor movement events have been processed, using a callback
function lets the application see each and every such event.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
@ -829,24 +857,24 @@ To query the state of a mouse button, call \textbf{glfwGetMouseButton}:
int glfwGetMouseButton(int button) int glfwGetMouseButton(int button)
\end{lstlisting} \end{lstlisting}
The argument \textit{button} can be one of the following mouse button The argument \textit{button} can be any \GLFW\ mouse button token, i.e.
identifiers: GLFW\_MOUSE\_BUTTON\_LEFT, GLFW\_MOUSE\_BUTTON\_RIGHT or GLFW\_MOUSE\_BUTTON\_1 through GLFW\_MOUSE\_BUTTON\_8 or one of
GLFW\_MOUSE\_BUTTON\_LEFT, GLFW\_MOUSE\_BUTTON\_RIGHT or
GLFW\_MOUSE\_BUTTON\_MIDDLE. \textbf{glfwGetMouseButton} will return GLFW\_MOUSE\_BUTTON\_MIDDLE. \textbf{glfwGetMouseButton} will return
GLFW\_PRESS (which is a non-zero value) if the corresponding mouse GLFW\_PRESS (which is a non-zero value) if the corresponding mouse button is
button is held down, otherwise it will return GLFW\_RELEASE (which is held down, otherwise it will return GLFW\_RELEASE (which is equal to zero).
equal to zero).
Just as it is possible to make keys ``sticky'', it is also possible to Just as it is possible to make keys ``sticky'', it is also possible to make
make mouse buttons appear as held down until the button is checked for each mouse button appear as held down until it is checked with
with \textbf{glfwGetMouseButton}. To enable sticky mouse buttons, call \textbf{glfwGetMouseButton}. To enable sticky mouse buttons, call
\textbf{glfwEnable} with the argument GLFW\_STICKY\_MOUSE\_BUTTONS. \textbf{glfwEnable} with the argument GLFW\_STICKY\_MOUSE\_BUTTONS.
When sticky mouse buttons are enabled, a mouse button will not be released When sticky mouse buttons are enabled, a mouse button will not be released
until it is checked with \textbf{glfwGetMouseButton}. To disable sticky until it is checked with \textbf{glfwGetMouseButton}. To disable sticky
mouse buttons, call \textbf{glfwDisable} with the argument mouse buttons, call \textbf{glfwDisable} with the argument
GLFW\_STICKY\_MOUSE\_BUTTONS. Then all mouse buttons that are not GLFW\_STICKY\_MOUSE\_BUTTONS. Then all mouse buttons that are not
currently held down will be released, and future mouse button releases currently held down will be released and future mouse button releases
will take place immediately when the user releases the mouse button, will take place immediately when the user releases the mouse button
without waiting for \textbf{glfwGetMouseButton} to check for the mouse without waiting for \textbf{glfwGetMouseButton} to check for the mouse
button. By default sticky mouse buttons are disabled. button. By default sticky mouse buttons are disabled.
@ -866,9 +894,10 @@ depending on the new state of the corresponding mouse button.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\subsection{Mouse wheel} \subsection{Mouse wheel}
Some mice have a mouse wheel, which can be thought of as a third mouse Some mice have a mouse wheel, most commonly used for vertical scrolling. Also,
axis. To get the position of the mouse wheel, call most modern touchpads allow the user to scroll at least vertically, either by
\textbf{glfwGetMouseWheel}: reserving an area for scrolling or through multi-finger gestures. To get the
position of the mouse wheel, call \textbf{glfwGetMouseWheel}:
\begin{lstlisting} \begin{lstlisting}
int glfwGetMouseWheel(void) int glfwGetMouseWheel(void)
@ -876,7 +905,8 @@ int glfwGetMouseWheel( void )
The function returns an integer that represents the position of the mouse 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 wheel. When the user turns the wheel, the wheel position will increase or
decrease. decrease. Note that since scrolling hardware has no absolute position, \GLFW\
simply sets the position to zero when the window is opened.
It is also possible to register a callback function for mouse wheel events It is also possible to register a callback function for mouse wheel events
with the \textbf{glfwSetMouseWheelCallback} function: with the \textbf{glfwSetMouseWheelCallback} function:
@ -930,7 +960,7 @@ have to be called in order for joystick state to be updated.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\subsection{Joystick capabilities} \subsection{Joystick capabilities}
First, it is often necessary to determine if a joystick is connected, and First, it is often necessary to determine if a joystick is connected and
what its capabilities are. To get this information the function what its capabilities are. To get this information the function
\textbf{glfwGetJoystickParam} can be used: \textbf{glfwGetJoystickParam} can be used:
@ -948,6 +978,10 @@ To determine the number of axes or buttons that are supported by the
joystick, \textit{param} should be GLFW\_AXES or GLFW\_BUTTONS, joystick, \textit{param} should be GLFW\_AXES or GLFW\_BUTTONS,
respectively. respectively.
Note that \GLFW\ supports both D-pads and POVs, even though they are not
explicitly mentioned in the API. D-pads are exposed as a set of four buttons
and POVs are as two axes.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\subsection{Joystick position} \subsection{Joystick position}
@ -960,8 +994,8 @@ int glfwGetJoystickPos( int joy, float *pos, int numaxes )
As with \textbf{glfwGetJoystickParam}, the \textit{joy} argument As with \textbf{glfwGetJoystickParam}, the \textit{joy} argument
specifies which joystick to retrieve information from. The specifies which joystick to retrieve information from. The
\textit{numaxes} argument specifies how many axes to return, and the \textit{numaxes} argument specifies how many axes to return positions for and the
\textit{pos} argument specifies an array in which all the axis positions \textit{pos} argument specifies an array in which they
are stored. The function returns the actual number of axes that were are stored. The function returns the actual number of axes that were
returned, which could be less than \textit{numaxes} if the joystick does 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. not support all the requested axes, or if the joystick is not connected.
@ -999,12 +1033,12 @@ int glfwGetJoystickButtons( int joy, unsigned char *buttons,
int numbuttons) int numbuttons)
\end{lstlisting} \end{lstlisting}
The function works just like the \textbf{glfwGetJoystickAxis} function, The function works just like the \textbf{glfwGetJoystickAxis} function, except
except that it returns the state of joystick buttons instead of axis that it returns the state of joystick buttons instead of axis positions. Each
positions. Each button in the array specified by the \textit{buttons} button in the array specified by the \textit{buttons} argument can be either
argument can be either GLFW\_PRESS or GLFW\_RELEASE, telling if the GLFW\_PRESS or GLFW\_RELEASE, indicating whether the corresponding button is
corresponding button is currently held down or not. Unsupported buttons currently held down or not. Unsupported buttons will have the value
will have the value GLFW\_RELEASE. GLFW\_RELEASE.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
@ -1065,8 +1099,8 @@ An extension is defined by:
\end{enumerate} \end{enumerate}
A list of official extensions, together with their definitions, can be A list of official extensions, together with their definitions, can be
found at the \textit{OpenGL Extension Registry} found at the \textit{OpenGL Registry}
(\url{http://oss.sgi.com/projects/ogl-sample/registry/}). (\url{http://www.opengl.org/registry/}).
To use a certain extension, the following steps must be performed: To use a certain extension, the following steps must be performed:
@ -1081,6 +1115,12 @@ How this is done using \GLFW\ is described in the following sections.
Please note that this chapter covers some advanced topics, and is quite Please note that this chapter covers some advanced topics, and is quite
specific to the C programming language. specific to the C programming language.
For a much easier way to get access to \OpenGL\ extensions, you should probably
use a dedicated extension loading library such as GLEW or GLee. This kind of
library greatly reduces the amount of work necessary to use \OpenGL\
extensions. GLEW in particular has been extensively tested with and works well
with \GLFW .
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\section{Compile Time Check} \section{Compile Time Check}
@ -1095,25 +1135,25 @@ is an example of how to check for the extension GL\_ARB\_multitexture:
// Extension is supported by the include files // Extension is supported by the include files
#else #else
// Extension is not supported by the include files // Extension is not supported by the include files
// Update your <GL/gl.h> file! // Get a more up-to-date <GL/gl.h> file!
#endif #endif
\end{lstlisting} \end{lstlisting}
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\section{Runtime Check} \section{Runtime Check}
Even if the compiler include files have defined all the necessary tokens, Even if the compiler include files have defined all the necessary tokens, a
the target system may not support the extension (perhaps it has a given machine may not actually support the extension (it may have a graphics
different graphic card with a different \OpenGL\ implementation, or it has card with a different \OpenGL\ implementation, or an older driver). That is why
an older driver). That is why it is necessary to do a run time check for it is necessary to do a run time check for the extension support as well. This
the extension support as well. This is done with the \GLFW\ function is done with the \GLFW\ function \textbf{glfwExtensionSupported}, which has the
\textbf{glfwExtensionSupported}, which has the C syntax: C syntax:
\begin{lstlisting} \begin{lstlisting}
int glfwExtensionSupported(const char* extension) int glfwExtensionSupported(const char* extension)
\end{lstlisting} \end{lstlisting}
The argument \textit{extension} is a null terminated ISO~8859-1 string The argument \textit{extension} is a null terminated ASCII string
with the extension name. \textbf{glfwExtensionSupported} returns GL\_TRUE with the extension name. \textbf{glfwExtensionSupported} returns GL\_TRUE
if the extension is supported, otherwise it returns GL\_FALSE. if the extension is supported, otherwise it returns GL\_FALSE.
@ -1127,11 +1167,10 @@ int multitexture_supported;
#ifdef GL_ARB_multitexture #ifdef GL_ARB_multitexture
// Check if extension is supported at run time // Check if extension is supported at run time
multitexture_supported = multitexture_supported = glfwExtensionSupported("GL_ARB_multitexture");
glfwExtensionSupported( "GL_ARB_multitexture" );
#else #else
// Extension is not supported by the include files // Extension is not supported by the include files
// Update your <GL/gl.h> file! // Get a more up-to-date <GL/gl.h> file!
multitexture_supported = GL_FALSE; multitexture_supported = GL_FALSE;
#endif #endif
\end{lstlisting} \end{lstlisting}
@ -1152,16 +1191,16 @@ Now it is easy to check for the extension within the program, simply do:
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\section{Fetching Function Pointers} \section{Fetching Function Pointers}
Some extensions (not all) require the use of new \OpenGL\ functions, which Some extensions, though not all, require the use of new \OpenGL\ functions.
are not necessarily defined by your link libraries. Thus it is necessary These entry points are not necessarily exposed by your link libraries, making
to get the function pointers dynamically at run time. This is done with it necessary to find them dynamically at run time. You can retrieve these
the \GLFW\ function \textbf{glfwGetProcAddress}: entry points using the \textbf{glfwGetProcAddress} function:
\begin{lstlisting} \begin{lstlisting}
void* glfwGetProcAddress(const char* procname) void* glfwGetProcAddress(const char* procname)
\end{lstlisting} \end{lstlisting}
The argument \textit{procname} is a null terminated ISO~8859-1 string The argument \textit{procname} is a null terminated ASCII string
holding the name of the \OpenGL\ function. \textbf{glfwGetProcAddress} holding the name of the \OpenGL\ function. \textbf{glfwGetProcAddress}
returns the address to the function if the function is available, returns the address to the function if the function is available,
otherwise NULL is returned. otherwise NULL is returned.
@ -1179,21 +1218,20 @@ errors. My proposed solution is the following:
\begin{itemize} \begin{itemize}
\item Do not use the function name for the variable name. Use something \item Do not use the function name for the variable name. Use something
similar (perhaps with a prefix or suffix), and then use similar, perhaps by adding a prefix or suffix, and then use
\texttt{\#define} to map the function name to your variable. \texttt{\#define} to map the function name to your variable.
\item The standard type definition naming convention for function pointers \item The standard type definition naming convention for function pointers
is \texttt{PFN\textit{xxxx}PROC}, where \texttt{\textit{xxxx}} is is \texttt{PFN\textit{xxxx}PROC}, where \texttt{\textit{xxxx}} is
the uppercase version of the function name (e.g. the uppercase version of the function name (e.g.
\texttt{PFNGLACTIVETEXTUREARBPROC}). Either make sure that a \texttt{PFNGLACTIVETEXTUREARBPROC}). Either make sure your compiler uses
compatible \texttt{gl.h} and/or \texttt{glext.h} file is used by a compatible \texttt{gl.h} and/or \texttt{glext.h} file and rely on it to
your compiler and rely on it to do the type definitions for you, or define these types, or use define the types yourself using a different
use a custom type definition naming convention (e.g. naming convention (for example \texttt{\textit{xxxx}\_T}) and do the
\texttt{\textit{xxxx}\_T} or something) and do the type definitions type definitions yourself.
yourself.
\end{itemize} \end{itemize}
Here is an example of how to do it (here we use our own function pointer Here is a slightly longer example of how to use an extension, this time using
type defintion): our own function pointer type definition):
\begin{lstlisting} \begin{lstlisting}
// Type definition of the function pointer // Type definition of the function pointer
@ -1226,27 +1264,25 @@ int multitexture_supported;
#endif #endif
\end{lstlisting} \end{lstlisting}
Please note that the code example is not 100\% complete. First of all, Even this example leaves some things to be desired. First of all, the
the GL\_ARB\_multitexture extension defines many more functions than the GL\_ARB\_multitexture extension defines many more functions than the single
single function that the code example defines. Secondly, checking if an function used above. Secondly, checking if an extension is supported using
extension is supported using \textbf{glfwExtensionSupported} is not enough \textbf{glfwExtensionSupported} is not enough to ensure that the corresponding
to ensure that the corresponding functions will be valid. You also need to functions will be valid. You also need to check that the all function pointers
check if the function pointers returned by \textbf{glfwGetProcAddress} are returned by \textbf{glfwGetProcAddress} are non-NULL.
non-NULL values.
%------------------------------------------------------------------------- %-------------------------------------------------------------------------
\subsection{Function pointer type definitions} \subsection{Function pointer type definitions}
To make a function pointer type definition, you need to know the function 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 prototype. This can often be found in the extension definitions (e.g. at
the \textit{OpenGL Extension Registry}). All the functions that are the \textit{OpenGL Registry}). All the entry points that are defined by an
defined for an extension are listed with their C prototype definitions extension are listed with their C prototype definitions under the section
under the section \textit{New Procedures and Functions} in the extension \textit{New Procedures and Functions} in the extension definition.
definition.
For instance, if we look at the definition of the For instance, if we look at the definition of the
GL\_ARB\_texture\_compression extension, we find a list of new functions. GL\_ARB\_texture\_compression extension, we find a list of new functions.
One of the functions looks like this: One of these is declared like this:
\begin{lstlisting} \begin{lstlisting}
void GetCompressedTexImageARB(enum target, int lod, void* img); void GetCompressedTexImageARB(enum target, int lod, void* img);
@ -1265,9 +1301,8 @@ pointer type definition, is to replace the function name with
\texttt{(APIENTRY * \textit{xxxx}\_T)}, where \textit{xxxx} is the \texttt{(APIENTRY * \textit{xxxx}\_T)}, where \textit{xxxx} is the
uppercase version of the name (according to the proposed naming uppercase version of the name (according to the proposed naming
convention). The keyword \texttt{APIENTRY} is needed to be compatible convention). The keyword \texttt{APIENTRY} is needed to be compatible
between different platforms. The \GLFW\ include file \texttt{GL/glfw.h} between different platforms. The \GLFW\ header file \texttt{GL/glfw.h}
always makes sure that \texttt{APIENTRY} is properly defined, regardless ensures that \texttt{APIENTRY} is properly defined on all supported platforms.
of which platform the program is compiled on.
In other words, for the function \textbf{glGetCompressedTexImageARB} we In other words, for the function \textbf{glGetCompressedTexImageARB} we
get: get:
@ -1278,10 +1313,4 @@ typedef void (APIENTRY * GLGETCOMPRESSEDTEXIMAGEARB_T)
\end{lstlisting} \end{lstlisting}
%-------------------------------------------------------------------------
% Index
%-------------------------------------------------------------------------
% ...
\end{document} \end{document}