| blob | 5db534229e6beceaf5f551d565f84301d85489c9 |
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 title
260 ;;The hints
277 "width
278 The width of the window. If width is zero, it will be calculated as width = 4/3 height, if height is
279 not zero. If both width and height are zero, then width will be set to 640.
280 height
281 The height of the window. If height is zero, it will be calculated as height = 3/4 width, if width is
282 not zero. If both width and height are zero, then height will be set to 480.
283 redbits, greenbits, bluebits
284 The number of bits to use for each color component of the color buffer (0 means default color
285 depth). For instance, setting redbits=5, greenbits=6, and bluebits=5 will generate a 16-bit color
286 buffer, if possible.
287 alphabits
288 The number of bits to use for the alpha buffer (0 means no alpha buffer).
289 depthbits
290 The number of bits to use for the depth buffer (0 means no depth buffer).
291 stencilbits
292 The number of bits to use for the stencil buffer (0 means no stencil buffer).
293 mode
294 Selects which type of OpenGL window to use. mode can be either +WINDOW+, which
295 will generate a normal desktop window, or +FULLSCREEN+ which will generate a
296 window which covers the entire screen. When +FULLSCREEN+ is selected, the video
297 mode will be changed to the resolution that closest matches the width and height parameters.
299 Return values
300 If the function succeeds, t is returned.
301 If the function fails, nil is returned.
303 Description
305 The function opens a window that best matches the parameters given to
306 the function. How well the resulting window matches the desired window
307 depends mostly on the available hardware and OpenGL drivers. In
308 general, selecting a fullscreen mode has better chances of generating
309 a close match than does a normal desktop window, since GLFW can freely
310 select from all the available video modes. A desktop window is
311 normally restricted to the video mode of the desktop.
313 Notes
315 For additional control of window properties, see glfw::OpenWindowHint.
316 In fullscreen mode the mouse cursor is hidden by default, and any system screensavers are prohibited
317 from starting. In windowed mode the mouse cursor is visible, and screensavers are allowed to start. To
318 change the visibility of the mouse cursor, use glfwEnable or glfwDisable with the argument
319 +MOUSE_CURSOR+
320 In order to determine the actual properties of an opened window, use glfw::GetWindowParam and
321 glfw::GetWindowSize (or glfw::SetWindowSizeCallback).
322 "
336 accum-red-bits accum-green-bits accum-blue-bits
337 accum-alpha-bits
338 aux-buffers
339 fsaa-samples
340 opengl-version-major
341 opengl-version-minor
342 opengl-profile
343 opengl-core-profile
344 opengl-compat-profile)
346 window-no-resize
347 opengl-forward-compat
348 opengl-debug-context))
356 "target
357 Can be any of the constants in the table 3.1.
358 hint
359 An integer giving the value of the corresponding target (see table 3.1).
361 Description
362 The function sets additional properties for a window that is to be opened. For a hint to be registered, the
363 function must be called before calling glfw::OpenWindow. When the glfw::OpenWindow function is
364 called, any hints that were registered with the glfw::OpenWindowHint function are used for setting the
365 corresponding window properties, and then all hints are reset to their default values.
367 Notes
368 In order to determine the actual properties of an opened window, use glfw::GetWindowParam (after the
369 window has been opened).
370 +STEREO+ is a hard constraint. If stereo rendering is requested, but no stereo rendering capable
371 pixel formats / visuals are available, glfw::OpenWindow will fail.
372 The +REFRESH_RATE+ property should be used with caution. Most systems have default values
373 for monitor refresh rates that are optimal for the specific system. Specifying the refresh rate can
374 override these settings, which can result in suboptimal operation. The monitor may be unable to display
375 the resulting video signal, or in the worst case it may even be damaged!
383 "Wraps forms such that there is an open window for them to execute in and cleans up the
384 window afterwards. An error is signalled if there was an error opening the window.
385 Takes the same parameters as open-window, with the addition of 'title' which will
386 set the window title after opening.
387 Wrapped in a block named glfw:with-open-window."
397 "Wraps forms in with-init, with-open-window. Passes through the other arguments to open-window."
405 "High-level convenience macro for opening a window (given the optional window parameters),
406 setting the title given,
407 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
408 The loop is in a block named do-open-window [so can be exited by a call to (return-from glfw:do-window)].
409 If the window is closed, the loop is also exited."
411 ,@setup-forms
414 ,@forms
422 "High-level convenience macro for initializing glfw, opening a window (given the optional window parameters),
423 setting the title given,
424 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
425 The loop is in a block named do-window [so can be exited by a call to (return-from glfw:do-window)].
426 If the window is closed, the loop is also exited."
430 (defmacro define-callback-setter (c-name callback-prefix return-type (&body args) &key before-form after-form documentation)
440 ,before-form
447 All callback setting functions can take either a pointer to a C function,
448 a function object, a function symbol, or nil to clear the callback function.
450 THIS CALLBACK FUNCTION
464 (t (error "Not an acceptable callback. Must be foreign pointer, function object, function's symbol, or nil.")))))))
468 :documentation
469 "
470 Function that will be called when a user requests that the window should be
471 closed, typically by clicking the window close icon (e.g. the cross in the upper right corner of a
472 window under Microsoft Windows). The function should have the following type:
473 (function () integer)
475 The return value of the callback function indicates whether or not the window close action should continue. If the function returns
476 gl:+true+, the window will be closed. If the function returns gl:+false+, the window will not
477 be closed. If you give a CFFI callback returning glfw:boolean, you can use t and nil as return types.
479 Notes
480 Window close events are recorded continuously, but only reported when glfwPollEvents,
481 glfwWaitEvents or glfwSwapBuffers is called.
482 The OpenGL context is still valid when this function is called.
483 Note that the window close callback function is not called when glfwCloseWindow is called, but only
484 when the close request comes from the window manager.
485 Do not call glfwCloseWindow from a window close callback function. Close the window by returning
486 gl:+true+ from the function.
491 "Parameters
492 title
493 Pointer to a null terminated ISO 8859-1 (8-bit Latin 1) string that holds the title of the window.
495 Description
496 The function changes the title of the opened window.
498 Notes
499 The title property of a window is often used in situations other
500 than for the window title, such as the title of an application icon
504 "Parameters
505 width
506 Width of the window.
507 height
508 Height of the window.
509 Return values
510 none
511 Description
513 The function changes the size of an opened window. The width and
514 height parameters denote the size of the client area of the
515 window (i.e. excluding any window borders and decorations). If the
516 window is in fullscreen mode, the video mode will be changed to a
517 resolution that closest matches the width and height parameters (the
518 number of color bits will not be changed).
520 Notes
522 The OpenGL context is guaranteed to be preserved after calling glfwSetWindowSize, even if the
523 video mode is changed.
527 "Parameters
528 x
529 Horizontal position of the window, relative to the upper left corner of the desktop.
530 y
531 Vertical position of the window, relative to the upper left corner of the desktop.
532 Return values
533 none
534 Description
535 The function changes the position of an opened window. It does not have any effect on a fullscreen
536 window.
541 "The function is used for determining the size of an opened window. The returned values are dimensions
542 of the client area of the window (i.e. excluding any window borders and decorations).
543 (list width height)"
550 (define-callback-setter "glfwSetWindowSizeCallback" #:window-size :void ((width :int) (height :int))
551 :documentation
552 "
553 Function that will be called every time the window size changes. The
554 function should takes the arguments (width height) giving the new width and height of the window client area.
556 A window has to be opened for this function to have any effect.
557 Notes
558 Window size changes are recorded continuously, but only reported when glfwPollEvents,
562 "Iconify a window. If the window is in fullscreen mode, then the desktop video mode will be restored.")
565 "Restore an iconified window. If the window that is restored is in fullscreen mode, then the fullscreen
569 "Parameters
570 param
571 A token selecting which parameter the function should return (see table 3.2).
573 Return values
575 The function returns different parameters depending on the value of
576 param. Table 3.2 lists valid param values, and their corresponding
577 return values.
579 Description
580 The function is used for acquiring various properties of an opened window.
582 Notes: GLFW_ACCELERATED is only supported under Windows. Other systems
583 will always return GL_TRUE. Under Windows, GLFW_ACCELERATED means that
584 the OpenGL renderer is a 3rd party renderer, rather than the fallback
585 Microsoft software OpenGL renderer. In other words, it is not a real
586 guarantee that the OpenGL renderer is actually hardware accelerated.
590 "The function swaps the back and front color buffers of the window. If +AUTO_POLL_EVENTS+
591 is enabled (which is the default), glfwPollEvents is called before swapping the front and back buffers.")
595 "Parameters
596 interval
597 Minimum number of monitor vertical retraces between each buffer swap performed by
598 glfwSwapBuffers. If interval is zero, buffer swaps will not be synchronized to the vertical
599 refresh of the monitor (also known as VSync off).
601 Description
603 The function selects the minimum number of monitor vertical retraces
604 that should occur between two buffer swaps. If the selected swap
605 interval is one, the rate of buffer swaps will never be higher than
606 the vertical refresh rate of the monitor. If the selected swap
607 interval is zero, the rate of buffer swaps is only limited by the
608 speed of the software and the hardware.
610 Notes
612 This function will only have an effect on hardware and drivers that
617 :documentation
618 "
619 Function that will be called when the window client area needs to be
620 refreshed. The function takes no arguments and returns nothing (void).
622 Description
624 The function selects which function to be called upon a window refresh
625 event, which occurs when any part of the window client area has been
626 damaged, and needs to be repainted (for instance, if a part of the
627 window that was previously occluded by another window has become
628 visible). A window has to be opened for this function to have any
629 effect.
631 Notes
632 Window refresh events are recorded continuously, but only reported when glfwPollEvents,
633 glfwWaitEvents or glfwSwapBuffers is called.
646 "Parameters
647 maxcount
648 Maximum number of video modes that list vector can hold.
650 Return values
651 The function returns the number of detected video modes (this number will never exceed maxcount).
652 The list vector is filled out with the video modes that are supported by the system.
654 Description
655 The function returns a list of supported video modes. Each video mode is represented by a
656 list of the form:
657 (width height redbits greenbits bluebits)
659 Notes
660 The returned list is sorted, first by color depth (RedBits + GreenBits + BlueBits), and then by
661 resolution (Width * Height), with the lowest resolution, fewest bits per pixel mode first. "
666 collecting
676 "Parameters
677 mode
678 Pointer to a GLFWvidmode structure, which will be filled out by the function.
679 Return values
680 The GLFWvidmode structure pointed to by mode is filled out with the desktop video mode.
681 Description
682 The function returns the desktop video mode in a GLFWvidmode structure. See glfwGetVideoModes
683 for a definition of the GLFWvidmode structure.
684 Notes
685 The color depth of the desktop display is always reported as the number of bits for each individual color
686 component (red, green and blue), even if the desktop is not using an RGB or RGBA color format. For
687 instance, an indexed 256 color display may report RedBits = 3, GreenBits = 3 and BlueBits = 2, which
688 adds up to 8 bits in total.
689 The desktop video mode is the video mode used by the desktop, not the current video mode (which may
690 differ from the desktop video mode if the GLFW window is a fullscreen window).
691 "
701 "Description
702 The function is used for polling for events, such as user input and window resize events. Upon calling
703 this function, all window states, keyboard states and mouse states are updated. If any related callback
704 functions are registered, these are called during the call to glfwPollEvents.
706 Notes
707 glfwPollEvents is called implicitly from glfwSwapBuffers if +AUTO_POLL_EVENTS+ is
708 enabled (default). Thus, if glfwSwapBuffers is called frequently, which is normally the case, there is
709 no need to call glfwPollEvents.
713 "Description
714 The function is used for waiting for events, such as user input and window resize events. Upon calling
715 this function, the calling thread will be put to sleep until any event appears in the event queue. When
716 events are ready, the events will be processed just as they are processed by glfwPollEvents.
717 If there are any events in the queue when the function is called, the function will behave exactly like
718 glfwPollEvents (i.e. process all messages and then return, without blocking the calling thread).
720 Notes
721 It is guaranteed that glfwWaitEvents will wake up on any event that can be processed by
722 glfw::PollEvents. However, glfwWaitEvents may wake up on events that are not processed or reported
723 by glfw::PollEvents too, and the function may behave differently on different systems. Do no make any
724 assumptions about when or why glfw::WaitEvents will return.
730 (loop for special-key in '("backspace" "del" "down" "end" "enter" "esc" "f1" "f10" "f11" "f12" "f13"
738 collect
739 `(,(symbol-value (find-symbol (string-upcase (format nil "+key-~a+" special-key)) (find-package '#:glfw)))
745 "Convert key-int from GLFW's integer representation to lisp characters if from 0 to 255, or keywords, if not within 0-255 inclusive."
752 "Parameters
753 key
754 A keyboard key identifier, which can be either an uppercase printable ISO 8859-1 (Latin 1)
755 character (e.g. 'A', '3' or '.'), or a special key identifier. Table 3.3 lists valid special key
756 identifiers.
757 Return values
758 The function returns +PRESS+ if the key is held down, or +RELEASE+ if the key is not
759 held down.
761 Description
762 The function queries the current state of a specific keyboard key. The physical location of each key
763 depends on the system keyboard layout setting.
765 Notes
766 The constant +KEY_SPACE+ is equal to 32, which is the ISO 8859-1 code for space.
767 Not all key codes are supported on all systems. Also, while some keys are available on some keyboard
768 layouts, they may not be available on other keyboard layouts.
769 For systems that do not distinguish between left and right versions of modifier keys (shift, alt and
770 control), the left version is used (e.g. +KEY_LSHIFT+)
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 keyboard events are recorded and reported by
773 glfw::GetKey.
778 "Convert button-int from GLFW's integer representation to a lisp keyword."
791 "Parameters
792 button
793 A mouse button identifier, which can be one of the mouse button identifiers listed in table 3.4.
794 Return values
795 The function returns +PRESS+ if the mouse button is held down, or +RELEASE+ if the
796 mouse button is not held down.
797 Description
798 The function queries the current state of a specific mouse button.
799 Notes
800 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
801 glfw::SwapBuffers must be called before any mouse button events are recorded and reported by
802 glfw::GetMouseButton.
803 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
804 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
805 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
810 "Return values
811 The function returns the current mouse position in xpos and ypos.
813 Description
814 The function returns the current mouse position. If the cursor is not hidden, the mouse position is the
815 cursor position, relative to the upper left corner of the window and limited to the client area of the
816 window. If the cursor is hidden, the mouse position is a virtual absolute position, not limited to any
817 boundaries except to those implied by the maximum number that can be represented by a signed integer
818 (normally -2147483648 to +2147483647).
820 Notes
821 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
822 glfw::SwapBuffers must be called before any mouse movements are recorded and reported by
823 glfw::GetMousePos.
828 "Parameters
829 xpos
830 Horizontal position of the mouse.
831 ypos
832 Vertical position of the mouse.
834 Description
835 The function changes the position of the mouse. If the cursor is visible (not disabled), the cursor will be
836 moved to the specified position, relative to the upper left corner of the window client area. If the cursor
837 is hidden (disabled), only the mouse position that is reported by GLFW is changed.
841 "Return values
842 The function returns the current mouse wheel position.
843 Description
844 The function returns the current mouse wheel position. The mouse wheel can be thought of as a third
845 mouse axis, which is available as a separate wheel or up/down stick on some mice.
846 Notes
847 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
848 glfw::SwapBuffers must be called before any mouse wheel movements are recorded and reported by
849 glfw::GetMouseWheel.
853 "Parameters
854 pos
855 Position of the mouse wheel.
856 Description
857 The function changes the position of the mouse wheel.
863 :documentation
864 "
865 Function that will be called every time a key is pressed or released.
866 Function should take the arguments (key action), where key is either a character,
867 if the key pressed was a member of iso-8859-1, or a keyword representing the key pressed if not.
868 See the GLFW manual, table 3.3 for special key identifiers. Action is either glfw:+press+ or
869 glfw:+release+. Use set-char-callback instead if you want to read just characters.
871 Description
872 The function selects which function to be called upon a keyboard key event. The callback function is
873 called every time the state of a single key is changed (from released to pressed or vice versa). The
874 reported keys are unaffected by any modifiers (such as shift or alt).
875 A window has to be opened for this function to have any effect.
877 Notes
878 Keyboard events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
879 or glfw::SwapBuffers is called.
883 :documentation
884 "
885 Function that will be called every time a printable character is generated by
886 the keyboard. The function should take the arguments (character action)
887 where character is a lisp character and action is either glfw:+press+ or glfw:+release+.
889 NB this makes the presumption that your lisp implementation will use Unicode for code-char.
891 Description
892 The function selects which function to be called upon a keyboard character event. The callback function
893 is called every time a key that results in a printable Unicode character is pressed or released. Characters
894 are affected by modifiers (such as shift or alt).
895 A window has to be opened for this function to have any effect.
897 Notes
898 Character events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
899 or glfw::SwapBuffers is called.
900 Control characters, such as tab and carriage return, are not reported to the character callback function,
901 since they are not part of the Unicode character set. Use the key callback function for such events (see
902 glfw::SetKeyCallback).
903 The Unicode character set supports character codes above 255, so never cast a Unicode character to an
904 eight bit data type (e.g. the C language char type) without first checking that the character code is less
905 than 256. Also note that Unicode character codes 0 to 255 are equal to ISO 8859-1 (Latin 1).
908 (define-callback-setter "glfwSetMouseButtonCallback" #:mouse-button :void ((button :int) (action :int))
910 :documentation
911 "
912 Function that will be called every time a mouse button is pressed or released.
913 The function takes the arguments (button action), where button is a keyword symbol as returned by
914 lispify-mouse-button and action is either glfw:+press+ or glfw:+release+.
916 Description
917 The function selects which function to be called upon a mouse button event.
918 A window has to be opened for this function to have any effect.
920 Notes
921 Mouse button events are recorded continuously, but only reported when glfw::PollEvents,
922 glfw::WaitEvents or glfw::SwapBuffers is called.
923 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
924 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
925 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
928 :documentation
929 "
930 Function that will be called every time the mouse is moved.
931 The function takes the arguments (x y), where x and y are the current position of the mouse.
933 Description
934 The function selects which function to be called upon a mouse motion event.
935 A window has to be opened for this function to have any effect.
937 Notes
938 Mouse motion events are recorded continuously, but only reported when glfw::PollEvents,
939 glfw::WaitEvents or glfw::SwapBuffers is called.
945 :documentation
946 "
947 Function that will be called every time the mouse wheel is moved.
948 The function takes one argument: the position of the mouse wheel.
949 This DIFFERS FROM GLFW's DEFAULT behaviour in that the position is
950 reset after every call to this function, effectively giving the delta.
951 As most programs are only interested in the delta anyway, this is thought
952 to save others recording the state of it again.
953 If you wish to have the original GLFW behaviour, set cl-glfw:*mouse-wheel-cumulative* to t.
955 Description
956 The function selects which function to be called upon a mouse wheel event.
957 A window has to be opened for this function to have any effect.
958 Notes
959 Mouse wheel events are recorded continuously, but only reported when glfw::PollEvents,
960 glfw::WaitEvents or glfw::SwapBuffers is called.
964 "Parameters
965 joy
966 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
967 param
968 A token selecting which parameter the function should return (see table 3.5).
969 Return values
970 The function returns different parameters depending on the value of param. Table 3.5 lists valid param
971 values, and their corresponding return values.
972 Description
973 The function is used for acquiring various properties of a joystick.
974 Notes
975 The joystick information is updated every time the function is called.
976 No window has to be opened for joystick information to be valid.
979 (defcfun ("glfwGetJoystickPos" %get-joystick-pos) :int (joy :int) (pos :pointer) (numaxes :int))
982 "Parameters
983 joy
984 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
985 numaxes
986 Specifies how many axes should be returned.
987 Return values
988 An list that will hold the positional values for all requested axes.
989 If the joystick is not supported or connected, the function will
990 return nil.
992 Description
993 The function queries the current position of one or more axes of a joystick. The positional values are
994 returned in an array, where the first element represents the first axis of the joystick (normally the X
995 axis). Each position is in the range -1.0 to 1.0. Where applicable, the positive direction of an axis is
996 right, forward or up, and the negative direction is left, back or down.
997 If numaxes exceeds the number of axes supported by the joystick, or if the joystick is not available, the
998 unused elements in the pos array will be set to 0.0 (zero).
1000 Notes
1001 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
1002 or glfw::WaitEvents for joystick state to be updated.
1003 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
1004 supported axes.
1005 No window has to be opened for joystick input to be valid.
1006 "
1012 (defcfun ("glfwGetJoystickButtons" %get-joystick-buttons) :int (joy :int) (buttons :pointer) (numbuttons :int))
1014 "Parameters
1015 joy
1016 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
1017 numbuttons
1018 Specifies how many buttons should be returned.
1019 Return values
1020 A list that will hold the button states for all requested buttons.
1021 The function returns the number of actually returned buttons. This is the minimum of numbuttons and
1022 the number of buttons supported by the joystick. If the joystick is not supported or connected, the
1023 function will return 0 (zero).
1025 Description
1026 The function queries the current state of one or more buttons of a joystick. The button states are
1027 returned in an array, where the first element represents the first button of the joystick. Each state can be
1028 either +PRESS+ or +RELEASE+
1029 If numbuttons exceeds the number of buttons supported by the joystick, or if the joystick is not
1030 available, the unused elements in the buttons array will be set to +RELEASE+
1032 Notes
1033 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
1034 or glfw::WaitEvents for joystick state to be updated.
1035 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
1036 supported buttons.
1037 No window has to be opened for joystick input to be valid.
1038 "
1045 "Return values
1046 The function returns the value of the high precision timer. The time is measured in seconds, and is
1047 returned as a double precision floating point value.
1049 Description
1050 The function returns the state of a high precision timer. Unless the timer has been set by the
1051 glfw::SetTime function, the time is measured as the number of seconds that have passed since glfw::Init
1052 was called.
1054 Notes
1055 The resolution of the timer depends on which system the program is running on. The worst case
1056 resolution is somewhere in the order of 10 ms, while for most systems the resolution should be better
1057 than 1us.
1061 "Parameters
1062 time
1063 Time (in seconds) that the timer should be set to.
1065 Description
1066 The function sets the current time of the high precision timer to the specified time. Subsequent calls to
1067 glfw::GetTime will be relative to this time. The time is given in seconds.
1071 "Parameters
1072 time
1073 Time, in seconds, to sleep.
1075 Description
1076 The function puts the calling thread to sleep for the requested period of time. Only the calling thread is
1077 put to sleep. Other threads within the same process can still execute.
1079 Notes
1080 There is usually a system dependent minimum time for which it is possible to sleep. This time is
1081 generally in the range 1 ms to 20 ms, depending on thread sheduling time slot intervals etc. Using a
1082 shorter time as a parameter to glfw::Sleep can give one of two results: either the thread will sleep for the
1083 minimum possible sleep time, or the thread will not sleep at all (glfw::Sleep returns immediately). The
1095 "Parameters
1096 name
1097 A null terminated ISO 8859-1 string holding the name of the file that should be read.
1098 img
1099 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1100 read was successful).
1101 flags
1102 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1103 Return values
1104 The function returns t if the image was loaded successfully. Otherwise nil is
1105 returned.
1106 Description
1107 The function reads an image from the file specified by the parameter name and returns the image
1108 information and data in a GLFWimage structure, which has the following definition:
1110 typedef struct {
1111 int Width, Height; // Image dimensions
1112 int Format; // OpenGL pixel format
1113 int BytesPerPixel; // Number of bytes per pixel
1114 unsigned char *Data; // Pointer to pixel data
1115 } GLFWimage;
1117 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1118 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1119 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1121 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1122 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1123 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1124 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1125 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1126 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1128 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1129 Notes
1130 glfw::ReadImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel formats
1131 are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color + alpha.
1132 Paletted images are translated into true color or true color + alpha pixel formats.
1133 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1134 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1139 "Parameters
1140 data
1141 The memory buffer holding the contents of the file that should be read.
1142 size
1143 The size, in bytes, of the memory buffer.
1144 img
1145 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1146 read was successful).
1147 flags
1148 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1149 Return values
1150 The function returns t if the image was loaded successfully. Otherwise nil is
1151 returned.
1152 Description
1153 The function reads an image from the memory buffer specified by the parameter data and returns the
1154 image information and data in a GLFWimage structure, which has the following definition:
1156 typedef struct {
1157 int Width, Height; // Image dimensions
1158 int Format; // OpenGL pixel format
1159 int BytesPerPixel; // Number of bytes per pixel
1160 unsigned char *Data; // Pointer to pixel data
1161 } GLFWimage;
1163 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1164 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1165 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1167 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1168 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1169 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1170 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1171 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1172 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1173 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1174 Notes
1175 glfw::ReadMemoryImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1176 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1177 alpha.
1178 Paletted images are translated into true color or true color + alpha pixel formats.
1179 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1180 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1184 "Parameters
1185 img
1186 Pointer to a GLFWimage struct.
1187 Description
1188 The function frees any memory occupied by a loaded image, and clears all the fields of the GLFWimage
1189 struct. Any image that has been loaded by the glfw::ReadImage function should be deallocated using
1193 "Parameters
1194 name
1195 An ISO 8859-1 string holding the name of the file that should be loaded.
1196 flags
1197 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1198 Return values
1199 The function returns t if the texture was loaded successfully. Otherwise nil is
1200 returned.
1202 Description
1204 The function reads an image from the file specified by the parameter
1205 name and uploads the image to OpenGL texture memory (using the
1206 glTexImage2D function). If the GLFW_BUILD_MIPMAPS_BIT flag is set,
1207 all mipmap levels for the loaded texture are generated and uploaded to
1208 texture memory. Unless the flag +ORIGIN_UL_BIT+ is set, the origin of
1209 the texture is the lower left corner of the loaded image. If the flag
1210 +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1211 corner. For single component images (i.e. gray scale), the texture is
1212 uploaded as an alpha mask if the flag +ALPHA_MAP_BIT+ flag is set,
1213 otherwise it is uploaded as a luminance texture.
1215 Notes
1216 glfw::LoadTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1217 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1218 alpha.
1219 Paletted images are translated into true color or true color + alpha pixel formats.
1220 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1221 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1222 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1223 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1224 generated by GLFW in software.
1226 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1227 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1228 texture is a single component texture. The red, green and blue components are set to 1.0.
1233 "Parameters
1234 data
1235 The memory buffer holding the contents of the file that should be loaded.
1236 size
1237 The size, in bytes, of the memory buffer.
1238 flags
1239 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1240 Return values
1241 The function returns t if the texture was loaded successfully. Otherwise nil is
1242 returned.
1244 Description
1245 The function reads an image from the memory buffer specified by the parameter data and uploads the
1246 image to OpenGL texture memory (using the glTexImage2D function).
1247 If the GLFW_BUILD_MIPMAPS_BIT flag is set, all mipmap levels for the loaded texture are
1248 generated and uploaded to texture memory.
1249 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1250 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1251 corner.
1252 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1253 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1255 Notes
1256 glfw::LoadMemoryTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported
1257 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1258 + alpha.
1259 Paletted images are translated into true color or true color + alpha pixel formats.
1260 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1261 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1262 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1263 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1264 generated by GLFW in software.
1266 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1267 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1268 texture is a single component texture. The red, green and blue components are set to 1.0.
1274 "Parameters
1275 img
1276 Pointer to a GLFWimage struct holding the information about the image to be loaded.
1277 flags
1278 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1279 Return values
1280 The function returns t if the texture was loaded successfully. Otherwise nil is
1281 returned.
1283 Description
1284 The function uploads the image specified by the parameter img to OpenGL texture memory (using
1285 the glTexImage2D function).
1286 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1287 generated and uploaded to texture memory.
1288 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1289 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1290 corner.
1291 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1292 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1294 Notes
1295 glfw::LoadTextureImage2D supports the Truevision Targa version 1 file format (.TGA). Supported
1296 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1297 + alpha.
1298 Paletted images are translated into true color or true color + alpha pixel formats.
1299 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1300 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1301 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1302 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1303 generated by GLFW in software.
1305 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1306 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1311 "Parameters
1312 extension
1313 A null terminated ISO 8859-1 string containing the name of an OpenGL extension.
1314 Return values
1315 The function returns t if the extension is supported. Otherwise it returns nil.
1316 Description
1317 The function does a string search in the list of supported OpenGL extensions to find if the specified
1318 extension is listed.
1319 Notes
1321 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1322 must have been opened with glfwOpenWindow).
1323 In addition to checking for OpenGL extensions, GLFW also checks for extensions in the operating
1324 system ?glue API?, such as WGL extensions under Windows and glX extensions under the X Window
1325 System.
1329 "Parameters
1330 procname
1331 A null terminated ISO 8859-1 string containing the name of an OpenGL extension function.
1332 Return values
1333 The function returns the pointer to the specified OpenGL function if it is supported, otherwise
1334 NULL is returned.
1335 Description
1336 The function acquires the pointer to an OpenGL extension function. Some (but not all) OpenGL
1337 extensions define new API functions, which are usually not available through normal linking. It is
1338 therefore necessary to get access to those API functions at runtime.
1339 Notes
1341 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1342 must have been opened with glfwOpenWindow).
1343 Some systems do not support dynamic function pointer retrieval, in which case glfwGetProcAddress
1344 will always return NULL.
1350 "Return values
1351 The function returns the major and minor version numbers and the revision for the currently used
1352 OpenGL implementation as a list (major minor rev).
1354 Description
1355 The function returns the OpenGL implementation version. This is a convenient function that parses
1356 the version number information from the string returned by calling
1357 glGetString( GL_VERSION ). The OpenGL version information can be used to determine
1358 what functionality is supported by the used OpenGL implementation.
1360 Notes
1361 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1370 "Parameters
1371 fun
1372 A pointer to a function that acts as the entry point for the new thread. The function should have
1373 the following C language prototype:
1374 void GLFWCALL functionname( void *arg );
1375 Where functionname is the name of the thread function, and arg is the user supplied argument
1376 (see below).
1377 arg
1378 An arbitrary argument for the thread. arg will be passed as the argument to the thread function
1379 pointed to by fun. For instance, arg can point to data that is to be processed by the thread.
1380 Return values
1381 The function returns a thread identification number if the thread was created successfully. This number
1382 is always positive. If the function fails, a negative number is returned.
1383 Description
1384 The function creates a new thread, which executes within the same address space as the calling process.
1385 The thread entry point is specified with the fun argument.
1386 Once the thread function fun returns, the thread dies.
1387 Notes
1388 Even if the function returns a positive thread ID, indicating that the thread was created successfully, the
1389 thread may be unable to execute, for instance if the thread start address is not a valid thread entry point.
1392 "Parameters
1393 ID
1394 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1395 Description
1396 The function kills a running thread and removes it from the thread list.
1397 Notes
1398 This function is a very dangerous operation, which may interrupt a thread in the middle of an important
1399 operation, and its use is discouraged. You should always try to end a thread in a graceful way using
1400 thread communication, and use glfw::WaitThread in order to wait for the thread to die.
1403 "Parameters
1404 ID
1405 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1406 waitmode
1407 Can be either +WAIT+ or +NOWAIT+
1408 Return values
1409 The function returns t if the specified thread died after the function was called, or the thread
1410 did not exist, in which case glfw::WaitThread will return immediately regardless of waitmode. The
1411 function returns nil if waitmode is +NOWAIT+ and the specified thread exists and is still
1412 running.
1415 "Return values
1416 The function returns a thread identification handle for the calling thread.
1417 Description
1418 The function determines the thread ID for the calling thread. The ID is the same value as was returned
1419 by glfw::CreateThread when the thread was created.
1423 "Return values
1424 The function returns a mutex handle, or NULL if the mutex could not be created.
1425 Description
1426 The function creates a mutex object, which can be used to control access to data that is shared between
1427 threads.
1430 "Parameters
1431 mutex
1432 A mutex object handle.
1433 Description
1434 The function destroys a mutex object. After a mutex object has been destroyed, it may no longer be
1435 used by any thread.
1438 "Parameters
1439 mutex
1440 A mutex object handle.
1441 Description
1442 The function will acquire a lock on the selected mutex object. If the mutex is already locked by another
1443 thread, the function will block the calling thread until it is released by the locking thread. Once the
1444 function returns, the calling thread has an exclusive lock on the mutex. To release the mutex, call
1445 glfw::UnlockMutex.
1448 "Parameters
1449 mutex
1450 A mutex object handle.
1451 Description
1452 The function releases the lock of a locked mutex object.
1456 "Parameters
1457 mutex
1458 A mutex object handle.
1459 forms
1460 Body of code to execute
1461 Description
1462 This macro will acquire a lock on the selected mutex object using glfw::LockMutex and release it afterwards
1463 using glfw::UnlockMutex.
1464 So, forms will not execute until an exclusive lock is held.
1465 The lock is then released when the stack is unwound."
1473 "Return values
1474 The function returns a condition variable handle, or NULL if the condition variable could not be
1475 created.
1476 Description
1477 The function creates a condition variable object, which can be used to synchronize threads.
1480 "Parameters
1481 cond
1482 A condition variable object handle.
1483 Description
1484 The function destroys a condition variable object. After a condition variable object has been destroyed,
1485 it may no longer be used by any thread.
1488 " arameters
1489 cond
1490 A condition variable object handle.
1491 mutex
1492 A mutex object handle.
1493 timeout
1494 Maximum time to wait for the condition variable. The parameter can either be a positive time (in
1495 seconds), or +INFINITY+
1496 Description
1497 The function atomically unlocks the mutex specified by mutex, and waits for the condition variable cond
1498 to be signaled. The thread execution is suspended and does not consume any CPU time until the
1499 condition variable is signaled or the amount of time specified by timeout has passed. If timeout is
1500 +INFINITY+ glfw::WaitCond will wait forever for cond to be signaled. Before returning to the
1501 calling thread, glfw::WaitCond automatically re-acquires the mutex.
1502 Notes
1503 The mutex specified by mutex must be locked by the calling thread before entrance to glfw::WaitCond.
1504 A condition variable must always be associated with a mutex, to avoid the race condition where a thread
1505 prepares to wait on a condition variable and another thread signals the condition just before the first
1506 thread actually waits on it.
1509 "Parameters
1510 cond
1511 A condition variable object handle.
1512 Description
1513 The function restarts one of the threads that are waiting on the condition variable cond. If no threads are
1514 waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it
1515 is not specified which.
1516 Notes
1517 When several threads are waiting for the condition variable, which thread is started depends on
1518 operating system scheduling rules, and may vary from system to system and from time to time.
1521 "Parameters
1522 cond
1523 A condition variable object handle.
1524 Description
1525 The function restarts all the threads that are waiting on the condition variable cond. If no threads are
1526 waiting on cond, nothing happens.
1527 Notes
1528 When several threads are waiting for the condition variable, the order in which threads are started
1529 depends on operating system scheduling rules, and may vary from system to system and from time to
1530 time.
1534 "Return values
1535 The function returns the number of active processors in the system.
1536 Description
1537 The function determines the number of active processors in the system.
1538 Notes
1539 Systems with several logical processors per physical processor, also known as SMT (Symmetric Multi
1540 Threading) processors, will report the number of logical processors.
1543 "Parameters
1544 token
1545 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1546 Return values
1547 none
1548 Description
1549 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1550 description of each feature.
1551 +AUTO_POLL_EVENTS+
1552 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1553 that glfw::SwapBuffers is called.
1554 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1555 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1556 function, since calling glfw::PollEvents from a callback function is not allowed.
1557 +KEY_REPEAT+
1558 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1559 when a key is held down long enough (according to the system key repeat configuration).
1560 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1561 when a key is pressed (and once when it is released).
1562 +MOUSE_CURSOR+
1563 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1564 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1565 the client area of the window.
1566 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1567 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1568 from the mouse, without being restricted or manipulated by the windowing system.
1569 +STICKY_KEYS+
1570 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1571 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1572 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1573 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1574 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1575 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1576 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfw::GetKey is always
1577 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1578 all keys.
1579 +STICKY_MOUSE_BUTTONS+
1580 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1581 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1582 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1583 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1584 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1585 glfw::GetMouseButton will never be released. Note also that enabling
1586 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1587 functionality.
1588 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1589 by glfw::GetMouseButton is always the physical state of the mouse button. Disabling
1590 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1591 +SYSTEM_KEYS+
1592 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1593 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1594 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1595 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1596 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1597 the GLFW video mode again.
1598 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1599 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1600 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1603 "Parameters
1604 token
1605 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1606 Return values
1607 none
1608 Description
1609 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1610 description of each feature.
1611 +AUTO_POLL_EVENTS+
1612 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1613 that glfw::SwapBuffers is called.
1614 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1615 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1616 function, since calling glfw::PollEvents from a callback function is not allowed.
1617 +KEY_REPEAT+
1618 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1619 when a key is held down long enough (according to the system key repeat configuration).
1620 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1621 when a key is pressed (and once when it is released).
1622 +MOUSE_CURSOR+
1623 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1624 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1625 the client area of the window.
1626 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1627 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1628 from the mouse, without being restricted or manipulated by the windowing system.
1629 +STICKY_KEYS+
1630 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1631 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1632 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1633 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1634 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1635 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1636 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfwGetKey is always
1637 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1638 all keys.
1639 +STICKY_MOUSE_BUTTONS+
1640 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1641 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1642 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1643 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1644 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1645 glfw::GetMouseButton will never be released. Note also that enabling
1646 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1647 functionality.
1648 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1649 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1650 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1651 +SYSTEM_KEYS+
1652 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1653 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1654 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1655 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1656 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1657 the GLFW video mode again.
1658 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1659 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1660 the GLFW program must not be interrupted (normally for games in fullscreen mode).