mirror of
https://github.com/glfw/glfw.git
synced 2024-11-10 00:51:47 +00:00
Add error sections to reference docs
[ci skip]
This commit is contained in:
Camilla Berglund
parent
58a83ca8ad
commit
f51cf81148
@ -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:__" \
|
||||
|
||||
@ -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.
|
||||
*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user