text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Initialization, version and error reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Modules |
Typedefs |
Functions

Initialization, version and error reference

Modules

 	Error codes

Typedefs

typedef void(* 	GLFWerrorfun) (int, const char *)

 	The function signature for error callbacks.  More...

Functions

int 	glfwInit (void)

 	Initializes the GLFW library.  More...

void 	glfwTerminate (void)

 	Terminates the GLFW library.  More...

void 	glfwGetVersion (int *major, int *minor, int *rev)

 	Retrieves the version of the GLFW library.  More...

const char * 	glfwGetVersionString (void)

 	Returns a string describing the compile-time configuration.  More...

GLFWerrorfun 	glfwSetErrorCallback (GLFWerrorfun cbfun)

 	Sets the error callback.  More...

GLFW version macros

#define 	GLFW_VERSION_MAJOR   3

 	The major version number of the GLFW library.  More...

#define 	GLFW_VERSION_MINOR   2

 	The minor version number of the GLFW library.  More...

#define 	GLFW_VERSION_REVISION   1

 	The revision number of the GLFW library.  More...

Detailed Description

This is the reference documentation for initialization and termination of the library, version management and error handling. For more task-oriented information, see the Introduction to the API.

Macro Definition Documentation

          #define GLFW_VERSION_MAJOR   3

This is incremented when the API is changed in non-compatible ways.

          #define GLFW_VERSION_MINOR   2

This is incremented when features are added to the API but it remains backward-compatible.

          #define GLFW_VERSION_REVISION   1

This is incremented when a bug fix release is made that does not contain any API changes.

Typedef Documentation

          typedef void(*  GLFWerrorfun) (int, const char *)

This is the function signature for error callback functions.

Parameters

[in]	error	An error code.

[in]	description	A UTF-8 encoded string describing the error.

See also

Error handling

glfwSetErrorCallback

Since

Added in version 3.0.

Function Documentation

          void glfwGetVersion
          (
          int *
          major,

          int *
          minor,

          int *
          rev

          )

This function retrieves the major, minor and revision numbers of the GLFW library. It is intended for when you are using GLFW as a shared library and want to ensure that you are using the minimum required version.

Any or all of the version arguments may be NULL.

Parameters

[out]	major	Where to store the major version number, or NULL.

[out]	minor	Where to store the minor version number, or NULL.

[out]	rev	Where to store the revision number, or NULL.

Errors

None.

Remarks

This function may be called before glfwInit.

Thread safety

This function may be called from any thread.

See also

Version management

glfwGetVersionString

Since

Added in version 1.0.

          const char* glfwGetVersionString
          (
          void
          	)

This function returns the compile-time generated version string of the GLFW library binary. It describes the version, platform, compiler and any platform-specific compile-time options. It should not be confused with the OpenGL or OpenGL ES version string, queried with glGetString.

Do not use the version string to parse the GLFW library version. The glfwGetVersion function provides the version of the running library binary in numerical format.

Returns

The ASCII encoded GLFW version string.

Errors

None.

Remarks

This function may be called before glfwInit.

Pointer lifetime

The returned string is static and compile-time generated.

Thread safety

This function may be called from any thread.

See also

Version management

glfwGetVersion

Since

Added in version 3.0.

          int glfwInit
          (
          void
          	)

This function initializes the GLFW library. Before most GLFW functions can be used, GLFW must be initialized, and before an application terminates GLFW should be terminated in order to free any resources allocated during or after initialization.

If this function fails, it calls glfwTerminate before returning. If it succeeds, you should call glfwTerminate before the application exits.

Additional calls to this function after successful initialization but before termination will return GLFW_TRUE immediately.

Returns

GLFW_TRUE if successful, or GLFW_FALSE if an error occurred.

Errors

Possible errors include GLFW_PLATFORM_ERROR.

Remarks

OS X: This function will change the current directory of the application to the Contents/Resources subdirectory of the application's bundle, if present. This can be disabled with a compile-time option.

Thread safety

This function must only be called from the main thread.

See also

Initialization and termination

glfwTerminate

Since

Added in version 1.0.

          GLFWerrorfun glfwSetErrorCallback
          (
          GLFWerrorfun
          cbfun	)

This function sets the error callback, which is called with an error code and a human-readable description each time a GLFW error occurs.

The error callback is called on the thread where the error occurred. If you are using GLFW from multiple threads, your error callback needs to be written accordingly.

Because the description string may have been generated specifically for that error, it is not guaranteed to be valid after the callback has returned. If you wish to use it after the callback returns, you need to make a copy.

Once set, the error callback remains set even after the library has been terminated.

Parameters

[in]	cbfun	The new callback, or NULL to remove the currently set callback.

Returns

The previously set callback, or NULL if no callback was set.

Errors

None.

Remarks

This function may be called before glfwInit.

Thread safety

This function must only be called from the main thread.

See also

Error handling

Since

Added in version 3.0.

          void glfwTerminate
          (
          void
          	)

This function destroys all remaining windows and cursors, restores any modified gamma ramps and frees any other allocated resources. Once this function is called, you must again call glfwInit successfully before you will be able to use most GLFW functions.

If GLFW has been successfully initialized, this function should be called before the application exits. If initialization fails, there is no need to call this function, as it is called by glfwInit before it returns failure.

Errors

Possible errors include GLFW_PLATFORM_ERROR.

Remarks

This function may be called before glfwInit.

Warning

The contexts of any remaining windows must not be current on any other thread when this function is called.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

See also

Initialization and termination

glfwInit

Since

Added in version 1.0.

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

- n -

GLFW_NATIVE_CONTEXT_API
: glfw3.h

GLFW_NO_API
: glfw3.h

GLFW_NO_CURRENT_CONTEXT
: glfw3.h

GLFW_NO_RESET_NOTIFICATION
: glfw3.h

GLFW_NO_ROBUSTNESS
: glfw3.h

GLFW_NO_WINDOW_CONTEXT
: glfw3.h

GLFW_NOT_INITIALIZED
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>

repo_language: C

mime_type: text/x-c


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Building applications</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Building applications

Table of Contents

Including the GLFW header file

GLFW header option macros

Link with the right libraries

With MinGW or Visual C++ on Windows

With CMake and GLFW source

With CMake and installed GLFW binaries

With makefiles and pkg-config on Unix

With Xcode on OS X

With command-line on OS X

This is about compiling and linking applications that use GLFW. For information on how to write such applications, start with the introductory tutorial. For information on how to compile the GLFW library itself, see Compiling GLFW.

This is not a tutorial on compilation or linking. It assumes basic understanding of how to compile and link a C program as well as how to use the specific compiler of your chosen development environment. The compilation and linking process should be explained in your C programming material and in the documentation for your development environment.

Including the GLFW header file

In the source files of your application where you use OpenGL or GLFW, you should include the GLFW header file, i.e.:

#include <GLFW/glfw3.h>

The GLFW header declares the GLFW API and by default also includes the OpenGL header of your development environment, which in turn defines all the constants, types and function prototypes of the OpenGL API.

The GLFW header also defines everything necessary for your OpenGL header to function. For example, under Windows you are normally required to include windows.h before the OpenGL header, which would pollute your code namespace with the entire Win32 API.

Instead, the GLFW header takes care of this for you, not by including windows.h, but by duplicating only the very few necessary parts of it. It does this only when needed, so if windows.h is included, the GLFW header does not try to redefine those symbols. The reverse is not true, i.e. windows.h cannot cope if any of its symbols have already been defined.

In other words:

Do not include the OpenGL headers yourself, as GLFW does this for you

Do not include windows.h or other platform-specific headers unless you plan on using those APIs directly

If you do need to include such headers, do it before including the GLFW header and it will handle this

If you are using an OpenGL extension loading library such as glad, the extension loader header should either be included before the GLFW one, or the GLFW_INCLUDE_NONE macro (described below) should be defined.

GLFW header option macros

These macros may be defined before the inclusion of the GLFW header and affect its behavior.

GLFW_DLL is required on Windows when using the GLFW DLL, to tell the compiler that the GLFW functions are defined in a DLL.

The following macros control which OpenGL or OpenGL ES API header is included. Only one of these may be defined at a time.

GLFW_INCLUDE_GLCOREARB makes the GLFW header include the modern GL/glcorearb.h header (OpenGL/gl3.h on OS X) instead of the regular OpenGL header.

GLFW_INCLUDE_ES1 makes the GLFW header include the OpenGL ES 1.x GLES/gl.h header instead of the regular OpenGL header.

GLFW_INCLUDE_ES2 makes the GLFW header include the OpenGL ES 2.0 GLES2/gl2.h header instead of the regular OpenGL header.

GLFW_INCLUDE_ES3 makes the GLFW header include the OpenGL ES 3.0 GLES3/gl3.h header instead of the regular OpenGL header.

GLFW_INCLUDE_ES31 makes the GLFW header include the OpenGL ES 3.1 GLES3/gl31.h header instead of the regular OpenGL header.

GLFW_INCLUDE_VULKAN makes the GLFW header include the Vulkan vulkan/vulkan.h header instead of the regular OpenGL header.

GLFW_INCLUDE_NONE makes the GLFW header not include any OpenGL or OpenGL ES API header. This is useful in combination with an extension loading library.

If none of the above inclusion macros are defined, the standard OpenGL GL/gl.h header (OpenGL/gl.h on OS X) is included.

The following macros control the inclusion of additional API headers. Any number of these may be defined simultaneously, and/or together with one of the above macros.

GLFW_INCLUDE_GLEXT makes the GLFW header include the appropriate extension header for the OpenGL or OpenGL ES header selected above after and in addition to that header.

GLFW_INCLUDE_GLU makes the header include the GLU header in addition to the header selected above. This should only be used with the standard OpenGL header and only for compatibility with legacy code. GLU has been deprecated and should not be used in new code.

Note

GLFW does not provide any of the API headers mentioned above. They must be provided by your development environment or your OpenGL, OpenGL ES or Vulkan SDK.

None of these macros may be defined during the compilation of GLFW itself. If your build includes GLFW and you define any these in your build files, make sure they are not applied to the GLFW sources.

Link with the right libraries

GLFW is essentially a wrapper of various platform-specific APIs and therefore needs to link against many different system libraries. If you are using GLFW as a shared library / dynamic library / DLL then it takes care of these links. However, if you are using GLFW as a static library then your executable will need to link against these libraries.

On Windows and OS X, the list of system libraries is static and can be hard-coded into your build environment. See the section for your development environment below. On Linux and other Unix-like operating systems, the list varies but can be retrieved in various ways as described below.

A good general introduction to linking is Beginner's Guide to Linkers by David Drysdale.

With MinGW or Visual C++ on Windows

The static version of the GLFW library is named glfw3. When using this version, it is also necessary to link with some libraries that GLFW uses.

When linking an application under Windows that uses the static version of GLFW, you must link with opengl32. On some versions of MinGW, you must also explicitly link with gdi32, while other versions of MinGW include it in the set of default libraries along with other dependencies like user32 and kernel32. If you are using GLU, you must also link with glu32.

The link library for the GLFW DLL is named glfw3dll. When compiling an application that uses the DLL version of GLFW, you need to define the GLFW_DLL macro before any inclusion of the GLFW header. This can be done either with a compiler switch or by defining it in your source code.

An application using the GLFW DLL does not need to link against any of its dependencies, but you still have to link against opengl32 if your application uses OpenGL and glu32 if it uses GLU.

With CMake and GLFW source

This section is about using CMake to compile and link GLFW along with your application. If you want to use an installed binary instead, see With CMake and installed GLFW binaries.

With just a few changes to your CMakeLists.txt you can have the GLFW source tree built along with your application.

When including GLFW as part of your build, you probably don't want to build the GLFW tests, examples and documentation. To disable these, set the corresponding cache variables before adding the GLFW source tree.

set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)

set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)

set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)

Then add the root directory of the GLFW source tree to your project. This will add the glfw target and the necessary cache variables to your project.

    1 add_subdirectory(path/to/glfw)

Once GLFW has been added to the project, link against it with the glfw target. This adds all link-time dependencies of GLFW as it is currently configured, the include directory for the GLFW header and, when applicable, the GLFW_DLL macro.

    1 target_link_libraries(myapp glfw)

Note that the dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU. If your application calls OpenGL directly, instead of using a modern extension loader library you can find it by requiring the OpenGL package.

    1 find_package(OpenGL REQUIRED)

If OpenGL is found, the OPENGL_FOUND variable is true and the OPENGL_INCLUDE_DIR and OPENGL_gl_LIBRARY cache variables can be used.

    1 target_include_directories(myapp ${OPENGL_INCLUDE_DIR})

    2 target_link_libraries(myapp ${OPENGL_gl_LIBRARY})

The OpenGL CMake package also looks for GLU. If GLU is found, the OPENGL_GLU_FOUND variable is true and the OPENGL_INCLUDE_DIR and OPENGL_glu_LIBRARY cache variables can be used.

    1 target_link_libraries(myapp ${OPENGL_glu_LIBRARY})

Note

GLU has been deprecated and should not be used in new code, but some legacy code requires it.

With CMake and installed GLFW binaries

This section is about using CMake to link GLFW after it has been built and installed. If you want to build it along with your application instead, see With CMake and GLFW source.

With just a few changes to your CMakeLists.txt, you can locate the package and target files generated when GLFW is installed.

    1 find_package(glfw3 3.2 REQUIRED)

Note that the dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU. If your application calls OpenGL directly, instead of using a modern extension loader library you can find it by requiring the OpenGL package.

    1 find_package(OpenGL REQUIRED)

If OpenGL is found, the OPENGL_FOUND variable is true and the OPENGL_INCLUDE_DIR and OPENGL_gl_LIBRARY cache variables can be used.

    1 target_include_directories(myapp ${OPENGL_INCLUDE_DIR})

    2 target_link_libraries(myapp ${OPENGL_gl_LIBRARY})

The OpenGL CMake package also looks for GLU. If GLU is found, the OPENGL_GLU_FOUND variable is true and the OPENGL_INCLUDE_DIR and OPENGL_glu_LIBRARY cache variables can be used.

    1 target_link_libraries(myapp ${OPENGL_glu_LIBRARY})

Note

GLU has been deprecated and should not be used in new code, but some legacy code requires it.

With makefiles and pkg-config on Unix

GLFW supports pkg-config, and the glfw3.pc pkg-config file is generated when the GLFW library is built and is installed along with it. A pkg-config file describes all necessary compile-time and link-time flags and dependencies needed to use a library. When they are updated or if they differ between systems, you will get the correct ones automatically.

A typical compile and link command-line when using the static version of the GLFW library may look like this:

    1 cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`

If you are using the shared version of the GLFW library, simply omit the --static flag.

    1 cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`

You can also use the glfw3.pc file without installing it first, by using the PKG_CONFIG_PATH environment variable.

    1 env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`

The dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU. On OS X, GLU is built into the OpenGL framework, so if you need GLU you don't need to do anything extra. If you need GLU and are using Linux or BSD, you should add the glu pkg-config package.

    1 cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`

Note

GLU has been deprecated and should not be used in new code, but some legacy code requires it.

If you are using the static version of the GLFW library, make sure you don't link statically against GLU.

    1 cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`

With Xcode on OS X

If you are using the dynamic library version of GLFW, simply add it to the project dependencies.

If you are using the static library version of GLFW, add it and the Cocoa, OpenGL, IOKit and CoreVideo frameworks to the project as dependencies. They can all be found in /System/Library/Frameworks.

With command-line on OS X

It is recommended that you use pkg-config when building from the command line on OS X. That way you will get any new dependencies added automatically. If you still wish to build manually, you need to add the required frameworks and libraries to your command-line yourself using the -l and -framework switches.

If you are using the dynamic GLFW library, which is named libglfw.3.dylib, do:

    1 cc -o myprog myprog.c -lglfw -framework Cocoa -framework OpenGL -framework IOKit -framework CoreVideo

If you are using the static library, named libglfw3.a, substitute -lglfw3 for -lglfw.

Note that you do not add the .framework extension to a framework when linking against it from the command-line.

The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing special to do when using GLU. Also note that even though your machine may have libGL-style OpenGL libraries, they are for use with the X Window System and will not work with the OS X native version of GLFW.

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Joysticks</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Macros

Joysticks
Input reference

Macros

#define 	GLFW_JOYSTICK_1   0

#define 	GLFW_JOYSTICK_2   1

#define 	GLFW_JOYSTICK_3   2

#define 	GLFW_JOYSTICK_4   3

#define 	GLFW_JOYSTICK_5   4

#define 	GLFW_JOYSTICK_6   5

#define 	GLFW_JOYSTICK_7   6

#define 	GLFW_JOYSTICK_8   7

#define 	GLFW_JOYSTICK_9   8

#define 	GLFW_JOYSTICK_10   9

#define 	GLFW_JOYSTICK_11   10

#define 	GLFW_JOYSTICK_12   11

#define 	GLFW_JOYSTICK_13   12

#define 	GLFW_JOYSTICK_14   13

#define 	GLFW_JOYSTICK_15   14

#define 	GLFW_JOYSTICK_16   15

#define 	GLFW_JOYSTICK_LAST   GLFW_JOYSTICK_16

Detailed Description

See joystick input for how these are used.

Macro Definition Documentation

          #define GLFW_JOYSTICK_1   0

          #define GLFW_JOYSTICK_10   9

          #define GLFW_JOYSTICK_11   10

          #define GLFW_JOYSTICK_12   11

          #define GLFW_JOYSTICK_13   12

          #define GLFW_JOYSTICK_14   13

          #define GLFW_JOYSTICK_15   14

          #define GLFW_JOYSTICK_16   15

          #define GLFW_JOYSTICK_2   1

          #define GLFW_JOYSTICK_3   2

          #define GLFW_JOYSTICK_4   3

          #define GLFW_JOYSTICK_5   4

          #define GLFW_JOYSTICK_6   5

          #define GLFW_JOYSTICK_7   6

          #define GLFW_JOYSTICK_8   7

          #define GLFW_JOYSTICK_9   8

          #define GLFW_JOYSTICK_LAST   GLFW_JOYSTICK_16

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: GLFWgammaramp Struct Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Data Structures

Data Structure Index

Data Fields

Data Fields

GLFWgammaramp Struct Reference
Monitor reference

Gamma ramp.
 More...

Data Fields

unsigned short * 	red

unsigned short * 	green

unsigned short * 	blue

unsigned int 	size

Detailed Description

This describes the gamma ramp for a monitor.

See also

Gamma ramp

glfwGetGammaRamp glfwSetGammaRamp

Since

Added in version 3.0.

Field Documentation

          unsigned short* GLFWgammaramp::blue

An array of value describing the response of the blue channel.

          unsigned short* GLFWgammaramp::green

An array of value describing the response of the green channel.

          unsigned short* GLFWgammaramp::red

An array of value describing the response of the red channel.

          unsigned int GLFWgammaramp::size

The number of elements in each array.

The documentation for this struct was generated from the following file:

glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

- h -

GLFW_HAND_CURSOR
: glfw3.h

GLFW_HRESIZE_CURSOR
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: intro.dox File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

intro.dox File Reference

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

w

Here is a list of all functions, variables, defines, enums, and typedefs with links to the files they belong to:

- k -

GLFW_KEY_0
: glfw3.h

GLFW_KEY_1
: glfw3.h

GLFW_KEY_2
: glfw3.h

GLFW_KEY_3
: glfw3.h

GLFW_KEY_4
: glfw3.h

GLFW_KEY_5
: glfw3.h

GLFW_KEY_6
: glfw3.h

GLFW_KEY_7
: glfw3.h

GLFW_KEY_8
: glfw3.h

GLFW_KEY_9
: glfw3.h

GLFW_KEY_A
: glfw3.h

GLFW_KEY_APOSTROPHE
: glfw3.h

GLFW_KEY_B
: glfw3.h

GLFW_KEY_BACKSLASH
: glfw3.h

GLFW_KEY_BACKSPACE
: glfw3.h

GLFW_KEY_C
: glfw3.h

GLFW_KEY_CAPS_LOCK
: glfw3.h

GLFW_KEY_COMMA
: glfw3.h

GLFW_KEY_D
: glfw3.h

GLFW_KEY_DELETE
: glfw3.h

GLFW_KEY_DOWN
: glfw3.h

GLFW_KEY_E
: glfw3.h

GLFW_KEY_END
: glfw3.h

GLFW_KEY_ENTER
: glfw3.h

GLFW_KEY_EQUAL
: glfw3.h

GLFW_KEY_ESCAPE
: glfw3.h

GLFW_KEY_F
: glfw3.h

GLFW_KEY_F1
: glfw3.h

GLFW_KEY_F10
: glfw3.h

GLFW_KEY_F11
: glfw3.h

GLFW_KEY_F12
: glfw3.h

GLFW_KEY_F13
: glfw3.h

GLFW_KEY_F14
: glfw3.h

GLFW_KEY_F15
: glfw3.h

GLFW_KEY_F16
: glfw3.h

GLFW_KEY_F17
: glfw3.h

GLFW_KEY_F18
: glfw3.h

GLFW_KEY_F19
: glfw3.h

GLFW_KEY_F2
: glfw3.h

GLFW_KEY_F20
: glfw3.h

GLFW_KEY_F21
: glfw3.h

GLFW_KEY_F22
: glfw3.h

GLFW_KEY_F23
: glfw3.h

GLFW_KEY_F24
: glfw3.h

GLFW_KEY_F25
: glfw3.h

GLFW_KEY_F3
: glfw3.h

GLFW_KEY_F4
: glfw3.h

GLFW_KEY_F5
: glfw3.h

GLFW_KEY_F6
: glfw3.h

GLFW_KEY_F7
: glfw3.h

GLFW_KEY_F8
: glfw3.h

GLFW_KEY_F9
: glfw3.h

GLFW_KEY_G
: glfw3.h

GLFW_KEY_GRAVE_ACCENT
: glfw3.h

GLFW_KEY_H
: glfw3.h

GLFW_KEY_HOME
: glfw3.h

GLFW_KEY_I
: glfw3.h

GLFW_KEY_INSERT
: glfw3.h

GLFW_KEY_J
: glfw3.h

GLFW_KEY_K
: glfw3.h

GLFW_KEY_KP_0
: glfw3.h

GLFW_KEY_KP_1
: glfw3.h

GLFW_KEY_KP_2
: glfw3.h

GLFW_KEY_KP_3
: glfw3.h

GLFW_KEY_KP_4
: glfw3.h

GLFW_KEY_KP_5
: glfw3.h

GLFW_KEY_KP_6
: glfw3.h

GLFW_KEY_KP_7
: glfw3.h

GLFW_KEY_KP_8
: glfw3.h

GLFW_KEY_KP_9
: glfw3.h

GLFW_KEY_KP_ADD
: glfw3.h

GLFW_KEY_KP_DECIMAL
: glfw3.h

GLFW_KEY_KP_DIVIDE
: glfw3.h

GLFW_KEY_KP_ENTER
: glfw3.h

GLFW_KEY_KP_EQUAL
: glfw3.h

GLFW_KEY_KP_MULTIPLY
: glfw3.h

GLFW_KEY_KP_SUBTRACT
: glfw3.h

GLFW_KEY_L
: glfw3.h

GLFW_KEY_LAST
: glfw3.h

GLFW_KEY_LEFT
: glfw3.h

GLFW_KEY_LEFT_ALT
: glfw3.h

GLFW_KEY_LEFT_BRACKET
: glfw3.h

GLFW_KEY_LEFT_CONTROL
: glfw3.h

GLFW_KEY_LEFT_SHIFT
: glfw3.h

GLFW_KEY_LEFT_SUPER
: glfw3.h

GLFW_KEY_M
: glfw3.h

GLFW_KEY_MENU
: glfw3.h

GLFW_KEY_MINUS
: glfw3.h

GLFW_KEY_N
: glfw3.h

GLFW_KEY_NUM_LOCK
: glfw3.h

GLFW_KEY_O
: glfw3.h

GLFW_KEY_P
: glfw3.h

GLFW_KEY_PAGE_DOWN
: glfw3.h

GLFW_KEY_PAGE_UP
: glfw3.h

GLFW_KEY_PAUSE
: glfw3.h

GLFW_KEY_PERIOD
: glfw3.h

GLFW_KEY_PRINT_SCREEN
: glfw3.h

GLFW_KEY_Q
: glfw3.h

GLFW_KEY_R
: glfw3.h

GLFW_KEY_RIGHT
: glfw3.h

GLFW_KEY_RIGHT_ALT
: glfw3.h

GLFW_KEY_RIGHT_BRACKET
: glfw3.h

GLFW_KEY_RIGHT_CONTROL
: glfw3.h

GLFW_KEY_RIGHT_SHIFT
: glfw3.h

GLFW_KEY_RIGHT_SUPER
: glfw3.h

GLFW_KEY_S
: glfw3.h

GLFW_KEY_SCROLL_LOCK
: glfw3.h

GLFW_KEY_SEMICOLON
: glfw3.h

GLFW_KEY_SLASH
: glfw3.h

GLFW_KEY_SPACE
: glfw3.h

GLFW_KEY_T
: glfw3.h

GLFW_KEY_TAB
: glfw3.h

GLFW_KEY_U
: glfw3.h

GLFW_KEY_UNKNOWN
: glfw3.h

GLFW_KEY_UP
: glfw3.h

GLFW_KEY_V
: glfw3.h

GLFW_KEY_W
: glfw3.h

GLFW_KEY_WORLD_1
: glfw3.h

GLFW_KEY_WORLD_2
: glfw3.h

GLFW_KEY_X
: glfw3.h

GLFW_KEY_Y
: glfw3.h

GLFW_KEY_Z
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

w

Here is a list of all functions, variables, defines, enums, and typedefs with links to the files they belong to:

- i -

GLFW_IBEAM_CURSOR
: glfw3.h

GLFW_ICONIFIED
: glfw3.h

GLFW_INVALID_ENUM
: glfw3.h

GLFW_INVALID_VALUE
: glfw3.h

glfwIconifyWindow()
: glfw3.h

glfwInit()
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: main.dox File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

main.dox File Reference

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: New features</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

New features

New features in 3.2

Support for Vulkan

GLFW now supports basic integration with Vulkan with glfwVulkanSupported, glfwGetRequiredInstanceExtensions, glfwGetInstanceProcAddress, glfwGetPhysicalDevicePresentationSupport and glfwCreateWindowSurface. Vulkan header inclusion can be selected with GLFW_INCLUDE_VULKAN.

Window mode switching

GLFW now supports switching between windowed and full screen modes and updating the monitor and desired resolution and refresh rate of full screen windows with glfwSetWindowMonitor.

Window maxmimization support

GLFW now supports window maximization with glfwMaximizeWindow and the GLFW_MAXIMIZED window hint and attribute.

Window input focus control

GLFW now supports giving windows input focus with glfwFocusWindow.

Window size limit support

GLFW now supports setting both absolute and relative window size limits with glfwSetWindowSizeLimits and glfwSetWindowAspectRatio.

Localized key names

GLFW now supports querying the localized name of printable keys with glfwGetKeyName, either by key token or by scancode.

Wait for events with timeout

GLFW now supports waiting for events for a set amount of time with glfwWaitEventsTimeout.

Window icon support

GLFW now supports setting the icon of windows with glfwSetWindowIcon.

Raw timer access

GLFW now supports raw timer values with glfwGetTimerValue and glfwGetTimerFrequency.

Joystick connection callback

GLFW now supports notifying when a joystick has been connected or disconnected with glfwSetJoystickCallback.

Context-less windows

GLFW now supports creating windows without a OpenGL or OpenGL ES context with GLFW_NO_API.

Run-time context creation API selection

GLFW now supports selecting the context creation API at run-time with the GLFW_CONTEXT_CREATION_API window hint value.

Error-free context creation

GLFW now supports creating OpenGL and OpenGL ES contexts that do not emit errors with the GLFW_CONTEXT_NO_ERROR window hint, provided the machine supports the GL_KHR_no_error extension.

CMake config-file package support

GLFW now supports being used as a config-file package from other projects for easy linking with the library and its dependencies.

New features in 3.1

These are the release highlights. For a full list of changes see the version history.

Custom mouse cursor images

GLFW now supports creating and setting both custom cursor images and standard cursor shapes. They are created with glfwCreateCursor or glfwCreateStandardCursor, set with glfwSetCursor and destroyed with glfwDestroyCursor.

See also

Cursor objects

Path drop event

GLFW now provides a callback for receiving the paths of files and directories dropped onto GLFW windows. The callback is set with glfwSetDropCallback.

See also

Path drop input

Main thread wake-up

GLFW now provides the glfwPostEmptyEvent function for posting an empty event from another thread to the main thread event queue, causing glfwWaitEvents to return.

See also

Event processing

Window frame size query

GLFW now supports querying the size, on each side, of the frame around the client area of a window, with glfwGetWindowFrameSize.

See also

Window size

Simultaneous multi-monitor rendering

GLFW now supports disabling auto-iconification of full screen windows with the GLFW_AUTO_ICONIFY window hint. This is intended for people building multi-monitor installations, where you need windows to stay in full screen despite losing input focus.

Floating windows

GLFW now supports floating windows, also called topmost or always on top, for easier debugging with the GLFW_FLOATING window hint.

Initially unfocused windows

GLFW now supports preventing a windowed mode window from gaining input focus on creation, with the GLFW_FOCUSED window hint.

Direct access for window attributes and cursor position

GLFW now queries the window input focus, visibility and iconification attributes and the cursor position directly instead of returning cached data.

Character with modifiers callback

GLFW now provides a callback for character events with modifier key bits. The callback is set with glfwSetCharModsCallback. Unlike the regular character callback, this will report character events that will not result in a character being input, for example if the Control key is held down.

See also

Text input

Single buffered framebuffers

GLFW now supports the creation of single buffered windows, with the GLFW_DOUBLEBUFFER window hint.

Macro for including extension header

GLFW now includes the extension header appropriate for the chosen OpenGL or OpenGL ES header when GLFW_INCLUDE_GLEXT is defined. GLFW does not provide these headers. They must be provided by your development environment or your OpenGL or OpenGL ES SDK.

Context release behaviors

GLFW now supports controlling whether the pipeline is flushed when a context is made non-current, with the GLFW_CONTEXT_RELEASE_BEHAVIOR window hint, provided the machine supports the GL_KHR_context_flush_control extension.

(Experimental) Wayland support

GLFW now has an experimental Wayland display protocol backend that can be selected on Linux with a CMake option.

(Experimental) Mir support

GLFW now has an experimental Mir display server backend that can be selected on Linux with a CMake option.

New features in 3.0

These are the release highlights. For a full list of changes see the version history.

CMake build system

GLFW now uses the CMake build system instead of the various makefiles and project files used by earlier versions. CMake is available for all platforms supported by GLFW, is present in most package systems and can generate makefiles and/or project files for most popular development environments.

For more information on how to use CMake, see the CMake manual.

Multi-window support

GLFW now supports the creation of multiple windows, each with their own OpenGL or OpenGL ES context, and all window functions now take a window handle. Event callbacks are now per-window and are provided with the handle of the window that received the event. The glfwMakeContextCurrent function has been added to select which context is current on a given thread.

Multi-monitor support

GLFW now explicitly supports multiple monitors. They can be enumerated with glfwGetMonitors, queried with glfwGetVideoModes, glfwGetMonitorPos, glfwGetMonitorName and glfwGetMonitorPhysicalSize, and specified at window creation to make the newly created window full screen on that specific monitor.

Unicode support

All string arguments to GLFW functions and all strings returned by GLFW now use the UTF-8 encoding. This includes the window title, error string, clipboard text, monitor and joystick names as well as the extension function arguments (as ASCII is a subset of UTF-8).

Clipboard text I/O

GLFW now supports reading and writing plain text to and from the system clipboard, with the glfwGetClipboardString and glfwSetClipboardString functions.

Gamma ramp support

GLFW now supports setting and reading back the gamma ramp of monitors, with the glfwGetGammaRamp and glfwSetGammaRamp functions. There is also glfwSetGamma, which generates a ramp from a gamma value and then sets it.

OpenGL ES support

GLFW now supports the creation of OpenGL ES contexts, by setting the GLFW_CLIENT_API window hint to GLFW_OPENGL_ES_API, where creation of such contexts are supported. Note that GLFW does not implement OpenGL ES, so your driver must provide support in a way usable by GLFW. Modern Nvidia and Intel drivers support creation of OpenGL ES context using the GLX and WGL APIs, while AMD provides an EGL implementation instead.

(Experimental) EGL support

GLFW now has an experimental EGL context creation back end that can be selected through CMake options.

High-DPI support

GLFW now supports high-DPI monitors on both Windows and OS X, giving windows full resolution framebuffers where other UI elements are scaled up. To achieve this, glfwGetFramebufferSize and glfwSetFramebufferSizeCallback have been added. These work with pixels, while the rest of the GLFW API works with screen coordinates. This is important as OpenGL uses pixels, not screen coordinates.

Error callback

GLFW now has an error callback, which can provide your application with much more detailed diagnostics than was previously possible. The callback is passed an error code and a description string.

Per-window user pointer

Each window now has a user-defined pointer, retrieved with glfwGetWindowUserPointer and set with glfwSetWindowUserPointer, to make it easier to integrate GLFW into C++ code.

Window iconification callback

Each window now has a callback for iconification and restoration events, which is set with glfwSetWindowIconifyCallback.

Window position callback

Each window now has a callback for position events, which is set with glfwSetWindowPosCallback.

Window position query

The position of a window can now be retrieved using glfwGetWindowPos.

Window focus callback

Each windows now has a callback for focus events, which is set with glfwSetWindowFocusCallback.

Cursor enter/leave callback

Each window now has a callback for when the mouse cursor enters or leaves its client area, which is set with glfwSetCursorEnterCallback.

Initial window title

The title of a window is now specified at creation time, as one of the arguments to glfwCreateWindow.

Hidden windows

Windows can now be hidden with glfwHideWindow, shown using glfwShowWindow and created initially hidden with the GLFW_VISIBLE window hint. This allows for off-screen rendering in a way compatible with most drivers, as well as moving a window to a specific position before showing it.

Undecorated windows

Windowed mode windows can now be created without decorations, e.g. things like a frame, a title bar, with the GLFW_DECORATED window hint. This allows for the creation of things like splash screens.

Modifier key bit masks

Modifier key bit mask parameters have been added to the mouse button and key callbacks.

Platform-specific scancodes

A scancode parameter has been added to the key callback. Keys that don't have a key token still get passed on with the key parameter set to GLFW_KEY_UNKNOWN. These scancodes will vary between machines and are intended to be used for key bindings.

Joystick names

The name of a joystick can now be retrieved using glfwGetJoystickName.

Doxygen documentation

You are reading it.

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

- t -

GLFW_TRUE
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Input guide</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Input guide

Table of Contents

Event processing

Keyboard input

Key input

Text input

Key names

Mouse input

Cursor position

Cursor modes

Cursor objects

Custom cursor creation

Standard cursor creation

Cursor destruction

Cursor setting

Cursor enter/leave events

Mouse button input

Scroll input

Joystick input

Joystick axis states

Joystick button states

Joystick name

Joystick configuration changes

Time input

Clipboard input and output

Path drop input

This guide introduces the input related functions of GLFW. For details on a specific function in this category, see the Input reference. There are also guides for the other areas of GLFW.

Introduction to the API

Window guide

Context guide

Vulkan guide

Monitor guide

GLFW provides many kinds of input. While some can only be polled, like time, or only received via callbacks, like scrolling, there are those that provide both callbacks and polling. Where a callback is provided, that is the recommended way to receive that kind of input. The more you can use callbacks the less time your users' machines will need to spend polling.

All input callbacks receive a window handle. By using the window user pointer, you can access non-global structures or objects from your callbacks.

To get a better feel for how the various events callbacks behave, run the events test program. It register every callback supported by GLFW and prints out all arguments provided for every event, along with time and sequence information.

Event processing

GLFW needs to communicate regularly with the window system both in order to receive events and to show that the application hasn't locked up. Event processing must be done regularly while you have any windows and is normally done each frame after buffer swapping. Even when you have no windows, event polling needs to be done in order to receive monitor connection events.

There are two functions for processing pending events. glfwPollEvents, processes only those events that have already been received and then returns immediately.

glfwPollEvents();

This is the best choice when rendering continually, like most games do.

If you only need to update the contents of the window when you receive new input, glfwWaitEvents is a better choice.

glfwWaitEvents();

It puts the thread to sleep until at least one event has been received and then processes all received events. This saves a great deal of CPU cycles and is useful for, for example, editing tools. There must be at least one GLFW window for this function to sleep.

If you want to wait for events but have UI elements that need periodic updates, call glfwWaitEventsTimeout.

glfwWaitEventsTimeout(0.7);

It puts the thread to sleep until at least one event has been received, or until the specified number of seconds have elapsed. It then processes any received events.

If the main thread is sleeping in glfwWaitEvents, you can wake it from another thread by posting an empty event to the event queue with glfwPostEmptyEvent.

glfwPostEmptyEvent();

Do not assume that callbacks will only be called through either of the above functions. While it is necessary to process events in the event queue, some window systems will send some events directly to the application, which in turn causes callbacks to be called outside of regular event processing.

Keyboard input

GLFW divides keyboard input into two categories; key events and character events. Key events relate to actual physical keyboard keys, whereas character events relate to the Unicode code points generated by pressing some of them.

Keys and characters do not map 1:1. A single key press may produce several characters, and a single character may require several keys to produce. This may not be the case on your machine, but your users are likely not all using the same keyboard layout, input method or even operating system as you.

Key input

If you wish to be notified when a physical key is pressed or released or when it repeats, set a key callback.

glfwSetKeyCallback(window, key_callback);

The callback function receives the keyboard key, platform-specific scancode, key action and modifier bits.

void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)

{

    if (key == GLFW_KEY_E && action == GLFW_PRESS)

        activate_airship();

}

The action is one of GLFW_PRESS, GLFW_REPEAT or GLFW_RELEASE. The key will be GLFW_KEY_UNKNOWN if GLFW lacks a key token for it, for example E-mail and Play keys.

The scancode is unique for every key, regardless of whether it has a key token. Scancodes are platform-specific but consistent over time, so keys will have different scancodes depending on the platform but they are safe to save to disk.

Key states for named keys are also saved in per-window state arrays that can be polled with glfwGetKey.

int state = glfwGetKey(window, GLFW_KEY_E);

if (state == GLFW_PRESS)

    activate_airship();

The returned state is one of GLFW_PRESS or GLFW_RELEASE.

This function only returns cached key event state. It does not poll the system for the current state of the key.

Whenever you poll state, you risk missing the state change you are looking for. If a pressed key is released again before you poll its state, you will have missed the key press. The recommended solution for this is to use a key callback, but there is also the GLFW_STICKY_KEYS input mode.

glfwSetInputMode(window, GLFW_STICKY_KEYS, 1);

When sticky keys mode is enabled, the pollable state of a key will remain GLFW_PRESS until the state of that key is polled with glfwGetKey. Once it has been polled, if a key release event had been processed in the meantime, the state will reset to GLFW_RELEASE, otherwise it will remain GLFW_PRESS.

The GLFW_KEY_LAST constant holds the highest value of any named key.

Text input

GLFW supports text input in the form of a stream of Unicode code points, as produced by the operating system text input system. Unlike key input, text input obeys keyboard layouts and modifier keys and supports composing characters using dead keys. Once received, you can encode the code points into UTF-8 or any other encoding you prefer.

Because an unsigned int is 32 bits long on all platforms supported by GLFW, you can treat the code point argument as native endian UTF-32.

There are two callbacks for receiving Unicode code points. If you wish to offer regular text input, set a character callback.

glfwSetCharCallback(window, character_callback);

The callback function receives Unicode code points for key events that would have led to regular text input and generally behaves as a standard text field on that platform.

void character_callback(GLFWwindow* window, unsigned int codepoint)

{

}

If you wish to receive even those Unicode code points generated with modifier key combinations that a plain text field would ignore, or just want to know exactly what modifier keys were used, set a character with modifiers callback.

glfwSetCharModsCallback(window, charmods_callback);

The callback function receives Unicode code points and modifier bits.

void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods)

{

}

Key names

If you wish to refer to keys by name, you can query the keyboard layout dependent name of printable keys with glfwGetKeyName.

const char* key_name = glfwGetKeyName(GLFW_KEY_W, 0);

show_tutorial_hint("Press %s to move forward", key_name);

This function can handle both keys and scancodes. If the specified key is GLFW_KEY_UNKNOWN then the scancode is used, otherwise it is ignored. This matches the behavior of the key callback, meaning the callback arguments can always be passed unmodified to this function.

Mouse input

Mouse input comes in many forms, including cursor motion, button presses and scrolling offsets. The cursor appearance can also be changed, either to a custom image or a standard cursor shape from the system theme.

Cursor position

If you wish to be notified when the cursor moves over the window, set a cursor position callback.

glfwSetCursorPosCallback(window, cursor_pos_callback);

The callback functions receives the cursor position, measured in screen coordinates but relative to the top-left corner of the window client area. On platforms that provide it, the full sub-pixel cursor position is passed on.

static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos)

{

}

The cursor position is also saved per-window and can be polled with glfwGetCursorPos.

double xpos, ypos;

glfwGetCursorPos(window, &xpos, &ypos);

Cursor modes

The GLFW_CURSOR input mode provides several cursor modes for special forms of mouse motion input. By default, the cursor mode is GLFW_CURSOR_NORMAL, meaning the regular arrow cursor (or another cursor set with glfwSetCursor) is used and cursor motion is not limited.

If you wish to implement mouse motion based camera controls or other input schemes that require unlimited mouse movement, set the cursor mode to GLFW_CURSOR_DISABLED.

glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED);

This will hide the cursor and lock it to the specified window. GLFW will then take care of all the details of cursor re-centering and offset calculation and providing the application with a virtual cursor position. This virtual position is provided normally via both the cursor position callback and through polling.

Note

You should not implement your own version of this functionality using other features of GLFW. It is not supported and will not work as robustly as GLFW_CURSOR_DISABLED.

If you just wish the cursor to become hidden when it is over a window, set the cursor mode to GLFW_CURSOR_HIDDEN.

glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN);

This mode puts no limit on the motion of the cursor.

To exit out of either of these special modes, restore the GLFW_CURSOR_NORMAL cursor mode.

glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL);

Cursor objects

GLFW supports creating both custom and system theme cursor images, encapsulated as GLFWcursor objects. They are created with glfwCreateCursor or glfwCreateStandardCursor and destroyed with glfwDestroyCursor, or glfwTerminate, if any remain.

Custom cursor creation

A custom cursor is created with glfwCreateCursor, which returns a handle to the created cursor object. For example, this creates a 16x16 white square cursor with the hot-spot in the upper-left corner:

unsigned char pixels[16 * 16 * 4];

memset(pixels, 0xff, sizeof(pixels));

GLFWimage image;

image.width = 16;

image.height = 16;

image.pixels = pixels;

GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);

If cursor creation fails, NULL will be returned, so it is necessary to check the return value.

The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits per channel. The pixels are arranged canonically as sequential rows, starting from the top-left corner.

Standard cursor creation

A cursor with a standard shape from the current system cursor theme can be can be created with glfwCreateStandardCursor.

GLFWcursor* cursor = glfwCreateStandardCursor(GLFW_HRESIZE_CURSOR);

These cursor objects behave in the exact same way as those created with glfwCreateCursor except that the system cursor theme provides the actual image.

Cursor destruction

When a cursor is no longer needed, destroy it with glfwDestroyCursor.

glfwDestroyCursor(cursor);

Cursor destruction always succeeds. All cursors remaining when glfwTerminate is called are destroyed as well.

Cursor setting

A cursor can be set as current for a window with glfwSetCursor.

glfwSetCursor(window, cursor);

Once set, the cursor image will be used as long as the system cursor is over the client area of the window and the cursor mode is set to GLFW_CURSOR_NORMAL.

A single cursor may be set for any number of windows.

To remove a cursor from a window, set the cursor of that window to NULL.

glfwSetCursor(window, NULL);

When a cursor is destroyed, it is removed from any window where it is set. This does not affect the cursor modes of those windows.

Cursor enter/leave events

If you wish to be notified when the cursor enters or leaves the client area of a window, set a cursor enter/leave callback.

glfwSetCursorEnterCallback(window, cursor_enter_callback);

The callback function receives the new classification of the cursor.

void cursor_enter_callback(GLFWwindow* window, int entered)

{

    if (entered)

    {

        // The cursor entered the client area of the window

    }

    else

    {

        // The cursor left the client area of the window

    }

}

Mouse button input

If you wish to be notified when a mouse button is pressed or released, set a mouse button callback.

glfwSetMouseButtonCallback(window, mouse_button_callback);

The callback function receives the mouse button, button action and modifier bits.

void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)

{

    if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS)

        popup_menu();

}

The action is one of GLFW_PRESS or GLFW_RELEASE.

Mouse button states for named buttons are also saved in per-window state arrays that can be polled with glfwGetMouseButton.

int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);

if (state == GLFW_PRESS)

    upgrade_cow();

The returned state is one of GLFW_PRESS or GLFW_RELEASE.

This function only returns cached mouse button event state. It does not poll the system for the current state of the mouse button.

Whenever you poll state, you risk missing the state change you are looking for. If a pressed mouse button is released again before you poll its state, you will have missed the button press. The recommended solution for this is to use a mouse button callback, but there is also the GLFW_STICKY_MOUSE_BUTTONS input mode.

glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, 1);

When sticky mouse buttons mode is enabled, the pollable state of a mouse button will remain GLFW_PRESS until the state of that button is polled with glfwGetMouseButton. Once it has been polled, if a mouse button release event had been processed in the meantime, the state will reset to GLFW_RELEASE, otherwise it will remain GLFW_PRESS.

The GLFW_MOUSE_BUTTON_LAST constant holds the highest value of any named button.

Scroll input

If you wish to be notified when the user scrolls, whether with a mouse wheel or touchpad gesture, set a scroll callback.

glfwSetScrollCallback(window, scroll_callback);

The callback function receives two-dimensional scroll offsets.

void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)

{

}

A simple mouse wheel, being vertical, provides offsets along the Y-axis.

Joystick input

The joystick functions expose connected joysticks and controllers, with both referred to as joysticks. It supports up to sixteen joysticks, ranging from GLFW_JOYSTICK_1, GLFW_JOYSTICK_2 up to GLFW_JOYSTICK_LAST. You can test whether a joystick is present with glfwJoystickPresent.

int present = glfwJoystickPresent(GLFW_JOYSTICK_1);

When GLFW is initialized, detected joysticks are added to to the beginning of the array, starting with GLFW_JOYSTICK_1. Once a joystick is detected, it keeps its assigned index until it is disconnected, so as joysticks are connected and disconnected, they will become spread out.

Joystick state is updated as needed when a joystick function is called and does not require a window to be created or glfwPollEvents or glfwWaitEvents to be called.

Joystick axis states

The positions of all axes of a joystick are returned by glfwGetJoystickAxes. See the reference documentation for the lifetime of the returned array.

int count;

const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_1, &count);

Each element in the returned array is a value between -1.0 and 1.0.

Joystick button states

The states of all buttons of a joystick are returned by glfwGetJoystickButtons. See the reference documentation for the lifetime of the returned array.

int count;

const unsigned char* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count);

Each element in the returned array is either GLFW_PRESS or GLFW_RELEASE.

Joystick name

The human-readable, UTF-8 encoded name of a joystick is returned by glfwGetJoystickName. See the reference documentation for the lifetime of the returned string.

const char* name = glfwGetJoystickName(GLFW_JOYSTICK_1);

Joystick names are not guaranteed to be unique. Two joysticks of the same model and make may have the same name. Only the joystick token is guaranteed to be unique, and only until that joystick is disconnected.

Joystick configuration changes

If you wish to be notified when a joystick is connected or disconnected, set a joystick callback.

glfwSetJoystickCallback(joystick_callback);

The callback function receives the ID of the joystick that has been connected and disconnected and the event that occurred.

void joystick_callback(int joy, int event)

{

    if (event == GLFW_CONNECTED)

    {

        // The joystick was connected

    }

    else if (event == GLFW_DISCONNECTED)

    {

        // The joystick was disconnected

    }

}

Time input

GLFW provides high-resolution time input, in seconds, with glfwGetTime.

double seconds = glfwGetTime();

It returns the number of seconds since the timer was started when the library was initialized with glfwInit. The platform-specific time sources used usually have micro- or nanosecond resolution.

You can modify the reference time with glfwSetTime.

glfwSetTime(4.0);

This sets the timer to the specified time, in seconds.

You can also access the raw timer value, measured in 1 / frequency seconds, with glfwGetTimerValue.

uint64_t value = glfwGetTimerValue();

The frequency of the raw timer varies depending on what time sources are available on the machine. You can query its frequency, in Hz, with glfwGetTimerFrequency.

uint64_t freqency = glfwGetTimerFrequency();

Clipboard input and output

If the system clipboard contains a UTF-8 encoded string or if it can be converted to one, you can retrieve it with glfwGetClipboardString. See the reference documentation for the lifetime of the returned string.

const char* text = glfwGetClipboardString(window);

if (text)

    insert_text(text);

If the clipboard is empty or if its contents could not be converted, NULL is returned.

The contents of the system clipboard can be set to a UTF-8 encoded string with glfwSetClipboardString.

glfwSetClipboardString(window, "A string with words in it");

The clipboard functions take a window handle argument because some window systems require a window to communicate with the system clipboard. Any valid window may be used.

Path drop input

If you wish to receive the paths of files and/or directories dropped on a window, set a file drop callback.

glfwSetDropCallback(window, drop_callback);

The callback function receives an array of paths encoded as UTF-8.

void drop_callback(GLFWwindow* window, int count, const char** paths)

{

    int i;

    for (i = 0;  i < count;  i++)

        handle_dropped_file(paths[i]);

}

The path array and its strings are only valid until the file drop callback returns, as they may have been generated specifically for that event. You need to make a deep copy of the array if you want to keep the paths.

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Introduction to the API</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

Introduction to the API

Table of Contents

Initialization and termination

Initializing GLFW

Terminating GLFW

Error handling

Coordinate systems

Guarantees and limitations

Pointer lifetimes

Reentrancy

Thread safety

Version compatibility

Event order

Version management

Compile-time version

Run-time version

Version string

This guide introduces the basic concepts of GLFW and describes initialization, error handling and API guarantees and limitations. For a broad but shallow tutorial, see Getting started instead. For details on a specific function in this category, see the Initialization, version and error reference.

There are also guides for the other areas of GLFW.

Window guide

Context guide

Vulkan guide

Monitor guide

Input guide

Initialization and termination

Before most GLFW functions may be called, the library must be initialized. This initialization checks what features are available on the machine, enumerates monitors and joysticks, initializes the timer and performs any required platform-specific initialization.

Only the following functions may be called before the library has been successfully initialized, and only from the main thread.

glfwGetVersion

glfwGetVersionString

glfwSetErrorCallback

glfwInit

glfwTerminate

Calling any other function before successful initialization will cause a GLFW_NOT_INITIALIZED error.

Initializing GLFW

The library is initialized with glfwInit, which returns GLFW_FALSE if an error occurred.

if (!glfwInit())

{

    // Handle initialization failure

}

If any part of initialization fails, any parts that succeeded are terminated as if glfwTerminate had been called. The library only needs to be initialized once and additional calls to an already initialized library will simply return GLFW_TRUE immediately.

Once the library has been successfully initialized, it should be terminated before the application exits. Modern systems are very good at freeing resources allocated by programs that simply exit, but GLFW sometimes has to change global system settings and these might not be restored without termination.

Terminating GLFW

Before your application exits, you should terminate the GLFW library if it has been initialized. This is done with glfwTerminate.

glfwTerminate();

This will destroy any remaining window, monitor and cursor objects, restore any modified gamma ramps, re-enable the screensaver if it had been disabled and free any other resources allocated by GLFW.

Once the library is terminated, it is as if it had never been initialized and you will need to initialize it again before being able to use GLFW. If the library was not initialized or had already been terminated, it return immediately.

Error handling

Some GLFW functions have return values that indicate an error, but this is often not very helpful when trying to figure out why the error occurred. Some functions also return otherwise valid values on error. Finally, far from all GLFW functions have return values.

This is where the error callback comes in. This callback is called whenever an error occurs. It is set with glfwSetErrorCallback, a function that may be called regardless of whether GLFW is initialized.

glfwSetErrorCallback(error_callback);

The error callback receives a human-readable description of the error and (when possible) its cause. The description encoded as UTF-8. The callback is also provided with an error code.

void error_callback(int error, const char* description)

{

    puts(description);

}

The error code indicates the general category of the error. Some error codes, such as GLFW_NOT_INITIALIZED has only a single meaning, whereas others like GLFW_PLATFORM_ERROR are used for many different errors.

The description string is only valid until the error callback returns, as it may have been generated specifically for that error. This lets GLFW provide much more specific error descriptions but means you must make a copy if you want to keep the description string.

Note

Relying on erroneous behavior is not forward compatible. In other words, do not rely on a currently invalid call to generate a specific error, as that same call may in future versions generate a different error or become valid.

Coordinate systems

GLFW has two primary coordinate systems: the virtual screen and the window client area or content area. Both use the same unit: virtual screen coordinates, or just screen coordinates, which don't necessarily correspond to pixels.

Both the virtual screen and the client area coordinate systems have the X-axis pointing to the right and the Y-axis pointing down.

Window and monitor positions are specified as the position of the upper-left corners of their content areas relative to the virtual screen, while cursor positions are specified relative to a window's client area.

Because the origin of the window's client area coordinate system is also the point from which the window position is specified, you can translate client area coordinates to the virtual screen by adding the window position. The window frame, when present, extends out from the client area but does not affect the window position.

Almost all positions and sizes in GLFW are measured in screen coordinates relative to one of the two origins above. This includes cursor positions, window positions and sizes, window frame sizes, monitor positions and video mode resolutions.

Two exceptions are the monitor physical size, which is measured in millimetres, and framebuffer size, which is measured in pixels.

Pixels and screen coordinates may map 1:1 on your machine, but they won't on every other machine, for example on a Mac with a Retina display. The ratio between screen coordinates and pixels may also change at run-time depending on which monitor the window is currently considered to be on.

Guarantees and limitations

This section describes the conditions under which GLFW can be expected to function, barring bugs in the operating system or drivers. Use of GLFW outside of these limits may work on some platforms, or on some machines, or some of the time, or on some versions of GLFW, but it may break at any time and this will not be considered a bug.

Pointer lifetimes

GLFW will never free any pointer you provide to it and you must never free any pointer it provides to you.

Many GLFW functions return pointers to dynamically allocated structures, strings or arrays, and some callbacks are provided with strings or arrays. These are always managed by GLFW and should never be freed by the application. The lifetime of these pointers is documented for each GLFW function and callback. If you need to keep this data, you must copy it before its lifetime expires.

Many GLFW functions accept pointers to structures or strings allocated by the application. These are never freed by GLFW and are always the responsibility of the application. If GLFW needs to keep the data in these structures or strings, it is copied before the function returns.

Pointer lifetimes are guaranteed not to be shortened in future minor or patch releases.

Reentrancy

GLFW event processing and object creation and destruction are not reentrant. This means that the following functions must not be called from any callback function:

glfwCreateWindow

glfwDestroyWindow

glfwCreateCursor

glfwCreateStandardCursor

glfwDestroyCursor

glfwPollEvents

glfwWaitEvents

glfwWaitEventsTimeout

glfwTerminate

These functions may be made reentrant in future minor or patch releases, but functions not on this list will not be made non-reentrant.

Thread safety

Most GLFW functions must only be called from the main thread, but some may be called from any thread. However, no GLFW function may be called from any thread but the main thread until GLFW has been successfully initialized, including functions that may called before initialization.

The reference documentation for every GLFW function states whether it is limited to the main thread.

Initialization and termination, event processing and the creation and destruction of windows, contexts and cursors are all limited to the main thread due to limitations of one or several platforms.

Because event processing must be performed on the main thread, all callbacks except for the error callback will only be called on that thread. The error callback may be called on any thread, as any GLFW function may generate errors.

The posting of empty events may be done from any thread. The window user pointer and close flag may also be accessed and modified from any thread, but this is not synchronized by GLFW. The following window related functions may be called from any thread:

glfwPostEmptyEvent

glfwGetWindowUserPointer

glfwSetWindowUserPointer

glfwWindowShouldClose

glfwSetWindowShouldClose

Rendering may be done on any thread. The following context related functions may be called from any thread:

glfwMakeContextCurrent

glfwGetCurrentContext

glfwSwapBuffers

glfwSwapInterval

glfwExtensionSupported

glfwGetProcAddress

The raw timer may be queried from any thread. The following raw timer related functions may be called from any thread:

glfwGetTimerFrequency

glfwGetTimerValue

The regular timer may be used from any thread, but the reading and writing of the timer offset is not synchronized by GLFW. The following timer related functions may be called from any thread:

glfwGetTime

glfwSetTime

Library version information may be queried from any thread. The following version related functions may be called from any thread:

glfwGetVersion

glfwGetVersionString

Vulkan objects may be created and information queried from any thread. The following Vulkan related functions may be called from any thread:

glfwVulkanSupported

glfwGetRequiredInstanceExtensions

glfwGetInstanceProcAddress

glfwGetPhysicalDevicePresentationSupport

glfwCreateWindowSurface

GLFW uses no synchronization objects internally except for thread-local storage to keep track of the current context for each thread. Synchronization is left to the application.

Functions that may currently be called from any thread will always remain so, but functions that are currently limited to the main thread may be updated to allow calls from any thread in future releases.

Version compatibility

GLFW guarantees source and binary backward compatibility with earlier minor versions of the API. This means that you can drop in a newer version of the library and existing programs will continue to compile and existing binaries will continue to run.

Once a function or constant has been added, the signature of that function or value of that constant will remain unchanged until the next major version of GLFW. No compatibility of any kind is guaranteed between major versions.

Undocumented behavior, i.e. behavior that is not described in the documentation, may change at any time until it is documented.

If the reference documentation and the implementation differ, the reference documentation is correct and the implementation will be fixed in the next release.

Event order

The order of arrival of related events is not guaranteed to be consistent across platforms. The exception is synthetic key and mouse button release events, which are always delivered after the window defocus event.

Version management

GLFW provides mechanisms for identifying what version of GLFW your application was compiled against as well as what version it is currently running against. If you are loading GLFW dynamically (not just linking dynamically), you can use this to verify that the library binary is compatible with your application.

Compile-time version

The compile-time version of GLFW is provided by the GLFW header with the GLFW_VERSION_MAJOR, GLFW_VERSION_MINOR and GLFW_VERSION_REVISION macros.

printf("Compiled against GLFW %i.%i.%i\n",

       GLFW_VERSION_MAJOR,

       GLFW_VERSION_MINOR,

       GLFW_VERSION_REVISION);

Run-time version

The run-time version can be retrieved with glfwGetVersion, a function that may be called regardless of whether GLFW is initialized.

int major, minor, revision;

glfwGetVersion(&major, &minor, &revision);

printf("Running against GLFW %i.%i.%i\n", major, minor, revision);

Version string

GLFW 3 also provides a compile-time generated version string that describes the version, platform, compiler and any platform-specific compile-time options. This is primarily intended for submitting bug reports, to allow developers to see which code paths are enabled in a binary.

The version string is returned by glfwGetVersionString, a function that may be called regardless of whether GLFW is initialized.

Do not use the version string to parse the GLFW library version. The glfwGetVersion function already provides the version of the running library binary.

The format of the string is as follows:

The version of GLFW

The name of the window system API

The name of the context creation API

Any additional options or APIs

For example, when compiling GLFW 3.0 with MinGW using the Win32 and WGL back ends, the version string may look something like this:

3.0.0 Win32 WGL MinGW

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

w

Here is a list of all functions, variables, defines, enums, and typedefs with links to the files they belong to:

- r -

GLFW_RED_BITS
: glfw3.h

GLFW_REFRESH_RATE
: glfw3.h

GLFW_RELEASE
: glfw3.h

GLFW_RELEASE_BEHAVIOR_FLUSH
: glfw3.h

GLFW_RELEASE_BEHAVIOR_NONE
: glfw3.h

GLFW_REPEAT
: glfw3.h

GLFW_RESIZABLE
: glfw3.h

glfwRestoreWindow()
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

w

Here is a list of all functions, variables, defines, enums, and typedefs with links to the files they belong to:

- t -

GLFW_TRUE
: glfw3.h

glfwTerminate()
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>


text:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>GLFW: Globals</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>

<link href="search/search.css" rel="stylesheet" type="text/css"/>

<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>

		GLFW

Documentation

Download

Media

Community

Main Page

Related Pages

Modules

Data Structures

Files

          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)"
               onblur="searchBox.OnSearchFieldFocus(false)"
               onkeyup="searchBox.OnSearchFieldChange(event)"/>

File List

Globals

All

Functions

Typedefs

Macros

a

b

c

d

e

f

g

h

i

j

k

l

m

n

o

p

r

s

t

v

w

Here is a list of all functions, variables, defines, enums, and typedefs with links to the files they belong to:

- g -

GLFW_GREEN_BITS
: glfw3.h

GLFWcharfun
: glfw3.h

GLFWcharmodsfun
: glfw3.h

GLFWcursor
: glfw3.h

GLFWcursorenterfun
: glfw3.h

GLFWcursorposfun
: glfw3.h

GLFWdropfun
: glfw3.h

GLFWerrorfun
: glfw3.h

GLFWframebuffersizefun
: glfw3.h

GLFWgammaramp
: glfw3.h

glfwGetClipboardString()
: glfw3.h

glfwGetCocoaMonitor()
: glfw3native.h

glfwGetCocoaWindow()
: glfw3native.h

glfwGetCurrentContext()
: glfw3.h

glfwGetCursorPos()
: glfw3.h

glfwGetEGLContext()
: glfw3native.h

glfwGetEGLDisplay()
: glfw3native.h

glfwGetEGLSurface()
: glfw3native.h

glfwGetFramebufferSize()
: glfw3.h

glfwGetGammaRamp()
: glfw3.h

glfwGetGLXContext()
: glfw3native.h

glfwGetGLXWindow()
: glfw3native.h

glfwGetInputMode()
: glfw3.h

glfwGetInstanceProcAddress()
: glfw3.h

glfwGetJoystickAxes()
: glfw3.h

glfwGetJoystickButtons()
: glfw3.h

glfwGetJoystickName()
: glfw3.h

glfwGetKey()
: glfw3.h

glfwGetKeyName()
: glfw3.h

glfwGetMirDisplay()
: glfw3native.h

glfwGetMirMonitor()
: glfw3native.h

glfwGetMirWindow()
: glfw3native.h

glfwGetMonitorName()
: glfw3.h

glfwGetMonitorPhysicalSize()
: glfw3.h

glfwGetMonitorPos()
: glfw3.h

glfwGetMonitors()
: glfw3.h

glfwGetMouseButton()
: glfw3.h

glfwGetNSGLContext()
: glfw3native.h

glfwGetPhysicalDevicePresentationSupport()
: glfw3.h

glfwGetPrimaryMonitor()
: glfw3.h

glfwGetProcAddress()
: glfw3.h

glfwGetRequiredInstanceExtensions()
: glfw3.h

glfwGetTime()
: glfw3.h

glfwGetTimerFrequency()
: glfw3.h

glfwGetTimerValue()
: glfw3.h

glfwGetVersion()
: glfw3.h

glfwGetVersionString()
: glfw3.h

glfwGetVideoMode()
: glfw3.h

glfwGetVideoModes()
: glfw3.h

glfwGetWaylandDisplay()
: glfw3native.h

glfwGetWaylandMonitor()
: glfw3native.h

glfwGetWaylandWindow()
: glfw3native.h

glfwGetWGLContext()
: glfw3native.h

glfwGetWin32Adapter()
: glfw3native.h

glfwGetWin32Monitor()
: glfw3native.h

glfwGetWin32Window()
: glfw3native.h

glfwGetWindowAttrib()
: glfw3.h

glfwGetWindowFrameSize()
: glfw3.h

glfwGetWindowMonitor()
: glfw3.h

glfwGetWindowPos()
: glfw3.h

glfwGetWindowSize()
: glfw3.h

glfwGetWindowUserPointer()
: glfw3.h

glfwGetX11Adapter()
: glfw3native.h

glfwGetX11Display()
: glfw3native.h

glfwGetX11Monitor()
: glfw3native.h

glfwGetX11Window()
: glfw3native.h

GLFWglproc
: glfw3.h

GLFWimage
: glfw3.h

GLFWjoystickfun
: glfw3.h

GLFWkeyfun
: glfw3.h

GLFWmonitor
: glfw3.h

GLFWmonitorfun
: glfw3.h

GLFWmousebuttonfun
: glfw3.h

GLFWscrollfun
: glfw3.h

GLFWvidmode
: glfw3.h

GLFWvkproc
: glfw3.h

GLFWwindow
: glfw3.h

GLFWwindowclosefun
: glfw3.h

GLFWwindowfocusfun
: glfw3.h

GLFWwindowiconifyfun
: glfw3.h

GLFWwindowposfun
: glfw3.h

GLFWwindowrefreshfun
: glfw3.h

GLFWwindowsizefun
: glfw3.h

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>