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: Standard cursor shapes</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

Standard cursor shapes
Input reference

Macros

#define 	GLFW_ARROW_CURSOR   0x00036001

 	The regular arrow cursor shape.  More...

#define 	GLFW_IBEAM_CURSOR   0x00036002

 	The text input I-beam cursor shape.  More...

#define 	GLFW_CROSSHAIR_CURSOR   0x00036003

 	The crosshair shape.  More...

#define 	GLFW_HAND_CURSOR   0x00036004

 	The hand shape.  More...

#define 	GLFW_HRESIZE_CURSOR   0x00036005

 	The horizontal resize arrow shape.  More...

#define 	GLFW_VRESIZE_CURSOR   0x00036006

 	The vertical resize arrow shape.  More...

Detailed Description

See standard cursor creation for how these are used.

Macro Definition Documentation

          #define GLFW_ARROW_CURSOR   0x00036001

The regular arrow cursor.

          #define GLFW_CROSSHAIR_CURSOR   0x00036003

The crosshair shape.

          #define GLFW_HAND_CURSOR   0x00036004

The hand shape.

          #define GLFW_HRESIZE_CURSOR   0x00036005

The horizontal resize arrow shape.

          #define GLFW_IBEAM_CURSOR   0x00036002

The text input I-beam cursor shape.

          #define GLFW_VRESIZE_CURSOR   0x00036006

The vertical resize arrow shape.

<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: Context 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)"/>

Context guide

Table of Contents

Context objects

Context creation hints

Context object sharing

Offscreen contexts

Windows without contexts

Current context

Buffer swapping

OpenGL and OpenGL ES extensions

Loading extension with a loader library

Loading extensions manually

The glext.h header

Checking for extensions

Fetching function pointers

This guide introduces the OpenGL and OpenGL ES context related functions of GLFW. For details on a specific function in this category, see the Context reference. There are also guides for the other areas of the GLFW API.

Introduction to the API

Window guide

Vulkan guide

Monitor guide

Input guide

Context objects

A window object encapsulates both a top-level window and an OpenGL or OpenGL ES context. It is created with glfwCreateWindow and destroyed with glfwDestroyWindow or glfwTerminate. See Window creation for more information.

As the window and context are inseparably linked, the window object also serves as the context handle.

To test the creation of various kinds of contexts and see their properties, run the glfwinfo test program.

Note

Vulkan does not have a context and the Vulkan instance is created via the Vulkan API itself. If you will be using Vulkan to render to a window, disable context creation by setting the GLFW_CLIENT_API hint to GLFW_NO_API. For more information, see the Vulkan guide.

Context creation hints

There are a number of hints, specified using glfwWindowHint, related to what kind of context is created. See context related hints in the window guide.

Context object sharing

When creating a window and its OpenGL or OpenGL ES context with glfwCreateWindow, you can specify another window whose context the new one should share its objects (textures, vertex and element buffers, etc.) with.

GLFWwindow* second_window = glfwCreateWindow(640, 480, "Second Window", NULL, first_window);

Object sharing is implemented by the operating system and graphics driver. On platforms where it is possible to choose which types of objects are shared, GLFW requests that all types are shared.

See the relevant chapter of the OpenGL or OpenGL ES reference documents for more information. The name and number of this chapter unfortunately varies between versions and APIs, but has at times been named Shared Objects and Multiple Contexts.

GLFW comes with a simple object sharing test program called sharing.

Offscreen contexts

GLFW doesn't support creating contexts without an associated window. However, contexts with hidden windows can be created with the GLFW_VISIBLE window hint.

glfwWindowHint(GLFW_VISIBLE, GLFW_FALSE);

GLFWwindow* offscreen_context = glfwCreateWindow(640, 480, "", NULL, NULL);

The window never needs to be shown and its context can be used as a plain offscreen context. Depending on the window manager, the size of a hidden window's framebuffer may not be usable or modifiable, so framebuffer objects are recommended for rendering with such contexts.

You should still process events as long as you have at least one window, even if none of them are visible.

OS X: The first time a window is created the menu bar is populated with common commands like Hide, Quit and About. This is not desirable for example when writing a command-line only application. The menu bar setup can be disabled with a compile-time option.

Windows without contexts

You can disable context creation by setting the GLFW_CLIENT_API hint to GLFW_NO_API. Windows without contexts must not be passed to glfwMakeContextCurrent or glfwSwapBuffers.

Current context

Before you can make OpenGL or OpenGL ES calls, you need to have a current context of the correct type. A context can only be current for a single thread at a time, and a thread can only have a single context current at a time.

The context of a window is made current with glfwMakeContextCurrent.

glfwMakeContextCurrent(window);

The window of the current context is returned by glfwGetCurrentContext.

GLFWwindow* window = glfwGetCurrentContext();

The following GLFW functions require a context to be current. Calling any these functions without a current context will generate a GLFW_NO_CURRENT_CONTEXT error.

glfwSwapInterval

glfwExtensionSupported

glfwGetProcAddress

Buffer swapping

Buffer swapping is part of the window and framebuffer, not the context. See Buffer swapping.

OpenGL and OpenGL ES extensions

One of the benefits of OpenGL and OpenGL ES is their extensibility. Hardware vendors may include extensions in their implementations that extend the API before that functionality is included in a new version of the OpenGL or OpenGL ES specification, and some extensions are never included and remain as extensions until they become obsolete.

An extension is defined by:

An extension name (e.g. GL_ARB_debug_output)

New OpenGL tokens (e.g. GL_DEBUG_SEVERITY_HIGH_ARB)

New OpenGL functions (e.g. glGetDebugMessageLogARB)

Note the ARB affix, which stands for Architecture Review Board and is used for official extensions. The extension above was created by the ARB, but there are many different affixes, like NV for Nvidia and AMD for, well, AMD. Any group may also use the generic EXT affix. Lists of extensions, together with their specifications, can be found at the OpenGL Registry and OpenGL ES Registry.

Loading extension with a loader library

An extension loader library is the easiest and best way to access both OpenGL and OpenGL ES extensions and modern versions of the core OpenGL or OpenGL ES APIs. They will take care of all the details of declaring and loading everything you need. One such library is glad and there are several others.

The following example will use glad but all extension loader libraries work similarly.

First you need to generate the source files using the glad Python script. This example generates a loader for any version of OpenGL, which is the default for both GLFW and glad, but loaders for OpenGL ES, as well as loaders for specific API versions and extension sets can be generated. The generated files are written to the output directory.

    1 python main.py --generator c --no-loader --out-path output

The --no-loader option is added because GLFW already provides a function for loading OpenGL and OpenGL ES function pointers, one that automatically uses the selected context creation API, and glad can call this instead of having to implement its own. There are several other command-line options as well. See the glad documentation for details.

Add the generated output/src/glad.c, output/include/glad/glad.h and output/include/KHR/khrplatform.h files to your build. Then you need to include the glad header file, which will replace the OpenGL header of your development environment. By including the glad header before the GLFW header, it suppresses the development environment's OpenGL or OpenGL ES header.

#include <glad/glad.h>

#include <GLFW/glfw3.h>

Finally you need to initialize glad once you have a suitable current context.

window = glfwCreateWindow(640, 480, "My Window", NULL, NULL);

if (!window)

{

    ...

}

glfwMakeContextCurrent(window);

gladLoadGLLoader((GLADloadproc) glfwGetProcAddress);

Once glad has been loaded, you have access to all OpenGL core and extension functions supported by both the context you created and the glad loader you generated and you are ready to start rendering.

You can specify a minimum required OpenGL or OpenGL ES version with context hints. If your needs are more complex, you can check the actual OpenGL or OpenGL ES version with context attributes, or you can check whether a specific version is supported by the current context with the GLAD_GL_VERSION_x_x booleans.

if (GLAD_GL_VERSION_3_2)

{

    // Call OpenGL 3.2+ specific code

}

To check whether a specific extension is supported, use the GLAD_GL_xxx booleans.

if (GLAD_GL_ARB_debug_output)

{

    // Use GL_ARB_debug_output

}

Loading extensions manually

Do not use this technique unless it is absolutely necessary. An extension loader library will save you a ton of tedious, repetitive, error prone work.

To use a certain extension, you must first check whether the context supports that extension and then, if it introduces new functions, retrieve the pointers to those functions. GLFW provides glfwExtensionSupported and glfwGetProcAddress for manual loading of extensions and new API functions.

This section will demonstrate manual loading of OpenGL extensions. The loading of OpenGL ES extensions is identical except for the name of the extension header.

The glext.h header

The glext.h extension header is a continually updated file that defines the interfaces for all OpenGL extensions. The latest version of this can always be found at the OpenGL Registry. There are also extension headers for the various versions of OpenGL ES at the OpenGL ES Registry. It it strongly recommended that you use your own copy of the extension header, as the one included in your development environment may be several years out of date and may not include the extensions you wish to use.

The header defines function pointer types for all functions of all extensions it supports. These have names like PFNGLGETDEBUGMESSAGELOGARBPROC (for glGetDebugMessageLogARB), i.e. the name is made uppercase and PFN (pointer to function) and PROC (procedure) are added to the ends.

To include the extension header, define GLFW_INCLUDE_GLEXT before including the GLFW header.

#define GLFW_INCLUDE_GLEXT

#include <GLFW/glfw3.h>

Checking for extensions

A given machine may not actually support the extension (it may have older drivers or a graphics card that lacks the necessary hardware features), so it is necessary to check at run-time whether the context supports the extension. This is done with glfwExtensionSupported.

if (glfwExtensionSupported("GL_ARB_debug_output"))

{

    // The extension is supported by the current context

}

The argument is a null terminated ASCII string with the extension name. If the extension is supported, glfwExtensionSupported returns GLFW_TRUE, otherwise it returns GLFW_FALSE.

Fetching function pointers

Many extensions, though not all, require the use of new OpenGL functions. These functions often do not have entry points in the client API libraries of your operating system, making it necessary to fetch them at run time. You can retrieve pointers to these functions with glfwGetProcAddress.

PFNGLGETDEBUGMESSAGELOGARBPROC pfnGetDebugMessageLog = glfwGetProcAddress("glGetDebugMessageLogARB");

In general, you should avoid giving the function pointer variables the (exact) same name as the function, as this may confuse your linker. Instead, you can use a different prefix, like above, or some other naming scheme.

Now that all the pieces have been introduced, here is what they might look like when used together.

#define GLFW_INCLUDE_GLEXT

#include <GLFW/glfw3.h>

#define glGetDebugMessageLogARB pfnGetDebugMessageLog

PFNGLGETDEBUGMESSAGELOGARBPROC pfnGetDebugMessageLog;

// Flag indicating whether the extension is supported

int has_ARB_debug_output = 0;

void load_extensions(void)

{

    if (glfwExtensionSupported("GL_ARB_debug_output"))

    {

        pfnGetDebugMessageLog = (PFNGLGETDEBUGMESSAGELOGARBPROC)

            glfwGetProcAddress("glGetDebugMessageLogARB");

        has_ARB_debug_output = 1;

    }

}

void some_function(void)

{

    if (has_ARB_debug_output)

    {

        // Now the extension function can be called as usual

        glGetDebugMessageLogARB(...);

    }

}

<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: 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:

- w -

glfwWaitEvents()
: glfw3.h

glfwWaitEventsTimeout()
: glfw3.h

glfwWindowHint()
: glfw3.h

glfwWindowShouldClose()
: 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: window.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

window.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: Related Pages</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)"/>

Related Pages

Here is a list of all related documentation pages:

 New features

 Moving from GLFW 2 to 3

 Getting started

 Compiling GLFW

 Building applications

 Introduction to the API

 Context guide

 Monitor guide

 Window guide

 Input guide

 Vulkan guide

 Standards conformance

 Bug List

<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: include Directory 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

glfw-3.2.1

include

include Directory Reference

Directories

directory  	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: 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

- d -

GLFW_DECORATED
: glfw3.h

GLFW_DEPTH_BITS
: glfw3.h

GLFW_DISCONNECTED
: glfw3.h

GLFW_DONT_CARE
: glfw3.h

GLFW_DOUBLEBUFFER
: 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: File List</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

File List

Here is a list of all files with brief descriptions:

 glfw3.h	The header of the GLFW 3 API

 glfw3native.h	The header of the native access functions

<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: vulkan.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

vulkan.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

- l -

GLFW_LOSE_CONTEXT_ON_RESET
: 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:

- v -

GLFW_VERSION_MAJOR
: glfw3.h

GLFW_VERSION_MINOR
: glfw3.h

GLFW_VERSION_REVISION
: glfw3.h

GLFW_VERSION_UNAVAILABLE
: glfw3.h

GLFW_VISIBLE
: glfw3.h

GLFW_VRESIZE_CURSOR
: glfw3.h

glfwVulkanSupported()
: 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:

- c -

GLFW_CLIENT_API
: glfw3.h

GLFW_CONNECTED
: glfw3.h

GLFW_CONTEXT_CREATION_API
: glfw3.h

GLFW_CONTEXT_NO_ERROR
: glfw3.h

GLFW_CONTEXT_RELEASE_BEHAVIOR
: glfw3.h

GLFW_CONTEXT_REVISION
: glfw3.h

GLFW_CONTEXT_ROBUSTNESS
: glfw3.h

GLFW_CONTEXT_VERSION_MAJOR
: glfw3.h

GLFW_CONTEXT_VERSION_MINOR
: glfw3.h

GLFW_CROSSHAIR_CURSOR
: glfw3.h

GLFW_CURSOR
: glfw3.h

GLFW_CURSOR_DISABLED
: glfw3.h

GLFW_CURSOR_HIDDEN
: glfw3.h

GLFW_CURSOR_NORMAL
: glfw3.h

glfwCreateCursor()
: glfw3.h

glfwCreateStandardCursor()
: glfw3.h

glfwCreateWindow()
: glfw3.h

glfwCreateWindowSurface()
: 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: build.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

build.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:

- h -

GLFW_HAND_CURSOR
: glfw3.h

GLFW_HRESIZE_CURSOR
: glfw3.h

glfwHideWindow()
: 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: Vulkan 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)"/>

Vulkan guide

Table of Contents

Including the Vulkan and GLFW header files

Querying for Vulkan support

Querying Vulkan function pointers

Querying required Vulkan extensions

Querying for Vulkan presentation support

Creating the window

Creating a Vulkan window surface

This guide is intended to fill the gaps between the Vulkan documentation and the rest of the GLFW documentation and is not a replacement for either. It assumes some familiarity with Vulkan concepts like loaders, devices, queues and surfaces and leaves it to the Vulkan documentation to explain the details of Vulkan functions.

To develop for Vulkan you should install an SDK for your platform, for example the LunarG Vulkan SDK. Apart from the headers and libraries, it also provides the validation layers necessary for development.

The GLFW library does not need the Vulkan SDK to enable support for Vulkan. However, any Vulkan-specific test and example programs are built only if the CMake files find a Vulkan SDK.

For details on a specific function in this category, see the Vulkan reference. There are also guides for the other areas of the GLFW API.

Introduction to the API

Window guide

Context guide

Monitor guide

Input guide

Including the Vulkan and GLFW header files

To include the Vulkan header, define GLFW_INCLUDE_VULKAN before including the GLFW header.

#define GLFW_INCLUDE_VULKAN

#include <GLFW/glfw3.h>

If you instead want to include the Vulkan header from a custom location or use your own custom Vulkan header then do this before the GLFW header.

#include <path/to/vulkan.h>

#include <GLFW/glfw3.h>

Unless a Vulkan header is included, either by the GLFW header or above it, any GLFW functions that take or return Vulkan types will not be declared.

The VK_USE_PLATFORM_*_KHR macros do not need to be defined for the Vulkan part of GLFW to work. Define them only if you are using these extensions directly.

Querying for Vulkan support

If you are linking directly against the Vulkan loader then you can skip this section. The canonical desktop loader library exports all Vulkan core and Khronos extension functions, allowing them to be called directly.

If you are loading the Vulkan loader dynamically instead of linking directly against it, you can check for the availability of a loader with glfwVulkanSupported.

if (glfwVulkanSupported())

{

    // Vulkan is available, at least for compute

}

This function returns GLFW_TRUE if the Vulkan loader was found. This check is performed by glfwInit.

If no loader was found, calling any other Vulkan related GLFW function will generate a GLFW_API_UNAVAILABLE error.

Querying Vulkan function pointers

To load any Vulkan core or extension function from the found loader, call glfwGetInstanceProcAddress. To load functions needed for instance creation, pass NULL as the instance.

PFN_vkCreateInstance pfnCreateInstance = (PFN_vkCreateInstance)

    glfwGetInstanceProcAddress(NULL, "vkCreateInstance");

Once you have created an instance, you can load from it all other Vulkan core functions and functions from any instance extensions you enabled.

PFN_vkCreateDevice pfnCreateDevice = (PFN_vkCreateDevice)

    glfwGetInstanceProcAddress(instance, "vkCreateDevice");

This function in turn calls vkGetInstanceProcAddr. If that fails, the function falls back to a platform-specific query of the Vulkan loader (i.e. dlsym or GetProcAddress). If that also fails, the function returns NULL. For more information about vkGetInstanceProcAddr, see the Vulkan documentation.

Vulkan also provides vkGetDeviceProcAddr for loading device-specific versions of Vulkan function. This function can be retrieved from an instance with glfwGetInstanceProcAddress.

PFN_vkGetDeviceProcAddr pfnGetDeviceProcAddr = (PFN_vkGetDeviceProcAddr)

    glfwGetInstanceProcAddress(instance, "vkGetDeviceProcAddr");

Device-specific functions may execute a little bit faster, due to not having to dispatch internally based on the device passed to them. For more information about vkGetDeviceProcAddr, see the Vulkan documentation.

Querying required Vulkan extensions

To do anything useful with Vulkan you need to create an instance. If you want to use Vulkan to render to a window, you must enable the instance extensions GLFW requires to create Vulkan surfaces.

To query the instance extensions required, call glfwGetRequiredInstanceExtensions.

uint32_t count;

const char** extensions = glfwGetRequiredInstanceExtensions(&count);

These extensions must all be enabled when creating instances that are going to be passed to glfwGetPhysicalDevicePresentationSupport and glfwCreateWindowSurface. The set of extensions will vary depending on platform and may also vary depending on graphics drivers and other factors.

If it fails it will return NULL and GLFW will not be able to create Vulkan window surfaces. You can still use Vulkan for off-screen rendering and compute work.

The returned array will always contain VK_KHR_surface, so if you don't require any additional extensions you can pass this list directly to the VkInstanceCreateInfo struct.

VkInstanceCreateInfo ici;

memset(&ici, 0, sizeof(ici));

ici.enabledExtensionCount = count;

ici.ppEnabledExtensionNames = extensions;

...

Additional extensions may be required by future versions of GLFW. You should check whether any extensions you wish to enable are already in the returned array, as it is an error to specify an extension more than once in the VkInstanceCreateInfo struct.

Querying for Vulkan presentation support

Not every queue family of every Vulkan device can present images to surfaces. To check whether a specific queue family of a physical device supports image presentation without first having to create a window and surface, call glfwGetPhysicalDevicePresentationSupport.

if (glfwGetPhysicalDevicePresentationSupport(instance, physical_device, queue_family_index))

{

    // Queue family supports image presentation

}

The VK_KHR_surface extension additionally provides the vkGetPhysicalDeviceSurfaceSupportKHR function, which performs the same test on an existing Vulkan surface.

Creating the window

Unless you will be using OpenGL or OpenGL ES with the same window as Vulkan, there is no need to create a context. You can disable context creation with the GLFW_CLIENT_API hint.

glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);

GLFWwindow* window = glfwCreateWindow(640, 480, "Window Title", NULL, NULL);

See Windows without contexts for more information.

Creating a Vulkan window surface

You can create a Vulkan surface (as defined by the VK_KHR_surface extension) for a GLFW window with glfwCreateWindowSurface.

VkSurfaceKHR surface;

VkResult err = glfwCreateWindowSurface(instance, window, NULL, &surface);

if (err)

{

    // Window surface creation failed

}

It is your responsibility to destroy the surface. GLFW does not destroy it for you. Call vkDestroySurfaceKHR function from the same extension to destroy 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: Mouse buttons</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

Mouse buttons
Input reference

Macros

#define 	GLFW_MOUSE_BUTTON_1   0

#define 	GLFW_MOUSE_BUTTON_2   1

#define 	GLFW_MOUSE_BUTTON_3   2

#define 	GLFW_MOUSE_BUTTON_4   3

#define 	GLFW_MOUSE_BUTTON_5   4

#define 	GLFW_MOUSE_BUTTON_6   5

#define 	GLFW_MOUSE_BUTTON_7   6

#define 	GLFW_MOUSE_BUTTON_8   7

#define 	GLFW_MOUSE_BUTTON_LAST   GLFW_MOUSE_BUTTON_8

#define 	GLFW_MOUSE_BUTTON_LEFT   GLFW_MOUSE_BUTTON_1

#define 	GLFW_MOUSE_BUTTON_RIGHT   GLFW_MOUSE_BUTTON_2

#define 	GLFW_MOUSE_BUTTON_MIDDLE   GLFW_MOUSE_BUTTON_3

Detailed Description

See mouse button input for how these are used.

Macro Definition Documentation

          #define GLFW_MOUSE_BUTTON_1   0

          #define GLFW_MOUSE_BUTTON_2   1

          #define GLFW_MOUSE_BUTTON_3   2

          #define GLFW_MOUSE_BUTTON_4   3

          #define GLFW_MOUSE_BUTTON_5   4

          #define GLFW_MOUSE_BUTTON_6   5

          #define GLFW_MOUSE_BUTTON_7   6

          #define GLFW_MOUSE_BUTTON_8   7

          #define GLFW_MOUSE_BUTTON_LAST   GLFW_MOUSE_BUTTON_8

          #define GLFW_MOUSE_BUTTON_LEFT   GLFW_MOUSE_BUTTON_1

          #define GLFW_MOUSE_BUTTON_MIDDLE   GLFW_MOUSE_BUTTON_3

          #define GLFW_MOUSE_BUTTON_RIGHT   GLFW_MOUSE_BUTTON_2

<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 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

Input reference

Modules

 	Joysticks

 	Keyboard keys

 	Modifier key flags

 	Mouse buttons

 	Standard cursor shapes

Typedefs

typedef void(* 	GLFWmousebuttonfun) (GLFWwindow *, int, int, int)

 	The function signature for mouse button callbacks.  More...

typedef void(* 	GLFWcursorposfun) (GLFWwindow *, double, double)

 	The function signature for cursor position callbacks.  More...

typedef void(* 	GLFWcursorenterfun) (GLFWwindow *, int)

 	The function signature for cursor enter/leave callbacks.  More...

typedef void(* 	GLFWscrollfun) (GLFWwindow *, double, double)

 	The function signature for scroll callbacks.  More...

typedef void(* 	GLFWkeyfun) (GLFWwindow *, int, int, int, int)

 	The function signature for keyboard key callbacks.  More...

typedef void(* 	GLFWcharfun) (GLFWwindow *, unsigned int)

 	The function signature for Unicode character callbacks.  More...

typedef void(* 	GLFWcharmodsfun) (GLFWwindow *, unsigned int, int)

 	The function signature for Unicode character with modifiers callbacks.  More...

typedef void(* 	GLFWdropfun) (GLFWwindow *, int, const char **)

 	The function signature for file drop callbacks.  More...

typedef void(* 	GLFWjoystickfun) (int, int)

 	The function signature for joystick configuration callbacks.  More...

Functions

int 	glfwGetInputMode (GLFWwindow *window, int mode)

 	Returns the value of an input option for the specified window.  More...

void 	glfwSetInputMode (GLFWwindow *window, int mode, int value)

 	Sets an input option for the specified window.  More...

const char * 	glfwGetKeyName (int key, int scancode)

 	Returns the localized name of the specified printable key.  More...

int 	glfwGetKey (GLFWwindow *window, int key)

 	Returns the last reported state of a keyboard key for the specified window.  More...

int 	glfwGetMouseButton (GLFWwindow *window, int button)

 	Returns the last reported state of a mouse button for the specified window.  More...

void 	glfwGetCursorPos (GLFWwindow *window, double *xpos, double *ypos)

 	Retrieves the position of the cursor relative to the client area of the window.  More...

void 	glfwSetCursorPos (GLFWwindow *window, double xpos, double ypos)

 	Sets the position of the cursor, relative to the client area of the window.  More...

GLFWcursor * 	glfwCreateCursor (const GLFWimage *image, int xhot, int yhot)

 	Creates a custom cursor.  More...

GLFWcursor * 	glfwCreateStandardCursor (int shape)

 	Creates a cursor with a standard shape.  More...

void 	glfwDestroyCursor (GLFWcursor *cursor)

 	Destroys a cursor.  More...

void 	glfwSetCursor (GLFWwindow *window, GLFWcursor *cursor)

 	Sets the cursor for the window.  More...

GLFWkeyfun 	glfwSetKeyCallback (GLFWwindow *window, GLFWkeyfun cbfun)

 	Sets the key callback.  More...

GLFWcharfun 	glfwSetCharCallback (GLFWwindow *window, GLFWcharfun cbfun)

 	Sets the Unicode character callback.  More...

GLFWcharmodsfun 	glfwSetCharModsCallback (GLFWwindow *window, GLFWcharmodsfun cbfun)

 	Sets the Unicode character with modifiers callback.  More...

GLFWmousebuttonfun 	glfwSetMouseButtonCallback (GLFWwindow *window, GLFWmousebuttonfun cbfun)

 	Sets the mouse button callback.  More...

GLFWcursorposfun 	glfwSetCursorPosCallback (GLFWwindow *window, GLFWcursorposfun cbfun)

 	Sets the cursor position callback.  More...

GLFWcursorenterfun 	glfwSetCursorEnterCallback (GLFWwindow *window, GLFWcursorenterfun cbfun)

 	Sets the cursor enter/exit callback.  More...

GLFWscrollfun 	glfwSetScrollCallback (GLFWwindow *window, GLFWscrollfun cbfun)

 	Sets the scroll callback.  More...

GLFWdropfun 	glfwSetDropCallback (GLFWwindow *window, GLFWdropfun cbfun)

 	Sets the file drop callback.  More...

int 	glfwJoystickPresent (int joy)

 	Returns whether the specified joystick is present.  More...

const float * 	glfwGetJoystickAxes (int joy, int *count)

 	Returns the values of all axes of the specified joystick.  More...

const unsigned char * 	glfwGetJoystickButtons (int joy, int *count)

 	Returns the state of all buttons of the specified joystick.  More...

const char * 	glfwGetJoystickName (int joy)

 	Returns the name of the specified joystick.  More...

GLFWjoystickfun 	glfwSetJoystickCallback (GLFWjoystickfun cbfun)

 	Sets the joystick configuration callback.  More...

void 	glfwSetClipboardString (GLFWwindow *window, const char *string)

 	Sets the clipboard to the specified string.  More...

const char * 	glfwGetClipboardString (GLFWwindow *window)

 	Returns the contents of the clipboard as a string.  More...

double 	glfwGetTime (void)

 	Returns the value of the GLFW timer.  More...

void 	glfwSetTime (double time)

 	Sets the GLFW timer.  More...

uint64_t 	glfwGetTimerValue (void)

 	Returns the current value of the raw timer.  More...

uint64_t 	glfwGetTimerFrequency (void)

 	Returns the frequency, in Hz, of the raw timer.  More...

Key and button actions

#define 	GLFW_RELEASE   0

 	The key or mouse button was released.  More...

#define 	GLFW_PRESS   1

 	The key or mouse button was pressed.  More...

#define 	GLFW_REPEAT   2

 	The key was held down until it repeated.  More...

Detailed Description

This is the reference documentation for input related functions and types. For more task-oriented information, see the Input guide.

Macro Definition Documentation

          #define GLFW_PRESS   1

The key or mouse button was pressed.

          #define GLFW_RELEASE   0

The key or mouse button was released.

          #define GLFW_REPEAT   2

The key was held down until it repeated.

Typedef Documentation

          typedef void(*  GLFWcharfun) (GLFWwindow *, unsigned int)

This is the function signature for Unicode character callback functions.

Parameters

[in]	window	The window that received the event.

[in]	codepoint	The Unicode code point of the character.

See also

Text input

glfwSetCharCallback

Since

Added in version 2.4.

GLFW 3: Added window handle parameter.

          typedef void(*  GLFWcharmodsfun) (GLFWwindow *, unsigned int, int)

This is the function signature for Unicode character with modifiers callback functions. It is called for each input character, regardless of what modifier keys are held down.

Parameters

[in]	window	The window that received the event.

[in]	codepoint	The Unicode code point of the character.

[in]	mods	Bit field describing which modifier keys were held down.

See also

Text input

glfwSetCharModsCallback

Since

Added in version 3.1.

          typedef void(*  GLFWcursorenterfun) (GLFWwindow *, int)

This is the function signature for cursor enter/leave callback functions.

Parameters

[in]	window	The window that received the event.

[in]	entered	GLFW_TRUE if the cursor entered the window's client area, or GLFW_FALSE if it left it.

See also

Cursor enter/leave events

glfwSetCursorEnterCallback

Since

Added in version 3.0.

          typedef void(*  GLFWcursorposfun) (GLFWwindow *, double, double)

This is the function signature for cursor position callback functions.

Parameters

[in]	window	The window that received the event.

[in]	xpos	The new cursor x-coordinate, relative to the left edge of the client area.

[in]	ypos	The new cursor y-coordinate, relative to the top edge of the client area.

See also

Cursor position

glfwSetCursorPosCallback

Since

Added in version 3.0. Replaces GLFWmouseposfun.

          typedef void(*  GLFWdropfun) (GLFWwindow *, int, const char **)

This is the function signature for file drop callbacks.

Parameters

[in]	window	The window that received the event.

[in]	count	The number of dropped files.

[in]	paths	The UTF-8 encoded file and/or directory path names.

See also

Path drop input

glfwSetDropCallback

Since

Added in version 3.1.

          typedef void(*  GLFWjoystickfun) (int, int)

This is the function signature for joystick configuration callback functions.

Parameters

[in]	joy	The joystick that was connected or disconnected.

[in]	event	One of GLFW_CONNECTED or GLFW_DISCONNECTED.

See also

Joystick configuration changes

glfwSetJoystickCallback

Since

Added in version 3.2.

          typedef void(*  GLFWkeyfun) (GLFWwindow *, int, int, int, int)

This is the function signature for keyboard key callback functions.

Parameters

[in]	window	The window that received the event.

[in]	key	The keyboard key that was pressed or released.

[in]	scancode	The system-specific scancode of the key.

[in]	action	GLFW_PRESS, GLFW_RELEASE or GLFW_REPEAT.

[in]	mods	Bit field describing which modifier keys were held down.

See also

Key input

glfwSetKeyCallback

Since

Added in version 1.0.

GLFW 3: Added window handle, scancode and modifier mask parameters.

          typedef void(*  GLFWmousebuttonfun) (GLFWwindow *, int, int, int)

This is the function signature for mouse button callback functions.

Parameters

[in]	window	The window that received the event.

[in]	button	The mouse button that was pressed or released.

[in]	action	One of GLFW_PRESS or GLFW_RELEASE.

[in]	mods	Bit field describing which modifier keys were held down.

See also

Mouse button input

glfwSetMouseButtonCallback

Since

Added in version 1.0.

GLFW 3: Added window handle and modifier mask parameters.

          typedef void(*  GLFWscrollfun) (GLFWwindow *, double, double)

This is the function signature for scroll callback functions.

Parameters

[in]	window	The window that received the event.

[in]	xoffset	The scroll offset along the x-axis.

[in]	yoffset	The scroll offset along the y-axis.

See also

Scroll input

glfwSetScrollCallback

Since

Added in version 3.0. Replaces GLFWmousewheelfun.

Function Documentation

          GLFWcursor* glfwCreateCursor
          (
          const GLFWimage *
          image,

          int
          xhot,

          int
          yhot

          )

Creates a new custom cursor image that can be set for a window with glfwSetCursor. The cursor can be destroyed with glfwDestroyCursor. Any remaining cursors are destroyed by glfwTerminate.

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

The cursor hotspot is specified in pixels, relative to the upper-left corner of the cursor image. Like all other coordinate systems in GLFW, the X-axis points to the right and the Y-axis points down.

Parameters

[in]	image	The desired cursor image.

[in]	xhot	The desired x-coordinate, in pixels, of the cursor hotspot.

[in]	yhot	The desired y-coordinate, in pixels, of the cursor hotspot.

Returns

The handle of the created cursor, or NULL if an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Pointer lifetime

The specified image data is copied before this function returns.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

See also

Cursor objects

glfwDestroyCursor

glfwCreateStandardCursor

Since

Added in version 3.1.

          GLFWcursor* glfwCreateStandardCursor
          (
          int
          shape	)

Returns a cursor with a standard shape, that can be set for a window with glfwSetCursor.

Parameters

[in]	shape	One of the standard shapes.

Returns

A new cursor ready to use or NULL if an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_ENUM and GLFW_PLATFORM_ERROR.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

See also

Cursor objects

glfwCreateCursor

Since

Added in version 3.1.

          void glfwDestroyCursor
          (
          GLFWcursor *
          cursor	)

This function destroys a cursor previously created with glfwCreateCursor. Any remaining cursors will be destroyed by glfwTerminate.

Parameters

[in]	cursor	The cursor object to destroy.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

See also

Cursor objects

glfwCreateCursor

Since

Added in version 3.1.

          const char* glfwGetClipboardString
          (
          GLFWwindow *
          window	)

This function returns the contents of the system clipboard, if it contains or is convertible to a UTF-8 encoded string. If the clipboard is empty or if its contents cannot be converted, NULL is returned and a GLFW_FORMAT_UNAVAILABLE error is generated.

Parameters

[in]	window	The window that will request the clipboard contents.

Returns

The contents of the clipboard as a UTF-8 encoded string, or NULL if an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Pointer lifetime

The returned string is allocated and freed by GLFW. You should not free it yourself. It is valid until the next call to glfwGetClipboardString or glfwSetClipboardString, or until the library is terminated.

Thread safety

This function must only be called from the main thread.

See also

Clipboard input and output

glfwSetClipboardString

Since

Added in version 3.0.

          void glfwGetCursorPos
          (
          GLFWwindow *
          window,

          double *
          xpos,

          double *
          ypos

          )

This function returns the position of the cursor, in screen coordinates, relative to the upper-left corner of the client area of the specified window.

If the cursor is disabled (with GLFW_CURSOR_DISABLED) then the cursor position is unbounded and limited only by the minimum and maximum values of a double.

The coordinate can be converted to their integer equivalents with the floor function. Casting directly to an integer type works for positive coordinates, but fails for negative ones.

Any or all of the position arguments may be NULL. If an error occurs, all non-NULL position arguments will be set to zero.

Parameters

[in]	window	The desired window.

[out]	xpos	Where to store the cursor x-coordinate, relative to the left edge of the client area, or NULL.

[out]	ypos	Where to store the cursor y-coordinate, relative to the to top edge of the client area, or NULL.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Thread safety

This function must only be called from the main thread.

See also

Cursor position

glfwSetCursorPos

Since

Added in version 3.0. Replaces glfwGetMousePos.

          int glfwGetInputMode
          (
          GLFWwindow *
          window,

          int
          mode

          )

This function returns the value of an input option for the specified window. The mode must be one of GLFW_CURSOR, GLFW_STICKY_KEYS or GLFW_STICKY_MOUSE_BUTTONS.

Parameters

[in]	window	The window to query.

[in]	mode	One of GLFW_CURSOR, GLFW_STICKY_KEYS or GLFW_STICKY_MOUSE_BUTTONS.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_INVALID_ENUM.

Thread safety

This function must only be called from the main thread.

See also

glfwSetInputMode

Since

Added in version 3.0.

          const float* glfwGetJoystickAxes
          (
          int
          joy,

          int *
          count

          )

This function returns the values of all axes of the specified joystick. Each element in the array is a value between -1.0 and 1.0.

Querying a joystick slot with no device present is not an error, but will cause this function to return NULL. Call glfwJoystickPresent to check device presence.

Parameters

[in]	joy	The joystick to query.

[out]	count	Where to store the number of axis values in the returned array. This is set to zero if the joystick is not present or an error occurred.

Returns

An array of axis values, or NULL if the joystick is not present or an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_ENUM and GLFW_PLATFORM_ERROR.

Pointer lifetime

The returned array is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected, this function is called again for that joystick or the library is terminated.

Thread safety

This function must only be called from the main thread.

See also

Joystick axis states

Since

Added in version 3.0. Replaces glfwGetJoystickPos.

          const unsigned char* glfwGetJoystickButtons
          (
          int
          joy,

          int *
          count

          )

This function returns the state of all buttons of the specified joystick. Each element in the array is either GLFW_PRESS or GLFW_RELEASE.

Querying a joystick slot with no device present is not an error, but will cause this function to return NULL. Call glfwJoystickPresent to check device presence.

Parameters

[in]	joy	The joystick to query.

[out]	count	Where to store the number of button states in the returned array. This is set to zero if the joystick is not present or an error occurred.

Returns

An array of button states, or NULL if the joystick is not present or an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_ENUM and GLFW_PLATFORM_ERROR.

Pointer lifetime

The returned array is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected, this function is called again for that joystick or the library is terminated.

Thread safety

This function must only be called from the main thread.

See also

Joystick button states

Since

Added in version 2.2.

GLFW 3: Changed to return a dynamic array.

          const char* glfwGetJoystickName
          (
          int
          joy	)

This function returns the name, encoded as UTF-8, of the specified joystick. The returned string is allocated and freed by GLFW. You should not free it yourself.

Querying a joystick slot with no device present is not an error, but will cause this function to return NULL. Call glfwJoystickPresent to check device presence.

Parameters

[in]	joy	The joystick to query.

Returns

The UTF-8 encoded name of the joystick, or NULL if the joystick is not present or an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_ENUM and GLFW_PLATFORM_ERROR.

Pointer lifetime

The returned string is allocated and freed by GLFW. You should not free it yourself. It is valid until the specified joystick is disconnected, this function is called again for that joystick or the library is terminated.

Thread safety

This function must only be called from the main thread.

See also

Joystick name

Since

Added in version 3.0.

          int glfwGetKey
          (
          GLFWwindow *
          window,

          int
          key

          )

This function returns the last state reported for the specified key to the specified window. The returned state is one of GLFW_PRESS or GLFW_RELEASE. The higher-level action GLFW_REPEAT is only reported to the key callback.

If the GLFW_STICKY_KEYS input mode is enabled, this function returns GLFW_PRESS the first time you call it for a key that was pressed, even if that key has already been released.

The key functions deal with physical keys, with key tokens named after their use on the standard US keyboard layout. If you want to input text, use the Unicode character callback instead.

The modifier key bit masks are not key tokens and cannot be used with this function.

Do not use this function to implement text input.

Parameters

[in]	window	The desired window.

[in]	key	The desired keyboard key. GLFW_KEY_UNKNOWN is not a valid key for this function.

Returns

One of GLFW_PRESS or GLFW_RELEASE.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_INVALID_ENUM.

Thread safety

This function must only be called from the main thread.

See also

Key input

Since

Added in version 1.0.

GLFW 3: Added window handle parameter.

          const char* glfwGetKeyName
          (
          int
          key,

          int
          scancode

          )

This function returns the localized name of the specified printable key. This is intended for displaying key bindings to the user.

If the key is GLFW_KEY_UNKNOWN, the scancode is used instead, otherwise the scancode is ignored. If a non-printable key or (if the key is GLFW_KEY_UNKNOWN) a scancode that maps to a non-printable key is specified, this function returns NULL.

This behavior allows you to pass in the arguments passed to the key callback without modification.

The printable keys are:

GLFW_KEY_APOSTROPHE

GLFW_KEY_COMMA

GLFW_KEY_MINUS

GLFW_KEY_PERIOD

GLFW_KEY_SLASH

GLFW_KEY_SEMICOLON

GLFW_KEY_EQUAL

GLFW_KEY_LEFT_BRACKET

GLFW_KEY_RIGHT_BRACKET

GLFW_KEY_BACKSLASH

GLFW_KEY_WORLD_1

GLFW_KEY_WORLD_2

GLFW_KEY_0 to GLFW_KEY_9

GLFW_KEY_A to GLFW_KEY_Z

GLFW_KEY_KP_0 to GLFW_KEY_KP_9

GLFW_KEY_KP_DECIMAL

GLFW_KEY_KP_DIVIDE

GLFW_KEY_KP_MULTIPLY

GLFW_KEY_KP_SUBTRACT

GLFW_KEY_KP_ADD

GLFW_KEY_KP_EQUAL

Parameters

[in]	key	The key to query, or GLFW_KEY_UNKNOWN.

[in]	scancode	The scancode of the key to query.

Returns

The localized name of the key, or NULL.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Pointer lifetime

The returned string is allocated and freed by GLFW. You should not free it yourself. It is valid until the next call to glfwGetKeyName, or until the library is terminated.

Thread safety

This function must only be called from the main thread.

See also

Key names

Since

Added in version 3.2.

          int glfwGetMouseButton
          (
          GLFWwindow *
          window,

          int
          button

          )

This function returns the last state reported for the specified mouse button to the specified window. The returned state is one of GLFW_PRESS or GLFW_RELEASE.

If the GLFW_STICKY_MOUSE_BUTTONS input mode is enabled, this function GLFW_PRESS the first time you call it for a mouse button that was pressed, even if that mouse button has already been released.

Parameters

[in]	window	The desired window.

[in]	button	The desired mouse button.

Returns

One of GLFW_PRESS or GLFW_RELEASE.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_INVALID_ENUM.

Thread safety

This function must only be called from the main thread.

See also

Mouse button input

Since

Added in version 1.0.

GLFW 3: Added window handle parameter.

          double glfwGetTime
          (
          void
          	)

This function returns the value of the GLFW timer. Unless the timer has been set using glfwSetTime, the timer measures time elapsed since GLFW was initialized.

The resolution of the timer is system dependent, but is usually on the order of a few micro- or nanoseconds. It uses the highest-resolution monotonic time source on each supported platform.

Returns

The current value, in seconds, or zero if an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function may be called from any thread. Reading and writing of the internal timer offset is not atomic, so it needs to be externally synchronized with calls to glfwSetTime.

See also

Time input

Since

Added in version 1.0.

          uint64_t glfwGetTimerFrequency
          (
          void
          	)

This function returns the frequency, in Hz, of the raw timer.

Returns

The frequency of the timer, in Hz, or zero if an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function may be called from any thread.

See also

Time input

glfwGetTimerValue

Since

Added in version 3.2.

          uint64_t glfwGetTimerValue
          (
          void
          	)

This function returns the current value of the raw timer, measured in 1 / frequency seconds. To get the frequency, call glfwGetTimerFrequency.

Returns

The value of the timer, or zero if an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function may be called from any thread.

See also

Time input

glfwGetTimerFrequency

Since

Added in version 3.2.

          int glfwJoystickPresent
          (
          int
          joy	)

This function returns whether the specified joystick is present.

Parameters

[in]	joy	The joystick to query.

Returns

GLFW_TRUE if the joystick is present, or GLFW_FALSE otherwise.

Errors

Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_ENUM and GLFW_PLATFORM_ERROR.

Thread safety

This function must only be called from the main thread.

See also

Joystick input

Since

Added in version 3.0. Replaces glfwGetJoystickParam.

          GLFWcharfun glfwSetCharCallback
          (
          GLFWwindow *
          window,

          GLFWcharfun
          cbfun

          )

This function sets the character callback of the specified window, which is called when a Unicode character is input.

The character callback is intended for Unicode text input. As it deals with characters, it is keyboard layout dependent, whereas the key callback is not. Characters do not map 1:1 to physical keys, as a key may produce zero, one or more characters. If you want to know whether a specific physical key was pressed or released, see the key callback instead.

The character callback behaves as system text input normally does and will not be called if modifier keys are held down that would prevent normal text input on that platform, for example a Super (Command) key on OS X or Alt key on Windows. There is a character with modifiers callback that receives these events.

Parameters

[in]	window	The window whose callback to set.

[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 or the library had not been initialized.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Text input

Since

Added in version 2.4.

GLFW 3: Added window handle parameter and return value.

          GLFWcharmodsfun glfwSetCharModsCallback
          (
          GLFWwindow *
          window,

          GLFWcharmodsfun
          cbfun

          )

This function sets the character with modifiers callback of the specified window, which is called when a Unicode character is input regardless of what modifier keys are used.

The character with modifiers callback is intended for implementing custom Unicode character input. For regular Unicode text input, see the character callback. Like the character callback, the character with modifiers callback deals with characters and is keyboard layout dependent. Characters do not map 1:1 to physical keys, as a key may produce zero, one or more characters. If you want to know whether a specific physical key was pressed or released, see the key callback instead.

Parameters

[in]	window	The window whose callback to set.

[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 or an error occurred.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Text input

Since

Added in version 3.1.

          void glfwSetClipboardString
          (
          GLFWwindow *
          window,

          const char *
          string

          )

This function sets the system clipboard to the specified, UTF-8 encoded string.

Parameters

[in]	window	The window that will own the clipboard contents.

[in]	string	A UTF-8 encoded string.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Pointer lifetime

The specified string is copied before this function returns.

Thread safety

This function must only be called from the main thread.

See also

Clipboard input and output

glfwGetClipboardString

Since

Added in version 3.0.

          void glfwSetCursor
          (
          GLFWwindow *
          window,

          GLFWcursor *
          cursor

          )

This function sets the cursor image to be used when the cursor is over the client area of the specified window. The set cursor will only be visible when the cursor mode of the window is GLFW_CURSOR_NORMAL.

On some platforms, the set cursor may not be visible unless the window also has input focus.

Parameters

[in]	window	The window to set the cursor for.

[in]	cursor	The cursor to set, or NULL to switch back to the default arrow cursor.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Thread safety

This function must only be called from the main thread.

See also

Cursor objects

Since

Added in version 3.1.

          GLFWcursorenterfun glfwSetCursorEnterCallback
          (
          GLFWwindow *
          window,

          GLFWcursorenterfun
          cbfun

          )

This function sets the cursor boundary crossing callback of the specified window, which is called when the cursor enters or leaves the client area of the window.

Parameters

[in]	window	The window whose callback to set.

[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 or the library had not been initialized.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Cursor enter/leave events

Since

Added in version 3.0.

          void glfwSetCursorPos
          (
          GLFWwindow *
          window,

          double
          xpos,

          double
          ypos

          )

This function sets the position, in screen coordinates, of the cursor relative to the upper-left corner of the client area of the specified window. The window must have input focus. If the window does not have input focus when this function is called, it fails silently.

Do not use this function to implement things like camera controls. GLFW already provides the GLFW_CURSOR_DISABLED cursor mode that hides the cursor, transparently re-centers it and provides unconstrained cursor motion. See glfwSetInputMode for more information.

If the cursor mode is GLFW_CURSOR_DISABLED then the cursor position is unconstrained and limited only by the minimum and maximum values of a double.

Parameters

[in]	window	The desired window.

[in]	xpos	The desired x-coordinate, relative to the left edge of the client area.

[in]	ypos	The desired y-coordinate, relative to the top edge of the client area.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.

Thread safety

This function must only be called from the main thread.

See also

Cursor position

glfwGetCursorPos

Since

Added in version 3.0. Replaces glfwSetMousePos.

          GLFWcursorposfun glfwSetCursorPosCallback
          (
          GLFWwindow *
          window,

          GLFWcursorposfun
          cbfun

          )

This function sets the cursor position callback of the specified window, which is called when the cursor is moved. The callback is provided with the position, in screen coordinates, relative to the upper-left corner of the client area of the window.

Parameters

[in]	window	The window whose callback to set.

[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 or the library had not been initialized.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Cursor position

Since

Added in version 3.0. Replaces glfwSetMousePosCallback.

          GLFWdropfun glfwSetDropCallback
          (
          GLFWwindow *
          window,

          GLFWdropfun
          cbfun

          )

This function sets the file drop callback of the specified window, which is called when one or more dragged files are dropped on the window.

Because the path array and its strings may have been generated specifically for that event, they are not guaranteed to be valid after the callback has returned. If you wish to use them after the callback returns, you need to make a deep copy.

Parameters

[in]	window	The window whose callback to set.

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

Returns

The previously set callback, or NULL if no callback was set or the library had not been initialized.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Path drop input

Since

Added in version 3.1.

          void glfwSetInputMode
          (
          GLFWwindow *
          window,

          int
          mode,

          int
          value

          )

This function sets an input mode option for the specified window. The mode must be one of GLFW_CURSOR, GLFW_STICKY_KEYS or GLFW_STICKY_MOUSE_BUTTONS.

If the mode is GLFW_CURSOR, the value must be one of the following cursor modes:

GLFW_CURSOR_NORMAL makes the cursor visible and behaving normally.

GLFW_CURSOR_HIDDEN makes the cursor invisible when it is over the client area of the window but does not restrict the cursor from leaving.

GLFW_CURSOR_DISABLED hides and grabs the cursor, providing virtual and unlimited cursor movement. This is useful for implementing for example 3D camera controls.

If the mode is GLFW_STICKY_KEYS, the value must be either GLFW_TRUE to enable sticky keys, or GLFW_FALSE to disable it. If sticky keys are enabled, a key press will ensure that glfwGetKey returns GLFW_PRESS the next time it is called even if the key had been released before the call. This is useful when you are only interested in whether keys have been pressed but not when or in which order.

If the mode is GLFW_STICKY_MOUSE_BUTTONS, the value must be either GLFW_TRUE to enable sticky mouse buttons, or GLFW_FALSE to disable it. If sticky mouse buttons are enabled, a mouse button press will ensure that glfwGetMouseButton returns GLFW_PRESS the next time it is called even if the mouse button had been released before the call. This is useful when you are only interested in whether mouse buttons have been pressed but not when or in which order.

Parameters

[in]	window	The window whose input mode to set.

[in]	mode	One of GLFW_CURSOR, GLFW_STICKY_KEYS or GLFW_STICKY_MOUSE_BUTTONS.

[in]	value	The new value of the specified input mode.

Errors

Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_ENUM and GLFW_PLATFORM_ERROR.

Thread safety

This function must only be called from the main thread.

See also

glfwGetInputMode

Since

Added in version 3.0. Replaces glfwEnable and glfwDisable.

          GLFWjoystickfun glfwSetJoystickCallback
          (
          GLFWjoystickfun
          cbfun	)

This function sets the joystick configuration callback, or removes the currently set callback. This is called when a joystick is connected to or disconnected from the system.

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 or the library had not been initialized.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Joystick configuration changes

Since

Added in version 3.2.

          GLFWkeyfun glfwSetKeyCallback
          (
          GLFWwindow *
          window,

          GLFWkeyfun
          cbfun

          )

This function sets the key callback of the specified window, which is called when a key is pressed, repeated or released.

The key functions deal with physical keys, with layout independent key tokens named after their values in the standard US keyboard layout. If you want to input text, use the character callback instead.

When a window loses input focus, it will generate synthetic key release events for all pressed keys. You can tell these events from user-generated events by the fact that the synthetic ones are generated after the focus loss event has been processed, i.e. after the window focus callback has been called.

The scancode of a key is specific to that platform or sometimes even to that machine. Scancodes are intended to allow users to bind keys that don't have a GLFW key token. Such keys have key set to GLFW_KEY_UNKNOWN, their state is not saved and so it cannot be queried with glfwGetKey.

Sometimes GLFW needs to generate synthetic key events, in which case the scancode may be zero.

Parameters

[in]	window	The window whose callback to set.

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

Returns

The previously set callback, or NULL if no callback was set or the library had not been initialized.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Key input

Since

Added in version 1.0.

GLFW 3: Added window handle parameter and return value.

          GLFWmousebuttonfun glfwSetMouseButtonCallback
          (
          GLFWwindow *
          window,

          GLFWmousebuttonfun
          cbfun

          )

This function sets the mouse button callback of the specified window, which is called when a mouse button is pressed or released.

When a window loses input focus, it will generate synthetic mouse button release events for all pressed mouse buttons. You can tell these events from user-generated events by the fact that the synthetic ones are generated after the focus loss event has been processed, i.e. after the window focus callback has been called.

Parameters

[in]	window	The window whose callback to set.

[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 or the library had not been initialized.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Mouse button input

Since

Added in version 1.0.

GLFW 3: Added window handle parameter and return value.

          GLFWscrollfun glfwSetScrollCallback
          (
          GLFWwindow *
          window,

          GLFWscrollfun
          cbfun

          )

This function sets the scroll callback of the specified window, which is called when a scrolling device is used, such as a mouse wheel or scrolling area of a touchpad.

The scroll callback receives all scrolling input, like that from a mouse wheel or a touchpad scrolling area.

Parameters

[in]	window	The window whose callback to set.

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

Returns

The previously set callback, or NULL if no callback was set or the library had not been initialized.

Errors

Possible errors include GLFW_NOT_INITIALIZED.

Thread safety

This function must only be called from the main thread.

See also

Scroll input

Since

Added in version 3.0. Replaces glfwSetMouseWheelCallback.

          void glfwSetTime
          (
          double
          time	)

This function sets the value of the GLFW timer. It then continues to count up from that value. The value must be a positive finite number less than or equal to 18446744073.0, which is approximately 584.5 years.

Parameters

[in]	time	The new value, in seconds.

Errors

Possible errors include GLFW_NOT_INITIALIZED and GLFW_INVALID_VALUE.

Remarks

The upper limit of the timer is calculated as floor((264 - 1) / 109) and is due to implementations storing nanoseconds in 64 bits. The limit may be increased in the future.

Thread safety

This function may be called from any thread. Reading and writing of the internal timer offset is not atomic, so it needs to be externally synchronized with calls to glfwGetTime.

See also

Time input

Since

Added in version 2.2.

<address class="footer">

Last update on Thu Aug 18 2016 for GLFW 3.2.1

</address>