b4ece500b8c756bd25b3aa3758176e9c34fc2b52
| blob | b4ece500b8c756bd25b3aa3758176e9c34fc2b52 |
7 ;; Key and button state/action definitions
11 ;; Keyboard key definitions: 8-bit ISO-8859-1 (Latin 1) encoding is used
12 ;; for printable keys (such as A-Z, 0-9 etc), and values above 256
13 ;; represent special (non-printable) keys (e.g. F1, Page Up etc).
81 ;; Mouse button definitions
92 ;; Mouse button aliases
97 ;; Joystick identifiers
117 ;;========================================================================
118 ;; Other definitions
119 ;;========================================================================
121 ;; glfwOpenWindow modes
125 ;; glfwGetWindowParam tokens
137 ;; The following constants are used for both glfwGetWindowParam
138 ;; and glfwOpenWindowHint
149 ;; glfwEnable/glfwDisable tokens
157 ;; glfwWaitThread wait modes
161 ;; glfwGetJoystickParam tokens
166 ;; glfwReadImage/glfwLoadTexture2D flags
172 ;; Time spans longer than this (seconds) are considered to be infinity
188 "Return values
189 If the function succeeds, t is returned.
190 If the function fails, nil is returned.
192 The glfwInit function initializes GLFW. No other GLFW functions may be used before this function
193 has been called.
195 On successful initialization, the list of functions in *init-hooks* is called.
197 Notes
198 This function may take several seconds to complete on some systems, while on other systems it may
199 take only a fraction of a second to complete."
203 t))
208 "The function terminates GLFW. Among other things it closes the window, if it is opened, and kills any
209 running threads. This function must be called before a program exits.
211 Before termination, the list of functions in *terminate-hooks* is called.
212 "
220 "Return values
221 The function returns the major and minor version numbers and the revision for the currently linked
225 "Call glfw:init, execute forms and clean-up with glfw:terminate once finished.
226 This makes a nice wrapper to an application higher-level form.
227 Signals an error on failure to initialize. Wrapped in a block named glfw:with-init."
243 "width
244 The width of the window. If width is zero, it will be calculated as width = 4/3 height, if height is
245 not zero. If both width and height are zero, then width will be set to 640.
246 height
247 The height of the window. If height is zero, it will be calculated as height = 3/4 width, if width is
248 not zero. If both width and height are zero, then height will be set to 480.
249 redbits, greenbits, bluebits
250 The number of bits to use for each color component of the color buffer (0 means default color
251 depth). For instance, setting redbits=5, greenbits=6, and bluebits=5 will generate a 16-bit color
252 buffer, if possible.
253 alphabits
254 The number of bits to use for the alpha buffer (0 means no alpha buffer).
255 depthbits
256 The number of bits to use for the depth buffer (0 means no depth buffer).
257 stencilbits
258 The number of bits to use for the stencil buffer (0 means no stencil buffer).
259 mode
260 Selects which type of OpenGL window to use. mode can be either +WINDOW+, which
261 will generate a normal desktop window, or +FULLSCREEN+ which will generate a
262 window which covers the entire screen. When +FULLSCREEN+ is selected, the video
263 mode will be changed to the resolution that closest matches the width and height parameters.
265 Return values
266 If the function succeeds, t is returned.
267 If the function fails, nil is returned.
269 Description
271 The function opens a window that best matches the parameters given to
272 the function. How well the resulting window matches the desired window
273 depends mostly on the available hardware and OpenGL drivers. In
274 general, selecting a fullscreen mode has better chances of generating
275 a close match than does a normal desktop window, since GLFW can freely
276 select from all the available video modes. A desktop window is
277 normally restricted to the video mode of the desktop.
279 Notes
281 For additional control of window properties, see glfw::OpenWindowHint.
282 In fullscreen mode the mouse cursor is hidden by default, and any system screensavers are prohibited
283 from starting. In windowed mode the mouse cursor is visible, and screensavers are allowed to start. To
284 change the visibility of the mouse cursor, use glfwEnable or glfwDisable with the argument
285 +MOUSE_CURSOR+
286 In order to determine the actual properties of an opened window, use glfw::GetWindowParam and
287 glfw::GetWindowSize (or glfw::SetWindowSizeCallback).
288 "
294 "target
295 Can be any of the constants in the table 3.1.
296 hint
297 An integer giving the value of the corresponding target (see table 3.1).
299 Description
300 The function sets additional properties for a window that is to be opened. For a hint to be registered, the
301 function must be called before calling glfw::OpenWindow. When the glfw::OpenWindow function is
302 called, any hints that were registered with the glfw::OpenWindowHint function are used for setting the
303 corresponding window properties, and then all hints are reset to their default values.
305 Notes
306 In order to determine the actual properties of an opened window, use glfw::GetWindowParam (after the
307 window has been opened).
308 +STEREO+ is a hard constraint. If stereo rendering is requested, but no stereo rendering capable
309 pixel formats / visuals are available, glfw::OpenWindow will fail.
310 The +REFRESH_RATE+ property should be used with caution. Most systems have default values
311 for monitor refresh rates that are optimal for the specific system. Specifying the refresh rate can
312 override these settings, which can result in suboptimal operation. The monitor may be unable to display
313 the resulting video signal, or in the worst case it may even be damaged!
323 "Wraps forms such that there is an open window for them to execute in and cleans up the
324 window afterwards. An error is signalled if there was an error opening the window.
325 Takes the same parameters as open-window, with the addition of 'title' which will
326 set the window title after opening.
327 Wrapped in a block named glfw:with-open-window."
328 `(if (%open-window ,width ,height ,redbits ,greenbits ,bluebits ,alphabits ,depthbits ,stencilbits ,mode)
341 "Wraps forms in with-init, with-open-window. Passes through the other arguments to open-window."
343 (with-open-window (:title ,title :width ,width :height ,height :redbits ,redbits :greenbits ,greenbits :bluebits ,bluebits :alphabits ,alphabits :depthbits ,depthbits :stencilbits ,stencilbits :mode ,mode)
351 "High-level convenience macro for initializing glfw, opening a window (given the optional window parameters),
352 setting the title given,
353 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
354 The loop is in a block named do-window [so can be exited by a call to (return-from glfw:do-window)].
355 If the window is closed, the loop is also exited."
356 `(with-init-window (:title ,title :width ,width :height ,height :redbits ,redbits :greenbits ,greenbits :bluebits ,bluebits :alphabits ,alphabits :depthbits ,depthbits :stencilbits ,stencilbits :mode ,mode)
357 ,@setup-forms
359 ,@forms
364 (defmacro define-callback-setter (c-name callback-prefix return-type (&body args) &key before-form after-form documentation)
374 ,before-form
381 All callback setting functions can take either a pointer to a C function,
382 a function object, a function symbol, or nil to clear the callback function.
384 THIS CALLBACK FUNCTION
398 (t (error "Not an acceptable callback. Must be foreign pointer, function object, function's symbol, or nil.")))))))
402 :documentation
403 "
404 Function that will be called when a user requests that the window should be
405 closed, typically by clicking the window close icon (e.g. the cross in the upper right corner of a
406 window under Microsoft Windows). The function should have the following type:
407 (function () integer)
409 The return value of the callback function indicates whether or not the window close action should continue. If the function returns
410 gl:+true+, the window will be closed. If the function returns gl:+false+, the window will not
411 be closed. If you give a CFFI callback returning glfw:boolean, you can use t and nil as return types.
413 Notes
414 Window close events are recorded continuously, but only reported when glfwPollEvents,
415 glfwWaitEvents or glfwSwapBuffers is called.
416 The OpenGL context is still valid when this function is called.
417 Note that the window close callback function is not called when glfwCloseWindow is called, but only
418 when the close request comes from the window manager.
419 Do not call glfwCloseWindow from a window close callback function. Close the window by returning
420 gl:+true+ from the function.
425 "Parameters
426 title
427 Pointer to a null terminated ISO 8859-1 (8-bit Latin 1) string that holds the title of the window.
429 Description
430 The function changes the title of the opened window.
432 Notes
433 The title property of a window is often used in situations other
434 than for the window title, such as the title of an application icon
438 "Parameters
439 width
440 Width of the window.
441 height
442 Height of the window.
443 Return values
444 none
445 Description
447 The function changes the size of an opened window. The width and
448 height parameters denote the size of the client area of the
449 window (i.e. excluding any window borders and decorations). If the
450 window is in fullscreen mode, the video mode will be changed to a
451 resolution that closest matches the width and height parameters (the
452 number of color bits will not be changed).
454 Notes
456 The OpenGL context is guaranteed to be preserved after calling glfwSetWindowSize, even if the
457 video mode is changed.
461 "Parameters
462 x
463 Horizontal position of the window, relative to the upper left corner of the desktop.
464 y
465 Vertical position of the window, relative to the upper left corner of the desktop.
466 Return values
467 none
468 Description
469 The function changes the position of an opened window. It does not have any effect on a fullscreen
470 window.
475 "The function is used for determining the size of an opened window. The returned values are dimensions
476 of the client area of the window (i.e. excluding any window borders and decorations).
477 (list width height)"
484 (define-callback-setter "glfwSetWindowSizeCallback" #:window-size :void ((width :int) (height :int))
485 :documentation
486 "
487 Function that will be called every time the window size changes. The
488 function should takes the arguments (width height) giving the new width and height of the window client area.
490 A window has to be opened for this function to have any effect.
491 Notes
492 Window size changes are recorded continuously, but only reported when glfwPollEvents,
496 "Iconify a window. If the window is in fullscreen mode, then the desktop video mode will be restored.")
499 "Restore an iconified window. If the window that is restored is in fullscreen mode, then the fullscreen
503 "Parameters
504 param
505 A token selecting which parameter the function should return (see table 3.2).
507 Return values
509 The function returns different parameters depending on the value of
510 param. Table 3.2 lists valid param values, and their corresponding
511 return values.
513 Description
514 The function is used for acquiring various properties of an opened window.
516 Notes: GLFW_ACCELERATED is only supported under Windows. Other systems
517 will always return GL_TRUE. Under Windows, GLFW_ACCELERATED means that
518 the OpenGL renderer is a 3rd party renderer, rather than the fallback
519 Microsoft software OpenGL renderer. In other words, it is not a real
520 guarantee that the OpenGL renderer is actually hardware accelerated.
524 "The function swaps the back and front color buffers of the window. If +AUTO_POLL_EVENTS+
525 is enabled (which is the default), glfwPollEvents is called before swapping the front and back buffers.")
529 "Parameters
530 interval
531 Minimum number of monitor vertical retraces between each buffer swap performed by
532 glfwSwapBuffers. If interval is zero, buffer swaps will not be synchronized to the vertical
533 refresh of the monitor (also known as VSync off).
535 Description
537 The function selects the minimum number of monitor vertical retraces
538 that should occur between two buffer swaps. If the selected swap
539 interval is one, the rate of buffer swaps will never be higher than
540 the vertical refresh rate of the monitor. If the selected swap
541 interval is zero, the rate of buffer swaps is only limited by the
542 speed of the software and the hardware.
544 Notes
546 This function will only have an effect on hardware and drivers that
551 :documentation
552 "
553 Function that will be called when the window client area needs to be
554 refreshed. The function takes no arguments and returns nothing (void).
556 Description
558 The function selects which function to be called upon a window refresh
559 event, which occurs when any part of the window client area has been
560 damaged, and needs to be repainted (for instance, if a part of the
561 window that was previously occluded by another window has become
562 visible). A window has to be opened for this function to have any
563 effect.
565 Notes
566 Window refresh events are recorded continuously, but only reported when glfwPollEvents,
567 glfwWaitEvents or glfwSwapBuffers is called.
580 "Parameters
581 maxcount
582 Maximum number of video modes that list vector can hold.
584 Return values
585 The function returns the number of detected video modes (this number will never exceed maxcount).
586 The list vector is filled out with the video modes that are supported by the system.
588 Description
589 The function returns a list of supported video modes. Each video mode is represented by a
590 list of the form:
591 (width height redbits greenbits bluebits)
593 Notes
594 The returned list is sorted, first by color depth (RedBits + GreenBits + BlueBits), and then by
595 resolution (Width * Height), with the lowest resolution, fewest bits per pixel mode first. "
600 collecting
610 "Parameters
611 mode
612 Pointer to a GLFWvidmode structure, which will be filled out by the function.
613 Return values
614 The GLFWvidmode structure pointed to by mode is filled out with the desktop video mode.
615 Description
616 The function returns the desktop video mode in a GLFWvidmode structure. See glfwGetVideoModes
617 for a definition of the GLFWvidmode structure.
618 Notes
619 The color depth of the desktop display is always reported as the number of bits for each individual color
620 component (red, green and blue), even if the desktop is not using an RGB or RGBA color format. For
621 instance, an indexed 256 color display may report RedBits = 3, GreenBits = 3 and BlueBits = 2, which
622 adds up to 8 bits in total.
623 The desktop video mode is the video mode used by the desktop, not the current video mode (which may
624 differ from the desktop video mode if the GLFW window is a fullscreen window).
625 "
635 "Description
636 The function is used for polling for events, such as user input and window resize events. Upon calling
637 this function, all window states, keyboard states and mouse states are updated. If any related callback
638 functions are registered, these are called during the call to glfwPollEvents.
640 Notes
641 glfwPollEvents is called implicitly from glfwSwapBuffers if +AUTO_POLL_EVENTS+ is
642 enabled (default). Thus, if glfwSwapBuffers is called frequently, which is normally the case, there is
643 no need to call glfwPollEvents.
647 "Description
648 The function is used for waiting for events, such as user input and window resize events. Upon calling
649 this function, the calling thread will be put to sleep until any event appears in the event queue. When
650 events are ready, the events will be processed just as they are processed by glfwPollEvents.
651 If there are any events in the queue when the function is called, the function will behave exactly like
652 glfwPollEvents (i.e. process all messages and then return, without blocking the calling thread).
654 Notes
655 It is guaranteed that glfwWaitEvents will wake up on any event that can be processed by
656 glfw::PollEvents. However, glfwWaitEvents may wake up on events that are not processed or reported
657 by glfw::PollEvents too, and the function may behave differently on different systems. Do no make any
658 assumptions about when or why glfw::WaitEvents will return.
664 (loop for special-key in '("backspace" "del" "down" "end" "enter" "esc" "f1" "f10" "f11" "f12" "f13"
671 collect
672 `(,(symbol-value (find-symbol (string-upcase (format nil "+key-~a+" special-key)) (find-package '#:glfw)))
678 "Convert key-int from GLFW's integer representation to lisp characters if from 0 to 255, or keywords, if not within 0-255 inclusive."
685 "Parameters
686 key
687 A keyboard key identifier, which can be either an uppercase printable ISO 8859-1 (Latin 1)
688 character (e.g. 'A', '3' or '.'), or a special key identifier. Table 3.3 lists valid special key
689 identifiers.
690 Return values
691 The function returns +PRESS+ if the key is held down, or +RELEASE+ if the key is not
692 held down.
694 Description
695 The function queries the current state of a specific keyboard key. The physical location of each key
696 depends on the system keyboard layout setting.
698 Notes
699 The constant +KEY_SPACE+ is equal to 32, which is the ISO 8859-1 code for space.
700 Not all key codes are supported on all systems. Also, while some keys are available on some keyboard
701 layouts, they may not be available on other keyboard layouts.
702 For systems that do not distinguish between left and right versions of modifier keys (shift, alt and
703 control), the left version is used (e.g. +KEY_LSHIFT+)
704 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
705 glfw::SwapBuffers must be called before any keyboard events are recorded and reported by
706 glfw::GetKey.
711 "Convert button-int from GLFW's integer representation to a lisp keyword."
724 "Parameters
725 button
726 A mouse button identifier, which can be one of the mouse button identifiers listed in table 3.4.
727 Return values
728 The function returns +PRESS+ if the mouse button is held down, or +RELEASE+ if the
729 mouse button is not held down.
730 Description
731 The function queries the current state of a specific mouse button.
732 Notes
733 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
734 glfw::SwapBuffers must be called before any mouse button events are recorded and reported by
735 glfw::GetMouseButton.
736 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
737 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
738 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
743 "Return values
744 The function returns the current mouse position in xpos and ypos.
746 Description
747 The function returns the current mouse position. If the cursor is not hidden, the mouse position is the
748 cursor position, relative to the upper left corner of the window and limited to the client area of the
749 window. If the cursor is hidden, the mouse position is a virtual absolute position, not limited to any
750 boundaries except to those implied by the maximum number that can be represented by a signed integer
751 (normally -2147483648 to +2147483647).
753 Notes
754 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
755 glfw::SwapBuffers must be called before any mouse movements are recorded and reported by
756 glfw::GetMousePos.
761 "Parameters
762 xpos
763 Horizontal position of the mouse.
764 ypos
765 Vertical position of the mouse.
767 Description
768 The function changes the position of the mouse. If the cursor is visible (not disabled), the cursor will be
769 moved to the specified position, relative to the upper left corner of the window client area. If the cursor
770 is hidden (disabled), only the mouse position that is reported by GLFW is changed.
774 "Return values
775 The function returns the current mouse wheel position.
776 Description
777 The function returns the current mouse wheel position. The mouse wheel can be thought of as a third
778 mouse axis, which is available as a separate wheel or up/down stick on some mice.
779 Notes
780 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
781 glfw::SwapBuffers must be called before any mouse wheel movements are recorded and reported by
782 glfw::GetMouseWheel.
786 "Parameters
787 pos
788 Position of the mouse wheel.
789 Description
790 The function changes the position of the mouse wheel.
796 :documentation
797 "
798 Function that will be called every time a key is pressed or released.
799 Function should take the arguments (key action), where key is either a character,
800 if the key pressed was a member of iso-8859-1, or a keyword representing the key pressed if not.
801 See the GLFW manual, table 3.3 for special key identifiers. Action is either glfw:+press+ or
802 glfw:+release+. Use set-char-callback instead if you want to read just characters.
804 Description
805 The function selects which function to be called upon a keyboard key event. The callback function is
806 called every time the state of a single key is changed (from released to pressed or vice versa). The
807 reported keys are unaffected by any modifiers (such as shift or alt).
808 A window has to be opened for this function to have any effect.
810 Notes
811 Keyboard events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
812 or glfw::SwapBuffers is called.
816 :documentation
817 "
818 Function that will be called every time a printable character is generated by
819 the keyboard. The function should take the arguments (character action)
820 where character is a lisp character and action is either glfw:+press+ or glfw:+release+.
822 NB this makes the presumption that your lisp implementation will use Unicode for code-char.
824 Description
825 The function selects which function to be called upon a keyboard character event. The callback function
826 is called every time a key that results in a printable Unicode character is pressed or released. Characters
827 are affected by modifiers (such as shift or alt).
828 A window has to be opened for this function to have any effect.
830 Notes
831 Character events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
832 or glfw::SwapBuffers is called.
833 Control characters, such as tab and carriage return, are not reported to the character callback function,
834 since they are not part of the Unicode character set. Use the key callback function for such events (see
835 glfw::SetKeyCallback).
836 The Unicode character set supports character codes above 255, so never cast a Unicode character to an
837 eight bit data type (e.g. the C language char type) without first checking that the character code is less
838 than 256. Also note that Unicode character codes 0 to 255 are equal to ISO 8859-1 (Latin 1).
841 (define-callback-setter "glfwSetMouseButtonCallback" #:mouse-button :void ((button :int) (action :int))
843 :documentation
844 "
845 Function that will be called every time a mouse button is pressed or released.
846 The function takes the arguments (button action), where button is a keyword symbol as returned by
847 lispify-mouse-button and action is either glfw:+press+ or glfw:+release+.
849 Description
850 The function selects which function to be called upon a mouse button event.
851 A window has to be opened for this function to have any effect.
853 Notes
854 Mouse button events are recorded continuously, but only reported when glfw::PollEvents,
855 glfw::WaitEvents or glfw::SwapBuffers is called.
856 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
857 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
858 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
861 :documentation
862 "
863 Function that will be called every time the mouse is moved.
864 The function takes the arguments (x y), where x and y are the current position of the mouse.
866 Description
867 The function selects which function to be called upon a mouse motion event.
868 A window has to be opened for this function to have any effect.
870 Notes
871 Mouse motion events are recorded continuously, but only reported when glfw::PollEvents,
872 glfw::WaitEvents or glfw::SwapBuffers is called.
878 :documentation
879 "
880 Function that will be called every time the mouse wheel is moved.
881 The function takes one argument: the position of the mouse wheel.
882 This DIFFERS FROM GLFW's DEFAULT behaviour in that the position is
883 reset after every call to this function, effectively giving the delta.
884 As most programs are only interested in the delta anyway, this is thought
885 to save others recording the state of it again.
886 If you wish to have the original GLFW behaviour, set cl-glfw:*mouse-wheel-cumulative* to t.
888 Description
889 The function selects which function to be called upon a mouse wheel event.
890 A window has to be opened for this function to have any effect.
891 Notes
892 Mouse wheel events are recorded continuously, but only reported when glfw::PollEvents,
893 glfw::WaitEvents or glfw::SwapBuffers is called.
897 "Parameters
898 joy
899 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
900 param
901 A token selecting which parameter the function should return (see table 3.5).
902 Return values
903 The function returns different parameters depending on the value of param. Table 3.5 lists valid param
904 values, and their corresponding return values.
905 Description
906 The function is used for acquiring various properties of a joystick.
907 Notes
908 The joystick information is updated every time the function is called.
909 No window has to be opened for joystick information to be valid.
912 (defcfun ("glfwGetJoystickPos" %get-joystick-pos) :int (joy :int) (pos :pointer) (numaxes :int))
915 "Parameters
916 joy
917 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
918 numaxes
919 Specifies how many axes should be returned.
920 Return values
921 An list that will hold the positional values for all requested axes.
922 If the joystick is not supported or connected, the function will
923 return nil.
925 Description
926 The function queries the current position of one or more axes of a joystick. The positional values are
927 returned in an array, where the first element represents the first axis of the joystick (normally the X
928 axis). Each position is in the range -1.0 to 1.0. Where applicable, the positive direction of an axis is
929 right, forward or up, and the negative direction is left, back or down.
930 If numaxes exceeds the number of axes supported by the joystick, or if the joystick is not available, the
931 unused elements in the pos array will be set to 0.0 (zero).
933 Notes
934 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
935 or glfw::WaitEvents for joystick state to be updated.
936 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
937 supported axes.
938 No window has to be opened for joystick input to be valid.
939 "
945 (defcfun ("glfwGetJoystickButtons" %get-joystick-buttons) :int (joy :int) (buttons :pointer) (numbuttons :int))
947 "Parameters
948 joy
949 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
950 numbuttons
951 Specifies how many buttons should be returned.
952 Return values
953 A list that will hold the button states for all requested buttons.
954 The function returns the number of actually returned buttons. This is the minimum of numbuttons and
955 the number of buttons supported by the joystick. If the joystick is not supported or connected, the
956 function will return 0 (zero).
958 Description
959 The function queries the current state of one or more buttons of a joystick. The button states are
960 returned in an array, where the first element represents the first button of the joystick. Each state can be
961 either +PRESS+ or +RELEASE+
962 If numbuttons exceeds the number of buttons supported by the joystick, or if the joystick is not
963 available, the unused elements in the buttons array will be set to +RELEASE+
965 Notes
966 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
967 or glfw::WaitEvents for joystick state to be updated.
968 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
969 supported buttons.
970 No window has to be opened for joystick input to be valid.
971 "
978 "Return values
979 The function returns the value of the high precision timer. The time is measured in seconds, and is
980 returned as a double precision floating point value.
982 Description
983 The function returns the state of a high precision timer. Unless the timer has been set by the
984 glfw::SetTime function, the time is measured as the number of seconds that have passed since glfw::Init
985 was called.
987 Notes
988 The resolution of the timer depends on which system the program is running on. The worst case
989 resolution is somewhere in the order of 10 ms, while for most systems the resolution should be better
990 than 1us.
994 "Parameters
995 time
996 Time (in seconds) that the timer should be set to.
998 Description
999 The function sets the current time of the high precision timer to the specified time. Subsequent calls to
1000 glfw::GetTime will be relative to this time. The time is given in seconds.
1004 "Parameters
1005 time
1006 Time, in seconds, to sleep.
1008 Description
1009 The function puts the calling thread to sleep for the requested period of time. Only the calling thread is
1010 put to sleep. Other threads within the same process can still execute.
1012 Notes
1013 There is usually a system dependent minimum time for which it is possible to sleep. This time is
1014 generally in the range 1 ms to 20 ms, depending on thread sheduling time slot intervals etc. Using a
1015 shorter time as a parameter to glfw::Sleep can give one of two results: either the thread will sleep for the
1016 minimum possible sleep time, or the thread will not sleep at all (glfw::Sleep returns immediately). The
1028 "Parameters
1029 name
1030 A null terminated ISO 8859-1 string holding the name of the file that should be read.
1031 img
1032 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1033 read was successful).
1034 flags
1035 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1036 Return values
1037 The function returns t if the image was loaded successfully. Otherwise nil is
1038 returned.
1039 Description
1040 The function reads an image from the file specified by the parameter name and returns the image
1041 information and data in a GLFWimage structure, which has the following definition:
1043 typedef struct {
1044 int Width, Height; // Image dimensions
1045 int Format; // OpenGL pixel format
1046 int BytesPerPixel; // Number of bytes per pixel
1047 unsigned char *Data; // Pointer to pixel data
1048 } GLFWimage;
1050 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1051 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1052 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1054 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1055 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1056 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1057 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1058 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1059 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1061 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1062 Notes
1063 glfw::ReadImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel formats
1064 are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color + alpha.
1065 Paletted images are translated into true color or true color + alpha pixel formats.
1066 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1067 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1072 "Parameters
1073 data
1074 The memory buffer holding the contents of the file that should be read.
1075 size
1076 The size, in bytes, of the memory buffer.
1077 img
1078 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1079 read was successful).
1080 flags
1081 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1082 Return values
1083 The function returns t if the image was loaded successfully. Otherwise nil is
1084 returned.
1085 Description
1086 The function reads an image from the memory buffer specified by the parameter data and returns the
1087 image information and data in a GLFWimage structure, which has the following definition:
1089 typedef struct {
1090 int Width, Height; // Image dimensions
1091 int Format; // OpenGL pixel format
1092 int BytesPerPixel; // Number of bytes per pixel
1093 unsigned char *Data; // Pointer to pixel data
1094 } GLFWimage;
1096 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1097 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1098 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1100 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1101 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1102 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1103 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1104 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1105 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1106 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1107 Notes
1108 glfw::ReadMemoryImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1109 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1110 alpha.
1111 Paletted images are translated into true color or true color + alpha pixel formats.
1112 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1113 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1117 "Parameters
1118 img
1119 Pointer to a GLFWimage struct.
1120 Description
1121 The function frees any memory occupied by a loaded image, and clears all the fields of the GLFWimage
1122 struct. Any image that has been loaded by the glfw::ReadImage function should be deallocated using
1126 "Parameters
1127 name
1128 An ISO 8859-1 string holding the name of the file that should be loaded.
1129 flags
1130 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1131 Return values
1132 The function returns t if the texture was loaded successfully. Otherwise nil is
1133 returned.
1135 Description
1137 The function reads an image from the file specified by the parameter
1138 name and uploads the image to OpenGL texture memory (using the
1139 glTexImage2D function). If the GLFW_BUILD_MIPMAPS_BIT flag is set,
1140 all mipmap levels for the loaded texture are generated and uploaded to
1141 texture memory. Unless the flag +ORIGIN_UL_BIT+ is set, the origin of
1142 the texture is the lower left corner of the loaded image. If the flag
1143 +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1144 corner. For single component images (i.e. gray scale), the texture is
1145 uploaded as an alpha mask if the flag +ALPHA_MAP_BIT+ flag is set,
1146 otherwise it is uploaded as a luminance texture.
1148 Notes
1149 glfw::LoadTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1150 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1151 alpha.
1152 Paletted images are translated into true color or true color + alpha pixel formats.
1153 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1154 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1155 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1156 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1157 generated by GLFW in software.
1159 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1160 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1161 texture is a single component texture. The red, green and blue components are set to 1.0.
1166 "Parameters
1167 data
1168 The memory buffer holding the contents of the file that should be loaded.
1169 size
1170 The size, in bytes, of the memory buffer.
1171 flags
1172 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1173 Return values
1174 The function returns t if the texture was loaded successfully. Otherwise nil is
1175 returned.
1177 Description
1178 The function reads an image from the memory buffer specified by the parameter data and uploads the
1179 image to OpenGL texture memory (using the glTexImage2D function).
1180 If the GLFW_BUILD_MIPMAPS_BIT flag is set, all mipmap levels for the loaded texture are
1181 generated and uploaded to texture memory.
1182 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1183 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1184 corner.
1185 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1186 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1188 Notes
1189 glfw::LoadMemoryTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported
1190 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1191 + alpha.
1192 Paletted images are translated into true color or true color + alpha pixel formats.
1193 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1194 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1195 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1196 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1197 generated by GLFW in software.
1199 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1200 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1201 texture is a single component texture. The red, green and blue components are set to 1.0.
1207 "Parameters
1208 img
1209 Pointer to a GLFWimage struct holding the information about the image to be loaded.
1210 flags
1211 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1212 Return values
1213 The function returns t if the texture was loaded successfully. Otherwise nil is
1214 returned.
1216 Description
1217 The function uploads the image specified by the parameter img to OpenGL texture memory (using
1218 the glTexImage2D function).
1219 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1220 generated and uploaded to texture memory.
1221 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1222 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1223 corner.
1224 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1225 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1227 Notes
1228 glfw::LoadTextureImage2D supports the Truevision Targa version 1 file format (.TGA). Supported
1229 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1230 + alpha.
1231 Paletted images are translated into true color or true color + alpha pixel formats.
1232 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1233 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1234 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1235 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1236 generated by GLFW in software.
1238 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1239 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1244 "Parameters
1245 extension
1246 A null terminated ISO 8859-1 string containing the name of an OpenGL extension.
1247 Return values
1248 The function returns t if the extension is supported. Otherwise it returns nil.
1249 Description
1250 The function does a string search in the list of supported OpenGL extensions to find if the specified
1251 extension is listed.
1252 Notes
1254 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1255 must have been opened with glfwOpenWindow).
1256 In addition to checking for OpenGL extensions, GLFW also checks for extensions in the operating
1257 system ?glue API?, such as WGL extensions under Windows and glX extensions under the X Window
1258 System.
1262 "Parameters
1263 procname
1264 A null terminated ISO 8859-1 string containing the name of an OpenGL extension function.
1265 Return values
1266 The function returns the pointer to the specified OpenGL function if it is supported, otherwise
1267 NULL is returned.
1268 Description
1269 The function acquires the pointer to an OpenGL extension function. Some (but not all) OpenGL
1270 extensions define new API functions, which are usually not available through normal linking. It is
1271 therefore necessary to get access to those API functions at runtime.
1272 Notes
1274 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1275 must have been opened with glfwOpenWindow).
1276 Some systems do not support dynamic function pointer retrieval, in which case glfwGetProcAddress
1277 will always return NULL.
1283 "Return values
1284 The function returns the major and minor version numbers and the revision for the currently used
1285 OpenGL implementation as a list (major minor rev).
1287 Description
1288 The function returns the OpenGL implementation version. This is a convenient function that parses
1289 the version number information from the string returned by calling
1290 glGetString( GL_VERSION ). The OpenGL version information can be used to determine
1291 what functionality is supported by the used OpenGL implementation.
1293 Notes
1294 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1303 "Parameters
1304 fun
1305 A pointer to a function that acts as the entry point for the new thread. The function should have
1306 the following C language prototype:
1307 void GLFWCALL functionname( void *arg );
1308 Where functionname is the name of the thread function, and arg is the user supplied argument
1309 (see below).
1310 arg
1311 An arbitrary argument for the thread. arg will be passed as the argument to the thread function
1312 pointed to by fun. For instance, arg can point to data that is to be processed by the thread.
1313 Return values
1314 The function returns a thread identification number if the thread was created successfully. This number
1315 is always positive. If the function fails, a negative number is returned.
1316 Description
1317 The function creates a new thread, which executes within the same address space as the calling process.
1318 The thread entry point is specified with the fun argument.
1319 Once the thread function fun returns, the thread dies.
1320 Notes
1321 Even if the function returns a positive thread ID, indicating that the thread was created successfully, the
1322 thread may be unable to execute, for instance if the thread start address is not a valid thread entry point.
1325 "Parameters
1326 ID
1327 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1328 Description
1329 The function kills a running thread and removes it from the thread list.
1330 Notes
1331 This function is a very dangerous operation, which may interrupt a thread in the middle of an important
1332 operation, and its use is discouraged. You should always try to end a thread in a graceful way using
1333 thread communication, and use glfw::WaitThread in order to wait for the thread to die.
1336 "Parameters
1337 ID
1338 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1339 waitmode
1340 Can be either +WAIT+ or +NOWAIT+
1341 Return values
1342 The function returns t if the specified thread died after the function was called, or the thread
1343 did not exist, in which case glfw::WaitThread will return immediately regardless of waitmode. The
1344 function returns nil if waitmode is +NOWAIT+ and the specified thread exists and is still
1345 running.
1348 "Return values
1349 The function returns a thread identification handle for the calling thread.
1350 Description
1351 The function determines the thread ID for the calling thread. The ID is the same value as was returned
1352 by glfw::CreateThread when the thread was created.
1356 "Return values
1357 The function returns a mutex handle, or NULL if the mutex could not be created.
1358 Description
1359 The function creates a mutex object, which can be used to control access to data that is shared between
1360 threads.
1363 "Parameters
1364 mutex
1365 A mutex object handle.
1366 Description
1367 The function destroys a mutex object. After a mutex object has been destroyed, it may no longer be
1368 used by any thread.
1371 "Parameters
1372 mutex
1373 A mutex object handle.
1374 Description
1375 The function will acquire a lock on the selected mutex object. If the mutex is already locked by another
1376 thread, the function will block the calling thread until it is released by the locking thread. Once the
1377 function returns, the calling thread has an exclusive lock on the mutex. To release the mutex, call
1378 glfw::UnlockMutex.
1381 "Parameters
1382 mutex
1383 A mutex object handle.
1384 Description
1385 The function releases the lock of a locked mutex object.
1389 "Parameters
1390 mutex
1391 A mutex object handle.
1392 forms
1393 Body of code to execute
1394 Description
1395 This macro will acquire a lock on the selected mutex object using glfw::LockMutex and release it afterwards
1396 using glfw::UnlockMutex.
1397 So, forms will not execute until an exclusive lock is held.
1398 The lock is then released when the stack is unwound."
1406 "Return values
1407 The function returns a condition variable handle, or NULL if the condition variable could not be
1408 created.
1409 Description
1410 The function creates a condition variable object, which can be used to synchronize threads.
1413 "Parameters
1414 cond
1415 A condition variable object handle.
1416 Description
1417 The function destroys a condition variable object. After a condition variable object has been destroyed,
1418 it may no longer be used by any thread.
1421 " arameters
1422 cond
1423 A condition variable object handle.
1424 mutex
1425 A mutex object handle.
1426 timeout
1427 Maximum time to wait for the condition variable. The parameter can either be a positive time (in
1428 seconds), or +INFINITY+
1429 Description
1430 The function atomically unlocks the mutex specified by mutex, and waits for the condition variable cond
1431 to be signaled. The thread execution is suspended and does not consume any CPU time until the
1432 condition variable is signaled or the amount of time specified by timeout has passed. If timeout is
1433 +INFINITY+ glfw::WaitCond will wait forever for cond to be signaled. Before returning to the
1434 calling thread, glfw::WaitCond automatically re-acquires the mutex.
1435 Notes
1436 The mutex specified by mutex must be locked by the calling thread before entrance to glfw::WaitCond.
1437 A condition variable must always be associated with a mutex, to avoid the race condition where a thread
1438 prepares to wait on a condition variable and another thread signals the condition just before the first
1439 thread actually waits on it.
1442 "Parameters
1443 cond
1444 A condition variable object handle.
1445 Description
1446 The function restarts one of the threads that are waiting on the condition variable cond. If no threads are
1447 waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it
1448 is not specified which.
1449 Notes
1450 When several threads are waiting for the condition variable, which thread is started depends on
1451 operating system scheduling rules, and may vary from system to system and from time to time.
1454 "Parameters
1455 cond
1456 A condition variable object handle.
1457 Description
1458 The function restarts all the threads that are waiting on the condition variable cond. If no threads are
1459 waiting on cond, nothing happens.
1460 Notes
1461 When several threads are waiting for the condition variable, the order in which threads are started
1462 depends on operating system scheduling rules, and may vary from system to system and from time to
1463 time.
1467 "Return values
1468 The function returns the number of active processors in the system.
1469 Description
1470 The function determines the number of active processors in the system.
1471 Notes
1472 Systems with several logical processors per physical processor, also known as SMT (Symmetric Multi
1473 Threading) processors, will report the number of logical processors.
1476 "Parameters
1477 token
1478 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1479 Return values
1480 none
1481 Description
1482 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1483 description of each feature.
1484 +AUTO_POLL_EVENTS+
1485 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1486 that glfw::SwapBuffers is called.
1487 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1488 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1489 function, since calling glfw::PollEvents from a callback function is not allowed.
1490 +KEY_REPEAT+
1491 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1492 when a key is held down long enough (according to the system key repeat configuration).
1493 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1494 when a key is pressed (and once when it is released).
1495 +MOUSE_CURSOR+
1496 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1497 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1498 the client area of the window.
1499 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1500 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1501 from the mouse, without being restricted or manipulated by the windowing system.
1502 +STICKY_KEYS+
1503 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1504 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1505 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1506 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1507 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1508 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1509 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfw::GetKey is always
1510 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1511 all keys.
1512 +STICKY_MOUSE_BUTTONS+
1513 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1514 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1515 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1516 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1517 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1518 glfw::GetMouseButton will never be released. Note also that enabling
1519 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1520 functionality.
1521 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1522 by glfw::GetMouseButton is always the physical state of the mouse button. Disabling
1523 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1524 +SYSTEM_KEYS+
1525 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1526 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1527 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1528 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1529 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1530 the GLFW video mode again.
1531 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1532 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1533 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1536 "Parameters
1537 token
1538 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1539 Return values
1540 none
1541 Description
1542 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1543 description of each feature.
1544 +AUTO_POLL_EVENTS+
1545 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1546 that glfw::SwapBuffers is called.
1547 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1548 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1549 function, since calling glfw::PollEvents from a callback function is not allowed.
1550 +KEY_REPEAT+
1551 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1552 when a key is held down long enough (according to the system key repeat configuration).
1553 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1554 when a key is pressed (and once when it is released).
1555 +MOUSE_CURSOR+
1556 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1557 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1558 the client area of the window.
1559 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1560 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1561 from the mouse, without being restricted or manipulated by the windowing system.
1562 +STICKY_KEYS+
1563 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1564 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1565 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1566 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1567 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1568 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1569 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfwGetKey is always
1570 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1571 all keys.
1572 +STICKY_MOUSE_BUTTONS+
1573 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1574 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1575 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1576 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1577 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1578 glfw::GetMouseButton will never be released. Note also that enabling
1579 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1580 functionality.
1581 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1582 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1583 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1584 +SYSTEM_KEYS+
1585 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1586 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1587 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1588 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1589 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1590 the GLFW video mode again.
1591 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1592 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1593 the GLFW program must not be interrupted (normally for games in fullscreen mode).