GLFW 3.0.1 A multi-platform library for OpenGL, window and input

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Typedefs | Functions
Window handling

## Typedefs

typedef struct GLFWwindow | GLFWwindow
typedef void(* | GLFWwindowposfun )(GLFWwindow *, int, int)
| The function signature for window position callbacks. More...
typedef void(* | GLFWwindowsizefun )(GLFWwindow *, int, int)
| The function signature for window resize callbacks. More...
typedef void(* | GLFWwindowclosefun )(GLFWwindow *)
| The function signature for window close callbacks. More...
typedef void(* | GLFWwindowrefreshfun )(GLFWwindow *)
| The function signature for window content refresh callbacks. More...
typedef void(* | GLFWwindowfocusfun )(GLFWwindow *, int)
| The function signature for window focus/defocus callbacks. More...
typedef void(* | GLFWwindowiconifyfun )(GLFWwindow *, int)
| The function signature for window iconify/restore callbacks. More...
typedef void(* | GLFWframebuffersizefun )(GLFWwindow *, int, int)
| The function signature for framebuffer resize callbacks. More...

## Functions

void | glfwDefaultWindowHints (void)
| Resets all window hints to their default values. More...
void | glfwWindowHint (int target, int hint)
| Sets the specified window hint to the desired value. More...
GLFWwindow * | glfwCreateWindow (int width, int height, const char *title, GLFWmonitor *monitor, GLFWwindow *share)
| Creates a window and its associated context. More...
void | glfwDestroyWindow (GLFWwindow *window)
| Destroys the specified window and its context. More...
int | glfwWindowShouldClose (GLFWwindow *window)
| Checks the close flag of the specified window. More...
void | glfwSetWindowShouldClose (GLFWwindow *window, int value)
| Sets the close flag of the specified window. More...
void | glfwSetWindowTitle (GLFWwindow *window, const char *title)
| Sets the title of the specified window. More...
void | glfwGetWindowPos (GLFWwindow *window, int *xpos, int *ypos)
| Retrieves the position of the client area of the specified window. More...
void | glfwSetWindowPos (GLFWwindow *window, int xpos, int ypos)
| Sets the position of the client area of the specified window. More...
void | glfwGetWindowSize (GLFWwindow *window, int *width, int *height)
| Retrieves the size of the client area of the specified window. More...
void | glfwSetWindowSize (GLFWwindow *window, int width, int height)
| Sets the size of the client area of the specified window. More...
void | glfwGetFramebufferSize (GLFWwindow *window, int *width, int *height)
| Retrieves the size of the framebuffer of the specified window. More...
void | glfwIconifyWindow (GLFWwindow *window)
| Iconifies the specified window. More...
void | glfwRestoreWindow (GLFWwindow *window)
| Restores the specified window. More...
void | glfwShowWindow (GLFWwindow *window)
| Makes the specified window visible. More...
void | glfwHideWindow (GLFWwindow *window)
| Hides the specified window. More...
GLFWmonitor * | glfwGetWindowMonitor (GLFWwindow *window)
| Returns the monitor that the window uses for full screen mode. More...
int | glfwGetWindowAttrib (GLFWwindow *window, int attrib)
| Returns an attribute of the specified window. More...
void | glfwSetWindowUserPointer (GLFWwindow *window, void *pointer)
| Sets the user pointer of the specified window. More...
void * | glfwGetWindowUserPointer (GLFWwindow *window)
| Returns the user pointer of the specified window. More...
GLFWwindowposfun | glfwSetWindowPosCallback (GLFWwindow *window, GLFWwindowposfun cbfun)
| Sets the position callback for the specified window. More...
GLFWwindowsizefun | glfwSetWindowSizeCallback (GLFWwindow *window, GLFWwindowsizefun cbfun)
| Sets the size callback for the specified window. More...
GLFWwindowclosefun | glfwSetWindowCloseCallback (GLFWwindow *window, GLFWwindowclosefun cbfun)
| Sets the close callback for the specified window. More...
GLFWwindowrefreshfun | glfwSetWindowRefreshCallback (GLFWwindow *window, GLFWwindowrefreshfun cbfun)
| Sets the refresh callback for the specified window. More...
GLFWwindowfocusfun | glfwSetWindowFocusCallback (GLFWwindow *window, GLFWwindowfocusfun cbfun)
| Sets the focus callback for the specified window. More...
GLFWwindowiconifyfun | glfwSetWindowIconifyCallback (GLFWwindow *window, GLFWwindowiconifyfun cbfun)
| Sets the iconify callback for the specified window. More...
GLFWframebuffersizefun | glfwSetFramebufferSizeCallback (GLFWwindow *window, GLFWframebuffersizefun cbfun)
| Sets the framebuffer resize callback for the specified window. More...
void | glfwPollEvents (void)
| Processes all pending events. More...
void | glfwWaitEvents (void)
| Waits until events are pending and processes them. More...

## Detailed Description

This is the reference documentation for the window handling API, including creation, deletion and event polling. For more information, see the article on window handling.

## Typedef Documentation

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

This is the function signature for framebuffer resize callback functions.

Parameters

  [in] | window | The window whose framebuffer was resized.
  [in] | width | The new width, in pixels, of the framebuffer.
  [in] | height | The new height, in pixels, of the framebuffer.

See Also
  glfwSetFramebufferSizeCallback

typedef struct GLFWwindow GLFWwindow

Opaque window object.

typedef void(* GLFWwindowclosefun)(GLFWwindow *)

This is the function signature for window close callback functions.

Parameters

  [in] | window | The window that the user attempted to close.

See Also
  glfwSetWindowCloseCallback

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

This is the function signature for window focus callback functions.

Parameters

  [in] | window | The window that was focused or defocused.
  [in] | focused | `GL_TRUE` if the window was focused, or `GL_FALSE` if it was defocused.

See Also
  glfwSetWindowFocusCallback

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

This is the function signature for window iconify/restore callback functions.

Parameters

  [in] | window | The window that was iconified or restored.
  [in] | iconified | `GL_TRUE` if the window was iconified, or `GL_FALSE` if it was restored.

See Also
  glfwSetWindowIconifyCallback

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

This is the function signature for window position callback functions.

Parameters

  [in] | window | The window that the user moved.
  [in] | xpos | The new x-coordinate, in screen coordinates, of the upper-left corner of the client area of the window.
  [in] | ypos | The new y-coordinate, in screen coordinates, of the upper-left corner of the client area of the window.

See Also
  glfwSetWindowPosCallback

typedef void(* GLFWwindowrefreshfun)(GLFWwindow *)

This is the function signature for window refresh callback functions.

Parameters

  [in] | window | The window whose content needs to be refreshed.

See Also
  glfwSetWindowRefreshCallback

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

This is the function signature for window size callback functions.

Parameters

  [in] | window | The window that the user resized.
  [in] | width | The new width, in screen coordinates, of the window.
  [in] | height | The new height, in screen coordinates, of the window.

See Also
  glfwSetWindowSizeCallback

## Function Documentation

GLFWwindow* glfwCreateWindow | ( | int | width,
|  | int | height,
|  | const char * | title,
|  | GLFWmonitor * | monitor,
|  | GLFWwindow * | share
| ) |  |

This function creates a window and its associated context. Most of the options controlling how the window and its context should be created are specified through glfwWindowHint.

Successful creation does not change which context is current. Before you can use the newly created context, you need to make it current using glfwMakeContextCurrent.

Note that the created window and context may differ from what you requested, as not all parameters and hints are hard constraints. This includes the size of the window, especially for full screen windows. To retrieve the actual attributes of the created window and context, use queries like glfwGetWindowAttrib and glfwGetWindowSize.

To create the window at a specific position, make it initially invisible using the `GLFW_VISIBLE` window hint, set its position and then show it.

If a fullscreen window is active, the screensaver is prohibited from starting.

Parameters

  [in] | width | The desired width, in screen coordinates, of the window. This must be greater than zero.
  [in] | height | The desired height, in screen coordinates, of the window. This must be greater than zero.
  [in] | title | The initial, UTF-8 encoded window title.
  [in] | monitor | The monitor to use for full screen mode, or `NULL` to use windowed mode.
  [in] | share | The window whose context to share resources with, or `NULL` to not share resources.

Returns
  The handle of the created window, or `NULL` if an error occurred.

Remarks
  Windows: If the executable has an icon resource named `GLFW_ICON,` it will be set as the icon for the window. If no such icon is present, the `IDI_WINLOGO` icon will be used instead.
  Mac OS X: The GLFW window has no icon, as it is not a document window, but the dock icon will be the same as the application bundle's icon. Also, the first time a window is opened the menu bar is populated with common commands like Hide, Quit and About. The (minimal) about dialog uses information from the application's bundle. For more information on bundles, see the Bundle Programming Guide provided by Apple.

Note
  This function may only be called from the main thread.

See Also
  glfwDestroyWindow

void glfwDefaultWindowHints | ( | void |  | ) |

This function resets all window hints to their default values.

Note
  This function may only be called from the main thread.

See Also
  glfwWindowHint

void glfwDestroyWindow | ( | GLFWwindow * | window | ) |

This function destroys the specified window and its context. On calling this function, no further callbacks will be called for that window.

Parameters

  [in] | window | The window to destroy.

Note
  This function may only be called from the main thread.
  This function may not be called from a callback.
  If the window's context is current on the main thread, it is detached before being destroyed.

Warning
  The window's context must not be current on any other thread.

See Also
  glfwCreateWindow

void glfwGetFramebufferSize | ( | GLFWwindow * | window,
|  | int * | width,
|  | int * | height
| ) |  |

This function retrieves the size, in pixels, of the framebuffer of the specified window.

Parameters

  [in] | window | The window whose framebuffer to query.
  [out] | width | Where to store the width, in pixels, of the framebuffer, or `NULL`.
  [out] | height | Where to store the height, in pixels, of the framebuffer, or `NULL`.

See Also
  glfwSetFramebufferSizeCallback

int glfwGetWindowAttrib | ( | GLFWwindow * | window,
|  | int | attrib
| ) |  |

This function returns an attribute of the specified window. There are many attributes, some related to the window and others to its context.

Parameters

  [in] | window | The window to query.
  [in] | attrib | The window attribute whose value to return.

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

GLFWmonitor* glfwGetWindowMonitor | ( | GLFWwindow * | window | ) |

This function returns the handle of the monitor that the specified window is in full screen on.

Parameters

  [in] | window | The window to query.

Returns
  The monitor, or `NULL` if the window is in windowed mode.

void glfwGetWindowPos | ( | GLFWwindow * | window,
|  | int * | xpos,
|  | int * | ypos
| ) |  |

This function retrieves the position, in screen coordinates, of the upper-left corner of the client area of the specified window.

Parameters

  [in] | window | The window to query.
  [out] | xpos | Where to store the x-coordinate of the upper-left corner of the client area, or `NULL`.
  [out] | ypos | Where to store the y-coordinate of the upper-left corner of the client area, or `NULL`.

See Also
  glfwSetWindowPos

void glfwGetWindowSize | ( | GLFWwindow * | window,
|  | int * | width,
|  | int * | height
| ) |  |

This function retrieves the size, in screen coordinates, of the client area of the specified window.

Parameters

  [in] | window | The window whose size to retrieve.
  [out] | width | Where to store the width, in screen coordinates, of the client area, or `NULL`.
  [out] | height | Where to store the height, in screen coordinates, of the client area, or `NULL`.

See Also
  glfwSetWindowSize

void* glfwGetWindowUserPointer | ( | GLFWwindow * | window | ) |

This function returns the current value of the user-defined pointer of the specified window. The initial value is `NULL`.

Parameters

  [in] | window | The window whose pointer to return.

See Also
  glfwSetWindowUserPointer

void glfwHideWindow | ( | GLFWwindow * | window | ) |

This function hides the specified window, if it was previously visible. If the window is already hidden or is in full screen mode, this function does nothing.

Parameters

  [in] | window | The window to hide.

Note
  This function may only be called from the main thread.

See Also
  glfwShowWindow

void glfwIconifyWindow | ( | GLFWwindow * | window | ) |

This function iconifies/minimizes the specified window, if it was previously restored. If it is a full screen window, the original monitor resolution is restored until the window is restored. If the window is already iconified, this function does nothing.

Parameters

  [in] | window | The window to iconify.

Note
  This function may only be called from the main thread.

See Also
  glfwRestoreWindow

void glfwPollEvents | ( | void |  | ) |

This function processes only those events that have already been received and then returns immediately. Processing events will cause the window and input callbacks associated with those events to be called.

This function is not required for joystick input to work.

New in GLFW 3
  This function is no longer called by glfwSwapBuffers. You need to call it or glfwWaitEvents yourself.

Note
  This function may only be called from the main thread.
  This function may not be called from a callback.
  On some platforms, certain callbacks may be called outside of a call to one of the event processing functions.

See Also
  glfwWaitEvents

void glfwRestoreWindow | ( | GLFWwindow * | window | ) |

This function restores the specified window, if it was previously iconified/minimized. If it is a full screen window, the resolution chosen for the window is restored on the selected monitor. If the window is already restored, this function does nothing.

Parameters

  [in] | window | The window to restore.

Note
  This function may only be called from the main thread.

See Also
  glfwIconifyWindow

GLFWframebuffersizefun glfwSetFramebufferSizeCallback | ( | GLFWwindow * | window,
|  | GLFWframebuffersizefun | cbfun
| ) |  |

This function sets the framebuffer resize callback of the specified window, which is called when the framebuffer of the specified window is resized.

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.

GLFWwindowclosefun glfwSetWindowCloseCallback | ( | GLFWwindow * | window,
|  | GLFWwindowclosefun | cbfun
| ) |  |

This function sets the close callback of the specified window, which is called when the user attempts to close the window, for example by clicking the close widget in the title bar.

The close flag is set before this callback is called, but you can modify it at any time with glfwSetWindowShouldClose.

The close callback is not triggered by glfwDestroyWindow.

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.

Remarks
  Mac OS X: Selecting Quit from the application menu will trigger the close callback for all windows.

GLFWwindowfocusfun glfwSetWindowFocusCallback | ( | GLFWwindow * | window,
|  | GLFWwindowfocusfun | cbfun
| ) |  |

This function sets the focus callback of the specified window, which is called when the window gains or loses focus.

After the focus callback is called for a window that lost focus, synthetic key and mouse button release events will be generated for all such that had been pressed. For more information, see glfwSetKeyCallback and glfwSetMouseButtonCallback.

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.

GLFWwindowiconifyfun glfwSetWindowIconifyCallback | ( | GLFWwindow * | window,
|  | GLFWwindowiconifyfun | cbfun
| ) |  |

This function sets the iconification callback of the specified window, which is called when the window is iconified or restored.

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.

void glfwSetWindowPos | ( | GLFWwindow * | window,
|  | int | xpos,
|  | int | ypos
| ) |  |

This function sets the position, in screen coordinates, of the upper-left corner of the client area of the window.

If the specified window is a full screen window, this function does nothing.

If you wish to set an initial window position you should create a hidden window (using glfwWindowHint and `GLFW_VISIBLE`), set its position and then show it.

Parameters

  [in] | window | The window to query.
  [in] | xpos | The x-coordinate of the upper-left corner of the client area.
  [in] | ypos | The y-coordinate of the upper-left corner of the client area.

Note
  It is very rarely a good idea to move an already visible window, as it will confuse and annoy the user.
  This function may only be called from the main thread.
  The window manager may put limits on what positions are allowed.

Bug:
  X11: Some window managers ignore the set position of hidden (i.e. unmapped) windows, instead placing them where it thinks is appropriate once they are shown.

See Also
  glfwGetWindowPos

GLFWwindowposfun glfwSetWindowPosCallback | ( | GLFWwindow * | window,
|  | GLFWwindowposfun | cbfun
| ) |  |

This function sets the position callback of the specified window, which is called when the window is moved. The callback is provided with the screen position of 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 an error occurred.

GLFWwindowrefreshfun glfwSetWindowRefreshCallback | ( | GLFWwindow * | window,
|  | GLFWwindowrefreshfun | cbfun
| ) |  |

This function sets the refresh callback of the specified window, which is called when the client area of the window needs to be redrawn, for example if the window has been exposed after having been covered by another window.

On compositing window systems such as Aero, Compiz or Aqua, where the window contents are saved off-screen, this callback may be called only very infrequently or never at all.

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.

Note
  On compositing window systems such as Aero, Compiz or Aqua, where the window contents are saved off-screen, this callback may be called only very infrequently or never at all.

void glfwSetWindowShouldClose | ( | GLFWwindow * | window,
|  | int | value
| ) |  |

This function sets the value of the close flag of the specified window. This can be used to override the user's attempt to close the window, or to signal that it should be closed.

Parameters

  [in] | window | The window whose flag to change.
  [in] | value | The new value.

void glfwSetWindowSize | ( | GLFWwindow * | window,
|  | int | width,
|  | int | height
| ) |  |

This function sets the size, in screen coordinates, of the client area of the specified window.

For full screen windows, this function selects and switches to the resolution closest to the specified size, without affecting the window's context. As the context is unaffected, the bit depths of the framebuffer remain unchanged.

Parameters

  [in] | window | The window to resize.
  [in] | width | The desired width of the specified window.
  [in] | height | The desired height of the specified window.

Note
  This function may only be called from the main thread.
  The window manager may put limits on what window sizes are allowed.

See Also
  glfwGetWindowSize

GLFWwindowsizefun glfwSetWindowSizeCallback | ( | GLFWwindow * | window,
|  | GLFWwindowsizefun | cbfun
| ) |  |

This function sets the size callback of the specified window, which is called when the window is resized. The callback is provided with the size, in screen coordinates, 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 an error occurred.

void glfwSetWindowTitle | ( | GLFWwindow * | window,
|  | const char * | title
| ) |  |

This function sets the window title, encoded as UTF-8, of the specified window.

Parameters

  [in] | window | The window whose title to change.
  [in] | title | The UTF-8 encoded window title.

Note
  This function may only be called from the main thread.

void glfwSetWindowUserPointer | ( | GLFWwindow * | window,
|  | void * | pointer
| ) |  |

This function sets the user-defined pointer of the specified window. The current value is retained until the window is destroyed. The initial value is `NULL`.

Parameters

  [in] | window | The window whose pointer to set.
  [in] | pointer | The new value.

See Also
  glfwGetWindowUserPointer

void glfwShowWindow | ( | GLFWwindow * | window | ) |

This function makes the specified window visible, if it was previously hidden. If the window is already visible or is in full screen mode, this function does nothing.

Parameters

  [in] | window | The window to make visible.

Note
  This function may only be called from the main thread.

See Also
  glfwHideWindow

void glfwWaitEvents | ( | void |  | ) |

This function puts the calling thread to sleep until at least one event has been received. Once one or more events have been recevied, it behaves as if glfwPollEvents was called, i.e. the events are processed and the function then returns immediately. Processing events will cause the window and input callbacks associated with those events to be called.

Since not all events are associated with callbacks, this function may return without a callback having been called even if you are monitoring all callbacks.

This function is not required for joystick input to work.

Note
  This function may only be called from the main thread.
  This function may not be called from a callback.
  On some platforms, certain callbacks may be called outside of a call to one of the event processing functions.

See Also
  glfwPollEvents

void glfwWindowHint | ( | int | target,
|  | int | hint
| ) |  |

This function sets hints for the next call to glfwCreateWindow. The hints, once set, retain their values until changed by a call to glfwWindowHint or glfwDefaultWindowHints, or until the library is terminated with glfwTerminate.

Parameters

  [in] | target | The window hint to set.
  [in] | hint | The new value of the window hint.

New in GLFW 3
  Hints are no longer reset to their default values on window creation. To set default hint values, use glfwDefaultWindowHints.

Note
  This function may only be called from the main thread.

See Also
  glfwDefaultWindowHints

int glfwWindowShouldClose | ( | GLFWwindow * | window | ) |

This function returns the value of the close flag of the specified window.

Parameters

  [in] | window | The window to query.

Returns
  The value of the close flag.