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