diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 6bc7da29..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,57 +0,0 @@ -########################################################################## -# Makefile for the GLFW documentation. -########################################################################## - -PDFDOCS = glfwrm.pdf glfwug.pdf -DVIDOCS = glfwrm.dvi glfwug.dvi - - -########################################################################## -# Build macros -########################################################################## -default: pdf -pdf: $(PDFDOCS) -dvi: $(DVIDOCS) - - -########################################################################## -# Clean macros -########################################################################## -clean: - rm -f glfwrm.dvi glfwrm.aux glfwrm.log glfwrm.out glfwrm.pdf glfwrm.toc glfwrm.lot - rm -f glfwug.dvi glfwug.aux glfwug.log glfwug.out glfwug.pdf glfwug.toc - -clean-win: - @.\\cleanup.bat - - -########################################################################## -# Rules for building the GLFW Reference Manual -########################################################################## - -glfwrm.pdf: glfwrm.tex glfwrm.toc glfwrm.lot glfwdoc.sty - pdflatex glfwrm.tex - -glfwrm.dvi: glfwrm.tex glfwrm.toc glfwrm.lot glfwdoc.sty - latex glfwrm.tex - -glfwrm.toc: glfwrm.tex glfwdoc.sty - latex glfwrm.tex - -glfwrm.lot: glfwrm.tex glfwdoc.sty - latex glfwrm.tex - - -########################################################################## -# Rules for building the GLFW Users Guide -########################################################################## - -glfwug.pdf: glfwug.tex glfwug.toc glfwdoc.sty - pdflatex glfwug.tex - -glfwug.dvi: glfwug.tex glfwug.toc glfwdoc.sty - latex glfwug.tex - -glfwug.toc: glfwug.tex glfwdoc.sty - latex glfwug.tex - diff --git a/docs/cleanup.bat b/docs/cleanup.bat deleted file mode 100644 index 268a27b6..00000000 --- a/docs/cleanup.bat +++ /dev/null @@ -1,22 +0,0 @@ -@echo off - -REM ---------------------------------------------------------------------- -REM Windows cleanup batch file for the GLFW documentation. -REM ---------------------------------------------------------------------- - -REM GLFW Reference Manual -if exist glfwrm.dvi del glfwrm.dvi -if exist glfwrm.aux del glfwrm.aux -if exist glfwrm.log del glfwrm.log -if exist glfwrm.out del glfwrm.out -if exist glfwrm.pdf del glfwrm.pdf -if exist glfwrm.toc del glfwrm.toc -if exist glfwrm.lot del glfwrm.lot - -REM GLFW Users Guide -if exist glfwug.dvi del glfwug.dvi -if exist glfwug.aux del glfwug.aux -if exist glfwug.log del glfwug.log -if exist glfwug.out del glfwug.out -if exist glfwug.pdf del glfwug.pdf -if exist glfwug.toc del glfwug.toc diff --git a/docs/glfwdoc.sty b/docs/glfwdoc.sty deleted file mode 100644 index e415570e..00000000 --- a/docs/glfwdoc.sty +++ /dev/null @@ -1,81 +0,0 @@ -%------------------------------------------------------------------------- -% Common document formatting and macros for GLFW manuals -%------------------------------------------------------------------------- - -% Misc. document info -\date{\today} - -% Packages -\usepackage{fancyhdr} -\usepackage{titling} -\usepackage{lastpage} -\usepackage{listings} -\usepackage{color} -\usepackage[overload]{textcase} -\usepackage{needspace} -\usepackage{times} - -% Logo macros -\newcommand{\OpenGL}[1][0]{OpenGL\textsuperscript{\textregistered}} -\newcommand{\GLFW}[1][0]{GLFW} - -% Encoding -\usepackage[latin1]{inputenc} -\usepackage[T1]{fontenc} - -% Page formatting -\usepackage[hmargin=2.5cm]{geometry} -\raggedright -\raggedbottom -\sloppy -\usepackage{parskip} - -% Header and footer -\pagestyle{fancy} -%\lhead{\textit{GLFW Reference Manual}} -\lhead{\textit{GLFW \glfwdoctype}} -\chead{API version \glfwapiver} -\rhead{Page \thepage/\pageref{LastPage}} -\lfoot{} -\cfoot{} -\rfoot{} -\renewcommand{\headrulewidth}{0.4pt} -\renewcommand{\footrulewidth}{0.0pt} - -% Titlepage -\newcommand{\glfwmaketitle}{\begin{titlepage}\ \\% - \begin{center}% - \vspace{7.0cm}{\Huge\textbf{GLFW}}\\% - \rule{10.0cm}{0.5pt}\\% - \vspace{0.5cm}{\LARGE\textbf{\glfwdoctype}}\\% - \vspace{0.8cm}{\large\textbf{API version \glfwapiver}}\\% - \textit{\today}\\% - \vspace{1.5cm}\textbf{\textcopyright2002-2006 Marcus Geelnard}\\ - \textbf{\textcopyright2006-2010 Camilla Berglund}\\% - \end{center}\end{titlepage}\newpage} - -% Colors -\definecolor{code}{rgb}{0.9,0.9,1.0} -\definecolor{link}{rgb}{0.6,0.0,0.0} -\definecolor{codeA}{rgb}{0.9,1.0,0.9} -\definecolor{codeB}{rgb}{1.0,0.9,0.9} - -% Code listings -\lstset{frame=single,frameround=tttt,backgroundcolor=\color{code},% - language=C,basicstyle={\ttfamily},% - breaklines,breakindent=0pt,postbreak=\space\space\space\space} - - -% A simple hack for keeping lines together -\newenvironment{mysamepage}[1][2]{\begin{samepage}\needspace{#1\baselineskip}}{\end{samepage}} - -% Macros for automating function reference entries -\newenvironment{refparameters}[1][0]{\begin{mysamepage}\textbf{Parameters}\\}{\end{mysamepage}\bigskip} -\newenvironment{refreturn}[1][0]{\begin{mysamepage}\textbf{Return values}\\}{\end{mysamepage}\bigskip} -\newenvironment{refdescription}[1][0]{\begin{mysamepage}\textbf{Description}\\}{\end{mysamepage}\bigskip} -\newenvironment{refnotes}[1][0]{\begin{mysamepage}\textbf{Notes}\\}{\end{mysamepage}\bigskip} - -% hyperref (bookmarks, links etc) - use this package last -\usepackage[colorlinks=true,linkcolor=link,bookmarks=true,bookmarksopen=true,% - pdfhighlight=/N,bookmarksnumbered=true,bookmarksopenlevel=1,% - pdfview=FitH,pdfstartview=FitH]{hyperref} diff --git a/docs/glfwrm.tex b/docs/glfwrm.tex deleted file mode 100644 index 48c80b42..00000000 --- a/docs/glfwrm.tex +++ /dev/null @@ -1,2364 +0,0 @@ -%------------------------------------------------------------------------- -% 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­-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-­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\_\textit{X} & Letter (\textit{X} can be in the range A..Z)\\ \hline -GLFW\_KEY\_\textit{n} & Number (\textit{n} can be in the range 0..9)\\ \hline -GLFW\_KEY\_SPACE & Space\\ \hline -GLFW\_KEY\_MINUS & Minus (-)\\ \hline -GLFW\_KEY\_EQUAL & Equal (=)\\ \hline -GLFW\_KEY\_LEFT\_BRACKET & Left bracket ([)\\ \hline -GLFW\_KEY\_RIGHT\_BRACKET & Right bracket (])\\ \hline -GLFW\_KEY\_GRAVE\_ACCENT & Grave accent (`)\\ \hline -GLFW\_KEY\_APOSTROPHE & Apostrophe (')\\ \hline -GLFW\_KEY\_COMMA & Comma (,)\\ \hline -GLFW\_KEY\_PERIOD & Period (.)\\ \hline -GLFW\_KEY\_SEMICOLON & Semicolon (;)\\ \hline -GLFW\_KEY\_SLASH & Slash ($/$)\\ \hline -GLFW\_KEY\_BACKSLASH & Backslash ($\backslash$)\\ \hline -GLFW\_KEY\_WORLD\_1 & Non-US character no. 1\\ \hline -GLFW\_KEY\_WORLD\_2 & Non-US character no. 2\\ \hline -\end{tabular} -\end{center} -\caption[Key codes for printable keys]{Key codes for printable keys. The keys are named according to the US keyboard layout, but represent physical keys (so for instance, GLFW\_KEY\_Z represents the same physical key, regardless of the system input language).} -\label{tab:keys1} -\end{table} - -\begin{table}[p] -\begin{center} -\begin{tabular}{|l|l|} \hline \raggedright -\textbf{Name} & \textbf{Description} \\ \hline -GLFW\_KEY\_ESCAPE & 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\_LEFT\_SHIFT & Left shift key\\ \hline -GLFW\_KEY\_RIGHT\_SHIFT & Right shift key\\ \hline -GLFW\_KEY\_LEFT\_CTRL & Left control key\\ \hline -GLFW\_KEY\_RIGHT\_CTRL & Right control key\\ \hline -GLFW\_KEY\_LEFT\_ALT & Left alternate function key\\ \hline -GLFW\_KEY\_RIGHT\_ALT & Right alternate function key\\ \hline -GLFW\_KEY\_LEFT\_SUPER & Left super key, WinKey, or command key\\ \hline -GLFW\_KEY\_RIGHT\_SUPER & 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\_DELETE & Delete\\ \hline -GLFW\_KEY\_PAGE\_UP & Page up\\ \hline -GLFW\_KEY\_PAGE\_DOWN & 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\_NUM\_LOCK & 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{Key codes for function keys} -\label{tab:keys2} -\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 any of the key codes in tables - \ref{tab:keys1} and \ref{tab:keys2}. -\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 code (see tables \ref{tab:keys1} and \ref{tab:keys2}), - 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} diff --git a/docs/glfwug.tex b/docs/glfwug.tex deleted file mode 100644 index 4f769a2c..00000000 --- a/docs/glfwug.tex +++ /dev/null @@ -1,1313 +0,0 @@ -%------------------------------------------------------------------------- -% GLFW Users Guide -% API Version: 3.0 -%------------------------------------------------------------------------- - -% Document class -\documentclass[a4paper,11pt,oneside]{report} - -% Document title and API version -\newcommand{\glfwdoctype}[1][0]{Users Guide} -\newcommand{\glfwapiver}[1][0]{3.0} - -% Common document settings and macros -\input{glfwdoc.sty} - -% PDF specific document settings -\hypersetup{pdftitle={GLFW Users Guide}} -\hypersetup{pdfauthor={Marcus Geelnard}} -\hypersetup{pdfkeywords={GLFW,OpenGL,guide,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 a users guide for the \GLFW\ API that gives a practical -introduction to using \GLFW . For a more detailed description of the -\GLFW\ API you should refer to the \textit{GLFW Reference Manual}. -\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 -IBM is a registered trademark of IBM Corporation.\linebreak - -All other trademarks mentioned in this document are the property of their respective owners. -\normalsize - - -%------------------------------------------------------------------------- -% Table of contents -%------------------------------------------------------------------------- -\tableofcontents -\pagebreak - - -% Document chapters starts here... -\pagenumbering{arabic} -\setcounter{page}{1} - -\pagestyle{fancy} - - -%------------------------------------------------------------------------- -% Introduction -%------------------------------------------------------------------------- -\chapter{Introduction} -\thispagestyle{fancy} -\GLFW\ is a portable API (Application Program Interface) that handles -operating system specific tasks related to \OpenGL\ programming. While -\OpenGL\ in general is portable, easy to use and often results in tidy and -compact code, the operating system specific mechanisms that are required -to set up and manage an \OpenGL\ window are quite the opposite. \GLFW\ tries -to remedy this by providing the following functionality: - -\begin{itemize} -\item Opening and managing an \OpenGL\ window. -\item Keyboard, mouse and joystick input. -\item High precision time input. -\item Support for querying and using \OpenGL\ extensions. -\end{itemize} -\vspace{18pt} - -All this functionality is implemented as a set of easy-to-use functions, -which makes it possible to write an \OpenGL\ application framework in just a -few lines of code. The \GLFW\ API is operating system and platform independent, -making it very simple to port \GLFW\ based \OpenGL\ applications between the -supported platforms. - -Currently supported platforms are: -\begin{itemize} -\item Microsoft Windows\textsuperscript{\textregistered} -\item Unix\textsuperscript{\textregistered} or Unix­-like systems running the -X Window System\texttrademark with GLX version 1.3 or later -\item Mac OS X\textsuperscript{\textregistered} 10.5 and later, using Cocoa\footnote{Support for joysticks missing at the time of writing.} -\end{itemize} - -There is also deprecated support for Mac OS X versions 10.3 and 10.4, using the Carbon API. - - -%------------------------------------------------------------------------- -% Getting Started -%------------------------------------------------------------------------- -\chapter{Getting Started} -\thispagestyle{fancy} -In this chapter you will learn how to write a simple \OpenGL\ application -using \GLFW . We start by initializing \GLFW , then we open a window and -read some user keyboard input. - - -%------------------------------------------------------------------------- -\section{Initializing GLFW} -Before using any of the \GLFW\ functions, it is necessary to call -\textbf{glfwInit}. It initializes the parts of \GLFW\ that are not dependent on -a window, such as time and joystick input. The C syntax is: - -\begin{lstlisting} -int glfwInit(void) -\end{lstlisting} - -\textbf{glfwInit} returns GL\_TRUE if initialization succeeded, or -GL\_FALSE if it failed. - -When your application is done using \GLFW , typically at the very end of -the program, you should call \textbf{glfwTerminate}. The C syntax is: - -\begin{lstlisting} -void glfwTerminate(void) -\end{lstlisting} - -This releases any resources allocated by GLFW and closes the window if it is -open. After this call, you must call \textbf{glfwInit} again before using any -\GLFW\ functions). - -%------------------------------------------------------------------------- -\section{Opening An OpenGL Window} -Opening an \OpenGL\ window is done with the \textbf{glfwOpenWindow} function. -The function takes nine arguments, which are used to describe the following -properties of the requested window: - -\begin{itemize} -\item Window dimensions (width and height) in pixels. -\item Color and alpha buffer bit depth. -\item Depth buffer (Z-buffer) bit depth. -\item Stencil buffer bit depth. -\item Whether to use fullscreen or windowed mode. -\end{itemize} - -The C language syntax for \textbf{glfwOpenWindow} is: -\begin{lstlisting} -int glfwOpenWindow(int width, int height, - int redbits, int greenbits, int bluebits, - int alphabits, int depthbits, int stencilbits, - int mode) -\end{lstlisting} - -\textbf{glfwOpenWindow} returns GL\_TRUE if the window was opened -correctly, or GL\_FALSE if \GLFW\ failed to open the window. - -\GLFW\ tries to open a window that best matches the requested parameters. -Some parameters may be omitted by setting them to zero, which will result -in \GLFW\ either using a default value, or the related functionality to be -disabled. For instance, if \textit{width} and \textit{height} are both -zero, \GLFW\ will use a window resolution of 640x480. If -\textit{depthbits} is zero, the opened window may not have a depth buffer. - -The \textit{mode} argument is used to specify if the window is to be a -fullscreen window or a regular window. - -If \textit{mode} is GLFW\_FULLSCREEN, the window will cover the entire -screen and no window border or decorations will be visible. If possible, the -video mode will be changed to the mode that closest matches the \textit{width}, -\textit{height}, \textit{redbits}, \textit{greenbits}, \textit{bluebits} and -\textit{alphabits} arguments. Furthermore, the mouse pointer will be hidden, -and screensavers are prohibited. This is usually the best mode for games and -demos. - -If \textit{mode} is GLFW\_WINDOW, the window will be opened as a normal, -decorated window on the desktop. The mouse pointer will not be hidden and -screensavers are allowed to be activated. - -To close the window, you can either use \textbf{glfwTerminate}, as -described earlier, or you can use the more explicit approach by calling -\textbf{glfwCloseWindow}, which has the C syntax: - -\begin{lstlisting} -void glfwCloseWindow(void) -\end{lstlisting} - -Note that you do not need to call \textbf{glfwTerminate} and \textbf{glfwInit} -before opening a new window after having closed the current one using -\textbf{glfwCloseWindow}. - - -%------------------------------------------------------------------------- -\section{Using Keyboard Input} -\GLFW\ provides several means for receiving user input, which will be -discussed in more detail in chapter \ref{par:inputhandling}. One of the -simplest ways of checking for keyboard input is to use the function -\textbf{glfwGetKey}: - -\begin{lstlisting} -int glfwGetKey(int key) -\end{lstlisting} - -It queries the current status of individual keyboard keys. The argument -\textit{key} specifies which key to check, and it must be a valid GLFW key code -(see the \textit{GLFW Reference Manual} for a list of key codes). -\textbf{glfwGetKey} returns GLFW\_PRESS if the key is currently held down, or -GLFW\_RELEASE if the key is not being held down. For example: - -\begin{lstlisting} -A_pressed = glfwGetKey(GLFW_KEY_A); -esc_pressed = glfwGetKey(GLFW_KEY_ESCAPE); -\end{lstlisting} - -In order for \textbf{glfwGetKey} to have any effect, you need to poll for -input events on a regular basis. This can be done in one of two ways: - -\begin{enumerate} -\item Implicitly by calling \textbf{glfwSwapBuffers} often. -\item Explicitly by calling \textbf{glfwPollEvents} often. -\end{enumerate} - -In general you do not have to care about this, since you will normally -call \textbf{glfwSwapBuffers} to swap front and back rendering buffers -every animation frame anyway. If, however, this is not the case, you -should call \textbf{glfwPollEvents} in the order of 10-100 times per -second in order for \GLFW\ to maintain an up to date input state. - - -%------------------------------------------------------------------------- -\section{Putting It Together: A Minimal GLFW Application} -Now that you know how to initialize \GLFW , open a window and poll for -keyboard input, let us exemplify this with a simple \OpenGL\ program: - -\begin{lstlisting} -#include -#include - -int main(void) -{ - int running = GL_TRUE; - - // Initialize GLFW - if (!glfwInit()) - exit(EXIT_FAILURE); - - // Open an OpenGL window - if (!glfwOpenWindow(300,300, 0,0,0,0,0,0, GLFW_WINDOW)) - { - glfwTerminate(); - exit(EXIT_FAILURE); - } - - // Main loop - while (running) - { - // OpenGL rendering goes here... - glClear(GL_COLOR_BUFFER_BIT); - - // Swap front and back rendering buffers - glfwSwapBuffers(); - - // Check if ESC key was pressed or window was closed - running = !glfwGetKey(GLFW_KEY_ESCAPE) && - glfwGetWindowParam(GLFW_OPENED); - } - - // Close window and terminate GLFW - glfwTerminate(); - - // Exit program - exit(EXIT_SUCCESS); -} -\end{lstlisting} - -The program opens a 300x300 window and runs in a loop until the escape key -is pressed, or the window was closed. All the \OpenGL\ ``rendering'' that -is done in this example is to clear the window. - - -%------------------------------------------------------------------------- -% Window Operations -%------------------------------------------------------------------------- -\chapter{Window Operations} -\thispagestyle{fancy} -In this chapter, you will learn more about window related \GLFW\ -functionality, including setting and getting window properties, buffer -swap control and video mode querying. - - -%------------------------------------------------------------------------- -\section{Setting Window Properties} -In the previous chapter the \textbf{glfwOpenWindow} function was -described, which specifies the sizes of the color, alpha, depth and -stencil buffers. It is also possible to request a specific minimum OpenGL -version, multisampling anti-aliasing, an accumulation buffer, stereo -rendering and more by using the \textbf{glfwOpenWindowHint} function: - -\begin{lstlisting} -void glfwOpenWindowHint(int target, int hint) -\end{lstlisting} - -The \textit{target} argument can be one of the constants listed in table~ -\ref{tab:winhints}, and \textit{hint} is the value to assign to the -specified target. - -%------------------------------------------------------------------------- -\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} -%------------------------------------------------------------------------- - -For a hint to have any effect, the \textbf{glfwOpenWindowHint} function -must be called before opening the window with the \textbf{glfwOpenWindow} -function. - -To request an accumulation buffer, set the GLFW\_ACCUM\_x\_BITS targets to -values greater than zero (usually eight or sixteen bits per component). -To request auxiliary buffers, set the GLFW\_AUX\_BUFFERS target to a value -greater than zero. To request a stereo rendering capable window, set the -GLFW\_STEREO target to GL\_TRUE. - -If you want to enable fullscreen antialiasing, set the GLFW\_FSAA\_SAMPLES -target to a value greater than zero. If the windowing system is unable to -fulfil the request, \GLFW\ will degrade gracefully and disable FSAA if necessary. - -The GLFW\_REFRESH\_RATE target should be used with caution, since it may -result in suboptimal operation, or even a blank or damaged screen. - -If you want to create a forward-compatible \OpenGL\ context, set the -GLFW\_OPENGL\_FORWARD\_COMPAT hint to GL\_TRUE. Note that such contexts are -only available for \OpenGL\ version 3.0 and above, so you will need to specify -a valid minimum version using the GLFW\_OPENGL\_VERSION\_MAJOR and -GLFW\_OPENGL\_VERSION\_MINOR hints. - -If you want to create a context using the core profile as available in \OpenGL\ -version 3.2 and above, set the GLFW\_OPENGL\_PROFILE hint accordingly. Note that -as above you have to set a valid minimum version for this to work. - -Also note that at the time of this release, Mac OS X did not support \OpenGL\ -version 3.0 or above; thus GLFW cannot create contexts of versions above 2.1 -on that platform. - -Besides the parameters that are given with the \textbf{glfwOpenWindow} and -\textbf{glfwOpenWindowHint} functions, a few more properties of a window -can be changed after the window has been opened, namely the window title, -window size, and window position. - -To change the window title of an open window, use the -\textbf{glfwSetWindowTitle} function: - -\begin{lstlisting} -void glfwSetWindowTitle(const char* title) -\end{lstlisting} - -\textit{title} is a null terminated ISO~8859-1 (8-bit Latin~1) string that -will be used as the window title. It will also be used as the application -name (for instance in the application list when using \texttt{Alt+Tab} -under Windows, or as the icon name when the window is iconified under -the X Window System). The default window name is ``GLFW Window'', which -will be used unless \textbf{glfwSetWindowTitle} is called after the window -has been opened. - -To change the size of a window, call \textbf{glfwSetWindowSize}: - -\begin{lstlisting} -void glfwSetWindowSize(int width, int height) -\end{lstlisting} - -Where \textit{width} and \textit{height} are the new dimensions of the -window. - -To change the position of a window, call \textbf{glfwSetWindowPos}: - -\begin{lstlisting} -void glfwSetWindowPos(int x, int y) -\end{lstlisting} - -Where \textit{x} and \textit{y} are the new desktop coordinates of the -window. This function does not have any effect when in fullscreen mode. - - -%------------------------------------------------------------------------- -\section{Getting Window Properties} -When opening a window, the opened window will not necessarily have the -requested properties, so you should always check the parameters that your -application relies on (e.g. number of stencil bits) using -\textbf{glfwGetWindowParam}, which has the C syntax: - -\begin{lstlisting} -int glfwGetWindowParam(int param) -\end{lstlisting} - -The argument \textit{param} can be one of the tokens listed in table -\ref{tab:winparams}, and the return value is an integer holding the -requested value. - -%------------------------------------------------------------------------- -\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} -%------------------------------------------------------------------------- - -Another useful function is \textbf{glfwSetWindowSizeCallback}, which -specifies a user function that will be called every time the window size -has changed. The C syntax is: - -\begin{lstlisting} -void glfwSetWindowSizeCallback(GLFWwindowsizefun cbfun) -\end{lstlisting} - -The user function \textit{fun} should be of the type: - -\begin{lstlisting} -void fun(int width, int height) -\end{lstlisting} - -The first argument passed to the user function is the width of the window, -and the second argument is the height of the window. Here is an example -of how to use a window size callback function: - -\begin{lstlisting} -int windowWidth, windowHeight; - -void WindowResize(int width, int height) -{ - windowWidth = width; - windowHeight = height; -} - -int main(void) -{ - ... - glfwSetWindowSizeCallback(WindowResize); - ... -} -\end{lstlisting} - -Using a callback function for getting the window size is mostly useful for -windowed applications, since the window size may be changed at any time by -the user. It can also be used to determine the actual fullscreen -resolution. - -An alternative to using a callback function for getting the window size, -is to use the function \textbf{glfwGetWindowSize}: - -\begin{lstlisting} -void glfwGetWindowSize(int* width, int* height) -\end{lstlisting} - -The variables pointed to by \textit{width} and \textit{height} are set to the -current window dimensions. Note that either of these may be NULL; that -argument is then ignored. - - -%------------------------------------------------------------------------- -\section{Buffer Swapping} -\GLFW\ windows are always double buffered. That means that you have two -rendering buffers; a front buffer and a back buffer. The front buffer is -the buffer that is being displayed, and the back buffer is not displayed. -\OpenGL\ lets you select which of these two buffers you want to render to -(with the \textbf{glDrawBuffer} command), but the default (and preferred) -rendering buffer is the back buffer. This way you will avoid flickering -and artifacts caused by graphics being only partly drawn at the same time -as the video raster beam is displaying the graphics on the monitor. - -When an entire frame has been rendered to the back buffer, it is time to -swap the back and the front buffers in order to display the rendered -frame, and begin rendering a new frame. This is done with the command -\textbf{glfwSwapBuffers}. The C syntax is: - -\begin{lstlisting} -void glfwSwapBuffers(void) -\end{lstlisting} - -After swapping the front and back rendering buffers, \textbf{glfwSwapBuffers} -by default calls \textbf{glfwPollEvents}\footnote{This behavior can be disabled -by calling \textbf{glfwDisable} with the argument GLFW\_AUTO\_POLL\_EVENTS.}. -This is to ensure frequent polling of events, such as keyboard and mouse input, -and window reshaping events. Even if a given application does not use input -events, without frequent polling of events (at \emph{least} once every few -seconds), most modern window systems will flag the application as unresponsive -and may suggest that the user terminate it. - -Sometimes it can be useful to select when the buffer swap will occur. With -the function \textbf{glfwSwapInterval} it is possible to select the -minimum number of vertical retraces the video raster line should do before -swapping the buffers: - -\begin{lstlisting} -void glfwSwapInterval(int interval) -\end{lstlisting} - -If \textit{interval} is zero, the swap will take place immediately when -\textbf{glfwSwapBuffers} is called, without waiting for a vertical retrace -(also known as ``vsync off''). Otherwise at least \textit{interval} -retraces will pass between each buffer swap (also known as ``vsync on''). -Using a swap interval of zero can be useful for benchmarking purposes, -when it is not desirable to measure the time it takes to wait for the -vertical retrace. However, a swap interval of 1 generally gives better -visual quality. - -It should be noted that not all \OpenGL\ implementations and hardware support -this function, in which case \textbf{glfwSwapInterval} will have no effect. ATI -Radeon cards under Microsoft Windows are especially notorious in this regard. -Sometimes it is only possible to affect the swap interval through driver -settings (e.g. the display settings under Windows, or as an environment -variable setting under Unix). - - -%------------------------------------------------------------------------- -\section{Querying Video Modes} -Although \GLFW\ generally does a good job at selecting a suitable video -mode for you when you open a fullscreen window, it is sometimes useful to -know exactly which modes are available on a certain system. For example, -you may want to present the user with a list of video modes to select -from. To get a list of available video modes, you can use the function -\textbf{glfwGetVideoModes}: - -\begin{lstlisting} -int glfwGetVideoModes(GLFWvidmode* list, int maxcount) -\end{lstlisting} - -The argument \textit{list} is a vector of GLFWvidmode structures, and -\textit{maxcount} is the maximum number of video modes that your vector can -hold. \textbf{glfwGetVideoModes} will return the number of video modes detected -on the system, up to \textit{maxcount}. - -The GLFWvidmode structure looks like this: - -\begin{lstlisting} -typedef struct { - int Width, Height; // Video resolution - int RedBits; // Red bits per pixel - int GreenBits; // Green bits per pixel - int BlueBits; // Blue bits per pixel -} GLFWvidmode; -\end{lstlisting} - -Here is an example of retrieving all available video modes: - -\begin{lstlisting} -int nummodes; -GLFWvidmode list[200]; -nummodes = glfwGetVideoModes(list, 200); -\end{lstlisting} - -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. - -To get the desktop video mode, use the function -\textbf{glfwGetDesktopMode}: - -\begin{lstlisting} -void glfwGetDesktopMode(GLFWvidmode* mode) -\end{lstlisting} - -The function returns the resolution and color depth of the user desktop in -the mode structure. Note that the user desktop mode is independent of the -current video mode if a \GLFW\ fullscreen window has been opened. - - -%------------------------------------------------------------------------- -% Input Handling -%------------------------------------------------------------------------- -\chapter{Input Handling} -\label{par:inputhandling} -\thispagestyle{fancy} -In this chapter you will learn how to use keyboard, mouse and joystick -input, using either polling or callback functions. - - -%------------------------------------------------------------------------- -\section{Event Polling} -The first thing to know about input handling in \GLFW\ is that all -keyboard and mouse input is collected by checking for input events. This -has do be done manually by calling either \textbf{glfwPollEvents} or -\textbf{glfwSwapBuffers} (which implicitly calls \textbf{glfwPollEvents} -for you). Normally this is not a cause for concern, as -\textbf{glfwSwapBuffers} is called every frame, which should be often -enough (about 10-100 times per second for a normal \OpenGL\ application) that -the window will feel responsive. - -One exception is when an application is updating its view only in response to input. -In this case the \textbf{glfwWaitEvents} is useful, as it blocks the calling -thread until an event arrives. The refresh callback, set with -\textbf{glfwSetWindowRefreshCallback}, may also be useful for such -applications, especially on unbuffered window systems. - -If it is not desirable that \textbf{glfwPollEvents is} called implicitly -from \textbf{glfwSwapBuffers}, call \textbf{glfwDisable} with the argument -GLFW\_AUTO\_POLL\_EVENTS. - -Note that event polling is not needed for joystick input, since all -relevant joystick state is gathered every time a joystick function is -called. - - -%------------------------------------------------------------------------- -\section{Keyboard Input} -\GLFW\ provides three mechanisms for getting keyboard input: - -\begin{itemize} -\item Manually polling the state of individual keys. -\item Automatically receive new key state for any key, using a callback - function. -\item Automatically receive characters, using a callback function. -\end{itemize} - -Depending on what the keyboard input will be used for, different methods may be -preferred. The main difference between the two last methods is that while -characters are affected by modifier keys (such as shift), key state is -independent of any modifier keys. Also, special keys (such as function keys, -cursor keys and modifier keys) are not reported to the character callback -function. - -%------------------------------------------------------------------------- -\subsection{Key state} -To check if a key is held down or not at any given moment, use the -function \textbf{glfwGetKey}: - -\begin{lstlisting} -int glfwGetKey(int key) -\end{lstlisting} - -It queries the current status of individual keyboard keys. The argument -\textit{key} specifies which key to check, which must be a valid GLFW key code. -\textbf{glfwGetKey} returns GLFW\_PRESS (or 1) if the key is currently -held down, or GLFW\_RELEASE (or 0) if the key is not being held down. - -In most situations, it may be useful to know if a key has been pressed and -released between two calls to \textbf{glfwGetKey} (especially if the -animation is fairly slow, which may allow the user to press and release a -key between two calls to \textbf{glfwGetKey}). This can be accomplished by -enabling sticky keys, which is done by calling \textbf{glfwEnable} with -the argument GLFW\_STICKY\_KEYS, as in the following example: - -\begin{lstlisting} -glfwEnable(GLFW_STICKY_KEYS); -\end{lstlisting} - -When sticky keys are enabled, a key will not be released until it is -checked with \textbf{glfwGetKey}. To disable sticky keys, call -\textbf{glfwDisable} witht the argument GLFW\_STICKY\_KEYS. Then all keys -that are not currently held down will be released and future key releases -will take place immediately when the user releases the key without -waiting for \textbf{glfwGetKey} to check the key. By default sticky keys -are disabled. - -Sticky keys are often very useful and should be used in most cases where -\textbf{glfwGetKey} is used. There is however a danger involved with -enabling sticky keys, and that is that keys that are pressed by the user -but are not checked with \textbf{glfwGetKey}, may remain ``pressed'' for a -very long time. A typical situation where this may be dangerous is in a -program that consists of two or more sections (e.g. a menu section and a -game section). If the first section enables sticky keys but does not check -for keys which the second section checks for, there is a potential of -recording many key presses in the first section that will be detected in -the second section. To avoid this problem, always disable sticky keys -before leaving a section of a program. - -A usually better alternative to using \textbf{glfwGetKey} is to register a -keyboard input callback function with \textbf{glfwSetKeyCallback}: - -\begin{lstlisting} -void glfwSetKeyCallback(GLFWkeyfun cbfun) -\end{lstlisting} - -The argument \textit{fun} is a pointer to a callback function. The -callback function shall take two integer arguments. The first is the key -identifier, and the second is the new key state, which can be GLFW\_PRESS -or GLFW\_RELEASE. To unregister a callback function, call -\textbf{glfwSetKeyCallback} with \textit{fun} = NULL. - -Using the callback function, you can be sure not to miss any key press or -release events, regardless of how many may have occurred during the last frame. -It also encourages event-based design, where the application responds only to -actual events instead of having to poll for every supported event. - -%------------------------------------------------------------------------- -\subsection{Character input} -If the keyboard is to be used as a text input device (e.g. in a user -dialog) rather than as a set of independent buttons, a character callback -function is more suitable. To register a character callback function, use -\textbf{glfwSetCharCallback}: - -\begin{lstlisting} -void glfwSetCharCallback(GLFWcharfun cbfun) -\end{lstlisting} - -The argument \textit{fun} is a pointer to a callback function. The -callback function shall take two integer arguments. The first is a Unicode -code point, and the second is GLFW\_PRESS if the key that generated -the character was pressed, or GLFW\_RELEASE if it was released. To -unregister a callback function, call \textbf{glfwSetCharCallback} with -\textit{fun} = NULL. - -The Unicode character set is an international standard for encoding -characters. It is much more comprehensive than seven or eight bit -character sets (e.g. US-ASCII and Latin~1), and includes characters for -most written languages in the world. It should be noted that Unicode -character codes 0 to 255 are the same as for ISO~8859-1 (Latin~1), so as -long as a proper range check is performed on the Unicode character code, -it can be used just as an eight bit Latin~1 character code (which can be -useful if full Unicode support is not possible). - - -%------------------------------------------------------------------------- -\subsection{Key repeat} -By default, \GLFW\ does not report key repeats when a key is held down. -To activate key repeat, call \textbf{glfwEnable} with the argument -GLFW\_KEY\_REPEAT: - -\begin{lstlisting} -glfwEnable(GLFW_KEY_REPEAT); -\end{lstlisting} - -This will let a registered key or character callback function receive key -repeat events when a key is held down. - - -%------------------------------------------------------------------------- -\subsection{Special system keys} -On most systems there are some special system keys that are normally not -intercepted by an application. For instance, under Windows it is possible -to switch programs by pressing \texttt{ALT+TAB}, which brings up a list of -running programs to select from. In certain situations it can be desirable -to prevent such special system keys from interfering with the program. -With \GLFW\ it is possible to do by calling \textbf{glfwDisable} with the -argument GLFW\_SYSTEM\_KEYS: - -\begin{lstlisting} -glfwDisable(GLFW_SYSTEM_KEYS); -\end{lstlisting} - -By doing so, most system keys will have no effect and will not interfere -with your program. System keys can be re-enabled by calling -\textbf{glfwEnable} with the argument GLFW\_SYSTEM\_KEYS. By default, -system keys are enabled. - - -%------------------------------------------------------------------------- -\section{Mouse Input} -Just like for keyboard input, mouse input can be realized with either -polling or callback functions. - - -%------------------------------------------------------------------------- -\subsection{Mouse position} -To query the position of the mouse cursor, call \textbf{glfwGetMousePos}: - -\begin{lstlisting} -void glfwGetMousePos(int* x, int* y) -\end{lstlisting} - -The variables pointed to by \textit{x} and \textit{y} will be updated with the -current position of the mouse cursor relative to the upper-left corner of the -client area of the \GLFW\ window. - -An alternative is to use a callback function, which can be set with -\textbf{glfwSetMousePosCallback}: - -\begin{lstlisting} -void glfwSetMousePosCallback(GLFWmouseposfun cbfun) -\end{lstlisting} - -The function that \textit{fun} points to will be called every time the -mouse cursor moves. The first argument to the callback function is -the cursor x-coordinate and the second the cursor y-coordinate, both relative -to the upper-left corner of the client area of the \GLFW\ window. - -Note that while the \textbf{glfwGetMousePos} function only reports the final -position after cursor movement events have been processed, using a callback -function lets the application see each and every such event. - - -%------------------------------------------------------------------------- -\subsection{Mouse buttons} -To query the state of a mouse button, call \textbf{glfwGetMouseButton}: - -\begin{lstlisting} -int glfwGetMouseButton(int button) -\end{lstlisting} - -The argument \textit{button} can be any \GLFW\ mouse button token, i.e. -GLFW\_MOUSE\_BUTTON\_1 through GLFW\_MOUSE\_BUTTON\_8 or one of -GLFW\_MOUSE\_BUTTON\_LEFT, GLFW\_MOUSE\_BUTTON\_RIGHT or -GLFW\_MOUSE\_BUTTON\_MIDDLE. \textbf{glfwGetMouseButton} will return -GLFW\_PRESS (which is a non-zero value) if the corresponding mouse button is -held down, otherwise it will return GLFW\_RELEASE (which is equal to zero). - -Just as it is possible to make keys ``sticky'', it is also possible to make -each mouse button appear as held down until it is checked with -\textbf{glfwGetMouseButton}. To enable sticky mouse buttons, call -\textbf{glfwEnable} with the argument GLFW\_STICKY\_MOUSE\_BUTTONS. - -When sticky mouse buttons are enabled, a mouse button will not be released -until it is checked with \textbf{glfwGetMouseButton}. To disable sticky -mouse buttons, call \textbf{glfwDisable} with the argument -GLFW\_STICKY\_MOUSE\_BUTTONS. Then all mouse buttons that are not -currently held down will be released and future mouse button releases -will take place immediately when the user releases the mouse button -without waiting for \textbf{glfwGetMouseButton} to check for the mouse -button. By default sticky mouse buttons are disabled. - -There is also a callback function for mouse button activities, which can -be set with \textbf{glfwSetMouseButtonCallback}: - -\begin{lstlisting} -void glfwSetMouseButtonCallback(GLFWmousebuttonfun fun) -\end{lstlisting} - -The argument \textit{fun} specifies a function that will be called -whenever a mouse button is pressed or released, or NULL to unregister a -callback function. The first argument to the callback function is a mouse -button identifier, and the second is either GLFW\_PRESS or GLFW\_RELEASE, -depending on the new state of the corresponding mouse button. - - -%------------------------------------------------------------------------- -\subsection{Mouse wheel} -Some mice have a mouse wheel, most commonly used for vertical scrolling. Also, -most modern touchpads allow the user to scroll at least vertically, either by -reserving an area for scrolling or through multi-finger gestures. To get the -position of the mouse wheel, call \textbf{glfwGetMouseWheel}: - -\begin{lstlisting} -int glfwGetMouseWheel(void) -\end{lstlisting} - -The function returns an integer that represents the position of the mouse -wheel. When the user turns the wheel, the wheel position will increase or -decrease. Note that since scrolling hardware has no absolute position, \GLFW\ -simply sets the position to zero when the window is opened. - -It is also possible to register a callback function for mouse wheel events -with the \textbf{glfwSetMouseWheelCallback} function: - -\begin{lstlisting} -void glfwSetMouseWheelCallback(GLFWmousewheelfun fun) -\end{lstlisting} - -The argument \textit{fun} specifies a function that will be called -whenever the mouse wheel is moved, or NULL to unregister a callback -function. The argument to the callback function is the position of the -mouse wheel. - - -%------------------------------------------------------------------------- -\subsection{Hiding the mouse cursor} -It is possible to hide the mouse cursor with the function call: - -\begin{lstlisting} -glfwDisable(GLFW_MOUSE_CURSOR); -\end{lstlisting} - -Hiding the mouse cursor has three effects: - -\begin{enumerate} -\item The cursor becomes invisible. -\item The cursor is guaranteed to be confined to the window. -\item Mouse coordinates are not limited to the window size. -\end{enumerate} - -To show the mouse cursor again, call \textbf{glfwEnable} with the -argument GLFW\_MOUSE\_CURSOR: - -\begin{lstlisting} -glfwEnable(GLFW_MOUSE_CURSOR); -\end{lstlisting} - -By default the mouse cursor is hidden if a window is opened in fullscreen -mode, otherwise it is not hidden. - - -%------------------------------------------------------------------------- -\section{Joystick Input} -\GLFW\ has support for up to sixteen joysticks, and an infinite\footnote{% -There are of course actual limitations posed by the underlying hardware, -drivers and operation system.} number of axes and buttons per joystick. -Unlike keyboard and mouse input, joystick input does not need an opened -window, and \textbf{glfwPollEvents} or \textbf{glfwSwapBuffers} does not -have to be called in order for joystick state to be updated. - - -%------------------------------------------------------------------------- -\subsection{Joystick capabilities} -First, it is often necessary to determine if a joystick is connected and -what its capabilities are. To get this information the function -\textbf{glfwGetJoystickParam} can be used: - -\begin{lstlisting} -int glfwGetJoystickParam(int joy, int param) -\end{lstlisting} - -The \textit{joy} argument specifies which joystick to retrieve the -parameter from, and it should be GLFW\_JOYSTICK\_\textit{n}, where -\textit{n} is in the range 1 to 16. The \textit{param} argument specifies -which parameter to retrieve. To determine if a joystick is connected, -\textit{param} should be GLFW\_PRESENT, which will cause the function to -return GL\_TRUE if the joystick is connected, or GL\_FALSE if it is not. -To determine the number of axes or buttons that are supported by the -joystick, \textit{param} should be GLFW\_AXES or GLFW\_BUTTONS, -respectively. - -Note that \GLFW\ supports both D-pads and POVs, even though they are not -explicitly mentioned in the API. D-pads are exposed as a set of four buttons -and POVs are as two axes. - - -%------------------------------------------------------------------------- -\subsection{Joystick position} -To get the current axis positions of the joystick, the -\textbf{glfwGetJoystickPos} is used: - -\begin{lstlisting} -int glfwGetJoystickPos(int joy, float* pos, int numaxes) -\end{lstlisting} - -As with \textbf{glfwGetJoystickParam}, the \textit{joy} argument -specifies which joystick to retrieve information from. The -\textit{numaxes} argument specifies how many axes to return positions for and the -\textit{pos} argument specifies an array in which they -are stored. The function returns the actual number of axes that were -returned, which could be less than \textit{numaxes} if the joystick does -not support all the requested axes, or if the joystick is not connected. - -For instance, to get the position of the first two axes (the X and Y axes) -of joystick 1, the following code can be used: - -\begin{lstlisting} -float position[2]; - -glfwGetJoystickPos(GLFW_JOYSTICK_1, position, 2); -\end{lstlisting} - -After this call, the first element of the \textit{position} array will -hold the X axis position of the joystick, and the second element will hold -the Y axis position. In this example we do not use the information about -how many axes were really returned. - -The position of an axis can be in the range -1.0 to 1.0, where positive -values represent right, forward or up directions, while negative values -represent left, back or down directions. If a requested axis is not -supported by the joystick, the corresponding array element will be set -to zero. The same goes for the situation when the joystick is not -connected (all axes are treated as unsupported). - - -%------------------------------------------------------------------------- -\subsection{Joystick buttons} -A function similar to the \textbf{glfwGetJoystickPos} function is -available for querying the state of joystick buttons, namely the -\textbf{glfwGetJoystickButtons} function: - -\begin{lstlisting} -int glfwGetJoystickButtons(int joy, unsigned char* buttons, - int numbuttons) -\end{lstlisting} - -The function works just like the \textbf{glfwGetJoystickAxis} function, except -that it returns the state of joystick buttons instead of axis positions. Each -button in the array specified by the \textit{buttons} argument can be either -GLFW\_PRESS or GLFW\_RELEASE, indicating whether the corresponding button is -currently held down or not. Unsupported buttons will have the value -GLFW\_RELEASE. - - -%------------------------------------------------------------------------- -% Timing -%------------------------------------------------------------------------- -\chapter{Timing} -\thispagestyle{fancy} - -%------------------------------------------------------------------------- -\section{High Resolution Timer} -In most applications, it is useful to know exactly how much time has -passed between point $A$ and point $B$ in a program. A typical situation -is in a game, where you need to know how much time has passed between two -rendered frames in order to calculate the correct movement and physics -etc. Another example is when you want to benchmark a certain piece of -code. - -\GLFW\ provides a high-resolution timer, which reports a double precision -floating point value representing the number of seconds that have passed -since \textbf{glfwInit} was called. The timer is accessed with the -function \textbf{glfwGetTime}: - -\begin{lstlisting} -double glfwGetTime(void) -\end{lstlisting} - -The precision of the timer depends on which computer and operating -system you are running, but it is almost guaranteed to be better than -$10~ms$, and in most cases it is much better than $1~ms$ (on a modern PC -you can get resolutions in the order of $1~ns$). - -It is possible to set the value of the high precision timer using the -\textbf{glfwSetTime} function: - -\begin{lstlisting} -void glfwSetTime(double time) -\end{lstlisting} - -The argument \textit{time} is the time, in seconds, that the timer should -be set to. - - -%------------------------------------------------------------------------- -% OpenGL Extension Support -%------------------------------------------------------------------------- -\chapter{OpenGL Extension Support} -\thispagestyle{fancy} -One of the benefits of \OpenGL\ is that it is extensible. Independent -hardware vendors (IHVs) may include functionality in their \OpenGL\ -implementations that exceed that of the \OpenGL\ standard. - -An extension is defined by: - -\begin{enumerate} -\item An extension name (e.g. GL\_ARB\_multitexture). -\item New OpenGL tokens (e.g. GL\_TEXTURE1\_ARB). -\item New OpenGL functions (e.g. \textbf{glActiveTextureARB}). -\end{enumerate} - -A list of official extensions, together with their definitions, can be -found at the \textit{OpenGL Registry} -(\url{http://www.opengl.org/registry/}). - -To use a certain extension, the following steps must be performed: - -\begin{enumerate} -\item A compile time check for the support of the extension. -\item A run time check for the support of the extension. -\item Fetch function pointers for the extended \OpenGL\ functions (done at - run time). -\end{enumerate} - -How this is done using \GLFW\ is described in the following sections. -Please note that this chapter covers some advanced topics, and is quite -specific to the C programming language. - -For a much easier way to get access to \OpenGL\ extensions, you should probably -use a dedicated extension loading library such as GLEW or GLee. This kind of -library greatly reduces the amount of work necessary to use \OpenGL\ -extensions. GLEW in particular has been extensively tested with and works well -with \GLFW . - - -%------------------------------------------------------------------------- -\section{Compile Time Check} -The compile time check is necessary to perform in order to know if the -compiler include files have defined the necessary tokens. It is very easy -to do. The include file \texttt{GL/gl.h} will define a constant with the -same name as the extension, if all the extension tokens are defined. Here -is an example of how to check for the extension GL\_ARB\_multitexture: - -\begin{lstlisting} -#ifdef GL_ARB_multitexture - // Extension is supported by the include files -#else - // Extension is not supported by the include files - // Get a more up-to-date file! -#endif -\end{lstlisting} - - -%------------------------------------------------------------------------- -\section{Runtime Check} -Even if the compiler include files have defined all the necessary tokens, a -given machine may not actually support the extension (it may have a graphics -card with a different \OpenGL\ implementation, or an older driver). That is why -it is necessary to do a run time check for the extension support as well. This -is done with the \GLFW\ function \textbf{glfwExtensionSupported}, which has the -C syntax: - -\begin{lstlisting} -int glfwExtensionSupported(const char* extension) -\end{lstlisting} - -The argument \textit{extension} is a null terminated ASCII string -with the extension name. \textbf{glfwExtensionSupported} returns GL\_TRUE -if the extension is supported, otherwise it returns GL\_FALSE. - -Let us extend the previous example of checking for support of the -extension GL\_ARB\_multitexture. This time we add a run time check, and a -variable which we set to GL\_TRUE if the extension is supported, or -GL\_FALSE if it is not supported. - -\begin{lstlisting} -int multitexture_supported; - -#ifdef GL_ARB_multitexture - // Check if extension is supported at run time - multitexture_supported = glfwExtensionSupported("GL_ARB_multitexture"); -#else - // Extension is not supported by the include files - // Get a more up-to-date file! - multitexture_supported = GL_FALSE; -#endif -\end{lstlisting} - -Now it is easy to check for the extension within the program, simply do: - -\begin{lstlisting} - if (multitexture_supported) - { - // Use multi texturing - } - else - { - // Use some other solution (or fail) - } -\end{lstlisting} - - -%------------------------------------------------------------------------- -\section{Fetching Function Pointers} -Some extensions, though not all, require the use of new \OpenGL\ functions. -These entry points are not necessarily exposed by your link libraries, making -it necessary to find them dynamically at run time. You can retrieve these -entry points using the \textbf{glfwGetProcAddress} function: - -\begin{lstlisting} -void* glfwGetProcAddress(const char* procname) -\end{lstlisting} - -The argument \textit{procname} is a null terminated ASCII string -holding the name of the \OpenGL\ function. \textbf{glfwGetProcAddress} -returns the address to the function if the function is available, -otherwise NULL is returned. - -Obviously, fetching the function pointer is trivial. For instance, if we -want to obtain the pointer to \textbf{glActiveTextureARB}, we simply call: - -\begin{lstlisting} -glActiveTextureARB = glfwGetProcAddress("glActiveTextureARB"); -\end{lstlisting} - -However, there are many possible naming and type definition conflicts -involved with such an operation, which may result in compiler warnings or -errors. My proposed solution is the following: - -\begin{itemize} -\item Do not use the function name for the variable name. Use something - similar, perhaps by adding a prefix or suffix, and then use - \texttt{\#define} to map the function name to your variable. -\item The standard type definition naming convention for function pointers - is \texttt{PFN\textit{xxxx}PROC}, where \texttt{\textit{xxxx}} is - the uppercase version of the function name (e.g. - \texttt{PFNGLACTIVETEXTUREARBPROC}). Either make sure your compiler uses - a compatible \texttt{gl.h} and/or \texttt{glext.h} file and rely on it to - define these types, or use define the types yourself using a different - naming convention (for example \texttt{\textit{xxxx}\_T}) and do the - type definitions yourself. -\end{itemize} - -Here is a slightly longer example of how to use an extension, this time using -our own function pointer type definition): - -\begin{lstlisting} -// Type definition of the function pointer -typedef void (APIENTRY * GLACTIVETEXTUREARB_T) (GLenum texture); - -// Function pointer -GLACTIVETEXTUREARB_T _ActiveTextureARB; -#define glActiveTextureARB _ActiveTextureARB - -// Extension availability flag -int multitexture_supported; - -#ifdef GL_ARB_multitexture - // Check if extension is supported at run time - if (glfwExtensionSupported("GL_ARB_multitexture")) - { - // Get the function pointer - glActiveTextureARB = (GLACTIVETEXTUREARB_T) - glfwGetProcAddress("glActiveTextureARB"); - - multitexture_supported = GL_TRUE; - } - else - { - multitexture_supported = GL_FALSE; - } -#else - // Extension is not supported by the include files - multitexture_supported = GL_FALSE; -#endif -\end{lstlisting} - -Even this example leaves some things to be desired. First of all, the -GL\_ARB\_multitexture extension defines many more functions than the single -function used above. Secondly, checking if an extension is supported using -\textbf{glfwExtensionSupported} is not enough to ensure that the corresponding -functions will be valid. You also need to check that the all function pointers -returned by \textbf{glfwGetProcAddress} are non-NULL. - - -%------------------------------------------------------------------------- -\subsection{Function pointer type definitions} -To make a function pointer type definition, you need to know the function -prototype. This can often be found in the extension definitions (e.g. at -the \textit{OpenGL Registry}). All the entry points that are defined by an -extension are listed with their C prototype definitions under the section -\textit{New Procedures and Functions} in the extension definition. - -For instance, if we look at the definition of the -GL\_ARB\_texture\_compression extension, we find a list of new functions. -One of these is declared like this: - -\begin{lstlisting} -void GetCompressedTexImageARB(enum target, int lod, void* img); -\end{lstlisting} - -Like in most official \OpenGL\ documentation, all the \texttt{GL} and -\texttt{gl} prefixes have been left out. In other words, the real function -prototype would look like this: - -\begin{lstlisting} -void glGetCompressedTexImageARB(GLenum target, GLint lod, void* img); -\end{lstlisting} - -All we have to do to turn this prototype definition into a function -pointer type definition, is to replace the function name with -\texttt{(APIENTRY * \textit{xxxx}\_T)}, where \textit{xxxx} is the -uppercase version of the name (according to the proposed naming -convention). The keyword \texttt{APIENTRY} is needed to be compatible -between different platforms. The \GLFW\ header file \texttt{GL/glfw.h} -ensures that \texttt{APIENTRY} is properly defined on all supported platforms. - -In other words, for the function \textbf{glGetCompressedTexImageARB} we -get: - -\begin{lstlisting} -typedef void (APIENTRY * GLGETCOMPRESSEDTEXIMAGEARB_T) - (GLenum target, GLint level, void* img); -\end{lstlisting} - - -\end{document} diff --git a/docs/readme.txt b/docs/readme.txt deleted file mode 100644 index f34521a2..00000000 --- a/docs/readme.txt +++ /dev/null @@ -1,52 +0,0 @@ -Introduction ------------- - -The GLFW documentation is written in LaTeX. Besides being powerful, LaTeX is -also very attractive since all the necessary tools for dealing with LaTeX -documentation are both free and ported to a wide variety of platforms. Another -advantage is that the LaTeX files are written in plain text, which means that -version control systems such as CVS handle them perfectly without having to -treat the documents as binary files. - - -The documents -------------- - -There are two main documents: - - glfwrm.tex - The GLFW Reference Manual - glfwug.tex - The GLFW Users Guide - -In addition, there is a common LaTeX style file that sets up things -such as page formatting and useful macros: - - glfwdoc.sty - Common GLFW document styles and macros - - -Requirements ------------- - -Of course you need LaTeX installed on your system in order to compile the GLFW -documentation. If you are using a Unix-like operating system, then your -package system most likely has a version of LaTeX adapted for your system. If -not, the easiest way to get a full LaTeX system is to download/get the TeXLive -CD from http://www.tug.org/texlive/. It has all the necessary software for -Windows, Mac OS X and most popular Unix-like operating systems. - -A number of LaTeX packages have to be installed in order to compile the -GLFW documentation successfully: - - color - fancyhdr - hyperref - lastpage - listings - needspace - textcase - times - titling - -These packages are all available on the TeXLive CD. Just make sure that -you have checked all these packages when installing TeXLive, or get them -in some other way if you do not have the TeXLive CD. -