| blob | 15747e338011fe26bda0dd0aa45320c7ee8017a5 |
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
275 "width
276 The width of the window. If width is zero, it will be calculated as width = 4/3 height, if height is
277 not zero. If both width and height are zero, then width will be set to 640.
278 height
279 The height of the window. If height is zero, it will be calculated as height = 3/4 width, if width is
280 not zero. If both width and height are zero, then height will be set to 480.
281 redbits, greenbits, bluebits
282 The number of bits to use for each color component of the color buffer (0 means default color
283 depth). For instance, setting redbits=5, greenbits=6, and bluebits=5 will generate a 16-bit color
284 buffer, if possible.
285 alphabits
286 The number of bits to use for the alpha buffer (0 means no alpha buffer).
287 depthbits
288 The number of bits to use for the depth buffer (0 means no depth buffer).
289 stencilbits
290 The number of bits to use for the stencil buffer (0 means no stencil buffer).
291 mode
292 Selects which type of OpenGL window to use. mode can be either +WINDOW+, which
293 will generate a normal desktop window, or +FULLSCREEN+ which will generate a
294 window which covers the entire screen. When +FULLSCREEN+ is selected, the video
295 mode will be changed to the resolution that closest matches the width and height parameters.
297 Return values
298 If the function succeeds, t is returned.
299 If the function fails, nil is returned.
301 Description
303 The function opens a window that best matches the parameters given to
304 the function. How well the resulting window matches the desired window
305 depends mostly on the available hardware and OpenGL drivers. In
306 general, selecting a fullscreen mode has better chances of generating
307 a close match than does a normal desktop window, since GLFW can freely
308 select from all the available video modes. A desktop window is
309 normally restricted to the video mode of the desktop.
311 Notes
313 For additional control of window properties, see glfw::OpenWindowHint.
314 In fullscreen mode the mouse cursor is hidden by default, and any system screensavers are prohibited
315 from starting. In windowed mode the mouse cursor is visible, and screensavers are allowed to start. To
316 change the visibility of the mouse cursor, use glfwEnable or glfwDisable with the argument
317 +MOUSE_CURSOR+
318 In order to determine the actual properties of an opened window, use glfw::GetWindowParam and
319 glfw::GetWindowSize (or glfw::SetWindowSizeCallback).
320 "
335 accum-red-bits accum-green-bits accum-blue-bits
336 accum-alpha-bits
337 aux-buffers
338 fsaa-samples
339 opengl-version-major
340 opengl-version-minor
341 opengl-profile)
343 window-no-resize
344 opengl-forward-compat
345 opengl-debug-context))
353 "target
354 Can be any of the constants in the table 3.1.
355 hint
356 An integer giving the value of the corresponding target (see table 3.1).
358 Description
359 The function sets additional properties for a window that is to be opened. For a hint to be registered, the
360 function must be called before calling glfw::OpenWindow. When the glfw::OpenWindow function is
361 called, any hints that were registered with the glfw::OpenWindowHint function are used for setting the
362 corresponding window properties, and then all hints are reset to their default values.
364 Notes
365 In order to determine the actual properties of an opened window, use glfw::GetWindowParam (after the
366 window has been opened).
367 +STEREO+ is a hard constraint. If stereo rendering is requested, but no stereo rendering capable
368 pixel formats / visuals are available, glfw::OpenWindow will fail.
369 The +REFRESH_RATE+ property should be used with caution. Most systems have default values
370 for monitor refresh rates that are optimal for the specific system. Specifying the refresh rate can
371 override these settings, which can result in suboptimal operation. The monitor may be unable to display
372 the resulting video signal, or in the worst case it may even be damaged!
380 "Wraps forms such that there is an open window for them to execute in and cleans up the
381 window afterwards. An error is signalled if there was an error opening the window.
382 Takes the same parameters as open-window, with the addition of 'title' which will
383 set the window title after opening.
384 Wrapped in a block named glfw:with-open-window."
394 "Wraps forms in with-init, with-open-window. Passes through the other arguments to open-window."
402 "High-level convenience macro for opening a window (given the optional window parameters),
403 setting the title given,
404 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
405 The loop is in a block named do-open-window [so can be exited by a call to (return-from glfw:do-window)].
406 If the window is closed, the loop is also exited."
408 ,@setup-forms
411 ,@forms
419 "High-level convenience macro for initializing glfw, opening a window (given the optional window parameters),
420 setting the title given,
421 running setup-forms and then running forms in a loop, with calls to swap-buffers after each loop iteration.
422 The loop is in a block named do-window [so can be exited by a call to (return-from glfw:do-window)].
423 If the window is closed, the loop is also exited."
427 (defmacro define-callback-setter (c-name callback-prefix return-type (&body args) &key before-form after-form documentation)
437 ,before-form
444 All callback setting functions can take either a pointer to a C function,
445 a function object, a function symbol, or nil to clear the callback function.
447 THIS CALLBACK FUNCTION
461 (t (error "Not an acceptable callback. Must be foreign pointer, function object, function's symbol, or nil.")))))))
465 :documentation
466 "
467 Function that will be called when a user requests that the window should be
468 closed, typically by clicking the window close icon (e.g. the cross in the upper right corner of a
469 window under Microsoft Windows). The function should have the following type:
470 (function () integer)
472 The return value of the callback function indicates whether or not the window close action should continue. If the function returns
473 gl:+true+, the window will be closed. If the function returns gl:+false+, the window will not
474 be closed. If you give a CFFI callback returning glfw:boolean, you can use t and nil as return types.
476 Notes
477 Window close events are recorded continuously, but only reported when glfwPollEvents,
478 glfwWaitEvents or glfwSwapBuffers is called.
479 The OpenGL context is still valid when this function is called.
480 Note that the window close callback function is not called when glfwCloseWindow is called, but only
481 when the close request comes from the window manager.
482 Do not call glfwCloseWindow from a window close callback function. Close the window by returning
483 gl:+true+ from the function.
488 "Parameters
489 title
490 Pointer to a null terminated ISO 8859-1 (8-bit Latin 1) string that holds the title of the window.
492 Description
493 The function changes the title of the opened window.
495 Notes
496 The title property of a window is often used in situations other
497 than for the window title, such as the title of an application icon
501 "Parameters
502 width
503 Width of the window.
504 height
505 Height of the window.
506 Return values
507 none
508 Description
510 The function changes the size of an opened window. The width and
511 height parameters denote the size of the client area of the
512 window (i.e. excluding any window borders and decorations). If the
513 window is in fullscreen mode, the video mode will be changed to a
514 resolution that closest matches the width and height parameters (the
515 number of color bits will not be changed).
517 Notes
519 The OpenGL context is guaranteed to be preserved after calling glfwSetWindowSize, even if the
520 video mode is changed.
524 "Parameters
525 x
526 Horizontal position of the window, relative to the upper left corner of the desktop.
527 y
528 Vertical position of the window, relative to the upper left corner of the desktop.
529 Return values
530 none
531 Description
532 The function changes the position of an opened window. It does not have any effect on a fullscreen
533 window.
538 "The function is used for determining the size of an opened window. The returned values are dimensions
539 of the client area of the window (i.e. excluding any window borders and decorations).
540 (list width height)"
547 (define-callback-setter "glfwSetWindowSizeCallback" #:window-size :void ((width :int) (height :int))
548 :documentation
549 "
550 Function that will be called every time the window size changes. The
551 function should takes the arguments (width height) giving the new width and height of the window client area.
553 A window has to be opened for this function to have any effect.
554 Notes
555 Window size changes are recorded continuously, but only reported when glfwPollEvents,
559 "Iconify a window. If the window is in fullscreen mode, then the desktop video mode will be restored.")
562 "Restore an iconified window. If the window that is restored is in fullscreen mode, then the fullscreen
566 "Parameters
567 param
568 A token selecting which parameter the function should return (see table 3.2).
570 Return values
572 The function returns different parameters depending on the value of
573 param. Table 3.2 lists valid param values, and their corresponding
574 return values.
576 Description
577 The function is used for acquiring various properties of an opened window.
579 Notes: GLFW_ACCELERATED is only supported under Windows. Other systems
580 will always return GL_TRUE. Under Windows, GLFW_ACCELERATED means that
581 the OpenGL renderer is a 3rd party renderer, rather than the fallback
582 Microsoft software OpenGL renderer. In other words, it is not a real
583 guarantee that the OpenGL renderer is actually hardware accelerated.
587 "The function swaps the back and front color buffers of the window. If +AUTO_POLL_EVENTS+
588 is enabled (which is the default), glfwPollEvents is called before swapping the front and back buffers.")
592 "Parameters
593 interval
594 Minimum number of monitor vertical retraces between each buffer swap performed by
595 glfwSwapBuffers. If interval is zero, buffer swaps will not be synchronized to the vertical
596 refresh of the monitor (also known as VSync off).
598 Description
600 The function selects the minimum number of monitor vertical retraces
601 that should occur between two buffer swaps. If the selected swap
602 interval is one, the rate of buffer swaps will never be higher than
603 the vertical refresh rate of the monitor. If the selected swap
604 interval is zero, the rate of buffer swaps is only limited by the
605 speed of the software and the hardware.
607 Notes
609 This function will only have an effect on hardware and drivers that
614 :documentation
615 "
616 Function that will be called when the window client area needs to be
617 refreshed. The function takes no arguments and returns nothing (void).
619 Description
621 The function selects which function to be called upon a window refresh
622 event, which occurs when any part of the window client area has been
623 damaged, and needs to be repainted (for instance, if a part of the
624 window that was previously occluded by another window has become
625 visible). A window has to be opened for this function to have any
626 effect.
628 Notes
629 Window refresh events are recorded continuously, but only reported when glfwPollEvents,
630 glfwWaitEvents or glfwSwapBuffers is called.
643 "Parameters
644 maxcount
645 Maximum number of video modes that list vector can hold.
647 Return values
648 The function returns the number of detected video modes (this number will never exceed maxcount).
649 The list vector is filled out with the video modes that are supported by the system.
651 Description
652 The function returns a list of supported video modes. Each video mode is represented by a
653 list of the form:
654 (width height redbits greenbits bluebits)
656 Notes
657 The returned list is sorted, first by color depth (RedBits + GreenBits + BlueBits), and then by
658 resolution (Width * Height), with the lowest resolution, fewest bits per pixel mode first. "
663 collecting
673 "Parameters
674 mode
675 Pointer to a GLFWvidmode structure, which will be filled out by the function.
676 Return values
677 The GLFWvidmode structure pointed to by mode is filled out with the desktop video mode.
678 Description
679 The function returns the desktop video mode in a GLFWvidmode structure. See glfwGetVideoModes
680 for a definition of the GLFWvidmode structure.
681 Notes
682 The color depth of the desktop display is always reported as the number of bits for each individual color
683 component (red, green and blue), even if the desktop is not using an RGB or RGBA color format. For
684 instance, an indexed 256 color display may report RedBits = 3, GreenBits = 3 and BlueBits = 2, which
685 adds up to 8 bits in total.
686 The desktop video mode is the video mode used by the desktop, not the current video mode (which may
687 differ from the desktop video mode if the GLFW window is a fullscreen window).
688 "
698 "Description
699 The function is used for polling for events, such as user input and window resize events. Upon calling
700 this function, all window states, keyboard states and mouse states are updated. If any related callback
701 functions are registered, these are called during the call to glfwPollEvents.
703 Notes
704 glfwPollEvents is called implicitly from glfwSwapBuffers if +AUTO_POLL_EVENTS+ is
705 enabled (default). Thus, if glfwSwapBuffers is called frequently, which is normally the case, there is
706 no need to call glfwPollEvents.
710 "Description
711 The function is used for waiting for events, such as user input and window resize events. Upon calling
712 this function, the calling thread will be put to sleep until any event appears in the event queue. When
713 events are ready, the events will be processed just as they are processed by glfwPollEvents.
714 If there are any events in the queue when the function is called, the function will behave exactly like
715 glfwPollEvents (i.e. process all messages and then return, without blocking the calling thread).
717 Notes
718 It is guaranteed that glfwWaitEvents will wake up on any event that can be processed by
719 glfw::PollEvents. However, glfwWaitEvents may wake up on events that are not processed or reported
720 by glfw::PollEvents too, and the function may behave differently on different systems. Do no make any
721 assumptions about when or why glfw::WaitEvents will return.
727 (loop for special-key in '("backspace" "del" "down" "end" "enter" "esc" "f1" "f10" "f11" "f12" "f13"
735 collect
736 `(,(symbol-value (find-symbol (string-upcase (format nil "+key-~a+" special-key)) (find-package '#:glfw)))
742 "Convert key-int from GLFW's integer representation to lisp characters if from 0 to 255, or keywords, if not within 0-255 inclusive."
749 "Parameters
750 key
751 A keyboard key identifier, which can be either an uppercase printable ISO 8859-1 (Latin 1)
752 character (e.g. 'A', '3' or '.'), or a special key identifier. Table 3.3 lists valid special key
753 identifiers.
754 Return values
755 The function returns +PRESS+ if the key is held down, or +RELEASE+ if the key is not
756 held down.
758 Description
759 The function queries the current state of a specific keyboard key. The physical location of each key
760 depends on the system keyboard layout setting.
762 Notes
763 The constant +KEY_SPACE+ is equal to 32, which is the ISO 8859-1 code for space.
764 Not all key codes are supported on all systems. Also, while some keys are available on some keyboard
765 layouts, they may not be available on other keyboard layouts.
766 For systems that do not distinguish between left and right versions of modifier keys (shift, alt and
767 control), the left version is used (e.g. +KEY_LSHIFT+)
768 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
769 glfw::SwapBuffers must be called before any keyboard events are recorded and reported by
770 glfw::GetKey.
775 "Convert button-int from GLFW's integer representation to a lisp keyword."
788 "Parameters
789 button
790 A mouse button identifier, which can be one of the mouse button identifiers listed in table 3.4.
791 Return values
792 The function returns +PRESS+ if the mouse button is held down, or +RELEASE+ if the
793 mouse button is not held down.
794 Description
795 The function queries the current state of a specific mouse button.
796 Notes
797 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
798 glfw::SwapBuffers must be called before any mouse button events are recorded and reported by
799 glfw::GetMouseButton.
800 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
801 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
802 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
807 "Return values
808 The function returns the current mouse position in xpos and ypos.
810 Description
811 The function returns the current mouse position. If the cursor is not hidden, the mouse position is the
812 cursor position, relative to the upper left corner of the window and limited to the client area of the
813 window. If the cursor is hidden, the mouse position is a virtual absolute position, not limited to any
814 boundaries except to those implied by the maximum number that can be represented by a signed integer
815 (normally -2147483648 to +2147483647).
817 Notes
818 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
819 glfw::SwapBuffers must be called before any mouse movements are recorded and reported by
820 glfw::GetMousePos.
825 "Parameters
826 xpos
827 Horizontal position of the mouse.
828 ypos
829 Vertical position of the mouse.
831 Description
832 The function changes the position of the mouse. If the cursor is visible (not disabled), the cursor will be
833 moved to the specified position, relative to the upper left corner of the window client area. If the cursor
834 is hidden (disabled), only the mouse position that is reported by GLFW is changed.
838 "Return values
839 The function returns the current mouse wheel position.
840 Description
841 The function returns the current mouse wheel position. The mouse wheel can be thought of as a third
842 mouse axis, which is available as a separate wheel or up/down stick on some mice.
843 Notes
844 A window must be opened for the function to have any effect, and glfw::PollEvents, glfw::WaitEvents or
845 glfw::SwapBuffers must be called before any mouse wheel movements are recorded and reported by
846 glfw::GetMouseWheel.
850 "Parameters
851 pos
852 Position of the mouse wheel.
853 Description
854 The function changes the position of the mouse wheel.
860 :documentation
861 "
862 Function that will be called every time a key is pressed or released.
863 Function should take the arguments (key action), where key is either a character,
864 if the key pressed was a member of iso-8859-1, or a keyword representing the key pressed if not.
865 See the GLFW manual, table 3.3 for special key identifiers. Action is either glfw:+press+ or
866 glfw:+release+. Use set-char-callback instead if you want to read just characters.
868 Description
869 The function selects which function to be called upon a keyboard key event. The callback function is
870 called every time the state of a single key is changed (from released to pressed or vice versa). The
871 reported keys are unaffected by any modifiers (such as shift or alt).
872 A window has to be opened for this function to have any effect.
874 Notes
875 Keyboard events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
876 or glfw::SwapBuffers is called.
880 :documentation
881 "
882 Function that will be called every time a printable character is generated by
883 the keyboard. The function should take the arguments (character action)
884 where character is a lisp character and action is either glfw:+press+ or glfw:+release+.
886 NB this makes the presumption that your lisp implementation will use Unicode for code-char.
888 Description
889 The function selects which function to be called upon a keyboard character event. The callback function
890 is called every time a key that results in a printable Unicode character is pressed or released. Characters
891 are affected by modifiers (such as shift or alt).
892 A window has to be opened for this function to have any effect.
894 Notes
895 Character events are recorded continuously, but only reported when glfw::PollEvents, glfw::WaitEvents
896 or glfw::SwapBuffers is called.
897 Control characters, such as tab and carriage return, are not reported to the character callback function,
898 since they are not part of the Unicode character set. Use the key callback function for such events (see
899 glfw::SetKeyCallback).
900 The Unicode character set supports character codes above 255, so never cast a Unicode character to an
901 eight bit data type (e.g. the C language char type) without first checking that the character code is less
902 than 256. Also note that Unicode character codes 0 to 255 are equal to ISO 8859-1 (Latin 1).
905 (define-callback-setter "glfwSetMouseButtonCallback" #:mouse-button :void ((button :int) (action :int))
907 :documentation
908 "
909 Function that will be called every time a mouse button is pressed or released.
910 The function takes the arguments (button action), where button is a keyword symbol as returned by
911 lispify-mouse-button and action is either glfw:+press+ or glfw:+release+.
913 Description
914 The function selects which function to be called upon a mouse button event.
915 A window has to be opened for this function to have any effect.
917 Notes
918 Mouse button events are recorded continuously, but only reported when glfw::PollEvents,
919 glfw::WaitEvents or glfw::SwapBuffers is called.
920 +MOUSE_BUTTON_LEFT+ is equal to +MOUSE_BUTTON_1+
921 +MOUSE_BUTTON_RIGHT+ is equal to +MOUSE_BUTTON_2+
922 +MOUSE_BUTTON_MIDDLE+ is equal to +MOUSE_BUTTON_3+
925 :documentation
926 "
927 Function that will be called every time the mouse is moved.
928 The function takes the arguments (x y), where x and y are the current position of the mouse.
930 Description
931 The function selects which function to be called upon a mouse motion event.
932 A window has to be opened for this function to have any effect.
934 Notes
935 Mouse motion events are recorded continuously, but only reported when glfw::PollEvents,
936 glfw::WaitEvents or glfw::SwapBuffers is called.
942 :documentation
943 "
944 Function that will be called every time the mouse wheel is moved.
945 The function takes one argument: the position of the mouse wheel.
946 This DIFFERS FROM GLFW's DEFAULT behaviour in that the position is
947 reset after every call to this function, effectively giving the delta.
948 As most programs are only interested in the delta anyway, this is thought
949 to save others recording the state of it again.
950 If you wish to have the original GLFW behaviour, set cl-glfw:*mouse-wheel-cumulative* to t.
952 Description
953 The function selects which function to be called upon a mouse wheel event.
954 A window has to be opened for this function to have any effect.
955 Notes
956 Mouse wheel events are recorded continuously, but only reported when glfw::PollEvents,
957 glfw::WaitEvents or glfw::SwapBuffers is called.
961 "Parameters
962 joy
963 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
964 param
965 A token selecting which parameter the function should return (see table 3.5).
966 Return values
967 The function returns different parameters depending on the value of param. Table 3.5 lists valid param
968 values, and their corresponding return values.
969 Description
970 The function is used for acquiring various properties of a joystick.
971 Notes
972 The joystick information is updated every time the function is called.
973 No window has to be opened for joystick information to be valid.
976 (defcfun ("glfwGetJoystickPos" %get-joystick-pos) :int (joy :int) (pos :pointer) (numaxes :int))
979 "Parameters
980 joy
981 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
982 numaxes
983 Specifies how many axes should be returned.
984 Return values
985 An list that will hold the positional values for all requested axes.
986 If the joystick is not supported or connected, the function will
987 return nil.
989 Description
990 The function queries the current position of one or more axes of a joystick. The positional values are
991 returned in an array, where the first element represents the first axis of the joystick (normally the X
992 axis). Each position is in the range -1.0 to 1.0. Where applicable, the positive direction of an axis is
993 right, forward or up, and the negative direction is left, back or down.
994 If numaxes exceeds the number of axes supported by the joystick, or if the joystick is not available, the
995 unused elements in the pos array will be set to 0.0 (zero).
997 Notes
998 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
999 or glfw::WaitEvents for joystick state to be updated.
1000 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
1001 supported axes.
1002 No window has to be opened for joystick input to be valid.
1003 "
1009 (defcfun ("glfwGetJoystickButtons" %get-joystick-buttons) :int (joy :int) (buttons :pointer) (numbuttons :int))
1011 "Parameters
1012 joy
1013 A joystick identifier, which should be +JOYSTICK_n+ where n is in the range 1 to 16.
1014 numbuttons
1015 Specifies how many buttons should be returned.
1016 Return values
1017 A list that will hold the button states for all requested buttons.
1018 The function returns the number of actually returned buttons. This is the minimum of numbuttons and
1019 the number of buttons supported by the joystick. If the joystick is not supported or connected, the
1020 function will return 0 (zero).
1022 Description
1023 The function queries the current state of one or more buttons of a joystick. The button states are
1024 returned in an array, where the first element represents the first button of the joystick. Each state can be
1025 either +PRESS+ or +RELEASE+
1026 If numbuttons exceeds the number of buttons supported by the joystick, or if the joystick is not
1027 available, the unused elements in the buttons array will be set to +RELEASE+
1029 Notes
1030 The joystick state is updated every time the function is called, so there is no need to call glfw::PollEvents
1031 or glfw::WaitEvents for joystick state to be updated.
1032 Use glfw::GetJoystickParam to retrieve joystick capabilities, such as joystick availability and number of
1033 supported buttons.
1034 No window has to be opened for joystick input to be valid.
1035 "
1042 "Return values
1043 The function returns the value of the high precision timer. The time is measured in seconds, and is
1044 returned as a double precision floating point value.
1046 Description
1047 The function returns the state of a high precision timer. Unless the timer has been set by the
1048 glfw::SetTime function, the time is measured as the number of seconds that have passed since glfw::Init
1049 was called.
1051 Notes
1052 The resolution of the timer depends on which system the program is running on. The worst case
1053 resolution is somewhere in the order of 10 ms, while for most systems the resolution should be better
1054 than 1us.
1058 "Parameters
1059 time
1060 Time (in seconds) that the timer should be set to.
1062 Description
1063 The function sets the current time of the high precision timer to the specified time. Subsequent calls to
1064 glfw::GetTime will be relative to this time. The time is given in seconds.
1068 "Parameters
1069 time
1070 Time, in seconds, to sleep.
1072 Description
1073 The function puts the calling thread to sleep for the requested period of time. Only the calling thread is
1074 put to sleep. Other threads within the same process can still execute.
1076 Notes
1077 There is usually a system dependent minimum time for which it is possible to sleep. This time is
1078 generally in the range 1 ms to 20 ms, depending on thread sheduling time slot intervals etc. Using a
1079 shorter time as a parameter to glfw::Sleep can give one of two results: either the thread will sleep for the
1080 minimum possible sleep time, or the thread will not sleep at all (glfw::Sleep returns immediately). The
1092 "Parameters
1093 name
1094 A null terminated ISO 8859-1 string holding the name of the file that should be read.
1095 img
1096 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1097 read was successful).
1098 flags
1099 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1100 Return values
1101 The function returns t if the image was loaded successfully. Otherwise nil is
1102 returned.
1103 Description
1104 The function reads an image from the file specified by the parameter name and returns the image
1105 information and data in a GLFWimage structure, which has the following definition:
1107 typedef struct {
1108 int Width, Height; // Image dimensions
1109 int Format; // OpenGL pixel format
1110 int BytesPerPixel; // Number of bytes per pixel
1111 unsigned char *Data; // Pointer to pixel data
1112 } GLFWimage;
1114 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1115 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1116 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1118 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1119 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1120 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1121 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1122 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1123 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1125 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1126 Notes
1127 glfw::ReadImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel formats
1128 are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color + alpha.
1129 Paletted images are translated into true color or true color + alpha pixel formats.
1130 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1131 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1136 "Parameters
1137 data
1138 The memory buffer holding the contents of the file that should be read.
1139 size
1140 The size, in bytes, of the memory buffer.
1141 img
1142 Pointer to a GLFWimage struct, which will hold the information about the loaded image (if the
1143 read was successful).
1144 flags
1145 Flags for controlling the image reading process. Valid flags are listed in table 3.6
1146 Return values
1147 The function returns t if the image was loaded successfully. Otherwise nil is
1148 returned.
1149 Description
1150 The function reads an image from the memory buffer specified by the parameter data and returns the
1151 image information and data in a GLFWimage structure, which has the following definition:
1153 typedef struct {
1154 int Width, Height; // Image dimensions
1155 int Format; // OpenGL pixel format
1156 int BytesPerPixel; // Number of bytes per pixel
1157 unsigned char *Data; // Pointer to pixel data
1158 } GLFWimage;
1160 Width and Height give the dimensions of the image. Format specifies an OpenGL pixel format,
1161 which can be GL_LUMINANCE or GL_ALPHA (for gray scale images), GL_RGB or GL_RGBA.
1162 BytesPerPixel specifies the number of bytes per pixel. Data is a pointer to the actual pixel data.
1164 By default the read image is rescaled to the nearest larger 2m ? 2n resolution using bilinear
1165 interpolation, if necessary, which is useful if the image is to be used as an OpenGL texture. This
1166 behavior can be disabled by setting the GLFW_NO_RESCALE_BIT flag.
1167 Unless the flag GLFW_ORIGIN_UL_BIT is set, the first pixel in img->Data is the lower left corner of
1168 the image. If the flag GLFW_ORIGIN_UL_BIT is set, however, the first pixel is the upper left corner.
1169 For single component images (i.e. gray scale), Format is set to GL_ALPHA if the flag
1170 +ALPHA_MAP_BIT+ flag is set, otherwise Format is set to GL_LUMINANCE.
1171 Notes
1172 glfw::ReadMemoryImage supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1173 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1174 alpha.
1175 Paletted images are translated into true color or true color + alpha pixel formats.
1176 Please note that OpenGL 1.0 does not support single component alpha maps, so do not use images
1177 with Format = GL_ALPHA directly as textures under OpenGL 1.0.
1181 "Parameters
1182 img
1183 Pointer to a GLFWimage struct.
1184 Description
1185 The function frees any memory occupied by a loaded image, and clears all the fields of the GLFWimage
1186 struct. Any image that has been loaded by the glfw::ReadImage function should be deallocated using
1190 "Parameters
1191 name
1192 An ISO 8859-1 string holding the name of the file that should be loaded.
1193 flags
1194 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1195 Return values
1196 The function returns t if the texture was loaded successfully. Otherwise nil is
1197 returned.
1199 Description
1201 The function reads an image from the file specified by the parameter
1202 name and uploads the image to OpenGL texture memory (using the
1203 glTexImage2D function). If the GLFW_BUILD_MIPMAPS_BIT flag is set,
1204 all mipmap levels for the loaded texture are generated and uploaded to
1205 texture memory. Unless the flag +ORIGIN_UL_BIT+ is set, the origin of
1206 the texture is the lower left corner of the loaded image. If the flag
1207 +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1208 corner. For single component images (i.e. gray scale), the texture is
1209 uploaded as an alpha mask if the flag +ALPHA_MAP_BIT+ flag is set,
1210 otherwise it is uploaded as a luminance texture.
1212 Notes
1213 glfw::LoadTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported pixel
1214 formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color +
1215 alpha.
1216 Paletted images are translated into true color or true color + alpha pixel formats.
1217 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1218 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1219 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1220 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1221 generated by GLFW in software.
1223 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1224 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1225 texture is a single component texture. The red, green and blue components are set to 1.0.
1230 "Parameters
1231 data
1232 The memory buffer holding the contents of the file that should be loaded.
1233 size
1234 The size, in bytes, of the memory buffer.
1235 flags
1236 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1237 Return values
1238 The function returns t if the texture was loaded successfully. Otherwise nil is
1239 returned.
1241 Description
1242 The function reads an image from the memory buffer specified by the parameter data and uploads the
1243 image to OpenGL texture memory (using the glTexImage2D function).
1244 If the GLFW_BUILD_MIPMAPS_BIT flag is set, all mipmap levels for the loaded texture are
1245 generated and uploaded to texture memory.
1246 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1247 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1248 corner.
1249 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1250 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1252 Notes
1253 glfw::LoadMemoryTexture2D supports the Truevision Targa version 1 file format (.TGA). Supported
1254 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1255 + alpha.
1256 Paletted images are translated into true color or true color + alpha pixel formats.
1257 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1258 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1259 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1260 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1261 generated by GLFW in software.
1263 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1264 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1265 texture is a single component texture. The red, green and blue components are set to 1.0.
1271 "Parameters
1272 img
1273 Pointer to a GLFWimage struct holding the information about the image to be loaded.
1274 flags
1275 Flags for controlling the texture loading process. Valid flags are listed in table 3.7.
1276 Return values
1277 The function returns t if the texture was loaded successfully. Otherwise nil is
1278 returned.
1280 Description
1281 The function uploads the image specified by the parameter img to OpenGL texture memory (using
1282 the glTexImage2D function).
1283 If the +BUILD_MIPMAPS_BIT+ flag is set, all mipmap levels for the loaded texture are
1284 generated and uploaded to texture memory.
1285 Unless the flag +ORIGIN_UL_BIT+ is set, the origin of the texture is the lower left corner of the
1286 loaded image. If the flag +ORIGIN_UL_BIT+ is set, however, the first pixel is the upper left
1287 corner.
1288 For single component images (i.e. gray scale), the texture is uploaded as an alpha mask if the flag
1289 +ALPHA_MAP_BIT+ flag is set, otherwise it is uploaded as a luminance texture.
1291 Notes
1292 glfw::LoadTextureImage2D supports the Truevision Targa version 1 file format (.TGA). Supported
1293 pixel formats are: 8-bit gray scale, 8-bit paletted (24/32-bit color), 24-bit true color and 32-bit true color
1294 + alpha.
1295 Paletted images are translated into true color or true color + alpha pixel formats.
1296 The read texture is always rescaled to the nearest larger 2m ? 2n resolution using bilinear interpolation,
1297 if necessary, since OpenGL requires textures to have a 2m ? 2n resolution.
1298 If the GL_SGIS_generate_mipmap extension, which is usually hardware accelerated, is supported by
1299 the OpenGL implementation it will be used for mipmap generation. Otherwise the mipmaps will be
1300 generated by GLFW in software.
1302 Since OpenGL 1.0 does not support single component alpha maps, alpha map textures are converted
1303 to RGBA format under OpenGL 1.0 when the GLFW_ALPHA_MAP_BIT flag is set and the loaded
1308 "Parameters
1309 extension
1310 A null terminated ISO 8859-1 string containing the name of an OpenGL extension.
1311 Return values
1312 The function returns t if the extension is supported. Otherwise it returns nil.
1313 Description
1314 The function does a string search in the list of supported OpenGL extensions to find if the specified
1315 extension is listed.
1316 Notes
1318 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1319 must have been opened with glfwOpenWindow).
1320 In addition to checking for OpenGL extensions, GLFW also checks for extensions in the operating
1321 system ?glue API?, such as WGL extensions under Windows and glX extensions under the X Window
1322 System.
1326 "Parameters
1327 procname
1328 A null terminated ISO 8859-1 string containing the name of an OpenGL extension function.
1329 Return values
1330 The function returns the pointer to the specified OpenGL function if it is supported, otherwise
1331 NULL is returned.
1332 Description
1333 The function acquires the pointer to an OpenGL extension function. Some (but not all) OpenGL
1334 extensions define new API functions, which are usually not available through normal linking. It is
1335 therefore necessary to get access to those API functions at runtime.
1336 Notes
1338 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1339 must have been opened with glfwOpenWindow).
1340 Some systems do not support dynamic function pointer retrieval, in which case glfwGetProcAddress
1341 will always return NULL.
1347 "Return values
1348 The function returns the major and minor version numbers and the revision for the currently used
1349 OpenGL implementation as a list (major minor rev).
1351 Description
1352 The function returns the OpenGL implementation version. This is a convenient function that parses
1353 the version number information from the string returned by calling
1354 glGetString( GL_VERSION ). The OpenGL version information can be used to determine
1355 what functionality is supported by the used OpenGL implementation.
1357 Notes
1358 An OpenGL context must be created before this function can be called (i.e. an OpenGL window
1367 "Parameters
1368 fun
1369 A pointer to a function that acts as the entry point for the new thread. The function should have
1370 the following C language prototype:
1371 void GLFWCALL functionname( void *arg );
1372 Where functionname is the name of the thread function, and arg is the user supplied argument
1373 (see below).
1374 arg
1375 An arbitrary argument for the thread. arg will be passed as the argument to the thread function
1376 pointed to by fun. For instance, arg can point to data that is to be processed by the thread.
1377 Return values
1378 The function returns a thread identification number if the thread was created successfully. This number
1379 is always positive. If the function fails, a negative number is returned.
1380 Description
1381 The function creates a new thread, which executes within the same address space as the calling process.
1382 The thread entry point is specified with the fun argument.
1383 Once the thread function fun returns, the thread dies.
1384 Notes
1385 Even if the function returns a positive thread ID, indicating that the thread was created successfully, the
1386 thread may be unable to execute, for instance if the thread start address is not a valid thread entry point.
1389 "Parameters
1390 ID
1391 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1392 Description
1393 The function kills a running thread and removes it from the thread list.
1394 Notes
1395 This function is a very dangerous operation, which may interrupt a thread in the middle of an important
1396 operation, and its use is discouraged. You should always try to end a thread in a graceful way using
1397 thread communication, and use glfw::WaitThread in order to wait for the thread to die.
1400 "Parameters
1401 ID
1402 A thread identification handle, which is returned by glfw::CreateThread or glfw::GetThreadID.
1403 waitmode
1404 Can be either +WAIT+ or +NOWAIT+
1405 Return values
1406 The function returns t if the specified thread died after the function was called, or the thread
1407 did not exist, in which case glfw::WaitThread will return immediately regardless of waitmode. The
1408 function returns nil if waitmode is +NOWAIT+ and the specified thread exists and is still
1409 running.
1412 "Return values
1413 The function returns a thread identification handle for the calling thread.
1414 Description
1415 The function determines the thread ID for the calling thread. The ID is the same value as was returned
1416 by glfw::CreateThread when the thread was created.
1420 "Return values
1421 The function returns a mutex handle, or NULL if the mutex could not be created.
1422 Description
1423 The function creates a mutex object, which can be used to control access to data that is shared between
1424 threads.
1427 "Parameters
1428 mutex
1429 A mutex object handle.
1430 Description
1431 The function destroys a mutex object. After a mutex object has been destroyed, it may no longer be
1432 used by any thread.
1435 "Parameters
1436 mutex
1437 A mutex object handle.
1438 Description
1439 The function will acquire a lock on the selected mutex object. If the mutex is already locked by another
1440 thread, the function will block the calling thread until it is released by the locking thread. Once the
1441 function returns, the calling thread has an exclusive lock on the mutex. To release the mutex, call
1442 glfw::UnlockMutex.
1445 "Parameters
1446 mutex
1447 A mutex object handle.
1448 Description
1449 The function releases the lock of a locked mutex object.
1453 "Parameters
1454 mutex
1455 A mutex object handle.
1456 forms
1457 Body of code to execute
1458 Description
1459 This macro will acquire a lock on the selected mutex object using glfw::LockMutex and release it afterwards
1460 using glfw::UnlockMutex.
1461 So, forms will not execute until an exclusive lock is held.
1462 The lock is then released when the stack is unwound."
1470 "Return values
1471 The function returns a condition variable handle, or NULL if the condition variable could not be
1472 created.
1473 Description
1474 The function creates a condition variable object, which can be used to synchronize threads.
1477 "Parameters
1478 cond
1479 A condition variable object handle.
1480 Description
1481 The function destroys a condition variable object. After a condition variable object has been destroyed,
1482 it may no longer be used by any thread.
1485 " arameters
1486 cond
1487 A condition variable object handle.
1488 mutex
1489 A mutex object handle.
1490 timeout
1491 Maximum time to wait for the condition variable. The parameter can either be a positive time (in
1492 seconds), or +INFINITY+
1493 Description
1494 The function atomically unlocks the mutex specified by mutex, and waits for the condition variable cond
1495 to be signaled. The thread execution is suspended and does not consume any CPU time until the
1496 condition variable is signaled or the amount of time specified by timeout has passed. If timeout is
1497 +INFINITY+ glfw::WaitCond will wait forever for cond to be signaled. Before returning to the
1498 calling thread, glfw::WaitCond automatically re-acquires the mutex.
1499 Notes
1500 The mutex specified by mutex must be locked by the calling thread before entrance to glfw::WaitCond.
1501 A condition variable must always be associated with a mutex, to avoid the race condition where a thread
1502 prepares to wait on a condition variable and another thread signals the condition just before the first
1503 thread actually waits on it.
1506 "Parameters
1507 cond
1508 A condition variable object handle.
1509 Description
1510 The function restarts one of the threads that are waiting on the condition variable cond. If no threads are
1511 waiting on cond, nothing happens. If several threads are waiting on cond, exactly one is restarted, but it
1512 is not specified which.
1513 Notes
1514 When several threads are waiting for the condition variable, which thread is started depends on
1515 operating system scheduling rules, and may vary from system to system and from time to time.
1518 "Parameters
1519 cond
1520 A condition variable object handle.
1521 Description
1522 The function restarts all the threads that are waiting on the condition variable cond. If no threads are
1523 waiting on cond, nothing happens.
1524 Notes
1525 When several threads are waiting for the condition variable, the order in which threads are started
1526 depends on operating system scheduling rules, and may vary from system to system and from time to
1527 time.
1531 "Return values
1532 The function returns the number of active processors in the system.
1533 Description
1534 The function determines the number of active processors in the system.
1535 Notes
1536 Systems with several logical processors per physical processor, also known as SMT (Symmetric Multi
1537 Threading) processors, will report the number of logical processors.
1540 "Parameters
1541 token
1542 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1543 Return values
1544 none
1545 Description
1546 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1547 description of each feature.
1548 +AUTO_POLL_EVENTS+
1549 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1550 that glfw::SwapBuffers is called.
1551 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1552 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1553 function, since calling glfw::PollEvents from a callback function is not allowed.
1554 +KEY_REPEAT+
1555 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1556 when a key is held down long enough (according to the system key repeat configuration).
1557 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1558 when a key is pressed (and once when it is released).
1559 +MOUSE_CURSOR+
1560 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1561 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1562 the client area of the window.
1563 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1564 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1565 from the mouse, without being restricted or manipulated by the windowing system.
1566 +STICKY_KEYS+
1567 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1568 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1569 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1570 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1571 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1572 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1573 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfw::GetKey is always
1574 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1575 all keys.
1576 +STICKY_MOUSE_BUTTONS+
1577 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1578 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1579 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1580 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1581 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1582 glfw::GetMouseButton will never be released. Note also that enabling
1583 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1584 functionality.
1585 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1586 by glfw::GetMouseButton is always the physical state of the mouse button. Disabling
1587 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1588 +SYSTEM_KEYS+
1589 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1590 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1591 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1592 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1593 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1594 the GLFW video mode again.
1595 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1596 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1597 the GLFW program must not be interrupted (normally for games in fullscreen mode).
1600 "Parameters
1601 token
1602 A value specifying a feature to enable or disable. Valid tokens are listed in table 3.8.
1603 Return values
1604 none
1605 Description
1606 glfw::Enable is used to enable a certain feature, while glfw::Disable is used to disable it. Below follows a
1607 description of each feature.
1608 +AUTO_POLL_EVENTS+
1609 When +AUTO_POLL_EVENTS+ is enabled, glfw::PollEvents is automatically called each time
1610 that glfw::SwapBuffers is called.
1611 When +AUTO_POLL_EVENTS+ is disabled, calling glfw::SwapBuffers will not result in a call to
1612 glfw::PollEvents. This can be useful if glfw::SwapBuffers needs to be called from within a callback
1613 function, since calling glfw::PollEvents from a callback function is not allowed.
1614 +KEY_REPEAT+
1615 When +KEY_REPEAT+ is enabled, the key and character callback functions are called repeatedly
1616 when a key is held down long enough (according to the system key repeat configuration).
1617 When +KEY_REPEAT+ is disabled, the key and character callback functions are only called once
1618 when a key is pressed (and once when it is released).
1619 +MOUSE_CURSOR+
1620 When +MOUSE_CURSOR+ is enabled, the mouse cursor is visible, and mouse coordinates are
1621 relative to the upper left corner of the client area of the GLFW window. The coordinates are limited to
1622 the client area of the window.
1623 When +MOUSE_CURSOR+ is disabled, the mouse cursor is invisible, and mouse coordinates are
1624 not limited to the drawing area of the window. It is as if the mouse coordinates are recieved directly
1625 from the mouse, without being restricted or manipulated by the windowing system.
1626 +STICKY_KEYS+
1627 When +STICKY_KEYS+ is enabled, keys which are pressed will not be released until they are
1628 physically released and checked with glfw::GetKey. This behavior makes it possible to catch keys that
1629 were pressed and then released again between two calls to glfw::PollEvents, glfw::WaitEvents or
1630 glfw::SwapBuffers, which would otherwise have been reported as released. Care should be taken when
1631 using this mode, since keys that are not checked with glfw::GetKey will never be released. Note also that
1632 enabling +STICKY_KEYS+ does not affect the behavior of the keyboard callback functionality.
1633 When +STICKY_KEYS+ is disabled, the status of a key that is reported by glfwGetKey is always
1634 the physical state of the key. Disabling +STICKY_KEYS+ also clears the sticky information for
1635 all keys.
1636 +STICKY_MOUSE_BUTTONS+
1637 When +STICKY_MOUSE_BUTTONS+ is enabled, mouse buttons that are pressed will not be
1638 released until they are physically released and checked with glfw::GetMouseButton. This behavior
1639 makes it possible to catch mouse buttons which were pressed and then released again between two calls
1640 to glfw::PollEvents, glfw::WaitEvents or glfw::SwapBuffers, which would otherwise have been reported
1641 as released. Care should be taken when using this mode, since mouse buttons that are not checked with
1642 glfw::GetMouseButton will never be released. Note also that enabling
1643 +STICKY_MOUSE_BUTTONS+ does not affect the behavior of the mouse button callback
1644 functionality.
1645 When +STICKY_MOUSE_BUTTONS+ is disabled, the status of a mouse button that is reported
1646 by glfwGetMouseButton is always the physical state of the mouse button. Disabling
1647 +STICKY_MOUSE_BUTTONS+ also clears the sticky information for all mouse buttons.
1648 +SYSTEM_KEYS+
1649 When +SYSTEM_KEYS+ is enabled, pressing standard system key combinations, such as
1650 ALT+TAB under Windows, will give the normal behavior. Note that when ALT+TAB is issued under
1651 Windows in this mode so that the GLFW application is deselected when GLFW is operating in
1652 fullscreen mode, the GLFW application window will be minimized and the video mode will be set to
1653 the original desktop mode. When the GLFW application is re-selected, the video mode will be set to
1654 the GLFW video mode again.
1655 When +SYSTEM_KEYS+ is disabled, pressing standard system key combinations will have no
1656 effect, since those key combinations are blocked by GLFW. This mode can be useful in situations when
1657 the GLFW program must not be interrupted (normally for games in fullscreen mode).