try
This commit is contained in:
Richard Smith
parent
62ff73d0e7
commit
be6cf57d85
65 changed files with 8668 additions and 4495 deletions
|
|
@ -169,9 +169,11 @@
|
|||
*
|
||||
* @ingroup input
|
||||
* @{ */
|
||||
/*! @ingroup input
|
||||
*/
|
||||
/*! @} */
|
||||
/*! @defgroup keys Keyboard keys
|
||||
* @brief Keyboard key IDs.
|
||||
/*! @defgroup keys Keyboard key tokens
|
||||
* @brief Keyboard key tokens.
|
||||
*
|
||||
* See [key input](@ref input_key) for how these are used.
|
||||
*
|
||||
|
|
@ -193,7 +195,6 @@
|
|||
* @ingroup input
|
||||
* @{
|
||||
*/
|
||||
/* The unknown key */
|
||||
/* Printable keys */
|
||||
/* Function keys */
|
||||
/*! @} */
|
||||
|
|
@ -420,11 +421,11 @@
|
|||
*/
|
||||
/*! @brief Platform unavailable or no matching platform was found.
|
||||
*
|
||||
* If emitted during initialization, no matching platform was found. If @ref
|
||||
* GLFW_PLATFORM is set to `GLFW_ANY_PLATFORM`, GLFW could not detect any of the
|
||||
* platforms supported by this library binary, except for the Null platform. If set to
|
||||
* a specific platform, it is either not supported by this library binary or GLFW was not
|
||||
* able to detect it.
|
||||
* If emitted during initialization, no matching platform was found. If the @ref
|
||||
* GLFW_PLATFORM init hint was set to `GLFW_ANY_PLATFORM`, GLFW could not detect any of
|
||||
* the platforms supported by this library binary, except for the Null platform. If the
|
||||
* init hint was set to a specific platform, it is either not supported by this library
|
||||
* binary or GLFW was not able to detect it.
|
||||
*
|
||||
* If emitted by a native access function, GLFW was initialized for a different platform
|
||||
* than the function is for.
|
||||
|
|
@ -640,8 +641,14 @@
|
|||
/*! @brief Window content area scaling window
|
||||
* [window hint](@ref GLFW_SCALE_TO_MONITOR).
|
||||
*/
|
||||
/*! @brief macOS specific
|
||||
* [window hint](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint).
|
||||
/*! @brief Window framebuffer scaling
|
||||
* [window hint](@ref GLFW_SCALE_FRAMEBUFFER_hint).
|
||||
*/
|
||||
/*! @brief Legacy name for compatibility.
|
||||
*
|
||||
* This is an alias for the
|
||||
* [GLFW_SCALE_FRAMEBUFFER](@ref GLFW_SCALE_FRAMEBUFFER_hint) window hint for
|
||||
* compatibility with earlier versions.
|
||||
*/
|
||||
/*! @brief macOS specific
|
||||
* [window hint](@ref GLFW_COCOA_FRAME_NAME_hint).
|
||||
|
|
@ -655,6 +662,8 @@
|
|||
/*! @brief X11 specific
|
||||
* [window hint](@ref GLFW_X11_CLASS_NAME_hint).
|
||||
*/
|
||||
/*! @brief Win32 specific [window hint](@ref GLFW_WIN32_SHOWDEFAULT_hint).
|
||||
*/
|
||||
/*! @brief Wayland specific
|
||||
* [window hint](@ref GLFW_WAYLAND_APP_ID_hint).
|
||||
*
|
||||
|
|
@ -703,11 +712,11 @@
|
|||
* @note @macos This shape is provided by a private system API and may fail
|
||||
* with @ref GLFW_CURSOR_UNAVAILABLE in the future.
|
||||
*
|
||||
* @note @x11 This shape is provided by a newer standard not supported by all
|
||||
* cursor themes.
|
||||
*
|
||||
* @note @wayland This shape is provided by a newer standard not supported by
|
||||
* all cursor themes.
|
||||
*
|
||||
* @note @x11 This shape is provided by a newer standard not supported by all
|
||||
* cursor themes.
|
||||
*/
|
||||
/*! @brief The top-right to bottom-left diagonal resize/move arrow shape.
|
||||
*
|
||||
|
|
@ -717,11 +726,11 @@
|
|||
* @note @macos This shape is provided by a private system API and may fail
|
||||
* with @ref GLFW_CURSOR_UNAVAILABLE in the future.
|
||||
*
|
||||
* @note @x11 This shape is provided by a newer standard not supported by all
|
||||
* cursor themes.
|
||||
*
|
||||
* @note @wayland This shape is provided by a newer standard not supported by
|
||||
* all cursor themes.
|
||||
*
|
||||
* @note @x11 This shape is provided by a newer standard not supported by all
|
||||
* cursor themes.
|
||||
*/
|
||||
/*! @brief The omni-directional resize/move cursor shape.
|
||||
*
|
||||
|
|
@ -733,11 +742,11 @@
|
|||
* The operation-not-allowed shape. This is usually a circle with a diagonal
|
||||
* line through it.
|
||||
*
|
||||
* @note @x11 This shape is provided by a newer standard not supported by all
|
||||
* cursor themes.
|
||||
*
|
||||
* @note @wayland This shape is provided by a newer standard not supported by
|
||||
* all cursor themes.
|
||||
*
|
||||
* @note @x11 This shape is provided by a newer standard not supported by all
|
||||
* cursor themes.
|
||||
*/
|
||||
/*! @brief Legacy name for compatibility.
|
||||
*
|
||||
|
|
@ -778,6 +787,10 @@
|
|||
*
|
||||
* X11 specific [init hint](@ref GLFW_X11_XCB_VULKAN_SURFACE_hint).
|
||||
*/
|
||||
/*! @brief Wayland specific init hint.
|
||||
*
|
||||
* Wayland specific [init hint](@ref GLFW_WAYLAND_LIBDECOR_hint).
|
||||
*/
|
||||
/*! @} */
|
||||
/*! @addtogroup init
|
||||
* @{ */
|
||||
|
|
@ -860,16 +873,25 @@ typedef struct GLFWcursor GLFWcursor;
|
|||
* or `NULL` if allocation failed. Note that not all parts of GLFW handle allocation
|
||||
* failures gracefully yet.
|
||||
*
|
||||
* This function may be called during @ref glfwInit but before the library is
|
||||
* flagged as initialized, as well as during @ref glfwTerminate after the
|
||||
* library is no longer flagged as initialized.
|
||||
* This function must support being called during @ref glfwInit but before the library is
|
||||
* flagged as initialized, as well as during @ref glfwTerminate after the library is no
|
||||
* longer flagged as initialized.
|
||||
*
|
||||
* Any memory allocated by this function will be deallocated during library
|
||||
* termination or earlier.
|
||||
* Any memory allocated via this function will be deallocated via the same allocator
|
||||
* during library termination or earlier.
|
||||
*
|
||||
* Any memory allocated via this function must be suitably aligned for any object type.
|
||||
* If you are using C99 or earlier, this alignment is platform-dependent but will be the
|
||||
* same as what `malloc` provides. If you are using C11 or later, this is the value of
|
||||
* `alignof(max_align_t)`.
|
||||
*
|
||||
* The size will always be greater than zero. Allocations of size zero are filtered out
|
||||
* before reaching the custom allocator.
|
||||
*
|
||||
* If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY.
|
||||
*
|
||||
* This function must not call any GLFW function.
|
||||
*
|
||||
* @param[in] size The minimum size, in bytes, of the memory block.
|
||||
* @param[in] user The user-defined pointer from the allocator.
|
||||
* @return The address of the newly allocated memory block, or `NULL` if an
|
||||
|
|
@ -880,7 +902,8 @@ typedef struct GLFWcursor GLFWcursor;
|
|||
*
|
||||
* @reentrancy This function should not call any GLFW function.
|
||||
*
|
||||
* @thread_safety This function may be called from any thread that calls GLFW functions.
|
||||
* @thread_safety This function must support being called from any thread that calls GLFW
|
||||
* functions.
|
||||
*
|
||||
* @sa @ref init_allocator
|
||||
* @sa @ref GLFWallocator
|
||||
|
|
@ -902,16 +925,26 @@ typedef void* (* GLFWallocatefun)(size_t size, void* user);
|
|||
* `NULL` if allocation failed. Note that not all parts of GLFW handle allocation
|
||||
* failures gracefully yet.
|
||||
*
|
||||
* This function may be called during @ref glfwInit but before the library is
|
||||
* flagged as initialized, as well as during @ref glfwTerminate after the
|
||||
* library is no longer flagged as initialized.
|
||||
* This function must support being called during @ref glfwInit but before the library is
|
||||
* flagged as initialized, as well as during @ref glfwTerminate after the library is no
|
||||
* longer flagged as initialized.
|
||||
*
|
||||
* Any memory allocated by this function will be deallocated during library
|
||||
* termination or earlier.
|
||||
* Any memory allocated via this function will be deallocated via the same allocator
|
||||
* during library termination or earlier.
|
||||
*
|
||||
* Any memory allocated via this function must be suitably aligned for any object type.
|
||||
* If you are using C99 or earlier, this alignment is platform-dependent but will be the
|
||||
* same as what `realloc` provides. If you are using C11 or later, this is the value of
|
||||
* `alignof(max_align_t)`.
|
||||
*
|
||||
* The block address will never be `NULL` and the size will always be greater than zero.
|
||||
* Reallocations of a block to size zero are converted into deallocations. Reallocations
|
||||
* of `NULL` to a non-zero size are converted into regular allocations.
|
||||
* Reallocations of a block to size zero are converted into deallocations before reaching
|
||||
* the custom allocator. Reallocations of `NULL` to a non-zero size are converted into
|
||||
* regular allocations before reaching the custom allocator.
|
||||
*
|
||||
* If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY.
|
||||
*
|
||||
* This function must not call any GLFW function.
|
||||
*
|
||||
* @param[in] block The address of the memory block to reallocate.
|
||||
* @param[in] size The new minimum size, in bytes, of the memory block.
|
||||
|
|
@ -924,7 +957,8 @@ typedef void* (* GLFWallocatefun)(size_t size, void* user);
|
|||
*
|
||||
* @reentrancy This function should not call any GLFW function.
|
||||
*
|
||||
* @thread_safety This function may be called from any thread that calls GLFW functions.
|
||||
* @thread_safety This function must support being called from any thread that calls GLFW
|
||||
* functions.
|
||||
*
|
||||
* @sa @ref init_allocator
|
||||
* @sa @ref GLFWallocator
|
||||
|
|
@ -945,13 +979,17 @@ typedef void* (* GLFWreallocatefun)(void* block, size_t size, void* user);
|
|||
* This function may deallocate the specified memory block. This memory block
|
||||
* will have been allocated with the same allocator.
|
||||
*
|
||||
* This function may be called during @ref glfwInit but before the library is
|
||||
* flagged as initialized, as well as during @ref glfwTerminate after the
|
||||
* library is no longer flagged as initialized.
|
||||
* This function must support being called during @ref glfwInit but before the library is
|
||||
* flagged as initialized, as well as during @ref glfwTerminate after the library is no
|
||||
* longer flagged as initialized.
|
||||
*
|
||||
* The block address will never be `NULL`. Deallocations of `NULL` are filtered out
|
||||
* before reaching the custom allocator.
|
||||
*
|
||||
* If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY.
|
||||
*
|
||||
* This function must not call any GLFW function.
|
||||
*
|
||||
* @param[in] block The address of the memory block to deallocate.
|
||||
* @param[in] user The user-defined pointer from the allocator.
|
||||
*
|
||||
|
|
@ -960,7 +998,8 @@ typedef void* (* GLFWreallocatefun)(void* block, size_t size, void* user);
|
|||
*
|
||||
* @reentrancy This function should not call any GLFW function.
|
||||
*
|
||||
* @thread_safety This function may be called from any thread that calls GLFW functions.
|
||||
* @thread_safety This function must support being called from any thread that calls GLFW
|
||||
* functions.
|
||||
*
|
||||
* @sa @ref init_allocator
|
||||
* @sa @ref GLFWallocator
|
||||
|
|
@ -1503,7 +1542,10 @@ typedef struct GLFWgamepadstate
|
|||
*/
|
||||
float axes[6];
|
||||
} GLFWgamepadstate;
|
||||
/*! @brief
|
||||
/*! @brief Custom heap memory allocator.
|
||||
*
|
||||
* This describes a custom heap memory allocator for GLFW. To set an allocator, pass it
|
||||
* to @ref glfwInitAllocator before initializing the library.
|
||||
*
|
||||
* @sa @ref init_allocator
|
||||
* @sa @ref glfwInitAllocator
|
||||
|
|
@ -1514,9 +1556,21 @@ typedef struct GLFWgamepadstate
|
|||
*/
|
||||
typedef struct GLFWallocator
|
||||
{
|
||||
/*! The memory allocation function. See @ref GLFWallocatefun for details about
|
||||
* allocation function.
|
||||
*/
|
||||
GLFWallocatefun allocate;
|
||||
/*! The memory reallocation function. See @ref GLFWreallocatefun for details about
|
||||
* reallocation function.
|
||||
*/
|
||||
GLFWreallocatefun reallocate;
|
||||
/*! The memory deallocation function. See @ref GLFWdeallocatefun for details about
|
||||
* deallocation function.
|
||||
*/
|
||||
GLFWdeallocatefun deallocate;
|
||||
/*! The user pointer for this custom allocator. This value will be passed to the
|
||||
* allocator functions.
|
||||
*/
|
||||
void* user;
|
||||
} GLFWallocator;
|
||||
/*************************************************************************
|
||||
|
|
@ -1558,6 +1612,13 @@ typedef struct GLFWallocator
|
|||
* and dock icon can be disabled entirely with the @ref GLFW_COCOA_MENUBAR init
|
||||
* hint.
|
||||
*
|
||||
* @remark __Wayland, X11:__ If the library was compiled with support for both
|
||||
* Wayland and X11, and the @ref GLFW_PLATFORM init hint is set to
|
||||
* `GLFW_ANY_PLATFORM`, the `XDG_SESSION_TYPE` environment variable affects
|
||||
* which platform is picked. If the environment variable is not set, or is set
|
||||
* to something other than `wayland` or `x11`, the regular detection mechanism
|
||||
* will be used instead.
|
||||
*
|
||||
* @remark @x11 This function will set the `LC_CTYPE` category of the
|
||||
* application locale according to the current environment if that category is
|
||||
* still "C". This is because the "C" locale breaks Unicode text input.
|
||||
|
|
@ -1643,8 +1704,12 @@ typedef struct GLFWallocator
|
|||
* To use the default allocator, call this function with a `NULL` argument.
|
||||
*
|
||||
* If you specify an allocator struct, every member must be a valid function
|
||||
* pointer. If any member is `NULL`, this function emits @ref
|
||||
* GLFW_INVALID_VALUE and the init allocator is unchanged.
|
||||
* pointer. If any member is `NULL`, this function will emit @ref
|
||||
* GLFW_INVALID_VALUE and the init allocator will be unchanged.
|
||||
*
|
||||
* The functions in the allocator must fulfil a number of requirements. See the
|
||||
* documentation for @ref GLFWallocatefun, @ref GLFWreallocatefun and @ref
|
||||
* GLFWdeallocatefun for details.
|
||||
*
|
||||
* @param[in] allocator The allocator to use at the next initialization, or
|
||||
* `NULL` to use the default one.
|
||||
|
|
@ -1952,9 +2017,10 @@ typedef struct GLFWallocator
|
|||
* specified monitor.
|
||||
*
|
||||
* Some platforms do not provide accurate monitor size information, either
|
||||
* because the monitor
|
||||
* [EDID](https://en.wikipedia.org/wiki/Extended_display_identification_data)
|
||||
* data is incorrect or because the driver does not report it accurately.
|
||||
* because the monitor [EDID][] data is incorrect or because the driver does
|
||||
* not report it accurately.
|
||||
*
|
||||
* [EDID]: https://en.wikipedia.org/wiki/Extended_display_identification_data
|
||||
*
|
||||
* Any or all of the size arguments may be `NULL`. If an error occurs, all
|
||||
* non-`NULL` size arguments will be set to zero.
|
||||
|
|
@ -2000,6 +2066,9 @@ typedef struct GLFWallocator
|
|||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
|
||||
* GLFW_PLATFORM_ERROR.
|
||||
*
|
||||
* @remark @wayland Fractional scaling information is not yet available for
|
||||
* monitors, so this function only returns integer content scales.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
* @sa @ref monitor_scale
|
||||
|
|
@ -2189,11 +2258,11 @@ typedef struct GLFWallocator
|
|||
* @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.
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref GLFW_INVALID_VALUE,
|
||||
* @ref GLFW_PLATFORM_ERROR and @ref GLFW_FEATURE_UNAVAILABLE (see remarks).
|
||||
*
|
||||
* @remark @wayland Gamma handling is a privileged protocol, this function
|
||||
* will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR.
|
||||
* will thus never be implemented and emits @ref GLFW_FEATURE_UNAVAILABLE.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
|
|
@ -2212,11 +2281,11 @@ typedef struct GLFWallocator
|
|||
* @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.
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref GLFW_PLATFORM_ERROR
|
||||
* and @ref GLFW_FEATURE_UNAVAILABLE (see remarks).
|
||||
*
|
||||
* @remark @wayland Gamma handling is a privileged protocol, this function
|
||||
* will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR while
|
||||
* will thus never be implemented and emits @ref GLFW_FEATURE_UNAVAILABLE while
|
||||
* returning `NULL`.
|
||||
*
|
||||
* @pointer_lifetime The returned structure and its arrays are allocated and
|
||||
|
|
@ -2250,8 +2319,8 @@ typedef struct GLFWallocator
|
|||
* @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.
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref GLFW_PLATFORM_ERROR
|
||||
* and @ref GLFW_FEATURE_UNAVAILABLE (see remarks).
|
||||
*
|
||||
* @remark The size of the specified gamma ramp should match the size of the
|
||||
* current ramp for that monitor.
|
||||
|
|
@ -2259,7 +2328,7 @@ typedef struct GLFWallocator
|
|||
* @remark @win32 The gamma ramp size must be 256.
|
||||
*
|
||||
* @remark @wayland Gamma handling is a privileged protocol, this function
|
||||
* will thus never be implemented and emits @ref GLFW_PLATFORM_ERROR.
|
||||
* will thus never be implemented and emits @ref GLFW_FEATURE_UNAVAILABLE.
|
||||
*
|
||||
* @pointer_lifetime The specified gamma ramp is copied before this function
|
||||
* returns.
|
||||
|
|
@ -2427,8 +2496,8 @@ typedef struct GLFWallocator
|
|||
*
|
||||
* @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.
|
||||
* GLFW_VERSION_UNAVAILABLE, @ref GLFW_FORMAT_UNAVAILABLE, @ref
|
||||
* GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
|
||||
*
|
||||
* @remark @win32 Window creation will fail if the Microsoft GDI software
|
||||
* OpenGL implementation is the only one available.
|
||||
|
|
@ -2450,23 +2519,35 @@ typedef struct GLFWallocator
|
|||
* @remark @macos 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](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
|
||||
* in the Mac Developer Library.
|
||||
* [Bundle Programming Guide][bundle-guide] in the Mac Developer Library.
|
||||
*
|
||||
* [bundle-guide]: https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/
|
||||
*
|
||||
* @remark @macos On OS X 10.10 and later the window frame will not be rendered
|
||||
* at full resolution on Retina displays unless the
|
||||
* [GLFW_COCOA_RETINA_FRAMEBUFFER](@ref GLFW_COCOA_RETINA_FRAMEBUFFER_hint)
|
||||
* [GLFW_SCALE_FRAMEBUFFER](@ref GLFW_SCALE_FRAMEBUFFER_hint)
|
||||
* hint is `GLFW_TRUE` and the `NSHighResolutionCapable` key is enabled in the
|
||||
* application bundle's `Info.plist`. For more information, see
|
||||
* [High Resolution Guidelines for OS X](https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html)
|
||||
* 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/Info.plist.in` in the source tree.
|
||||
* [High Resolution Guidelines for OS X][hidpi-guide] 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/Info.plist.in` in the source
|
||||
* tree.
|
||||
*
|
||||
* [hidpi-guide]: https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html
|
||||
*
|
||||
* @remark @macos When activating frame autosaving with
|
||||
* [GLFW_COCOA_FRAME_NAME](@ref GLFW_COCOA_FRAME_NAME_hint), the specified
|
||||
* window size and position may be overridden by previously saved values.
|
||||
*
|
||||
* @remark @wayland GLFW uses [libdecor][] where available to create its window
|
||||
* decorations. This in turn uses server-side XDG decorations where available
|
||||
* and provides high quality client-side decorations on compositors like GNOME.
|
||||
* If both XDG decorations and libdecor are unavailable, GLFW falls back to
|
||||
* a very simple set of window decorations that only support moving, resizing
|
||||
* and the window manager's right-click menu.
|
||||
*
|
||||
* [libdecor]: https://gitlab.freedesktop.org/libdecor/libdecor
|
||||
*
|
||||
* @remark @x11 Some window managers will not respect the placement of
|
||||
* initially hidden windows.
|
||||
*
|
||||
|
|
@ -2483,20 +2564,6 @@ typedef struct GLFWallocator
|
|||
* [GLFW_X11_INSTANCE_NAME](@ref GLFW_X11_INSTANCE_NAME_hint) window hints to
|
||||
* override this.
|
||||
*
|
||||
* @remark @wayland Compositors should implement the xdg-decoration protocol
|
||||
* for GLFW to decorate the window properly. If this protocol isn't
|
||||
* supported, or if the compositor prefers client-side decorations, a very
|
||||
* simple fallback frame will be drawn using the wp_viewporter protocol. A
|
||||
* compositor can still emit close, maximize or fullscreen events, using for
|
||||
* instance a keybind mechanism. If neither of these protocols is supported,
|
||||
* the window won't be decorated.
|
||||
*
|
||||
* @remark @wayland A full screen window will not attempt to change the mode,
|
||||
* no matter what the requested size or refresh rate.
|
||||
*
|
||||
* @remark @wayland Screensaver inhibition requires the idle-inhibit protocol
|
||||
* to be implemented in the user's compositor.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
* @sa @ref window_creation
|
||||
|
|
@ -2575,6 +2642,37 @@ typedef struct GLFWallocator
|
|||
* @ingroup window
|
||||
*/
|
||||
void glfwSetWindowShouldClose(GLFWwindow* window, int value);
|
||||
/*! @brief Returns the title of the specified window.
|
||||
*
|
||||
* This function returns the window title, encoded as UTF-8, of the specified
|
||||
* window. This is the title set previously by @ref glfwCreateWindow
|
||||
* or @ref glfwSetWindowTitle.
|
||||
*
|
||||
* @param[in] window The window to query.
|
||||
* @return The UTF-8 encoded window title, or `NULL` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
*
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
|
||||
*
|
||||
* @remark The returned title is currently a copy of the title last set by @ref
|
||||
* glfwCreateWindow or @ref glfwSetWindowTitle. It does not include any
|
||||
* additional text which may be appended by the platform or another program.
|
||||
*
|
||||
* @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
|
||||
* glfwGetWindowTitle or @ref glfwSetWindowTitle, or until the library is
|
||||
* terminated.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
* @sa @ref window_title
|
||||
* @sa @ref glfwSetWindowTitle
|
||||
*
|
||||
* @since Added in version 3.4.
|
||||
*
|
||||
* @ingroup window
|
||||
*/
|
||||
const char* glfwGetWindowTitle(GLFWwindow* window);
|
||||
/*! @brief Sets the title of the specified window.
|
||||
*
|
||||
* This function sets the window title, encoded as UTF-8, of the specified
|
||||
|
|
@ -2592,6 +2690,7 @@ typedef struct GLFWallocator
|
|||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
* @sa @ref window_title
|
||||
* @sa @ref glfwGetWindowTitle
|
||||
*
|
||||
* @since Added in version 1.0.
|
||||
* @glfw3 Added window handle parameter.
|
||||
|
|
@ -2630,8 +2729,9 @@ typedef struct GLFWallocator
|
|||
* @remark @macos Regular windows do not have icons on macOS. This function
|
||||
* will emit @ref GLFW_FEATURE_UNAVAILABLE. The dock icon will be the same as
|
||||
* the application bundle's icon. For more information on bundles, see the
|
||||
* [Bundle Programming Guide](https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/)
|
||||
* in the Mac Developer Library.
|
||||
* [Bundle Programming Guide][bundle-guide] in the Mac Developer Library.
|
||||
*
|
||||
* [bundle-guide]: https://developer.apple.com/library/mac/documentation/CoreFoundation/Conceptual/CFBundles/
|
||||
*
|
||||
* @remark @wayland There is no existing protocol to change an icon, the
|
||||
* window will thus inherit the one defined in the application's desktop file.
|
||||
|
|
@ -2849,9 +2949,6 @@ typedef struct GLFWallocator
|
|||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
|
||||
* GLFW_PLATFORM_ERROR.
|
||||
*
|
||||
* @remark @wayland A full screen window will not attempt to change the mode,
|
||||
* no matter what the requested size.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
* @sa @ref window_size
|
||||
|
|
@ -3172,11 +3269,11 @@ typedef struct GLFWallocator
|
|||
*
|
||||
* @param[in] window The window to give input focus.
|
||||
*
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||
* GLFW_PLATFORM_ERROR and @ref GLFW_FEATURE_UNAVAILABLE (see remarks).
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
|
||||
* GLFW_PLATFORM_ERROR.
|
||||
*
|
||||
* @remark @wayland It is not possible for an application to set the input
|
||||
* focus. This function will emit @ref GLFW_FEATURE_UNAVAILABLE.
|
||||
* @remark @wayland The compositor will likely ignore focus requests unless
|
||||
* another window created by the same application already has input focus.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
|
|
@ -3278,9 +3375,6 @@ typedef struct GLFWallocator
|
|||
* @remark @wayland The desired window position is ignored, as there is no way
|
||||
* for an application to set this property.
|
||||
*
|
||||
* @remark @wayland Setting the window to full screen will not attempt to
|
||||
* change the mode, no matter what the requested size or refresh rate.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
* @sa @ref window_monitor
|
||||
|
|
@ -3351,11 +3445,15 @@ typedef struct GLFWallocator
|
|||
* @param[in] value `GLFW_TRUE` or `GLFW_FALSE`.
|
||||
*
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||
* GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE and @ref GLFW_PLATFORM_ERROR.
|
||||
* GLFW_INVALID_ENUM, @ref GLFW_INVALID_VALUE, @ref GLFW_PLATFORM_ERROR and @ref
|
||||
* GLFW_FEATURE_UNAVAILABLE (see remarks).
|
||||
*
|
||||
* @remark Calling @ref glfwGetWindowAttrib will always return the latest
|
||||
* value, even if that value is ignored by the current mode of the window.
|
||||
*
|
||||
* @remark @wayland The [GLFW_FLOATING](@ref GLFW_FLOATING_attrib) window attribute is
|
||||
* not supported. Setting this will emit @ref GLFW_FEATURE_UNAVAILABLE.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
* @sa @ref window_attribs
|
||||
|
|
@ -4011,8 +4109,8 @@ typedef struct GLFWallocator
|
|||
* @param[in] scancode The scancode of the key to query.
|
||||
* @return The UTF-8 encoded, layout-specific name of the key, or `NULL`.
|
||||
*
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
|
||||
* GLFW_PLATFORM_ERROR.
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||
* GLFW_INVALID_VALUE, @ref GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
||||
*
|
||||
* @remark The contents of the returned string may change when a keyboard
|
||||
* layout change event is received.
|
||||
|
|
@ -4033,15 +4131,18 @@ typedef struct GLFWallocator
|
|||
*
|
||||
* This function returns the platform-specific scancode of the specified key.
|
||||
*
|
||||
* If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
|
||||
* method will return `-1`.
|
||||
* If the specified [key token](@ref keys) corresponds to a physical key not
|
||||
* supported on the current platform then this method will return `-1`.
|
||||
* Calling this function with anything other than a key token will return `-1`
|
||||
* and generate a @ref GLFW_INVALID_ENUM error.
|
||||
*
|
||||
* @param[in] key Any [named key](@ref keys).
|
||||
* @return The platform-specific scancode for the key, or `-1` if an
|
||||
* [error](@ref error_handling) occurred.
|
||||
* @param[in] key Any [key token](@ref keys).
|
||||
* @return The platform-specific scancode for the key, or `-1` if the key is
|
||||
* not supported on the current platform or an [error](@ref error_handling)
|
||||
* occurred.
|
||||
*
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
|
||||
* GLFW_INVALID_ENUM.
|
||||
*
|
||||
* @thread_safety This function may be called from any thread.
|
||||
*
|
||||
|
|
@ -4178,11 +4279,11 @@ typedef struct GLFWallocator
|
|||
* @param[in] ypos The desired y-coordinate, relative to the top edge of the
|
||||
* content area.
|
||||
*
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
|
||||
* GLFW_PLATFORM_ERROR.
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||
* GLFW_PLATFORM_ERROR and @ref GLFW_FEATURE_UNAVAILABLE (see remarks).
|
||||
*
|
||||
* @remark @wayland This function will only work when the cursor mode is
|
||||
* `GLFW_CURSOR_DISABLED`, otherwise it will do nothing.
|
||||
* `GLFW_CURSOR_DISABLED`, otherwise it will emit @ref GLFW_FEATURE_UNAVAILABLE.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
|
|
@ -4341,9 +4442,9 @@ typedef struct GLFWallocator
|
|||
* [character callback](@ref glfwSetCharCallback) instead.
|
||||
*
|
||||
* When a window loses input focus, it will generate synthetic key release
|
||||
* events for all pressed keys. You can tell these events from user-generated
|
||||
* events by the fact that the synthetic ones are generated after the focus
|
||||
* loss event has been processed, i.e. after the
|
||||
* events for all pressed keys with associated key tokens. You can tell these
|
||||
* events from user-generated events by the fact that the synthetic ones are
|
||||
* generated after the focus loss event has been processed, i.e. after the
|
||||
* [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
|
||||
*
|
||||
* The scancode of a key is specific to that platform or sometimes even to that
|
||||
|
|
@ -4617,8 +4718,6 @@ typedef struct GLFWallocator
|
|||
*
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED.
|
||||
*
|
||||
* @remark @wayland File drop is currently unimplemented.
|
||||
*
|
||||
* @thread_safety This function must only be called from the main thread.
|
||||
*
|
||||
* @sa @ref path_drop
|
||||
|
|
@ -5071,6 +5170,11 @@ typedef struct GLFWallocator
|
|||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
|
||||
* GLFW_PLATFORM_ERROR.
|
||||
*
|
||||
* @remark @win32 The clipboard on Windows has a single global lock for reading and
|
||||
* writing. GLFW tries to acquire it a few times, which is almost always enough. If it
|
||||
* cannot acquire the lock then this function emits @ref GLFW_PLATFORM_ERROR and returns.
|
||||
* It is safe to try this multiple times.
|
||||
*
|
||||
* @pointer_lifetime The specified string is copied before this function
|
||||
* returns.
|
||||
*
|
||||
|
|
@ -5098,6 +5202,11 @@ typedef struct GLFWallocator
|
|||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||
* GLFW_FORMAT_UNAVAILABLE and @ref GLFW_PLATFORM_ERROR.
|
||||
*
|
||||
* @remark @win32 The clipboard on Windows has a single global lock for reading and
|
||||
* writing. GLFW tries to acquire it a few times, which is almost always enough. If it
|
||||
* cannot acquire the lock then this function emits @ref GLFW_PLATFORM_ERROR and returns.
|
||||
* It is safe to try this multiple times.
|
||||
*
|
||||
* @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
|
||||
|
|
@ -5215,12 +5324,15 @@ typedef struct GLFWallocator
|
|||
* thread.
|
||||
*
|
||||
* This function makes the OpenGL or OpenGL ES context of the specified window
|
||||
* current on the calling thread. A context must only be made current on
|
||||
* a single thread at a time and each thread can have only a single current
|
||||
* context at a time.
|
||||
* current on the calling thread. It can also detach the current context from
|
||||
* the calling thread without making a new one current by passing in `NULL`.
|
||||
*
|
||||
* When moving a context between threads, you must make it non-current on the
|
||||
* old thread before making it current on the new one.
|
||||
* A context must only be made current on a single thread at a time and each
|
||||
* thread can have only a single current context at a time. Making a context
|
||||
* current detaches any previously current context on the calling thread.
|
||||
*
|
||||
* When moving a context between threads, you must detach it (make it
|
||||
* non-current) on the old thread before making it current on the new one.
|
||||
*
|
||||
* By default, making a context non-current implicitly forces a pipeline flush.
|
||||
* On machines that support `GL_KHR_context_flush_control`, you can control
|
||||
|
|
@ -5235,6 +5347,10 @@ typedef struct GLFWallocator
|
|||
* @param[in] window The window whose context to make current, or `NULL` to
|
||||
* detach the current context.
|
||||
*
|
||||
* @remarks If the previously current context was created via a different
|
||||
* context creation API than the one passed to this function, GLFW will still
|
||||
* detach the previous one from its API before making the new one current.
|
||||
*
|
||||
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
|
||||
* GLFW_NO_WINDOW_CONTEXT and @ref GLFW_PLATFORM_ERROR.
|
||||
*
|
||||
|
|
|
|||
Reference in a new issue