| blob | 8f96138abf4031019dfad4ede4f6a77207b865bd |
8 ;; Key and button state/action definitions
12 ;; Keyboard key definitions: 8-bit ISO-8859-1 (Latin 1) encoding is used
13 ;; for printable keys (such as A-Z, 0-9 etc), and values above 256
14 ;; represent special (non-printable) keys (e.g. F1, Page Up etc).
89 ;; Mouse button definitions
100 ;; Mouse button aliases
105 ;; Joystick identifiers
125 ;;========================================================================
126 ;; Other definitions
127 ;;========================================================================
129 ;; glfwOpenWindow modes
133 ;; glfwGetWindowParam tokens
145 ;; The following constants are used for both glfwGetWindowParam
146 ;; and glfwOpenWindowHint
165 ;; glfwEnable/glfwDisable tokens
173 ;; glfwWaitThread wait modes
177 ;; glfwGetJoystickParam tokens
182 ;; glfwReadImage/glfwLoadTexture2D flags
188 ;; Time spans longer than this (seconds) are considered to be infinity
204 "Return values
205 If the function succeeds, t is returned.
206 If the function fails, nil is returned.
208 The glfwInit function initializes GLFW. No other GLFW functions may be used before this function
209 has been called.
211 On successful initialization, the list of functions in *init-hooks* is called.
213 Notes
214 This function may take several seconds to complete on some systems, while on other systems it may
215 take only a fraction of a second to complete."
219 t))
224 "The function terminates GLFW. Among other things it closes the window, if it is opened, and kills any
225 running threads. This function must be called before a program exits.
227 Before termination, the list of functions in *terminate-hooks* is called.
228 "
236 "Return values
237 The function returns the major and minor version numbers and the revision for the currently linked
241 "Call glfw:init, execute forms and clean-up with glfw:terminate once finished.
242 This makes a nice wrapper to an application higher-level form.
243 Signals an error on failure to initialize. Wrapped in a block named glfw:with-init."
259 "width
260 The width of the window. If width is zero, it will be calculated as width = 4/3 height, if height is
261 not zero. If both width and height are zero, then width will be set to 640.
262 height
263 The height of the window. If height is zero, it will be calculated as height = 3/4 width, if width is
264 not zero. If both width and height are zero, then height will be set to 480.
265 redbits, greenbits, bluebits
266 The number of bits to use for each color component of the color buffer (0 means default color
267 depth). For instance, setting redbits=5, greenbits=6, and bluebits=5 will generate a 16-bit color
268 buffer, if possible.
269 alphabits
270 The number of bits to use for the alpha buffer (0 means no alpha buffer).
271 depthbits
272 The number of bits to use for the depth buffer (0 means no depth buffer).
273 stencilbits
274 The number of bits to use for the stencil buffer (0 means no stencil buffer).
275 mode
276 Selects which type of OpenGL window to use. mode can be either +WINDOW+, which
277 will generate a normal desktop window, or +FULLSCREEN+ which will generate a
278 window which covers the entire screen. When +FULLSCREEN+ is selected, the video
279 mode will be changed to the resolution that closest matches the width and height parameters.
281 Return values
282 If the function succeeds, t is returned.
283 If the function fails, nil is returned.
285 Description
287 The function opens a window that best matches the parameters given to
288 the function. How well the resulting window matches the desired window
289 depends mostly on the available hardware and OpenGL drivers. In
290 general, selecting a fullscreen mode has better chances of generating
291 a close match than does a normal desktop window, since GLFW can freely
292 select from all the available video modes. A desktop window is
293 normally restricted to the video mode of the desktop.
295 Notes
297 For additional control of window properties, see glfw::OpenWindowHint.
298 In fullscreen mode the mouse cursor is hidden by default, and any system screensavers are prohibited
299 from starting. In windowed mode the mouse cursor is visible, and screensavers are allowed to start. To
300 change the visibility of the mouse cursor, use glfwEnable or glfwDisable with the argument
301 +MOUSE_CURSOR+
302 In order to determine the actual properties of an opened window, use glfw::GetWindowParam and
303 glfw::GetWindowSize (or glfw::SetWindowSizeCallback).
304 "
310 "target
311 Can be any of the constants in the table 3.1.
312 hint
313 An integer giving the value of the corresponding target (see table 3.1).
315 Description
316 The function sets additional properties for a window that is to be opened. For a hint to be registered, the
317 function must be called before calling glfw::OpenWindow. When the glfw::OpenWindow function is
318 called, any hints that were registered with the glfw::OpenWindowHint function are used for setting the
319 corresponding window properties, and then all hints are reset to their default values.
321 Notes
322 In order to determine the actual properties of an opened window, use glfw::GetWindowParam (after the
323 window has been opened).
324 +STEREO+ is a hard constraint. If stereo rendering is requested, but no stereo rendering capable
325 pixel formats / visuals are available, glfw::OpenWindow will fail.
326 The +REFRESH_RATE+ property should be used with caution. Most systems have default values
327 for monitor refresh rates that are optimal for the specific system. Specifying the refresh rate can
328 override these settings, which can result in suboptimal operation. The monitor may be unable to display
329 the resulting video signal, or in the worst case it may even be damaged!
339 "Wraps forms such that there is an open window for them to execute in and cleans up the
340 window afterwards. An error is signalled if there was an error opening the window.
341 Takes the same parameters as open-window, with the addition of 'title' which will
342 set the window title after opening.
343 Wrapped in a block named glfw:with-open-window."
344 `(if (%open-window ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
357 "Wraps forms in with-init, with-open-window. Passes through the other arguments to open-window."
359 (with-open-window (:title ,title :width ,width :height ,height :redbits ,redbits :greenbits ,greenbits :bluebits ,bluebits :alphabits ,alphabits :depthbits ,depthbits :stencilbits ,stencilbits :mode ,mode)
367 "High-level convenience macro for initializing glfw, opening a window (given the optional window parameters),
368 setting the title given,
369 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
370 The loop is in a block named do-window [so can be exited by a call to (return-from glfw:do-window)].
371 If the window is closed, the loop is also exited."
372 `(with-init-window (:title ,title :width ,width :height ,height :redbits ,redbits :greenbits ,greenbits :bluebits ,bluebits :alphabits ,alphabits :depthbits ,depthbits :stencilbits ,stencilbits :mode ,mode)
373 ,@setup-forms
375 ,@forms
380 (defmacro define-callback-setter (c-name callback-prefix return-type (&body args) &key before-form after-form documentation)
390 ,before-form
397 All callback setting functions can take either a pointer to a C function,
398 a function object, a function symbol, or nil to clear the callback function.
400 THIS CALLBACK FUNCTION
414 (t (error "Not an acceptable callback. Must be foreign pointer, function object, function's symbol, or nil.")))))))
418 :documentation
419 "
420 Function that will be called when a user requests that the window should be
421 closed, typically by clicking the window close icon (e.g. the cross in the upper right corner of a
422 window under Microsoft Windows). The function should have the following type:
423 (function () integer)
425 The return value of the callback function indicates whether or not the window close action should continue. If the function returns
426 gl:+true+, the window will be closed. If the function returns gl:+false+, the window will not
427 be closed. If you give a CFFI callback returning glfw:boolean, you can use t and nil as return types.
429 Notes
430 Window close events are recorded continuously, but only reported when glfwPollEvents,
431 glfwWaitEvents or glfwSwapBuffers is called.
432 The OpenGL context is still valid when this function is called.
433 Note that the window close callback function is not called when glfwCloseWindow is called, but only
434 when the close request comes from the window manager.
435 Do not call glfwCloseWindow from a window close callback function. Close the window by returning
436 gl:+true+ from the function.
441 "Parameters
442 title
443 Pointer to a null terminated ISO 8859-1 (8-bit Latin 1) string that holds the title of the window.
445 Description
446 The function changes the title of the opened window.
448 Notes
449 The title property of a window is often used in situations other
450 than for the window title, such as the title of an application icon
454 "Parameters
455 width
456 Width of the window.
457 height
458 Height of the window.
459 Return values
460 none
461 Description
463 The function changes the size of an opened window. The width and
464 height parameters denote the size of the client area of the
465 window (i.e. excluding any window borders and decorations). If the
466 window is in fullscreen mode, the video mode will be changed to a
467 resolution that closest matches the width and height parameters (the
468 number of color bits will not be changed).
470 Notes
472 The OpenGL context is guaranteed to be preserved after calling glfwSetWindowSize, even if the
473 video mode is changed.
477 "Parameters
478 x
479 Horizontal position of the window, relative to the upper left corner of the desktop.
480 y
481 Vertical position of the window, relative to the upper left corner of the desktop.
482 Return values
483 none
484 Description
485 The function changes the position of an opened window. It does not have any effect on a fullscreen
486 window.
491 "The function is used for determining the size of an opened window. The returned values are dimensions
492 of the client area of the window (i.e. excluding any window borders and decorations).
493 (list width height)"
500 (define-callback-setter "glfwSetWindowSizeCallback" #:window-size :void ((width :int) (height :int))
501 :documentation
502 "
503 Function that will be called every time the window size changes. The
504 function should takes the arguments (width height) giving the new width and height of the window client area.
506 A window has to be opened for this function to have any effect.
507 Notes
508 Window size changes are recorded continuously, but only reported when glfwPollEvents,
512 "Iconify a window. If the window is in fullscreen mode, then the desktop video mode will be restored.")
515 "Restore an iconified window. If the window that is restored is in fullscreen mode, then the fullscreen
519 "Parameters
520 param
521 A token selecting which parameter the function should return (see table 3.2).
523 Return values
525 The function returns different parameters depending on the value of
526 param. Table 3.2 lists valid param values, and their corresponding
527 return values.
529 Description
530 The function is used for acquiring various properties of an opened window.
532 Notes: GLFW_ACCELERATED is only supported under Windows. Other systems
533 will always return GL_TRUE. Under Windows, GLFW_ACCELERATED means that
534 the OpenGL renderer is a 3rd party renderer, rather than the fallback
535 Microsoft software OpenGL renderer. In other words, it is not a real
536 guarantee that the OpenGL renderer is actually hardware accelerated.
540 "The function swaps the back and front color buffers of the window. If +AUTO_POLL_EVENTS+
541 is enabled (which is the default), glfwPollEvents is called before swapping the front and back buffers.")
545 "Parameters
546 interval
547 Minimum number of monitor vertical retraces between each buffer swap performed by
548 glfwSwapBuffers. If interval is zero, buffer swaps will not be synchronized to the vertical
549 refresh of the monitor (also known as VSync off).
551 Description
553 The function selects the minimum number of monitor vertical retraces
554 that should occur between two buffer swaps. If the selected swap
555 interval is one, the rate of buffer swaps will never be higher than
556 the vertical refresh rate of the monitor. If the selected swap
557 interval is zero, the rate of buffer swaps is only limited by the
558 speed of the software and the hardware.
560 Notes
562 This function will only have an effect on hardware and drivers that
567 :documentation
568 "
569 Function that will be called when the window client area needs to be
570 refreshed. The function takes no arguments and returns nothing (void).
572 Description
574 The function selects which function to be called upon a window refresh
575 event, which occurs when any part of the window client area has been
576 damaged, and needs to be repainted (for instance, if a part of the
577 window that was previously occluded by another window has become
578 visible). A window has to be opened for this function to have any
579 effect.
581 Notes
582 Window refresh events are recorded continuously, but only reported when glfwPollEvents,
583 glfwWaitEvents or glfwSwapBuffers is called.
596 "Parameters
597 maxcount
598 Maximum number of video modes that list vector can hold.
600 Return values
601 The function returns the number of detected video modes (this number will never exceed maxcount).
602 The list vector is filled out with the video modes that are supported by the system.
604 Description
605 The function returns a list of supported video modes. Each video mode is represented by a
606 list of the form:
607 (width height redbits greenbits bluebits)
609 Notes
610 The returned list is sorted, first by color depth (RedBits + GreenBits + BlueBits), and then by
611 resolution (Width * Height), with the lowest resolution, fewest bits per pixel mode first. "
616 collecting
626 "Parameters
627 mode
628 Pointer to a GLFWvidmode structure, which will be filled out by the function.
629 Return values
630 The GLFWvidmode structure pointed to by mode is filled out with the desktop video mode.
631 Description
632 The function returns the desktop video mode in a GLFWvidmode structure. See glfwGetVideoModes
633 for a definition of the GLFWvidmode structure.
634 Notes
635 The color depth of the desktop display is always reported as the number of bits for each individual color
636 component (red, green and blue), even if the desktop is not using an RGB or RGBA color format. For
637 instance, an indexed 256 color display may report RedBits = 3, GreenBits = 3 and BlueBits = 2, which
638 adds up to 8 bits in total.
639 The desktop video mode is the video mode used by the desktop, not the current video mode (which may
640 differ from the desktop video mode if the GLFW window is a fullscreen window).
641 "
651 "Description
652 The function is used for polling for events, such as user input and window resize events. Upon calling
653 this function, all window states, keyboard states and mouse states are updated. If any related callback
654 functions are registered, these are called during the call to glfwPollEvents.
656 Notes
657 glfwPollEvents is called implicitly from glfwSwapBuffers if +AUTO_POLL_EVENTS+ is
658 enabled (default). Thus, if glfwSwapBuffers is called frequently, which is normally the case, there is
659 no need to call glfwPollEvents.
663 "Description
664 The function is used for waiting for events, such as user input and window resize events. Upon calling
665 this function, the calling thread will be put to sleep until any event appears in the event queue. When
666 events are ready, the events will be processed just as they are processed by glfwPollEvents.
667 If there are any events in the queue when the function is called, the function will behave exactly like
668 glfwPollEvents (i.e. process all messages and then return, without blocking the calling thread).
670 Notes
671 It is guaranteed that glfwWaitEvents will wake up on any event that can be processed by
672 glfw::PollEvents. However, glfwWaitEvents may wake up on events that are not processed or reported
673 by glfw::PollEvents too, and the function may behave differently on different systems. Do no make any
674 assumptions about when or why glfw::WaitEvents will return.
680 (loop for special-key in '("backspace" "del" "down" "end" "enter" "esc" "f1" "f10" "f11" "f12" "f13"
688 collect
689 `(,(symbol-value (find-symbol (string-upcase (format nil "+key-~a+" special-key)) (find-package '#:glfw)))
695 "Convert key-int from GLFW's integer representation to lisp characters if from 0 to 255, or keywords, if not within 0-255 inclusive."
702 "Parameters
703 key
704 A keyboard key identifier, which can be either an uppercase printable ISO 8859-1 (Latin 1)
705 character (e.g. 'A', '3' or '.'), or a special key identifier. Table 3.3 lists valid special key
706 identifiers.
707 Return values
708 The function returns +PRESS+ if the key is held down, or +RELEASE+ if the key is not
709 held down.
711 Description
712 The function queries the current state of a specific keyboard key. The physical location of each key
713 depends on the system keyboard layout setting.
715 Notes
716 The constant +KEY_SPACE+ is equal to 32, which is the ISO 8859-1 code for space.
717 Not all key codes are supported on all systems. Also, while some keys are available on some keyboard
718 layouts, they may not be available on other keyboard layouts.
719 For systems that do not distinguish between left and right versions of modifier keys (shift, alt and
720 control), the left version is used (e.g. +KEY_LSHIFT+)
721 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
722 glfw::SwapBuffers must be called before any keyboard events are recorded and reported by
723 glfw::GetKey.
728 "Convert button-int from GLFW's integer representation to a lisp keyword."
741 "Parameters
742 button
743 A mouse button identifier, which can be one of the mouse button identifiers listed in table 3.4.
744 Return values
745 The function returns +PRESS+ if the mouse button is held down, or +RELEASE+ if the
746 mouse button is not held down.
747 Description
748 The function queries the current state of a specific mouse button.
749 Notes
750 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
751 glfw::SwapBuffers must be called before any mouse button events are recorded and reported by
752 glfw::GetMouseButton.
753 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
754 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
755 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
760 "Return values
761 The function returns the current mouse position in xpos and ypos.
763 Description
764 The function returns the current mouse position. If the cursor is not hidden, the mouse position is the
765 cursor position, relative to the upper left corner of the window and limited to the client area of the
766 window. If the cursor is hidden, the mouse position is a virtual absolute position, not limited to any
767 boundaries except to those implied by the maximum number that can be represented by a signed integer
768 (normally -2147483648 to +2147483647).
770 Notes
771 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
772 glfw::SwapBuffers must be called before any mouse movements are recorded and reported by
773 glfw::GetMousePos.
778 "Parameters
779 xpos
780 Horizontal position of the mouse.
781 ypos
782 Vertical position of the mouse.
784 Description
785 The function changes the position of the mouse. If the cursor is visible (not disabled), the cursor will be
786 moved to the specified position, relative to the upper left corner of the window client area. If the cursor
787 is hidden (disabled), only the mouse position that is reported by GLFW is changed.
791 "Return values
792 The function returns the current mouse wheel position.
793 Description
794 The function returns the current mouse wheel position. The mouse wheel can be thought of as a third
795 mouse axis, which is available as a separate wheel or up/down stick on some mice.
796 Notes
797 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
798 glfw::SwapBuffers must be called before any mouse wheel movements are recorded and reported by
799 glfw::GetMouseWheel.
803 "Parameters
804 pos
805 Position of the mouse wheel.
806 Description
807 The function changes the position of the mouse wheel.
813 :documentation
814 "
815 Function that will be called every time a key is pressed or released.
816 Function should take the arguments (key action), where key is either a character,
817 if the key pressed was a member of iso-8859-1, or a keyword representing the key pressed if not.
818 See the GLFW manual, table 3.3 for special key identifiers. Action is either glfw:+press+ or
819 glfw:+release+. Use set-char-callback instead if you want to read just characters.
821 Description
822 The function selects which function to be called upon a keyboard key event. The callback function is
823 called every time the state of a single key is changed (from released to pressed or vice versa). The
824 reported keys are unaffected by any modifiers (such as shift or alt).
825 A window has to be opened for this function to have any effect.
827 Notes
828 Keyboard events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
829 or glfw::SwapBuffers is called.
833 :documentation
834 "
835 Function that will be called every time a printable character is generated by
836 the keyboard. The function should take the arguments (character action)
837 where character is a lisp character and action is either glfw:+press+ or glfw:+release+.
839 NB this makes the presumption that your lisp implementation will use Unicode for code-char.
841 Description
842 The function selects which function to be called upon a keyboard character event. The callback function
843 is called every time a key that results in a printable Unicode character is pressed or released. Characters
844 are affected by modifiers (such as shift or alt).
845 A window has to be opened for this function to have any effect.
847 Notes
848 Character events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
849 or glfw::SwapBuffers is called.
850 Control characters, such as tab and carriage return, are not reported to the character callback function,
851 since they are not part of the Unicode character set. Use the key callback function for such events (see
852 glfw::SetKeyCallback).
853 The Unicode character set supports character codes above 255, so never cast a Unicode character to an
854 eight bit data type (e.g. the C language char type) without first checking that the character code is less
855 than 256. Also note that Unicode character codes 0 to 255 are equal to ISO 8859-1 (Latin 1).
858 (define-callback-setter "glfwSetMouseButtonCallback" #:mouse-button :void ((button :int) (action :int))
860 :documentation
861 "
862 Function that will be called every time a mouse button is pressed or released.
863 The function takes the arguments (button action), where button is a keyword symbol as returned by
864 lispify-mouse-button and action is either glfw:+press+ or glfw:+release+.
866 Description
867 The function selects which function to be called upon a mouse button event.
868 A window has to be opened for this function to have any effect.
870 Notes
871 Mouse button events are recorded continuously, but only reported when glfw::PollEvents,
872 glfw::WaitEvents or glfw::SwapBuffers is called.
873 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
874 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
875 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
878 :documentation
879 "
880 Function that will be called every time the mouse is moved.
881 The function takes the arguments (x y), where x and y are the current position of the mouse.
883 Description
884 The function selects which function to be called upon a mouse motion event.
885 A window has to be opened for this function to have any effect.
887 Notes
888 Mouse motion events are recorded continuously, but only reported when glfw::PollEvents,
889 glfw::WaitEvents or glfw::SwapBuffers is called.
895 :documentation
896 "
897 Function that will be called every time the mouse wheel is moved.
898 The function takes one argument: the position of the mouse wheel.
899 This DIFFERS FROM GLFW's DEFAULT behaviour in that the position is
900 reset after every call to this function, effectively giving the delta.
901 As most programs are only interested in the delta anyway, this is thought
902 to save others recording the state of it again.
903 If you wish to have the original GLFW behaviour, set cl-glfw:*mouse-wheel-cumulative* to t.
905 Description
906 The function selects which function to be called upon a mouse wheel event.
907 A window has to be opened for this function to have any effect.
908 Notes
909 Mouse wheel events are recorded continuously, but only reported when glfw::PollEvents,
910 glfw::WaitEvents or glfw::SwapBuffers is called.
914 "Parameters
915 joy
916 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
917 param
918 A token selecting which parameter the function should return (see table 3.5).
919 Return values
920 The function returns different parameters depending on the value of param. Table 3.5 lists valid param
921 values, and their corresponding return values.
922 Description
923 The function is used for acquiring various properties of a joystick.
924 Notes
925 The joystick information is updated every time the function is called.
926 No window has to be opened for joystick information to be valid.
929 (defcfun ("glfwGetJoystickPos" %get-joystick-pos) :int (joy :int) (pos :pointer) (numaxes :int))
932 "Parameters
933 joy
934 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
935 numaxes
936 Specifies how many axes should be returned.
937 Return values
938 An list that will hold the positional values for all requested axes.
939 If the joystick is not supported or connected, the function will
940 return nil.
942 Description
943 The function queries the current position of one or more axes of a joystick. The positional values are
944 returned in an array, where the first element represents the first axis of the joystick (normally the X
945 axis). Each position is in the range -1.0 to 1.0. Where applicable, the positive direction of an axis is
946 right, forward or up, and the negative direction is left, back or down.
947 If numaxes exceeds the number of axes supported by the joystick, or if the joystick is not available, the
948 unused elements in the pos array will be set to 0.0 (zero).
950 Notes
951 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
952 or glfw::WaitEvents for joystick state to be updated.
953 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
954 supported axes.
955 No window has to be opened for joystick input to be valid.
956 "
962 (defcfun ("glfwGetJoystickButtons" %get-joystick-buttons) :int (joy :int) (buttons :pointer) (numbuttons :int))
964 "Parameters
965 joy
966 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
967 numbuttons
968 Specifies how many buttons should be returned.
969 Return values
970 A list that will hold the button states for all requested buttons.
971 The function returns the number of actually returned buttons. This is the minimum of numbuttons and
972 the number of buttons supported by the joystick. If the joystick is not supported or connected, the
973 function will return 0 (zero).
975 Description
976 The function queries the current state of one or more buttons of a joystick. The button states are
977 returned in an array, where the first element represents the first button of the joystick. Each state can be
978 either +PRESS+ or +RELEASE+
979 If numbuttons exceeds the number of buttons supported by the joystick, or if the joystick is not
980 available, the unused elements in the buttons array will be set to +RELEASE+
982 Notes
983 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
984 or glfw::WaitEvents for joystick state to be updated.
985 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
986 supported buttons.
987 No window has to be opened for joystick input to be valid.
988 "
995 "Return values
996 The function returns the value of the high precision timer. The time is measured in seconds, and is
997 returned as a double precision floating point value.
999 Description
1000 The function returns the state of a high precision timer. Unless the timer has been set by the
1001 glfw::SetTime function, the time is measured as the number of seconds that have passed since glfw::Init
1002 was called.
1004 Notes
1005 The resolution of the timer depends on which system the program is running on. The worst case
1006 resolution is somewhere in the order of 10 ms, while for most systems the resolution should be better
1007 than 1us.
1011 "Parameters
1012 time
1013 Time (in seconds) that the timer should be set to.
1015 Description
1016 The function sets the current time of the high precision timer to the specified time. Subsequent calls to
1017 glfw::GetTime will be relative to this time. The time is given in seconds.
1021 "Parameters
1022 time
1023 Time, in seconds, to sleep.
1025 Description
1026 The function puts the calling thread to sleep for the requested period of time. Only the calling thread is
1027 put to sleep. Other threads within the same process can still execute.
1029 Notes
1030 There is usually a system dependent minimum time for which it is possible to sleep. This time is
1031 generally in the range 1 ms to 20 ms, depending on thread sheduling time slot intervals etc. Using a
1032 shorter time as a parameter to glfw::Sleep can give one of two results: either the thread will sleep for the
1033 minimum possible sleep time, or the thread will not sleep at all (glfw::Sleep returns immediately). The
1045 "Parameters
1046 name
1047 A null terminated ISO 8859-1 string holding the name of the file that should be read.
1048 img
1049 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1050 read was successful).
1051 flags
1052 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1053 Return values
1054 The function returns t if the image was loaded successfully. Otherwise nil is
1055 returned.
1056 Description
1057 The function reads an image from the file specified by the parameter name and returns the image
1058 information and data in a GLFWimage structure, which has the following definition:
1060 typedef struct {
1061 int Width, Height; // Image dimensions
1062 int Format; // OpenGL pixel format
1063 int BytesPerPixel; // Number of bytes per pixel
1064 unsigned char *Data; // Pointer to pixel data
1065 } GLFWimage;
1067 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1068 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1069 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1071 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1072 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1073 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1074 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1075 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1076 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1078 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1079 Notes
1080 glfw::ReadImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel formats
1081 are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color + alpha.
1082 Paletted images are translated into true color or true color + alpha pixel formats.
1083 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1084 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1089 "Parameters
1090 data
1091 The memory buffer holding the contents of the file that should be read.
1092 size
1093 The size, in bytes, of the memory buffer.
1094 img
1095 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1096 read was successful).
1097 flags
1098 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1099 Return values
1100 The function returns t if the image was loaded successfully. Otherwise nil is
1101 returned.
1102 Description
1103 The function reads an image from the memory buffer specified by the parameter data and returns the
1104 image information and data in a GLFWimage structure, which has the following definition:
1106 typedef struct {
1107 int Width, Height; // Image dimensions
1108 int Format; // OpenGL pixel format
1109 int BytesPerPixel; // Number of bytes per pixel
1110 unsigned char *Data; // Pointer to pixel data
1111 } GLFWimage;
1113 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1114 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1115 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1117 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1118 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1119 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1120 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1121 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1122 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1123 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1124 Notes
1125 glfw::ReadMemoryImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1126 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1127 alpha.
1128 Paletted images are translated into true color or true color + alpha pixel formats.
1129 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1130 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1134 "Parameters
1135 img
1136 Pointer to a GLFWimage struct.
1137 Description
1138 The function frees any memory occupied by a loaded image, and clears all the fields of the GLFWimage
1139 struct. Any image that has been loaded by the glfw::ReadImage function should be deallocated using
1143 "Parameters
1144 name
1145 An ISO 8859-1 string holding the name of the file that should be loaded.
1146 flags
1147 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1148 Return values
1149 The function returns t if the texture was loaded successfully. Otherwise nil is
1150 returned.
1152 Description
1154 The function reads an image from the file specified by the parameter
1155 name and uploads the image to OpenGL texture memory (using the
1156 glTexImage2D function). If the GLFW_BUILD_MIPMAPS_BIT flag is set,
1157 all mipmap levels for the loaded texture are generated and uploaded to
1158 texture memory. Unless the flag +ORIGIN_UL_BIT+ is set, the origin of
1159 the texture is the lower left corner of the loaded image. If the flag
1160 +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1161 corner. For single component images (i.e. gray scale), the texture is
1162 uploaded as an alpha mask if the flag +ALPHA_MAP_BIT+ flag is set,
1163 otherwise it is uploaded as a luminance texture.
1165 Notes
1166 glfw::LoadTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1167 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1168 alpha.
1169 Paletted images are translated into true color or true color + alpha pixel formats.
1170 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1171 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1172 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1173 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1174 generated by GLFW in software.
1176 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1177 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1178 texture is a single component texture. The red, green and blue components are set to 1.0.
1183 "Parameters
1184 data
1185 The memory buffer holding the contents of the file that should be loaded.
1186 size
1187 The size, in bytes, of the memory buffer.
1188 flags
1189 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1190 Return values
1191 The function returns t if the texture was loaded successfully. Otherwise nil is
1192 returned.
1194 Description
1195 The function reads an image from the memory buffer specified by the parameter data and uploads the
1196 image to OpenGL texture memory (using the glTexImage2D function).
1197 If the GLFW_BUILD_MIPMAPS_BIT flag is set, all mipmap levels for the loaded texture are
1198 generated and uploaded to texture memory.
1199 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1200 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1201 corner.
1202 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1203 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1205 Notes
1206 glfw::LoadMemoryTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported
1207 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1208 + alpha.
1209 Paletted images are translated into true color or true color + alpha pixel formats.
1210 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1211 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1212 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1213 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1214 generated by GLFW in software.
1216 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1217 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1218 texture is a single component texture. The red, green and blue components are set to 1.0.
1224 "Parameters
1225 img
1226 Pointer to a GLFWimage struct holding the information about the image to be loaded.
1227 flags
1228 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1229 Return values
1230 The function returns t if the texture was loaded successfully. Otherwise nil is
1231 returned.
1233 Description
1234 The function uploads the image specified by the parameter img to OpenGL texture memory (using
1235 the glTexImage2D function).
1236 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1237 generated and uploaded to texture memory.
1238 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1239 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1240 corner.
1241 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1242 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1244 Notes
1245 glfw::LoadTextureImage2D supports the Truevision Targa version 1 file format (.TGA). Supported
1246 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1247 + alpha.
1248 Paletted images are translated into true color or true color + alpha pixel formats.
1249 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1250 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1251 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1252 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1253 generated by GLFW in software.
1255 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1256 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1261 "Parameters
1262 extension
1263 A null terminated ISO 8859-1 string containing the name of an OpenGL extension.
1264 Return values
1265 The function returns t if the extension is supported. Otherwise it returns nil.
1266 Description
1267 The function does a string search in the list of supported OpenGL extensions to find if the specified
1268 extension is listed.
1269 Notes
1271 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1272 must have been opened with glfwOpenWindow).
1273 In addition to checking for OpenGL extensions, GLFW also checks for extensions in the operating
1274 system ?glue API?, such as WGL extensions under Windows and glX extensions under the X Window
1275 System.
1279 "Parameters
1280 procname
1281 A null terminated ISO 8859-1 string containing the name of an OpenGL extension function.
1282 Return values
1283 The function returns the pointer to the specified OpenGL function if it is supported, otherwise
1284 NULL is returned.
1285 Description
1286 The function acquires the pointer to an OpenGL extension function. Some (but not all) OpenGL
1287 extensions define new API functions, which are usually not available through normal linking. It is
1288 therefore necessary to get access to those API functions at runtime.
1289 Notes
1291 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1292 must have been opened with glfwOpenWindow).
1293 Some systems do not support dynamic function pointer retrieval, in which case glfwGetProcAddress
1294 will always return NULL.
1300 "Return values
1301 The function returns the major and minor version numbers and the revision for the currently used
1302 OpenGL implementation as a list (major minor rev).
1304 Description
1305 The function returns the OpenGL implementation version. This is a convenient function that parses
1306 the version number information from the string returned by calling
1307 glGetString( GL_VERSION ). The OpenGL version information can be used to determine
1308 what functionality is supported by the used OpenGL implementation.
1310 Notes
1311 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1320 "Parameters
1321 fun
1322 A pointer to a function that acts as the entry point for the new thread. The function should have
1323 the following C language prototype:
1324 void GLFWCALL functionname( void *arg );
1325 Where functionname is the name of the thread function, and arg is the user supplied argument
1326 (see below).
1327 arg
1328 An arbitrary argument for the thread. arg will be passed as the argument to the thread function
1329 pointed to by fun. For instance, arg can point to data that is to be processed by the thread.
1330 Return values
1331 The function returns a thread identification number if the thread was created successfully. This number
1332 is always positive. If the function fails, a negative number is returned.
1333 Description
1334 The function creates a new thread, which executes within the same address space as the calling process.
1335 The thread entry point is specified with the fun argument.
1336 Once the thread function fun returns, the thread dies.
1337 Notes
1338 Even if the function returns a positive thread ID, indicating that the thread was created successfully, the
1339 thread may be unable to execute, for instance if the thread start address is not a valid thread entry point.
1342 "Parameters
1343 ID
1344 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1345 Description
1346 The function kills a running thread and removes it from the thread list.
1347 Notes
1348 This function is a very dangerous operation, which may interrupt a thread in the middle of an important
1349 operation, and its use is discouraged. You should always try to end a thread in a graceful way using
1350 thread communication, and use glfw::WaitThread in order to wait for the thread to die.
1353 "Parameters
1354 ID
1355 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1356 waitmode
1357 Can be either +WAIT+ or +NOWAIT+
1358 Return values
1359 The function returns t if the specified thread died after the function was called, or the thread
1360 did not exist, in which case glfw::WaitThread will return immediately regardless of waitmode. The
1361 function returns nil if waitmode is +NOWAIT+ and the specified thread exists and is still
1362 running.
1365 "Return values
1366 The function returns a thread identification handle for the calling thread.
1367 Description
1368 The function determines the thread ID for the calling thread. The ID is the same value as was returned
1369 by glfw::CreateThread when the thread was created.
1373 "Return values
1374 The function returns a mutex handle, or NULL if the mutex could not be created.
1375 Description
1376 The function creates a mutex object, which can be used to control access to data that is shared between
1377 threads.
1380 "Parameters
1381 mutex
1382 A mutex object handle.
1383 Description
1384 The function destroys a mutex object. After a mutex object has been destroyed, it may no longer be
1385 used by any thread.
1388 "Parameters
1389 mutex
1390 A mutex object handle.
1391 Description
1392 The function will acquire a lock on the selected mutex object. If the mutex is already locked by another
1393 thread, the function will block the calling thread until it is released by the locking thread. Once the
1394 function returns, the calling thread has an exclusive lock on the mutex. To release the mutex, call
1395 glfw::UnlockMutex.
1398 "Parameters
1399 mutex
1400 A mutex object handle.
1401 Description
1402 The function releases the lock of a locked mutex object.
1406 "Parameters
1407 mutex
1408 A mutex object handle.
1409 forms
1410 Body of code to execute
1411 Description
1412 This macro will acquire a lock on the selected mutex object using glfw::LockMutex and release it afterwards
1413 using glfw::UnlockMutex.
1414 So, forms will not execute until an exclusive lock is held.
1415 The lock is then released when the stack is unwound."
1423 "Return values
1424 The function returns a condition variable handle, or NULL if the condition variable could not be
1425 created.
1426 Description
1427 The function creates a condition variable object, which can be used to synchronize threads.
1430 "Parameters
1431 cond
1432 A condition variable object handle.
1433 Description
1434 The function destroys a condition variable object. After a condition variable object has been destroyed,
1435 it may no longer be used by any thread.
1438 " arameters
1439 cond
1440 A condition variable object handle.
1441 mutex
1442 A mutex object handle.
1443 timeout
1444 Maximum time to wait for the condition variable. The parameter can either be a positive time (in
1445 seconds), or +INFINITY+
1446 Description
1447 The function atomically unlocks the mutex specified by mutex, and waits for the condition variable cond
1448 to be signaled. The thread execution is suspended and does not consume any CPU time until the
1449 condition variable is signaled or the amount of time specified by timeout has passed. If timeout is
1450 +INFINITY+ glfw::WaitCond will wait forever for cond to be signaled. Before returning to the
1451 calling thread, glfw::WaitCond automatically re-acquires the mutex.
1452 Notes
1453 The mutex specified by mutex must be locked by the calling thread before entrance to glfw::WaitCond.
1454 A condition variable must always be associated with a mutex, to avoid the race condition where a thread
1455 prepares to wait on a condition variable and another thread signals the condition just before the first
1456 thread actually waits on it.
1459 "Parameters
1460 cond
1461 A condition variable object handle.
1462 Description
1463 The function restarts one of the threads that are waiting on the condition variable cond. If no threads are
1464 waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it
1465 is not specified which.
1466 Notes
1467 When several threads are waiting for the condition variable, which thread is started depends on
1468 operating system scheduling rules, and may vary from system to system and from time to time.
1471 "Parameters
1472 cond
1473 A condition variable object handle.
1474 Description
1475 The function restarts all the threads that are waiting on the condition variable cond. If no threads are
1476 waiting on cond, nothing happens.
1477 Notes
1478 When several threads are waiting for the condition variable, the order in which threads are started
1479 depends on operating system scheduling rules, and may vary from system to system and from time to
1480 time.
1484 "Return values
1485 The function returns the number of active processors in the system.
1486 Description
1487 The function determines the number of active processors in the system.
1488 Notes
1489 Systems with several logical processors per physical processor, also known as SMT (Symmetric Multi
1490 Threading) processors, will report the number of logical processors.
1493 "Parameters
1494 token
1495 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1496 Return values
1497 none
1498 Description
1499 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1500 description of each feature.
1501 +AUTO_POLL_EVENTS+
1502 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1503 that glfw::SwapBuffers is called.
1504 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1505 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1506 function, since calling glfw::PollEvents from a callback function is not allowed.
1507 +KEY_REPEAT+
1508 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1509 when a key is held down long enough (according to the system key repeat configuration).
1510 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1511 when a key is pressed (and once when it is released).
1512 +MOUSE_CURSOR+
1513 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1514 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1515 the client area of the window.
1516 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1517 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1518 from the mouse, without being restricted or manipulated by the windowing system.
1519 +STICKY_KEYS+
1520 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1521 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1522 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1523 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1524 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1525 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1526 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfw::GetKey is always
1527 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1528 all keys.
1529 +STICKY_MOUSE_BUTTONS+
1530 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1531 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1532 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1533 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1534 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1535 glfw::GetMouseButton will never be released. Note also that enabling
1536 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1537 functionality.
1538 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1539 by glfw::GetMouseButton is always the physical state of the mouse button. Disabling
1540 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1541 +SYSTEM_KEYS+
1542 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1543 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1544 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1545 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1546 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1547 the GLFW video mode again.
1548 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1549 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1550 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1553 "Parameters
1554 token
1555 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1556 Return values
1557 none
1558 Description
1559 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1560 description of each feature.
1561 +AUTO_POLL_EVENTS+
1562 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1563 that glfw::SwapBuffers is called.
1564 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1565 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1566 function, since calling glfw::PollEvents from a callback function is not allowed.
1567 +KEY_REPEAT+
1568 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1569 when a key is held down long enough (according to the system key repeat configuration).
1570 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1571 when a key is pressed (and once when it is released).
1572 +MOUSE_CURSOR+
1573 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1574 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1575 the client area of the window.
1576 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1577 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1578 from the mouse, without being restricted or manipulated by the windowing system.
1579 +STICKY_KEYS+
1580 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1581 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1582 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1583 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1584 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1585 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1586 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfwGetKey is always
1587 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1588 all keys.
1589 +STICKY_MOUSE_BUTTONS+
1590 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1591 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1592 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1593 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1594 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1595 glfw::GetMouseButton will never be released. Note also that enabling
1596 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1597 functionality.
1598 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1599 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1600 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1601 +SYSTEM_KEYS+
1602 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1603 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1604 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1605 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1606 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1607 the GLFW video mode again.
1608 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1609 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1610 the GLFW program must not be interrupted (normally for games in fullscreen mode).