|
|
%------------------------------------------------------------------------- |
|
|
% GLFW Reference Manual |
|
|
% API Version: 3.0 |
|
|
%------------------------------------------------------------------------- |
|
|
|
|
|
% Document class |
|
|
\documentclass[a4paper,11pt,oneside]{report} |
|
|
|
|
|
% Document title and API version |
|
|
\newcommand{\glfwdoctype}[1][0]{Reference Manual} |
|
|
\newcommand{\glfwapiver}[1][0]{3.0} |
|
|
|
|
|
% Common document settings and macros |
|
|
\input{glfwdoc.sty} |
|
|
|
|
|
% PDF specific document settings |
|
|
\hypersetup{pdftitle={GLFW Reference Manual}} |
|
|
\hypersetup{pdfauthor={Camilla Berglund}} |
|
|
\hypersetup{pdfkeywords={GLFW,OpenGL,reference,manual}} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
% Document body |
|
|
%------------------------------------------------------------------------- |
|
|
|
|
|
\begin{document} |
|
|
|
|
|
\pagestyle{plain} |
|
|
|
|
|
% Title page |
|
|
\glfwmaketitle |
|
|
|
|
|
% Summary, trademarks and table of contents |
|
|
\pagenumbering{roman} |
|
|
\setcounter{page}{1} |
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
% Summary and Trademarks |
|
|
%------------------------------------------------------------------------- |
|
|
\chapter*{Summary} |
|
|
|
|
|
This document is primarily a function reference manual for the \GLFW\ API. |
|
|
For a description of how to use \GLFW\ you should refer to the |
|
|
\textit{GLFW Users Guide}. |
|
|
\vspace{5cm} |
|
|
|
|
|
\large |
|
|
Trademarks |
|
|
|
|
|
\small |
|
|
OpenGL and IRIX are registered trademarks of Silicon Graphics, Inc.\linebreak |
|
|
Microsoft and Windows are registered trademarks of Microsoft Corporation.\linebreak |
|
|
Mac OS is a registered trademark of Apple Computer, Inc.\linebreak |
|
|
Linux is a registered trademark of Linus Torvalds.\linebreak |
|
|
FreeBSD is a registered trademark of Wind River Systems, Inc.\linebreak |
|
|
Solaris is a trademark of Sun Microsystems, Inc.\linebreak |
|
|
UNIX is a registered trademark of The Open Group.\linebreak |
|
|
X Window System is a trademark of The Open Group.\linebreak |
|
|
POSIX is a trademark of IEEE.\linebreak |
|
|
Truevision, TARGA and TGA are registered trademarks of Truevision, Inc.\linebreak |
|
|
|
|
|
All other trademarks mentioned in this document are the property of their respective owners. |
|
|
\normalsize |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
% Table of contents |
|
|
%------------------------------------------------------------------------- |
|
|
\tableofcontents |
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
% List of tables |
|
|
%------------------------------------------------------------------------- |
|
|
\listoftables |
|
|
\pagebreak |
|
|
|
|
|
|
|
|
% Document chapters starts here... |
|
|
\pagenumbering{arabic} |
|
|
\setcounter{page}{1} |
|
|
|
|
|
\pagestyle{fancy} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
% Introduction |
|
|
%------------------------------------------------------------------------- |
|
|
\chapter{Introduction} |
|
|
\thispagestyle{fancy} |
|
|
|
|
|
\GLFW\ is a portable API (Application Program Interface) that handles |
|
|
operating system specific tasks related to \OpenGL\ programming. While |
|
|
\OpenGL\ in general is portable, easy to use and often results in tidy and |
|
|
compact code, the operating system specific mechanisms that are required |
|
|
to set up and manage an \OpenGL\ window are quite the opposite. \GLFW\ tries |
|
|
to remedy this by providing the following functionality: |
|
|
|
|
|
\begin{itemize} |
|
|
\item Opening and managing an \OpenGL\ context and its associated window. |
|
|
\item Keyboard, mouse and joystick input. |
|
|
\item A high precision timer. |
|
|
\item Support for querying and using \OpenGL\ extensions. |
|
|
\end{itemize} |
|
|
|
|
|
All this functionality is implemented as a set of easy-to-use functions, |
|
|
which makes it possible to write an \OpenGL\ application framework in just a |
|
|
few lines of code. The \GLFW\ API looks and behaves the same on all supported |
|
|
platforms, making it very simple to port \GLFW\ based \OpenGL\ applications to |
|
|
a variety of platforms. |
|
|
|
|
|
Currently supported platforms are: |
|
|
\begin{itemize} |
|
|
\item Microsoft Windows\textsuperscript{\textregistered} (32-bit only). |
|
|
\item Unix\textsuperscript{\textregistered} or Unix<EFBFBD>-like systems running |
|
|
resonably a modern version of the X Window |
|
|
System\texttrademark\footnote{X11.app on Mac OS X is not supported due to its |
|
|
incomplete implementation of GLXFBConfigs} e.g. |
|
|
Linux\textsuperscript{\textregistered}, |
|
|
FreeBSD\textsuperscript{\textregistered} and Solaris\texttrademark (32- and |
|
|
64-bit). |
|
|
\item Mac OS\textsuperscript{\textregistered} X, using Cocoa\footnote{Joystick |
|
|
input is not yet supported on Mac OS X.} (32- and 64-bit). |
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
% GLFW Operation |
|
|
%------------------------------------------------------------------------- |
|
|
\chapter{GLFW Operation Overview} |
|
|
\thispagestyle{fancy} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\section{The GLFW Window} |
|
|
\GLFW\ only supports having one window open at a time. The window can be either |
|
|
a normal desktop window or a fullscreen window. The latter is completely |
|
|
undecorated, without window borders, and covers the entire monitor. With a |
|
|
fullscreen window, it is also possible to select which video mode to use. |
|
|
|
|
|
When a window is opened, an \OpenGL\ rendering context is created and |
|
|
attached to the entire client area of the window. When the window is closed, |
|
|
the \OpenGL\ rendering context is detached and destroyed. |
|
|
|
|
|
Through a window it is possible to receive user input in the form of |
|
|
keyboard and mouse input. User input is exposed through the \GLFW\ API |
|
|
primarily via a set of callback functions. Also, \GLFW\ stores most user input |
|
|
as internal state that can be queried through different \GLFW\ API functions |
|
|
(for instance it is possible to query the position of the mouse cursor with the |
|
|
\textbf{glfwGetMousePos} function). |
|
|
|
|
|
As for user input, it is possible to receive information about window |
|
|
state changes, such as window resize or close events, through callback |
|
|
functions. It is also possible to query some kinds of information about the |
|
|
window information using \GLFW\ API functions. |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\section{The GLFW Event Loop} |
|
|
The \GLFW\ event loop is an open loop, which means that it is up to the |
|
|
programmer to design the loop. Events are processed by calling specific |
|
|
\GLFW\ functions, which in turn query the system for new input and window |
|
|
events and reports these events back to the program through callback |
|
|
functions. |
|
|
|
|
|
The programmer decides when to call the event processing functions and |
|
|
when to abort the event loop. |
|
|
|
|
|
In pseudo language, a typical event loop might look like this: |
|
|
|
|
|
\begin{lstlisting} |
|
|
repeat until window is closed |
|
|
{ |
|
|
poll events |
|
|
draw OpenGL graphics |
|
|
} |
|
|
\end{lstlisting} |
|
|
|
|
|
There are two ways to handle events in \GLFW : |
|
|
|
|
|
\begin{itemize} |
|
|
\item Block the event loop while waiting for new events. |
|
|
\item Poll for new events and continue the loop regardless of whether there |
|
|
are any new events or not. |
|
|
\end{itemize} |
|
|
|
|
|
The first method is useful for interactive applications that do not |
|
|
need to refresh the \OpenGL\ display unless the user interacts with the |
|
|
application through user input. Typical applications are CAD software |
|
|
and other kinds of editors. |
|
|
|
|
|
The second method is useful for applications that need to refresh the |
|
|
\OpenGL\ display constantly, regardless of user input, such as games, |
|
|
demos, 3D animations, screen savers and so on. |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\section{Callback Functions} |
|
|
Using callback functions can be a good method for receiving up to date |
|
|
information about window state and user input. When a window has been |
|
|
opened, it is possible to register custom callback functions that will |
|
|
be called when certain events occur. |
|
|
|
|
|
Callback functions are called from any of the event polling functions |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or |
|
|
\textbf{glfwSwapBuffers}. |
|
|
|
|
|
Callback functions should \emph{only} be used to gather information. Since |
|
|
the callback functions are called from within the internal \GLFW\ event |
|
|
polling loops, they should not call any \GLFW\ functions that might |
|
|
result in considerable \GLFW\ state changes, nor stall the event polling |
|
|
loop for a lengthy period of time. |
|
|
|
|
|
In other words, most or all \OpenGL\ rendering should be called from the |
|
|
main application event loop, not from any of the \GLFW\ callback |
|
|
functions. Also, the only \GLFW\ functions that may be safely called from |
|
|
callback functions are the different Get functions (e.g. |
|
|
\textbf{glfwGetKey}, \textbf{glfwGetTime}, \textbf{glfwGetWindowParam} |
|
|
etc.). |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
% Function Reference |
|
|
%------------------------------------------------------------------------- |
|
|
\chapter{Function Reference} |
|
|
\thispagestyle{fancy} |
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\section{GLFW Initialization and Termination} |
|
|
Before any other \GLFW\ functions can be used, \GLFW\ must be initialized to |
|
|
ensure proper functionality, and before a program terminates \GLFW\ should be |
|
|
terminated in order to free allocated resources, memory, etc. |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwInit} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwInit(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
If the function succeeds, GL\_TRUE is returned.\\ |
|
|
If the function fails, GL\_FALSE is returned. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
The glfwInit function initializes \GLFW. No other \GLFW\ functions may be |
|
|
called before this function has succeeded. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
This function may take several seconds to complete on some systems, while |
|
|
on other systems it may take only a fraction of a second to complete. |
|
|
|
|
|
This function registers a function calling \textbf{glfwTerminate} with the |
|
|
atexit facility of the C library. |
|
|
|
|
|
On Mac OS X, this function will change the current directory of the application |
|
|
to the \textbf{Contents/Resources} subdirectory of the application's bundle, if |
|
|
present. For more information on bundles, see the Bundle Programming Guide |
|
|
provided by Apple. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwTerminate} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwTerminate(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function terminates \GLFW. Among other things it closes the window, if |
|
|
open. This function should be called before a program exits. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetVersion} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwGetVersion(int* major, int* minor, int* rev) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{major}]\ \\ |
|
|
Pointer to an integer that will hold the major version number. |
|
|
\item [\textit{minor}]\ \\ |
|
|
Pointer to an integer that will hold the minor version number. |
|
|
\item [\textit{rev}]\ \\ |
|
|
Pointer to an integer that will hold the revision. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the major and minor version numbers and the revision |
|
|
for the currently linked \GLFW\ library. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function returns the \GLFW\ library version. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\pagebreak |
|
|
\section{Window Handling} |
|
|
The primary purpose of \GLFW\ is to provide a simple interface to |
|
|
\OpenGL\ context creation and window management. \GLFW\ supports one window at |
|
|
a time, which can be either a normal desktop window or a fullscreen window. |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwOpenWindow} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwOpenWindow(int width, int height, |
|
|
int redbits, int greenbits, int bluebits, |
|
|
int alphabits, int depthbits, int stencilbits, |
|
|
int mode) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{width}]\ \\ |
|
|
The width of the window. If \textit{width} is zero, it will be |
|
|
calculated as ${width=\frac{4}{3}height}$, if \textit{height} is not |
|
|
zero. If both \textit{width} and \textit{height} are zero, |
|
|
\textit{width} will be set to 640. |
|
|
\item [\textit{height}]\ \\ |
|
|
The height of the window. If \textit{height} is zero, it will be |
|
|
calculated as ${height=\frac{3}{4}width}$, if \textit{width} is not |
|
|
zero. If both \textit{width} and \textit{height} are zero, |
|
|
\textit{height} will be set to 480. |
|
|
\item [\textit{redbits, greenbits, bluebits}]\ \\ |
|
|
The number of bits to use for each color component of the color buffer |
|
|
(0 means default color depth). For instance, setting \textit{redbits=5, |
|
|
greenbits=6 and bluebits=5} will create a 16-<EFBFBD>bit color buffer, if |
|
|
possible. |
|
|
\item [\textit{alphabits}]\ \\ |
|
|
The number of bits to use for the alpha channel of the color buffer (0 means |
|
|
no alpha channel). |
|
|
\item [\textit{depthbits}]\ \\ |
|
|
The number of bits to use for the depth buffer (0 means no depth |
|
|
buffer). |
|
|
\item [\textit{stencilbits}]\ \\ |
|
|
The number of bits to use for the stencil buffer (0 means no stencil |
|
|
buffer). |
|
|
\item [\textit{mode}]\ \\ |
|
|
Selects which type of \OpenGL\ window to use. \textit{mode} must be |
|
|
either GLFW\_WINDOW, which will generate a normal desktop window, or |
|
|
GLFW\_FULLSCREEN, which will generate a window which covers the entire |
|
|
screen. When GLFW\_FULLSCREEN is selected, the video mode will be |
|
|
changed to the resolution that closest matches the \textit{width} and |
|
|
\textit{height} parameters. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
If the function succeeds, GL\_TRUE is returned.\\ |
|
|
If the function fails, GL\_FALSE is returned. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function opens a window that best matches the parameters given to the |
|
|
function. How well the resulting window matches the desired window depends |
|
|
mostly on the available hardware and \OpenGL\ drivers. In general, |
|
|
selecting a fullscreen mode has better chances of generating a close match |
|
|
of buffers and channel sizes than does a normal desktop window, since \GLFW\ |
|
|
can freely select from all the available video modes. A desktop window is |
|
|
normally restricted to the video mode of the desktop. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
For additional control of window properties, see |
|
|
\textbf{glfwOpenWindowHint}. |
|
|
|
|
|
In fullscreen mode the mouse cursor is hidden by default and the |
|
|
screensaver is prohibited from starting. In windowed mode the mouse |
|
|
cursor is visible and screensavers are allowed to start. To change the |
|
|
visibility of the mouse cursor, use \textbf{glfwEnable} or |
|
|
\textbf{glfwDisable} with the argument GLFW\_MOUSE\_CURSOR. |
|
|
|
|
|
In order to determine the actual properties of an opened window, use |
|
|
\textbf{glfwGetWindowParam} and \textbf{glfwGetWindowSize} (or |
|
|
\textbf{glfwSetWindowSizeCallback}). |
|
|
|
|
|
On Microsoft Windows, if the executable has an icon resource named |
|
|
\textbf{GLFW\_ICON}, it will be set as the icon for the window. If no such |
|
|
icon is present, the \textbf{IDI\_WINLOGO} icon will be used instead. |
|
|
|
|
|
On Mac OS X the \GLFW\ window has no icon, but programs using \GLFW\ will use |
|
|
the application bundle's icon. For more information on bundles, see the Bundle |
|
|
Programming Guide provided by Apple. |
|
|
|
|
|
For information on how the availability of different platform-specific |
|
|
extensions affect the behavior of this function, see appendix |
|
|
\ref{chap:compatibility}. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\begin{table}[p] |
|
|
\begin{center} |
|
|
\begin{tabular}{|l|l|p{7.0cm}|} \hline \raggedright |
|
|
\textbf{Name} & \textbf{Default} & \textbf{Description} \\ \hline |
|
|
GLFW\_REFRESH\_RATE & 0 & Vertical monitor refresh rate in Hz (only used for fullscreen windows). Zero means system default.\\ \hline |
|
|
GLFW\_ACCUM\_RED\_BITS & 0 & Number of bits for the red channel of the accumulation buffer.\\ \hline |
|
|
GLFW\_ACCUM\_GREEN\_BITS & 0 & Number of bits for the green channel of the accumulation buffer.\\ \hline |
|
|
GLFW\_ACCUM\_BLUE\_BITS & 0 & Number of bits for the blue channel of the accumulation buffer.\\ \hline |
|
|
GLFW\_ACCUM\_ALPHA\_BITS & 0 & Number of bits for the alpha channel of the accumulation buffer.\\ \hline |
|
|
GLFW\_AUX\_BUFFERS & 0 & Number of auxiliary buffers.\\ \hline |
|
|
GLFW\_STEREO & GL\_FALSE & Specify if stereo rendering should be supported (can be GL\_TRUE or GL\_FALSE).\\ \hline |
|
|
GLFW\_WINDOW\_NO\_RESIZE & GL\_FALSE & Specify whether the window can be resized by the user (not used for fullscreen windows).\\ \hline |
|
|
GLFW\_FSAA\_SAMPLES & 0 & Number of samples to use for the multisampling buffer. Zero disables multisampling.\\ \hline |
|
|
GLFW\_OPENGL\_VERSION\_MAJOR & 1 & Major number of the desired minimum \OpenGL\ version.\\ \hline |
|
|
GLFW\_OPENGL\_VERSION\_MINOR & 1 & Minor number of the desired minimum \OpenGL\ version.\\ \hline |
|
|
GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_FALSE & Specify whether the \OpenGL\ context should be forward-compatible (i.e. disallow legacy functionality). |
|
|
This should only be used when requesting \OpenGL\ version 3.0 or above.\\ \hline |
|
|
GLFW\_OPENGL\_DEBUG\_CONTEXT & GL\_FALSE & Specify whether a debug context should be created.\\ \hline |
|
|
GLFW\_OPENGL\_PROFILE & 0 & The \OpenGL\ profile the context should implement, or zero to let the system choose. |
|
|
Available profiles are GLFW\_OPENGL\_CORE\_PROFILE and GLFW\_OPENGL\_COMPAT\_PROFILE.\\ \hline |
|
|
\end{tabular} |
|
|
\end{center} |
|
|
\caption{Targets for \textbf{glfwOpenWindowHint}} |
|
|
\label{tab:winhints} |
|
|
\end{table} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwOpenWindowHint} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwOpenWindowHint(int target, int hint) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{target}]\ \\ |
|
|
Can be any of the tokens in the table \ref{tab:winhints}. |
|
|
\item [\textit{hint}]\ \\ |
|
|
An integer giving the value of the corresponding token (see table |
|
|
\ref{tab:winhints}). |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets additional properties for a window that is to be opened. |
|
|
For a hint to be registered, the function must be called before calling |
|
|
\textbf{glfwOpenWindow}. When the \textbf{glfwOpenWindow} function is |
|
|
called, any hints that were registered with the \textbf{glfwOpenWindowHint} |
|
|
function are used for setting the corresponding window properties, and |
|
|
then all hints are reset to their default values. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
In order to determine the actual properties of an opened window, use |
|
|
\textbf{glfwGetWindowParam} (after the window has been opened). |
|
|
|
|
|
GLFW\_STEREO is a hard constraint. If stereo rendering is requested, but no |
|
|
stereo rendering capable pixel formats / framebuffer configs are available, |
|
|
\textbf{glfwOpenWindow} will fail. |
|
|
|
|
|
The GLFW\_REFRESH\_RATE hint should be used with caution. Most |
|
|
systems have default values for monitor refresh rates that are optimal |
|
|
for the specific system. Specifying the refresh rate can override these |
|
|
settings, which can result in suboptimal operation. The monitor may be |
|
|
unable to display the resulting video signal, or in the worst case it may |
|
|
even be damaged! |
|
|
|
|
|
The GLFW\_WINDOW\_NO\_RESIZE hint applies only to manual resizing by the user. |
|
|
A window created with this hint enabled can still be resized by the application |
|
|
by calling \textbf{glfwSetWindowSize}. |
|
|
|
|
|
The GLFW\_OPENGL\_VERSION\_MAJOR and GLFW\_OPENGL\_VERSION\_MINOR hints specify |
|
|
the \OpenGL\ version that the created context must be compatible with, |
|
|
\emph{not} the exact version to use. It is therefore perfectly safe to use the |
|
|
default of version 1.1 for legacy code and you will still get |
|
|
backwards-compatible contexts of version 3.0 and above when available. |
|
|
|
|
|
To make the behavior of the above version hints consistent across both modern |
|
|
and legacy drivers, \textbf{glfwOpenWindow} will fail if the modern creation |
|
|
mechanism (as specified in \textbf{WGL\_ARB\_create\_context} |
|
|
and \textbf{GLX\_ARB\_create\_context}) is unavailable \emph{and} the created |
|
|
context is of a version lower than the one that was requested. |
|
|
|
|
|
At the time of release, the exact meaning of what a "debug context" is (as |
|
|
created using the GLFW\_OPENGL\_DEBUG\_CONTEXT hint) has yet to be defined by |
|
|
the Khronos ARB WG. |
|
|
|
|
|
For information on how the availability of different extensions affect the |
|
|
behavior of this function, see appendix \ref{chap:compatibility}. |
|
|
|
|
|
For full details on the workings of the \OpenGL\ version, forward-compatibility |
|
|
and debug hints, see the specifications for \textbf{WGL\_ARB\_create\_context} |
|
|
and \textbf{GLX\_ARB\_create\_context}, respectively. The relevant \GLFW\ |
|
|
hints map very closely to their platform-specific counterparts. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwCloseWindow} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwCloseWindow(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function closes an opened window and destroys the associated \OpenGL\ |
|
|
context. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetWindowCloseCallback} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetWindowCloseCallback(GLFWwindowclosefun cbfun) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{cbfun}]\ \\ |
|
|
Pointer to a callback function that will be called when a user requests |
|
|
that the window should be closed, typically by clicking the window close |
|
|
icon (e.g. the cross in the upper right corner of a window under |
|
|
Microsoft Windows), and on Mac OS X also when selecting \textbf{Quit} from |
|
|
the application menu. The function should have the following C language |
|
|
prototype: |
|
|
|
|
|
\texttt{int functionname(void);} |
|
|
|
|
|
Where \textit{functionname} is the name of the callback function. The |
|
|
return value of the callback function indicates wether or not the window |
|
|
close action should continue. If the function returns GL\_TRUE, the |
|
|
window will be closed. If the function returns GL\_FALSE, the window |
|
|
will not be closed. |
|
|
|
|
|
If \textit{cbfun} is NULL, any previously set callback function |
|
|
will be unset. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the callback for window close events. |
|
|
|
|
|
A window has to be opened for this function to have any effect. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Window close events are recorded continuously, but only reported when |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called. |
|
|
|
|
|
The \OpenGL\ context is still valid when this function is called. |
|
|
|
|
|
Note that the window close callback function is not called when |
|
|
\textbf{glfwCloseWindow} is called, but only when the close request |
|
|
comes from the window manager. |
|
|
|
|
|
Do \emph{not} call \textbf{glfwCloseWindow} from a window close |
|
|
callback function. Close the window by returning GL\_TRUE from the |
|
|
function. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetWindowTitle} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetWindowTitle(const char* title) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{title}]\ \\ |
|
|
Pointer to a null terminated ISO~8859-1 (8-bit Latin~1) string that |
|
|
holds the title of the window. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function changes the title of the opened window. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
The title property of a window is often used in situations other than for |
|
|
the window title, such as the title of an application icon when it is in |
|
|
iconified state. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetWindowSize} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetWindowSize(int width, int height) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{width}]\ \\ |
|
|
Width of the window. |
|
|
\item [\textit{height}]\ \\ |
|
|
Height of the window. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function changes the size of an opened window. The \textit{width} and |
|
|
\textit{height} parameters denote the size of the client area of the |
|
|
window (i.e. excluding any window borders and decorations). |
|
|
|
|
|
If the window is in fullscreen mode, the video mode will be changed to a |
|
|
resolution that closest matches the width and height parameters (the |
|
|
number of color bits will not be changed). |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
This function has no effect if the window is iconified. |
|
|
|
|
|
The \OpenGL\ context is guaranteed to be preserved after calling |
|
|
\textbf{glfwSetWindowSize}, even if the video mode is changed. |
|
|
|
|
|
This function is not affected by the value of the GLFW\_WINDOW\_NO\_RESIZE |
|
|
hint. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetWindowPos} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetWindowPos(int x, int y) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{x}]\ \\ |
|
|
Horizontal position of the window, relative to the upper left corner |
|
|
of the desktop. |
|
|
\item [\textit{y}]\ \\ |
|
|
Vertical position of the window, relative to the upper left corner of |
|
|
the desktop. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function changes the position of an opened window. It does not have |
|
|
any effect on a fullscreen window. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
This function has no effect if the window is iconified. |
|
|
|
|
|
The behaviour of this function on multi-monitor systems is ill-defined. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetWindowSize} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwGetWindowSize(int* width, int* height) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{width}]\ \\ |
|
|
Pointer to an integer that will hold the width of the window. |
|
|
\item [\textit{height}]\ \\ |
|
|
Pointer to an integer that will hold the height of the window. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The current width and height of the opened window is returned in the |
|
|
\textit{width} and \textit{height} parameters, respectively. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function is used for determining the size of an opened window. |
|
|
The returned values are dimensions of the client area of the window |
|
|
(i.e. excluding any window borders and decorations). |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Even if the size of a fullscreen window does not change once the window |
|
|
has been opened, it does not necessarily have to be the same as the size |
|
|
that was requested using \textbf{glfwOpenWindow}. Therefor it is wise to |
|
|
use this function to determine the true size of the window once it has |
|
|
been opened. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetWindowSizeCallback} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetWindowSizeCallback(GLFWwindowsizefun cbfun) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{cbfun}]\ \\ |
|
|
Pointer to a callback function that will be called every time the |
|
|
window size changes. The function should have the following C language |
|
|
prototype: |
|
|
|
|
|
\texttt{void functionname(int width, int height);} |
|
|
|
|
|
Where \textit{functionname} is the name of the callback function, and |
|
|
\textit{width} and \textit{height} are the dimensions of the window |
|
|
client area. |
|
|
|
|
|
If \textit{cbfun} is NULL, any previously set callback function |
|
|
will be unset. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the callback for window size change events. |
|
|
|
|
|
A window has to be opened for this function to have any effect. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Window size changes are recorded continuously, but only reported when |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called. |
|
|
|
|
|
When a callback function is set, it will be called with the current window |
|
|
size before this function returns. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwIconifyWindow} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwIconifyWindow(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
Iconify a window. If the window is in fullscreen mode, then the desktop |
|
|
video mode will be restored. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwRestoreWindow} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwRestoreWindow(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
Restore an iconified window. If the window that is restored is in |
|
|
fullscreen mode, then the fullscreen video mode will be restored. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\begin{table}[p] |
|
|
\begin{center} |
|
|
\begin{tabular}{|l|p{9.5cm}|} \hline \raggedright |
|
|
\textbf{Name} & \textbf{Description} \\ \hline |
|
|
GLFW\_OPENED & GL\_TRUE if window is opened, else GL\_FALSE.\\ \hline |
|
|
GLFW\_ACTIVE & GL\_TRUE if window has focus, else GL\_FALSE.\\ \hline |
|
|
GLFW\_ICONIFIED & GL\_TRUE if window is iconified, else GL\_FALSE.\\ \hline |
|
|
GLFW\_ACCELERATED & GL\_TRUE if window is hardware accelerated, else GL\_FALSE.\\ \hline |
|
|
GLFW\_RED\_BITS & Number of bits for the red color component.\\ \hline |
|
|
GLFW\_GREEN\_BITS & Number of bits for the green color component.\\ \hline |
|
|
GLFW\_BLUE\_BITS & Number of bits for the blue color component.\\ \hline |
|
|
GLFW\_ALPHA\_BITS & Number of bits for the alpha buffer.\\ \hline |
|
|
GLFW\_DEPTH\_BITS & Number of bits for the depth buffer.\\ \hline |
|
|
GLFW\_STENCIL\_BITS & Number of bits for the stencil buffer.\\ \hline |
|
|
GLFW\_REFRESH\_RATE & Vertical monitor refresh rate in Hz. Zero indicates an unknown or a default refresh rate.\\ \hline |
|
|
GLFW\_ACCUM\_RED\_BITS & Number of bits for the red channel of the accumulation buffer.\\ \hline |
|
|
GLFW\_ACCUM\_GREEN\_BITS & Number of bits for the green channel of the accumulation buffer.\\ \hline |
|
|
GLFW\_ACCUM\_BLUE\_BITS & Number of bits for the blue channel of the accumulation buffer.\\ \hline |
|
|
GLFW\_ACCUM\_ALPHA\_BITS & Number of bits for the alpha channel of the accumulation buffer.\\ \hline |
|
|
GLFW\_AUX\_BUFFERS & Number of auxiliary buffers.\\ \hline |
|
|
GLFW\_STEREO & GL\_TRUE if stereo rendering is supported, else GL\_FALSE.\\ \hline |
|
|
GLFW\_WINDOW\_NO\_RESIZE & GL\_TRUE if the window cannot be resized by the user, else GL\_FALSE.\\ \hline |
|
|
GLFW\_FSAA\_SAMPLES & Number of multisampling buffer samples. Zero indicated multisampling is disabled.\\ \hline |
|
|
GLFW\_OPENGL\_VERSION\_MAJOR & Major number of the actual version of the context.\\ \hline |
|
|
GLFW\_OPENGL\_VERSION\_MINOR & Minor number of the actual version of the context.\\ \hline |
|
|
GLFW\_OPENGL\_FORWARD\_COMPAT & GL\_TRUE if the context is forward-compatible, else GL\_FALSE.\\ \hline |
|
|
GLFW\_OPENGL\_DEBUG\_CONTEXT & GL\_TRUE if the context is a debug context.\\ \hline |
|
|
GLFW\_OPENGL\_PROFILE & The profile implemented by the context, or zero.\\ \hline |
|
|
\end{tabular} |
|
|
\end{center} |
|
|
\caption{Window parameters for \textbf{glfwGetWindowParam}} |
|
|
\label{tab:winparams} |
|
|
\end{table} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetWindowParam} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwGetWindowParam(int param) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{param}]\ \\ |
|
|
A token selecting which parameter the function should return (see |
|
|
table \ref{tab:winparams}). |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the value the window parameter corresponding to the token |
|
|
\textit{param}. Table \ref{tab:winparams} lists the available tokens. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function is used for acquiring various properties of an opened window. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
GLFW\_ACCELERATED is only supported under Windows. Other systems will |
|
|
always return GL\_TRUE. Under Windows, GLFW\_ACCELERATED means that the |
|
|
\OpenGL\ renderer is a 3rd party renderer, rather than the fallback |
|
|
Microsoft software \OpenGL\ renderer. In other words, it is not a real |
|
|
guarantee that the \OpenGL\ renderer is actually hardware accelerated. |
|
|
|
|
|
GLFW\_OPENGL\_VERSION\_MAJOR and GLFW\_OPENGL\_VERSION\_MINOR always return the |
|
|
same values as those returned by \textbf{glfwGetGLVersion}. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSwapBuffers} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSwapBuffers(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function swaps the back and front color buffers of the window. If |
|
|
GLFW\_AUTO\_POLL\_EVENTS is enabled (which is the default), |
|
|
\textbf{glfwPollEvents} is called after swapping the front and back |
|
|
buffers. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
In previous versions of \GLFW , \textbf{glfwPollEvents} was called |
|
|
\emph{before} buffer swap. This was changed in order to decrease input |
|
|
lag but may affect code that relied on the former behavior. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSwapInterval} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSwapInterval(int interval) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{interval}]\ \\ |
|
|
Minimum number of monitor vertical retraces between each buffer swap |
|
|
performed by \textbf{glfwSwapBuffers}. If \textit{interval} is zero, |
|
|
buffer swaps will not be synchronized to the vertical refresh of the |
|
|
monitor (also known as 'VSync off'). |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function selects the minimum number of monitor vertical retraces that |
|
|
should occur between two buffer swaps. If the selected swap interval is |
|
|
one, the rate of buffer swaps will never be higher than the vertical |
|
|
refresh rate of the monitor. If the selected swap interval is zero, the |
|
|
rate of buffer swaps is only limited by the speed of the software and |
|
|
the hardware. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
This function will only have an effect on hardware and drivers that support |
|
|
user selection of the swap interval. ATI drivers in particular have been known |
|
|
to ignore this setting. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetWindowRefreshCallback} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetWindowRefreshCallback(GLFWwindowrefreshfun cbfun) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{cbfun}]\ \\ |
|
|
Pointer to a callback function that will be called when the window client |
|
|
area needs to be refreshed. The function should have the following C |
|
|
language prototype: |
|
|
|
|
|
\texttt{void functionname(void);} |
|
|
|
|
|
Where \textit{functionname} is the name of the callback function. |
|
|
|
|
|
If \textit{cbfun} is NULL, any previously set callback function |
|
|
will be unset. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the callback for window refresh events, which occurs when |
|
|
any part of the window client area has been damaged, and needs to be repainted |
|
|
(for instance, if a part of the window that was previously occluded by another |
|
|
window has become visible). |
|
|
|
|
|
A window has to be opened for this function to have any effect. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Window refresh events are recorded continuously, but only reported when |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called. |
|
|
|
|
|
Modern windowing systems using hardware compositing, such as Aqua, Aero and |
|
|
Compiz, very rarely need to refresh the contents of windows, so the specified |
|
|
callback will very rarely be called on such systems. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\pagebreak |
|
|
\section{Video Modes} |
|
|
Since \GLFW\ supports video mode changes when using a fullscreen window, |
|
|
it also provides functionality for querying which video modes are |
|
|
supported on a system. |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetVideoModes} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwGetVideoModes(GLFWvidmode* list, int maxcount) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{list}]\ \\ |
|
|
A vector of \textit{GLFWvidmode} structures, which will be filled out |
|
|
by the function. |
|
|
\item [\textit{maxcount}]\ \\ |
|
|
Maximum number of video modes that \textit{list} vector can hold. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the number of detected video modes (this number |
|
|
will never exceed \textit{maxcount}). The \textit{list} vector is |
|
|
filled out with the video modes that are supported by the system. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function returns a list of supported video modes. Each video mode is |
|
|
represented by a \textit{GLFWvidmode} structure, which has the following |
|
|
definition: |
|
|
|
|
|
\begin{lstlisting} |
|
|
typedef struct { |
|
|
int Width, Height; // Video resolution |
|
|
int RedBits; // Number of red bits |
|
|
int GreenBits; // Number of green bits |
|
|
int BlueBits; // Number of blue bits |
|
|
} GLFWvidmode; |
|
|
\end{lstlisting} |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
The returned list is sorted, first by color depth ($RedBits + GreenBits + |
|
|
BlueBits$), and then by resolution ($Width \times Height$), with the |
|
|
lowest resolution, fewest bits per pixel mode first. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetDesktopMode} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwGetDesktopMode(GLFWvidmode* mode) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{mode}]\ \\ |
|
|
Pointer to a \textit{GLFWvidmode} structure, which will be filled out |
|
|
by the function. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The \textit{GLFWvidmode} structure pointed to by \textit{mode} is filled |
|
|
out with the desktop video mode. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function returns the desktop video mode in a \textit{GLFWvidmode} |
|
|
structure. See \textbf{glfwGetVideoModes} for a definition of the |
|
|
\textit{GLFWvidmode} structure. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
The color depth of the desktop display is always reported as the number |
|
|
of bits for each individual color component (red, green and blue), even |
|
|
if the desktop is not using an RGB or RGBA color format. For instance, an |
|
|
indexed 256 color display may report \textit{RedBits} = 3, |
|
|
\textit{GreenBits} = 3 and \textit{BlueBits} = 2, which adds up to 8 bits |
|
|
in total. |
|
|
|
|
|
The desktop video mode is the video mode used by the desktop at the time |
|
|
the \GLFW\ window was opened, \textit{not} the current video mode (which |
|
|
may differ from the desktop video mode if the \GLFW\ window is a |
|
|
fullscreen window). |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\pagebreak |
|
|
\section{Input Handling} |
|
|
\GLFW\ supports three channels of user input: keyboard input, mouse input |
|
|
and joystick input. |
|
|
|
|
|
Keyboard and mouse input can be treated either as events, using callback |
|
|
functions, or as state, using functions for polling specific keyboard and |
|
|
mouse states. Regardless of which method is used, all keyboard and mouse |
|
|
input is collected using window event polling. |
|
|
|
|
|
Joystick input is asynchronous to the keyboard and mouse input, and does |
|
|
not require event polling for keeping up to date joystick information. |
|
|
Also, joystick input is independent of any window, so a window does not |
|
|
have to be opened for joystick input to be used. |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwPollEvents} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwPollEvents(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function is used for polling for events, such as user input and |
|
|
window resize events. Upon calling this function, all window states, |
|
|
keyboard states and mouse states are updated. If any related callback |
|
|
functions are registered, these are called during the call to |
|
|
\textbf{glfwPollEvents}. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
\textbf{glfwPollEvents} is called implicitly from \textbf{glfwSwapBuffers} |
|
|
if GLFW\_AUTO\_POLL\_EVENTS is enabled (as it is by default). Thus, if |
|
|
\textbf{glfwSwapBuffers} is called frequently, which is normally the case, |
|
|
there is no need to call \textbf{glfwPollEvents}. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwWaitEvents} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwWaitEvents(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function is used for waiting for events, such as user input and |
|
|
window resize events. Upon calling this function, the calling thread will |
|
|
be put to sleep until any event appears in the event queue. When events |
|
|
are available, they will be processed just as they are processed by |
|
|
\textbf{glfwPollEvents}. |
|
|
|
|
|
If there are any events in the queue when the function is called, the |
|
|
function will behave exactly like \textbf{glfwPollEvents} (i.e. process |
|
|
all messages and then return, without blocking the calling thread). |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
It is guaranteed that \textbf{glfwWaitEvents} will wake up on any event that |
|
|
can be processed by \textbf{glfwPollEvents}. However, \GLFW\ receives many |
|
|
events that are only processed internally and the function may behave |
|
|
differently on different systems. Do not make any assumptions about when or why |
|
|
\textbf{glfwWaitEvents} will return. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\begin{table}[p] |
|
|
\begin{center} |
|
|
\begin{tabular}{|l|l|} \hline \raggedright |
|
|
\textbf{Name} & \textbf{Description} \\ \hline |
|
|
GLFW\_KEY\_SPACE & Space\\ \hline |
|
|
GLFW\_KEY\_ESC & Escape\\ \hline |
|
|
GLFW\_KEY\_F\textit{n} & Function key \textit{n} (\textit{n} can be in the range 1..25)\\ \hline |
|
|
GLFW\_KEY\_UP & Cursor up\\ \hline |
|
|
GLFW\_KEY\_DOWN & Cursor down\\ \hline |
|
|
GLFW\_KEY\_LEFT & Cursor left\\ \hline |
|
|
GLFW\_KEY\_RIGHT & Cursor right\\ \hline |
|
|
GLFW\_KEY\_LSHIFT & Left shift key\\ \hline |
|
|
GLFW\_KEY\_RSHIFT & Right shift key\\ \hline |
|
|
GLFW\_KEY\_LCTRL & Left control key\\ \hline |
|
|
GLFW\_KEY\_RCTRL & Right control key\\ \hline |
|
|
GLFW\_KEY\_LALT & Left alternate function key\\ \hline |
|
|
GLFW\_KEY\_RALT & Right alternate function key\\ \hline |
|
|
GLFW\_KEY\_LSUPER & Left super key, WinKey, or command key\\ \hline |
|
|
GLFW\_KEY\_RSUPER & Right super key, WinKey, or command key\\ \hline |
|
|
GLFW\_KEY\_TAB & Tabulator\\ \hline |
|
|
GLFW\_KEY\_ENTER & Enter\\ \hline |
|
|
GLFW\_KEY\_BACKSPACE & Backspace\\ \hline |
|
|
GLFW\_KEY\_INSERT & Insert\\ \hline |
|
|
GLFW\_KEY\_DEL & Delete\\ \hline |
|
|
GLFW\_KEY\_PAGEUP & Page up\\ \hline |
|
|
GLFW\_KEY\_PAGEDOWN & Page down\\ \hline |
|
|
GLFW\_KEY\_HOME & Home\\ \hline |
|
|
GLFW\_KEY\_END & End\\ \hline |
|
|
GLFW\_KEY\_KP\_\textit{n} & Keypad numeric key \textit{n} (\textit{n} can be in the range 0..9)\\ \hline |
|
|
GLFW\_KEY\_KP\_DIVIDE & Keypad divide ($\div$)\\ \hline |
|
|
GLFW\_KEY\_KP\_MULTIPLY & Keypad multiply ($\times$)\\ \hline |
|
|
GLFW\_KEY\_KP\_SUBTRACT & Keypad subtract ($-$)\\ \hline |
|
|
GLFW\_KEY\_KP\_ADD & Keypad add ($+$)\\ \hline |
|
|
GLFW\_KEY\_KP\_DECIMAL & Keypad decimal (. or ,)\\ \hline |
|
|
GLFW\_KEY\_KP\_EQUAL & Keypad equal (=)\\ \hline |
|
|
GLFW\_KEY\_KP\_ENTER & Keypad enter\\ \hline |
|
|
GLFW\_KEY\_KP\_NUM\_LOCK & Keypad num lock\\ \hline |
|
|
GLFW\_KEY\_CAPS\_LOCK & Caps lock\\ \hline |
|
|
GLFW\_KEY\_SCROLL\_LOCK & Scroll lock\\ \hline |
|
|
GLFW\_KEY\_PAUSE & Pause key\\ \hline |
|
|
GLFW\_KEY\_MENU & Menu key\\ \hline |
|
|
\end{tabular} |
|
|
\end{center} |
|
|
\caption{Special key identifiers} |
|
|
\label{tab:keys} |
|
|
\end{table} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\begin{table}[p] |
|
|
\begin{center} |
|
|
\begin{tabular}{|l|l|} \hline \raggedright |
|
|
\textbf{Name} & \textbf{Description} \\ \hline |
|
|
GLFW\_MOUSE\_BUTTON\_LEFT & Left mouse button (button 1) \\ \hline |
|
|
GLFW\_MOUSE\_BUTTON\_RIGHT & Right mouse button (button 2) \\ \hline |
|
|
GLFW\_MOUSE\_BUTTON\_MIDDLE & Middle mouse button (button 3) \\ \hline |
|
|
GLFW\_MOUSE\_BUTTON\_\textit{n} & Mouse button \textit{n} (\textit{n} can be in the range 1..8)\\ \hline |
|
|
\end{tabular} |
|
|
\end{center} |
|
|
\caption{Valid mouse button identifiers} |
|
|
\label{tab:mousebuttons} |
|
|
\end{table} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetKey} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwGetKey(int key) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{key}]\ \\ |
|
|
A keyboard key identifier, which can be either an uppercase printable |
|
|
ISO~8859-1 (Latin~1) character (e.g. 'A', '3' or '.'), or a special key |
|
|
identifier. Table \ref{tab:keys} lists valid special key identifiers. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns GLFW\_PRESS if the key is held down, or GLFW\_RELEASE |
|
|
if the key is not held down. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function queries the current state of a specific keyboard key. The |
|
|
physical location of each key depends on the system keyboard layout |
|
|
setting. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
The constant GLFW\_KEY\_SPACE is equal to 32, which is the ISO~8859-1 code |
|
|
for space. This is the only named \GLFW\ key identifier with a value in the |
|
|
ISO~8859-1 range. |
|
|
|
|
|
Not all key codes are supported on all systems. Also, while some keys are |
|
|
available on some keyboard layouts, they may not be available on other |
|
|
keyboard layouts. |
|
|
|
|
|
For systems that do not distinguish between left and right versions of |
|
|
modifier keys (shift, alt and control), the left version is used (e.g. |
|
|
GLFW\_KEY\_LSHIFT). |
|
|
|
|
|
A window must be opened for the function to have any effect, and |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) must be called before any keyboard |
|
|
events are recorded and reported by \textbf{glfwGetKey}. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetMouseButton} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwGetMouseButton(int button) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{button}]\ \\ |
|
|
A mouse button identifier, which can be one of the mouse button |
|
|
identifiers listed in table \ref{tab:mousebuttons}. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns GLFW\_PRESS if the mouse button is held down, or |
|
|
GLFW\_RELEASE if the mouse button is not held down. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function queries the current state of a specific mouse button. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
A window must be opened for the function to have any effect, and |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) must be called before any mouse button |
|
|
events are recorded and reported by \textbf{glfwGetMouseButton}. |
|
|
|
|
|
GLFW\_MOUSE\_BUTTON\_LEFT is equal to GLFW\_MOUSE\_BUTTON\_1. |
|
|
GLFW\_MOUSE\_BUTTON\_RIGHT is equal to GLFW\_MOUSE\_BUTTON\_2. |
|
|
GLFW\_MOUSE\_BUTTON\_MIDDLE is equal to GLFW\_MOUSE\_BUTTON\_3. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetMousePos} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwGetMousePos(int* xpos, int* ypos) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{xpos}]\ \\ |
|
|
Pointer to an integer that will be set to the horizontal position of the |
|
|
mouse cursor. |
|
|
\item [\textit{ypos}]\ \\ |
|
|
Pointer to an integer that will be set to the vertical position of the mouse cursor. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the current mouse cursor position in \textit{xpos} and |
|
|
\textit{ypos}. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function returns the current mouse position. If the cursor is not |
|
|
hidden, the mouse position is the cursor position, relative to the upper |
|
|
left corner of the window and with the Y-axis down. If the cursor is hidden, |
|
|
the mouse position is a virtual absolute position, not limited to any |
|
|
boundaries except to those implied by the maximum number that can be |
|
|
represented by a signed integer. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
A window must be opened for the function to have any effect, and |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) must be called before any mouse |
|
|
movements are recorded and reported by \textbf{glfwGetMousePos}. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetMousePos} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetMousePos(int xpos, int ypos) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{xpos}]\ \\ |
|
|
Horizontal position of the mouse. |
|
|
\item [\textit{ypos}]\ \\ |
|
|
Vertical position of the mouse. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function changes the position of the mouse. If the cursor is visible (not |
|
|
disabled), the cursor will be moved to the specified position, relative to the |
|
|
upper left corner of the window client area and with the Y-axis down. If the |
|
|
cursor is hidden (disabled), only the mouse position that is reported by \GLFW\ |
|
|
is changed. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetMouseWheel} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwGetMouseWheel(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the current mouse wheel position. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function returns the current mouse wheel position. The mouse wheel can |
|
|
be thought of as a third mouse axis, which is available as a separate |
|
|
wheel or up/down stick on some mice. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
A window must be opened for the function to have any effect, and |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) must be called before any mouse wheel |
|
|
movements are recorded and reported by \textbf{glfwGetMouseWheel}. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetMouseWheel} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetMouseWheel(int pos) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{pos}]\ \\ |
|
|
Position of the mouse wheel. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function changes the position of the mouse wheel. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetKeyCallback} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetKeyCallback(GLFWkeyfun cbfun) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{cbfun}]\ \\ |
|
|
Pointer to a callback function that will be called every time a key is |
|
|
pressed or released. The function should have the following C language |
|
|
prototype: |
|
|
|
|
|
\texttt{void functionname(int key, int action);} |
|
|
|
|
|
Where \textit{functionname} is the name of the callback function, |
|
|
\textit{key} is a key identifier, which is an uppercase printable |
|
|
ISO~8859-1 character or a special key identifier (see table |
|
|
\ref{tab:keys}), and \textit{action} is either GLFW\_PRESS or |
|
|
GLFW\_RELEASE. |
|
|
|
|
|
If \textit{cbfun} is NULL, any previously set callback function |
|
|
will be unset. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the callback for keyboard key events. The callback function |
|
|
is called every time the state of a single key is changed (from released to |
|
|
pressed or vice versa). The reported keys are unaffected by any modifiers (such |
|
|
as shift or alt) and each modifier is reported as a separate key. |
|
|
|
|
|
A window has to be opened for this function to have any effect. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Keyboard key events are not intended for text input and many languages |
|
|
will not be able to be input using it. Use Unicode character events for |
|
|
text input instead. |
|
|
|
|
|
Keyboard events are recorded continuously, but only reported when |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetCharCallback} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetCharCallback(GLFWcharfun cbfun) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{cbfun}]\ \\ |
|
|
Pointer to a callback function that will be called every time a |
|
|
printable character is generated by the keyboard. The function should |
|
|
have the following C language prototype: |
|
|
|
|
|
\texttt{void functionname(int character, int action);} |
|
|
|
|
|
Where \textit{functionname} is the name of the callback function, |
|
|
\textit{character} is a Unicode (ISO~10646) character, and |
|
|
\textit{action} is either GLFW\_PRESS or GLFW\_RELEASE. |
|
|
|
|
|
If \textit{cbfun} is NULL, any previously set callback function |
|
|
will be unset. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the callback for keyboard character events. The callback |
|
|
function is called every time a key that results in a printable Unicode |
|
|
character is pressed or released. Characters are affected by modifiers (such |
|
|
as shift or alt). |
|
|
|
|
|
A window has to be opened for this function to have any effect. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Character events are recorded continuously, but only reported when |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called. |
|
|
|
|
|
Control characters such as tab and carriage return are not reported to |
|
|
the character callback function, since they are not part of the Unicode |
|
|
character set. Use the key callback function for such events (see |
|
|
\textbf{glfwSetKeyCallback}). |
|
|
|
|
|
The Unicode character set supports character codes above 255, so never |
|
|
cast a Unicode character to an eight bit data type (e.g. the C language |
|
|
'char' type) without first checking that the character code is less than |
|
|
256. Also note that Unicode character codes 0 to 255 are equal to |
|
|
ISO~8859-1 (Latin~1). |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetMouseButtonCallback} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetMouseButtonCallback(GLFWmousebuttonfun cbfun) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{cbfun}]\ \\ |
|
|
Pointer to a callback function that will be called every time a mouse |
|
|
button is pressed or released. The function should have the following C |
|
|
language prototype: |
|
|
|
|
|
\texttt{void functionname(int button, int action);} |
|
|
|
|
|
Where \textit{functionname} is the name of the callback function, |
|
|
\textit{button} is a mouse button identifier (see table |
|
|
\ref{tab:mousebuttons} on page \pageref{tab:mousebuttons}), and |
|
|
\textit{action} is either GLFW\_PRESS or GLFW\_RELEASE. |
|
|
|
|
|
If \textit{cbfun} is NULL, any previously set callback function |
|
|
will be unset. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the callback for mouse button events. |
|
|
|
|
|
A window has to be opened for this function to have any effect. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Mouse button events are recorded continuously, but only reported when |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called. |
|
|
|
|
|
GLFW\_MOUSE\_BUTTON\_LEFT is equal to GLFW\_MOUSE\_BUTTON\_1. |
|
|
GLFW\_MOUSE\_BUTTON\_RIGHT is equal to GLFW\_MOUSE\_BUTTON\_2. |
|
|
GLFW\_MOUSE\_BUTTON\_MIDDLE is equal to GLFW\_MOUSE\_BUTTON\_3. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetMousePosCallback} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetMousePosCallback(GLFWmouseposfun cbfun) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{cbfun}]\ \\ |
|
|
Pointer to a callback function that will be called every time the mouse |
|
|
is moved. The function should have the following C language prototype: |
|
|
|
|
|
\texttt{void functionname(int x, int y);} |
|
|
|
|
|
Where \textit{functionname} is the name of the callback function, and |
|
|
\textit{x} and \textit{y} are the mouse coordinates (see |
|
|
\textbf{glfwGetMousePos} for more information on mouse coordinates). |
|
|
|
|
|
If \textit{cbfun} is NULL, any previously set callback function |
|
|
will be unset. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the callback for mouse motion events. |
|
|
|
|
|
A window has to be opened for this function to have any effect. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Mouse motion events are recorded continuously, but only reported when |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetMouseWheelCallback} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetMouseWheelCallback(GLFWmousewheelfun cbfun) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{cbfun}]\ \\ |
|
|
Pointer to a callback function that will be called every time the mouse |
|
|
wheel is moved. The function should have the following C language |
|
|
prototype: |
|
|
|
|
|
\texttt{void functionname(int pos);} |
|
|
|
|
|
Where \textit{functionname} is the name of the callback function, and |
|
|
\textit{pos} is the mouse wheel position. |
|
|
|
|
|
If \textit{cbfun} is NULL, any previously set callback function |
|
|
will be unset. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the callback for mouse wheel events. |
|
|
|
|
|
A window has to be opened for this function to have any effect. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
Mouse wheel events are recorded continuously, but only reported when |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled) is called. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\begin{table}[p] |
|
|
\begin{center} |
|
|
\begin{tabular}{|l|l|}\hline \raggedright |
|
|
\textbf{Name} & \textbf{Return value}\\ \hline |
|
|
GLFW\_PRESENT & GL\_TRUE if the joystick is connected, else GL\_FALSE.\\ \hline |
|
|
GLFW\_AXES & Number of axes supported by the joystick.\\ \hline |
|
|
GLFW\_BUTTONS & Number of buttons supported by the joystick.\\ \hline |
|
|
\end{tabular} |
|
|
\end{center} |
|
|
\caption{Joystick parameters for \textbf{glfwGetJoystickParam}} |
|
|
\label{tab:joyparams} |
|
|
\end{table} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetJoystickParam} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwGetJoystickParam(int joy, int param) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{joy}]\ \\ |
|
|
A joystick identifier, which should be GLFW\_JOYSTICK\_\textit{n}, where |
|
|
\textit{n} is in the range 1 to 16. |
|
|
\item [\textit{param}]\ \\ |
|
|
A token selecting which parameter the function should return (see table |
|
|
\ref{tab:joyparams}). |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns different parameters depending on the value of |
|
|
\textit{param}. Table \ref{tab:joyparams} lists valid \textit{param} |
|
|
values, and their corresponding return values. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function is used for acquiring various properties of a joystick. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
The joystick information is updated every time the function is called. |
|
|
|
|
|
No window has to be opened for joystick information to be available. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetJoystickPos} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwGetJoystickPos(int joy, float* pos, int numaxes) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{joy}]\ \\ |
|
|
A joystick identifier, which should be GLFW\_JOYSTICK\_\textit{n}, where |
|
|
\textit{n} is in the range 1 to 16. |
|
|
\item [\textit{pos}]\ \\ |
|
|
An array that will hold the positional values for all requested axes. |
|
|
\item [\textit{numaxes}]\ \\ |
|
|
Specifies how many axes should be returned. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the number of actually returned axes. This is the |
|
|
minimum of \textit{numaxes} and the number of axes supported by the |
|
|
joystick. If the joystick is not supported or connected, the function will |
|
|
return 0 (zero). |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function queries the current position of one or more axes of a |
|
|
joystick. The positional values are returned in an array, where the first |
|
|
element represents the first axis of the joystick (normally the X axis). |
|
|
Each position is in the range -1.0 to 1.0. Where applicable, the positive |
|
|
direction of an axis is right, forward or up, and the negative direction |
|
|
is left, back or down. |
|
|
|
|
|
If \textit{numaxes} exceeds the number of axes supported by the joystick, |
|
|
or if the joystick is not available, the unused elements in the |
|
|
\textit{pos} array will be set to 0.0 (zero). |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
The joystick state is updated every time the function is called, so there |
|
|
is no need to call \textbf{glfwPollEvents} or \textbf{glfwWaitEvents} for |
|
|
joystick state to be updated. |
|
|
|
|
|
Use \textbf{glfwGetJoystickParam} to retrieve joystick capabilities, such |
|
|
as joystick availability and number of supported axes. |
|
|
|
|
|
No window has to be opened for joystick input to be available. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetJoystickButtons} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwGetJoystickButtons(int joy, unsigned char* buttons, |
|
|
int numbuttons) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{joy}]\ \\ |
|
|
A joystick identifier, which should be GLFW\_JOYSTICK\_\textit{n}, where |
|
|
\textit{n} is in the range 1 to 16. |
|
|
\item [\textit{buttons}]\ \\ |
|
|
An array that will hold the button states for all requested buttons. |
|
|
\item [\textit{numbuttons}]\ \\ |
|
|
Specifies how many buttons should be returned. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the number of actually returned buttons. This is the |
|
|
minimum of \textit{numbuttons} and the number of buttons supported by the |
|
|
joystick. If the joystick is not supported or connected, the function will |
|
|
return 0 (zero). |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function queries the current state of one or more buttons of a |
|
|
joystick. The button states are returned in an array, where the first |
|
|
element represents the first button of the joystick. Each state can be |
|
|
either GLFW\_PRESS or GLFW\_RELEASE. |
|
|
|
|
|
If \textit{numbuttons} exceeds the number of buttons supported by the |
|
|
joystick, or if the joystick is not available, the unused elements in the |
|
|
\textit{buttons} array will be set to GLFW\_RELEASE. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
The joystick state is updated every time the function is called, so there |
|
|
is no need to call \textbf{glfwPollEvents} or \textbf{glfwWaitEvents} for |
|
|
joystick state to be updated. |
|
|
|
|
|
Use \textbf{glfwGetJoystickParam} to retrieve joystick capabilities, such |
|
|
as joystick availability and number of supported buttons. |
|
|
|
|
|
No window has to be opened for joystick input to be available. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\pagebreak |
|
|
\section{Timing} |
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetTime} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
double glfwGetTime(void) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
none |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the value of the high precision timer. The time is |
|
|
measured in seconds, and is returned as a double precision floating point |
|
|
value. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function returns the state of a high precision timer. Unless the timer |
|
|
has been set by the \textbf{glfwSetTime} function, the time is measured as |
|
|
the number of seconds that have passed since \textbf{glfwInit} was called. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
The resolution of the timer depends on which system the program is running |
|
|
on. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwSetTime} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwSetTime(double time) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{time}]\ \\ |
|
|
Time (in seconds) that the timer should be set to. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function sets the current time of the high precision timer to the |
|
|
specified time. Subsequent calls to \textbf{glfwGetTime} will be relative |
|
|
to this time. The time is given in seconds. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\pagebreak |
|
|
\section{OpenGL Extension Support} |
|
|
One of the great features of \OpenGL\ is its support for extensions, which |
|
|
allow independent vendors to supply non-standard functionality in their |
|
|
\OpenGL\ implementations. As the mechanism for querying extensions varies |
|
|
among systems, \GLFW\ provides an operating system independent interface for |
|
|
querying \OpenGL\ version, extensions and entry points. |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwExtensionSupported} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
int glfwExtensionSupported(const char* extension) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{extension}]\ \\ |
|
|
A null terminated ISO~8859-1 string containing the name of an \OpenGL\ |
|
|
extension. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns GL\_TRUE if the extension is supported. Otherwise it |
|
|
returns GL\_FALSE. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function does a string search in the list of supported \OpenGL\ |
|
|
extensions to find if the specified extension is listed. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
An \OpenGL\ context must be created before this function can be called |
|
|
(i.e. an \OpenGL\ window must have been opened with |
|
|
\textbf{glfwOpenWindow}). |
|
|
|
|
|
In addition to checking for \OpenGL\ extensions, \GLFW\ also checks for |
|
|
extensions in the operating system ``glue API'', such as WGL extensions |
|
|
under Microsoft Windows and GLX extensions under the X Window System. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetProcAddress} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void* glfwGetProcAddress(const char* procname) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{procname}]\ \\ |
|
|
A null terminated ISO~8859-1 string containing the name of an \OpenGL\ |
|
|
extension function. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the address of the specified \OpenGL\ function, if it |
|
|
is available. Otherwise NULL is returned. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function acquires the pointer to an \OpenGL\ extension function. Some |
|
|
(but not all) \OpenGL\ extensions define new API functions, which are |
|
|
usually not available through normal linking. It is therefore necessary to |
|
|
get access to those API functions at runtime. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
An \OpenGL\ context must be created before this function can be called |
|
|
(i.e. an \OpenGL\ window must have been opened with |
|
|
\textbf{glfwOpenWindow}). |
|
|
|
|
|
Some systems do not support dynamic function pointer retrieval, in which |
|
|
case \textbf{glfwGetProcAddress} will always return NULL. |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwGetGLVersion} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwGetGLVersion(int* major, int* minor, int* rev) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{major}]\ \\ |
|
|
Pointer to an integer that will hold the major version number. |
|
|
\item [\textit{minor}]\ \\ |
|
|
Pointer to an integer that will hold the minor version number. |
|
|
\item [\textit{rev}]\ \\ |
|
|
Pointer to an integer that will hold the revision. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
The function returns the major and minor version numbers and the revision |
|
|
for the currently used \OpenGL\ implementation. |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
This function returns the \OpenGL\ implementation version. This is a |
|
|
convenient function that parses the version number information at the beginning |
|
|
of the string returned by calling \texttt{glGetString(~GL\_VERSION~)}. The |
|
|
\OpenGL\ version information can be used to determine what functionality is |
|
|
supported by the used \OpenGL\ implementation. |
|
|
\end{refdescription} |
|
|
|
|
|
\begin{refnotes} |
|
|
An \OpenGL\ context must be created before this function can be called |
|
|
(i.e. an \OpenGL\ window must have been opened with |
|
|
\textbf{glfwOpenWindow}). |
|
|
\end{refnotes} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\pagebreak |
|
|
\section{Miscellaneous} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\subsection{glfwEnable/glfwDisable} |
|
|
|
|
|
\textbf{C language syntax} |
|
|
\begin{lstlisting} |
|
|
void glfwEnable(int token) |
|
|
void glfwDisable(int token) |
|
|
\end{lstlisting} |
|
|
|
|
|
\begin{refparameters} |
|
|
\begin{description} |
|
|
\item [\textit{token}]\ \\ |
|
|
A value specifying a feature to enable or disable. Valid tokens are |
|
|
listed in table \ref{tab:enable}. |
|
|
\end{description} |
|
|
\end{refparameters} |
|
|
|
|
|
\begin{refreturn} |
|
|
none |
|
|
\end{refreturn} |
|
|
|
|
|
\begin{refdescription} |
|
|
\textbf{glfwEnable} is used to enable a certain feature, while |
|
|
\textbf{glfwDisable} is used to disable it. Below follows a description of |
|
|
each feature. |
|
|
\end{refdescription} |
|
|
|
|
|
|
|
|
\begin{table}[p] |
|
|
\begin{center} |
|
|
\begin{tabular}{|l|p{5.0cm}|p{3.0cm}|} \hline \raggedright |
|
|
\textbf{Name} & \textbf{Controls} & \textbf{Default}\\ \hline |
|
|
\hyperlink{lnk:autopollevents}{GLFW\_AUTO\_POLL\_EVENTS} & Automatic event polling when \textbf{glfwSwapBuffers} is called & Enabled\\ \hline |
|
|
\hyperlink{lnk:keyrepeat}{GLFW\_KEY\_REPEAT} & Keyboard key repeat & Disabled\\ \hline |
|
|
\hyperlink{lnk:mousecursor}{GLFW\_MOUSE\_CURSOR} & Mouse cursor visibility & Enabled in windowed mode. Disabled in fullscreen mode.\\ \hline |
|
|
\hyperlink{lnk:stickykeys}{GLFW\_STICKY\_KEYS} & Keyboard key ``stickiness'' & Disabled\\ \hline |
|
|
\hyperlink{lnk:stickymousebuttons}{GLFW\_STICKY\_MOUSE\_BUTTONS} & Mouse button ``stickiness'' & Disabled\\ \hline |
|
|
\hyperlink{lnk:systemkeys}{GLFW\_SYSTEM\_KEYS} & Special system key actions & Enabled\\ \hline |
|
|
\end{tabular} |
|
|
\end{center} |
|
|
\caption{Tokens for \textbf{glfwEnable}/\textbf{glfwDisable}} |
|
|
\label{tab:enable} |
|
|
\end{table} |
|
|
|
|
|
|
|
|
\bigskip\begin{mysamepage}\hypertarget{lnk:autopollevents}{} |
|
|
\textbf{GLFW\_AUTO\_POLL\_EVENTS}\\ |
|
|
When GLFW\_AUTO\_POLL\_EVENTS is enabled, \textbf{glfwPollEvents} is |
|
|
automatically called each time that \textbf{glfwSwapBuffers} is called, |
|
|
immediately after the buffer swap itself. |
|
|
|
|
|
When GLFW\_AUTO\_POLL\_EVENTS is disabled, calling |
|
|
\textbf{glfwSwapBuffers} will not result in a call to |
|
|
\textbf{glfwPollEvents}. This can be useful if for example \textbf{glfwSwapBuffers} |
|
|
needs to be called from within a callback function, since calling |
|
|
\textbf{glfwPollEvents} from a callback function is not allowed. |
|
|
\end{mysamepage} |
|
|
|
|
|
|
|
|
\bigskip\begin{mysamepage}\hypertarget{lnk:keyrepeat}{} |
|
|
\textbf{GLFW\_KEY\_REPEAT}\\ |
|
|
When GLFW\_KEY\_REPEAT is enabled, the key and character callback |
|
|
functions are called repeatedly when a key is held down long enough |
|
|
(according to the system key repeat configuration). |
|
|
|
|
|
When GLFW\_KEY\_REPEAT is disabled, the key and character callback |
|
|
functions are only called once when a key is pressed (and once when it is |
|
|
released). |
|
|
\end{mysamepage} |
|
|
|
|
|
|
|
|
\bigskip\begin{mysamepage}\hypertarget{lnk:mousecursor}{} |
|
|
\textbf{GLFW\_MOUSE\_CURSOR}\\ |
|
|
When GLFW\_MOUSE\_CURSOR is enabled, the mouse cursor is visible, and |
|
|
mouse coordinates are relative to the upper left corner of the client area |
|
|
of the \GLFW\ window. The coordinates are limited to the client area of |
|
|
the window. |
|
|
|
|
|
When GLFW\_MOUSE\_CURSOR is disabled, the mouse cursor is invisible, and |
|
|
mouse coordinates are not limited to the drawing area of the window. It is |
|
|
as if the mouse coordinates are received directly from the mouse, without |
|
|
being restricted or manipulated by the windowing system. |
|
|
\end{mysamepage} |
|
|
|
|
|
|
|
|
\bigskip\begin{mysamepage}\hypertarget{lnk:stickykeys}{} |
|
|
\textbf{GLFW\_STICKY\_KEYS}\\ |
|
|
When GLFW\_STICKY\_KEYS is enabled, keys which are pressed will not be |
|
|
released until they are physically released and checked with |
|
|
\textbf{glfwGetKey}. This behavior makes it possible to catch keys that |
|
|
were pressed and then released again between two calls to |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or |
|
|
\textbf{glfwSwapBuffers}, which would otherwise have been reported as |
|
|
released. Care should be taken when using this mode, since keys that are |
|
|
not checked with \textbf{glfwGetKey} will never be released. Note also |
|
|
that enabling GLFW\_STICKY\_KEYS does not affect the behavior of the |
|
|
keyboard callback functionality. |
|
|
|
|
|
When GLFW\_STICKY\_KEYS is disabled, the status of a key that is reported |
|
|
by \textbf{glfwGetKey} is always the physical state of the key. Disabling |
|
|
GLFW\_STICKY\_KEYS also clears the sticky information for all keys. |
|
|
\end{mysamepage} |
|
|
|
|
|
|
|
|
\bigskip\begin{mysamepage}\hypertarget{lnk:stickymousebuttons}{} |
|
|
\textbf{GLFW\_STICKY\_MOUSE\_BUTTONS}\\ |
|
|
When GLFW\_STICKY\_MOUSE\_BUTTONS is enabled, mouse buttons that are pressed |
|
|
will not be released until they are physically released and checked with |
|
|
\textbf{glfwGetMouseButton}. This behavior makes it possible to catch mouse |
|
|
buttons which were pressed and then released again between two calls to |
|
|
\textbf{glfwPollEvents}, \textbf{glfwWaitEvents} or \textbf{glfwSwapBuffers} |
|
|
(with GLFW\_AUTO\_POLL\_EVENTS enabled), which would otherwise have been |
|
|
reported as released. Care should be taken when using this mode, since mouse |
|
|
buttons that are not checked with \textbf{glfwGetMouseButton} will never be |
|
|
released. Note also that enabling GLFW\_STICKY\_MOUSE\_BUTTONS does not affect |
|
|
the behavior of the mouse button callback functionality. |
|
|
|
|
|
When GLFW\_STICKY\_MOUSE\_BUTTONS is disabled, the status of a mouse |
|
|
button that is reported by \textbf{glfwGetMouseButton} is always the |
|
|
physical state of the mouse button. Disabling GLFW\_STICKY\_MOUSE\_BUTTONS |
|
|
also clears the sticky information for all mouse buttons. |
|
|
\end{mysamepage} |
|
|
|
|
|
|
|
|
\bigskip\begin{mysamepage}\hypertarget{lnk:systemkeys}{} |
|
|
\textbf{GLFW\_SYSTEM\_KEYS}\\ |
|
|
When GLFW\_SYSTEM\_KEYS is enabled, pressing standard system key |
|
|
combinations, such as \texttt{Alt+Tab} under Windows, will give the normal |
|
|
behavior. Note that when \texttt{Alt+Tab} is issued under Windows in this |
|
|
mode so that the \GLFW\ application is deselected when \GLFW\ is operating |
|
|
in fullscreen mode, the \GLFW\ application window will be minimized and |
|
|
the video mode will be set to the original desktop mode. When the \GLFW\ |
|
|
application is re-selected, the video mode will be set to the \GLFW\ video |
|
|
mode again. |
|
|
|
|
|
When GLFW\_SYSTEM\_KEYS is disabled, pressing standard system key |
|
|
combinations will have no effect, since those key combinations are blocked |
|
|
by \GLFW . This mode can be useful in situations when the \GLFW\ program |
|
|
must not be interrupted (normally for games in fullscreen mode). |
|
|
\end{mysamepage} |
|
|
|
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
% GLFW Standards Conformance |
|
|
%------------------------------------------------------------------------- |
|
|
\appendix |
|
|
\chapter{GLFW Compatibility} |
|
|
\label{chap:compatibility} |
|
|
\thispagestyle{fancy} |
|
|
|
|
|
This chapter describes the various API extensions used by this version of |
|
|
\GLFW . It lists what are essentially implementation details, but which are |
|
|
nonetheless vital knowledge for developers wishing to deploy their applications |
|
|
on machines with varied specifications. |
|
|
|
|
|
Note that the information in this appendix is not a part of the API |
|
|
specification but merely list some of the preconditions for certain parts of |
|
|
the API to function on a given machine. As such, any part of it may change in |
|
|
future versions without this being considered a breaking API change. |
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\section{ICCCM and EWMH Conformance} |
|
|
|
|
|
As \GLFW\ uses \textbf{Xlib}, directly, without any intervening toolkit |
|
|
library, it has sole responsibility for interacting well with the many and |
|
|
varied window managers in use on Unix-like systems. In order for applications |
|
|
and window managers to work well together, a number of standards and |
|
|
conventions have been developed that regulate behavior outside the scope of the |
|
|
X11 API; most importantly the \textbf{Inter-Client Communication Conventions |
|
|
Manual} (ICCCM) and \textbf{Extended Window Manager Hints} (EWMH) standards. |
|
|
|
|
|
\GLFW\ uses the ICCCM \textbf{WM\_DELETE\_WINDOW} protocol to intercept the user |
|
|
attempting to close the \GLFW\ window. If the running window manager does not |
|
|
support this protocol, the close callback will never be called. |
|
|
|
|
|
\GLFW\ uses the EWMH \textbf{\_NET\_WM\_PING} protocol, allowing the window |
|
|
manager notify the user when the application has stopped responding, i.e. when |
|
|
it has ceased to process events. If the running window manager does not |
|
|
support this protocol, the user will not be notified if the application locks |
|
|
up. |
|
|
|
|
|
\GLFW\ uses the EWMH \textbf{\_NET\_WM\_STATE} protocol to tell the window |
|
|
manager to make the \GLFW\ window fullscreen. If the running window manager |
|
|
does not support this protocol, fullscreen windows may not work properly. |
|
|
\GLFW\ has a fallback code path in case this protocol is unavailable, but every |
|
|
window manager behaves slightly differently in this regard. |
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\section{GLX Extensions} |
|
|
|
|
|
The \textbf{GLX} API is used to create \OpenGL\ contexts on Unix-like systems |
|
|
using the X Window System. |
|
|
|
|
|
\GLFW\ uses the \textbf{GLXFBConfig} API to enumerate and select framebuffer |
|
|
pixel formats. This requires either \textbf{GLX} 1.3 or greater, or the |
|
|
\textbf{GLX\_SGIX\_fbconfig} extension. Where both are available, the SGIX |
|
|
extension is preferred. If neither is available, \GLFW\ will be unable to open |
|
|
windows. |
|
|
|
|
|
% This paragraph repeated almost verbatim below |
|
|
\GLFW\ uses the \textbf{GLX\_SGI\_swap\_control} extension to provide vertical |
|
|
retrace synchronization (or ``vsync''). Where this extension is unavailable, |
|
|
calling \textbf{glfwSwapInterval} will have no effect. |
|
|
|
|
|
% This paragraph repeated almost verbatim below |
|
|
\GLFW\ uses the \textbf{GLX\_ARB\_multisample} extension to create contexts |
|
|
with multisampling anti-aliasing. Where this extension is unavailable, the |
|
|
GLFW\_FSAA\_SAMPLES hint will have no effect. |
|
|
|
|
|
% This paragraph repeated almost verbatim below |
|
|
\GLFW\ uses the \textbf{GLX\_ARB\_create\_context} extension when available, |
|
|
even when creating \OpenGL\ contexts of version 2.1 and below. Where this |
|
|
extension is unavailable, the GLFW\_OPENGL\_VERSION\_MAJOR and |
|
|
GLFW\_OPENGL\_VERSION\_MINOR hints will only be partially supported, the |
|
|
GLFW\_OPENGL\_DEBUG\_CONTEXT hint will have no effect, and setting the |
|
|
GLFW\_OPENGL\_PROFILE or GLFW\_FORWARD\_COMPAT hints to a non-zero value will |
|
|
cause \textbf{glfwOpenWindow} to fail. |
|
|
|
|
|
% This paragraph repeated almost verbatim below |
|
|
\GLFW\ uses the \textbf{GLX\_ARB\_create\_context\_profile} extension to |
|
|
provide support for context profiles. Where this extension is unavailable, |
|
|
setting the GLFW\_OPENGL\_PROFILE hint to anything but zero will cause |
|
|
\textbf{glfwOpenWindow} to fail. |
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\section{WGL Extensions} |
|
|
|
|
|
The \textbf{WGL} API is used to create \OpenGL\ contexts on Microsoft Windows |
|
|
and other implementations of the Win32 API, such as Wine. |
|
|
|
|
|
\GLFW\ uses either the \textbf{WGL\_EXT\_extension\_string} or the |
|
|
\textbf{WGL\_ARB\_extension\_string} extension to check for the presence of all |
|
|
other \textbf{WGL} extensions listed below. If both are available, the EXT one |
|
|
is preferred. If neither is available, no other extensions are used and many |
|
|
\GLFW\ features related to context creation will have no effect or cause errors |
|
|
when used. |
|
|
|
|
|
% This paragraph repeated almost verbatim above |
|
|
\GLFW\ uses the \textbf{WGL\_EXT\_swap\_control} extension to provide vertical |
|
|
retrace synchronization (or ``vsync''). Where this extension is unavailable, |
|
|
calling \textbf{glfwSwapInterval} will have no effect. |
|
|
|
|
|
% This paragraph repeated almost verbatim above |
|
|
\GLFW\ uses the \textbf{WGL\_ARB\_pixel\_format} and |
|
|
\textbf{WGL\_ARB\_multisample} extensions to create contexts with multisampling |
|
|
anti-aliasing. Where these extensions are unavailable, the GLFW\_FSAA\_SAMPLES |
|
|
hint will have no effect. |
|
|
|
|
|
% This paragraph repeated almost verbatim above |
|
|
\GLFW\ uses the \textbf{WGL\_ARB\_create\_context} extension when available, |
|
|
even when creating \OpenGL\ contexts of version 2.1 and below. Where this |
|
|
extension is unavailable, the GLFW\_OPENGL\_VERSION\_MAJOR and |
|
|
GLFW\_OPENGL\_VERSION\_MINOR hints will only be partially supported, the |
|
|
GLFW\_OPENGL\_DEBUG\_CONTEXT hint will have no effect, and setting the |
|
|
GLFW\_OPENGL\_PROFILE or GLFW\_FORWARD\_COMPAT hints to a non-zero value will |
|
|
cause \textbf{glfwOpenWindow} to fail. |
|
|
|
|
|
% This paragraph repeated almost verbatim above |
|
|
\GLFW\ uses the \textbf{WGL\_ARB\_create\_context\_profile} extension to |
|
|
provide support for context profiles. Where this extension is unavailable, |
|
|
setting the GLFW\_OPENGL\_PROFILE hint to anything but zero will cause |
|
|
\textbf{glfwOpenWindow} to fail. |
|
|
|
|
|
%------------------------------------------------------------------------- |
|
|
\section{OpenGL 3.0+ on Mac OS X} |
|
|
|
|
|
At the time of writing, Mac OS X does not support OpenGL 3.0 or above. |
|
|
Because of this, the GLFW\_OPENGL\_VERSION\_MAJOR and |
|
|
GLFW\_OPENGL\_VERSION\_MINOR hints will fail if given a version above 2.1, the |
|
|
GLFW\_OPENGL\_DEBUG\_CONTEXT hint will have no effect, and setting the |
|
|
GLFW\_OPENGL\_PROFILE or GLFW\_FORWARD\_COMPAT hints to a non-zero value will |
|
|
cause \textbf{glfwOpenWindow} to fail. |
|
|
|
|
|
|
|
|
\end{document}
|
|
|
|
