Window reference
Overview
This is the reference documentation for window related functions and types, including creation, deletion and event polling.
For more task-oriented information, see the window_guide.
// typedefs typedef struct GLFWwindow GLFWwindow; typedef void (*GLFWwindowposfun)( GLFWwindow *, int, int ); typedef void (*GLFWwindowsizefun)( GLFWwindow *, int, int ); typedef void (*GLFWwindowclosefun)(GLFWwindow *); typedef void (*GLFWwindowrefreshfun)(GLFWwindow *); typedef void (*GLFWwindowfocusfun)( GLFWwindow *, int ); typedef void (*GLFWwindowiconifyfun)( GLFWwindow *, int ); typedef void (*GLFWframebuffersizefun)( GLFWwindow *, int, int ); // global functions GLFWAPI void glfwDefaultWindowHints(void); GLFWAPI void glfwWindowHint(int hint, int value); GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share); GLFWAPI void glfwDestroyWindow(GLFWwindow* window); GLFWAPI int glfwWindowShouldClose(GLFWwindow* window); GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value); GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title); GLFWAPI void glfwSetWindowIcon(GLFWwindow* window, int count, const GLFWimage* images); GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos); GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos); GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height); GLFWAPI void glfwSetWindowSizeLimits(GLFWwindow* window, int minwidth, int minheight, int maxwidth, int maxheight); GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom); GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height); GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height); GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int* right, int* bottom); GLFWAPI void glfwIconifyWindow(GLFWwindow* window); GLFWAPI void glfwRestoreWindow(GLFWwindow* window); GLFWAPI void glfwMaximizeWindow(GLFWwindow* window); GLFWAPI void glfwShowWindow(GLFWwindow* window); GLFWAPI void glfwHideWindow(GLFWwindow* window); GLFWAPI void glfwFocusWindow(GLFWwindow* window); GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window); GLFWAPI void glfwSetWindowMonitor( GLFWwindow* window, GLFWmonitor* monitor, int xpos, int ypos, int width, int height, int refreshRate ); GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib); GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer); GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window); GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun); GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun cbfun); GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun cbfun); GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun cbfun); GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun cbfun); GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun cbfun); GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun cbfun); GLFWAPI void glfwPollEvents(void); GLFWAPI void glfwWaitEvents(void); GLFWAPI void glfwWaitEventsTimeout(double timeout); GLFWAPI void glfwPostEmptyEvent(void); GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
Typedefs
typedef struct GLFWwindow GLFWwindow
Opaque window object.
Opaque window object.
Added in version 3.0.
See also:
window_object
typedef void (*GLFWwindowposfun)( GLFWwindow *, int, int )
The function signature for window position callbacks.
This is the function signature for window position callback functions.
Added in version 3.0.
Parameters:
window |
The window that was moved. |
xpos |
The new x-coordinate, in screen coordinates, of the upper-left corner of the client area of the window. |
ypos |
The new y-coordinate, in screen coordinates, of the upper-left corner of the client area of the window. |
See also:
window_pos
typedef void (*GLFWwindowsizefun)( GLFWwindow *, int, int )
The function signature for window resize callbacks.
This is the function signature for window size callback functions.
Added in version 1.0. @glfw3 Added window handle parameter.
Parameters:
window |
The window that was resized. |
width |
The new width, in screen coordinates, of the window. |
height |
The new height, in screen coordinates, of the window. |
See also:
window_size
typedef void (*GLFWwindowclosefun)(GLFWwindow *)
The function signature for window close callbacks.
This is the function signature for window close callback functions.
Added in version 2.5. @glfw3 Added window handle parameter.
Parameters:
window |
The window that the user attempted to close. |
See also:
window_close
typedef void (*GLFWwindowrefreshfun)(GLFWwindow *)
The function signature for window content refresh callbacks.
This is the function signature for window refresh callback functions.
Added in version 2.5. @glfw3 Added window handle parameter.
Parameters:
window |
The window whose content needs to be refreshed. |
See also:
window_refresh
typedef void (*GLFWwindowfocusfun)( GLFWwindow *, int )
The function signature for window focus/defocus callbacks.
This is the function signature for window focus callback functions.
Added in version 3.0.
Parameters:
window |
The window that gained or lost input focus. |
focused |
|
See also:
window_focus
typedef void (*GLFWwindowiconifyfun)( GLFWwindow *, int )
The function signature for window iconify/restore callbacks.
This is the function signature for window iconify/restore callback functions.
Added in version 3.0.
Parameters:
window |
The window that was iconified or restored. |
iconified |
|
See also:
window_iconify
typedef void (*GLFWframebuffersizefun)( GLFWwindow *, int, int )
The function signature for framebuffer resize callbacks.
This is the function signature for framebuffer resize callback functions.
Added in version 3.0.
Parameters:
window |
The window whose framebuffer was resized. |
width |
The new width, in pixels, of the framebuffer. |
height |
The new height, in pixels, of the framebuffer. |
See also:
window_fbsize
Global Functions
GLFWAPI void glfwDefaultWindowHints(void)
Resets all window hints to their default values.
This function resets all window hints to their default values.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
See also:
window_hints
GLFWAPI void glfwWindowHint(int hint, int value)
Sets the specified window hint to the desired value.
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.
This function does not check whether the specified hint values are valid. If you set hints to invalid values this will instead be reported by the next call to glfwCreateWindow.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_INVALID_ENUM.
@thread_safety This function must only be called from the main thread.
Added in version 3.0. Replaces glfwOpenWindowHint.
Parameters:
hint |
The window hint to set. |
value |
The new value of the window hint. |
See also:
window_hints
GLFWAPI GLFWwindow* glfwCreateWindow( int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share )
Creates a window and its associated context.
This function creates a window and its associated OpenGL or OpenGL ES context. Most of the options controlling how the window and its context should be created are specified with window hints.
Successful creation does not change which context is current. Before you can use the newly created context, you need to make it current. For information about the share parameter, see context_sharing.
The created window, framebuffer 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 query the actual attributes of the created window, framebuffer and context, see glfwGetWindowAttrib, glfwGetWindowSize and glfwGetFramebufferSize.
To create a full screen window, you need to specify the monitor the window will cover. If no monitor is specified, the window will be windowed mode. Unless you have a way for the user to choose a specific monitor, it is recommended that you pick the primary monitor. For more information on how to query connected monitors, see monitor_monitors.
For full screen windows, the specified size becomes the resolution of the window’s desired video mode. As long as a full screen window is not iconified, the supported video mode most closely matching the desired video mode is set for the specified monitor. For more information about full screen windows, including the creation of so called windowed full screen or borderless full screen windows, see window_windowed_full_screen.
By default, newly created windows use the placement recommended by the window system. 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.
As long as at least one full screen window is not iconified, the screensaver is prohibited from starting.
Window systems put limits on window sizes. Very large or very small window dimensions may be overridden by the window system on creation. Check the actual size after creation.
The swap interval is not set during window creation and the initial value may vary depending on driver settings and defaults.
@errors Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_ENUM, GLFW_INVALID_VALUE, GLFW_API_UNAVAILABLE, GLFW_VERSION_UNAVAILABLE, GLFW_FORMAT_UNAVAILABLE and GLFW_PLATFORM_ERROR.
@win32 Window creation will fail if the Microsoft GDI software OpenGL implementation is the only one available.
@win32 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.
@win32 The context to share resources with must not be current on any other thread.
@osx 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. For more information on bundles, see the Bundle Programming Guide in the Mac Developer Library.
@osx The first time a window is created the menu bar is populated with common commands like Hide, Quit and About. The About entry opens a minimal about dialog with information from the application’s bundle. The menu bar can be disabled with a compile-time option.
@osx On OS X 10.10 and later the window frame will not be rendered at full resolution on Retina displays unless the NSHighResolutionCapable key is enabled in the application bundle’s Info.plist. For more information, see High Resolution Guidelines for OS X in the Mac Developer Library. The GLFW test and example programs use a custom Info.plist template for this, which can be found as CMake/MacOSXBundleInfo.plist.in in the source tree.
@x11 There is no mechanism for setting the window icon yet.
@x11 Some window managers will not respect the placement of initially hidden windows.
@x11 Due to the asynchronous nature of X11, it may take a moment for a window to reach its requested state. This means you may not be able to query the final size, position or other attributes directly after window creation.
@reentrancy This function must not be called from a callback.
@thread_safety This function must only be called from the main thread.
Added in version 3.0. Replaces glfwOpenWindow.
Parameters:
width |
The desired width, in screen coordinates, of the window. This must be greater than zero. |
height |
The desired height, in screen coordinates, of the window. This must be greater than zero. |
title |
The initial, UTF-8 encoded window title. |
monitor |
The monitor to use for full screen mode, or |
share |
The window whose context to share resources with, or |
Returns:
The handle of the created window, or NULL if an error occurred.
See also:
window_creation
GLFWAPI void glfwDestroyWindow(GLFWwindow* window)
Destroys the specified window and its context.
This function destroys the specified window and its context. On calling this function, no further callbacks will be called for that window.
If the context of the specified window is current on the main thread, it is detached before being destroyed.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
The context of the specified window must not be current on any other thread when this function is called.
@reentrancy This function must not be called from a callback.
@thread_safety This function must only be called from the main thread.
Added in version 3.0. Replaces glfwCloseWindow.
Parameters:
window |
The window to destroy. |
See also:
window_creation
GLFWAPI int glfwWindowShouldClose(GLFWwindow* window)
Checks the close flag of the specified window.
This function returns the value of the close flag of the specified window.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function may be called from any thread. Access is not synchronized.
Added in version 3.0.
Parameters:
window |
The window to query. |
Returns:
The value of the close flag.
See also:
window_close
GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value)
Sets the close flag of the specified window.
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.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function may be called from any thread. Access is not synchronized.
Added in version 3.0.
Parameters:
window |
The window whose flag to change. |
value |
The new value. |
See also:
window_close
GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title)
Sets the title of the specified window.
This function sets the window title, encoded as UTF-8, of the specified window.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@osx The window title will not be updated until the next time you process events.
@thread_safety This function must only be called from the main thread.
Added in version 1.0. @glfw3 Added window handle parameter.
Parameters:
window |
The window whose title to change. |
title |
The UTF-8 encoded window title. |
See also:
window_title
GLFWAPI void glfwSetWindowIcon(GLFWwindow* window, int count, const GLFWimage* images)
Sets the icon for the specified window.
This function sets the icon of the specified window. If passed an array of candidate images, those of or closest to the sizes desired by the system are selected. If no images are specified, the window reverts to its default icon.
The desired image sizes varies depending on platform and system settings. The selected images will be rescaled as needed. Good sizes include 16x16, 32x32 and 48x48.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@pointer_lifetime The specified image data is copied before this function returns.
@osx 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. For more information on bundles, see the Bundle Programming Guide in the Mac Developer Library.
@thread_safety This function must only be called from the main thread.
Added in version 3.2.
Parameters:
window |
The window whose icon to set. |
count |
The number of images in the specified array, or zero to revert to the default window icon. |
images |
The images to create the icon from. This is ignored if count is zero. |
See also:
window_icon
GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos)
Retrieves the position of the client area of the specified window.
This function retrieves the position, in screen coordinates, of the upper-left corner of the client area of the specified window.
Any or all of the position arguments may be NULL. If an error occurs, all non- NULL position arguments will be set to zero.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window to query. |
xpos |
Where to store the x-coordinate of the upper-left corner of the client area, or |
ypos |
Where to store the y-coordinate of the upper-left corner of the client area, or |
See also:
window_pos
GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos)
Sets the position of the client area of the specified window.
This function sets the position, in screen coordinates, of the upper-left corner of the client area of the specified windowed mode window. If the window is a full screen window, this function does nothing.
Do not use this function to move an already visible window unless you have very good reasons for doing so, as it will confuse and annoy the user.
The window manager may put limits on what positions are allowed. GLFW cannot and should not override these limits.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 1.0. @glfw3 Added window handle parameter.
Parameters:
window |
The window to query. |
xpos |
The x-coordinate of the upper-left corner of the client area. |
ypos |
The y-coordinate of the upper-left corner of the client area. |
See also:
window_pos
GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height)
Retrieves the size of the client area of the specified window.
This function retrieves the size, in screen coordinates, of the client area of the specified window. If you wish to retrieve the size of the framebuffer of the window in pixels, see glfwGetFramebufferSize.
Any or all of the size arguments may be NULL. If an error occurs, all non- NULL size arguments will be set to zero.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 1.0. @glfw3 Added window handle parameter.
Parameters:
window |
The window whose size to retrieve. |
width |
Where to store the width, in screen coordinates, of the client area, or |
height |
Where to store the height, in screen coordinates, of the client area, or |
See also:
window_size
GLFWAPI void glfwSetWindowSizeLimits( GLFWwindow* window, int minwidth, int minheight, int maxwidth, int maxheight )
Sets the size limits of the specified window.
This function sets the size limits of the client area of the specified window. If the window is full screen, the size limits only take effect if once it is made windowed. If the window is not resizable, this function does nothing.
The size limits are applied immediately to a windowed mode window and may cause it to be resized.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
If you set size limits and an aspect ratio that conflict, the results are undefined.
@thread_safety This function must only be called from the main thread.
Added in version 3.2.
Parameters:
window |
The window to set limits for. |
minwidth |
The minimum width, in screen coordinates, of the client area, or |
minheight |
The minimum height, in screen coordinates, of the client area, or |
maxwidth |
The maximum width, in screen coordinates, of the client area, or |
maxheight |
The maximum height, in screen coordinates, of the client area, or |
See also:
window_sizelimits
GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom)
Sets the aspect ratio of the specified window.
This function sets the required aspect ratio of the client area of the specified window. If the window is full screen, the aspect ratio only takes effect once it is made windowed. If the window is not resizable, this function does nothing.
The aspect ratio is specified as a numerator and a denominator and both values must be greater than zero. For example, the common 16:9 aspect ratio is specified as 16 and 9, respectively.
If the numerator and denominator is set to GLFW_DONT_CARE then the aspect ratio limit is disabled.
The aspect ratio is applied immediately to a windowed mode window and may cause it to be resized.
@errors Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_VALUE and GLFW_PLATFORM_ERROR.
If you set size limits and an aspect ratio that conflict, the results are undefined.
@thread_safety This function must only be called from the main thread.
Added in version 3.2.
Parameters:
window |
The window to set limits for. |
numer |
The numerator of the desired aspect ratio, or |
denom |
The denominator of the desired aspect ratio, or |
See also:
window_sizelimits
GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height)
Sets the size of the client area of the specified window.
This function sets the size, in screen coordinates, of the client area of the specified window.
For full screen windows, this function updates the resolution of its desired video mode and switches to the video mode closest to it, without affecting the window’s context. As the context is unaffected, the bit depths of the framebuffer remain unchanged.
If you wish to update the refresh rate of the desired video mode in addition to its resolution, see glfwSetWindowMonitor.
The window manager may put limits on what sizes are allowed. GLFW cannot and should not override these limits.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 1.0. @glfw3 Added window handle parameter.
Parameters:
window |
The window to resize. |
width |
The desired width, in screen coordinates, of the window client area. |
height |
The desired height, in screen coordinates, of the window client area. |
See also:
window_size
GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height)
Retrieves the size of the framebuffer of the specified window.
This function retrieves the size, in pixels, of the framebuffer of the specified window. If you wish to retrieve the size of the window in screen coordinates, see glfwGetWindowSize.
Any or all of the size arguments may be NULL. If an error occurs, all non- NULL size arguments will be set to zero.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window whose framebuffer to query. |
width |
Where to store the width, in pixels, of the framebuffer, or |
height |
Where to store the height, in pixels, of the framebuffer, or |
See also:
window_fbsize
glfwSetFramebufferSizeCallback
GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int* right, int* bottom)
Retrieves the size of the frame of the window.
This function retrieves the size, in screen coordinates, of each edge of the frame of the specified window. This size includes the title bar, if the window has one. The size of the frame may vary depending on the window-related hints used to create it.
Because this function retrieves the size of each window frame edge and not the offset along a particular coordinate axis, the retrieved values will always be zero or positive.
Any or all of the size arguments may be NULL. If an error occurs, all non- NULL size arguments will be set to zero.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 3.1.
Parameters:
window |
The window whose frame size to query. |
left |
Where to store the size, in screen coordinates, of the left edge of the window frame, or |
top |
Where to store the size, in screen coordinates, of the top edge of the window frame, or |
right |
Where to store the size, in screen coordinates, of the right edge of the window frame, or |
bottom |
Where to store the size, in screen coordinates, of the bottom edge of the window frame, or |
See also:
window_size
GLFWAPI void glfwIconifyWindow(GLFWwindow* window)
Iconifies the specified window.
This function iconifies (minimizes) the specified window if it was previously restored. If the window is already iconified, this function does nothing.
If the specified window is a full screen window, the original monitor resolution is restored until the window is restored.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 2.1. @glfw3 Added window handle parameter.
Parameters:
window |
The window to iconify. |
See also:
window_iconify
GLFWAPI void glfwRestoreWindow(GLFWwindow* window)
Restores the specified window.
This function restores the specified window if it was previously iconified (minimized) or maximized. If the window is already restored, this function does nothing.
If the specified window is a full screen window, the resolution chosen for the window is restored on the selected monitor.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 2.1. @glfw3 Added window handle parameter.
Parameters:
window |
The window to restore. |
See also:
window_iconify
GLFWAPI void glfwMaximizeWindow(GLFWwindow* window)
Maximizes the specified window.
This function maximizes the specified window if it was previously not maximized. If the window is already maximized, this function does nothing.
If the specified window is a full screen window, this function does nothing.
This function may only be called from the main thread.
Added in GLFW 3.2.
Parameters:
window |
The window to maximize. |
See also:
window_iconify
GLFWAPI void glfwShowWindow(GLFWwindow* window)
Makes the specified window visible.
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.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window to make visible. |
See also:
window_hide
GLFWAPI void glfwHideWindow(GLFWwindow* window)
Hides the specified 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.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window to hide. |
See also:
window_hide
GLFWAPI void glfwFocusWindow(GLFWwindow* window)
Brings the specified window to front and sets input focus.
This function brings the specified window to front and sets input focus. The window should already be visible and not iconified.
By default, both windowed and full screen mode windows are focused when initially created. Set the GLFW_FOCUSED to disable this behavior.
Do not use this function to steal focus from other applications unless you are certain that is what the user wants. Focus stealing can be extremely disruptive.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 3.2.
Parameters:
window |
The window to give input focus. |
See also:
window_focus
GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window)
Returns the monitor that the window uses for full screen mode.
This function returns the handle of the monitor that the specified window is in full screen on.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window to query. |
Returns:
The monitor, or NULL if the window is in windowed mode or an error occurred.
See also:
window_monitor
GLFWAPI void glfwSetWindowMonitor( GLFWwindow* window, GLFWmonitor* monitor, int xpos, int ypos, int width, int height, int refreshRate )
Sets the mode, monitor, video mode and placement of a window.
This function sets the monitor that the window uses for full screen mode or, if the monitor is NULL, makes it windowed mode.
When setting a monitor, this function updates the width, height and refresh rate of the desired video mode and switches to the video mode closest to it. The window position is ignored when setting a monitor.
When the monitor is NULL, the position, width and height are used to place the window client area. The refresh rate is ignored when no monitor is specified.
If you only wish to update the resolution of a full screen window or the size of a windowed mode window, see glfwSetWindowSize.
When a window transitions from full screen to windowed mode, this function restores any previous window settings such as whether it is decorated, floating, resizable, has size or aspect ratio limits, etc..
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function must only be called from the main thread.
Added in version 3.2.
Parameters:
window |
The window whose monitor, size or video mode to set. |
monitor |
The desired monitor, or |
xpos |
The desired x-coordinate of the upper-left corner of the client area. |
ypos |
The desired y-coordinate of the upper-left corner of the client area. |
width |
The desired with, in screen coordinates, of the client area or video mode. |
height |
The desired height, in screen coordinates, of the client area or video mode. |
refreshRate |
The desired refresh rate, in Hz, of the video mode. |
See also:
window_monitor
window_full_screen
GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib)
Returns an attribute of the specified window.
This function returns the value of an attribute of the specified window or its OpenGL or OpenGL ES context.
@errors Possible errors include GLFW_NOT_INITIALIZED, GLFW_INVALID_ENUM and GLFW_PLATFORM_ERROR.
Framebuffer related hints are not window attributes. See window_attribs_fb for more information.
Zero is a valid value for many window and context related attributes so you cannot use a return value of zero as an indication of errors. However, this function should not fail as long as it is passed valid arguments and the library has been initialized.
@thread_safety This function must only be called from the main thread.
Added in version 3.0. Replaces glfwGetWindowParam and glfwGetGLVersion.
Parameters:
window |
The window to query. |
attrib |
The window attribute whose value to return. |
Returns:
The value of the attribute, or zero if an error occurred.
See also:
window_attribs
GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer)
Sets the user pointer of the specified window.
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.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function may be called from any thread. Access is not synchronized.
Added in version 3.0.
Parameters:
window |
The window whose pointer to set. |
pointer |
The new value. |
See also:
window_userptr
GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window)
Returns the user pointer of the specified window.
This function returns the current value of the user-defined pointer of the specified window. The initial value is NULL.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function may be called from any thread. Access is not synchronized.
Added in version 3.0.
Parameters:
window |
The window whose pointer to return. |
See also:
window_userptr
GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindowposfun cbfun)
Sets the position callback for the specified window.
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.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window whose callback to set. |
cbfun |
The new callback, or |
Returns:
The previously set callback, or NULL if no callback was set or the library had not been initialized.
See also:
window_pos
GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwindowsizefun cbfun)
Sets the size callback for the specified window.
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.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function must only be called from the main thread.
Added in version 1.0. @glfw3 Added window handle parameter and return value.
Parameters:
window |
The window whose callback to set. |
cbfun |
The new callback, or |
Returns:
The previously set callback, or NULL if no callback was set or the library had not been initialized.
See also:
window_size
GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun cbfun)
Sets the close callback for the specified window.
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.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@osx Selecting Quit from the application menu will trigger the close callback for all windows.
@thread_safety This function must only be called from the main thread.
Added in version 2.5. @glfw3 Added window handle parameter and return value.
Parameters:
window |
The window whose callback to set. |
cbfun |
The new callback, or |
Returns:
The previously set callback, or NULL if no callback was set or the library had not been initialized.
See also:
window_close
GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GLFWwindowrefreshfun cbfun)
Sets the refresh callback for the specified window.
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.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function must only be called from the main thread.
Added in version 2.5. @glfw3 Added window handle parameter and return value.
Parameters:
window |
The window whose callback to set. |
cbfun |
The new callback, or |
Returns:
The previously set callback, or NULL if no callback was set or the library had not been initialized.
See also:
window_refresh
GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwindowfocusfun cbfun)
Sets the focus callback for the specified window.
This function sets the focus callback of the specified window, which is called when the window gains or loses input focus.
After the focus callback is called for a window that lost input 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.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window whose callback to set. |
cbfun |
The new callback, or |
Returns:
The previously set callback, or NULL if no callback was set or the library had not been initialized.
See also:
window_focus
GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GLFWwindowiconifyfun cbfun)
Sets the iconify callback for the specified window.
This function sets the iconification callback of the specified window, which is called when the window is iconified or restored.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window whose callback to set. |
cbfun |
The new callback, or |
Returns:
The previously set callback, or NULL if no callback was set or the library had not been initialized.
See also:
window_iconify
GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window, GLFWframebuffersizefun cbfun)
Sets the framebuffer resize callback for the specified window.
This function sets the framebuffer resize callback of the specified window, which is called when the framebuffer of the specified window is resized.
@errors Possible errors include GLFW_NOT_INITIALIZED.
@thread_safety This function must only be called from the main thread.
Added in version 3.0.
Parameters:
window |
The window whose callback to set. |
cbfun |
The new callback, or |
Returns:
The previously set callback, or NULL if no callback was set or the library had not been initialized.
See also:
window_fbsize
GLFWAPI void glfwPollEvents(void)
Processes all pending events.
This function processes only those events that are already in the event queue and then returns immediately. Processing events will cause the window and input callbacks associated with those events to be called.
On some platforms, a window move, resize or menu operation will cause event processing to block. This is due to how event processing is designed on those platforms. You can use the window refresh callback to redraw the contents of your window when necessary during such operations.
On some platforms, certain events are sent directly to the application without going through the event queue, causing callbacks to be called outside of a call to one of the event processing functions.
Event processing is not required for joystick input to work.
@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.
Added in version 1.0.
See also:
events
GLFWAPI void glfwWaitEvents(void)
Waits until events are queued and processes them.
This function puts the calling thread to sleep until at least one event is available in the event queue. Once one or more events are available, it behaves exactly like glfwPollEvents, i.e. the events in the queue 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.
On some platforms, a window move, resize or menu operation will cause event processing to block. This is due to how event processing is designed on those platforms. You can use the window refresh callback to redraw the contents of your window when necessary during such operations.
On some platforms, certain callbacks may be called outside of a call to one of the event processing functions.
If no windows exist, this function returns immediately. For synchronization of threads in applications that do not create windows, use your threading library of choice.
Event processing is not required for joystick input to work.
@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.
Added in version 2.5.
See also:
events
GLFWAPI void glfwWaitEventsTimeout(double timeout)
Waits with timeout until events are queued and processes them.
This function puts the calling thread to sleep until at least one event is available in the event queue, or until the specified timeout is reached. If one or more events are available, it behaves exactly like glfwPollEvents, i.e. the events in the queue are processed and the function then returns immediately. Processing events will cause the window and input callbacks associated with those events to be called.
The timeout value must be a positive finite number.
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.
On some platforms, a window move, resize or menu operation will cause event processing to block. This is due to how event processing is designed on those platforms. You can use the window refresh callback to redraw the contents of your window when necessary during such operations.
On some platforms, certain callbacks may be called outside of a call to one of the event processing functions.
If no windows exist, this function returns immediately. For synchronization of threads in applications that do not create windows, use your threading library of choice.
Event processing is not required for joystick input to work.
@reentrancy This function must not be called from a callback.
@thread_safety This function must only be called from the main thread.
Added in version 3.2.
Parameters:
timeout |
The maximum amount of time, in seconds, to wait. |
See also:
events
GLFWAPI void glfwPostEmptyEvent(void)
Posts an empty event to the event queue.
This function posts an empty event from the current thread to the event queue, causing glfwWaitEvents to return.
If no windows exist, this function returns immediately. For synchronization of threads in applications that do not create windows, use your threading library of choice.
@errors Possible errors include GLFW_NOT_INITIALIZED and GLFW_PLATFORM_ERROR.
@thread_safety This function may be called from any thread.
Added in version 3.1.
See also:
events
GLFWAPI void glfwSwapBuffers(GLFWwindow* window)
Swaps the front and back buffers of the specified window.
This function swaps the front and back buffers of the specified window when rendering with OpenGL or OpenGL ES. If the swap interval is greater than zero, the GPU driver waits the specified number of screen updates before swapping the buffers.
The specified window must have an OpenGL or OpenGL ES context. Specifying a window without a context will generate a GLFW_NO_WINDOW_CONTEXT error.
This function does not apply to Vulkan. If you are rendering with Vulkan, see vkQueuePresentKHR instead.
@errors Possible errors include GLFW_NOT_INITIALIZED, GLFW_NO_WINDOW_CONTEXT and GLFW_PLATFORM_ERROR.
EGL: The context of the specified window must be current on the calling thread.
@thread_safety This function may be called from any thread.
Added in version 1.0. @glfw3 Added window handle parameter.
Parameters:
window |
The window whose buffers to swap. |
See also:
buffer_swap