mirror of
https://github.com/glfw/glfw.git
synced 2024-11-10 00:51:47 +00:00
2129 lines
72 KiB
TeX
2129 lines
72 KiB
TeX
%-------------------------------------------------------------------------
|
||
% GLFW Reference Manual
|
||
% API Version: 2.7
|
||
%-------------------------------------------------------------------------
|
||
|
||
% Document class
|
||
\documentclass[a4paper,11pt,oneside]{report}
|
||
|
||
% Document title and API version
|
||
\newcommand{\glfwdoctype}[1][0]{Reference Manual}
|
||
\newcommand{\glfwapiver}[1][0]{2.7}
|
||
|
||
% Common document settings and macros
|
||
\input{glfwdoc.sty}
|
||
|
||
% PDF specific document settings
|
||
\hypersetup{pdftitle={GLFW Reference Manual}}
|
||
\hypersetup{pdfauthor={Marcus Geelnard}}
|
||
\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{10cm}
|
||
|
||
\large
|
||
Trademarks
|
||
|
||
\small
|
||
OpenGL and IRIX are registered trademarks of Silicon Graphics, Inc.\linebreak
|
||
Microsoft and Windows are registered trademarks of Microsoft Corporation.\linebreak
|
||
Mac OS is a registered trademark of Apple Computer, Inc.\linebreak
|
||
Linux is a registered trademark of Linus Torvalds.\linebreak
|
||
FreeBSD is a registered trademark of Wind River Systems, Inc.\linebreak
|
||
Solaris is a trademark of Sun Microsystems, Inc.\linebreak
|
||
UNIX is a registered trademark of The Open Group.\linebreak
|
||
X Window System is a trademark of The Open Group.\linebreak
|
||
POSIX is a trademark of IEEE.\linebreak
|
||
Truevision, TARGA and TGA are registered trademarks of Truevision, Inc.\linebreak
|
||
|
||
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\ window.
|
||
\item Keyboard, mouse and joystick input.
|
||
\item A high precision timer.
|
||
\item Support for querying and using \OpenGL\ extensions.
|
||
\end{itemize}
|
||
\vspace{18pt}
|
||
|
||
All this functionality is implemented as a set of easy-to-use functions,
|
||
which makes it possible to write an \OpenGL\ application framework in just a
|
||
few lines of code. The \GLFW\ API is completely operating system and
|
||
platform independent, which makes it very simple to port \GLFW\ based \OpenGL\
|
||
applications to a variety of platforms.
|
||
|
||
Currently supported platforms are:
|
||
\begin{itemize}
|
||
\item Microsoft Windows\textsuperscript{\textregistered} 95/98/ME/NT/2000/XP/Vista.
|
||
\item Unix\textsuperscript{\textregistered} or Unix<69>-like systems running the
|
||
X Window System\texttrademark, e.g. Linux\textsuperscript{\textregistered},
|
||
IRIX\textsuperscript{\textregistered}, FreeBSD\textsuperscript{\textregistered},
|
||
Solaris\texttrademark, QNX\textsuperscript{\textregistered} and
|
||
Mac OS\textsuperscript{\textregistered} X.
|
||
\item Mac OS\textsuperscript{\textregistered} X (Carbon)\footnote{Support for joysticks missing at the time of writing.}
|
||
\end{itemize}
|
||
|
||
|
||
|
||
%-------------------------------------------------------------------------
|
||
% GLFW Operation
|
||
%-------------------------------------------------------------------------
|
||
\chapter{GLFW Operation Overview}
|
||
\thispagestyle{fancy}
|
||
|
||
|
||
%-------------------------------------------------------------------------
|
||
\section{The GLFW Window}
|
||
\GLFW\ only supports one opened window 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 via
|
||
callback functions. There are different callback functions for dealing with
|
||
different kinds of user input. 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 different kinds of window
|
||
information through different \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 if 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 \GLFW\ functions can be used, \GLFW\ must be initialized to
|
||
ensure proper functionality, and before a program terminates, \GLFW\ has to
|
||
be terminated in order to free up resources 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
|
||
used before this function has been called.
|
||
\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.
|
||
\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}
|
||
The function terminates \GLFW. Among other things it closes the window,
|
||
if it is opened. This function must 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}
|
||
The function returns the \GLFW\ library version.
|
||
\end{refdescription}
|
||
|
||
|
||
%-------------------------------------------------------------------------
|
||
\pagebreak
|
||
\section{Window Handling}
|
||
The main functionality of \GLFW\ is to provide a simple interface to
|
||
\OpenGL\ window management. \GLFW\ can open one window, 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, then
|
||
\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, then
|
||
\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 generate a 16-<2D>bit color buffer, if
|
||
possible.
|
||
\item [\textit{alphabits}]\ \\
|
||
The number of bits to use for the alpha buffer (0 means no alpha
|
||
buffer).
|
||
\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} can 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}
|
||
The 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
|
||
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 any system
|
||
screensavers are 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}).
|
||
\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 accumulator buffer.\\ \hline
|
||
GLFW\_ACCUM\_GREEN\_BITS & 0 & Number of bits for the green channel of the accumulator buffer.\\ \hline
|
||
GLFW\_ACCUM\_BLUE\_BITS & 0 & Number of bits for the blue channel of the accumulator buffer.\\ \hline
|
||
GLFW\_ACCUM\_ALPHA\_BITS & 0 & Number of bits for the alpha channel of the accumulator buffer.\\ \hline
|
||
GLFW\_AUX\_BUFFERS & 0 & Number of auxiliary buffers.\\ \hline
|
||
GLFW\_STEREO & GL\_FALSE & Specify if stereo rendering should be supported (can be GL\_TRUE or GL\_FALSE).\\ \hline
|
||
GLFW\_WINDOW\_NO\_RESIZE & GL\_FALSE & Specify whether the window can be resized (not used for fullscreen windows).\\ \hline
|
||
GLFW\_FSAA\_SAMPLES & 0 & Number of samples to use for the multisampling buffer. Zero disables multisampling.\\ \hline
|
||
GLFW\_OPENGL\_VERSION\_MAJOR & 0 & Major number of the desired OpenGL version.
|
||
The default requests the highest OpenGL version equal to or lower than 2.1.\\ \hline
|
||
GLFW\_OPENGL\_VERSION\_MINOR & 0 & Minor number of the desired OpenGL version.
|
||
The default requests the highest OpenGL version equal to or lower than 2.1.\\ \hline
|
||
GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_FALSE & Specify whether the OpenGL context should be forward compatible (i.e. disallow legacy functionality).
|
||
This hint is ignored for OpenGL version 2.1 and below.\\ \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 constants in the table \ref{tab:winhints}.
|
||
\item [\textit{hint}]\ \\
|
||
An integer giving the value of the corresponding target (see table
|
||
\ref{tab:winhints}).
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The 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 / visuals are available,
|
||
\textbf{glfwOpenWindow} will fail.
|
||
|
||
The GLFW\_REFRESH\_RATE property 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!
|
||
|
||
If you want to create a context with OpenGL version 3.0 or above you have to
|
||
set the GLFW\_OPENGL\_VERSION\_MAJOR and GLFW\_OPENGL\_VERSION\_MINOR hints
|
||
accordingly. If you don't do this, the highest OpenGL version available for a
|
||
context is 2.1 or lower.
|
||
\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}
|
||
The 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). The function should have the following C language
|
||
prototype:
|
||
|
||
\texttt{int GLFWCALL 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 selected callback function
|
||
will be deselected.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The function selects which function to be called upon a window close
|
||
event.
|
||
|
||
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} 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}
|
||
The 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}
|
||
The 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}
|
||
The \OpenGL\ context is guaranteed to be preserved after calling
|
||
\textbf{glfwSetWindowSize}, even if the video mode is changed.
|
||
\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}
|
||
The function changes the position of an opened window. It does not have
|
||
any effect on a fullscreen window.
|
||
\end{refdescription}
|
||
|
||
|
||
%-------------------------------------------------------------------------
|
||
\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}
|
||
The 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 GLFWCALL 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 selected callback function
|
||
will be deselected.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The function selects which function to be called upon a window size
|
||
change event.
|
||
|
||
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} is called.
|
||
\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 accumulator buffer.\\ \hline
|
||
GLFW\_ACCUM\_GREEN\_BITS & Number of bits for the green channel of the accumulator buffer.\\ \hline
|
||
GLFW\_ACCUM\_BLUE\_BITS & Number of bits for the blue channel of the accumulator buffer.\\ \hline
|
||
GLFW\_ACCUM\_ALPHA\_BITS & Number of bits for the alpha channel of the accumulator buffer.\\ \hline
|
||
GLFW\_AUX\_BUFFERS & Number of auxiliary buffers.\\ \hline
|
||
GLFW\_STEREO & GL\_TRUE if stereo rendering is supported, else GL\_FALSE.\\ \hline
|
||
GLFW\_WINDOW\_NO\_RESIZE & GL\_TRUE if the window cannot be resized, 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 desired OpenGL version.\\ \hline
|
||
GLFW\_OPENGL\_VERSION\_MINOR & Minor number of the desired OpenGL version.\\ \hline
|
||
GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_TRUE if the OpenGL context is forward compatible (i.e. disallows legacy functionality), else GL\_FALSE.
|
||
This is always GL\_FALSE for OpenGL version 2.1 and below.\\ \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 different parameters depending on the value of
|
||
\textit{param}. Table \ref{tab:winparams} lists valid \textit{param}
|
||
values, and their corresponding return values.
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The 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.
|
||
\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}
|
||
The 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 before swapping the front and back
|
||
buffers.
|
||
\end{refdescription}
|
||
|
||
|
||
%-------------------------------------------------------------------------
|
||
\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}
|
||
The 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.
|
||
\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 GLFWCALL functionname( void );}
|
||
|
||
Where \textit{functionname} is the name of the callback function.
|
||
|
||
If \textit{cbfun} is NULL, any previously selected callback function
|
||
will be deselected.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The function selects which function to be called upon a window refresh
|
||
event, 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} is called.
|
||
\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}
|
||
The 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}
|
||
The 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, \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}
|
||
The 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 (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}
|
||
The 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 ready, the events 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,
|
||
\textbf{glfwWaitEvents} may wake up on events that are \emph{not}
|
||
processed or reported by \textbf{glfwPollEvents} too, 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\_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
|
||
\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}
|
||
The 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.
|
||
|
||
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} 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}
|
||
The 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} 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 filled out with the horizontal
|
||
position of the mouse.
|
||
\item [\textit{ypos}]\ \\
|
||
Pointer to an integer that will be filled out with the vertical
|
||
position of the mouse.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
The function returns the current mouse position in \textit{xpos} and
|
||
\textit{ypos}.
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The 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 limited to the client area of the window.
|
||
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 (normally
|
||
-2147483648 to +2147483647).
|
||
\end{refdescription}
|
||
|
||
\begin{refnotes}
|
||
A window must be opened for the function to have any effect, and
|
||
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or
|
||
\textbf{glfwSwapBuffers} 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}
|
||
The 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.
|
||
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}
|
||
The 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} 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}
|
||
The 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 GLFWCALL 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 selected callback function
|
||
will be deselected.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The function selects which function to be called upon a keyboard key
|
||
event. 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).
|
||
|
||
A window has to be opened for this function to have any effect.
|
||
\end{refdescription}
|
||
|
||
\begin{refnotes}
|
||
Keyboard events are recorded continuously, but only reported when
|
||
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or
|
||
\textbf{glfwSwapBuffers} 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 GLFWCALL 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 selected callback function
|
||
will be deselected.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The function selects which function to be called upon a keyboard character
|
||
event. 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} 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 GLFWCALL 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 selected callback function
|
||
will be deselected.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The function selects which function to be called upon a mouse button
|
||
event.
|
||
|
||
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} 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 GLFWCALL 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 selected callback function
|
||
will be deselected.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The function selects which function to be called upon a mouse motion event.
|
||
|
||
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} 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 GLFWCALL 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 selected callback function
|
||
will be deselected.
|
||
\end{description}
|
||
\end{refparameters}
|
||
|
||
\begin{refreturn}
|
||
none
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The function selects which function to be called upon a mouse wheel event.
|
||
|
||
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} 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}
|
||
The 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 valid.
|
||
\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}
|
||
The 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 valid.
|
||
\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}
|
||
The 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 valid.
|
||
\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}
|
||
The 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. The worst case resolution is somewhere in the order of $10~ms$, while
|
||
for most systems the resolution should be better than $1~\mu s$.
|
||
\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}
|
||
The 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. Using extensions is different under different
|
||
systems, which is why \GLFW\ has provided an operating system independent
|
||
interface to querying and using \OpenGL\ extensions.
|
||
|
||
|
||
%-------------------------------------------------------------------------
|
||
\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}
|
||
The 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 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 pointer to the specified \OpenGL\ function if it
|
||
is supported, otherwise NULL is returned.
|
||
\end{refreturn}
|
||
|
||
\begin{refdescription}
|
||
The 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}
|
||
The function returns the \OpenGL\ implementation version. This is a
|
||
convenient function that parses the version number information from 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.
|
||
|
||
When GLFW\_AUTO\_POLL\_EVENTS is disabled, calling
|
||
\textbf{glfwSwapBuffers} will not result in a call to
|
||
\textbf{glfwPollEvents}. This can be useful if \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 recieved 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}, 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}
|
||
|
||
|
||
\end{document}
|