anulax
/
glfw
1
0
Fork 0
Code Issues Pull Requests Packages project_board Releases Wiki Activity

Add error sections to reference docs

Browse Source 
[ci skip]
master
Camilla Berglund ago%!(EXTRA string=10 years)
parent 58a83ca8ad
commit f51cf81148
2 changed files with 218 additions and 6 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      docs/Doxyfile.in
  2. 223
      include/GLFW/glfw3.h

1
docs/Doxyfile.in
Unescape View File

@ -199,6 +199,7 @@ ALIASES = "thread_safety=@par Thread safety\n" \
"pointer_lifetime=@par Pointer lifetime\n" \
"analysis=@par Analysis\n" \
"reentrancy=@par Reentrancy\n" \
"errors=@par Errors\n" \
"glfw3=@par\n__GLFW 3:__" \
"x11=__X11:__" \
"win32=__Windows:__" \

223
include/GLFW/glfw3.h
Unescape View File

@ -1178,6 +1178,8 @@ typedef struct GLFWimage
* @return `GLFW_TRUE` if successful, or `GLFW_FALSE` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_PLATFORM_ERROR.
*
* @remark @osx This function will change the current directory of the
* application to the `Contents/Resources` subdirectory of the application's
* bundle, if present. This can be disabled with a
@ -1206,6 +1208,8 @@ GLFWAPI int glfwInit(void);
* call this function, as it is called by @ref glfwInit before it returns
* failure.
*
* @errors Possible errors include @ref GLFW_PLATFORM_ERROR.
*
* @remark This function may be called before @ref glfwInit.
*
* @warning The contexts of any remaining windows must not be current on any
@ -1230,13 +1234,14 @@ GLFWAPI void glfwTerminate(void);
* library. It is intended for when you are using GLFW as a shared library and
* want to ensure that you are using the minimum required version.
*
* Any or all of the version arguments may be `NULL`. This function always
* succeeds.
* Any or all of the version arguments may be `NULL`.
*
* @param[out] major Where to store the major version number, or `NULL`.
* @param[out] minor Where to store the minor version number, or `NULL`.
* @param[out] rev Where to store the revision number, or `NULL`.
*
* @errors None.
*
* @remark This function may be called before @ref glfwInit.
*
* @thread_safety This function may be called from any thread.
@ -1261,10 +1266,10 @@ GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev);
* @ref glfwGetVersion function already provides the version of the running
* library binary.
*
* This function always succeeds.
*
* @return The GLFW version string.
*
* @errors None.
*
* @remark This function may be called before @ref glfwInit.
*
* @pointer_lifetime The returned string is static and compile-time generated.
@ -1300,6 +1305,8 @@ GLFWAPI const char* glfwGetVersionString(void);
* callback.
* @return The previously set callback, or `NULL` if no callback was set.
*
* @errors None.
*
* @remark This function may be called before @ref glfwInit.
*
* @thread_safety This function must only be called from the main thread.
@ -1323,6 +1330,8 @@ GLFWAPI GLFWerrorfun glfwSetErrorCallback(GLFWerrorfun cbfun);
* @return An array of monitor handles, or `NULL` if no monitors were found or
* if an [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @pointer_lifetime The returned array is allocated and freed by GLFW. You
* should not free it yourself. It is guaranteed to be valid only until the
* monitor configuration changes or the library is terminated.
@ -1347,6 +1356,8 @@ GLFWAPI GLFWmonitor** glfwGetMonitors(int* count);
* @return The primary monitor, or `NULL` if no monitors were found or if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @remark The primary monitor is always first in the array returned by @ref
@ -1373,6 +1384,9 @@ GLFWAPI GLFWmonitor* glfwGetPrimaryMonitor(void);
* @param[out] xpos Where to store the monitor x-coordinate, or `NULL`.
* @param[out] ypos Where to store the monitor y-coordinate, or `NULL`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref monitor_properties
@ -1402,6 +1416,8 @@ GLFWAPI void glfwGetMonitorPos(GLFWmonitor* monitor, int* xpos, int* ypos);
* @param[out] heightMM Where to store the height, in millimetres, of the
* monitor's display area, or `NULL`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @remark @win32 calculates the returned physical size from the
* current resolution and system DPI instead of querying the monitor EDID data.
*
@ -1425,6 +1441,8 @@ GLFWAPI void glfwGetMonitorPhysicalSize(GLFWmonitor* monitor, int* widthMM, int*
* @return The UTF-8 encoded name of the monitor, or `NULL` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @pointer_lifetime The returned string is allocated and freed by GLFW. You
* should not free it yourself. It is valid until the specified monitor is
* disconnected or the library is terminated.
@ -1450,6 +1468,8 @@ GLFWAPI const char* glfwGetMonitorName(GLFWmonitor* monitor);
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref monitor_event
@ -1473,6 +1493,9 @@ GLFWAPI GLFWmonitorfun glfwSetMonitorCallback(GLFWmonitorfun cbfun);
* @return An array of video modes, or `NULL` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* 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 monitor is
* disconnected, this function is called again for that monitor or the library
@ -1500,6 +1523,9 @@ GLFWAPI const GLFWvidmode* glfwGetVideoModes(GLFWmonitor* monitor, int* count);
* @return The current mode of the monitor, or `NULL` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* 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 monitor is
* disconnected or the library is terminated.
@ -1524,6 +1550,9 @@ GLFWAPI const GLFWvidmode* glfwGetVideoMode(GLFWmonitor* monitor);
* @param[in] monitor The monitor whose gamma ramp to set.
* @param[in] gamma The desired exponent.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref monitor_gamma
@ -1542,6 +1571,9 @@ GLFWAPI void glfwSetGamma(GLFWmonitor* monitor, float gamma);
* @return The current gamma ramp, or `NULL` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @pointer_lifetime The returned structure and its arrays are allocated and
* freed by GLFW. You should not free them yourself. They are valid until the
* specified monitor is disconnected, this function is called again for that
@ -1566,6 +1598,9 @@ GLFWAPI const GLFWgammaramp* glfwGetGammaRamp(GLFWmonitor* monitor);
* @param[in] monitor The monitor whose gamma ramp to set.
* @param[in] ramp The gamma ramp to use.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @remark Gamma ramp sizes other than 256 are not supported by all platforms
* or graphics hardware.
*
@ -1589,6 +1624,8 @@ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp);
* This function resets all window hints to their
* [default values](@ref window_hints_values).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_hints
@ -1610,6 +1647,9 @@ GLFWAPI void glfwDefaultWindowHints(void);
* @param[in] hint The [window hint](@ref window_hints) to set.
* @param[in] value The new value of the window hint.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_INVALID_ENUM.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_hints
@ -1680,6 +1720,11 @@ GLFWAPI void glfwWindowHint(int hint, int value);
* @return The handle of the created window, or `NULL` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_API_UNAVAILABLE, @ref
* GLFW_VERSION_UNAVAILABLE, @ref GLFW_FORMAT_UNAVAILABLE and @ref
* GLFW_PLATFORM_ERROR.
*
* @remark @win32 Window creation will fail if the Microsoft GDI software
* OpenGL implementation is the only one available.
*
@ -1744,6 +1789,9 @@ GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, G
*
* @param[in] window The window to destroy.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @note The context of the specified window must not be current on any other
* thread when this function is called.
*
@ -1767,6 +1815,8 @@ GLFWAPI void glfwDestroyWindow(GLFWwindow* window);
* @param[in] window The window to query.
* @return The value of the close flag.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function may be called from any thread. Access is not
* synchronized.
*
@ -1787,6 +1837,8 @@ GLFWAPI int glfwWindowShouldClose(GLFWwindow* window);
* @param[in] window The window whose flag to change.
* @param[in] value The new value.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function may be called from any thread. Access is not
* synchronized.
*
@ -1806,6 +1858,9 @@ GLFWAPI void glfwSetWindowShouldClose(GLFWwindow* window, int value);
* @param[in] window The window whose title to change.
* @param[in] title The UTF-8 encoded window title.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @remark @osx The window title will not be updated until the next time you
* process events.
*
@ -1834,6 +1889,9 @@ GLFWAPI void glfwSetWindowTitle(GLFWwindow* window, const char* title);
* @param[out] ypos Where to store the y-coordinate of the upper-left corner of
* the client area, or `NULL`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_pos
@ -1861,6 +1919,9 @@ GLFWAPI void glfwGetWindowPos(GLFWwindow* window, int* xpos, int* ypos);
* @param[in] xpos The x-coordinate of the upper-left corner of the client area.
* @param[in] ypos The y-coordinate of the upper-left corner of the client area.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_pos
@ -1888,6 +1949,9 @@ GLFWAPI void glfwSetWindowPos(GLFWwindow* window, int xpos, int ypos);
* @param[out] height Where to store the height, in screen coordinates, of the
* client area, or `NULL`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_size
@ -1919,6 +1983,9 @@ GLFWAPI void glfwGetWindowSize(GLFWwindow* window, int* width, int* height);
* @param[in] maxheight The maximum height, in screen coordinates, of the
* client area, or `GLFW_DONT_CARE`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @remark If you set size limits and an aspect ratio that conflict, the
* results are undefined.
*
@ -1955,6 +2022,9 @@ GLFWAPI void glfwSetWindowSizeLimits(GLFWwindow* window, int minwidth, int minhe
* @param[in] denom The denominator of the desired aspect ratio, or
* `GLFW_DONT_CARE`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
*
* @remark If you set size limits and an aspect ratio that conflict, the
* results are undefined.
*
@ -1986,6 +2056,9 @@ GLFWAPI void glfwSetWindowAspectRatio(GLFWwindow* window, int numer, int denom);
* @param[in] width The desired width of the specified window.
* @param[in] height The desired height of the specified window.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_size
@ -2013,6 +2086,9 @@ GLFWAPI void glfwSetWindowSize(GLFWwindow* window, int width, int height);
* @param[out] height Where to store the height, in pixels, of the framebuffer,
* or `NULL`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_fbsize
@ -2048,6 +2124,9 @@ GLFWAPI void glfwGetFramebufferSize(GLFWwindow* window, int* width, int* height)
* @param[out] bottom Where to store the size, in screen coordinates, of the
* bottom edge of the window frame, or `NULL`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_size
@ -2069,6 +2148,9 @@ GLFWAPI void glfwGetWindowFrameSize(GLFWwindow* window, int* left, int* top, int
*
* @param[in] window The window to iconify.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_iconify
@ -2091,6 +2173,9 @@ GLFWAPI void glfwIconifyWindow(GLFWwindow* window);
*
* @param[in] window The window to restore.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_iconify
@ -2111,6 +2196,9 @@ GLFWAPI void glfwRestoreWindow(GLFWwindow* window);
*
* @param[in] window The window to make visible.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_hide
@ -2130,6 +2218,9 @@ GLFWAPI void glfwShowWindow(GLFWwindow* window);
*
* @param[in] window The window to hide.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_hide
@ -2150,6 +2241,8 @@ GLFWAPI void glfwHideWindow(GLFWwindow* window);
* @return The monitor, or `NULL` if the window is in windowed mode or an error
* occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_monitor
@ -2171,6 +2264,9 @@ GLFWAPI GLFWmonitor* glfwGetWindowMonitor(GLFWwindow* window);
* @return The value of the attribute, or zero if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
*
* @remark Framebuffer related hints are not window attributes. See @ref
* window_attribs_fb for more information.
*
@ -2199,6 +2295,8 @@ GLFWAPI int glfwGetWindowAttrib(GLFWwindow* window, int attrib);
* @param[in] window The window whose pointer to set.
* @param[in] pointer The new value.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function may be called from any thread. Access is not
* synchronized.
*
@ -2218,6 +2316,8 @@ GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* window, void* pointer);
*
* @param[in] window The window whose pointer to return.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function may be called from any thread. Access is not
* synchronized.
*
@ -2242,6 +2342,8 @@ GLFWAPI void* glfwGetWindowUserPointer(GLFWwindow* window);
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_pos
@ -2264,6 +2366,8 @@ GLFWAPI GLFWwindowposfun glfwSetWindowPosCallback(GLFWwindow* window, GLFWwindow
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_size
@ -2292,6 +2396,8 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @remark @osx Selecting Quit from the application menu will trigger the close
* callback for all windows.
*
@ -2322,6 +2428,8 @@ GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwi
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_refresh
@ -2349,6 +2457,8 @@ GLFWAPI GLFWwindowrefreshfun glfwSetWindowRefreshCallback(GLFWwindow* window, GL
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_focus
@ -2370,6 +2480,8 @@ GLFWAPI GLFWwindowfocusfun glfwSetWindowFocusCallback(GLFWwindow* window, GLFWwi
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_iconify
@ -2391,6 +2503,8 @@ GLFWAPI GLFWwindowiconifyfun glfwSetWindowIconifyCallback(GLFWwindow* window, GL
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref window_fbsize
@ -2419,6 +2533,9 @@ GLFWAPI GLFWframebuffersizefun glfwSetFramebufferSizeCallback(GLFWwindow* window
*
* Event processing is not required for joystick input to work.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* 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.
@ -2460,6 +2577,9 @@ GLFWAPI void glfwPollEvents(void);
*
* Event processing is not required for joystick input to work.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* 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.
@ -2482,6 +2602,9 @@ GLFWAPI void glfwWaitEvents(void);
* of threads in applications that do not create windows, use your threading
* library of choice.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function may be called from any thread.
*
* @sa @ref events
@ -2503,6 +2626,9 @@ GLFWAPI void glfwPostEmptyEvent(void);
* @param[in] mode One of `GLFW_CURSOR`, `GLFW_STICKY_KEYS` or
* `GLFW_STICKY_MOUSE_BUTTONS`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_INVALID_ENUM.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa glfwSetInputMode
@ -2548,6 +2674,9 @@ GLFWAPI int glfwGetInputMode(GLFWwindow* window, int mode);
* `GLFW_STICKY_MOUSE_BUTTONS`.
* @param[in] value The new value of the specified input mode.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa glfwGetInputMode
@ -2569,6 +2698,9 @@ GLFWAPI void glfwSetInputMode(GLFWwindow* window, int mode, int value);
* @param[in] scancode The scancode of the key to query.
* @return The localized name of the key.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* 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 @ref
* glfwGetKeyName, or until the library is terminated.
@ -2609,6 +2741,9 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode);
* not a valid key for this function.
* @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_INVALID_ENUM.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref input_key
@ -2635,6 +2770,9 @@ GLFWAPI int glfwGetKey(GLFWwindow* window, int key);
* @param[in] button The desired [mouse button](@ref buttons).
* @return One of `GLFW_PRESS` or `GLFW_RELEASE`.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_INVALID_ENUM.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref input_mouse_button
@ -2670,6 +2808,9 @@ GLFWAPI int glfwGetMouseButton(GLFWwindow* window, int button);
* @param[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 @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref cursor_pos
@ -2704,6 +2845,9 @@ GLFWAPI void glfwGetCursorPos(GLFWwindow* window, double* xpos, double* ypos);
* @param[in] ypos The desired y-coordinate, relative to the top edge of the
* client area.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @remark @x11 Due to the asynchronous nature of X11, it may take a moment for
* the window focus event to arrive. This means you may not be able to set the
* cursor position directly after window creation.
@ -2736,10 +2880,12 @@ GLFWAPI void glfwSetCursorPos(GLFWwindow* window, double xpos, double ypos);
* @param[in] image The desired cursor image.
* @param[in] xhot The desired x-coordinate, in pixels, of the cursor hotspot.
* @param[in] yhot The desired y-coordinate, in pixels, of the cursor hotspot.
*
* @return The handle of the created cursor, or `NULL` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @pointer_lifetime The specified image data is copied before this function
* returns.
*
@ -2763,10 +2909,12 @@ GLFWAPI GLFWcursor* glfwCreateCursor(const GLFWimage* image, int xhot, int yhot)
* a window with @ref glfwSetCursor.
*
* @param[in] shape One of the [standard shapes](@ref shapes).
*
* @return A new cursor ready to use or `NULL` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM and @ref 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.
@ -2788,6 +2936,9 @@ GLFWAPI GLFWcursor* glfwCreateStandardCursor(int shape);
*
* @param[in] cursor The cursor object to destroy.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* 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.
@ -2815,6 +2966,9 @@ GLFWAPI void glfwDestroyCursor(GLFWcursor* cursor);
* @param[in] cursor The cursor to set, or `NULL` to switch back to the default
* arrow cursor.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref cursor_object
@ -2855,6 +3009,8 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref input_key
@ -2891,6 +3047,8 @@ GLFWAPI GLFWkeyfun glfwSetKeyCallback(GLFWwindow* window, GLFWkeyfun cbfun);
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref input_char
@ -2923,6 +3081,8 @@ GLFWAPI GLFWcharfun glfwSetCharCallback(GLFWwindow* window, GLFWcharfun cbfun);
* @return The previously set callback, or `NULL` if no callback was set or an
* error occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref input_char
@ -2950,6 +3110,8 @@ GLFWAPI GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow* window, GLFWcharmods
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref input_mouse_button
@ -2974,6 +3136,8 @@ GLFWAPI GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow* window, GLFWmo
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref cursor_pos
@ -2996,6 +3160,8 @@ GLFWAPI GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow* window, GLFWcursor
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref cursor_enter
@ -3021,6 +3187,8 @@ GLFWAPI GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow* window, GLFWcu
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref scrolling
@ -3047,6 +3215,8 @@ GLFWAPI GLFWscrollfun glfwSetScrollCallback(GLFWwindow* window, GLFWscrollfun cb
* @return The previously set callback, or `NULL` if no callback was set or the
* library had not been [initialized](@ref intro_init).
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref path_drop
@ -3064,6 +3234,9 @@ GLFWAPI GLFWdropfun glfwSetDropCallback(GLFWwindow* window, GLFWdropfun cbfun);
* @param[in] joy The [joystick](@ref joysticks) to query.
* @return `GLFW_TRUE` if the joystick is present, or `GLFW_FALSE` otherwise.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
*
* @thread_safety This function must only be called from the main thread.
*
* @sa @ref joystick
@ -3084,6 +3257,9 @@ GLFWAPI int glfwJoystickPresent(int joy);
* array. This is set to zero if an error occurred.
* @return An array of axis values, or `NULL` if the joystick is not present.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM and @ref 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
@ -3109,6 +3285,9 @@ GLFWAPI const float* glfwGetJoystickAxes(int joy, int* count);
* array. This is set to zero if an error occurred.
* @return An array of button states, or `NULL` if the joystick is not present.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM and @ref 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
@ -3135,6 +3314,9 @@ GLFWAPI const unsigned char* glfwGetJoystickButtons(int joy, int* count);
* @return The UTF-8 encoded name of the joystick, or `NULL` if the joystick
* is not present.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM and @ref 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
@ -3158,6 +3340,9 @@ GLFWAPI const char* glfwGetJoystickName(int joy);
* @param[in] window The window that will own the clipboard contents.
* @param[in] string A UTF-8 encoded string.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_PLATFORM_ERROR.
*
* @pointer_lifetime The specified string is copied before this function
* returns.
*
@ -3183,6 +3368,9 @@ GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string);
* @return The contents of the clipboard as a UTF-8 encoded string, or `NULL`
* if an [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* 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 @ref
* glfwGetClipboardString or @ref glfwSetClipboardString, or until the library
@ -3212,6 +3400,8 @@ GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window);
* @return The current value, in seconds, or zero if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function may be called from any thread. Access is not
* synchronized.
*
@ -3231,6 +3421,9 @@ GLFWAPI double glfwGetTime(void);
*
* @param[in] time The new value, in seconds.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_INVALID_VALUE.
*
* @remark The upper limit of the timer is calculated as
* floor((2<sup>64</sup> - 1) / 10<sup>9</sup>) and is due to implementations
* storing nanoseconds in 64 bits. The limit may be increased in the future.
@ -3265,6 +3458,9 @@ GLFWAPI void glfwSetTime(double time);
* @param[in] window The window whose context to make current, or `NULL` to
* detach the current context.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
*
* @thread_safety This function may be called from any thread.
*
* @sa @ref context_current
@ -3284,6 +3480,8 @@ GLFWAPI void glfwMakeContextCurrent(GLFWwindow* window);
* @return The window whose context is current, or `NULL` if no window's
* context is current.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
*
* @thread_safety This function may be called from any thread.
*
* @sa @ref context_current
@ -3307,6 +3505,9 @@ GLFWAPI GLFWwindow* glfwGetCurrentContext(void);
*
* @param[in] window The window whose buffers to swap.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
*
* @remark __EGL:__ The context of the specified window must be current on the
* calling thread.
*
@ -3343,6 +3544,9 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* window);
* @param[in] interval The minimum number of screen updates to wait for
* until the buffers are swapped by @ref glfwSwapBuffers.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR.
*
* @remark This function is not called during context creation, leaving the
* swap interval set to whatever is the default on that platform. This is done
* because some swap interval extensions used by GLFW do not allow the swap
@ -3382,6 +3586,10 @@ GLFWAPI void glfwSwapInterval(int interval);
* @return `GLFW_TRUE` if the extension is available, or `GLFW_FALSE`
* otherwise.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_NO_CURRENT_CONTEXT, @ref GLFW_INVALID_VALUE and @ref
* GLFW_PLATFORM_ERROR.
*
* @thread_safety This function may be called from any thread.
*
* @sa @ref context_glext
@ -3407,6 +3615,9 @@ GLFWAPI int glfwExtensionSupported(const char* extension);
* @return The address of the function, or `NULL` if an
* [error](@ref error_handling) occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_NO_CURRENT_CONTEXT and @ref GLFW_PLATFORM_ERROR.
*
* @remark The address of a given function is not guaranteed to be the same
* between contexts.
*

Write Preview
Loading…
Cancel
Save